Docs: Add SELinux chapter

fixes #10553

diff --git a/doc/12-agent-based-checks.md b/doc/12-agent-based-checks.md
index 6c1c661c99ad345ab04d344b1744ba4ec0349199..8be055e377d4d0f97fa62226e13553b6716314c7 100644 (file)
--- a/doc/12-agent-based-checks.md
+++ b/doc/12-agent-based-checks.md
@@ -181,7 +181,7 @@ SNMP Traps can be received and filtered by using [SNMPTT](http://snmptt.sourcefo
 and specific trap handlers passing the check results to Icinga 2.
 
 Following the SNMPTT [Format](http://snmptt.sourceforge.net/docs/snmptt.shtml#SNMPTT.CONF-FORMAT)
-documentation and the Icinga external command syntax found [here](23-appendix.md#external-commands-list-detail)
+documentation and the Icinga external command syntax found [here](24-appendix.md#external-commands-list-detail)
 we can create generic services that can accommodate any number of hosts for a given scenario.
 
 ### <a id="simple-traps"></a> Simple SNMP Traps

diff --git a/doc/15-features.md b/doc/15-features.md
index f01c54d747683a1482275b022171c48f2c0d5b74..1799d2c08b836d690f415209662b8a9916548f6c 100644 (file)
--- a/doc/15-features.md
+++ b/doc/15-features.md
@@ -74,7 +74,7 @@ Example for PostgreSQL:
     (1 Zeile)
 
 
-A detailed list on the available table attributes can be found in the [DB IDO Schema documentation](23-appendix.md#schema-db-ido).
+A detailed list on the available table attributes can be found in the [DB IDO Schema documentation](24-appendix.md#schema-db-ido).
 
 
 ## <a id="external-commands"></a> External Commands
@@ -102,7 +102,7 @@ a forced service check:
     Oct 17 15:01:25 icinga-server icinga2: Executing external command: [1382014885] SCHEDULE_FORCED_SVC_CHECK;localhost;ping4;1382014885
     Oct 17 15:01:25 icinga-server icinga2: Rescheduling next check for service 'ping4'
 
-A list of currently supported external commands can be found [here](23-appendix.md#external-commands-list-detail).
+A list of currently supported external commands can be found [here](24-appendix.md#external-commands-list-detail).
 
 Detailed information on the commands and their required parameters can be found
 on the [Icinga 1.x documentation](http://docs.icinga.org/latest/en/extcommands2.html).
@@ -432,7 +432,7 @@ re-implementation of the Livestatus protocol which is compatible with MK
 Livestatus.
 
 Details on the available tables and attributes with Icinga 2 can be found
-in the [Livestatus Schema](23-appendix.md#schema-livestatus) section.
+in the [Livestatus Schema](24-appendix.md#schema-livestatus) section.
 
 You can enable Livestatus using icinga2 feature enable:
 
@@ -508,7 +508,7 @@ Example using the tcp socket listening on port `6558`:
 
 ### <a id="livestatus-command-queries"></a> Livestatus COMMAND Queries
 
-A list of available external commands and their parameters can be found [here](23-appendix.md#external-commands-list-detail)
+A list of available external commands and their parameters can be found [here](24-appendix.md#external-commands-list-detail)
 
     $ echo -e 'COMMAND <externalcommandstring>' | netcat 127.0.0.1 6558
 
@@ -609,7 +609,7 @@ Default separators.
 
 The `commands` table is populated with `CheckCommand`, `EventCommand` and `NotificationCommand` objects.
 
-A detailed list on the available table attributes can be found in the [Livestatus Schema documentation](23-appendix.md#schema-livestatus).
+A detailed list on the available table attributes can be found in the [Livestatus Schema documentation](24-appendix.md#schema-livestatus).
 
 
 ## <a id="status-data"></a> Status Data Files

diff --git a/doc/22-selinux.md b/doc/22-selinux.md
new file mode 100644 (file)
index 0000000..a4b4e6e
--- /dev/null
+++ b/doc/22-selinux.md
@@ -0,0 +1,232 @@
+# <a id="selinux"></a> SELinux
+
+## <a id="selinux-introduction"></a> Introduction
+
+SELinux is a mandatory access control (MAC) system on Linux which adds a fine granular permission system for access to all resources on the system such as files, devices, networks and inter-process communication.
+
+The most important questions are answered briefly in the [FAQ of the SELinux Project](http://selinuxproject.org/page/FAQ). For more details on SELinux and how to actually use and administrate it on your systems have a look at [Red Hat Enterprise Linux 7 - SELinux User's and Administrator's Guide](https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/SELinux_Users_and_Administrators_Guide/index.html). For an simplified (and funny) introduction download the [SELinux Coloring Book](https://github.com/mairin/selinux-coloring-book).
+
+This documentation will use a similar format like the SELinux User's and Administrator's Guide.
+
+### <a id="selinux-policy"></a> Policy
+
+Icinga 2 is providing its own SELinux Policy. At the moment it is not upstreamed to the reference policy because it is under development. Target of the development is a policy package for Red Hat Enterprise Linux 7 and its derivates running the targeted policy which confines Icinga2 with all features and all checks executed. All other distributions will require some tweaks.
+
+### <a id="selinux-policy-installation"></a> Installation
+
+There are two ways to install the SELinux Policy for Icinga 2 on Enterprise Linux 7. Installing it from the provided package which is the preferred option and manual installation if you need some fixes not released yet or for development.
+
+The policy package will run the daemon in a permissive domain so nothing will be denied also if the system runs in enforcing mode, so please make sure to run the system in this mode.
+
+    # sestatus
+    SELinux status:                 enabled
+    SELinuxfs mount:                /sys/fs/selinux
+    SELinux root directory:         /etc/selinux
+    Loaded policy name:             targeted
+    Current mode:                   enforcing
+    Mode from config file:          enforcing
+    Policy MLS status:              enabled
+    Policy deny_unknown status:     allowed
+    Max kernel policy version:      28
+
+You can change the configured mode by editing `/etc/selinux/config` and the current mode by executing `setenforce 0`.
+
+#### <a id="selinux-policy-installation-package"></a> Package installation
+
+The packages are provided with release version 2.4 onwards.
+
+Simply add the selinux subpackage to your installation.
+
+    # yum install icinga2-selinux
+
+After that restart Icinga 2 and verify it running in its own domain `icinga2_t`.
+
+    # systemctl restart icinga2.service
+    # ps -eZ | grep icinga2
+    system_u:system_r:icinga2_t:s0   2825 ?        00:00:00 icinga2
+
+#### <a id="selinux-policy-installation-manual"></a> Manual installation
+
+This section describes the installation to support development and testing. It assumes that Icinga 2 is already installed from packages and running on the system.
+
+As a prerequisite install the `git`, `selinux-policy-devel` and `audit` package. Enable and start the audit daemon afterwards.
+
+    # yum install git selinux-policy-devel audit
+    # systemctl enable auditd.service
+    # systemctl start auditd.service
+
+After that clone the icinga2 git repository.
+
+    # git clone git://git.icinga.org/icinga2.git
+
+To create and install the policy package run the installation script which also labels the resources. (The script assumes Icinga 2 was started once after system startup, the labeling of the port will only happen once and fail later on.)
+
+    # cd tools/selinux/
+    # ./icinga.sh
+
+After that restart Icinga 2 and verify it running in its own domain `icinga2_t`.
+
+    # systemctl restart icinga2.service
+    # ps -eZ | grep icinga2
+    system_u:system_r:icinga2_t:s0   2825 ?        00:00:00 icinga2
+
+### <a id="selinux-policy-general"></a> General
+
+When the SELinux policy package for Icinga 2 is installed, the Icinga 2 daemon (icinga2) runs in its own domain `icinga2_t` and is separated from other confined services.
+
+Files have to be labeled correctly for allowing icinga2 access to it. For example it writes to its own log files labeled `icinga2_log_t`. Also the API port is labeled `icinga_port_t` and icinga2 is allowed to manage it. Furthermore icinga2 can open high ports and unix sockets to connect to databases and features like graphite. It executes the nagios plugins and transitions to their context if those are labeled for example `nagios_services_plugin_exec_t` or `nagios_system_plugin_exec_t`.
+
+Additional the Apache webserver is allowed to connect to the Command pipe of Icinga 2 to allow web interfaces sending commands to icinga2. This will perhaps change later on while investigating Icinga Web 2 for SELinux!
+
+### <a id="selinux-policy-types"></a> Types
+
+The command pipe is labeled `icinga2_command_t` and other services can request access to it by using the interface `icinga2_send_commands`.
+
+The nagios plugins use their own contexts and icinga2 will transition to it. This means plugins have to be labeled correctly for their required permissions. The plugins installed from package should have set their permissions by the corresponding policy module and you can restore them using `restorecon -R -v /usr/lib64/nagios/plugins/`. To label your own plugins use `chcon -t type /path/to/plugin`, for the type have a look at table below.
+
+Type                              | Domain                       | Use case                                                         | Provided by policy package
+----------------------------------|------------------------------|------------------------------------------------------------------|---------------------------
+nagios_admin_plugin_exec_t        | nagios_admin_plugin_t        | Plugins which require require read access on all file attributes | nagios
+nagios_checkdisk_plugin_exec_t    | nagios_checkdisk_plugin_t    | Plugins which require read access to all filesystem attributes   | nagios
+nagios_mail_plugin_exec_t         | nagios_mail_plugin_t         | Plugins which access the local mail service                      | nagios
+nagios_services_plugin_exec_t     | nagios_services_plugin_t     | Plugins monitoring network services                              | nagios
+nagios_system_plugin_exec_t       | nagios_system_plugin_t       | Plugins checking local system state                              | nagios
+nagios_unconfined_plugin_exec_t   | nagios_unconfined_plugin_t   | Plugins running without confinement                              | nagios
+nagios_eventhandler_plugin_exec_t | nagios_eventhandler_plugin_t | Eventhandler (actually running unconfined)                       | nagios
+nagios_openshift_plugin_exec_t    | nagios_openshift_plugin_t    | Plugins monitoring openshift                                     | nagios
+nagios_notification_plugin_exec_t | nagios_notification_plugin_t | Notification commands                                            | icinga (will be moved later)
+
+If one of those plugin domains causes problems you can set it to permissive by executing `semanage permissive -a domain`.
+
+The policy provides a role `icinga2adm_r` for confining an user which enables an administrative user managing only Icinga 2 on the system. This user will also execute the plugins in their domain instead of the users one, so you can verify their execution with the same restrictions like they have when executed by icinga2.
+
+### <a id="selinux-policy-booleans"></a> Booleans
+
+SELinux is based on the least level of access required for a service to run. Using booleans you can grant more access in a defined way. The Icinga 2 policy package provides the following booleans.
+
+**icinga2_can_connect_all** 
+
+Having this boolean enabled allows icinga2 to connect to all ports. This can be neccesary if you use features which connect to unconfined services.
+
+### <a id="selinux-policy-examples"></a> Configuration Examples
+
+#### <a id="selinux-policy-examples-plugin"></a> Confining a plugin
+
+Download and install a plugin, for example check_mysql_health.
+
+    # wget http://labs.consol.de/download/shinken-nagios-plugins/check_mysql_health-2.1.9.2.tar.gz
+    # tar xvzf check_mysql_health-2.1.9.2.tar.gz
+    # cd check_mysql_health-2.1.9.2/
+    # ./configure --libexecdir /usr/lib64/nagios/plugins
+    # make
+    # make install
+
+It is labeled `nagios_unconfined_plugins_exec_t` by default, so it runs without restrictions.
+
+    # ls -lZ /usr/lib64/nagios/plugins/check_mysql_health
+    -rwxr-xr-x. root root system_u:object_r:nagios_unconfined_plugin_exec_t:s0 /usr/lib64/nagios/plugins/check_mysql_health
+
+In this case the plugin is monitoring a service, so it should be labeled `nagios_services_plugin_exec_t` to restrict its permissions.
+
+    # chcon -t nagios_services_plugin_exec_t /usr/lib64/nagios/plugins/check_mysql_health
+    # ls -lZ /usr/lib64/nagios/plugins/check_mysql_health
+    -rwxr-xr-x. root root system_u:object_r:nagios_services_plugin_exec_t:s0 /usr/lib64/nagios/plugins/check_mysql_health
+
+The plugin still runs fine but if someone changes the script to do weird stuff it will fail to do so.
+
+#### <a id="selinux-policy-examples-connectall"></a> Allow icinga to connect to all ports.
+
+You are running graphite on a different port than `2003` and want `icinga2` to connect to it.
+
+Change the port value for the graphite feature according to your graphite installation before enabling it.
+
+    # cat /etc/icinga2/features-enabled/graphite.conf 
+    /**
+     * The GraphiteWriter type writes check result metrics and
+     * performance data to a graphite tcp socket.
+     */
+
+    library "perfdata"
+
+    object GraphiteWriter "graphite" {
+      //host = "127.0.0.1"
+      //port = 2003
+      port = 2004
+    }
+    # icinga2 feature enable graphite
+
+Before you restart the icinga2 service allow it to connect to all ports by enabling the boolean ´icinga2_can_connect_all` (now and permanent).
+
+    # setsebool icinga2_can_connect_all true
+    # setsebool -P icinga2_can_connect_all true
+
+If you restart the daemon now it will successfully connect to graphite.
+
+#### <a id="selinux-policy-examples-user"></a> Confining a user
+
+If you want to have an administrative account capable of only managing icinga2 and not the complete system, you can restrict the privileges by confining
+this user. This is completly optional!
+
+Start by adding the Icinga 2 administrator role `icinga2adm_r` to the administrative SELinux user `staff_u`.
+
+    # semanage user -m -R "staff_r sysadm_r system_r unconfined_r icinga2adm_r" staff_u
+
+Confine your user login and create a sudo rule.
+
+    # semanage login -a dirk -s staff_u
+    # echo "dirk ALL=(ALL) NOPASSWD: ALL" > /etc/sudoers.d/dirk
+
+Login to the system using ssh and verify your id.
+
+    $ id -Z
+    staff_u:staff_r:staff_t:s0-s0:c0.c1023
+
+Try to execute some commands as root using sudo.
+
+    $ sudo id -Z
+    staff_u:staff_r:staff_t:s0-s0:c0.c1023
+    $ sudo vi /etc/icinga2/icinga2.conf
+    "/etc/icinga2/icinga2.conf" [Permission Denied]
+    $ sudo cat /var/log/icinga2/icinga2.log
+    cat: /var/log/icinga2/icinga2.log: Keine Berechtigung
+    $ sudo systemctl reload icinga2.service
+    Failed to get D-Bus connection: No connection to service manager.
+
+Those commands fail because you only switch to root but do not change your SELinux role. Try again but tell sudo also to switch the SELinux role and type.
+
+    $ sudo -r icinga2adm_r -t icinga2adm_t id -Z
+    staff_u:icinga2adm_r:icinga2adm_t:s0-s0:c0.c1023
+    $ sudo -r icinga2adm_r -t icinga2adm_t vi /etc/icinga2/icinga2.conf
+    "/etc/icinga2/icinga2.conf"
+    $ sudo -r icinga2adm_r -t icinga2adm_t cat /var/log/icinga2/icinga2.log
+    [2015-03-26 20:48:14 +0000] information/DynamicObject: Dumping program state to file '/var/lib/icinga2/icinga2.state'
+    $ sudo -r icinga2adm_r -t icinga2adm_t systemctl reload icinga2.service
+
+Now the commands will work, but you have always to remember to add the arguments, so change the sudo rule to set it by default.
+
+    # echo "dirk ALL=(ALL) ROLE=icinga2adm_r TYPE=icinga2adm_t NOPASSWD: ALL" > /etc/sudoers.d/dirk
+
+Now try the commands again without providing the role and type and they will work, but if you try to read apache logs or restart apache for example it will still fail.
+
+    $ sudo cat /var/log/httpd/error_log
+    /bin/cat: /var/log/httpd/error_log: Keine Berechtigung
+    $ sudo systemctl reload httpd.service
+    Failed to issue method call: Access denied
+
+## <a id="selinux-bugreports"></a> Bugreports
+
+If you experience any problems while running in enforcing mode try to reproduce it in permissive mode. If the problem persists it is not related to SELinux because in permissive mode SELinux will not deny anything.
+
+For now Icinga 2 is running in a permissive domain and adds also some rules for other necessary services so no problems should occure at all. But you can help to enhance the policy by testing Icinga 2 running confined by SELinux.
+
+When filing a bug report please add the following information additionally to the [normal ones](https://www.icinga.org/icinga/faq/):
+* Output of `semodule -l | grep -e icinga2 -e nagios -e apache`
+* Output of `ps -eZ | grep icinga2`
+* Output of `semanage port -l | grep icinga2`
+* Output of `audit2allow -li /var/log/audit/audit.log`
+
+If access to a file is blocked and you can tell which one please provided the output of `ls -lZ /path/to/file` (and perhaps the directory above).
+
+If asked for full audit.log add `-w /etc/shadow -p w` to `/etc/audit/rules.d/audit.rules`, restart the audit daemon, reproduce the problem and add `/var/log/audit/audit.log` to the bug report. With the added audit rule it will include the path of files access was denied to.
+
+If asked to provide full audit log with dontaudit rules disabled executed `semodule -DB` before reproducing the problem. After that enable the rules again to prevent auditd spamming your logfile by executing `semodule -B`.

diff --git a/doc/22-migrating-from-icinga-1x.md b/doc/23-migrating-from-icinga-1x.md
similarity index 98%
rename from doc/22-migrating-from-icinga-1x.md
rename to doc/23-migrating-from-icinga-1x.md
index 874077e7a4512109c54257cd960a1d6403b0850b..6c7a7a443e4f61d1b5e682f4c088b384c1b430aa 100644 (file)
--- a/doc/22-migrating-from-icinga-1x.md
+++ b/doc/23-migrating-from-icinga-1x.md
@@ -11,7 +11,7 @@ on your migration requirements.
 For a long-term migration of your configuration you should consider re-creating
 your configuration based on the proposed Icinga 2 configuration paradigm.
 
-Please read the [next chapter](22-migrating-from-icinga-1x.md#differences-1x-2) to find out more about the differences
+Please read the [next chapter](23-migrating-from-icinga-1x.md#differences-1x-2) to find out more about the differences
 between 1.x and 2.
 
 ### <a id="manual-config-migration-hints"></a> Manual Config Migration Hints
@@ -24,7 +24,7 @@ The examples are taken from Icinga 1.x test and production environments and conv
 straight into a possible Icinga 2 format. If you found a different strategy, please
 let us know!
 
-If you require in-depth explanations, please check the [next chapter](22-migrating-from-icinga-1x.md#differences-1x-2).
+If you require in-depth explanations, please check the [next chapter](23-migrating-from-icinga-1x.md#differences-1x-2).
 
 #### <a id="manual-config-migration-hints-Intervals"></a> Manual Config Migration Hints for Intervals
 
@@ -187,7 +187,7 @@ While you could manually migrate this like (please note the new generic command
 
 #### <a id="manual-config-migration-hints-runtime-macros"></a> Manual Config Migration Hints for Runtime Macros
 
-Runtime macros have been renamed. A detailed comparison table can be found [here](22-migrating-from-icinga-1x.md#differences-1x-2-runtime-macros).
+Runtime macros have been renamed. A detailed comparison table can be found [here](23-migrating-from-icinga-1x.md#differences-1x-2-runtime-macros).
 
 For example, accessing the service check output looks like the following in Icinga 1.x:
 
@@ -260,7 +260,7 @@ while the service check command resolves its value to the service attribute attr
 #### <a id="manual-config-migration-hints-contacts-users"></a> Manual Config Migration Hints for Contacts (Users)
 
 Contacts in Icinga 1.x act as users in Icinga 2, but do not have any notification commands specified.
-This migration part is explained in the [next chapter](22-migrating-from-icinga-1x.md#manual-config-migration-hints-notifications).
+This migration part is explained in the [next chapter](23-migrating-from-icinga-1x.md#manual-config-migration-hints-notifications).
 
     define contact{
       contact_name                    testconfig-user
@@ -270,8 +270,8 @@ This migration part is explained in the [next chapter](22-migrating-from-icinga-
       email                           icinga@localhost
     }
 
-The `service_notification_options` can be [mapped](22-migrating-from-icinga-1x.md#manual-config-migration-hints-notification-filters)
-into generic `state` and `type` filters if additional notification filtering is required. `alias` gets
+The `service_notification_options` can be [mapped](23-migrating-from-icinga-1x.md#manual-config-migration-hints-notification-filters)
+into generic `state` and `type` filters, if additional notification filtering is required. `alias` gets
 renamed to `display_name`.
 
     object User "testconfig-user" {
@@ -322,7 +322,7 @@ Assign it to the host or service and set the newly generated notification comman
 
 
 Convert the `notification_options` attribute from Icinga 1.x to Icinga 2 `states` and `types`. Details
-[here](22-migrating-from-icinga-1x.md#manual-config-migration-hints-notification-filters). Add the notification period.
+[here](23-migrating-from-icinga-1x.md#manual-config-migration-hints-notification-filters). Add the notification period.
 
       states = [ OK, Warning, Critical ]
       types = [ Recovery, Problem, Custom ]
@@ -559,7 +559,7 @@ enabled.
       assign where "hg_svcdep2" in host.groups
     }
 
-Host dependencies are explained in the [next chapter](22-migrating-from-icinga-1x.md#manual-config-migration-hints-host-parents).
+Host dependencies are explained in the [next chapter](23-migrating-from-icinga-1x.md#manual-config-migration-hints-host-parents).
 
 
 
@@ -930,7 +930,7 @@ In Icinga 1.x arguments are specified in the `check_command` attribute and
 are separated from the command name using an exclamation mark (`!`).
 
 Please check the migration hints for a detailed
-[migration example](22-migrating-from-icinga-1x.md#manual-config-migration-hints-check-command-arguments).
+[migration example](23-migrating-from-icinga-1x.md#manual-config-migration-hints-check-command-arguments).
 
 > **Note**
 >

diff --git a/doc/23-appendix.md b/doc/24-appendix.md
similarity index 100%
rename from doc/23-appendix.md
rename to doc/24-appendix.md

diff --git a/doc/3-monitoring-basics.md b/doc/3-monitoring-basics.md
index 4bdb06b2583a9e40b2418112e4cfce191b9e44e4..663a3b84d950e6fa1e94e1cab68601cf7513c104 100644 (file)
--- a/doc/3-monitoring-basics.md
+++ b/doc/3-monitoring-basics.md
@@ -1779,7 +1779,7 @@ Rephrased: If the parent service object changes into the `Warning` state, this
 dependency will fail and render all child objects (hosts or services) unreachable.
 
 You can determine the child's reachability by querying the `is_reachable` attribute
-in for example [DB IDO](23-appendix.md#schema-db-ido-extensions).
+in for example [DB IDO](24-appendix.md#schema-db-ido-extensions).
 
 ### <a id="dependencies-implicit-host-service"></a> Implicit Dependencies for Services on Host
 

diff --git a/doc/8-cli-commands.md b/doc/8-cli-commands.md
index 6ffb8c6cd58267a86fa2cb0352640c091b75f42e..2d4750fcea63885e3f830c1ca73aa2bedcc6e8d8 100644 (file)
--- a/doc/8-cli-commands.md
+++ b/doc/8-cli-commands.md
@@ -678,5 +678,5 @@ safely reload the Icinga 2 daemon.
 > which will validate the configuration in a separate process and not stop
 > the other events like check execution, notifications, etc.
 >
-> Details can be found [here](22-migrating-from-icinga-1x.md#differences-1x-2-real-reload).
+> Details can be found [here](23-migrating-from-icinga-1x.md#differences-1x-2-real-reload).
 

diff --git a/mkdocs.yml b/mkdocs.yml
index 1550c1516f2df91766c853501672ce788ad3c5f6..237bbcea7773daf9dd81acf2538c7b14f0fc1413 100644 (file)
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -23,8 +23,9 @@ pages:
 - [19-library-reference.md, Library Reference]
 - [20-script-debugger.md, Script Debugger]
 - [21-development.md, Development]
-- [22-migrating-from-icinga-1x.md, Migrating from Icinga 1.x]
-- [23-appendix.md, Appendix]
+- [22-selinux.md, SELinux]
+- [23-migrating-from-icinga-1x.md, Migrating from Icinga 1.x]
+- [24-appendix.md, Appendix]
 theme: readthedocs
 markdown_extensions: [smarty]
 extra_javascript: [scroll.js]