From abb42e726b17fb320de96866a31a7c7330d6ccdd Mon Sep 17 00:00:00 2001
From: Konrad Bucheli <konrad.bucheli@psi.ch>
Date: Fri, 14 Jun 2024 15:05:47 +0200
Subject: [PATCH] more SELinux details

---
 admin-guide/configuration.md                  |  1 +
 .../configuration/selinux_configuration.md    | 88 +++++++++++++++----
 admin-guide/troubleshooting/selinux.md        |  8 ++
 3 files changed, 80 insertions(+), 17 deletions(-)

diff --git a/admin-guide/configuration.md b/admin-guide/configuration.md
index fcf35d12..bf568c3b 100644
--- a/admin-guide/configuration.md
+++ b/admin-guide/configuration.md
@@ -43,4 +43,5 @@ Here starts a so far small collections of configuration guides for sysadmins of
 - [SSH Host Hopping as Root (e.g. between cluster members)](configuration/ssh_host_hopping)
 - [Install Citrix VDA](configuration/citrix_vda)
 - [Sending / Relaying Emails](configuration/configuration_email)
+- [SELinux Configuration](configuration/selinux_configuration)
 
diff --git a/admin-guide/configuration/selinux_configuration.md b/admin-guide/configuration/selinux_configuration.md
index b5c42c45..1f9eebbc 100644
--- a/admin-guide/configuration/selinux_configuration.md
+++ b/admin-guide/configuration/selinux_configuration.md
@@ -1,32 +1,57 @@
 # SELinux Configuration
 
-Enable troubleshoot tools
-```yml
-base::enable_auditd: true
-selinux::setroubleshootd: true
-```
+SELinux can be configured in Hiera.
 
-Enable or disable selinux on a machine (default depends on the RHEL version)
-```yml
-base::selinux_mode: 'disabled'
-```
+For troubleshooting SELinux related problems please have a look at [SELinux Troublehooting Guide](../troubleshooting/selinux)`
 
-Options:
+## Basic Settings
+
+Enable or disable SELinux with `base::selinux`. Options:
 * `enforcing`
 * `permissive`
 * `disabled`
 
+Example:
 
-Use nfs home directory:
+```yml
+base::selinux_mode: 'disabled'
+```
+
+The default depends on the Puppet role, e.g. for servers it is `enforcing` while for workstations and consoles it is `disabled`.
+
+The `permissive` option is useful for setting up a new server to see where SELinux would block if enabled.
+
+## Logging Violations
+
+To record such violations `auditd` needs to run:
+
+```yml
+base::enable_auditd: true
+```
+On RHEL9 and later this is enabled by default if SELinux is `permissive` or `enforcing`.
+
+Then `setroubleshootd` is very helpful to learn how to configure SELinux if an action is wrongly considered a violation:
+```yml
+selinux::setroubleshootd: true
+```
+On RHEL9 and later this is enabled by default if SELinux is `permissive` or `enforcing`.
+
+
+## Finetuning
+
+### SELinux Booleans
+
+Use NFS home directory:
 ```yaml
 selinux::use_nfs_home_dirs: true
 ```
 
-Set selinux booleans
+Set SELinux booleans:
 ```yml
 selinux::booleans: [ 'httpd_can_network_connect', 'domain_can_mmap_files']
 ```
 
+### File Context (`fcontext`)
 
 Set fcontext for specific directories/directory
 ```yml
@@ -38,10 +63,41 @@ selinux::fcontext:
     pathspec: '/var/www/html/logbook-data-local(/.*)?'
     seltype: 'httpd_sys_rw_content_t'
 ```
-(you can choose any unique key name)
+a unique arbitrary key name for each entry is needed.
 
 
-Explicitly specify a selinux module:
+If you wish to have the same fcontext configuation as another path do
+
+```yml
+selinux::fcontext::equivalence:
+  apache_ssl_conf:
+    path: '/srv/online/config/ssl.conf'
+    target: '/etc/httpd/conf/httpd.conf'
+  apache_index_html:
+    path: '/srv/online/config/index.html'
+    target: '/var/www/html/index.html'
+  apache_online_web:
+    path: '/srv/online/web'
+    target: '/var/www/html'
+  apache_offlinecheck:
+    path: '/srv/offlinecheck'
+    target: '/var/www/html'
+```
+
+a unique arbitrary key name for each entry is needed here as well.
+
+
+### Custom Module
+Custom SELinux modules can also be added.
+
+Such a module can be created from recorded violations with
+```
+ausearch --raw | audit2allow -r -m $CUSTOM_SELINUX_MODULE_NAME
+```
+Note that the `setroubleshootd` log output ususally gives you a narrower search filter for `ausearch` for each recorded violation.
+
+Each such module needs to be added with a unique key at the Hiera key `selinux::modules::te`. A full example is
+
 ```yml
 selinux::modules::te:
   # SELinux is preventing /usr/local/bin/musrview from setattr access on the directory /usr/lib/fontconfig/cache
@@ -53,8 +109,6 @@ selinux::modules::te:
         class dir setattr;
     }
     allow httpd_sys_script_t lib_t:dir setattr;
-
 ```
 
-
-For troubleshooting SELinux related problems please have a look at [SELinux Troublehooting Guide](../troubleshooting/selinux.md)`
\ No newline at end of file
+Do not forget to increase the version number if you update such a module.
diff --git a/admin-guide/troubleshooting/selinux.md b/admin-guide/troubleshooting/selinux.md
index 898069e2..f6c5187a 100644
--- a/admin-guide/troubleshooting/selinux.md
+++ b/admin-guide/troubleshooting/selinux.md
@@ -76,6 +76,14 @@ ausearch -ts 14:28 --raw | audit2allow -M my-application
 
 This will create a `my-application.te` policy file with the source code (e.g. to be modified and distributed with Ansible or Puppet) and the copiled `my-application.pp` policy file.
 
+If you just need the TE source code as output (e.g. for Puppet), then do
+
+```bash
+ausearch -ts 14:28 --raw | audit2allow -r -m my-application
+```
+
+See [SELinux Configuration](../configuration/selinux_configuration)` how to add such a module to Hiera for Puppet.
+
 To install the new SELinux policy file run
 ```bash
 semodule --install my-application.pp