summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/appendix/guides/centos.txt18
-rw-r--r--doc/development/core.txt5
-rw-r--r--doc/development/lint.txt167
-rw-r--r--doc/development/plugins.txt2
-rw-r--r--doc/exts/xmlschema.py10
-rw-r--r--doc/help/troubleshooting.txt2
-rw-r--r--doc/installation/distributions.txt14
-rw-r--r--doc/server/configuration.txt37
-rw-r--r--doc/server/encryption.txt3
-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
-rw-r--r--doc/server/plugins/grouping/metadata.txt2
-rw-r--r--doc/server/snapshots/index.txt5
15 files changed, 234 insertions, 63 deletions
diff --git a/doc/appendix/guides/centos.txt b/doc/appendix/guides/centos.txt
index 5a2d1bed0..febdf5769 100644
--- a/doc/appendix/guides/centos.txt
+++ b/doc/appendix/guides/centos.txt
@@ -185,21 +185,15 @@ line of ``bcfg2.conf``. Then create Packages layout (as per
<Sources>
<!-- CentOS (5.4) sources -->
- <YUMSource>
- <Group>centos-5.4</Group>
- <RawURL>http://mrepo/centos5-x86_64/RPMS.os</RawURL>
+ <Source type="yum" rawurl="http://mrepo/centos5-x86_64/RPMS.os">
<Arch>x86_64</Arch>
- </YUMSource>
- <YUMSource>
- <Group>centos-5.4</Group>
- <RawURL>http://mrepo/centos5-x86_64/RPMS.updates</RawURL>
+ </Source>
+ <Source type="yum" rawurl="http://mrepo/centos5-x86_64/RPMS.updates">
<Arch>x86_64</Arch>
- </YUMSource>
- <YUMSource>
- <Group>centos-5.4</Group>
- <RawURL>http://mrepo/centos5-x86_64/RPMS.extras</RawURL>
+ </Source>
+ <Source type="yum" rawurl="http://mrepo/centos5-x86_64/RPMS.extras">
<Arch>x86_64</Arch>
- </YUMSource>
+ </Source>
</Sources>
Due to the :ref:`server-plugins-generators-packages-magic-groups`,
diff --git a/doc/development/core.txt b/doc/development/core.txt
index 3607533ea..886a5538b 100644
--- a/doc/development/core.txt
+++ b/doc/development/core.txt
@@ -71,6 +71,11 @@ XML-RPC Server
.. automodule:: Bcfg2.SSLServer
+Multiprocessing Core
+--------------------
+
+.. automodule:: Bcfg2.Server.MultiprocessingCore
+
CherryPy Core
-------------
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/development/plugins.txt b/doc/development/plugins.txt
index 593c2f83e..3f2a888ac 100644
--- a/doc/development/plugins.txt
+++ b/doc/development/plugins.txt
@@ -213,4 +213,4 @@ See Also
--------
* :ref:`development-compat`
-* :ref:`development-utils
+* :ref:`development-utils`
diff --git a/doc/exts/xmlschema.py b/doc/exts/xmlschema.py
index 24cbf2e2d..c26aed81e 100644
--- a/doc/exts/xmlschema.py
+++ b/doc/exts/xmlschema.py
@@ -115,6 +115,7 @@ class _XMLDirective(Directive):
def run(self):
name = self.arguments[0]
env = self.state.document.settings.env
+ reporter = self.state.memo.reporter
ns_name = self.options.get('namespace')
try:
ns_uri = env.xmlschema_namespaces[ns_name]
@@ -129,8 +130,9 @@ class _XMLDirective(Directive):
except KeyError:
pass
else:
- env.app.error("No XML %s %s found" %
- (" or ".join(self.types), name))
+ reporter.error("No XML %s %s found" %
+ (" or ".join(self.types), name))
+ return []
documentor = XMLDocumentor(entity, env, self.state, name=name,
ns_uri=ns_uri,
include=self.process_include(),
@@ -172,6 +174,7 @@ class XMLDocumentor(object):
self.include = include
self.options = options
self.app = self.env.app
+ self.reporter = self.state.memo.reporter
if name is None:
self.ns_uri = ns_uri
@@ -312,7 +315,8 @@ class XMLDocumentor(object):
rv.extend(doc.document_complexType())
return rv
else:
- self.app.error("Unknown element type %s" % fqtype)
+ self.reporter.error("Unknown element type %s" % fqtype)
+ return []
else:
rv = []
typespec = self.entity.xpath("xs:complexType", namespaces=NSMAP)[0]
diff --git a/doc/help/troubleshooting.txt b/doc/help/troubleshooting.txt
index aac831ae0..72fec4c63 100644
--- a/doc/help/troubleshooting.txt
+++ b/doc/help/troubleshooting.txt
@@ -54,7 +54,7 @@ the debug level individually on a given plugin, e.g.::
bcfg2-admin xcmd Probes.toggle_debug
Finally, the File Activity Monitor has its own analogue to these two
-methods, for setting the debug level of the FAM:
+methods, for setting the debug level of the FAM::
bcfg2-admin xcmd Inotify.toggle_debug
bcfg2-admin xcmd Inotify.set_debug false
diff --git a/doc/installation/distributions.txt b/doc/installation/distributions.txt
index 3dcfd7721..9db111682 100644
--- a/doc/installation/distributions.txt
+++ b/doc/installation/distributions.txt
@@ -66,19 +66,7 @@ This way is not recommended on production systems. Only for testing.
Gentoo
======
-Early in July 2008, Bcfg2 was added to the Gentoo portage tree. So far
-it's still keyworded for all architectures, but we are actively working
-to get it marked as stable.
-
-If you don't use portage to install Bcfg2, you'll want to make sure you
-have all the prerequisites installed first. For a server, you'll need:
-
-* ``app-admin/gamin`` or ``app-admin/fam``
-* ``dev-python/lxml``
-
-Clients will need at least:
-
-* ``app-portage/gentoolkit``
+Bcfg2 can be installed via portage.
OS X
====
diff --git a/doc/server/configuration.txt b/doc/server/configuration.txt
index 2c5879ff0..7892c2612 100644
--- a/doc/server/configuration.txt
+++ b/doc/server/configuration.txt
@@ -20,6 +20,9 @@ Bcfg2, although it has become easier in 1.3.0. The steps to do so are
described in three sections below: Common steps for all versions;
steps for older versions only; and steps for 1.3.0.
+Many of the steps below may have already been performed by your OS
+packages.
+
Common Steps
------------
@@ -131,7 +134,7 @@ is even invoked.
Restart ``bcfg2-server`` and you should see it running as non-root in
``ps`` output::
- % ps -ef | grep '[b]cfg2-server'
+ % ps -ef | grep '[b]cfg2-server'
1000 11581 1 0 07:55 ? 00:00:15 python usr/sbin/bcfg2-server -C /etc/bcfg2.conf -D /var/run/bcfg2-server/bcfg2-server.pid
Steps on Bcfg2 1.3.0
@@ -159,7 +162,7 @@ natively in 1.3. Simply add the following lines to ``bcfg2.conf``::
Restart ``bcfg2-server`` and you should see it running as non-root in
``ps`` output::
- % ps -ef | grep '[b]cfg2-server'
+ % ps -ef | grep '[b]cfg2-server'
1000 11581 1 0 07:55 ? 00:00:15 python usr/sbin/bcfg2-server -C /etc/bcfg2.conf -D /var/run/bcfg2-server/bcfg2-server.pid
.. _server-backends:
@@ -169,10 +172,11 @@ Server Backends
.. versionadded:: 1.3.0
-Bcfg2 supports two different server backends: a builtin server
-based on the Python SimpleXMLRPCServer object, and a server that uses
-CherryPy (http://www.cherrypy.org). Each one has advantages and
-disadvantages.
+Bcfg2 supports three different server backends: a builtin server based
+on the Python SimpleXMLRPCServer object; a server that uses CherryPy
+(http://www.cherrypy.org); and a version of the builtin server that
+uses the Python :mod:`multiprocessing` module. Each one has
+advantages and disadvantages.
The builtin server:
@@ -181,27 +185,36 @@ The builtin server:
* Works on Python 2.4;
* Is slow with larger numbers of clients.
+The multiprocessing server:
+
+* Leverages most of the stability and maturity of the builtin server,
+ but does have some new bits;
+* Introduces concurrent processing to Bcfg2, which may break in
+ various edge cases;
+* Supports certificate authentication;
+* Requires Python 2.6;
+* Is faster with large numbers of concurrent runs.
+
The CherryPy server:
* Is very new and potentially buggy;
* Does not support certificate authentication yet, only password
authentication;
-* Requires CherryPy 3.2, which requires Python 2.5;
+* Requires CherryPy 3.3, which requires Python 2.5;
* Is smarter about daemonization, particularly if you are
:ref:`server-dropping-privs`;
* Is faster with large numbers of clients.
Basically, the builtin server should be used unless you have a
-particular need for performance, and can sacrifice certificate
-authentication.
+particular need for performance. The CherryPy server is purely
+experimental at this point.
To select which backend to use, set the ``backend`` option in the
``[server]`` section of ``/etc/bcfg2.conf``. Options are:
* ``cherrypy``
* ``builtin``
+* ``multiprocessing``
* ``best`` (the default; currently the same as ``builtin``)
-If the certificate authentication issues (a limitation in CherryPy
-itself) can be resolved and the CherryPy server proves to be stable,
-it will likely become the default (and ``best``) in a future release.
+``best`` may change in future releases.
diff --git a/doc/server/encryption.txt b/doc/server/encryption.txt
index b56487620..e31124d4b 100644
--- a/doc/server/encryption.txt
+++ b/doc/server/encryption.txt
@@ -12,7 +12,8 @@ Bcfg2 supports encrypting some data on the disk, which can help
protect sensitive data from other people who need access to the Bcfg2
repository but are perhaps not authorized to see all data. It
supports multiple passphrases, which can be used to enforce
-separations between teams, environments, etc.
+separations between teams, environments, etc. Use of the encryption
+feature requires M2Crypto 0.18 or newer.
.. note::
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 606e1e128..cdc4f7282 100644
--- a/doc/server/plugins/generators/packages.txt
+++ b/doc/server/plugins/generators/packages.txt
@@ -252,7 +252,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>
@@ -280,7 +281,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 845006115..2493be53f 100644
--- a/doc/server/plugins/generators/rules.txt
+++ b/doc/server/plugins/generators/rules.txt
@@ -395,9 +395,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 "."
diff --git a/doc/server/plugins/grouping/metadata.txt b/doc/server/plugins/grouping/metadata.txt
index 32834b458..ceac5dc24 100644
--- a/doc/server/plugins/grouping/metadata.txt
+++ b/doc/server/plugins/grouping/metadata.txt
@@ -222,7 +222,7 @@ to include a different file, or explicit content in the case that the
parent include does not exist.)
Wildcard XInclude
-~~~~~~~~~~~~~~~~~
+-----------------
.. versionadded:: 1.3.1
diff --git a/doc/server/snapshots/index.txt b/doc/server/snapshots/index.txt
index 13a9fe2c0..a7e5940ed 100644
--- a/doc/server/snapshots/index.txt
+++ b/doc/server/snapshots/index.txt
@@ -8,9 +8,8 @@ Bcfg2 Snapshots
.. versionadded:: 1.0.0
-This page describes the Snapshots plugin. This plugin is meant to replace
-the older :ref:`reports-dynamic`. It stores various aspects of a client's
-state when the client checks into the server.
+This page describes the Snapshots plugin. Snapshots is deprecated, and
+will be removed in a future release.
Before you begin
================
generated by cgit v1.2.3-1-g7c22 (git 2.25.1) at 2024-07-22 05:04:51 +0000