.. -*- 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 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 --------- .. 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 `_ 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 vcs ^^^ Check out the specified VCS repository to the given path. .. 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 ```` tags. For instance: .. code-block:: xml .. 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 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 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 ```` will *not* match a Service named ``bcfg2-server``; you'd have to explicitly specify ````. Note that only one Rule can apply to any abstract entry, so you cannot specify multiple regexes to match the same rule.