diff options
author | Jason Kincl <kincljc@ornl.gov> | 2012-11-27 14:28:01 -0500 |
---|---|---|
committer | Jason Kincl <kincljc@ornl.gov> | 2012-11-27 14:28:01 -0500 |
commit | 5e0265f837f0eb72123be0b5150451aebdf8b031 (patch) | |
tree | dbd5fdbe4ec93c48cbba6fec3f608ffefb26eac5 /doc | |
parent | 894299b01b6138c54a99fd41f166554d175d6106 (diff) | |
parent | 4c70626094248495bf2c11c09bf2f2f60917187d (diff) | |
download | bcfg2-5e0265f837f0eb72123be0b5150451aebdf8b031.tar.gz bcfg2-5e0265f837f0eb72123be0b5150451aebdf8b031.tar.bz2 bcfg2-5e0265f837f0eb72123be0b5150451aebdf8b031.zip |
Merge remote branch 'upstream/master' into jasons-hacking
Diffstat (limited to 'doc')
-rw-r--r-- | doc/development/plugins.txt | 1 | ||||
-rw-r--r-- | doc/man/bcfg2.conf.txt | 22 | ||||
-rw-r--r-- | doc/server/caching.txt | 3 | ||||
-rw-r--r-- | doc/server/plugins/generators/cfg.txt | 85 | ||||
-rw-r--r-- | doc/server/plugins/generators/rules.txt | 26 | ||||
-rw-r--r-- | doc/server/plugins/structures/bundler/index.txt | 55 |
6 files changed, 108 insertions, 84 deletions
diff --git a/doc/development/plugins.txt b/doc/development/plugins.txt index a680e7d04..91a4e6868 100644 --- a/doc/development/plugins.txt +++ b/doc/development/plugins.txt @@ -67,6 +67,7 @@ provide interfaces that a given plugin may or must implement. Interfaces ^^^^^^^^^^ +.. class:: Bcfg2.Server.Plugin.interfaces .. automodule:: Bcfg2.Server.Plugin.interfaces Exposing XML-RPC Functions diff --git a/doc/man/bcfg2.conf.txt b/doc/man/bcfg2.conf.txt index b8e252cc4..d8f2bc3df 100644 --- a/doc/man/bcfg2.conf.txt +++ b/doc/man/bcfg2.conf.txt @@ -434,6 +434,28 @@ Trigger Plugin The Trigger plugin provides a method for calling external scripts when clients are configured. +Caching options +--------------- + +These options are specified in the **[caching]** section. + + client_metadata + The following four caching modes are available for client + metadata: + + * off: No caching of client metadata objects is performed. This + is the default. + * initial: Only initial metadata objects are cached. Initial + metadata objects are created only from the data in the + Metadata plugin, before additional groups from other plugins + are merged in. + * cautious: Final metadata objects are cached, but each client’s + cache is cleared at the start of each client run, immediately + after probe data is received. Cache is also cleared as in + aggressive mode. *on* is a synonym for cautious. + * aggressive: Final metadata objects are cached. Each plugin is + responsible for clearing cache when appropriate. + Client options -------------- diff --git a/doc/server/caching.txt b/doc/server/caching.txt index ab98e9902..51245bd08 100644 --- a/doc/server/caching.txt +++ b/doc/server/caching.txt @@ -20,7 +20,8 @@ can be generated anywhere from 7 to dozens of times per client run was made more complex and powerful in 1.3.0, caching these objects provides the easiest performance gain. -There are four caching modes available: +To enable caching, add a ``[caching]`` section to bcfg2.conf with a +client_metadata option containing one of the following modes: * ``off``: No caching of client metadata objects is performed. This is the default. diff --git a/doc/server/plugins/generators/cfg.txt b/doc/server/plugins/generators/cfg.txt index 25986a413..7d0e0acff 100644 --- a/doc/server/plugins/generators/cfg.txt +++ b/doc/server/plugins/generators/cfg.txt @@ -106,26 +106,13 @@ Genshi templates allow you to use the `Genshi the deprecated :ref:`server-plugins-generators-tgenshi-index` plugin. Genshi templates should be named with a ``.genshi`` extension, e.g.:: - % ls Cfg/etc/motd + % ls Cfg/etc/motd info.xml motd.genshi See the genshi `documentation <http://genshi.edgewall.org/wiki/Documentation>`_ for examples of Genshi syntax. -Inside Genshi Templates -~~~~~~~~~~~~~~~~~~~~~~~ - -Several variables are pre-defined inside templates: - -* **metadata** is the client's :ref:`metadata - <server-plugins-grouping-metadata-clientmetadata>` -* **name** is the path name specified in Bcfg2 -* **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`` - Troubleshooting ~~~~~~~~~~~~~~~ @@ -138,7 +125,8 @@ E.g.:: bcfg2-info buildfile /etc/foo.conf foo.example.com -To generate a file with an altsrc attribute, you can run:: +To generate a file with an :ref:`altsrc +<server-plugins-structures-altsrc>` attribute, you can run:: bcfg2-info buildfile /etc/foo/foo.conf --altsrc=/etc/foo.conf \ foo.example.com @@ -149,13 +137,13 @@ debug``, and, once in the Python interpreter, run:: metadata = self.build_metadata("<hostname>") path = "<relative path to template (see note below)>" - + ``path`` should be set to the path to the template file with a leading slash, relative to the Bcfg2 specification root. See `Inside Genshi Templates`_ for examples. Then, run:: - + import os, Bcfg2.Options from genshi.template import TemplateLoader, NewTextTemplate name = os.path.dirname(path[path.find('/', 1):]) @@ -230,19 +218,9 @@ Cheetah templates allow you to use the `cheetah templating system the deprecated :ref:`server-plugins-generators-tcheetah` plugin. Cheetah templates should be named with a ``.cheetah`` extension, e.g.:: - % ls Cfg/etc/motd + % ls Cfg/etc/motd info.xml motd.cheetah -Inside Cheetah Templates -~~~~~~~~~~~~~~~~~~~~~~~~ - -Several variables are pre-defined inside templates: - -* **self.metadata** is the client's :ref:`metadata - <server-plugins-grouping-metadata-clientmetadata>` -* **self.path** is the path name specified in Bcfg2 -* **self.source_path** is the path to the Genshi template on the filesystem. - Examples ~~~~~~~~ @@ -265,12 +243,48 @@ comment to appear in the final config file.:: # This is a comment in my template which will be stripped when it's processed through Cheetah \# This comment will appear in the generated config file. +Inside Templates +---------------- + +Several variables are pre-defined inside templates: + ++-------------+--------------------------------------------------------+ +| Name | Description | ++=============+========================================================+ +| metadata | :ref:`Client metadata | +| | <server-plugins-grouping-metadata-clientmetadata>` | ++-------------+--------------------------------------------------------+ +| name | The value of the ``name`` attribute as specified in | +| | the Path entry in Bcfg2. If an :ref:`altsrc | +| | <server-plugins-structures-altsrc>` attribute is used, | +| | then ``name`` will be the value of that attribute. | ++-------------+--------------------------------------------------------+ +| source_path | The path to the template file on the filesystem | ++-------------+--------------------------------------------------------+ +| repo | The path to the Bcfg2 repository on the filesystem | ++-------------+--------------------------------------------------------+ +| path | In Genshi templates, ``path`` is a synonym for | +| | ``source_path``. In Cheetah templates, it's a synonym | +| | for ``name``. For this reason, use of ``path`` is | +| | discouraged, and it may be deprecated in a future | +| | release. | ++-------------+--------------------------------------------------------+ + +To access these variables in a Genshi template, you can simply use the +name, e.g.:: + + Path to this file: ${name} + +In a Cheetah template, the variables are properties of ``self``, +e.g.:: + + Path to this file: $self.name Notes on Using Templates ------------------------ Templates can be host and group specific as well. Deltas will not be -processed for any genshi or cheetah base file. +processed for any Genshi or Cheetah base file. .. note:: @@ -278,19 +292,22 @@ processed for any genshi or cheetah base file. or group-specific files, you will need to ensure that the ``.genshi`` or ``.cheetah`` extension is at the **end** of the filename. Using the examples from above for *host.example.com* and group *server* you would - have the following (using genshi only):: + have the following:: Cfg/etc/fstab/fstab.H_host.example.com.genshi - Cfg/etc/fstab/fstab.G50_server.genshi + Cfg/etc/fstab/fstab.G50_server.cheetah Genshi templates take precence over cheetah templates. For example, if -two files exist named +two files exist named:: Cfg/etc/fstab/fstab.genshi Cfg/etc/fstab/fstab.cheetah -the cheetah template is ignored. But you can mix genshi and cheetah when -using different host-specific or group-specific files. For example: +The Cheetah template is ignored. Exploiting this fact is probably a +pretty bad idea in practice. + +You can mix Genshi and Cheetah when 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 diff --git a/doc/server/plugins/generators/rules.txt b/doc/server/plugins/generators/rules.txt index 079911238..542b38f01 100644 --- a/doc/server/plugins/generators/rules.txt +++ b/doc/server/plugins/generators/rules.txt @@ -300,24 +300,26 @@ nonexistent +===========+====================+=============+ | type | Type of file | nonexistent | +-----------+--------------------+-------------+ -| recursive | Recursively remove | true | +| recursive | Recursively remove | Boolean | | | directory contents | | +-----------+--------------------+-------------+ permissions ^^^^^^^^^^^ -+-----------+--------------------------+--------+ -| Name | Description | Values | -+===========+==========================+========+ -| mode | Mode of the file. | String | -+-----------+--------------------------+--------+ -| owner | Owner of the file. | String | -+-----------+--------------------------+--------+ -| group | Group of the file. | String | -+-----------+--------------------------+--------+ -| secontext | SELinux context | String | -+-----------+--------------------------+--------+ ++-----------+-----------------------------+---------+ +| Name | Description | Values | ++===========+=============================+=========+ +| mode | Mode of the file | String | ++-----------+-----------------------------+---------+ +| owner | Owner of the file | String | ++-----------+-----------------------------+---------+ +| group | Group of the file | String | ++-----------+-----------------------------+---------+ +| secontext | SELinux context | String | ++-----------+-----------------------------+---------+ +| recursive | Recursively set permissions | Boolean | ++-----------+-----------------------------+---------+ symlink ^^^^^^^ diff --git a/doc/server/plugins/structures/bundler/index.txt b/doc/server/plugins/structures/bundler/index.txt index 528df79db..1cc287ebd 100644 --- a/doc/server/plugins/structures/bundler/index.txt +++ b/doc/server/plugins/structures/bundler/index.txt @@ -113,40 +113,31 @@ demonstrates how group entries can be used in bundles) Genshi templates ================ -Genshi xml templates can be specified one of two ways: +Genshi XML templates allow you to use the `Genshi +<http://genshi.edgewall.org>`_ templating system to dynamically +generate a bundle. Genshi templates can be specified one of two ways: -1. Add an xml-style genshi template to the Bundler directory with a +1. Add an XML-style genshi template to the Bundler directory with a ``.genshi`` and the associated namespace attribute. -2. Simply add the appropriate namespace attribute to your existing xml +2. Simply add the appropriate namespace attribute to your existing XML bundle. -The namespace attribute in this case should look like the following:: +The top-level Bundle tag should look like the following:: - xmlns:py="http://genshi.edgewall.org/" + <Bundle name="foo" xmlns:py="http://genshi.edgewall.org/"> -Motivation ----------- +Several variables are pre-defined inside templates: -Static Bundles have served us relatively well, but have a relatively -weak set of interal per-client differentiation mechanisms. In static -Bundles, the group hierarchy (from the perspective of the current -client) is available for use via boolean constraints with negation. This -notion does not mesh well with the use of Probes, which can result in -freeform data. In the presence of probe results, clients can have a wide -array of data, and rendering down to a boolean logic may not always -be desirable. Moreover, while static Bundles allow entry inclusion or -exclusion based on group memberships, they do not allow programatic entry -rendering. Hence, Genshi templates not only provide more control options, -but it also provide the ability to perform new entry rendering operations. ++-------------+--------------------------------------------------------+ +| Name | Description | ++=============+========================================================+ +| metadata | :ref:`Client metadata | +| | <server-plugins-grouping-metadata-clientmetadata>` | ++-------------+--------------------------------------------------------+ +| repo | The path to the Bcfg2 repository on the filesystem | ++-------------+--------------------------------------------------------+ -The `Genshi templating system`_ is used internally. - -.. _Genshi templating system: http://genshi.edgewall.org/ - -Use ---- - -.. warning:: +.. note:: ``<Group>`` and ``<Client>`` tags are allowed inside of Genshi templates as of Bcfg2 1.2. However, they do not behave the same @@ -154,7 +145,7 @@ Use <py:if test="'groupname' in metadata.groups"> </py:if> - + The conditional is evaluated when the template is rendered, so code inside the conditional is not executed if the conditional fails. A ``<Group>`` tag is evaluated *after* the template is @@ -163,16 +154,6 @@ Use groups, you *must* use a Genshi conditional, not a ``<Group>`` tag. The same caveats apply to ``<Client>`` tags. -Bcfg2 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>` -is available inside of the template using the 'metadata' name. Note that -only the markup Genshi template format can be used, as the target output -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 --------------- |