path: root/doc/server/plugins/generators/rules.txt

.. -*- mode: rst -*-

.. _server-plugins-generators-rules:

=====
Rules
=====

The Rules plugin resolves the following Abstract Configuration Entities:

* Service
* Package
* Path
* Action

to literal configuration entries suitable for the client drivers to
consume.

For an entity specification to be included in the Literal configuration
the name attribute from an Abstract Entity Tag (from Base or Bundler)
must match the name attribute of an Entity tag in Rules, along with the
appropriate group associations of course.

Each file in the Rules directory has a priority. This allows the same
Entities to be served by multiple files. The priorities can be used to
break ties in the case that multiple files serve data for the same Entity.


Usage of Groups in Rules
========================

Groups are used by the Rules plugin, along with host metadata, for
selecting the Configuration Entity entries to include in the clients
literal configuration. They can be thought of as::

    if client is a member of group1 then
        assign to literal config

Nested groups are conjunctive (logical and).::

    if client is a member of group1 and group2 then
        assign to literal config

Group membership may be negated.

Tag Attributes in Rules
=======================

Running ``bcfg2-lint`` will check your configuration specification for
the presence of any mandatory attributes that are necessary for the
entry specified.

Rules Tag
---------

The Rules Tag may have the following attributes:

+----------+-------------------------------------+--------+
| Name     | Description                         | Values |
+==========+=====================================+========+
| priority | Sets the priority for Rules in this | String |
|          | Rules list.The higher value wins.   |        |
+----------+-------------------------------------+--------+

Group Tag
---------

The Group Tag may have the following attributes:

+--------+-------------------------+--------------+
| Name   | Description             | Values       |
+========+=========================+==============+
| name   | Group Name              | String       |
+--------+-------------------------+--------------+
| negate | Negate group membership | (true|false) |
|        | (is not a member of)    |              |
+--------+-------------------------+--------------+

Client Tag
----------

The Client Tag is used in Rules for selecting the package entries to
include in the clients literal configuration.  Its function is similar
to the Group tag in this context.  It can be thought of as::

    if client is name then
        assign to literal config

The Client Tag may have the following attributes:

+--------+-------------------------+--------------+
| Name   | Description             | Values       |
+========+=========================+==============+
| name   | Client Name             | String       |
+--------+-------------------------+--------------+
| negate | Negate client selection | (true|false) |
|        | (if not client name)    |              |
+--------+-------------------------+--------------+

Package Tag
-----------

The Package Tag may have the following attributes:

+------------+----------------------------------------------+----------+
| Name       | Description                                  | Values   |
+============+==============================================+==========+
| name       | Package name                                 | String   |
+------------+----------------------------------------------+----------+
| version    | Package Version or version='noverify' to     | String   |
|            | not do version checking in the Yum driver    |          |
|            | only (temporary work a round).               |          |
+------------+----------------------------------------------+----------+
| file       | Package file name.  Several other attributes | String   |
|            | (name, version) can be automatically defined |          |
|            | based on regular expressions defined in the  |          |
|            | Pkgmgr plugin.                               |          |
+------------+----------------------------------------------+----------+
| simplefile | Package file name. No name parsing is        | String   |
|            | performed, so no extra fields get set        |          |
+------------+----------------------------------------------+----------+
| verify     | verify='false' - do not do package           | String   |
|            | verification                                 |          |
+------------+----------------------------------------------+----------+
| multiarch  | Comma separated list of the architectures of | String   |
|            | this package that should be installed.       |          |
+------------+----------------------------------------------+----------+
| srcs       | Filename creation rules for multiarch        | String   |
|            | packages.                                    |          |
+------------+----------------------------------------------+----------+
| type       | Package type. (rpm, yum, apt,sysv,blast)     | String   |
+------------+----------------------------------------------+----------+

Action Tag
----------

See :ref:`client-tools-actions`

Service Tag
-----------

