.. -*- mode: rst -*-

.. _server-selinux:

=======
SELinux
=======

This document describes two related but somewhat disparate concepts:
First, how to run Bcfg2 under SELinux; and secondly, how to use Bcfg2
to manage SELinux.

.. _server-selinux-policy:

Running Bcfg2 under SELinux
===========================

.. versionadded:: 1.3.0

Bcfg2 now ships with an SELinux policy that can be used to run both
the client and server in enforcing mode.  (Most of the helper tools,
like ``bcfg2-info`` and ``bcfg2-admin``, will still need to be run
unconfined.)

It defines the following booleans:

+-------------------------------------+-----------------------------------------+----------------------------------------------------------+---------+
| Boolean Name                        | Description                             | Plugins Affected                                         | Default |
+=====================================+=========================================+==========================================================+=========+
| bcfg2_server_exec_scripts           | Allow the Bcfg2 server to execute       | :ref:`server-plugins-misc-trigger` and                   | off     |
|                                     | scripts in ``unconfined_t``. This       | :ref:`server-plugins-connectors-puppetenc`,              |         |
|                                     | ability is limited to scripts in the    | and Cfg                                                  |         |
|                                     | ``bcfg2_server_script_exec_t`` context. | :ref:`server-plugins-generators-cfg-validation`          |         |
|                                     | If this boolean is off, then external   |                                                          |         |
|                                     | server-side scripts will be run in      |                                                          |         |
|                                     | ``bcfg2_server_t``, which is a fairly   |                                                          |         |
|                                     | limited context.                        |                                                          |         |
+-------------------------------------+-----------------------------------------+----------------------------------------------------------+---------+
| bcfg2_server_can_network_connect_db | Allow the Bcfg2 server to connect to    | :ref:`server-plugins-statistics-reporting`, the          | off     |
|                                     | databases (e.g., MySQL and PostgreSQL)  | :ref:`server-plugins-grouping-metadata-clients-database` |         |
|                                     |                                         | feature of Metadata, and the database                    |         |
|                                     |                                         | :ref:`server-plugins-probes-data-storage`                |         |
|                                     |                                         | feature of Probes                                        |         |
+-------------------------------------+-----------------------------------------+----------------------------------------------------------+---------+


It also defines the following SELinux types:

+----------------------------+-------------------------------------------------+
| Type Name                  | Description                                     |
+============================+=================================================+
| bcfg2_t                    | The context the Bcfg2 client runs in            |
+----------------------------+-------------------------------------------------+
| bcfg2_exec_t               | The context of the Bcfg2 client script itself   |
+----------------------------+-------------------------------------------------+
| bcfg2_server_t             | The context the Bcfg2 server runs in            |
+----------------------------+-------------------------------------------------+
| bcfg2_server_exec_t        | The context of the Bcfg2 server script itself   |
+----------------------------+-------------------------------------------------+
| bcfg2_initrc_exec_t        | The context of the Bcfg2 client init script     |
+----------------------------+-------------------------------------------------+
| bcfg2_server_initrc_exec_t | The context of the Bcfg2 server init script     |
+----------------------------+-------------------------------------------------+
| bcfg2_var_lib_t            | The context of most Bcfg2 specification data,   |
|                            | with the exception of the executable scripts in |
|                            | ``bcfg2_server_script_exec_t``                  |
+----------------------------+-------------------------------------------------+
| bcfg2_server_script_t      | The context server-side scripts run in. This    |
|                            | type is unconfined if the                       |
|                            | ``bcfg2_server_exec_scripts`` is on.            |
+----------------------------+-------------------------------------------------+
| bcfg2_server_script_exec_t | The context of the server-side scripts in the   |
|                            | Bcfg2 specification                             |
+----------------------------+-------------------------------------------------+
| bcfg2_yum_helper_exec_t    | The context of the bcfg2-yum-helper script      |
+----------------------------+-------------------------------------------------+
| bcfg2_var_run_t            | The context of the server pidfile               |
+----------------------------+-------------------------------------------------+
| bcfg2_lock_t               | The context of the client lock file             |
+----------------------------+-------------------------------------------------+
| bcfg2_conf_t               | The context of bcfg2.conf                       |
+----------------------------+-------------------------------------------------+
| bcfg2_tmp_t                | The context of temp files created by the Bcfg2  |
|                            | server                                          |
+----------------------------+-------------------------------------------------+

If you do run your server in enforcing mode, it is highly recommend
that you run ``restorecon -R /var/lib/bcfg2`` every time you update
the content in that directory, particularly if you are using plugins
that execute arbitrary scripts.

.. _server-selinux-entries:

Managing SELinux Entries
========================

.. versionadded:: 1.3.0

Bcfg2 has the ability to handle the majority of SELinux entries with
the ``SELinux`` entry type, which handles modules (with the
:ref:`server-plugins-generators-semodules` plugin), file contexts,
users and user mappings, permissive domains, nodes, and interfaces.
In addition, ``info.xml`` files and most types of the ``Path`` tag can
accept an ``secontext`` attribute to set the context of that entry.
The full semantics of each configuration entry is documented with the
:ref:`server-plugins-generators-rules` plugin.

.. note:: The ``secontext`` attribute takes a *full* context,
          e.g., "``system_u:object_r:etc_t:s0``"; the ``selinuxtype``
          attribute always takes *only* an SELinux type, e.g.,
          "``etc_t``".  ``secontext`` (but not ``selinuxtype``) can
          also accept the special value "``__default__``", which will
          restore the context on the Path entry in question to the
          default supplied by the SELinux policy.

In its current version, the SELinux support in Bcfg2 is not sufficient
to manage MCS/MLS policies.

Extra Entries
-------------

As it can be very tedious to create a baseline of all existing SELinux
entries, you can use ``selinux_baseline.py`` located in the ``tools/``
directory to do that for you.

The actual definition of an "extra" entry actually depends on the
version of SELinux available; the SELinux APIs have been extremely
fluid, so many features available in newer versions are not available
in older versions.  Newer SELinux versions (e.g., in recent versions
of Fedora) can be queried for only entries that have been locally
modified; on these versions of SELinux, only locally modified entries
will be considered extra.  On older SELinux versions (e.g., on RHEL
5), however, that functionality is missing, so *all* SELinux entries
will be considered extra, making ``selinux_baseline.py`` quite
necessary.

``selinux_baseline.py`` writes a bundle to stdout that contains
``BoundSELinux`` entries for the appropriate SELinux entities.

.. _server-selinux-duplicate-entries:

Duplicate Entries
-----------------

It may be necessary to use `BoundSELinux` tags if a single fcontext
needs two different SELinux types depending on whether it's a symlink
or a plain file.  For instance:

.. code-block:: xml

    <BoundSELinux type="fcontext" filetype="symlink"
                  name="/etc/localtime" selinuxtype="etc_t"/>
    <BoundSELinux type="fcontext" filetype="regular"
                  name="/etc/localtime" selinuxtype="locale_t"/>