diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/appendix/files/ntp.txt | 2 | ||||
| -rw-r--r-- | doc/appendix/guides/nat_howto.txt | 4 | ||||
| -rw-r--r-- | doc/development/client-driver.txt | 2 | ||||
| -rw-r--r-- | doc/server/configurationentries.txt | 167 | ||||
| -rw-r--r-- | doc/server/index.txt | 1 | ||||
| -rw-r--r-- | doc/server/info.txt | 45 | ||||
| -rw-r--r-- | doc/server/plugins/connectors/properties.txt | 194 | ||||
| -rw-r--r-- | doc/server/plugins/connectors/puppetenc.txt | 123 | ||||
| -rw-r--r-- | doc/server/plugins/generators/cfg.txt | 129 | ||||
| -rw-r--r-- | doc/server/plugins/generators/nagiosgen.txt | 8 | ||||
| -rw-r--r-- | doc/server/plugins/generators/packages.txt | 160 | ||||
| -rw-r--r-- | doc/server/plugins/generators/rules.txt | 297 | ||||
| -rw-r--r-- | doc/server/plugins/generators/semodules.txt | 66 | ||||
| -rw-r--r-- | doc/server/plugins/generators/sslca.txt | 8 | ||||
| -rw-r--r-- | doc/server/plugins/generators/tgenshi/index.txt | 2 | ||||
| -rw-r--r-- | doc/server/plugins/grouping/metadata.txt | 16 | ||||
| -rw-r--r-- | doc/server/plugins/misc/trigger.txt | 4 | ||||
| -rw-r--r-- | doc/server/plugins/plugin-roles.txt | 159 | ||||
| -rw-r--r-- | doc/server/plugins/probes/index.txt | 2 | ||||
| -rw-r--r-- | doc/server/selinux.txt | 97 |
20 files changed, 1025 insertions, 461 deletions
diff --git a/doc/appendix/files/ntp.txt b/doc/appendix/files/ntp.txt index ec1fa3094..53b3347c8 100644 --- a/doc/appendix/files/ntp.txt +++ b/doc/appendix/files/ntp.txt @@ -26,7 +26,7 @@ a client, a profile group, a list of packages, and a base configuration. .. code-block:: xml <Clients version='3.0'> - <Client profile='fedora' pingable='N' pingtime='0' name='foo.bar.com'/> + <Client profile='fedora' name='foo.bar.com'/> </Clients> ``Metadata/groups.xml``: diff --git a/doc/appendix/guides/nat_howto.txt b/doc/appendix/guides/nat_howto.txt index 818d3e644..5bd3f7b13 100644 --- a/doc/appendix/guides/nat_howto.txt +++ b/doc/appendix/guides/nat_howto.txt @@ -43,14 +43,14 @@ the Client entry in clients.xml will look something like this: .. code-block:: xml - <Client profile="desktop" name="test1" pingable="N" + <Client profile="desktop" name="test1" uuid='9001ec29-1531-4b16-8198-a71bea093d0a' location='floating'/> Alternatively, the Client entry can be setup like this: .. code-block:: xml - <Client profile="desktop" name="test1" pingable="N" + <Client profile="desktop" name="test1" uuid='9001ec29-1531-4b16-8198-a71bea093d0a' address='ip-address-of-NAT'/> The difference between these definitions is explained in detail in the diff --git a/doc/development/client-driver.txt b/doc/development/client-driver.txt index 32bb0aff4..c42d2b964 100644 --- a/doc/development/client-driver.txt +++ b/doc/development/client-driver.txt @@ -20,7 +20,7 @@ an existing driver, and the process that was used to create it. * Otherwise, subclass ``Bcfg2.Client.Tools.Tool`` (from here referenced as branch [T]) -#. Set ``__name__`` to "RPM" +#. Set ``name`` to "RPM" #. Add any required executable programs to ``__execs__`` #. Set ``__handles__`` to a list of (**entry.tag**, **entry.get('type')**) tuples. This determines which entries the Tool module can be used diff --git a/doc/server/configurationentries.txt b/doc/server/configurationentries.txt index 8e669b90a..fb1589926 100644 --- a/doc/server/configurationentries.txt +++ b/doc/server/configurationentries.txt @@ -1,138 +1,13 @@ .. -*- mode: rst -*- -.. NOTE: these are relative links (change when directory structure -.. changes) - -.. _Base: plugins/structures/base -.. _Bundler: plugins/structures/bundler -.. _Cfg: plugins/generators/cfg.html -.. _TGenshi: plugins/generators/tgenshi -.. _TCheetah: plugins/generators/tcheetah.html -.. _Rules: plugins/generators/rules.html - .. _server-configurationentries: ===================== Configuration Entries ===================== -This page describes the names and semantics of each of the configuration -entries used by Bcfg2. - -Non-POSIX entries -================= - -+-------------+---------------------+--------------------------------------------+ -| TagName | Description | Attributes | -+=============+=====================+============================================+ -| Action | Command | name, command, when, timing, status, build | -+-------------+---------------------+--------------------------------------------+ -| Package | Software Packages | name, type, version, url | -+-------------+---------------------+--------------------------------------------+ -| PostInstall | PostInstall command | name | -+-------------+---------------------+--------------------------------------------+ -| Service | System Services | name, type, status, target | -+-------------+---------------------+--------------------------------------------+ - -.. note:: - - PostInstall entries are deprecated in favor of Action entries. In - fact, a PostInstall entry is simply a specific type of Action. - Basically, the following are equivalent: - - .. code-block:: xml - - <PostInstall name='foo'/> - - and - - .. code-block:: xml - - <Action timing='post' when='modified' name='n' command='foo' status='ignore'/> - -POSIX entries -============= - -.. versionadded:: 1.0.0 - -The unified POSIX Path entries prevent inconsistent configuration -specifications of multiple entries for a given path. The following table -describes the various types available for new **Path** entries. - -The abstract specification of these entries (i.e. In `Bundler`_) -will only contain a *name* attribute. The type will be added by the -plugin that handles the entry in the case of `Cfg`_, `TGenshi`_, or -`TCheetah`_. If the entry is handled by the `Rules`_ plugin (i.e. it is -a device, directory, hardlink, symlink, etc), then you will specify both -the *type* and any other necessary attributes in `Rules`_. - -Running ``bcfg2-lint`` will check your configuration specification for -the presence of any mandatory attributes that are necessary for the -Path type specified. - -.. note:: A tool for converting old POSIX entries is available in the - Bcfg2 source directory at tools/posixunified.py - -+-------------+----------------------+-----------------+--------------------------+ -| Type | Replacement/New | Description | Attributes | -+=============+======================+=================+==========================+ -| device | New | Create block, | name, owner, group, | -| | | character, and | dev_type | -| | | fifo devices | (block, char, fifo), | -| | | | major/minor | -| | | | (for block/char devices) | -+-------------+----------------------+-----------------+--------------------------+ -| directory | Replaces Directory | Directories | name, owner, group, | -| | entries | | perms, prune | -+-------------+----------------------+-----------------+--------------------------+ -| file | Replaces ConfigFile | Configuration | name, owner, group, | -| | entries | File | perms, encoding, empty | -| | | | | -| | | | **Note:** see below | -+-------------+----------------------+-----------------+--------------------------+ -| hardlink | New | Create | name, to | -| | | hardlinks | | -+-------------+----------------------+-----------------+--------------------------+ -| symlink | Replaces SymLink | SymLinks | name, to | -| | entries | | | -+-------------+----------------------+-----------------+--------------------------+ -| ignore | New | Ignore files | name | -| | | that cause | | -| | | package | | -| | | verification | | -| | | failures | | -| | | (currently | | -| | | applies to only | | -| | | APT and YUMng) | | -+-------------+----------------------+-----------------+--------------------------+ -| nonexistent | New | Specify a path | name, recursive | -| | | that should not | | -| | | exist | | -+-------------+----------------------+-----------------+--------------------------+ -| permissions | Replaces Permissions | Permissions of | name, owner, group, | -| | entries | POSIX entities | perms, recursive | -| | | | | -+-------------+----------------------+-----------------+--------------------------+ -| vcs | New | Create version | vcstype (git), | -| | | control | sourceurl, revision | -| | | checkout | | -+-------------+----------------------+-----------------+--------------------------+ - -Keep in mind that permissions for files handled by Cfg/TGenshi/TCheetah -are still handled via the traditional :ref:`server-info` mechanisms. - -Additional information ----------------------- - -This section describes some additional behavior relating to POSIX entry -attributes. - -Recursive permissions -^^^^^^^^^^^^^^^^^^^^^ - -As per the request in ticket 871, Path type='permissions' entries allow you to -set a recursive attribute which allows the owner/group to be set recursively -for a directory. +The full semantics of each configuration entry is documented with the +:ref:`server-plugins-generators-rules` plugin. .. _boundentries: @@ -178,13 +53,14 @@ Use Cases Examples -------- -* Consider the case of ``/etc/hosts`` on linux and ``/etc/inet/hosts`` on - solaris. These files contain the same data in the same format, +* Consider the case of ``/etc/hosts`` on linux and ``/etc/inet/hosts`` + on solaris. These files contain the same data in the same format, and should typically be synchronized, however, exist in different locations. Classically, one would need to create one entry for each - in `Cfg`_ or `TCheetah`_ and perform manual synchronization. Or, - you could use symlinks and pray. Altsrc is driven from the bundle - side. For example: + in :ref:`server-plugins-generators-cfg` or + :ref:`server-plugins-generators-tcheetah` and perform manual + synchronization. Or, you could use symlinks and pray. Altsrc is + driven from the bundle side. For example: .. code-block:: xml @@ -220,10 +96,12 @@ Examples named "openssl" with different types. * Finally, consider the case where there exist complicated, but - completely independent specifications for the same configuration entry - but different groups of clients. The following bundle will allow the use - of two different `TCheetah`_ templates ``/etc/firewall-rules-external`` - and ``/etc/firewall-rules-internal`` for different clients based on + completely independent specifications for the same configuration + entry but different groups of clients. The following bundle will + allow the use of two different + :ref:`server-plugins-generators-tcheetah` templates + ``/etc/firewall-rules-external`` and + ``/etc/firewall-rules-internal`` for different clients based on their group membership. .. code-block:: xml @@ -239,11 +117,13 @@ Examples </Bundle> * Consider the case where a variety of files can be constructed by a - single template (`TCheetah`_ or `TGenshi`_). It would be possible to - copy this template into the proper location for each file, but that - requires proper synchronization upon modification and knowing up front - what the files will all be called. Instead, the following bundle allows - the use of a single template for all proper config file instances. + single template (:ref:`server-plugins-generators-tcheetah` or + :ref:`server-plugins-generators-tgenshi-index`). It would be + possible to copy this template into the proper location for each + file, but that requires proper synchronization upon modification and + knowing up front what the files will all be called. Instead, the + following bundle allows the use of a single template for all proper + config file instances. .. code-block:: xml @@ -253,5 +133,6 @@ Examples <Path name='/etc/sysconfig/network-scripts/ifcfg-eth2' altsrc='/etc/ifcfg-template'/> </Bundle> - altsrc can be used as a parameter for any entry type, and can be used - in any structure, including `Bundler`_ and `Base`_. + altsrc can be used as a parameter for any entry type, and can be + used in any structure, including + :ref:`server-plugins-structures-bundler-index`. diff --git a/doc/server/index.txt b/doc/server/index.txt index 9c427a0f4..fb1c95444 100644 --- a/doc/server/index.txt +++ b/doc/server/index.txt @@ -28,3 +28,4 @@ clients. info snapshots/index bcfg2-info + selinux diff --git a/doc/server/info.txt b/doc/server/info.txt index d949aab68..d6bcf67e2 100644 --- a/doc/server/info.txt +++ b/doc/server/info.txt @@ -1,8 +1,5 @@ .. -*- mode: rst -*- -.. NOTE: these are relative links (change when directory structure -.. changes) - .. _server-info: ==== @@ -26,24 +23,29 @@ possible fields in an info file are: +------------+-------------------+----------------------------------+---------+ | Field | Possible values | Description | Default | +============+===================+==================================+=========+ -| encoding: | ascii | base64 | Encoding of the file. Use | ascii | +| encoding | ascii | base64 | Encoding of the file. Use | ascii | | | | base64 for binary files | | +------------+-------------------+----------------------------------+---------+ -| group: | Any valid group | Sets group of the file | root | +| owner | Any valid user | Sets owner of the file | root | +------------+-------------------+----------------------------------+---------+ -| important: | true | false | Important entries are | false | -| | | installed first during client | | -| | | execution | | +| group | Any valid group | Sets group of the file | root | +------------+-------------------+----------------------------------+---------+ -| owner: | Any valid user | Sets owner of the file | root | +| perms | Numeric file mode | Sets the permissions of the file | 0644 | +| | | 'inherit' | (or inherits from the files on | | +| | | disk if set to 'inherit') | | +------------+-------------------+----------------------------------+---------+ -| paranoid: | true | false | Backup file before replacement? | true | +| secontext | A valid SELinux | Sets the SELinux context of the | default | +| | context string or | file, or sets to the default | | +| | '__default__' | context set by policy if set to | | +| | | '__default__' | | +------------+-------------------+----------------------------------+---------+ -| perms: | Numeric file mode | Sets the permissions of the file | 0644 | -| | | 'inherit' | (or inherits from the files on | | -| | | disk if set to inherit) | | +| important | true | false | Important entries are | false | +| | | installed first during client | | +| | | execution | | +------------+-------------------+----------------------------------+---------+ -| sensitive: | true | false | The contents of sensitive | false | +| paranoid | true | false | Backup file before replacement? | true | ++------------+-------------------+----------------------------------+---------+ +| sensitive | true | false | The contents of sensitive | false | | | | entries aren't included in | | | | | reports | | +------------+-------------------+----------------------------------+---------+ @@ -54,15 +56,26 @@ A sample info file for CGI script on a web server might look like:: group: www perms: 0755 +The equivalent ``info.xml`` file would be: + +.. code-block:: xml + + <FileInfo> + <Info owner="www" group="www" perms="0755"/> + </FileInfo> + Back to the fstab example again, our final ``Cfg/etc/fstab/`` directory might look like:: - :info + info.xml fstab fstab.G50_server fstab.G99_fileserver fstab.H_host.example.com +See :ref:`server-selinux` for more information on the ``secontext`` +attribute and managing SELinux in general. + Important attribute =================== @@ -76,7 +89,7 @@ specification. +------------+-------------------+----------------------------------+---------+ | Field | Possible values | Description | Default | +============+===================+==================================+=========+ -| important: | true | false | Important entries are | root | +| important | true | false | Important entries are | root | | | | installed first during client | | | | | execution | | +------------+-------------------+----------------------------------+---------+ diff --git a/doc/server/plugins/connectors/properties.txt b/doc/server/plugins/connectors/properties.txt index 7695e902c..b56c2a488 100644 --- a/doc/server/plugins/connectors/properties.txt +++ b/doc/server/plugins/connectors/properties.txt @@ -33,25 +33,95 @@ be checked when running ``bcfg2-lint``. For instance, given:: ``dns-config.xml`` will be validated against ``dns-config.xsd``. +Although Properties files are technically freeform XML, the top-level +XML tag should be ``<Properties>``. + Usage ===== -Specific property files can be referred to in -templates as ``metadata.Properties[<filename>]``. The -``xdata`` attribute is an LXML element object. (Documented -`here <http://codespeak.net/lxml/tutorial.html#the-element-class>`_) +Specific property files can be referred to in templates as +``metadata.Properties[<filename>]``. The ``xdata`` attribute is an +lxml.etree._Element object. (Documented `here +<http://codespeak.net/lxml/tutorial.html#the-element-class>`_) + +In addition to the ``xdata`` attribute that can be used to access the +raw data, the following access methods are defined: -Currently, only one access method is defined for this data, ``Match``. -``Match`` parses the Group and Client tags in the file and returns a -list of elements that apply to the client described by a set of -metadata. (See :ref:`server-plugins-structures-bundler-index` for -more details on how Group and Client tags are parsed.) For instance:: +* ``Match()`` parses the Group and Client tags in the file and returns + a list of elements that apply to the client described by a set of + metadata. For instance:: {% python ntp_servers = [el.text - for el in metadata.Properties['ntp.xml'].Match(metadata): + for el in metadata.Properties['ntp.xml'].Match(metadata) if el.tag == "Server"] %} +* ``XMLMatch()`` parses the Group and Client tags in the file and + returns an XML document containing only the data that applies to the + client described by a set of metadata. (The Group and Client tags + themselves are also removed, leaving only the tags and data + contained in them.) For instance:: + + {% python + ntp_servers = [el.text + for el in metadata.Properties['ntp.xml'].XMLMatch(metadata).findall("//Server")] + %} + +As we formulate more common use cases, we will add them to the +``PropertyFile`` class as methods. This will simplify templates. + +You can also access the XML data that comprises a property file +directly in one of several ways: + +* ``metadata.Properties['prop-file'].xdata`` is an lxml.etree._Element + object representing the top-level element in the file. +* ``metadata.Properties['prop-file'].data`` is the raw contents of the + property file as a string. +* ``metadata.Properties['prop-file'].entries`` is a list of + lxml.etree._Element objects representing the direct children of the + top-level element. (I.e., everything directly under the + ``<Properties>`` tag.) + +.. _server-plugins-connectors-properties-automatch: + +Automatch +========= + +.. versionadded:: 1.3.0 + +You can enable ``XMLMatch()`` for all Property files by setting +``automatch`` to ``true`` in the ``[properties]`` section of +``bcfg2.conf``. This makes ``metadata.Properties`` values +lxml.etree._Element objects that contain only matching data. (This +makes it impossible to do +:ref:`server-plugins-connectors-properties-write-back` as a +side-effect.) + +In Python terms, setting ``automatch=true`` is the same as doing the +following at the top of each template:: + + {% python + for prop in metadata.Properties.values(): + prop = prop.XMLMatch(metadata) + %} + +The example above that describes ``XMLMatch()`` would then become +simply:: + + {% python + ntp_servers = [el.text + for el in metadata.Properties['ntp.xml'].findall("//Server")] + %} + +You can also enable automatch for individual Property files by setting +the attribute ``automatch="true"`` in the top-level ``<Property>`` tag. + +.. _server-plugins-connectors-properties-write-back: + +Writing to Properties files +=========================== + +.. versionadded:: 1.2.0 If you need to make persistent changes to properties data, you can use the ``write`` method of the ``PropertyFile`` class:: @@ -68,20 +138,82 @@ the ``write`` method of the ``PropertyFile`` class:: The ``write`` method checks the data in the object against its schema before writing it; see `Data Structures`_ for details. -As we formulate more common use cases, we will add them to the -``PropertyFile`` class as methods. This will simplify templates. +Note that use of the ``write`` method can cause race conditions if you +run more than one Bcfg2 server. If you run more than one Bcfg2 +server, you can disable Properties write-back by setting the following +in ``bcfg2.conf``:: -You can also access the XML data that comprises a property file -directly in one of several ways: + [properties] + writes_enabled = false -* ``metadata.Properties['prop-file'].xdata`` is an lxml.etree._Element - object representing the top-level element in the file. -* ``metadata.Properties['prop-file'].data`` is the raw contents of the - property file as a string. -* ``metadata.Properties['prop-file'].entries`` is a list of - lxml.etree._Element objects representing the direct children of the - top-level element. (I.e., everything directly under the - ``<Properties>`` tag.) +.. _server-plugins-connectors-properties-encrypted: + +Encrypted Properties data +========================= + +.. versionadded:: 1.3.0 + +You can encrypt selected data in Properties files to protect that data +from other people who need access to the repository. See +:ref:`server-plugins-generators-cfg-configuring-encryption` for +details on configuring encryption passphrases. The data is decrypted +transparently on-the-fly by the server; you never need to decrypt the +data in your templates. + +.. note:: + + This feature is *not* intended to secure the files against a + malicious attacker who has gained access to your Bcfg2 server, as + the encryption passphrases are held in plaintext in + ``bcfg2.conf``. This is only intended to make it easier to use a + single Bcfg2 repository with multiple admins who should not + necessarily have access to each other's sensitive data. + +Properties files are encrypted on a per-element basis; that is, rather +than encrypting the whole file, only the character content of +individual elements is encrypted. This makes it easier to track +changes to the file in a VCS, and also lets unprivileged users work +with the other data in the file. Only character content of an element +can be encrypted; attribute content and XML elements themselves cannot +be encrypted. + +To encrypt a file, use ``bcfg2-crypt``, e.g.:: + + bcfg2-crypt foo.xml + +If the top-level tag of a Properties file is not ``<Properties>``, +then you need to use the ``--properties`` flag to ``bcfg2-crypt``:: + + bcfg2-crypt --properties foo.xml + +The first time you run ``bcfg2-crypt`` on a Properties file, it will +encrypt all character data of all elements. Additionally, it will add +``encrypted="<key name>"`` to each element that has encrypted character +data. It also adds ``encryption="true"`` to the top-level +``<Properties>`` tag as a flag to the server that it should try to +decrypt the data in that file. (If you are using Properties schemas, +you will need to make sure to add support for these attributes.) On +subsequent runs, only those elements flagged with ``encrypted="*"`` +are encrypted or decrypted. + +To decrypt a Properties file, simply re-run ``bcfg2-crypt``:: + + bcfg2-crypt foo.xml + +This decrypts the encrypted elements, but it does *not* remove the +``encrypted`` attribute; this way, you can decrypt a Properties +file, modify the contents, and then simply re-run ``bcfg2-crypt`` to +encrypt it again. If you added elements that you also want to be +encrypted, you can either add the ``encrypted`` attribute to +them manually, or run:: + + bcfg2-crypt --xpath '*' foo.xml + +You can also use the ``--xpath`` option to specify more restrictive +XPath expressions to only encrypt a subset of elements, or to encrypt +different elements with different passphrases. Alternatively, you can +manally set the ``encrypted`` attribute on various elements and +``bcfg2-crypt`` will automatically do the right thing. Accessing Properties contents from TGenshi ========================================== @@ -89,3 +221,21 @@ Accessing Properties contents from TGenshi Access contents of ``Properties/auth.xml``:: ${metadata.Properties['auth.xml'].xdata.find('file').find('bcfg2.key').text} + +Configuration +============= + +``bcfg2.conf`` contains several miscellaneous configuration options +for the Properties plugin, which can be set in the ``[properties]`` +section. Any booleans in the config file accept the values "1", "yes", +"true", and "on" for True, and "0", "no", "false", and "off" for +False. + +It understands the following directives: + +* ``automatch``: Enable + :ref:`server-plugins-connectors-properties-automatch`. Default is + false. +* ``writes_enabled``: Enable + :ref:`server-plugins-connectors-properties-write-back`. Default is + true. diff --git a/doc/server/plugins/connectors/puppetenc.txt b/doc/server/plugins/connectors/puppetenc.txt new file mode 100644 index 000000000..dc472c546 --- /dev/null +++ b/doc/server/plugins/connectors/puppetenc.txt @@ -0,0 +1,123 @@ +.. -*- mode: rst -*- + +.. _server-plugins-connectors-puppetenc: + +========= +PuppetENC +========= + +PuppetENC is a connector plugin that adds support for Puppet External +Node Classifiers +(`<http://docs.puppetlabs.com/guides/external_nodes.html>`_), or ENCs. + +Output Format +============= + +The PuppetENC plugin implements the Puppet 2.6.5+ ENC output format +with some modifications. The basic output format is described `here +<http://docs.puppetlabs.com/guides/external_nodes.html#puppet-265-and-higher>`_. +The following modifications apply: + +* ``classes`` are considered to be Bcfg2 groups. (This is basically + just a difference in terminology between Puppet and Bcfg2; Bcfg2 + calls "groups" what Puppet calls "classes.") +* As an alternative to the Puppet-specific ``classes`` value, you may + use ``groups`` if you are writing an ENC from scratch specifically + for Bcfg2. +* Since Bcfg2 does not have the notion of parameterized classes, any + class parameters provided will be merged in with the ``parameters`` + dict. +* ``parameters`` are presented as connector data. (See Usage + below.) +* The ``environment`` value is not supported. If present, PuppetENC + will issue a warning and skip it. + +The ``parameters`` from separate ENCs are all merged together, +including parameters from any parameterized classes. This is a +shallow merge; in other words, only the top-level keys are +considered. For instance, assuming you had one ENC that produced:: + + parameters: + ntp_servers: + - 0.pool.ntp.org + - ntp1.example.com + +And another that produced:: + + parameters: + ntp_servers: + - ntp2.example.com + +This would result in connector data that included *either* the first +value of ``ntp_servers`` *or* the second, but not both; this would +depend on the order in which the ENCs were run, which is +non-deterministic and should not be relied upon. However, if you add +one ENC that produced:: + + parameters: + ntp_servers: + - 0.pool.ntp.org + - ntp1.example.com + +And another that produced:: + + parameters: + mail_servers: + - mail.example.com + +Then the connector data would consist of:: + + {"ntp_servers": ["0.pool.ntp.org", "ntp1.example.com"], + "mail_servers": ["mail.example.com"]} + +Usage +===== + +To use the PuppetENC plugin, first do ``mkdir +/var/lib/bcfg2/PuppetENC``. Add ``PuppetENC`` to your ``plugins`` +line in ``/etc/bcfg2.conf``. Now you can place any ENCs you wish to +run in ``/var/lib/bcfg2/PuppetENC``. Note that ENCs are run each time +client metadata is generated, so if you have a large number of ENCs or +ENCs that are very time-consuming, they could have a significant +impact on server performance. In that case, it could be worthwhile to +write a dedicated Connector plugin. + +PuppetENC parameters can be accessed in templates as +``metadata.PuppetENC``, which is a dict of all parameter data merged +together. For instance, given the following ENC output:: + + --- + classes: + common: + puppet: + ntp: + ntpserver: 0.pool.ntp.org + aptsetup: + additional_apt_repos: + - deb localrepo.example.com/ubuntu lucid production + - deb localrepo.example.com/ubuntu lucid vendor + parameters: + ntp_servers: + - 0.pool.ntp.org + - ntp.example.com + mail_server: mail.example.com + iburst: true + environment: production + +``metadata.PuppetENC`` would contain:: + + 'additional_apt_repos': ['deb localrepo.example.com/ubuntu lucid production', + 'deb localrepo.example.com/ubuntu lucid vendor'], + 'iburst': True, + 'mail_server': 'mail.example.com', + 'ntp_servers': ['0.pool.ntp.org', 'ntp.example.com'], + 'ntpserver': '0.pool.ntp.org'} + +(Note that the duplication of NTP server data doesn't make this an +especially *good* example; it's just the official Puppet example.) + +So, in a template you could do something like:: + + {% for repo in metadata.PuppetENC['additional_apt_repos'] %}\ + ${repo} + {% end %}\ diff --git a/doc/server/plugins/generators/cfg.txt b/doc/server/plugins/generators/cfg.txt index ba02b929d..6c848fddb 100644 --- a/doc/server/plugins/generators/cfg.txt +++ b/doc/server/plugins/generators/cfg.txt @@ -35,24 +35,24 @@ templating -- see below). Group-Specific Files ==================== -It is often that you want one version of a config file for all of your -machines except those in a particular group. For example, ``/etc/fstab`` -should look alike on all of your desktop machines, but should be -different on your file servers. Bcfg2 can handle this case through use -of group-specific files. +It is often the case that you want one version of a config file for +all of your machines except those in a particular group. For example, +``/etc/fstab`` should look alike on all of your desktop machines, but +should be different on your file servers. Bcfg2 can handle this case +through use of group-specific files. As mentioned above, all Cfg entries live in like-named directories at the end of their directory tree. In the case of fstab, the file at ``Cfg/etc/fstab/fstab`` will be handed out by default to any client that asks for a copy of ``/etc/fstab``. Group-specific files are located in -the same directory and are named with the syntax:: +the same directory and are named with the following syntax:: /path/to/filename/filename.GNN_groupname -in which **NN** is a priority number where **00** is lowest and -**99** is highest, and **groupname** is the name of a group defined in +**NN** is a priority number where **00** is lowest and **99** +is highest, and **groupname** is the name of a group defined in ``Metadata/groups.xml``. Back to our fstab example, we might have a -``Cfg/etc/fstab/`` directory that looks like:: +``Cfg/etc/fstab/`` directory that looks like this:: fstab fstab.G50_server @@ -139,6 +139,99 @@ using different host-specific or group-specific files. For example: Cfg/etc/fstab/fstab.H_host.example.com.genshi Cfg/etc/fstab/fstab.G50_server.cheetah +Encrypted Files +=============== + +.. versionadded:: 1.3.0 + +Bcfg2 allows you to encrypt files stored in ``Cfg/`` to protect the +data in them from other people who need access to the repository. See +also :ref:`server-plugins-connectors-properties-encrypted` for +information on encrypting elements in Properties files, which is often +more friendly for tracking changes in a VCS. + +.. note:: + + This feature is *not* intended to secure the files against a + malicious attacker who has gained access to your Bcfg2 server, as + the encryption passphrases are held in plaintext in + ``bcfg2.conf``. This is only intended to make it easier to use a + single Bcfg2 repository with multiple admins who should not + necessarily have access to each other's sensitive data. + +Encrypting Files +---------------- + +An encrypted file should end with ``.crypt``, e.g.:: + + Cfg/etc/foo.conf + Cfg/etc/foo.conf/foo.conf.crypt + Cfg/etc/foo.conf/foo.conf.G10_foo.crypt + +Encrypted Genshi or Cheetah templates can have the extensions in +either order, e.g.:: + + Cfg/etc/foo.conf/foo.conf.crypt.genshi + Cfg/etc/foo.conf/foo.conf.G10_foo.genshi.crypt + Cfg/etc/foo.conf/foo.conf.H_bar.example.com.crypt.cheetah + +To encrypt a file, you can use ``bcfg2-crypt``, e.g.:: + + bcfg2-crypt foo.conf + +Once you are satisfied that the file has been encrypted as you wish, +you can remove the plaintext version, or you can use the ``--remove`` +flag of ``bcfg2-crypt``. + +To decrypt a file, simply run ``bcfg2-crypt`` again:: + + bcfg2-crypt foo.conf + +See the ``bcfg2-crypt`` man page for more information. + +``bcfg2-crypt`` simply performs an AES256 encryption, and is +more-or-less equivalent to the following commands (encryption and +decryption, respectively:: + + openssl enc -aes-256-cbc -k <passphrase> -in foo.conf -out foo.conf.crypt -a + openssl enc -d -aes-256-cbc -k <passphrase> -in foo.conf.crypt -out foo.conf -a + +.. _server-plugins-generators-cfg-configuring-encryption: + +Configuring Encryption +---------------------- + +To configure encryption, add a ``[encryption]`` section to +``bcfg2.conf`` with any number of name-passphrase pairs. When +decrypting a file, _all_ passphrases will be tried; the passphrase +name is currently purely cosmetic, but at some point in the future the +ability to give Bcfg2 a "hint" about which passphrase to use will be +added. + +For instance:: + + [encryption] + foo_team=P4ssphr4se + bar_team=Pa55phra5e + +This would define two separate encryption passphrases, presumably for +use by two separate teams. The passphrase names are completely +arbitrary. + +Note that this does entail a chicken-and-egg problem. In order for +the Bcfg2 server to be able to decrypt encrypted files, the +passphrases must exist in ``bcfg2.conf`` in plaintext; but, if you're +encrypting data, presumably you don't want to include those plaintext +passphrases in your Bcfg2 repository, so you'll want to encrypt +``bcfg2.conf``. The best way to solve this is: + +#. On your Bcfg2 server, manually add the ``[encryption]`` section to + ``bcfg2.conf`` and restart the Bcfg2 server. +#. Update ``bcfg2.conf`` in your Bcfg2 repository with the + passphrases, and encrypt it. + +The first (manual) step breaks the mutual dependency. + Deltas ====== @@ -237,13 +330,19 @@ For ``sudoers``, a very simple validator is:: This uses the ``visudo`` command's built-in validation. -.. note: +If you wish to disable validation, this can be done with the following +setting in ``bcfg2.conf``:: + + [cfg] + validation=no - Before 1.3 is released, it will be possible to disable validation - in the configuration, but enable it for ``bcfg2-test``. This is - recommended for heavily-used servers, since running an external - command is fairly resource intensive and could quickly exhaust the - file descriptors of a server. +If you have a very large number of validators, you may wish to disable +validation by default to avoid slowing down the generation of +configurations on the server, and use ``bcfg2-test`` (for instance, as +a post-commit hook or as part of a code review process) to run +validation. You can do this by setting ``validation=no`` in +``bcfg2.conf`` as described above, and then calling ``bcfg2-test`` +with the ``--cfg-validation`` flag. File permissions ================ diff --git a/doc/server/plugins/generators/nagiosgen.txt b/doc/server/plugins/generators/nagiosgen.txt index b839c10ca..f722909fc 100644 --- a/doc/server/plugins/generators/nagiosgen.txt +++ b/doc/server/plugins/generators/nagiosgen.txt @@ -20,7 +20,7 @@ Create the NagiosGen directory:: Create default host, and group specs in: -* /var/lib/bcfg2/NagiosGen/default-host.cfg:: +``/var/lib/bcfg2/NagiosGen/default-host.cfg``:: define host{ name default @@ -44,7 +44,7 @@ Create default host, and group specs in: retry_interval 1 } -* /var/lib/bcfg2/NagiosGen/default-group.cfg:: +``/var/lib/bcfg2/NagiosGen/default-group.cfg``:: define service{ name default-service @@ -73,7 +73,7 @@ Create default host, and group specs in: Create group configuration files (Named identical to Bcfg2 groups) and add services, and commands specific to the hostgroup (Bcfg2 group) in -* /var/lib/bcfg2/NagiosGen/base-group.cfg:: +``/var/lib/bcfg2/NagiosGen/base-group.cfg``:: define hostgroup{ hostgroup_name base @@ -100,7 +100,7 @@ add services, and commands specific to the hostgroup (Bcfg2 group) in hostgroup_name base } -* /var/lib/bcfg2/NagiosGen/web-server-group.cfg:: +``/var/lib/bcfg2/NagiosGen/web-server-group.cfg``:: define hostgroup{ hostgroup_name web-server diff --git a/doc/server/plugins/generators/packages.txt b/doc/server/plugins/generators/packages.txt index 62574be76..fc2e30980 100644 --- a/doc/server/plugins/generators/packages.txt +++ b/doc/server/plugins/generators/packages.txt @@ -126,17 +126,19 @@ Disabling dependency resolution .. versionadded:: 1.1.0 -Dependency resolution can be disabled by adding this to -``Packages/packages.conf`` in the ``global`` section:: +Dependency resolution can be disabled by adding the following setting +to ``bcfg2.conf`` in the ``packages`` section:: - [global] + [packages] resolver=0 All metadata processing can be disabled as well:: - [global] + [packages] metadata=0 +This setting implies disabling the resolver. + Blacklisting faulty dependencies -------------------------------- @@ -145,7 +147,9 @@ Packages, please file a bug report so that we can fix the problem in future releases. In the meantime, you can work around this issue by blacklisting the offending Package in your Sources. The blacklist element should immediately follow the Component section of your source -and should look like the following:: +and should look like the following: + +.. code-block:: xml <Blacklist>unwanted-packagename</Blacklist> @@ -162,7 +166,9 @@ If you have yum libraries installed, Packages can automatically handle GPG signing keys for Yum and Pulp repositories. (You do not need to use the native yum resolver; if yum libraries are available, GPG signing keys can be handled automatically.) Simply specify the URL to -the GPG key(s) for a repository in ``sources.xml``:: +the GPG key(s) for a repository in ``sources.xml``: + +.. code-block:: xml <Source type="yum" rawurl="http://mirror.example.com/centos6-x86_64/RPMS.os"> @@ -176,17 +182,53 @@ With the keys specified thusly, Packages will include the keys in the generated yum config file, and will ensure that the keys are imported on the client. -There is no need to specify ``<GPGKey>`` tags for :ref:``Pulp sources -<pulp-source-support>``; that data is pulled directly from the Pulp +There is no need to specify ``<GPGKey>`` tags for :ref:`Pulp sources +<pulp-source-support>`; that data is pulled directly from the Pulp REST API. +Arbitrary Repo Options +---------------------- + +.. versionadded:: 1.2.3 + +You can specify arbitrary options to be added to the repository config +on the server side, if you are using the native yum libraries, and on +the client side if you are using the ability of Packages to +automatically generate your Yum config. To do this, add an +``<Options>`` tag to a Source; all of its attributes will be added +verbatim to the repository in the generated config. For instance: + +.. code-block:: xml + + <Source type="yum" rawurl="http://mirror.example.com/centos-6-os"> + <Arch>x86_64</Arch> + <Options proxy="http://proxy.example.com"/> + </Source> + +If you are using native yum libraries and need to set options only on +the Bcfg2 server, you can set the ``serveronly`` attribute to "true"; +or, if you need to set options only on the client, you can set the +``clientonly`` attribute to "true". For instance, if your Bcfg2 +server needed to use a proxy to access a repo, and you wanted to +expire metadata caches very quickly on the client, you could do: + +.. code-block:: xml + + <Source type="yum" rawurl="http://mirror.example.com/centos-6-os"> + <Arch>x86_64</Arch> + <Options serveronly="true" proxy="http://proxy.example.com"/> + <Options clientonly="true" metadata_expire="0"/> + </Source> + .. _packages-exampleusage: Example usage ============= Create a ``sources.xml`` file in the Packages directory that looks -something like this:: +something like this: + +.. code-block:: xml <Sources> <Group name="ubuntu-intrepid"> @@ -228,7 +270,9 @@ something like this:: <Source type="apt" essential="false" ...> -Yum sources can be similarly specified:: +Yum sources can be similarly specified: + +.. code-block:: xml <Sources> <Group name="centos-5.2"> @@ -248,8 +292,10 @@ Yum sources can be similarly specified:: For sources with a **URL** attribute, the **Version** attribute is also necessary. -:ref:``Pulp sources <pulp-source-support>`` are very simple to specify -due to the amount of data that can be queried from Pulp itself:: +:ref:`Pulp sources <pulp-source-support>` are very simple to specify +due to the amount of data that can be queried from Pulp itself: + +.. code-block:: xml <Sources> <Group name="centos-6-x86_64"> @@ -353,20 +399,13 @@ be validated using ``bcfg2-lint``. .. note:: The schema requires that elements be specified in the above order. -Limitations -=========== - -Packages does not do traditional caching as other plugins -do. Modifying sources in the Packages ``sources.xml`` file requires a -server restart for the time being. You do not have to restart the -server after changing ``packages.conf`` or after adding new sources to -``sources.xml``. - Package Checking and Verification ================================= In order to do disable per-package verification Pkgmgr style, you will -need to use :ref:`BoundEntries <boundentries>`, e.g.:: +need to use :ref:`BoundEntries <boundentries>`, e.g.: + +.. code-block:: xml <BoundPackage name="mem-agent" priority="1" version="auto" type="yum" verify="false"/> @@ -380,10 +419,10 @@ Generating Client APT/Yum Configurations .. versionadded:: 1.2.0 The Packages plugin has native support for generating Yum configs. -You must set ``yum_config`` in ``Packages/packages.conf`` to the path -to the yum config file you want to generate:: +You must set ``yum_config`` in ``bcfg2.conf`` to the path to the yum +config file you want to generate:: - [global] + [packages] yum_config=/etc/yum.repos.d/all.repo Then add the corresponding Path entry to your Yum bundle. @@ -414,7 +453,7 @@ resolution and other routines so that the Bcfg2 server can be run on a host that does not support Yum itself. If you run the Bcfg2 server on a machine that does have Yum libraries, however, you can enable use of those native libraries in Bcfg2 by setting ``use_yum_libraries`` to -``1`` in the ``[yum]`` section of ``Packages/packages.conf``. +``1`` in the ``[packages:yum]`` section of ``bcfg2.conf``. Benefits to this include: @@ -440,23 +479,24 @@ Configuring the Yum Helper Due to poor memory management by the Yum API, the long-lived bcfg2-server process uses an external short-lived helper, ``bcfg2-yum-helper``, to do the actual Yum API calls for native yum -library support. By default, Bcfg2 looks for this helper at -``/usr/sbin/bcfg2-yum-helper``. If you have installed the helper -elsewhere, you will need to configure that location with the -``helper`` option in the ``[yum]`` section, e.g.:: +library support. By default, Bcfg2 looks for this helper in +``$PATH``, or, failing that, at ``/usr/sbin/bcfg2-yum-helper``. If +you have installed the helper elsewhere, you will need to configure +that location with the ``helper`` option in the ``[packages:yum]`` +section, e.g.:: - [yum] + [packages:yum] use_yum_libraries = 1 helper = /usr/local/sbin/bcfg2-yum-helper Setting Yum Options ------------------- -In ``Packages/packages.conf``, any options you set in the ``[yum]`` +In ``bcfg2.conf``, any options you set in the ``[packages:yum]`` section other than ``use_yum_libraries`` and ``helper`` will be passed along verbatim to the configuration of the Yum objects used in the -Bcfg2 server. The following options are set by default, and should -not generally be overridden: +Bcfg2 server. The following options are set by default, and should not +generally be overridden: * ``cachedir`` is set to a hashed value unique to each distinct Yum configuration. Don't set this unless you know what you're doing. @@ -472,14 +512,18 @@ Package Groups Yum package groups are supported by the native Yum libraries. To include a package group, use the ``group`` attribute of the ``Package`` tag. You can use either the short group ID or the long -group name:: +group name: + +.. code-block:: xml <Package group="SNMP Support"/> <Package group="system-management-snmp"/> By default, only those packages considered the "default" packages in a group will be installed. You can change this behavior using the -"type" attribute:: +"type" attribute: + +.. code-block:: xml <Package group="development" type="optional"/> <Package group="Administration Tools" type="mandatory"/> @@ -506,7 +550,9 @@ Pulp Support Bcfg2 contains explicit support for repositories managed by Pulp (http://pulpproject.org/). Due to the amount of data about a repository that can be retrieved directly from Pulp, the only thing -necessary to configure a Pulp repo is the repo ID:: +necessary to configure a Pulp repo is the repo ID: + +.. code-block:: xml <Sources> <Group name="centos-6-x86_64"> @@ -521,8 +567,8 @@ server must have a valid ``/etc/pulp/consumer/consumer.conf`` that is readable by the user your Bcfg2 server runs as; the Pulp server, URLs, and so on, are determined from this. -Secondly, in ``Packages/packages.conf`` you must set the following -options in the ``[pulp]`` section: +Secondly, in ``bcfg2.conf`` you must set the following +options in the ``[packages:pulp]`` section: * ``username`` and ``password``: The username and password of a Pulp user that will be used to register new clients and bind them to @@ -643,26 +689,27 @@ multiple data sources need to be multiplexed. The APT source in ``src/lib/Server/Plugins/Packages.py`` provides a relatively simple implementation of a source. -packages.conf +Configuration ============= -``packages.conf`` contains miscellaneous configuration options for the +``bcfg2.conf`` contains miscellaneous configuration options for the Packages plugin. Any booleans in the config file accept the values "1", "yes", "true", and "on" for True, and "0", "no", "false", and -"off" for False +"off" for False. It understands the following directives: -[global] section ----------------- +[packages] section +------------------ * ``resolver``: Enable dependency resolution. Default is ``1`` (true). For historical reasons, this also accepts "enabled" and "disabled". -* ``metadata``: Enable metadata processing. Default is ``1`` - (true). For historical reasons, this also accepts "enabled" and - "disabled". -* ``yum_config``: The path at which to generate Yum configs. No +* ``metadata``: Enable metadata processing. Default is ``1`` + (true). If ``metadata`` is disabled, it's implied that ``resolver`` + is also disabled. For historical reasons, this also accepts + "enabled" and "disabled". +* ``yum_config``: The path at which to generate Yum configs. No default. * ``apt_config``: The path at which to generate APT configs. No default. @@ -672,18 +719,21 @@ It understands the following directives: * ``version``: Set the version attribute used when binding Packages. Default is ``auto``. -[yum] section -------------- +[packages:yum] section +---------------------- * ``use_yum_libraries``: Whether or not to use the :ref:`native yum library support <native-yum-libraries>`. Default is ``0`` (false). +* ``helper``: Path to ``bcfg2-yum-helper``. By default, Bcfg2 looks + first in ``$PATH`` and then in ``/usr/sbin/bcfg2-yum-helper`` for + the helper. -All other options in the ``[yum]`` section will be passed along -verbatim to the Yum configuration if you are using the native Yum -library support. +All other options in the ``[packages:yum]`` section will be passed +along verbatim to the Yum configuration if you are using the native +Yum library support. -[pulp] section --------------- +[packages:pulp] section +----------------------- * ``username`` and ``password``: The username and password of a Pulp user that will be used to register new clients and bind them to diff --git a/doc/server/plugins/generators/rules.txt b/doc/server/plugins/generators/rules.txt index c084c5681..f693f6e62 100644 --- a/doc/server/plugins/generators/rules.txt +++ b/doc/server/plugins/generators/rules.txt @@ -46,6 +46,10 @@ 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 --------- @@ -118,7 +122,14 @@ Service Tag +------------+-------------------------------+---------------------------------------------------------+ | Name | Description | Values | +============+===============================+=========================================================+ -| mode | Per Service Mode (New in 1.0) | (manual | default | supervised | interactive_only ) | +| 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 or regular | String or regex | | | expression | | @@ -139,29 +150,33 @@ Service Tag | | (Upstart services only) | | +------------+-------------------------------+---------------------------------------------------------+ -Service mode descriptions -^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. versionadded:: 1.0.0 - -* manual +Service mode specification +^^^^^^^^^^^^^^^^^^^^^^^^^^ - * do not start/stop/restart this service - * service installation is not performed +.. versionadded:: 1.3.0 -* interactive_only +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: - * only attempt to start/stop/restart this service if the client is run interactively - * service installation is performed ++-----------------------------+------------------------------------------+ +| 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"`` | ++-----------------------------+------------------------------------------+ -* default +The default is ``restart="true" install="true"`` - * perform appropriate service operations - -* supervised - - * default and ensure service is running (or stopped) when verification is performed - * deprecates supervised='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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -206,6 +221,12 @@ 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: +----------+---------------------------------------------------+-----------------+ @@ -218,46 +239,58 @@ Attributes common to all Path tags: device ^^^^^^ -+----------+---------------------+-------------------+ -| Name | Description | Values | -+==========+=====================+===================+ -| dev_type | Type of device | (block|char|fifo) | -+----------+---------------------+-------------------+ -| owner | Device owner | String | -+----------+---------------------+-------------------+ -| group | Device group | String | -+----------+---------------------+-------------------+ -| major | Major number (block | integer | -| | or char devices) | | -+----------+---------------------+-------------------+ -| minor | Minor number (block | integer | -| | or char devices) | | -+----------+---------------------+-------------------+ ++-----------+---------------------+-------------------+ +| Name | Description | Values | ++===========+=====================+===================+ +| dev_type | Type of device | (block|char|fifo) | ++-----------+---------------------+-------------------+ +| owner | Device owner | String | ++-----------+---------------------+-------------------+ +| group | Device group | 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 | -+=======+==============================+============+ -| perms | Permissions of the directory | String | -+-------+------------------------------+------------+ -| owner | Owner of the directory | String | -+-------+------------------------------+------------+ -| group | Group Owner of the directory | String | -+-------+------------------------------+------------+ -| prune | prune unspecified entries | true|false | -| | from the Directory | | -+-------+------------------------------+------------+ ++-----------+------------------------------+------------+ +| Name | Description | Values | ++===========+==============================+============+ +| perms | Permissions 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 | -+------+----------------------+--------+ ++-----------+------------------------------+--------+ +| Name | Description | Values | ++===========+==============================+========+ +| to | File to link to | String | ++-----------+------------------------------+--------+ +| perms | Permissions of the directory | String | ++-----------+------------------------------+--------+ +| owner | Owner of the directory | String | ++-----------+------------------------------+--------+ +| group | Group Owner of the directory | String | ++-----------+------------------------------+--------+ +| secontext | SELinux context | String | ++-----------+------------------------------+--------+ nonexistent ^^^^^^^^^^^ @@ -274,15 +307,17 @@ nonexistent permissions ^^^^^^^^^^^ -+-------+--------------------------+--------+ -| Name | Description | Values | -+=======+==========================+========+ -| perms | Permissions of the file. | String | -+-------+--------------------------+--------+ -| owner | Owner of the file. | String | -+-------+--------------------------+--------+ -| group | Group of the file. | String | -+-------+--------------------------+--------+ ++-----------+--------------------------+--------+ +| Name | Description | Values | ++===========+==========================+========+ +| perms | Permissions of the file. | String | ++-----------+--------------------------+--------+ +| owner | Owner of the file. | String | ++-----------+--------------------------+--------+ +| group | Group of the file. | String | ++-----------+--------------------------+--------+ +| secontext | SELinux context | String | ++-----------+--------------------------+--------+ symlink ^^^^^^^ @@ -293,6 +328,141 @@ symlink | to | File to link to | String | +------+----------------------+--------+ +SELinux Tag +----------- + +The SELinux tag has different values depending on the *type* attribute +of the SELinux entry specified in your configuration. Below is a set +of tables which describe the attributes available for various SELinux +types. The 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. + +In certain cases, it may be necessary to create multiple SELinux +entries with the same name. For instance, "root" is both an SELinux +user and an SELinux login record; or a given fcontext may need two +different SELinux types depending on whether it's a symlink or a plain +file. In these (few) cases, it is necessary to create BoundSELinux +entries directly in Bundler rather than using abstract SELinux entries +in Bundler and binding them with Rules. + +See :ref:`server-selinux` for more information. + +boolean +^^^^^^^ + ++-------+----------------------+---------+----------+ +| Name | Description | Values | Required | ++=======+======================+=========+==========+ +| name | Name of the boolean | String | Yes | ++-------+----------------------+---------+----------+ +| value | Value of the boolean | on|off | Yes | ++-------+----------------------+---------+----------+ + +port +^^^^ + ++-------------+------------------------+---------------------------+----------+ +| 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 | | | ++-------------+------------------------+---------------------------+----------+ + +fcontext +^^^^^^^^ + ++-------------+-------------------------+---------------------+----------+ +| 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) | | ++-------------+-------------------------+---------------------+----------+ + +node +^^^^ + ++-------------+------------------------------------+------------------+----------+ +| 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 | ++-------------+------------------------------------+------------------+----------+ +| netmask | Netmask | String | Yes | ++-------------+------------------------------------+------------------+----------+ + +login +^^^^^ + ++-------------+-------------------------------+-----------+----------+ +| Name | Description | Values | Required | ++=============+===============================+===========+==========+ +| name | Unix username | String | Yes | ++-------------+-------------------------------+-----------+----------+ +| selinuxuser | SELinux username | String | Yes | ++-------------+-------------------------------+-----------+----------+ + +user +^^^^ + ++-------------+-------------------------------+-----------+----------+ +| Name | Description | Values | Required | ++=============+===============================+===========+==========+ +| name | SELinux username | String | Yes | ++-------------+-------------------------------+-----------+----------+ +| roles | Space-separated list of roles | String | No | ++-------------+-------------------------------+-----------+----------+ +| prefix | Home directory context prefix | String | No | ++-------------+-------------------------------+-----------+----------+ + +interface +^^^^^^^^^ + ++-------------+-------------------------+-------------+----------+ +| Name | Description | Values | Required | ++=============+=========================+=============+==========+ +| name | Interface name | String | Yes | ++-------------+-------------------------+-------------+----------+ +| selinuxtype | SELinux type to apply | String | Yes | +| | to this interface | | | ++-------------+-------------------------+-------------+----------+ + +permissive +^^^^^^^^^^ + ++-------------+------------------------------------+-------------+----------+ +| Name | Description | Values | Required | ++=============+====================================+=============+==========+ +| name | SELinux type to make permissive | String | Yes | ++-------------+------------------------------------+-------------+----------+ + +module +^^^^^^ + +See :ref:`server-plugins-generators-semodules` + Rules Directory =============== @@ -356,14 +526,11 @@ 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, create a file, "Rules/rules.conf", and add the -following text:: +penalty. To do so, add the following setting to ``bcfg2.conf``:: [rules] regex = yes -You will have to restart the Bcfg2 server after making that change. - With regular expressions enabled, you can use a regex in the ``name`` attribute to match multiple abstract configuration entries. @@ -372,4 +539,4 @@ 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 regexs to match the same rule. +specify multiple regexes to match the same rule. diff --git a/doc/server/plugins/generators/semodules.txt b/doc/server/plugins/generators/semodules.txt new file mode 100644 index 000000000..0d725fc1a --- /dev/null +++ b/doc/server/plugins/generators/semodules.txt @@ -0,0 +1,66 @@ +.. -*- mode: rst -*- + +.. _server-plugins-generators-semodules: + +========= +SEModules +========= + +.. versionadded:: 1.3.0 + +The SEModules plugin handles SELinux module entries. It supports +group- and host-specific module versions, and enabling/disabling +modules. + +You can use ``selinux_baseline.py`` located in the tools/ directory to +create a baseline of all of your installed modules. + +See :ref:`server-selinux` for more information. + +Usage +===== + +To use the SEModules plugin, first do ``mkdir +/var/lib/bcfg2/SEModules``. Add ``SEModules`` to your ``plugins`` +line in ``/etc/bcfg2.conf`` and restart bcfg2-server. + +The SEModules directory contains modules in a layout similar to the +Cfg plugin: at the top level, SEModules should contain directories +named after the modules you want to install, and each of those +directories can contain a global module, plus any number of group- and +host-specific modules. For instance: + + $ ls -F SEModules + foo.pp/ bar.pp/ + $ ls SEModules/foo.pp/ + foo.pp + foo.pp.G50_server + foo.pp.H_baz.example.com + +For more information on this directory layout, see +:ref:`server-plugins-generators-cfg`. + +Entries +======= + +SEModules handles ``<SELinux>`` entries with the ``module`` type. For +instance: + +.. code-block:: xml + + <Bundle name="foo"> + <SELinux type="module" name="foo.pp"/> + </Bundle> + +The ``.pp`` extension is optional. + +.. note:: + + If you use a ``BoundSELinux`` tag, you must *not* include the + ``.pp`` extension. This is not recommend, though. + +You can also install a disabled module: + +.. code-block:: xml + + <SELinux type="module" name="foo" disabled="true"/> diff --git a/doc/server/plugins/generators/sslca.txt b/doc/server/plugins/generators/sslca.txt index 8e33148cb..d2b051535 100644 --- a/doc/server/plugins/generators/sslca.txt +++ b/doc/server/plugins/generators/sslca.txt @@ -33,7 +33,7 @@ must contain full (not relative) paths. #. Add SSLCA to the **plugins** line in ``/etc/bcfg2.conf`` and restart the server -- This enabled the SSLCA plugin on the Bcfg2 server. -#. Add a section to your ``/etc/bcfg2.conf`` called sslca_foo, replacing foo +#. Add a section to your ``/etc/bcfg2.conf`` called ``sslca_foo``, replacing foo with the name you wish to give your CA so you can reference it in certificate definitions. @@ -51,6 +51,12 @@ must contain full (not relative) paths. specification. If you're using a self signing CA this would be the CA cert that you generated. +#. Optionally, add ``verify_certs = false`` if you don't wish to + perform certificate verification on the certs SSLCA generates. + Verification includes ``openssl verify`` to verify the CA chain, + and ensuring that both the key file and certificate file contain + the same key. + #. Once all this is done, you should have a section in your ``/etc/bcfg2.conf`` that looks similar to the following:: diff --git a/doc/server/plugins/generators/tgenshi/index.txt b/doc/server/plugins/generators/tgenshi/index.txt index 21ef8f17f..0d4a7ffb0 100644 --- a/doc/server/plugins/generators/tgenshi/index.txt +++ b/doc/server/plugins/generators/tgenshi/index.txt @@ -17,7 +17,7 @@ on the client in the created files. To begin, you will need to download and install the Genshi templating engine. -To install on CentOS or RHEL 5, run:: +To install on CentOS or RHEL, run:: sudo yum install python-genshi diff --git a/doc/server/plugins/grouping/metadata.txt b/doc/server/plugins/grouping/metadata.txt index 305857578..2c05e9e7e 100644 --- a/doc/server/plugins/grouping/metadata.txt +++ b/doc/server/plugins/grouping/metadata.txt @@ -37,11 +37,11 @@ describe one host. A sample file is below: .. code-block:: xml <Clients version="3.0"> - <Client profile="backup-server" pingable="Y" pingtime="0" name="backup.example.com"/> - <Client profile="console-server" pingable="Y" pingtime="0" name="con.example.com"/> - <Client profile="kerberos-master" pingable="Y" pingtime="0" name="kdc.example.com"/> - <Client profile="mail-server" pingable="Y" pingtime="0" name="mail.example.com"/> - <Client name='foo' address='10.0.0.1' pingable='N' pingtime='-1'> + <Client profile="backup-server" name="backup.example.com"/> + <Client profile="console-server" name="con.example.com"/> + <Client profile="kerberos-master" name="kdc.example.com"/> + <Client profile="mail-server" name="mail.example.com"/> + <Client name='foo' address='10.0.0.1'> <Alias name='foo-mgmt' address='10.1.0.1'/> </Client> </Clients> @@ -93,12 +93,6 @@ Additionally, the following properties can be specified: | | can be used instead of the global | | | | password. | | +----------+----------------------------------------+----------------+ -| pingable | If the client is pingable (deprecated; | Y|N | -| | for old reporting system) | | -+----------+----------------------------------------+----------------+ -| pingtime | Last time the client was pingable | String | -| | (deprecated; for old reporting system) | | -+----------+----------------------------------------+----------------+ | secure | Requires the use of the per-client | true|false | | | password for this client. | | +----------+----------------------------------------+----------------+ diff --git a/doc/server/plugins/misc/trigger.txt b/doc/server/plugins/misc/trigger.txt index 7547f2fdd..224b7444b 100644 --- a/doc/server/plugins/misc/trigger.txt +++ b/doc/server/plugins/misc/trigger.txt @@ -6,8 +6,8 @@ Trigger ======= -Trigger is a plugin that calls external scripts (on the server) when -clients are configured. +Trigger is a plugin that calls external scripts (on the server) at the +end of each client run. Setup ===== diff --git a/doc/server/plugins/plugin-roles.txt b/doc/server/plugins/plugin-roles.txt index 2ce7e21ff..58dc36296 100644 --- a/doc/server/plugins/plugin-roles.txt +++ b/doc/server/plugins/plugin-roles.txt @@ -6,124 +6,41 @@ Plugin Roles ============ -This documents available plugin roles. - -1. list of plugin roles - - +---------------+--------------------+--------+ - | Role | Class | Status | - +===============+====================+========+ - | Metadata | Metadata | done | - +---------------+--------------------+--------+ - | Connector | Connector | done | - +---------------+--------------------+--------+ - | Probing | Probing | done | - +---------------+--------------------+--------+ - | Structure | Structure | done | - +---------------+--------------------+--------+ - | Structure Val | StructureValidator | done | - +---------------+--------------------+--------+ - | Generator | Generator | done | - +---------------+--------------------+--------+ - | Goals Val | GoalValidator | done | - +---------------+--------------------+--------+ - | Statistics | Statistics | done | - +---------------+--------------------+--------+ - | Pull Source | PullSource | done | - +---------------+--------------------+--------+ - | Pull Target | PullTarget | done | - +---------------+--------------------+--------+ - | Version | Version | done | - +---------------+--------------------+--------+ - | Decision | Decision | done | - +---------------+--------------------+--------+ - | Remote | Remote | none | - +---------------+--------------------+--------+ - | Syncing | Syncing | none | - +---------------+--------------------+--------+ - -2. Plugin Capabilities - - * Metadata - - * Initial metadata construction - * Connector data accumulation - * ClientMetadata instance delivery - * Introspection interface (for bcfg2-info & co) - - * Connector - - * Provide additional data for ClientMetadata instances - - * Probing - - * send executable probes to clients and receive data responses - - * Structure - - * Produce a list of configuration entries that should be included in client configurations - * Each structure plugin is produces a list of structures - * Core verifies that each bundle listed has been constructed - - * Structure Validation - - * Validate a client entry list's internal consistency, modifying if needed - - * Generator - * Goals Validation - - * Validate client goals, modifying if needed - - * Pull Source - - * Plugin can provide entry information about clients - - * Pull Target - - * Plugin can accept entry data and merge it into the specification - - * Version - - * Plugin can read revision information from VCS of choice - * Will provide an interface for producing commits made by the bcfg2-server - - * Decision - -3. Configuration of plugins - - Plugin configuration will be simplified substantially. Now, a single - list of plugins (including plugins of all capabilities) is specified - upon startup (either via bcfg2.conf or equivalent). This mechanism - replaces the current split configuration mechanism where generators, - structures, and other plugins are listed independently. Instead, all - plugins included in the startup list will be initialized, and each - will be enabled in all roles that it supports. This will remove a - current source of confusion and potential configuration errors, - wherein a plugin is enabled for an improper set of goals. (ie Cfg - enabled as a structure, etc) This does remove the possibility of - partially enabling a plugin for one of its roles without activating it - across the board, but I think this is a corner case, which will be - poorly supported by plugin implementers. If needed, this use case can - be explicitly supported by the plugin author, through use of a config - file directive. - -4. User Visible Changes - - Connector data is added to ClientMetadata instances using the name of - the connector plugin. This means that the dictionary of key/val probe - pairs included with metadata is now available as metadata.Probes - (instead of metadata.probes). Once properties are available the same - way, they will likewise change names to metadata.Properties from their - current name. - - Plugin configuration will change. A single field "plugins" in - bcfg2.conf will supercede the combination of the "generators" and - "structures" fields. - - Default loading of needed plugins is now explicit; this means that - Statistics (if used) should be listed in the plugins line of - bcfg2.conf. - -5. Notes - - * Need to ensure bundle accumulation occurs with connector groups +* Metadata + * Initial metadata construction + * Connector data accumulation + * ClientMetadata instance delivery + * Introspection interface (for bcfg2-info & co) +* Connector + * Provide additional data for ClientMetadata instances +* Probing + * send executable probes to clients and receive data responses +* Structure + * Produce a list of configuration entries that should be included in + client configurations + * Each structure plugin is produces a list of structures + * Core verifies that each bundle listed has been constructed +* StructureValidator + * Validate a client entry list's internal consistency, modifying if + needed +* Generator +* GoalValidator + * Validate client goals, modifying if needed +* PullSource + * Plugin can provide entry information about clients +* PullTarget + * Plugin can accept entry data and merge it into the specification +* Version + * Plugin can read revision information from VCS of choice + * Will provide an interface for producing commits made by the bcfg2-server +* Decision +* ClientRunHooks + * Provides hooks executed at the start and end of each client run + +Configuration of plugins +======================== + +A single list of plugins (including plugins of all capabilities) is +specified upon startup (either via bcfg2.conf or equivalent). All +plugins included in the startup list are initialized, and each is +enabled in all roles that it supports. diff --git a/doc/server/plugins/probes/index.txt b/doc/server/plugins/probes/index.txt index 95aa2d0ce..cacc42bc1 100644 --- a/doc/server/plugins/probes/index.txt +++ b/doc/server/plugins/probes/index.txt @@ -211,7 +211,7 @@ look something like: <FileProbe name="/etc/blah.conf" update="true"/> </Group> <Client name="bar.example.com"> - <FileProbe name="/var/lib/bar.gz" base64="true"/> + <FileProbe name="/var/lib/bar.gz" encoding="base64"/> </Client> </FileProbes> diff --git a/doc/server/selinux.txt b/doc/server/selinux.txt new file mode 100644 index 000000000..0cbf0985e --- /dev/null +++ b/doc/server/selinux.txt @@ -0,0 +1,97 @@ +.. -*- mode: rst -*- + +.. _server-selinux: + +======= +SELinux +======= + +.. 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. It +does this rather than separate Bundle/Rules files because of the +:ref:`server-selinux-duplicate-entries` problem. + +.. _server-selinux-duplicate-entries: + +Duplicate Entries +================= + +In certain cases, it may be necessary to create multiple SELinux +entries with the same name. For instance, "root" is both an SELinux +user and an SELinux login record, so to manage both, you would have +the following in Bundler: + +.. code-block:: xml + + <SELinux name="root"/> + <SELinux name="root"/> + +And in Rules: + +.. code-block:: xml + + <SELinux type="login" selinuxuser="root" name="root"/> + <SELinux type="user" prefix="user" name="root" + roles="system_r sysadm_r user_r"/> + +But Rules has no way to tell which "root" is which, and you will get +errors. In these cases, it is necessary to use ``BoundSELinux`` tags +directly in Bundler. (See :ref:`boundentries` for more details on +bound entries.) For instance: + +.. code-block:: xml + + <BoundSELinux type="login" selinuxuser="root" name="root"/> + <BoundSELinux type="user" prefix="user" name="root" + roles="system_r sysadm_r user_r"/> + +It may also 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"/> |