+------------+-------------------------------+---------------------------------------------------------+
| Name       | Description                   | Values                                                  |
+============+===============================+=========================================================+
| restart    | Whether to restart the        | ( true | false | interactive )                          |
|            | service when the bundle       |                                                         |
|            | changes (new in 1.3; replaces |                                                         |
|            | "mode" attribute)             |                                                         |
+------------+-------------------------------+---------------------------------------------------------+
| install    | Whether to install the        | ( true | false )                                        |
|            | service (new in 1.3; replaces |                                                         |
|            | "mode" attribute)             |                                                         |
+------------+-------------------------------+---------------------------------------------------------+
| name       | Service name                  | String                                                  |
+------------+-------------------------------+---------------------------------------------------------+
| status     | Should the service be on or   | (on | off | ignore)                                     |
|            | off (default: off).           |                                                         |
+------------+-------------------------------+---------------------------------------------------------+
| target     | Service command for restart   | String                                                  |
|            | (default: restart)            |                                                         |
+------------+-------------------------------+---------------------------------------------------------+
| type       | Driver to use on the client   | (chkconfig | deb | rc-update | smf | upstart |          |
|            | to manage this service.       |  systemd | freebsd | launchd )                          |
+------------+-------------------------------+---------------------------------------------------------+
| sequence   | Order for service startup     | integer                                                 |
|            | (debian services only)        |                                                         |
+------------+-------------------------------+---------------------------------------------------------+
| parameters | Pass parameters to service    | String                                                  |
|            | (Upstart services only)       |                                                         |
+------------+-------------------------------+---------------------------------------------------------+

Service mode specification
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. versionadded:: 1.3.0

In the 1.3.0 release, the "mode" attribute has been replaced by a pair
of attributes, "restart" and "install," which control how a service is
handled more granularly than the old "mode" attribute.  The old "mode"
attribute values are equivalent as follows:

+-----------------------------+------------------------------------------+
| Mode attribute              | Equivalent                               |
+=============================+==========================================+
| ``mode="default"``          | ``restart="true" install="true"``        |
+-----------------------------+------------------------------------------+
| ``mode="interactive_only"`` | ``restart="interactive" install="true"`` |
+-----------------------------+------------------------------------------+
| ``mode="supervised"``       | ``restart="true" install="true"``        |
+-----------------------------+------------------------------------------+
| ``mode="manual"``           | ``restart="false" install="false"``      |
+-----------------------------+------------------------------------------+

The default is ``restart="true" install="true"``

Previously, "supervised" could be used to start a service during the
verification phase; this is no longer supported.  Services that have
been stopped on a client will be started during the install phase.

Service status descriptions
^^^^^^^^^^^^^^^^^^^^^^^^^^^

* on

  * start the service at boot time

* off

  * don't start the service at boot time

* ignore

  * Don't perform service status checks.

Path Tag
--------

The Path tag has different values depending on the *type* attribute of
the path specified in your configuration. Below is a set of tables which
describe the attributes available for various Path types.

Note that ``secontext`` below expects a full context, not just the
type.  For instance, "``system_u:object_r:etc_t:s0``", not just
``etc_t``.  You can also specify "``__default__``", which will restore
the context of the file to the default set by policy.  See
:ref:`server-selinux` for more information.

Attributes common to all Path tags:

+----------+-------------+--------+
| Name     | Description | Values |
+==========+=============+========+
| name     | Full path   | String |
+----------+-------------+--------+


device
^^^^^^

+-----------+---------------------+-------------------+
| Name      | Description         | Values            |
+===========+=====================+===================+
| dev_type  | Type of device      | (block|char|fifo) |
+-----------+---------------------+-------------------+
| owner     | Device owner        | String            |
+-----------+---------------------+-------------------+
| group     | Device group        | String            |
+-----------+---------------------+-------------------+
| mode      | Mode for the device | String            |
+-----------+---------------------+-------------------+
| secontext | SELinux context     | String            |
+-----------+---------------------+-------------------+
| major     | Major number (block | integer           |
|           | or char devices)    |                   |
+-----------+---------------------+-------------------+
| minor     | Minor number (block | integer           |
|           | or char devices)    |                   |
+-----------+---------------------+-------------------+

directory
^^^^^^^^^

