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

.. -*- mode: rst -*-
.. vim: ft=rst

.. _server-plugins-generators-rules:

=====
Rules
=====

The Rules plugin resolves the following Abstract Configuration Entities:

* Service
* Package
* Path
* Action
* All SELinux entries
* POSIXUser
* POSIXGroup

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
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.

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
---------

.. xml:element:: Rules
   :linktotype:
   :noautodep:
   :inlinetypes: RContainerType

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

.. xml:type:: PackageType

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

.. xml:type:: ActionType

See also :ref:`client-tools-actions`.

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

.. xml:type:: ServiceType

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

.. versionadded:: 1.3.0

In the 1.3.0 release, the "mode" attribute has been replaced by a pair
of attributes, :xml:attribute:`ServiceType:restart` and
:xml:attribute:`ServiceType: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.

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.  If a file has
no default context rule, and you don't wish to set one, you can
specify ``secontext=''`` (i.e., an empty ``secontext``), in which case
the client will not try to manage the SELinux context of the file at
all.

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

Attributes common to all Path tags:

.. xml:type:: PathType
   :nochildren:
   :noattributegroups:
   :nodoc:
   :notext:
   :onlyattrs: name,type


augeas
^^^^^^

Run `Augeas <http://www.augeas.net>`_ commands.  See
:ref:`client-tools-augeas` for more details.

.. xml:type:: PathType
   :nochildren:
   :noattributegroups:
   :nodoc:
   :notext:
   :onlyattrs: owner,group,mode,secontext,lens
   :requiredattrs: owner,group,mode

device
^^^^^^

Manage devices.

.. xml:type:: PathType
   :nochildren:
   :noattributegroups:
   :nodoc:
   :notext:
   :onlyattrs: dev_type,owner,group,mode,secontext,major,minor
   :requiredattrs: dev_type,owner,group,mode

directory
^^^^^^^^^

Entry represents a directory.  :xml:attribute:`PathType:prune` can be
set to remove all contents from the directory that are not explicitly
specified in Bcfg2.

.. xml:type:: PathType
   :nochildren:
   :noattributegroups:
   :nodoc:
   :notext:
   :onlyattrs: owner,group,mode,secontext,prune
   :requiredattrs: owner,group,mode

file
^^^^

Distribute an file with content explicitly specified in-line (i.e., as
opposed to using :ref:`server-plugins-generators-cfg` for this file).
If the file has no content, :xml:attribute:`PathType:empty` *must* be
set to ``true``.

.. xml:type:: PathType
   :nochildren:
   :noattributegroups:
   :nodoc:
   :onlyattrs: owner,group,mode,secontext,empty
   :requiredattrs: owner,group,mode

hardlink
^^^^^^^^

Manage a hard link.

.. xml:type:: PathType
   :nochildren:
   :noattributegroups:
   :nodoc:
   :notext:
   :onlyattrs: owner,group,mode,secontext,to
   :requiredattrs: owner,group,mode,to

.. _path-ignore:

ignore
^^^^^^

``ignore`` lets you flag files that are distributed by system software
packages, but have been modified locally, to be ignored by package
verification routines.  This is useful for, e.g., a package that
installs an initial version of a file and then modifies it
automatically.

.. xml:type:: PathType
   :nochildren:
   :noattributegroups:
   :nodoc:
   :notext:
   :onlyattrs: name
   :requiredattrs: name

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

Remove the specified file or directory.  If
:xml:attribute:`PathType:recursive` is set, remove the directory
recursively (i.e., ``rm -rf``).

.. xml:type:: PathType
   :nochildren:
   :noattributegroups:
   :nodoc:
   :notext:
   :onlyattrs: recursive

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

Merely set permissions on the specified path, which is presumed to
already exist.

.. xml:type:: PathType
   :nochildren:
   :noattributegroups:
   :nodoc:
   :notext:
   :onlyattrs: owner,group,mode,secontext,recursive
   :requiredattrs: owner,group,mode

symlink
^^^^^^^

Manage symlinks.

.. xml:type:: PathType
   :nochildren:
   :noattributegroups:
   :nodoc:
   :notext:
   :onlyattrs: to
   :requiredattrs: to

.. _server-plugins-generators-rules-vcs:

vcs
^^^

Check out the specified VCS repository to the given path.  See
:ref:`client-tools-vcs` for more details.

.. xml:type:: PathType
   :nochildren:
   :noattributegroups:
   :nodoc:
   :notext:
   :onlyattrs: vcstype,revision,sourceurl
   :requiredattrs: vcstype,revision,sourceurl

.. _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"/>
      <ACL type="default" scope="other" perms="r"/>
    </Path>

.. xml:element:: ACL

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.

For directories either no default ACL entries or at least an entry for
the owner, owning group and other must be defined.

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
^^^^^^^^^^^^^

.. xml:type:: SEBooleanType

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

.. xml:type:: SEPortType

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

.. xml:type:: SEFcontextType

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

.. xml:type:: SENodeType

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

.. xml:type:: SELoginType

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

.. xml:type:: SEUserType

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

.. xml:type:: SEInterfaceType

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

.. xml:type:: SEPermissiveType

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

.. xml:type:: SEModuleType

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

.. _server-plugins-generators-rules-posixuser-tag:

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.

.. xml:type:: POSIXUserType

For example:

.. code-block:: xml

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

The group specified will automatically be created if it does not
exist, even if there is no :xml:type:`POSIXGroup tag <POSIXGroupType>`
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>`.

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

.. _server-plugins-generators-rules-posixgroup-tag:

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.

.. xml:type:: POSIXGroupType

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.