more SELinux details

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)`
+Do not forget to increase the version number if you update such a module.