+-----------+------------------------------+------------+
| Name      | Description                  | Values     |
+===========+==============================+============+
| mode      | File mode of the directory   | String     |
+-----------+------------------------------+------------+
| owner     | Owner of the directory       | String     |
+-----------+------------------------------+------------+
| group     | Group Owner of the directory | String     |
+-----------+------------------------------+------------+
| secontext | SELinux context              | String     |
+-----------+------------------------------+------------+
| prune     | prune unspecified entries    | true|false |
|           | from the Directory           |            |
+-----------+------------------------------+------------+

hardlink
^^^^^^^^

+-----------+------------------------------+--------+
| Name      | Description                  | Values |
+===========+==============================+========+
| to        | File to link to              | String |
+-----------+------------------------------+--------+
| owner     | Owner of the directory       | String |
+-----------+------------------------------+--------+
| group     | Group Owner of the directory | String |
+-----------+------------------------------+--------+
| secontext | SELinux context              | String |
+-----------+------------------------------+--------+

nonexistent
^^^^^^^^^^^

+-----------+--------------------+-------------+
| Name      | Description        | Values      |
+===========+====================+=============+
| type      | Type of file       | nonexistent |
+-----------+--------------------+-------------+
| recursive | Recursively remove | Boolean     |
|           | directory contents |             |
+-----------+--------------------+-------------+

permissions
^^^^^^^^^^^

+-----------+-----------------------------+---------+
| Name      | Description                 | Values  |
+===========+=============================+=========+
| mode      | Mode of the file            | String  |
+-----------+-----------------------------+---------+
| owner     | Owner of the file           | String  |
+-----------+-----------------------------+---------+
| group     | Group of the file           | String  |
+-----------+-----------------------------+---------+
| secontext | SELinux context             | String  |
+-----------+-----------------------------+---------+
| recursive | Recursively set permissions | Boolean |
+-----------+-----------------------------+---------+

symlink
^^^^^^^

+------+----------------------+--------+
| Name | Description          | Values |
+======+======================+========+
| to   | File to link to      | String |
+------+----------------------+--------+

.. _server-plugins-generators-rules-acls:

ACLs
^^^^

.. versionadded:: 1.3.0

ACLs on a Path entry are specified not by attributes on the tag but by
child ``<ACL>`` tags.  For instance:

.. code-block:: xml

    <Path name="/etc/foo" type="directory" owner="root" group="root"
          mode="0775">
      <ACL type="default" scope="user" user="foouser" perms="rw"/>
      <ACL type="default" scope="group" group="users" perms="rx"/>
    </Path>

The ACL tag has the following attributes:

+-------+---------------------------------------------------+----------------+
| Name  | Description                                       | Values         |
+=======+===================================================+================+
| type  | ACL type                                          | default|access |
+-------+---------------------------------------------------+----------------+
| scope | ACL scope                                         | user|group     |
+-------+---------------------------------------------------+----------------+
| user  | User the ACL applies to ``(with scope="user"``)   | String         |
+-------+---------------------------------------------------+----------------+
| group | Group the ACL applies to ``(with scope="group"``) | String         |
+-------+---------------------------------------------------+----------------+
| perms | Permissions for the ACL                           | See below      |
+-------+---------------------------------------------------+----------------+

The ``perms`` attribute can either be a single octal digit (e.g.,
``6`` would indicate read and write, but not execute), or a symbolic
mode including 'r', 'w', and 'x'.  You can include '-' for operations
that are not permitted, but it's not required.  I.e., all of the
following are identical::

    perms="5"
    perms="rx"
    perms="r-x"

It is not currently possible to manually set an effective rights mask;
the mask will be automatically calculated from the given ACLs when
they are applied.

Note that it is possible to set ACLs that demand different permissions
on a file than those specified in the ``perms`` attribute on the
``Path`` tag.  For instance:

.. code-block:: xml

    <Path name="/etc/foo" mode="0644" group="root" owner="root">
      <ACL type="access" scope="user" user="foouser" perms="rwx"/>
    </Path>

