diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/appendix/guides/centos.txt | 22 | ||||
-rw-r--r-- | doc/conf.py | 24 | ||||
-rw-r--r-- | doc/help/troubleshooting.txt | 112 | ||||
-rw-r--r-- | doc/reports/dynamic.txt | 55 | ||||
-rw-r--r-- | doc/server/configurationentries.txt | 35 | ||||
-rw-r--r-- | doc/server/info.txt | 2 | ||||
-rw-r--r-- | doc/server/plugins/connectors/properties.txt | 17 | ||||
-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/tgenshi/index.txt | 61 | ||||
-rw-r--r-- | doc/server/plugins/index.txt | 2 | ||||
-rw-r--r-- | doc/server/plugins/probes/index.txt | 43 | ||||
-rw-r--r-- | doc/server/plugins/structures/base.txt | 7 | ||||
-rw-r--r-- | doc/server/plugins/structures/bundler/index.txt | 27 | ||||
-rw-r--r-- | doc/server/plugins/structures/deps.txt (renamed from doc/server/plugins/generators/deps.txt) | 0 |
15 files changed, 350 insertions, 101 deletions
diff --git a/doc/appendix/guides/centos.txt b/doc/appendix/guides/centos.txt index d788891de..ce8e49703 100644 --- a/doc/appendix/guides/centos.txt +++ b/doc/appendix/guides/centos.txt @@ -195,17 +195,17 @@ line of ``bcfg2.conf``. Then create Packages layout (as per <Sources> <!-- CentOS (5.4) sources --> <YUMSource> - <Group>centos5.4</Group> + <Group>centos-5.4</Group> <RawURL>http://mrepo/centos5-x86_64/RPMS.os</RawURL> <Arch>x86_64</Arch> </YUMSource> <YUMSource> - <Group>centos5.4</Group> + <Group>centos-5.4</Group> <RawURL>http://mrepo/centos5-x86_64/RPMS.updates</RawURL> <Arch>x86_64</Arch> </YUMSource> <YUMSource> - <Group>centos5.4</Group> + <Group>centos-5.4</Group> <RawURL>http://mrepo/centos5-x86_64/RPMS.extras</RawURL> <Arch>x86_64</Arch> </YUMSource> @@ -227,9 +227,9 @@ file should look something like this <Groups version='3.0'> <Group profile='true' public='true' default='true' name='basic'> - <Group name='centos5.4'/> + <Group name='centos-5.4'/> </Group> - <Group name='centos5.4'> + <Group name='centos-5.4'> <Group name='centos'/> </Group> <Group name='ubuntu'/> @@ -497,6 +497,18 @@ Then add the files to Cfg:: mkdir -p Cfg/etc/pki/rpm-gpg/RPM-GPG-KEY-EPEL cp /etc/pki/rpm-gpg/RPM-GPG-KEY-EPEL !$/RPM-GPG-KEY-EPEL +You will also want to add an *important* attribute to these files so +that they are installed on the client prior to any attempts to install +the **gpg-pubkey** rpm packages. This is especially important during the +bootstrapping phase and can be accomplished using an :ref:`server-info` +file that looks like the following: + +.. code-block:: xml + + <FileInfo> + <Info owner='root' group='root' perms='0644' important='true'/> + </FileInfo> + Now, running the client shows only unmanaged Service entries. Woohoo! Manage services diff --git a/doc/conf.py b/doc/conf.py index 77ab6fd94..4b13579d7 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -40,8 +40,13 @@ source_suffix = '.txt' master_doc = 'index' # General information about the project. -project = u'Bcfg2' -copyright = u'2009-%s, Narayan Desai' % time.strftime('%Y') +# py3k compatibility +if sys.hexversion >= 0x03000000: + project = 'Bcfg2' + copyright = '2009-%s, Narayan Desai' % time.strftime('%Y') +else: + project = u'Bcfg2' + copyright = u'2009-%s, Narayan Desai' % time.strftime('%Y') # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -174,10 +179,17 @@ latex_font_size = '11pt' # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass [howto/manual]). -latex_documents = [ - ('contents', 'bcfg2.tex', u'Bcfg2 Documentation', - u'Narayan Desai et al.', 'manual', True), -] +# py3k compatibility +if sys.hexversion >= 0x03000000: + latex_documents = [ + ('contents', 'bcfg2.tex', 'Bcfg2 Documentation', + 'Narayan Desai et al.', 'manual', True), + ] +else: + latex_documents = [ + ('contents', 'bcfg2.tex', u'Bcfg2 Documentation', + u'Narayan Desai et al.', 'manual', True), + ] # The name of an image file (relative to this directory) to place at the top of # the title page. diff --git a/doc/help/troubleshooting.txt b/doc/help/troubleshooting.txt index 88a0febc5..5fe1500f4 100644 --- a/doc/help/troubleshooting.txt +++ b/doc/help/troubleshooting.txt @@ -81,101 +81,138 @@ Type `help` in bcfg2-info for more information. Error Messages ============== -This page describes error messages produced by Bcfg2 and steps that can +The tables below describe error messages produced by Bcfg2 and steps that can be taken to remedy them. +Client Errors +------------- + +------------------------------+----------+---------------------+--------------+ | Error | Location | Meaning | Repair | +==============================+==========+=====================+==============+ -| Incomplete information for | Client | The described entry | [1]_ | +| Incomplete information for | Client | The described entry | [c1]_ | | entry <EntryTag>:<EntryName> | | is not fully | | | cannot verify | | specified by the | | | | | server, so no | | | | | verification can be | | | | | performed. | | +------------------------------+----------+---------------------+--------------+ -| Incomplete information for | Client | The described entry | [1]_ | +| Incomplete information for | Client | The described entry | [c1]_ | | entry <EntryTag>:<EntryName> | | is not fully | | | cannot install | | specified by the | | | | | server, so no | | | | | verification can be | | | | | performed. | | +------------------------------+----------+---------------------+--------------+ -| The following entries are | Client | The client cannot | [2]_ | +| The following entries are | Client | The client cannot | [c2]_ | | not handled by any tool: | | figure out how to | | | <EntryTag>:<EntryName> | | handle this entry. | | +------------------------------+----------+---------------------+--------------+ -| No ca is specified. Cannot | Client | The client is | [3]_ | +| No ca is specified. Cannot | Client | The client is | [c3]_ | | authenticate the server with | | unable to verify | | | SSL. | | the server | | +------------------------------+----------+---------------------+--------------+ -| Failed to bind entry: | Server | The server was | [4]_ | +| GID normalization failed for | Client | The client is | [c4]_ | +| FILENAME. Does group GROUP | | unable to convert | | +| exist? | | the group GROUP to | | +| | | a usable GID | | ++------------------------------+----------+---------------------+--------------+ +| UID normalization failed for | Client | The client is | [c5]_ | +| FILENAME. Does owner OWNER | | unable to convert | | +| exist? | | the owner OWNER to | | +| | | a usable UID | | ++------------------------------+----------+---------------------+--------------+ + + +.. [c1] This entry is not being bound. Ensure that a version of this + entry applies to this client. +.. [c2] It is possible that the type attribute for this generator entry + is undefined. You may need to add the appropriate type attribute + in the literal entry specification. +.. [c3] Copy the Bcfg2 server's CA certificate to the client and specify it + using the **ca** option in the [communication] section of + ``bcfg2.conf`` +.. [c4] If the group doesn't exist, you need to specify the correct one + in an :ref:`info.xml <server-info>` file or set the default group + appropriately. +.. [c5] If the owner doesn't exist, you need to specify the correct one + in an :ref:`info.xml <server-info>` file or set the default owner + appropriately. + +Server Errors +------------- + ++------------------------------+----------+---------------------+--------------+ +| Error | Location | Meaning | Repair | ++==============================+==========+=====================+==============+ +| Failed to bind entry: | Server | The server was | [s1]_ | | <EntryTag> <EntryName> | | unable to find a | | | | | suitable version of | | | | | entry for client. | | +------------------------------+----------+---------------------+--------------+ -| Failed to bind to socket | Server | The server was | [5]_ | +| Failed to bind to socket | Server | The server was | [s2]_ | | | | unable to bind to | | | | | the tcp server | | | | | socket. | | +------------------------------+----------+---------------------+--------------+ -| Failed to load | Server | The server was | [6]_ | +| Failed to load | Server | The server was | [s3]_ | | ssl key <path> | | unable to read and | | | | | process the ssl key.| | +------------------------------+----------+---------------------+--------------+ -| Failed to read file <path> | Server | The server failed | [7]_ | +| Failed to read file <path> | Server | The server failed | [s4]_ | | | | to read the | | | | | specified file | | +------------------------------+----------+---------------------+--------------+ -| Failed to parse file <path> | Server | The server failed | [8]_ | +| Failed to parse file <path> | Server | The server failed | [s5]_ | | | | to parse the | | | | | specified XML file | | +------------------------------+----------+---------------------+--------------+ -| Client metadata resolution | Server | The server cannot | [9]_ | +| Client metadata resolution | Server | The server cannot | [s6]_ | | error for <IP> | | resolve the client | | | | | hostname or the | | | | | client is | | | | | associated with a | | | | | non-profile group. | | +------------------------------+----------+---------------------+--------------+ -| Failed to decode <filename> | Server | The encoding being | [10]_ | +| Failed to decode <filename> | Server | The encoding being | [s7]_ | | Please verify you are using | | used is unable to | | | the proper encoding | | decode the | | | | | character present | | | | | in this file. | | +------------------------------+----------+---------------------+--------------+ -| Got unknown entries | Server | The Packages plugin | [11]_ | +| Got unknown entries | Server | The Packages plugin | [s8]_ | | [list of unknown entries] | | has no knowledge of | | | | | the listed entries | | +------------------------------+----------+---------------------+--------------+ -| Failed to import lxml | Server | The server cannot | [12]_ | +| Failed to import lxml | Server | The server cannot | [s9]_ | | dependency. Shutting | | import lxml | | | down server. | | | | +------------------------------+----------+---------------------+--------------+ +| You need to specify base64 | Server | The server cannot | [s10]_ | +| encoding for <path> | | send the file as | | +| | | ascii text | | ++------------------------------+----------+---------------------+--------------+ +| ERROR: Error reading file | Server | The server cannot | [s11]_ | +| '/path/to/schema': failed to | | find the schema | | +| load external entity | | file | | +| "/path/to/schema" | | | | ++------------------------------+----------+---------------------+--------------+ -.. [1] This entry is not being bound. Ensure that a version of this - entry applies to this client. -.. [2] It is possible that the type attribute for this generator entry - is undefined. You may need to add the appropriate type attribute - in the literal entry specification. -.. [3] Copy the Bcfg2 server's CA certificate to the client and specify it - using the **ca** option in the [communication] section of - ``bcfg2.conf`` -.. [4] This entry is not being bound. Ensure that a version of this - entry applies to this client. -.. [5] Ensure that another instance of the daemon (or any other process) - is not listening on the same port. -.. [6] Ensure that the key is readable by the user running the daemon - and that it is well-formed. -.. [7] Ensure that this file still exists; a frequent cause is the - deletion of a temp file. -.. [8] Ensure that the file is properly formed XML. -.. [9] Fix hostname resolution for the client or ensure that the profile - group is properly setup. -.. [10] Ensure the correct encoding is specified in the [components] +.. [s1] This entry is not being bound. Ensure that a version of this + entry applies to this client. +.. [s2] Ensure that another instance of the daemon (or any other process) + is not listening on the same port. +.. [s3] Ensure that the key is readable by the user running the daemon + and that it is well-formed. +.. [s4] Ensure that this file still exists; a frequent cause is the + deletion of a temp file. +.. [s5] Ensure that the file is properly formed XML. +.. [s6] Fix hostname resolution for the client or ensure that the profile + group is properly setup. +.. [s7] Ensure the correct encoding is specified in the [components] section of ``bcfg2.conf``. -.. [11] For packages listed other than **gpg-pubkey**, this error means +.. [s8] For packages listed other than **gpg-pubkey**, this error means that the Packages plugin is unable to find the package in any of the sources listed in ``Packages/config.xml``. The issue often arises when the client is not in one of the groups necessary for @@ -183,8 +220,11 @@ be taken to remedy them. ignore the message as the Packages plugin has no knowledge of these packages (however, note that this package is most often specified as a BoundPackage entry). -.. [12] Ensure that you have installed all the necessary +.. [s9] Ensure that you have installed all the necessary :ref:`installation-prerequisites`. +.. [s10] You likely need to specify a base64 encoding using an + :ref:`server-info` file for this entry. +.. [s11] Verify that you have the proper prefix set in bcfg2.conf. FAQs ==== diff --git a/doc/reports/dynamic.txt b/doc/reports/dynamic.txt index 6e0ea8050..4c75cce32 100644 --- a/doc/reports/dynamic.txt +++ b/doc/reports/dynamic.txt @@ -188,29 +188,38 @@ displays:: Usage: python bcfg2-reports [option] ... Options and arguments (and corresponding environment variables): - -a : shows all hosts, including expired hosts - -b NAME : single-host mode - shows bad entries from the - current interaction of NAME - -c : shows only clean hosts - -d : shows only dirty hosts - -e NAME : single-host mode - shows extra entries from the - current interaction of NAME - -h : shows help and usage info about bcfg2-reports - -s NAME : single-host mode - shows bad and extra entries from - the current interaction of NAME - -x NAME : toggles expired/unexpired state of NAME - --badentry=KIND,NAME : shows only hosts whose current interaction has bad - entries in of KIND kind and NAME name; if a single - argument ARG1 is given, then KIND,NAME pairs will be - read from a file of name ARG1 - --extraentry=KIND,NAME : shows only hosts whose current interaction has extra - entries in of KIND kind and NAME name; if a single - argument ARG1 is given, then KIND,NAME pairs will be - read from a file of name ARG1 - --fields=ARG1,ARG2,... : only displays the fields ARG1,ARG2,... - (name,time,state) - --sort=ARG1,ARG2,... : sorts output on ARG1,ARG2,... (name,time,state) - --stale : shows hosts which haven't run in the last 24 hours + -a : shows all hosts, including expired hosts + -b NAME : single-host mode - shows bad entries from the + current interaction of NAME + -c : shows only clean hosts + -d : shows only dirty hosts + -e NAME : single-host mode - shows extra entries from the + current interaction of NAME + -h : shows help and usage info about bcfg2-reports + -m NAME : single-host mode - shows modified entries from the + current interaction of NAME + -s NAME : single-host mode - shows bad, modified, and extra + entries from the current interaction of NAME + -t NAME : single-host mode - shows total number of managed and + good entries from the current interaction of NAME + -x NAME : toggles expired/unexpired state of NAME + --badentry=KIND,NAME : shows only hosts whose current interaction has bad + entries in of KIND kind and NAME name; if a single + argument ARG1 is given, then KIND,NAME pairs will be + read from a file of name ARG1 + --modifiedentry=KIND,NAME : shows only hosts whose current interaction has + modified entries in of KIND kind and NAME name; if a + single argument ARG1 is given, then KIND,NAME pairs + will be read from a file of name ARG1 + --extraentry=KIND,NAME : shows only hosts whose current interaction has extra + entries in of KIND kind and NAME name; if a single + argument ARG1 is given, then KIND,NAME pairs will be + read from a file of name ARG1 + --fields=ARG1,ARG2,... : only displays the fields ARG1,ARG2,... + (name,time,state,total,good,bad) + --sort=ARG1,ARG2,... : sorts output on ARG1,ARG2,... + (name,time,state,total,good,bad) + --stale : shows hosts which haven't run in the last 24 hours Screenshots =========== diff --git a/doc/server/configurationentries.txt b/doc/server/configurationentries.txt index 5602da189..0c12ce9c9 100644 --- a/doc/server/configurationentries.txt +++ b/doc/server/configurationentries.txt @@ -34,6 +34,22 @@ Non-POSIX entries | 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,7 +64,7 @@ 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-lint`` will check your configuration specification for the presence of any mandatory attributes that are necessary for the @@ -91,8 +107,8 @@ Path type specified. | | | that should not | | | | | exist | | +-------------+----------------------+-----------------+--------------------------+ -| permissions | Replaces Permissions | Permissions of | name, owner, | -| | entries | POSIX entities | group, perms | +| permissions | Replaces Permissions | Permissions of | name, owner, group, | +| | entries | POSIX entities | perms, recursive | | | | | | +-------------+----------------------+-----------------+--------------------------+ | vcs | New | Create version | vcstype (git), | @@ -103,6 +119,19 @@ Path type specified. Keep in mind that permissions for files served up 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. + .. _boundentries: Bound Entries diff --git a/doc/server/info.txt b/doc/server/info.txt index 231a83a52..f1154e665 100644 --- a/doc/server/info.txt +++ b/doc/server/info.txt @@ -41,6 +41,8 @@ possible fields in an info file are: | paranoid: | yes | no | Backup file before replacement? | no | +------------+-------------------+----------------------------------+---------+ | perms: | Numeric file mode | Sets the permissions of the file | 0644 | +| | | 'inherit' | (or inherits from the files on | | +| | | disk if set to inherit) | | +------------+-------------------+----------------------------------+---------+ A sample info file for CGI script on a web server might look like:: diff --git a/doc/server/plugins/connectors/properties.txt b/doc/server/plugins/connectors/properties.txt index 1cbc4cf65..3329f48bd 100644 --- a/doc/server/plugins/connectors/properties.txt +++ b/doc/server/plugins/connectors/properties.txt @@ -38,7 +38,7 @@ Usage Specific property files can be referred to in templates as ``metadata.Properties[<filename>]``. The -data attribute is an LXML element object. (Documented +``xdata`` attribute is an LXML element object. (Documented `here <http://codespeak.net/lxml/tutorial.html#the-element-class>`_) Currently, only one access method is defined for this data, ``Match``. @@ -56,10 +56,21 @@ more details on how Group and Client tags are parsed.) For instance:: 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.) + Accessing Properties contents from TGenshi ========================================== Access contents of ``Properties/auth.xml``:: - - ${metadata.Properties['auth.xml'].data.find('file').find('bcfg2.key').text} + ${metadata.Properties['auth.xml'].xdata.find('file').find('bcfg2.key').text} 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/tgenshi/index.txt b/doc/server/plugins/generators/tgenshi/index.txt index 0fc541b52..d7e0b3bf2 100644 --- a/doc/server/plugins/generators/tgenshi/index.txt +++ b/doc/server/plugins/generators/tgenshi/index.txt @@ -54,7 +54,10 @@ Inside of templates 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 @@ -91,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 ================ @@ -101,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/index.txt b/doc/server/plugins/index.txt index 8ef3d5af3..ca1cf459a 100644 --- a/doc/server/plugins/index.txt +++ b/doc/server/plugins/index.txt @@ -65,8 +65,8 @@ Literal Configuration (Generators) :maxdepth: 1 :glob: - generators/tgenshi/index generators/* + generators/tgenshi/index Each of these plugins has a corresponding subdirectory with the same name in the Bcfg2 repository. diff --git a/doc/server/plugins/probes/index.txt b/doc/server/plugins/probes/index.txt index b9f698a0f..5b1f9e259 100644 --- a/doc/server/plugins/probes/index.txt +++ b/doc/server/plugins/probes/index.txt @@ -85,10 +85,12 @@ file looks like:: #end if Any Probe script you run will store its output in -``$self.metadata.Probes["scriptname"]``, so we get to our `scratchlocal` -script's output as seen above. Note that we had to wrap the output in an -`int()` call; the script output is treated as a string, so it needs to -be converted before it can be tested numerically. +``$self.metadata.Probes["scriptname"]``, so we get to our +`scratchlocal` script's output as seen above. (See `Handling Probe +Output`_, below, for more information on how this is done.) Note that +we had to wrap the output in an `int()` call; the script output is +treated as a string, so it needs to be converted before it can be +tested numerically. With all of these pieces in place, the following series of events will happen when the client is run: @@ -110,8 +112,37 @@ is to add the ``/etc/auto.master`` to a Bundle: <Path name='/etc/auto.master'/> -Host and Group Specific probes -============================== +Handling Probe Output +===================== + +Bcfg2 stores output from probes in the ``Probes`` property of a +client's metadata object. To access this data in TGenshi, for +instance, you could do:: + + ${metadata.Probes['script-name']} + +This is not the full output of the probe; any lines that start with +"group:" have been stripped from the output. The data is a +string-like object that has some interesting and salient features: + +* If the data is a valid XML document, then + ``metadata.Probes['script-name'].xdata`` will be an + ``lxml.etree._Element`` object representing the XML data. +* If the data is a valid JSON document, and either the Python ``json`` + or ``simplejson`` module is installed, then + ``metadata.Probes['script-name'].json`` will be a data structure + representing the JSON data. +* If the data is a valid YAML document, and either the Python ``yaml`` + or ``syck`` module is installed, then + ``metadata.Probes['script-name'].yaml`` will be a data structure + representing the YAML data. + +If these conditions are not met, then the named properties will be +``None``. In all other fashions, the probe data objects should act +like strings. + +Host- and Group-Specific probes +=============================== Bcfg2 has the ability to alter probes based on client hostname and group membership. These files work similarly to 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 9fd897385..5ca53b010 100644 --- a/doc/server/plugins/structures/bundler/index.txt +++ b/doc/server/plugins/structures/bundler/index.txt @@ -146,6 +146,16 @@ The `Genshi templating system`_ is used internally. Use --- +.. warning:: + + Group tags are not used inside of Genshi templates. You can get the + same logic (and more) using Genshi conditionals. + + .. code-block:: xml + + <py:if test="groupname in metadata.groups"> + </py:if> + Bcfg uses the Genshi API for templates, and performs a XML format stream rendering of the template into an lxml entry, which is included in the client configuration. :ref:`Client metadata <client-metadata>` @@ -156,6 +166,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 ====== diff --git a/doc/server/plugins/generators/deps.txt b/doc/server/plugins/structures/deps.txt index 7c5861d06..7c5861d06 100644 --- a/doc/server/plugins/generators/deps.txt +++ b/doc/server/plugins/structures/deps.txt |