From 65caf3f586d7985d88652c73e7b214ba3e40eac2 Mon Sep 17 00:00:00 2001 From: "Chris St. Pierre" Date: Wed, 6 Feb 2013 16:47:44 -0500 Subject: documented which XML files have which features --- doc/development/cfg.txt | 1 - doc/server/encryption.txt | 5 + doc/server/genshi-xml.txt | 24 --- doc/server/index.txt | 2 +- doc/server/plugins/connectors/properties.txt | 48 +----- doc/server/plugins/grouping/metadata.txt | 34 +--- doc/server/plugins/probes/fileprobes.txt | 2 + doc/server/plugins/structures/bundler/index.txt | 34 +--- doc/server/xml-common.txt | 199 ++++++++++++++++++++++++ 9 files changed, 218 insertions(+), 131 deletions(-) delete mode 100644 doc/server/genshi-xml.txt create mode 100644 doc/server/xml-common.txt (limited to 'doc') diff --git a/doc/development/cfg.txt b/doc/development/cfg.txt index 71c455b52..a4360559f 100644 --- a/doc/development/cfg.txt +++ b/doc/development/cfg.txt @@ -97,6 +97,5 @@ Other Cfg Objects These other objects comprise the remainder of the Cfg plugin, and are included for completeness. -.. autoattribute:: Bcfg2.Server.Plugins.Cfg.DEFAULT_INFO .. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgEntrySet .. autoclass:: Bcfg2.Server.Plugins.Cfg.Cfg diff --git a/doc/server/encryption.txt b/doc/server/encryption.txt index 09b1ea183..a701a42ca 100644 --- a/doc/server/encryption.txt +++ b/doc/server/encryption.txt @@ -210,6 +210,8 @@ get a list of valid algorithms, you can run:: openssl list-cipher-algorithms | grep -v ' => ' | \ tr 'A-Z-' 'a-z_' | sort -u +.. _server-encryption-lax-strict: + Lax vs. Strict decryption ------------------------- @@ -230,6 +232,9 @@ This can be overridden by individual XML files by setting ``decrypt="strict"`` on the top-level tag (or, vice-versa; if strict is the default an XML file can specify ``decrypt="lax"``. +Note that you could, for instance, set lax decryption by default, and +then set strict decryption on individual files. + Encryption API ============== diff --git a/doc/server/genshi-xml.txt b/doc/server/genshi-xml.txt deleted file mode 100644 index 3216cc00d..000000000 --- a/doc/server/genshi-xml.txt +++ /dev/null @@ -1,24 +0,0 @@ -.. -*- mode: rst -*- - -.. _xml-genshi-reference: - -=============================== - Genshi XML Template Reference -=============================== - -Genshi's XML templating language is used in -:ref:`server-plugins-structures-bundler-index` for templated bundles. -The language is described in depth at `Genshi -`_. The XML schema reference follows. - -Genshi Tags -=========== - -.. xml:group:: genshiElements - :namespace: py - -Genshi Attributes -================= - -.. xml:attributegroup:: genshiAttrs - :namespace: py diff --git a/doc/server/index.txt b/doc/server/index.txt index 42abb454c..71431b2a8 100644 --- a/doc/server/index.txt +++ b/doc/server/index.txt @@ -32,4 +32,4 @@ clients. database caching encryption - genshi-xml + xml-common diff --git a/doc/server/plugins/connectors/properties.txt b/doc/server/plugins/connectors/properties.txt index da511736d..6e53de216 100644 --- a/doc/server/plugins/connectors/properties.txt +++ b/doc/server/plugins/connectors/properties.txt @@ -120,6 +120,8 @@ in ``bcfg2.conf``:: [properties] writes_enabled = false +.. _server-plugins-connectors-properties-xml: + XML Property Files ------------------ @@ -262,47 +264,13 @@ Encrypted Properties data .. versionadded:: 1.3.0 You can encrypt selected data in XML Properties files to protect that -data from other people who need access to the repository. See -:ref:`server-encryption-configuration` for details on configuring -encryption passphrases. The data is decrypted transparently -on-the-fly by the server; you never need to decrypt the data in your -templates. Encryption is only supported on XML properties files. - -.. note:: - - This feature is *not* intended to secure the files against a - malicious attacker who has gained access to your Bcfg2 server, as - the encryption passphrases are held in plaintext in - ``bcfg2.conf``. This is only intended to make it easier to use a - single Bcfg2 repository with multiple admins who should not - necessarily have access to each other's sensitive data. - -Properties files are encrypted on a per-element basis; that is, rather -than encrypting the whole file, only the character content of -individual elements is encrypted. This makes it easier to track -changes to the file in a VCS, and also lets unprivileged users work -with the other data in the file. Only character content of an element -can be encrypted; attribute content and XML elements themselves cannot -be encrypted. - -By default, decryption is *strict*; that is, if any element cannot be -decrypted, parsing of the file is aborted. If you wish for parsing to -continue, with unencryptable elements simply skipped, then you can set -decryption to *lax* in one of two ways: - -* Set ``decrypt=lax`` in the ``[encryption]`` section of - ``bcfg2.conf`` to set lax decryption on all files by default; or -* Set the ``decrypt="lax"`` attribute on the top-level ``Properties`` - tag of a Properties file to set lax decryption for a single file. - -Note that you could, for instance, set lax decryption by default, and -then set strict decryption on individual files. - -To encrypt or decrypt a file, use :ref:`bcfg2-crypt`. - -See :ref:`server-encryption` for more details on encryption in Bcfg2 -in general. +data from other people who need access to the repository. The +data is decrypted transparently on-the-fly by the server; you never +need to decrypt the data in your templates. Encryption is only +supported on XML properties files. +See :ref:`server-encryption` for details on encryption in general, and +:ref:`xml-encryption` for details on encryption in XML files. Accessing Properties contents from Genshi Templates =================================================== diff --git a/doc/server/plugins/grouping/metadata.txt b/doc/server/plugins/grouping/metadata.txt index a6ed37f8e..7fcc83d4c 100644 --- a/doc/server/plugins/grouping/metadata.txt +++ b/doc/server/plugins/grouping/metadata.txt @@ -90,6 +90,8 @@ Database Settings `. The `clients.xml`_-based model remains the default. +.. _server-plugins-grouping-metadata-groups-xml: + groups.xml ========== @@ -181,38 +183,6 @@ groups: .. xml:schema:: metadata.xsd - -XInclude -======== - -.. versionadded:: 0.9.0 - -`XInclude `_ is a W3C specification -for the inclusion of external XML documents into XML source files, -allowing complex definitions to be split into smaller, more manageable -pieces. The `Metadata`_ plugin supports the use of XInclude -specifications to split the `clients.xml`_ and `groups.xml`_ -files. This mechanism allows the following specification to produce -useful results: - -.. code-block:: xml - - - - - - -Each of the included groups files has the same format. These files are -properly validated by ``bcfg2-lint``. This mechanism is useful for -composing group definitions from multiple sources, or setting -different permissions in an svn repository. - -Probes -====== - -The metadata plugin includes client-side probing functionality. This -is fully documented :ref:`here `. - Metadata Caching ================ diff --git a/doc/server/plugins/probes/fileprobes.txt b/doc/server/plugins/probes/fileprobes.txt index 0baec2c59..1bee38c5a 100644 --- a/doc/server/plugins/probes/fileprobes.txt +++ b/doc/server/plugins/probes/fileprobes.txt @@ -1,3 +1,5 @@ +.. -*- mode: rst -*- + .. _server-plugins-probes-fileprobes: ========== diff --git a/doc/server/plugins/structures/bundler/index.txt b/doc/server/plugins/structures/bundler/index.txt index f6ed1357d..67d8963a9 100644 --- a/doc/server/plugins/structures/bundler/index.txt +++ b/doc/server/plugins/structures/bundler/index.txt @@ -123,39 +123,7 @@ generate a bundle. Genshi templates can be specified one of two ways: 2. Add the Genshi namespace to your existing XML bundle. -The top-level Bundle tag should look like the following:: - - - -Several variables are pre-defined inside templates: - -+-------------+--------------------------------------------------------+ -| Name | Description | -+=============+========================================================+ -| metadata | :ref:`Client metadata | -| | ` | -+-------------+--------------------------------------------------------+ -| repo | The path to the Bcfg2 repository on the filesystem | -+-------------+--------------------------------------------------------+ - -.. note:: - - ```` and ```` tags are allowed inside of Genshi - templates as of Bcfg2 1.2. However, they do not behave the same - as using a Genshi conditional, e.g.:: - - - - - The conditional is evaluated when the template is rendered, so - code inside the conditional is not executed if the conditional - fails. A ```` tag is evaluated *after* the template is - rendered, so code inside the tag is always executed. This is an - important distinction: if you have code that will fail on some - groups, you *must* use a Genshi conditional, not a ```` - tag. The same caveats apply to ```` tags. - -See also the :ref:`xml-genshi-reference`. +See :ref:`xml-genshi-templating` for details. Troubleshooting --------------- diff --git a/doc/server/xml-common.txt b/doc/server/xml-common.txt new file mode 100644 index 000000000..44205ed42 --- /dev/null +++ b/doc/server/xml-common.txt @@ -0,0 +1,199 @@ +.. -*- mode: rst -*- + +.. _xml-features: + +===================== + Common XML Features +===================== + +Most of the XML files in Bcfg2 have a common set of features that are +supported. These are described in some detail below, and a precise +rundown of which features are supported by which files is provided. + +.. _xml-group-client-tags: + +Group and Client tags +===================== + +These allow the portions of an XML document inside a Client or Group +tag to only apply to the given client group. See +:ref:`server-plugins-structures-bundler-index` for examples and more +details. + +.. _xml-genshi-templating: + +Genshi templating +================= + +Genshi XML templates allow you to use the `Genshi +`_ templating system to dynamically +generate XML file content for a given client. Genshi templating can +be enabled on a file by adding the Genshi namespace to the top-level +tag, e.g.: + +.. code-block:: xml + + + +Several variables are pre-defined inside Genshi XML templates: + ++-------------+--------------------------------------------------------+ +| Name | Description | ++=============+========================================================+ +| metadata | :ref:`Client metadata | +| | ` | ++-------------+--------------------------------------------------------+ +| repo | The path to the Bcfg2 repository on the filesystem | ++-------------+--------------------------------------------------------+ + +.. note:: + + ```` and ```` tags can be used inside templates as + of Bcfg2 1.2, but they do not behave the same as using a Genshi + conditional, e.g.:: + + + + + The conditional is evaluated when the template is rendered, so + code inside the conditional is not executed if the conditional + fails. A ```` tag is evaluated *after* the template is + rendered, so code inside the tag is always executed. This is an + important distinction: if you have code that will fail on some + groups, you *must* use a Genshi conditional, not a ```` + tag. The same caveats apply to ```` tags. + +.. _xml-genshi-reference: + +Genshi XML Template Reference +----------------------------- + +The Genshi XML templating language is described in depth at `Genshi +`_. The XML schema reference follows. + +Genshi Tags +~~~~~~~~~~~ + +.. xml:group:: genshiElements + :namespace: py + +Genshi Attributes +~~~~~~~~~~~~~~~~~ + +.. xml:attributegroup:: genshiAttrs + :namespace: py + +.. _xml-encryption: + +Encryption +========== + +You can encrypt data in XML files to protect that data from other +people who need access to the repository. The data is decrypted +transparently on-the-fly by the server. + +.. note:: + + This feature is *not* intended to secure the files against a + malicious attacker who has gained access to your Bcfg2 server, as + the encryption passphrases are held in plaintext in + ``bcfg2.conf``. This is only intended to make it easier to use a + single Bcfg2 repository with multiple admins who should not + necessarily have access to each other's sensitive data. + +XML files are encrypted on a per-element basis; that is, rather than +encrypting the whole file, only the character content of individual +elements is encrypted. This makes it easier to track changes to the +file in a VCS, and also lets unprivileged users work with the other +data in the file. Only character content of an element can be +encrypted; attribute content and XML elements themselves cannot be +encrypted. + +By default, decryption is *strict*; that is, if any element cannot be +decrypted, parsing of the file is aborted. See +:ref:`server-encryption-lax-strict` for information on changing this +on a global or per-file basis. + +To encrypt or decrypt a file, use :ref:`bcfg2-crypt`. + +See :ref:`server-encryption` for more details on encryption in Bcfg2 +in general. + +XInclude +======== + +.. versionadded:: 0.9.0 + +`XInclude `_ is a W3C specification +for the inclusion of external XML documents into XML source files, +allowing complex definitions to be split into smaller, more manageable +pieces. For instance, in the :ref:`server-plugins-grouping-metadata` +``groups.xml`` file, you might do: + +.. code-block:: xml + + + + + + +To enable XInclude on a file, you need only add the XInclude namespace +to the top-level tag. + +XInclude can only include whole, well-formed XML files. In many +cases, if a file type does not support XInclude it is because the XML +schema lacks support. + +Feature Matrix +============== + ++--------------------------------------------------------------+--------------+--------+------------+----------+ +| File | Group/Client | Genshi | Encryption | XInclude | ++==============================================================+==============+========+============+==========+ +| :ref:`Bundles ` | Yes | Yes | Yes | Yes | ++--------------------------------------------------------------+--------------+--------+------------+----------+ +| :ref:`info.xml ` | Yes [#f1]_ | Yes | No | No | ++--------------------------------------------------------------+--------------+--------+------------+----------+ +| :ref:`authorizedkeys.xml, privkey.xml, and pubkey.xml | Yes | Yes | Yes | No | +| ` | | | | | ++--------------------------------------------------------------+--------------+--------+------------+----------+ +| :ref:`Decisions ` | Yes | Yes | Yes | Yes | ++--------------------------------------------------------------+--------------+--------+------------+----------+ +| :ref:`Defaults ` | Yes | Yes | Yes | Yes | ++--------------------------------------------------------------+--------------+--------+------------+----------+ +| :ref:`FileProbes ` | Yes | Yes | No | Yes | ++--------------------------------------------------------------+--------------+--------+------------+----------+ +| :ref:`GroupPatterns ` | No | No | No | Yes | ++--------------------------------------------------------------+--------------+--------+------------+----------+ +| :ref:`Metadata clients.xml | No | No | No | Yes | +| ` | | | | | ++--------------------------------------------------------------+--------------+--------+------------+----------+ +| :ref:`Metadata clients.xml | Yes [#f2]_ | No | No | Yes | +| ` | | | | | ++--------------------------------------------------------------+--------------+--------+------------+----------+ +| :ref:`NagiosGen ` | Yes | Yes | No | Yes | ++--------------------------------------------------------------+--------------+--------+------------+----------+ +| :ref:`Pkgmgr ` | Yes | No | No | No | ++--------------------------------------------------------------+--------------+--------+------------+----------+ +| :ref:`Properties ` | Yes [#f3]_ | Yes | Yes | Yes | ++--------------------------------------------------------------+--------------+--------+------------+----------+ +| :ref:`Rules ` | Yes | Yes | Yes | Yes | ++--------------------------------------------------------------+--------------+--------+------------+----------+ +| :ref:`SSLCA cert.xml and key.xml | Yes | Yes | Yes | No | +| ` | | | | | ++--------------------------------------------------------------+--------------+--------+------------+----------+ + +.. rubric:: Footnotes + +.. [#f1] ``info.xml`` also supports conditional Path tags; see + :ref:`server-info` for more. +.. [#f2] The semantics of Group tags in ``groups.xml`` is slightly + different; see + :ref:`server-plugins-grouping-metadata-groups-xml` for + details. +.. [#f3] Group and Client tags in XML Properties are not automatic by + default; they can be resolved by use of either the + ``Match()`` or ``XMLMatch()`` methods, or by use of the + :ref:`server-plugins-connectors-properties-automatch` + feature. See :ref:`server-plugins-connectors-properties-xml` + for details. -- cgit v1.2.3-1-g7c22