In this case, we've specified permissions of ``0644``, but the
effective rights mask will be "rwx," so setting the ACL will change
the permissions to ``0674``.  When this happens, Bcfg2 will change the
permissions and set the ACLs on every run and the entry will be
eternally marked as bad.

SELinux Entries
---------------

.. versionadded:: 1.3.0

.. note::

    In order to use these entries, the client also needs to be at least
    version 1.3.0 since they require a client tool which is unavailable
    in previous versions.

Below is a set of tables which describe the attributes available
for various SELinux types.  The entry types (except for ``module``)
correspond to ``semanage`` subcommands.

Note that the ``selinuxtype`` attribute takes only an SELinux type,
not a full context; e.g., "``etc_t``", not
"``system_u:object_r:etc_t:s0``".

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.

See :ref:`server-selinux` for more information.

SEBoolean Tag
^^^^^^^^^^^^^

+-------+----------------------+---------+----------+
| Name  | Description          | Values  | Required |
+=======+======================+=========+==========+
| name  | Name of the boolean  | String  | Yes      |
+-------+----------------------+---------+----------+
| value | Value of the boolean | on|off  | Yes      |
+-------+----------------------+---------+----------+

SEPort Tag
^^^^^^^^^^

+-------------+------------------------+---------------------------+----------+
| Name        | Description            | Values                    | Required |
+=============+========================+===========================+==========+
| name        | Port number or range   | ``<port>/<proto>`` or     | Yes      |
|             | and protocol (tcp|udp) | ``<start>-<end>/<proto>`` |          |
+-------------+------------------------+---------------------------+----------+
| selinuxtype | SELinux type to apply  | String                    | Yes      |
|             | to this port           |                           |          |
+-------------+------------------------+---------------------------+----------+

SEFcontext Tag
^^^^^^^^^^^^^^

+-------------+-------------------------+---------------------+----------+
| Name        | Description             | Values              | Required |
+=============+=========================+=====================+==========+
| name        | File specification      | String              | Yes      |
+-------------+-------------------------+---------------------+----------+
| selinuxtype | SELinux type to apply   | String              | Yes      |
|             | to files matching this  |                     |          |
|             | specification           |                     |          |
+-------------+-------------------------+---------------------+----------+
| filetype    | File type to match.     | (regular|directory| | No       |
|             | Default: all            |  symlink|pipe|all|  |          |
|             |                         |  socket|block|char) |          |
+-------------+-------------------------+---------------------+----------+

SENode Tag
^^^^^^^^^^

+-------------+------------------------------------+------------------+----------+
| Name        | Description                        | Values           | Required |
+=============+====================================+==================+==========+
| name        | IP address and netmask of node.    | <addr>/<netmask> | Yes      |
|             | Netmask can be numeric (/16) or    |                  |          |
|             | dotted-quad (/255.255.0.0)         |                  |          |
+-------------+------------------------------------+------------------+----------+
| selinuxtype | SELinux type to apply to this node | String           | Yes      |
+-------------+------------------------------------+------------------+----------+
| proto       | Protocol                           | (ipv4|ipv6)      | Yes      |
+-------------+------------------------------------+------------------+----------+

SELogin Tag
^^^^^^^^^^^

+-------------+-------------------------------+-----------+----------+
| Name        | Description                   | Values    | Required |
+=============+===============================+===========+==========+
| name        | Unix username                 | String    | Yes      |
+-------------+-------------------------------+-----------+----------+
| selinuxuser | SELinux username              | String    | Yes      |
+-------------+-------------------------------+-----------+----------+

SEUser Tag
^^^^^^^^^^

+-------------+-------------------------------+-----------+----------+
| Name        | Description                   | Values    | Required |
+=============+===============================+===========+==========+
| name        | SELinux username              | String    | Yes      |
+-------------+-------------------------------+-----------+----------+
| roles       | Space-separated list of roles | String    | Yes      |
+-------------+-------------------------------+-----------+----------+
| prefix      | Home directory context prefix | String    | Yes      |
+-------------+-------------------------------+-----------+----------+

SEInterface Tag
^^^^^^^^^^^^^^^

