diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/appendix/guides/centos.txt | 12 | ||||
| -rw-r--r-- | doc/conf.py | 24 | ||||
| -rw-r--r-- | doc/server/configurationentries.txt | 17 | ||||
| -rw-r--r-- | doc/server/info.txt | 2 | ||||
| -rw-r--r-- | doc/server/plugins/connectors/properties.txt | 17 | ||||
| -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/bundler/index.txt | 10 | ||||
| -rw-r--r-- | doc/server/plugins/structures/deps.txt (renamed from doc/server/plugins/generators/deps.txt) | 0 |
9 files changed, 109 insertions, 18 deletions
diff --git a/doc/appendix/guides/centos.txt b/doc/appendix/guides/centos.txt index 0b5b83211..ce8e49703 100644 --- a/doc/appendix/guides/centos.txt +++ b/doc/appendix/guides/centos.txt @@ -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/server/configurationentries.txt b/doc/server/configurationentries.txt index 10eccf6be..0c12ce9c9 100644 --- a/doc/server/configurationentries.txt +++ b/doc/server/configurationentries.txt @@ -107,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), | @@ -119,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/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/bundler/index.txt b/doc/server/plugins/structures/bundler/index.txt index 6b5c246aa..c74e13e9d 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-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>` 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 |