diff options
Diffstat (limited to 'doc/server')
| -rw-r--r-- | doc/server/configurationentries.txt | 30 | ||||
| -rw-r--r-- | doc/server/plugins/connectors/properties.txt | 30 | ||||
| -rw-r--r-- | doc/server/plugins/generators/cfg.txt | 6 | ||||
| -rw-r--r-- | doc/server/plugins/generators/decisions.txt | 38 | ||||
| -rw-r--r-- | doc/server/plugins/generators/nagiosgen.txt | 34 | ||||
| -rw-r--r-- | doc/server/plugins/generators/packages.txt | 19 | ||||
| -rw-r--r-- | doc/server/plugins/generators/rules.txt | 71 | ||||
| -rw-r--r-- | doc/server/plugins/generators/sslca.txt | 52 | ||||
| -rw-r--r-- | doc/server/plugins/generators/tcheetah.txt | 16 | ||||
| -rw-r--r-- | doc/server/plugins/generators/tgenshi/index.txt | 68 | ||||
| -rw-r--r-- | doc/server/plugins/grouping/metadata.txt | 6 | ||||
| -rw-r--r-- | doc/server/plugins/probes/index.txt | 57 | ||||
| -rw-r--r-- | doc/server/plugins/structures/base.txt | 7 | ||||
| -rw-r--r-- | doc/server/plugins/structures/bundler/index.txt | 63 |
14 files changed, 385 insertions, 112 deletions
diff --git a/doc/server/configurationentries.txt b/doc/server/configurationentries.txt index 6e6ab79f7..10eccf6be 100644 --- a/doc/server/configurationentries.txt +++ b/doc/server/configurationentries.txt @@ -31,9 +31,25 @@ Non-POSIX entries +-------------+---------------------+-----------------------------+ | PostInstall | PostInstall command | name | +-------------+---------------------+-----------------------------+ -| Service | System Services | name, type, status, reload | +| 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 ============= @@ -48,11 +64,11 @@ 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`_. +the *type* and any other necessary attributes in `Rules`_. -Running ``bcfg2-repo-validate`` will check your configuration -specification for the presence of any mandatory attributes that are -necessary for the Path type specified. +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 @@ -95,6 +111,10 @@ necessary for the Path type specified. | | entries | POSIX entities | group, perms | | | | | | +-------------+----------------------+-----------------+--------------------------+ +| vcs | New | Create version | vcstype (git), | +| | | control | sourceurl, revision | +| | | checkout | | ++-------------+----------------------+-----------------+--------------------------+ Keep in mind that permissions for files served up by Cfg/TGenshi/TCheetah are still handled via the traditional :ref:`server-info` mechanisms. diff --git a/doc/server/plugins/connectors/properties.txt b/doc/server/plugins/connectors/properties.txt index ae8bf0caa..1cbc4cf65 100644 --- a/doc/server/plugins/connectors/properties.txt +++ b/doc/server/plugins/connectors/properties.txt @@ -1,6 +1,6 @@ .. -*- mode: rst -*- -.. _server-plugins-properties: +.. _server-plugins-connectors-properties: ========== Properties @@ -24,17 +24,37 @@ Properties adds a new dictionary to client metadata instances that maps property file names to PropertyFile instances. PropertyFile instances contain parsed XML data as the "data" attribute. +The XML data in a property file is arbitrary, but a matching ``.xsd`` +file can be created to assign a schema to a property file, which will +be checked when running ``bcfg2-lint``. For instance, given:: + + Properties/dns-config.xml + Properties/dns-config.xsd + +``dns-config.xml`` will be validated against ``dns-config.xsd``. + Usage ===== Specific property files can be referred to in -templates as metadata.Properties[<filename>]. The +templates as ``metadata.Properties[<filename>]``. The data attribute is an LXML element object. (Documented `here <http://codespeak.net/lxml/tutorial.html#the-element-class>`_) -Currently, no access methods are defined for this data, but as we -formulate common use cases, we will add them to the !PropertyFile class -as methods. This will simplify templates. +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:: + + {% python + ntp_servers = [el.text + for el in metadata.Properties['ntp.xml'].Match(metadata): + if el.tag == "Server"] + %} + +As we formulate more common use cases, we will add them to the +!PropertyFile class as methods. This will simplify templates. Accessing Properties contents from TGenshi ========================================== diff --git a/doc/server/plugins/generators/cfg.txt b/doc/server/plugins/generators/cfg.txt index 612b14bec..1039ff556 100644 --- a/doc/server/plugins/generators/cfg.txt +++ b/doc/server/plugins/generators/cfg.txt @@ -132,16 +132,16 @@ server and we have the following configuration files:: motd.G01_web-server motd.G01_mail-server.cat motd.G02_file-server.cat - motd.H_foo.example.cat + motd.H_foo.example.com.cat -If our machine isn't *foo.example.com* then here's what would happen: +If our machine **isn't** *foo.example.com* then here's what would happen: Bcfg2 would choose ``motd.G01_web-server`` as the base file. It is the most specific base file for this host. Bcfg2 would apply the ``motd.G01_mail-server.cat`` delta to the ``motd.G01_web-server`` base file. It is the least specific delta. Bcfg2 would then apply the ``motd.G02_file-server.cat`` delta to the result of the delta before -it. If our machine is foo.example.com then here's what would happen: +it. If our machine **is** *foo.example.com* then here's what would happen: Bcfg2 would choose ``motd.G01_web-server`` as the base file. It is the most specific base file for this host. Bcfg2 would apply the diff --git a/doc/server/plugins/generators/decisions.txt b/doc/server/plugins/generators/decisions.txt index ba01f7fc2..d75a9fede 100644 --- a/doc/server/plugins/generators/decisions.txt +++ b/doc/server/plugins/generators/decisions.txt @@ -22,6 +22,12 @@ should be corrected during the current run of the installation tool. The Decisions plugin is the only stock plugin that generates entries for client's whitelists or blacklists. +.. note:: + + If the client is not explicitly configured to run in whitelist or + blacklist mode, the list of entries is not downloaded and decisions + is not used. See `Decision Mode`_ below. + The Decisions plugin uses a directory in the Bcfg2 repository called Decisions. Files in the Decisions subdirectory are named similarly to files managed by Cfg, probes, TCheetah, and TGenshi (so you can use host- @@ -37,12 +43,6 @@ the following is an example. <Decision type='Path' name='/etc/apt/apt.conf'/> </Decisions> -.. note:: To add syntax highlighting in vim, you can add a modeline such as this: - - <!-- - vim: ft=xml - --> - This example, included as a whitelist due to its name, enables all services, and the path entry named ``/etc/apt/apt.conf``. All these entries must already be present in your repository, the Decisions plugin just references @@ -55,11 +55,27 @@ When a client asks for its whitelist or blacklist, all of the files pertaining to that client of the correct type are aggregated into a single list. This list is sent to the client. -.. note:: This list is only generated when a client is explicitly run with - the appropriate option (``-l (whitelist|blacklist)``); client - behavior is not controlled unless this option is used. If you do - not use Decisions, all your entries will be installed normally. -.. note:: Also, using this plugin does not present additional prompts or +.. note:: Using this plugin does not present additional prompts or safety nets to the administrator running the client, you have to control these via their respective options (``-I`` or ``-n``, for example). + +To add syntax highlighting to Decisions files in vim and emacs, you +can add comments such as this:: + + <Decisions><!--*- mode: xml; -*--> + <!-- vim: set ft=xml : --> + + +============= +Decision Mode +============= + +The whitelist or blacklist is only generated when a client is run in +whitelist or blacklist mode. This can either be set at the command +line with the appropriate option (``-l (whitelist|blacklist)``), or in +``bcfg2.conf`` by setting ``decision`` in the ``client`` section to +``whitelist`` or ``blacklist``). + +Client behavior is not controlled unless the decision mode is set. If +you do not use Decisions, all your entries will be installed normally. diff --git a/doc/server/plugins/generators/nagiosgen.txt b/doc/server/plugins/generators/nagiosgen.txt index 196f1e76b..b839c10ca 100644 --- a/doc/server/plugins/generators/nagiosgen.txt +++ b/doc/server/plugins/generators/nagiosgen.txt @@ -169,3 +169,37 @@ Note that some of these files are built on demand, each time a client in group "nagios-server" checks in with the Bcfg2 server. Local nagios instances can be configured to use the NagiosGen directory in the Bcfg2 repository directly. + +Fine-Grained Configuration +========================== + +NagiosGen can be configured in excruciating detail by editing +``NagiosGen/config.xml``, which will let you set individual Nagios +options for hosts or groups. E.g.: + +.. code-block:: xml + + <NagiosGen> + <Group name="datacenter-2"> + <Option name="parents">dc-2-switch</Option> + <Group> + <Group name="non-production"> + <Option name="notification_period">workhours</Option> + <Option name="notification_options">d</Option> + </Group> + <Client name="foo.example.com"> + <Option name="max_check_attempts">10</Option> + </Client> + </NagiosGen> + +Obviously the sort of fine-grained control you get from this overlaps +to some degree with Nagios' own templating, so use it wisely and in +moderation. + +``NagiosGen/config.xml`` replaces the files +``Properties/NagiosGen.xml`` and ``NagiosGen/parents.xml`` in older +versions of Bcfg2; your old configs can be migrated using the +``nagiosgen-convert.py`` tool. The plugin does contain a +backwards-compatibility layer for those older config files, but +``NagiosGen/config.xml`` must exist (even if empty) for the plugin to +function. diff --git a/doc/server/plugins/generators/packages.txt b/doc/server/plugins/generators/packages.txt index d1a68b16e..90cd19de4 100644 --- a/doc/server/plugins/generators/packages.txt +++ b/doc/server/plugins/generators/packages.txt @@ -15,6 +15,8 @@ information, Packages delegates control of package version information to the underlying package manager, installing the latest version available through those channels. +.. _server-plugins-generators-packages-magic-groups: + "Magic Groups" ============== @@ -152,14 +154,15 @@ like this: </Sources> .. note:: + The default behavior of the Packages plugin is to not make any assumptions about which packages you want to have added - automatically. For that reason, neither **Recommended** - nor **Suggested** packages are added as dependencies by - default. You will notice that the default behavior for apt is - to add Recommended packages as dependencies. You can configure - the Packages plugin to add recommended packages by adding - the following line immediately following the URL: + automatically. For that reason, neither **Recommended** nor + **Suggested** packages are added as dependencies by default. You + will notice that the default behavior for apt is to add Recommended + packages as dependencies. You can configure the Packages plugin to + add recommended packages by adding the following line immediately + following the **URL**: .. versionadded:: 1.1.0 @@ -184,6 +187,8 @@ Yum sources can be similarly specified: </YUMSource> </Sources> +For sources with a **URL** tag, the **Version** tag is also necessary. + .. note:: There is also a RawURL syntax for specifying APT or YUM sources that don't follow the conventional layout: @@ -268,7 +273,7 @@ Validation ========== A schema for Packages/config.xml is included; config.xml can be validated -using ``bcfg2-repo-validate``. +using ``bcfg2-lint``. .. note:: The schema requires that elements be specified in the above order. diff --git a/doc/server/plugins/generators/rules.txt b/doc/server/plugins/generators/rules.txt index cff78a8ee..a2953ad08 100644 --- a/doc/server/plugins/generators/rules.txt +++ b/doc/server/plugins/generators/rules.txt @@ -116,34 +116,28 @@ See :ref:`client-tools-actions` Service Tag ----------- -+------------+--------------------------+---------------------------------------+ -| Name | Description | Values | -+============+==========================+=======================================+ -| mode | Per Service Mode (New in | (manual|default|supervised) | -| | 1.0) | | -+------------+--------------------------+---------------------------------------+ -| name | Service Name | String | -+------------+--------------------------+---------------------------------------+ -| status | Should the service be | (on|off) | -| | on or off (default: | | -| | off). | | -+------------+--------------------------+---------------------------------------+ -| target | Service command for | String | -| | restart (default: | | -| | restart) | | -+------------+--------------------------+---------------------------------------+ -| type | Driver to use on the | (chkconfig|deb|rc-update|smf|upstart) | -| | client to manage this | | -| | service. | | -+------------+--------------------------+---------------------------------------+ -| sequence | Order for service | integer | -| | startup (debian services | | -| | only) | | -+------------+--------------------------+---------------------------------------+ -| parameters | Pass parameters to | String | -| | service (Upstart | | -| | services only) | | -+------------+--------------------------+---------------------------------------+ ++------------+-------------------------------+-----------------------------------------------+ +| Name | Description | Values | ++============+===============================+===============================================+ +| mode | Per Service Mode (New in 1.0) | (manual | default | supervised) | ++------------+-------------------------------+-----------------------------------------------+ +| name | Service Name | String | ++------------+-------------------------------+-----------------------------------------------+ +| status | Should the service be on or | (on | off | ignore) | +| | off (default: off). | | ++------------+-------------------------------+-----------------------------------------------+ +| target | Service command for restart | String | +| | (default: restart) | | ++------------+-------------------------------+-----------------------------------------------+ +| type | Driver to use on the client | (chkconfig | deb | rc-update | smf | upstart) | +| | to manage this service. | | ++------------+-------------------------------+-----------------------------------------------+ +| sequence | Order for service startup | integer | +| | (debian services only) | | ++------------+-------------------------------+-----------------------------------------------+ +| parameters | Pass parameters to service | String | +| | (Upstart services only) | | ++------------+-------------------------------+-----------------------------------------------+ Service mode descriptions ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -153,6 +147,12 @@ Service mode descriptions * manual * do not start/stop/restart this service + * service installation is not performed + +* interactive_only + + * only attempt to start/stop/restart this service if the client is run interactively + * service installation is performed * default @@ -163,6 +163,21 @@ Service mode descriptions * default and ensure service is running (or stopped) when verification is performed * deprecates supervised='true' +Service status descriptions +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* on + + * start the service at boot time + +* off + + * don't start the service at boot time + +* ignore + + * don't check the status, leave it as-is (valid for deb and upstart services only) + Client Tag ---------- diff --git a/doc/server/plugins/generators/sslca.txt b/doc/server/plugins/generators/sslca.txt index ebc625e11..c91905d78 100644 --- a/doc/server/plugins/generators/sslca.txt +++ b/doc/server/plugins/generators/sslca.txt @@ -34,39 +34,39 @@ must contain full (not relative) paths. server -- This enabled the SSLCA plugin on the Bcfg2 server. #. 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. + with the name you wish to give your CA so you can reference it in certificate + definitions. #. Under that section, add an entry for ``config`` that gives the location of -the openssl configuration file for your CA. + the openssl configuration file for your CA. #. If necessary, add an entry for ``passphrase`` containing the passphrase for -the CA's private key. We store this in ``/etc/bcfg2.conf`` as the permissions -on that file should have it only readable by the bcfg2 user. If no passphrase -is entry exists, it is assumed that the private key is stored unencrypted. + the CA's private key. We store this in ``/etc/bcfg2.conf`` as the permissions + on that file should have it only readable by the bcfg2 user. If no passphrase + is entry exists, it is assumed that the private key is stored unencrypted. #. Add an entry ``chaincert`` that points to the location of your ssl chaining -certificate. This is used when preexisting certifcate hostfiles are found, so -that they can be validated and only regenerated if they no longer meet the -specification. + certificate. This is used when preexisting certifcate hostfiles are found, so + that they can be validated and only regenerated if they no longer meet the + specification. #. Once all this is done, you should have a section in your ``/etc/bcfg2.conf`` -that looks similar to the following: + that looks similar to the following:: - [sslca_default] - config = /etc/pki/CA/openssl.cnf - passphrase = youReallyThinkIdShareThis? - chaincert = /etc/pki/CA/chaincert.crt + [sslca_default] + config = /etc/pki/CA/openssl.cnf + passphrase = youReallyThinkIdShareThis? + chaincert = /etc/pki/CA/chaincert.crt #. You are now ready to create key and certificate definitions. For this -example we'll assume you've added Path entries for the key, -``/etc/pki/tls/private/localhost.key``, and the certificate, -``/etc/pki/tls/certs/localhost.crt`` to a bundle or base. + example we'll assume you've added Path entries for the key, + ``/etc/pki/tls/private/localhost.key``, and the certificate, + ``/etc/pki/tls/certs/localhost.crt`` to a bundle or base. #. Defining a key or certificate is similar to defining a TGenshi template. -Under your Bcfg2's SSLCA directory, create the directory structure to match the -path to your key. In this case this would be something like -``/var/lib/bcfg2/SSLCA/etc/pki/tls/private/localhost.key``. + Under your Bcfg2's SSLCA directory, create the directory structure to match the + path to your key. In this case this would be something like + ``/var/lib/bcfg2/SSLCA/etc/pki/tls/private/localhost.key``. #. Within that directory, create a ``key.xml`` file containing the following: @@ -77,11 +77,11 @@ path to your key. In this case this would be something like </KeyInfo> #. This will cause the generation of an 2048 bit RSA key when a client requests -that Path. Alternatively you can specify ``dsa`` as the keytype, or a different -number of bits. + that Path. Alternatively you can specify ``dsa`` as the keytype, or a different + number of bits. #. Similarly, create the matching directory structure for the certificate path, -and a ``cert.xml`` containinng the following: + and a ``cert.xml`` containinng the following: .. code-block:: xml @@ -90,9 +90,9 @@ and a ``cert.xml`` containinng the following: </CertInfo> #. When a client requests the cert path, a certificate will be generated using -the key hostfile at the specified key location, using the CA matching the ca -attribute. ie. ca="default" will match [sslca_default] in your -``/etc/bcfg2.conf`` + the key hostfile at the specified key location, using the CA matching the ca + attribute. ie. ca="default" will match [sslca_default] in your + ``/etc/bcfg2.conf`` TODO ==== diff --git a/doc/server/plugins/generators/tcheetah.txt b/doc/server/plugins/generators/tcheetah.txt index f2ca6c87c..ef8bb5513 100644 --- a/doc/server/plugins/generators/tcheetah.txt +++ b/doc/server/plugins/generators/tcheetah.txt @@ -50,6 +50,12 @@ self.metadata is an instance of the class ClientMetadata and documented self.metadata.Properties.data ============================= +.. note:: + + If you want to use Properties, you will need to enable the + :ref:`server-plugins-connectors-properties` plugin in + ``/etc/bcfg2.conf``. + Properties.data is a python `ElementTree <http://codespeak.net/lxml/>`_ object, loaded from the data in ``/var/lib/bcfg2/Properties/<properties file>.xml``. That file should have a ``Properties`` node at its root. @@ -78,6 +84,12 @@ on the host 'www.example.com':: ${self.metadata.Properties['example.xml'].data.xpath($path)[0].text} ${self.metadata.Properties['example.xml'].data.xpath(path)[0].text} +Other Variables +=============== + +* **Template.searchList(self)[1]['path']** is the Path name specified in a Bundle +* **Template.searchList(self)[1]['source_path']** is the path to the TCheetah template on the Bcfg2 server + Simple Example ============== @@ -92,6 +104,8 @@ directory. Below is a simple example a file ``/foo``. > buildfile /foo <clientname> Hostname is $self.metadata.hostname + Filename is $Template.searchList(self)[1]['path'] + Template is $Template.searchList(self)[1]['source_path'] Groups: #for $group in $self.metadata.groups: * $group @@ -124,6 +138,8 @@ current client probe state. <Path type="file" name="/foo" owner="root" perms="0624" group="root"> Hostname is topaz.mcs.anl.gov + Filename is /foo + Template is /var/lib/bcfg2/TCheetah/foo/template Groups: * desktop * mcs-base diff --git a/doc/server/plugins/generators/tgenshi/index.txt b/doc/server/plugins/generators/tgenshi/index.txt index c1970ee0d..d7e0b3bf2 100644 --- a/doc/server/plugins/generators/tgenshi/index.txt +++ b/doc/server/plugins/generators/tgenshi/index.txt @@ -48,10 +48,16 @@ supported. Inside of templates =================== -* **metadata** is the client's :ref:`metadata <server-plugins-grouping-metadata-clientmetadata>` -* **properties.properties** is an xml document of unstructured data +* **metadata** is the client's :ref:`metadata + <server-plugins-grouping-metadata-clientmetadata>` +* **metadata.Properties** is an xml document of unstructured data (only + available when used in conjunction with the + :ref:`server-plugins-connectors-properties` plugin) * **name** is the path name specified in bcfg -* **path** is the path to the TGenshi template +* **path** is the path to the TGenshi template. It starts with a + leading slash, and is relative to the Bcfg2 specification root. + E.g., ``/Cfg/etc/foo.conf/foo.conf.genshi`` or + ``/TGenshi/etc/foo.conf/template.newtxt.H_foo.example.com`` See the genshi `documentation <http://genshi.edgewall.org/wiki/Documentation>`_ for examples of @@ -88,6 +94,56 @@ Produces: This flexibility provides the ability to build much more compact and succinct definitions of configuration contents than Cfg can. +Troubleshooting +=============== + +When developing a template, you can see what the template would +generate on a client with :ref:`bcfg2-info <server-bcfg2-info>`:: + + bcfg2-info buildfile <path> <hostname> + +E.g.:: + + bcfg2-info buildfile /etc/foo.conf foo.example.com + +Sometimes, it's useful to be able to do more in-depth troubleshooting +by running the template manually. (This is also necessary if you want +to generate a template that depends on an :ref:`altsrc +<server-plugins-structures-altsrc>` tag.) To do this, run ``bcfg2-info +debug``, and, once in the Python interpreter, run:: + + metadata = self.build_metadata("<hostname>") + path = "<relative path to template (see note below)>" + bcfg2root = "<path to bcfg2 specification root>" + +``path`` should be set to the path to the template file with a leading +slash, relative to the Bcfg2 specification root. See `Inside of +Templates`_ for examples. + +``bcfg2root`` should be set to the absolute path to the Bcfg2 +specification. (This is ``/var/lib/bcfg2`` by default.) + +Then, run:: + + import os + name = os.path.dirname(path[path.find('/', 1):]) + from genshi.template import TemplateLoader, NewTextTemplate + template = TemplateLoader().load(bcfg2root + path, cls=NewTextTemplate) + print template.generate(metadata=metadata, path=path, name=name).render() + +This gives you more fine-grained control over how your template is +rendered. + +You can also use this approach to render templates that depend on +:ref:`altsrc <server-plugins-structures-altsrc>` tags by setting +``path`` to the path to the template, and setting ``name`` to the path +to the file to be generated, e.g.:: + + metadata = self.build_metadata("foo.example.com") + path = "/Cfg/etc/sysconfig/network-scripts/ifcfg-template/ifcfg-template.genshi" + bcfg2root = "/var/lib/bcfg2" + name = "/etc/sysconfig/network-scripts/ifcfg-bond0" + File permissions ================ @@ -98,10 +154,10 @@ Permissions entry and a Path entry to handle the same file. Error handling ================ -Situations may arrise where a templated file cannot be generated due to +Situations may arise where a templated file cannot be generated due to missing or incomplete information. A TemplateError can be raised to -force a bind failure and prevent sending an incomplete file to the client. -For example, this template:: +force a bind failure and prevent sending an incomplete file to the +client. For example, this template:: {% python from genshi.template import TemplateError diff --git a/doc/server/plugins/grouping/metadata.txt b/doc/server/plugins/grouping/metadata.txt index 1c915e2cf..43cc6a2d7 100644 --- a/doc/server/plugins/grouping/metadata.txt +++ b/doc/server/plugins/grouping/metadata.txt @@ -217,9 +217,9 @@ useful results: </Groups> Each of the included groups files has the same format. These files are -properly validated by ``bcfg2-repo-validate``. This mechanism is -useful for composing group definitions from multiple sources, or -setting different permissions in an svn repository. +properly validated by ``bcfg2-lint``. This mechanism is useful for +composing group definitions from multiple sources, or setting +different permissions in an svn repository. Probes ====== diff --git a/doc/server/plugins/probes/index.txt b/doc/server/plugins/probes/index.txt index 33ec6f444..b9f698a0f 100644 --- a/doc/server/plugins/probes/index.txt +++ b/doc/server/plugins/probes/index.txt @@ -143,3 +143,60 @@ Other examples :hidden: ohai + +.. _server-plugins-probes-fileprobes: + +FileProbes +========== + +The FileProbes plugin allows you to probe a client for a file, +which is then added to the :ref:`server-plugins-generators-cfg` +specification. If the file changes on the client, FileProbes can +either update it in the specification or allow Cfg to replace it. + +FileProbes will not probe a file if there's already a file in Cfg that +will apply to the client. So if, for instance, you have a generic +file in ``Cfg/etc/foo.conf/foo.conf`` that applies to all hosts, +FileProbes will not retrieve ``/etc/foo.conf`` from the client (unless +``update`` is enabled; see Configuration_ below). + +When a new config file is first probed, an ``info.xml`` file is also +written to enforce the permissions from that client. Subsequent +probes from other clients will not modify or overwrite the data in +``info.xml``. (This ensures that any manual changes you make to +``info.xml`` for that file are not circumvented.) + +Configuration +------------- + +FileProbes is configured in ``FileProbes/config.xml``, which might +look something like: + +.. code-block:: xml + + <FileProbes> + <FileProbe name="/etc/foo.conf"/> + <Group name="blah-servers"> + <FileProbe name="/etc/blah.conf" update="true" + </Group> + <Client name="bar.example.com"> + <FileProbe name="/var/lib/bar.gz" base64="true"/> + </Client> + </FileProbes> + +This will result in ``/etc/foo.conf`` being retrieved from all +clients; if it changes on a client, it will be overwritten by the +version that was retrieved initially. + +Clients in the ``blah-servers`` group will be probed for +``/etc/blah.conf``; if it changes on a client, those changes will be +written into the Bcfg2 specification. If the file is deleted from a +client, it will be rewritten from Bcfg2. + +``bar.example.com`` will be probed for ``/var/lib/bar.gz``, which +contains non-ASCII characters and so needs to use base64 encoding when +transferring the file. + +The paths probed by FileProbes must also be included as Path entries +in your bundles in order to be handled properly by Cfg. Permissions +are handled as usual, with ``info.xml`` files in Cfg. diff --git a/doc/server/plugins/structures/base.txt b/doc/server/plugins/structures/base.txt index 66d8062e1..03eae0573 100644 --- a/doc/server/plugins/structures/base.txt +++ b/doc/server/plugins/structures/base.txt @@ -6,6 +6,13 @@ Base ==== +.. deprecated:: 1.2.0 + +.. warning:: + + The Base plugin no longer receives new features/functionality. + Please use :ref:`server-plugins-structures-bundler-index` instead. + The Base plugin is a structure plugin that provides the ability to add lists of unrelated entries into client configuration entry inventories. diff --git a/doc/server/plugins/structures/bundler/index.txt b/doc/server/plugins/structures/bundler/index.txt index 0d0054a2c..6b5c246aa 100644 --- a/doc/server/plugins/structures/bundler/index.txt +++ b/doc/server/plugins/structures/bundler/index.txt @@ -16,14 +16,15 @@ entries. For example, a bundle could say that the configuration file describe the particular version of ``/etc/passwd`` that a given client will receive. -Groups can be used inside of bundles to differentiate which entries -particular clients will recieve; this is useful for the case where -entries are named differently across systems; for example, one linux -distro may have a package called openssh while another uses the name -ssh. Configuration entries nested inside of Group elements only apply -to clients who are a member of those groups; multiple nested groups must -all apply. Also, groups may be negated; entries included in such groups -will only apply to clients who are not a member of said group. +Group and Client tags can be used inside of bundles to differentiate +which entries particular clients will recieve; this is useful for the +case where entries are named differently across systems; for example, +one linux distro may have a package called openssh while another uses +the name ssh. Configuration entries nested inside of Group elements +only apply to clients who are a member of those groups; multiple +nested groups must all apply. Also, groups may be negated; entries +included in such groups will only apply to clients who are not a +member of said group. The same applies to Client elements. The following is an annotated copy of a bundle: @@ -54,20 +55,25 @@ The following is an annotated copy of a bundle: <Package name='ssh'/> <Service name='ssh'/> </Group> + <Client name='trust.example.com'> + <Path name='/etc/ssh/shosts.equiv'/> + </Client> </Bundle> -In this bundle, most of the entries are common to all systems. Clients in -group **deb** get one extra package and service, while clients in group -**rpm** get two extra packages and an extra service. In addition, clients -in group **fedora** *and* group **rpm** get one extra package entries, -unless they are not in the **fc14** group, in which case, they get an -extra package. Notice that this file doesn't describe which versions -of these entries that clients should get, only that they should get -them. (Admittedly, this example is slightly contrived, but demonstrates -how group entries can be used in bundles) +In this bundle, most of the entries are common to all systems. Clients +in group **deb** get one extra package and service, while clients in +group **rpm** get two extra packages and an extra service. In +addition, clients in group **fedora** *and* group **rpm** get one +extra package entries, unless they are not in the **fc14** group, in +which case, they get an extra package. The client +**trust.example.com** gets one extra file that is not distributed to +any other clients. Notice that this file doesn't describe which +versions of these entries that clients should get, only that they +should get them. (Admittedly, this example is slightly contrived, but +demonstrates how group entries can be used in bundles) +----------------------------+-------------------------------+ -| Group | Entry | +| Group/Hostname | Entry | +============================+===============================+ | all | /etc/ssh/ssh_host_dsa_key | +----------------------------+-------------------------------+ @@ -101,6 +107,8 @@ how group entries can be used in bundles) +----------------------------+-------------------------------+ | deb | Service ssh | +----------------------------+-------------------------------+ +| trust.example.com | /etc/ssh/shosts.equiv | ++----------------------------+-------------------------------+ Genshi templates ================ @@ -148,6 +156,23 @@ format is XML. A Genshi template looks much like a Bundler file, except the Bundle tag has an additional `xmlns:py` attribute. See the examples. +Troubleshooting +--------------- + +There is no :ref:`bcfg2-info <server-bcfg2-info>` command like +``buildfile`` for Bundler templates, so if you want to generate a +Bundler template for a given client, you have to do so manually by +first invoking ``bcfg2-info debug``, then run:: + + metadata = self.build_metadata("<hostname>") + path = "<full path to template file>" + from genshi.template import TemplateLoader, MarkupTemplate + template = TemplateLoader().load(path, cls=MarkupTemplate) + print template.generate(metadata=metadata).render('xml') + +``path`` needs to be the full path to the template file on the +filesystem, not just within the Bcfg2 repo. + Altsrc ====== @@ -220,6 +245,8 @@ The latter form is preferred if the if block contains multiple files. While this example is simple, the test in the if block can in fact be any python statement. +.. _server-plugins-structures-bundler-index-examples: + Other examples ============== |