+-------------+-------------------------+-------------+----------+
| Name        | Description             | Values      | Required |
+=============+=========================+=============+==========+
| name        | Interface name          | String      | Yes      |
+-------------+-------------------------+-------------+----------+
| selinuxtype | SELinux type to apply   | String      | Yes      |
|             | to this interface       |             |          |
+-------------+-------------------------+-------------+----------+

SEPermissive Tag
^^^^^^^^^^^^^^^^

+-------------+------------------------------------+-------------+----------+
| Name        | Description                        | Values      | Required |
+=============+====================================+=============+==========+
| name        | SELinux type to make permissive    | String      | Yes      |
+-------------+------------------------------------+-------------+----------+

SEModule Tag
^^^^^^^^^^^^

See :ref:`server-plugins-generators-semodules`

POSIXUser Tag
-------------

.. versionadded:: 1.3.0

.. note::

    In order to use this, the client also needs to be at least version
    1.3.0 since they require a client tool which is unavailable in
    previous versions.

The POSIXUser tag allows you to create users on client machines.  It
takes the following attributes:

+-------+-----------------------+---------+-------------------------------+
| Name  | Description           | Values  | Default                       |
+=======+=======================+=========+===============================+
| name  | Username              | String  | None                          |
+-------+-----------------------+---------+-------------------------------+
| uid   | User ID number        | Integer | The client sets the uid       |
+-------+-----------------------+---------+-------------------------------+
| group | Name of the user's    | String  | The username                  |
|       | primary group         |         |                               |
+-------+-----------------------+---------+-------------------------------+
| gecos | Human-readable user   | String  | The username                  |
|       | name or comment       |         |                               |
+-------+-----------------------+---------+-------------------------------+
| home  | User's home directory | String  | /root (for "root");           |
|       |                       |         | /home/<username> otherwise    |
+-------+-----------------------+---------+-------------------------------+
| shell | User's shell          | String  | /bin/bash                     |
+-------+-----------------------+---------+-------------------------------+

The group specified will automatically be created if it does not
exist, even if there is no `POSIXGroup Tag`_ for it.  If you need to
specify a particular GID for the group, you must specify that in a
``POSIXGroup`` tag.

If you with to change the default shell, you can do so with :ref:`the
Defaults plugin <server-plugins-structures-defaults>`.

Additionally, a user may be a member of supplementary groups.  These
can be specified with the ``MemberOf`` child tag of the ``POSIXUser``
tag.

For example:

.. code-block:: xml

    <POSIXUser name="daemon" home="/sbin" shell="/sbin/nologin"
               gecos="daemon" uid="2" group="daemon">
      <MemberOf>lp</MemberOf>
      <MemberOf>adm</MemberOf>
      <MemberOf>bin</MemberOf>
    </BoundPOSIXUser>

See :ref:`client-tools-posixusers` for more information on managing
users and groups.

POSIXGroup Tag
--------------

.. versionadded:: 1.3.0

.. note::

    In order to use this, the client also needs to be at least version
    1.3.0 since they require a client tool which is unavailable in
    previous versions.

The POSIXGroup tag allows you to create groups on client machines.  It
takes the following attributes:

+-------+-------------------+---------+-------------------------+
| Name  | Description       | Values  | Default                 |
+=======+===================+=========+=========================+
| name  | Name of the group | String  | None                    |
+-------+-------------------+---------+-------------------------+
| gid   | Group ID number   | Integer | The client sets the gid |
+-------+-------------------+---------+-------------------------+

See :ref:`client-tools-posixusers` for more information on managing
users and groups.

Rules Directory
===============

The Rules/ directory keeps the XML files that define what rules are
available for a host.  All the files in the directory are processed.

The names of the XML files have no special meaning to Bcfg2; they
are simply named so it's easy for the administrator to know what the
contents hold.  All Rules could be kept in a single file if so desired.
Bcfg2 simply uses the Groups in the files and priorities to determine
how to assign Rules to a host's literal configuration.

