summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorChris St. Pierre <chris.a.st.pierre@gmail.com>2013-05-17 15:07:45 -0400
committerChris St. Pierre <chris.a.st.pierre@gmail.com>2013-05-17 15:07:45 -0400
commitb7e2699f5156607258ed0d500c5d6d6b92c35f26 (patch)
tree24bde5be78c5d9920d21b3f79de06474ff3d282f /doc
parent044213c789c4f1ee214da3d70f02352b1aaa8673 (diff)
parent7e93fe741c17203fa63f60a7d1f66bfcdfb90d03 (diff)
downloadbcfg2-b7e2699f5156607258ed0d500c5d6d6b92c35f26.tar.gz
bcfg2-b7e2699f5156607258ed0d500c5d6d6b92c35f26.tar.bz2
bcfg2-b7e2699f5156607258ed0d500c5d6d6b92c35f26.zip
Merge branch 'maint'
Conflicts: doc/appendix/guides/centos.txt doc/server/plugins/grouping/metadata.txt setup.py src/lib/Bcfg2/Client/Frame.py src/lib/Bcfg2/Client/Proxy.py src/lib/Bcfg2/Server/Lint/Genshi.py src/lib/Bcfg2/Server/Lint/Validate.py src/lib/Bcfg2/Server/Plugins/Bundler.py src/lib/Bcfg2/Server/Plugins/SSHbase.py src/sbin/bcfg2-lint
Diffstat (limited to 'doc')
-rw-r--r--doc/_templates/indexsidebar.html1
-rw-r--r--doc/development/documentation.txt27
-rw-r--r--doc/development/lint.txt167
-rw-r--r--doc/server/plugins/connectors/grouplogic.txt4
-rw-r--r--doc/server/plugins/generators/packages.txt5
-rw-r--r--doc/server/plugins/generators/rules.txt6
-rw-r--r--doc/server/plugins/grouping/grouppatterns.txt17
7 files changed, 202 insertions, 25 deletions
diff --git a/doc/_templates/indexsidebar.html b/doc/_templates/indexsidebar.html
index 39916315d..2133cdcc5 100644
--- a/doc/_templates/indexsidebar.html
+++ b/doc/_templates/indexsidebar.html
@@ -7,5 +7,6 @@
<ul>
<li><a href="http://docs.bcfg2.org/1.1/">Bcfg2 1.1 (stable)</a></li>
<li><a href="http://docs.bcfg2.org/1.2/">Bcfg2 1.2 (stable)</a></li>
+ <li><a href="http://docs.bcfg2.org/1.3/">Bcfg2 1.3 (stable)</a></li>
<li><a href="http://docs.bcfg2.org/dev/">Bcfg2 development documentation</a></li>
</ul>
diff --git a/doc/development/documentation.txt b/doc/development/documentation.txt
index 2a3cf46d1..4d8a7c9f8 100644
--- a/doc/development/documentation.txt
+++ b/doc/development/documentation.txt
@@ -8,13 +8,14 @@
There are two parts of documentation in the Bcfg2 project:
-* The wiki
-* The manual
+* The Wiki_
+* The Manual_
The wiki
========
.. _Wiki: http://bcfg2.org
+.. _Manual: http://docs.bcfg2.org
.. _Trac: http://trac.edgewall.org/
.. _OpenID: https://openid.org/
.. _MCS: http://www.mcs.anl.gov/
@@ -31,9 +32,9 @@ The manual
==========
.. _rst: http://en.wikipedia.org/wiki/ReStructuredText
.. _Sphinx: http://sphinx.pocoo.org
-.. _Docutils:
+.. _Docutils: http://docutils.sourceforge.net
-The source for the manual is located in the ``doc/`` directory in the
+The source for the Manual_ is located in the ``doc/`` directory in the
git repository or in the source tarball. All files are written in
rst_ (ReStructuredText) format. Sphinx_ is used to build the
documentation from the restructured text sources.
@@ -49,11 +50,20 @@ Building the Manual
apt-get -t lenny-backports install python-sphinx
- * The needed tools for Fedora based systems are in the `Fedora
+ * The tools for Fedora based systems are in the `Fedora
Package Collection <https://admin.fedoraproject.org/pkgdb>`_;
installation can be done easily with Yum::
yum -y install python-sphinx python-docutils
+
+ * The tools for RHEL6-based systems are in the base distribution; you can install them with Yum::
+
+ yum -y install python-sphinx python-docutils
+
+ * The tools for RHEL5-based systems are in the `Extra Packages for Enterprise Linux(EPEL) <https://fedoraproject.org/wiki/EPEL>`_ repository; if your system is configured for EPEL, you can install them with Yum::
+
+ yum -y install python-sphinx python-docutils
+
* Additionally, to build the PDF version:
@@ -80,14 +90,14 @@ Documentation Style Guide for Bcfg2
===================================
This is a style guide to use when creating documentation for Bcfg2. It
-is meant to be helpful, not a hinderence.
+is meant to be helpful, not a hindrance.
Basics
------
**Bcfg2**
- When referring to project, Bcfg2 is the preferred use of cases.
+ When referring to project, Bcfg2 is the preferred use of case.
**Monospace fonts**
@@ -97,8 +107,7 @@ Basics
**Repository**
When used alone this refers to a Bcfg2 :term:`repository`. When there
- is a chance for confusion, for instance in documents also talking
- about :term:`VCS`, be sure to use the longer Bcfg2 :term:`repository`.
+ is a chance for confusion, for instance in documents that also discuss :term:`VCS`, be sure to use the longer phrase "Bcfg2 :term:`repository`".
Sections
--------
diff --git a/doc/development/lint.txt b/doc/development/lint.txt
new file mode 100644
index 000000000..6a4651f92
--- /dev/null
+++ b/doc/development/lint.txt
@@ -0,0 +1,167 @@
+.. -*- mode: rst -*-
+
+.. _development-lint:
+
+===============================
+ bcfg2-lint Plugin Development
+===============================
+
+``bcfg2-lint``, like most parts of Bcfg2, has a pluggable backend that
+lets you easily write your own plugins to verify various parts of your
+Bcfg2 specification.
+
+Plugins are loaded in one of two ways:
+
+* They may be included in a module of the same name as the plugin
+ class in :mod:`Bcfg2.Server.Lint`, e.g.,
+ :mod:`Bcfg2.Server.Lint.Validate`.
+* They may be included directly in a Bcfg2 server plugin, called
+ "<plugin>Lint", e.g.,
+ :class:`Bcfg2.Server.Plugins.Metadata.MetadataLint`.
+
+Plugin Types
+============
+
+There are two types of ``bcfg2-lint`` plugins:
+
+Serverless plugins
+------------------
+
+Serverless plugins are run before ``bcfg2-lint`` starts up a local
+Bcfg2 server, so the amount of introspection they can do is fairly
+limited. They can directly examine the Bcfg2 specification, of
+course, but they can't examine the entries handled by a given plugin
+or anything that requires a running server.
+
+If a serverless plugin raises a lint error, however, the server will
+not be started and no `Server plugins`_ will be run. This makes them
+useful to check for the sorts of errors that might prevent the Bcfg2
+server from starting properly.
+
+Serverless plugins must subclass
+:class:`Bcfg2.Server.Lint.ServerlessPlugin`.
+
+:mod:`Bcfg2.Server.Lint.Validate` is an example of a serverless
+plugin.
+
+Server plugins
+--------------
+
+Server plugins are run after a local Bcfg2 server has been started,
+and have full access to all of the parsed data and so on. Because of
+this, they tend to be easier to use than `Serverless plugins`_, and
+thus are more common.
+
+Server plugins are only run if all `Serverless plugins`_ run
+successfully (i.e., raise no errors).
+
+Server plugins must subclass :class:`Bcfg2.Server.Lint.ServerPlugin`.
+
+:mod:`Bcfg2.Server.Lint.Genshi` is an example of a server plugin.
+
+Error Handling
+==============
+
+The job of a ``bcfg2-lint`` plugin is to find errors. Each error that
+a plugin may produce must have a name, a short string that briefly
+describes the error and will be used to configure error levels in
+``bcfg2.conf``. It must also have a default reporting level.
+Possible reporting levels are "error", "warning", or "silent". All of
+the errors that may be produced by a plugin must be returned as a dict
+by :func:`Bcfg2.Server.Lint.Plugin.Errors`. For instance, consider
+:func:`Bcfg2.Server.Lint.InfoXML.InfoXML.Errors`:
+
+.. code-block:: python
+
+ @classmethod
+ def Errors(cls):
+ return {"no-infoxml": "warning",
+ "deprecated-info-file": "warning",
+ "paranoid-false": "warning",
+ "required-infoxml-attrs-missing": "error"}
+
+This means that the :class:`Bcfg2.Server.Lint.InfoXML.InfoXML` lint
+plugin can produce five lint errors, although four of them are just
+warnings by default.
+
+The errors returned by each plugin's ``Errors()`` method will be
+passed to :func:`Bcfg2.Server.Lint.ErrorHandler.RegisterErrors`, which
+will use that information and the information in the config file to
+determine how to display (or not display) each error to the end user.
+
+Errors are produced in a plugin with
+:func:`Bcfg2.Server.Lint.Plugin.LintError`, which takes two arguments:
+the name of the error, which must correspond to a key in the dict
+returned by :func:`Bcfg2.Server.Lint.Plugin.Errors`, and a freeform
+string that will be displayed to the end user. Note that the error
+name and its display are thus only tied together when the error is
+produced; that is, a single error (by name) can have two completely
+different outputs.
+
+Basics
+======
+
+.. automodule:: Bcfg2.Server.Lint
+
+Existing ``bcfg2-lint`` Plugins
+===============================
+
+BundlerLint
+-----------
+
+.. autoclass:: Bcfg2.Server.Plugins.Bundler.BundlerLint
+
+Comments
+--------
+
+.. automodule:: Bcfg2.Server.Lint.Comments
+
+Genshi
+------
+
+.. automodule:: Bcfg2.Server.Lint.Genshi
+
+GroupNames
+----------
+
+.. automodule:: Bcfg2.Server.Lint.GroupNames
+
+GroupPatternsLint
+-----------------
+
+.. autoclass:: Bcfg2.Server.Plugins.GroupPatterns.GroupPatternsLint
+
+InfoXML
+-------
+
+.. automodule:: Bcfg2.Server.Lint.InfoXML
+
+MergeFiles
+----------
+
+.. automodule:: Bcfg2.Server.Lint.MergeFiles
+
+MetadataLint
+------------
+
+.. autoclass:: Bcfg2.Server.Plugins.Metadata.MetadataLint
+
+PkgmgrLint
+----------
+
+.. autoclass:: Bcfg2.Server.Plugins.Pkgmgr.PkgmgrLint
+
+RequiredAttrs
+-------------
+
+.. automodule:: Bcfg2.Server.Lint.RequiredAttrs
+
+TemplateHelperLint
+------------------
+
+.. autoclass:: Bcfg2.Server.Plugins.TemplateHelper.TemplateHelperLint
+
+Validate
+--------
+
+.. automodule:: Bcfg2.Server.Lint.Validate
diff --git a/doc/server/plugins/connectors/grouplogic.txt b/doc/server/plugins/connectors/grouplogic.txt
index b9a5b00d6..abf425202 100644
--- a/doc/server/plugins/connectors/grouplogic.txt
+++ b/doc/server/plugins/connectors/grouplogic.txt
@@ -110,8 +110,8 @@ individually, there's a more elegant way to accomplish the same thing:
<GroupLogic xmlns:py="http://genshi.edgewall.org/">
<?python
-component = metadata.group_in_category("webapp-component")
-env = metadata.group_in_category("environment")
+ component = metadata.group_in_category("webapp-component")
+ env = metadata.group_in_category("environment")
?>
<py:if test="component and env">
<Group name="${component}-${env}"/>
diff --git a/doc/server/plugins/generators/packages.txt b/doc/server/plugins/generators/packages.txt
index 092cff1ae..a7cdfad2d 100644
--- a/doc/server/plugins/generators/packages.txt
+++ b/doc/server/plugins/generators/packages.txt
@@ -190,7 +190,8 @@ something like this:
<Group name="ubuntu-intrepid">
<Source type="apt"
url="http://us.archive.ubuntu.com/ubuntu"
- version="intrepid">
+ version="intrepid"
+ debsrc="true">
<Component>main</Component>
<Component>universe</Component>
<Arch>i386</Arch>
@@ -218,7 +219,7 @@ something like this:
.. warning:: You must regenerate the Packages cache when adding or
removing the recommended attribute (``bcfg2-admin xcmd
- Packages.Refresh``).
+ Packages.Refresh``).
.. [#f1] Bcfg2 will by default add **Essential** packages to the
client specification. You can disable this behavior by
diff --git a/doc/server/plugins/generators/rules.txt b/doc/server/plugins/generators/rules.txt
index ccde65eb0..a85cd3fc9 100644
--- a/doc/server/plugins/generators/rules.txt
+++ b/doc/server/plugins/generators/rules.txt
@@ -377,9 +377,9 @@ For example:
<POSIXUser name="daemon" home="/sbin" shell="/sbin/nologin"
gecos="daemon" uid="2" group="daemon">
- <MemberOf>lp</MemberOf>
- <MemberOf>adm</MemberOf>
- <MemberOf>bin</MemberOf>
+ <MemberOf group="lp"/>
+ <MemberOf group="adm"/>
+ <MemberOf group="bin/>
</POSIXUser>
The group specified will automatically be created if it does not
diff --git a/doc/server/plugins/grouping/grouppatterns.txt b/doc/server/plugins/grouping/grouppatterns.txt
index 39c632f82..44ffa5066 100644
--- a/doc/server/plugins/grouping/grouppatterns.txt
+++ b/doc/server/plugins/grouping/grouppatterns.txt
@@ -8,7 +8,7 @@ GroupPatterns
The GroupPatterns plugin is a connector that can assign clients
group membership pased on patterns in client hostnames. Two basic
-methods are supported:
+methods are supported:
- regular expressions (NamePatterns)
- ranges (NameRange)
@@ -20,7 +20,7 @@ Setup
=====
#. Enable the GroupPatterns plugin
-#. Create the GroupPatterns/config.xml file (similar to the example below).
+#. Create the ``GroupPatterns/config.xml`` file (similar to the example below).
#. Client groups will be augmented based on the specification
Pattern Types
@@ -52,7 +52,7 @@ Examples
</GroupPattern>
<GroupPattern>
<NamePattern>(.*)</NamePattern>
- <Group>group-$1'</Group>
+ <Group>group-$1</Group>
</GroupPattern>
<GroupPattern>
<NameRange>node[[1-32]]</NameRange>
@@ -82,15 +82,14 @@ GroupPatterns configuration:
<GroupPatterns>
<GroupPattern>
- <NamePattern>^x(\w[^\d|\.]+)\d*\..*</NamePattern>
+ <NamePattern>x(\w[^\d\.]+)\d*\.</NamePattern>
<Group>$1-server</Group>
</GroupPattern>
</GroupPatterns>
Regex explanation:
-#. !^x Match any hostname that begins with "x"
-#. (\w[!^\d|\.]+) followed by one or more word characters that are not a decimal digit or "." and save the string to $1
-#. \d* followed by 0 or more decimal digit(s)
-#. \..* followed by a "."
-#. .* followed by 1 or more of anything else.
+#. ``x`` Match any hostname that begins with "x"
+#. ``(\w[!^\d|\.]+)`` followed by one or more word characters that are not a decimal digit or "." and save the string to $1
+#. ``\d*`` followed by 0 or more decimal digit(s)
+#. ``\.`` followed by a literal "."