diff options
Diffstat (limited to 'doc')
24 files changed, 484 insertions, 159 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/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/compat.txt b/doc/development/compat.txt index 90df45676..f90274ce5 100644 --- a/doc/development/compat.txt +++ b/doc/development/compat.txt @@ -100,6 +100,8 @@ behavior (e.g., :func:`input`) do not cause unexpected side-effects. +---------------------------------+--------------------------------------------------+---------------------------------------------------------+ | long | :func:`long` | :func:`int` | +---------------------------------+--------------------------------------------------+---------------------------------------------------------+ +| cmp | :func:`cmp` | Not implemented | ++---------------------------------+--------------------------------------------------+---------------------------------------------------------+ Python 2.4 compatibility ------------------------ 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/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/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/reports/dynamic.txt b/doc/reports/dynamic.txt index b3028e9e1..6b8a1f467 100644 --- a/doc/reports/dynamic.txt +++ b/doc/reports/dynamic.txt @@ -39,7 +39,7 @@ Prerequisites * sqlite3 * pysqlite2 (if using python 2.4) -* `Django <http://www.djangoproject.com>`_ >= 1.2 +* `Django <http://www.djangoproject.com>`_ >= 1.3 * mod-wsgi .. warning:: @@ -53,40 +53,41 @@ Prerequisites Install ------- -Be sure to include the specified fields included in the example -``bcfg2.conf`` file. These can be specified in either ``/etc/bcfg2.conf``, -if it is readable by the webserver user, or ``/etc/bcfg2-web.conf``. Any -database supported by `Django <http://www.djangoproject.com>`_ can be used. -As of version 1.3, `South <http://south.aeracode.org>`_ is used to control -schema changes. If your database is not supported by South, any updates -will need to be applied manually. Sqlite is configured by default. -Please see the :ref:`reporting-databases` section to configure alternative -databases. -.. warning:: +1. Be sure to include the specified fields included in the example + ``bcfg2.conf`` file. These can be specified in either + ``/etc/bcfg2.conf``, if it is readable by the webserver user, + or ``/etc/bcfg2-web.conf``. Any database supported by `Django + <http://www.djangoproject.com>`_ can be used. As of version 1.3, + `South <http://south.aeracode.org>`_ is used to control schema changes. + If your database is not supported by South, any updates will need to + be applied manually. Sqlite is configured by default. Please see the + :ref:`reporting-databases` section to configure alternative databases. - If you are using an sqlite database, the directory containing the - database file will need to be writable by the web server. The reason - for this is that sqlite will create another file for its journal - when it tries to update the database file. + .. warning:: -.. note:: + If you are using an sqlite database, the directory containing the + database file will need to be writable by the web server. The reason + for this is that sqlite will create another file for its journal + when it tries to update the database file. + + .. note:: - Distributed environments can share a single remote database for - reporting. + Distributed environments can share a single remote database for + reporting. -After configuring your database be sure to run `bcfg2-admin reports init` -to create the schema. +2. After configuring your database be sure to run ``bcfg2-admin reports + init`` to create the schema. -To enable statistics collection in the bcfg2-server, add -:ref:`server-plugins-statistics-reporting` to the **plugins** -line in your ``bcfg2.conf`` and restart the bcfg2-server. A report collecting -daemon should be run to import the collected statistics into the backend. -Please see the section :ref:`Report Collector <report_collector>` for more -information. +3. To enable statistics collection in the bcfg2-server, add + :ref:`server-plugins-statistics-reporting` to the **plugins** + line in your ``bcfg2.conf`` and restart the bcfg2-server. A report + collecting daemon should be run to import the collected statistics + into the backend. Please see the section :ref:`Report Collector + <report_collector>` for more information. -Detailed installation instructions can be found :ref:`here -<appendix-guides-web-reports-install>`. + Detailed installation instructions can be found :ref:`here + <appendix-guides-web-reports-install>`. .. _dynamic-http-install: @@ -175,7 +176,7 @@ Upgrading .. note:: After the database is upgraded all of the old tables are left - intact. To remove them any table starting with reports_ can + intact. To remove them any table starting with **reports\_** can be dropped. 4. `(Optional)` Run the :ref:`Report Collector <report_collector>` @@ -199,11 +200,6 @@ An example using the defaults is listed below:: host = port = - [statistics] - config = /etc/bcfg2-web.conf - time_zone = - web_debug = False - [reporting] transport = DirectStore web_prefix = @@ -241,6 +237,8 @@ section: statistics ^^^^^^^^^^ +.. deprecated: 1.3.0 + * config: The config file to be read for additional reporting data. This is used to restrict what can be read by the web server. 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/database.txt b/doc/server/database.txt index 87d3e3afe..b0ec7b571 100644 --- a/doc/server/database.txt +++ b/doc/server/database.txt @@ -34,9 +34,10 @@ of ``/etc/bcfg2.conf``. +-------------+------------------------------------------------------------+-------------------------------+ | Option name | Description | Default | +=============+============================================================+===============================+ -| engine | The full name of the Django database backend to use. See | "django.db.backends.sqlite3" | +| engine | The name of the Django database backend to use. See | "sqlite3" | | | https://docs.djangoproject.com/en/dev/ref/settings/#engine | | -| | for available options | | +| | for available options (note that django.db.backends is not | | +| | included in the engine name) | | +-------------+------------------------------------------------------------+-------------------------------+ | name | The name of the database | "/var/lib/bcfg2/bcfg2.sqlite" | +-------------+------------------------------------------------------------+-------------------------------+ 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 new file mode 100644 index 000000000..abf425202 --- /dev/null +++ b/doc/server/plugins/connectors/grouplogic.txt @@ -0,0 +1,122 @@ +.. -*- mode: rst -*- + +.. _server-plugins-connectors-grouplogic: + +========== +GroupLogic +========== + +.. versionadded:: 1.3.2 + +GroupLogic is a connector plugin that lets you use an XML Genshi +template to dynamically set additional groups for clients. + +Usage +===== + +To use the GroupLogic plugin, first do ``mkdir +/var/lib/bcfg2/GroupLogic``. Add ``GroupLogic`` to your ``plugins`` +line in ``/etc/bcfg2.conf``. Next, create +``/var/lib/bcfg2/GroupLogic/groups.xml``: + +.. code-block:: xml + + <GroupLogic xmlns:py="http://genshi.edgewall.org/"> + </GroupLogic> + +``groups.xml`` is structured very similarly to the +:ref:`server-plugins-grouping-metadata` ``groups.xml``. A Group tag +that contains no children is a declaration of membership; a Group or +Client tag that does contain children is a conditional. + +Unlike ``Metadata/groups.xml``, GroupLogic supports genshi templating, +so you can dynamically create groups. ``GroupLogic/groups.xml`` is +rendered for each client, and the groups set in it are added to the +client metadata. + +.. note:: + + Also unlike ``Metadata/groups.xml``, GroupLogic can not be used to + associate bundles with clients directly, or to negate groups. But + you can use GroupLogic to assign a group that is associated with a + bundle in Metadata. + +Consider the case where you have four environments -- dev, test, +staging, and production -- and four components to a web application -- +the frontend, the API, the database server, and the caching proxy. In +order to make files specific to the component *and* to the +environment, you need groups to describe each combination: +webapp-frontend-dev, webapp-frontend-test, and so on. You *could* do +this in ``Metadata/groups.xml``: + +.. code-block:: xml + + <Groups> + <Group name="webapp-frontend"> + <Group name="dev"> + <Group name="webapp-frontend-dev"/> + </Group> + <Group name="test"> + <Group name="webapp-frontend-test"/> + </Group> + ... + </Group> + <Group name="webapp-api"> + ... + </Group> + ... + </Groups> + +Creating the sixteen groups this way is incredibly tedious, and this +is a quite *small* site. GroupLogic can automate this process. + +Assume that we've declared the groups thusly in +``Metadata/groups.xml``: + +.. code-block:: xml + + <Groups> + <Group name="webapp-frontend" category="webapp-component"/> + <Group name="webapp-api" category="webapp-component"/> + <Group name="webapp-db" category="webapp-component"/> + <Group name="webapp-proxy" category="webapp-component"/> + <Group name="dev" category="environment"/> + <Group name="test" category="environment"/> + <Group name="staging" category="environment"/> + <Group name="prod" category="environment"/> + </Groups> + +One way to automate the creation of the groups would be to simply +generate the tedious config: + +.. code-block:: xml + + <GroupLogic xmlns:py="http://genshi.edgewall.org/"> + <py:for each="component in metadata.query.all_groups_in_category("webapp-component")> + <Group name="${component}"> + <py:for each="env in metadata.query.all_groups_in_category("environment")> + <Group name="${env}"> + <Group name="${component}-${env}"/> + </Group> + </py:for> + </Group> + </py:for> + </GroupLogic> + +But, since ``GroupLogic/groups.xml`` is rendered for each client +individually, there's a more elegant way to accomplish the same thing: + +.. code-block:: xml + + <GroupLogic xmlns:py="http://genshi.edgewall.org/"> + <?python + component = metadata.group_in_category("webapp-component") + env = metadata.group_in_category("environment") + ?> + <py:if test="component and env"> + <Group name="${component}-${env}"/> + </py:if> + </GroupLogic> + +This gets only the component and environment for the current client, +and, if both are set, sets the single appropriate group. diff --git a/doc/server/plugins/generators/cfg.txt b/doc/server/plugins/generators/cfg.txt index f31923866..e3768a3ba 100644 --- a/doc/server/plugins/generators/cfg.txt +++ b/doc/server/plugins/generators/cfg.txt @@ -596,6 +596,11 @@ Deltas cat file functionality. ``bcfg2-lint`` checks for deltas and warns about them. +.. warning:: + + In Bcfg2 1.3, deltas **do not** work with `SSH key or + authorized_keys generation <SSH Keys>`_. + Bcfg2 has finer grained control over how to deliver configuration files to a host. Let's say we have a Group named file-server. Members of this group need the exact same ``/etc/motd`` as all other hosts except @@ -632,23 +637,35 @@ server and we have the following configuration files:: motd.G01_web-server motd.G01_mail-server.cat motd.G02_file-server.cat + motd.H_bar.example.com motd.H_foo.example.com.cat -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: - -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.H_foo.example.com.cat`` delta to the ``motd.G01_web-server`` base -file. The reason the other deltas aren't applied to *foo.example.com* -is because a **.H_** delta is more specific than a **.G##_** delta. Bcfg2 -applies all the deltas at the most specific level. +If our machine isn't *foo.example.com* or *bar.example.com*, but +is a web server, then 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* and a web server, then 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.H_foo.example.com.cat`` delta to the ``motd.G01_web-server`` +base file. The reason the other deltas aren't applied to +*foo.example.com* is because a **.H_** delta is more specific than a +**.G##_** delta. Bcfg2 applies all the deltas at the most specific +level. + +If our machine is *bar.example.com*, then Bcfg2 would chose +``motd.H_foo.example.com`` as the base file because it is the most +specific base file for this host. Regardless of the groups +*bar.example.com* is a member of, **no cat files** would be applied, +because only cat files as specific or more specific than the base file +are applied. (In other words, if a group-specific base file is +selected, only group- or host-specific cat files can be applied; if a +host-specific base file is selected, only host-specific cat files can +be applied.) .. _server-plugins-generators-cfg-validation: diff --git a/doc/server/plugins/generators/packages.txt b/doc/server/plugins/generators/packages.txt index 73145fd6b..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 @@ -434,7 +435,7 @@ configs. Simply add entries like these to the appropriate bundles: .. code-block:: xml <Path name="/etc/yum.repos.d/bcfg2.repo"/> - <Path name="/etc/apt/sources.d/bcfg2"/> + <Path name="/etc/apt/sources.list.d/bcfg2-packages-generated-sources.list"/> If you want to change the path to either of those files, you can set ``yum_config`` or ``apt_config`` in ``bcfg2.conf`` to the path to the @@ -702,25 +703,25 @@ It understands the following directives: [packages] section ------------------ -+-------------+------------------------------------------------------+----------+-----------------------------+ -| Name | Description | Values | Default | -+=============+======================================================+==========+=============================+ -| resolver | Enable dependency resolution | Boolean | True | -+-------------+------------------------------------------------------+----------+-----------------------------+ -| metadata | Enable metadata processing. Disabling ``metadata`` | Boolean | True | -| | implies disabling ``resolver`` as well. | | | -+-------------+------------------------------------------------------+----------+-----------------------------+ -| yum_config | The path at which to generate Yum configs. | String | /etc/yum.repos.d/bcfg2.repo | -+-------------+------------------------------------------------------+----------+-----------------------------+ -| apt_config | The path at which to generate APT configs. | String | /etc/apt/sources.d/bcfg2 | -+-------------+------------------------------------------------------+----------+-----------------------------+ -| gpg_keypath | The path on the client RPM GPG keys will be copied | String | /etc/pki/rpm-gpg | -| | to before they are imported on the client. | | | -+-------------+------------------------------------------------------+----------+-----------------------------+ -| version | Set the version attribute used when binding Packages | any|auto | auto | -+-------------+------------------------------------------------------+----------+-----------------------------+ -| cache | Path where Packages will store its cache | String | <repo>/Packages/cache | -+-------------+------------------------------------------------------+----------+-----------------------------+ ++-------------+------------------------------------------------------+----------+-------------------------------------------------------------------+ +| Name | Description | Values | Default | ++=============+======================================================+==========+===================================================================+ +| resolver | Enable dependency resolution | Boolean | True | ++-------------+------------------------------------------------------+----------+-------------------------------------------------------------------+ +| metadata | Enable metadata processing. Disabling ``metadata`` | Boolean | True | +| | implies disabling ``resolver`` as well. | | | ++-------------+------------------------------------------------------+----------+-------------------------------------------------------------------+ +| yum_config | The path at which to generate Yum configs. | String | /etc/yum.repos.d/bcfg2.repo | ++-------------+------------------------------------------------------+----------+-------------------------------------------------------------------+ +| apt_config | The path at which to generate APT configs. | String | /etc/apt/sources.list.d/bcfg2-packages-generated-sources.list | ++-------------+------------------------------------------------------+----------+-------------------------------------------------------------------+ +| gpg_keypath | The path on the client RPM GPG keys will be copied | String | /etc/pki/rpm-gpg | +| | to before they are imported on the client. | | | ++-------------+------------------------------------------------------+----------+-------------------------------------------------------------------+ +| version | Set the version attribute used when binding Packages | any|auto | auto | ++-------------+------------------------------------------------------+----------+-------------------------------------------------------------------+ +| cache | Path where Packages will store its cache | String | <repo>/Packages/cache | ++-------------+------------------------------------------------------+----------+-------------------------------------------------------------------+ [packages:yum] section diff --git a/doc/server/plugins/generators/rules.txt b/doc/server/plugins/generators/rules.txt index 2789411e7..2493be53f 100644 --- a/doc/server/plugins/generators/rules.txt +++ b/doc/server/plugins/generators/rules.txt @@ -117,8 +117,13 @@ describe the attributes available for various Path types. Note that ``secontext`` below expects a full context, not just the type. For instance, "``system_u:object_r:etc_t:s0``", not just ``etc_t``. You can also specify "``__default__``", which will restore -the context of the file to the default set by policy. See -:ref:`server-selinux` for more information. +the context of the file to the default set by policy. If a file has +no default context rule, and you don't wish to set one, you can +specify ``secontext=''`` (i.e., an empty ``secontext``), in which case +the client will not try to manage the SELinux context of the file at +all. + +See :ref:`server-selinux` for more information. Attributes common to all Path tags: @@ -390,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/generators/sslca.txt b/doc/server/plugins/generators/sslca.txt index cab7eb233..7ef358a31 100644 --- a/doc/server/plugins/generators/sslca.txt +++ b/doc/server/plugins/generators/sslca.txt @@ -156,7 +156,7 @@ Example .. code-block:: xml <CertInfo> - <SubjectAltName>test.example.com</SubjectAltName> + <subjectAltName>test.example.com</subjectAltName> <Group name="apache"> <Cert key="/etc/pki/tls/private/foo.key" days="730"/> </Group> diff --git a/doc/server/plugins/generators/tcheetah.txt b/doc/server/plugins/generators/tcheetah.txt index ab147ce56..c79a8ced5 100644 --- a/doc/server/plugins/generators/tcheetah.txt +++ b/doc/server/plugins/generators/tcheetah.txt @@ -99,7 +99,7 @@ Simple Example ============== TCheetah works similar to Cfg in that you define all literal information -about a particular file in a directory rooted at TGenshi/path_to_file. +about a particular file in a directory rooted at TCheetah/path_to_file. The actual file contents are placed in a file named `template` in that directory. Below is a simple example a file ``/foo``. 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 fe0d2683e..ceac5dc24 100644 --- a/doc/server/plugins/grouping/metadata.txt +++ b/doc/server/plugins/grouping/metadata.txt @@ -119,20 +119,19 @@ a simple ``groups.xml`` file: <Group name='oracle-server'> <Group name='selinux-enabled' negate='true'/> </Group> - <Client name='foo.eample.com'> + <Client name='foo.example.com'> <Group name='oracle-server'/> <Group name='apache-server'/> </Client> </Groups> -A Group or Client tag that does not contain any child tags is a -declaration of membership; a Group or Client tag that does contain -children is a conditional. So the example above does not assign -either the ``rhel5`` or ``rhel6`` groups to machines in the -``mail-server`` group, but conditionally assigns the -``sendmail-server`` or ``postfix-server`` groups depending on the OS -of the client. (Presumably in this example the OS groups are set by a -probe.) +A Group tag that does not contain any child tags is a declaration of +membership; a Group or Client tag that does contain children is a +conditional. So the example above does not assign either the +``rhel5`` or ``rhel6`` groups to machines in the ``mail-server`` +group, but conditionally assigns the ``sendmail-server`` or +``postfix-server`` groups depending on the OS of the client. +(Presumably in this example the OS groups are set by a probe.) Consequently, a client that is RHEL 5 and a member of the ``mail-server`` profile group would also be a member of the @@ -223,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/selinux.txt b/doc/server/selinux.txt index 9f54b0d68..79384970a 100644 --- a/doc/server/selinux.txt +++ b/doc/server/selinux.txt @@ -142,13 +142,13 @@ necessary. Duplicate Entries ----------------- -It may be necessary to use `BoundSELinux` tags if a single fcontext +It may be necessary to use `BoundSEFcontext` tags if a single fcontext needs two different SELinux types depending on whether it's a symlink or a plain file. For instance: .. code-block:: xml - <BoundSELinux type="fcontext" filetype="symlink" - name="/etc/localtime" selinuxtype="etc_t"/> - <BoundSELinux type="fcontext" filetype="regular" - name="/etc/localtime" selinuxtype="locale_t"/> + <BoundSEFcontext filetype="symlink" + name="/etc/localtime" selinuxtype="etc_t"/> + <BoundSEFcontext filetype="regular" + name="/etc/localtime" selinuxtype="locale_t"/> 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 ================ |