.. code-block:: xml

    <Rules priority="0">
        <Path type='directory' group="root" name="/autonfs" owner="root" mode="0755"/>
        <Path type='directory' group="utmp" name="/var/run/screen" owner="root" mode="0775"/>
        <Path type='directory' group="root" name="/autonfs/stage" owner="root" mode="0755"/>
        <Path type='directory' group="root" name="/exports" owner="root" mode="0755"/>
        <Path type='directory' name="/etc/condor" owner="root" group="root" mode="0755"/>
        <Path type='directory' name="/logs" group="wwwtrans" owner="root" mode="0775"/>
        <Path type='directory' name="/mnt" group="root" owner="root" mode="0755"/>
        <Path type='directory' name="/my" owner="root" group="root" mode="0755"/>
        <Path type='directory' name="/my/bin" owner="root" group="root" mode="0755"/>
        <Path type='directory' name="/nfs" owner="root" group="root" mode="0755"/>
        <Path type='directory' name="/sandbox" mode="0777" owner="root" group="root"/>
        <Path type='directory' name="/software" group="root" owner="root" mode="0755"/>
        <Path type='permissions' mode="0555" group="audio" owner="root" name="/dev/dsp"/>
        <Path type='permissions' mode="0555" group="audio" owner="root" name="/dev/mixer"/>
        <Path type='symlink' name="/bin/whatami" to="/mcs/adm/bin/whatami"/>
        <Path type='symlink' name="/chibahomes" to="/nfs/chiba-homefarm"/>
        <Path type='symlink' name="/home" to="/nfs/mcs-homefarm"/>
        <Path type='symlink' name="/homes" to="/home"/>
        <Path type='symlink' name="/mcs" to="/nfs/mcs"/>
        <Path type='symlink' name="/my/bin/bash" to="/bin/bash"/>
        <Path type='symlink' name="/my/bin/tcsh" to="/bin/tcsh"/>
        <Path type='symlink' name="/my/bin/zsh" to="/bin/zsh"/>
        <Path type='symlink' name="/software/common" to="/nfs/software-common"/>
        <Path type='symlink' name="/software/linux" to="/nfs/software-linux"/>
        <Path type='symlink' name="/software/linux-debian_sarge" to="/nfs/linux-debian_sarge"/>
        <Path type='symlink' name="/usr/bin/passwd" to="/usr/bin/yppasswd"/>
        <Path type='symlink' name="/usr/bin/yppasswd" to="/mcs/bin/passwd"/>
        <Path type='symlink' name="/usr/lib/libgd.so.1.8" to="/usr/lib/libgd.so.1.8.4"/>
        <Path type='symlink' name="/usr/lib/libtermcap.so.2" to="/usr/lib/libtermcap.so"/>
        <Path type='symlink' name="/usr/local/bin/perl" to="/usr/bin/perl"/>
        <Path type='symlink' name="/usr/local/bin/perl5" to="/usr/bin/perl"/>
        <Path type='symlink' name="/usr/local/bin/tcsh" to="/bin/tcsh"/>
        <Service name='ntpd' status='on' type='chkconfig'/>
        <Service name='haldaemon' status='on' type='chkconfig'/>
        <Service name='messagebus' status='on' type='chkconfig'/>
        <Service name='netfs' status='on' type='chkconfig'/>
        <Service name='network' status='on' type='chkconfig'/>
        <Service name='rawdevices' status='on' type='chkconfig'/>
        <Service name='sshd' status='on' type='chkconfig'/>
        <Service name='syslog' status='on' type='chkconfig'/>
        <Service name='vmware-tools' status='on' type='chkconfig'/>
    </Rules>

Using Regular Expressions in Rules
==================================

If you wish, you can configure the Rules plugin to support regular
expressions.  This entails a small performance and memory usage
penalty.  To do so, add the following setting to ``bcfg2.conf``::

  [rules]
  regex = yes

With regular expressions enabled, you can use a regex in the ``name``
attribute to match multiple abstract configuration entries.

Regular expressions are anchored at both ends, so ``<Service
name="bcfg2".../>`` will *not* match a Service named ``bcfg2-server``;
you'd have to explicitly specify ``<Service name="bcfg2.*".../>``.

Note that only one Rule can apply to any abstract entry, so you cannot
specify multiple regexes to match the same rule.