From 398be2c5cb613d9506e0c115510c1b55881ca64e Mon Sep 17 00:00:00 2001 From: "Chris St. Pierre" Date: Fri, 8 Feb 2013 13:43:40 -0500 Subject: Bundler: added support for independent bundles --- doc/server/plugins/structures/base.txt | 83 -------------- doc/server/plugins/structures/bundler/bcfg2.txt | 88 +++++++++++++++ doc/server/plugins/structures/bundler/index.txt | 143 ++++++++++++------------ doc/server/xml-common.txt | 83 ++++++++++++++ 4 files changed, 244 insertions(+), 153 deletions(-) delete mode 100644 doc/server/plugins/structures/base.txt create mode 100644 doc/server/plugins/structures/bundler/bcfg2.txt (limited to 'doc') diff --git a/doc/server/plugins/structures/base.txt b/doc/server/plugins/structures/base.txt deleted file mode 100644 index 03eae0573..000000000 --- a/doc/server/plugins/structures/base.txt +++ /dev/null @@ -1,83 +0,0 @@ -.. -*- mode: rst -*- - -.. _server-plugins-structures-base: - -==== -Base -==== - -.. deprecated:: 1.2.0 - -.. warning:: - - The Base plugin no longer receives new features/functionality. - Please use :ref:`server-plugins-structures-bundler-index` instead. - -The Base plugin is a structure plugin that provides the ability to add -lists of unrelated entries into client configuration entry inventories. - -Base works much like Bundler in its file format. The main difference -between Base and Bundler is that Base files are included in all clients' -configuration whereas bundles must be included explicitly in your -Metadata. See the :ref:`server-plugins-structures-bundler-index` page -for details. - -If you have lots of unconnected items (for instance: software packages -whose configuration wasn't modified, and that are also not depended -on by other packages; or single directories or files not belonging -to a package), using Bundles in Metadata would clutter or enlarge -your ``Metadata/groups.xml`` file, because they all would need to be -explicitly specified. ``Base/`` on the other hand is the perfect place -to put these items. - -Without using Base, you would be forced to put them directly -into your group definitions in ``groups.xml``, either as many -small bundles (substantially enlarging it) or into something like -``Bundler/unrelated-entries.xml``. Using the latter is especially bad -if you mix packages and services in your Bundle, since for any updated -package in that bundle, the now-related services would be restarted. - -The Base entries can still be assigned based on group membership, but when -they aren't part of a group, each and every client gets the entry. So Base is -also a great place to put entries that a large number of your clients will -get. - -For example, you could have a file ``Base/packages.xml`` - -.. code-block:: xml - - - - - [...] - - - - - - - [...] - - - -.. note:: - - You don't have to reference to the files in Base from anywhere. As long - as you include ``Base`` in your ``plugins = ...`` line in ``bcfg2.conf``, - these are included automatically. - -.. note:: - - Your Base files have to match the pattern ``Base/*.xml`` to be included. - - -The decision when to use Base and when to use Bundler depends on the -configuration entry in question, and what you are trying to achieve. - -Base is mainly used for cases where you don't want/need to explicitly -include particular configuration items. Let's say all your machines are -various linux distributions. In this case, you may want to manage the -``/etc/hosts`` file using Base instead of Bundler since you will not have -to include any Bundles in your Metadata. However, you could alternatively -have a base 'linux' group that all the clients inherit which includes a -*linux* Bundle with the ``/etc/hosts`` configuration entry. diff --git a/doc/server/plugins/structures/bundler/bcfg2.txt b/doc/server/plugins/structures/bundler/bcfg2.txt new file mode 100644 index 000000000..7465f15cb --- /dev/null +++ b/doc/server/plugins/structures/bundler/bcfg2.txt @@ -0,0 +1,88 @@ +.. -*- mode: rst -*- + +.. _server-plugins-structures-bundler-bcfg2-server: + +Bcfg2 Server +============ + +These two bundles split out the entries that do require a restart of +``bcfg2-server`` from those that don't. + +These bundles also demonstrate use of bound entries to avoid splitting +entries between Bundler and Rules. + +``Bundler/bcfg2-server.xml``: + +.. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + +``Bundler/bcfg2-server-base.xml``: + +.. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/server/plugins/structures/bundler/index.txt b/doc/server/plugins/structures/bundler/index.txt index 8f767ba03..c7dde193f 100644 --- a/doc/server/plugins/structures/bundler/index.txt +++ b/doc/server/plugins/structures/bundler/index.txt @@ -20,91 +20,94 @@ Group and Client tags can be used inside of bundles to differentiate which entries particular clients will recieve; this is useful for the case where entries are named differently across systems; for example, one Linux distro may have a package called ``openssh`` while another -uses the name ``ssh``. See :ref:`xml-group-client-tags` for details. +uses the name ``ssh``. See :ref:`xml-group-client-tags` for details +and a longer example. -The following is an annotated copy of a bundle: +A brief example: .. code-block:: xml - - - - - - - - - - - - - - - - + - - - -In this bundle, most of the entries are common to all systems. Clients -in group **deb** get one extra package and service, while clients in -group **rpm** get two extra packages and an extra service. In -addition, clients in group **fedora** *and* group **rpm** get one -extra package entries, unless they are not in the **fc14** group, in -which case, they get an extra package. The client -**trust.example.com** gets one extra file that is not distributed to -any other clients. Notice that this file doesn't describe which -versions of these entries that clients should get, only that they -should get them. (Admittedly, this example is slightly contrived, but -demonstrates how group entries can be used in bundles) - -+----------------------------+-------------------------------+ -| Group/Hostname | Entry | -+============================+===============================+ -| all | /etc/ssh/ssh_host_dsa_key | -+----------------------------+-------------------------------+ -| all | /etc/ssh/ssh_host_rsa_key | -+----------------------------+-------------------------------+ -| all | /etc/ssh/ssh_host_dsa_key.pub | -+----------------------------+-------------------------------+ -| all | /etc/ssh/ssh_host_rsa_key.pub | -+----------------------------+-------------------------------+ -| all | /etc/ssh/ssh_host_key | -+----------------------------+-------------------------------+ -| all | /etc/ssh/ssh_host_key.pub | -+----------------------------+-------------------------------+ -| all | /etc/ssh/sshd_config | -+----------------------------+-------------------------------+ -| all | /etc/ssh/ssh_config | -+----------------------------+-------------------------------+ -| all | /etc/ssh/ssh_known_hosts | -+----------------------------+-------------------------------+ -| rpm | Package openssh | -+----------------------------+-------------------------------+ -| rpm | Package openssh-askpass | -+----------------------------+-------------------------------+ -| rpm | Service sshd | -+----------------------------+-------------------------------+ -| rpm and fedora | Package openssh-server | -+----------------------------+-------------------------------+ -| rpm and fedora and not fc4 | Package openssh-clients | -+----------------------------+-------------------------------+ -| deb | Package ssh | -+----------------------------+-------------------------------+ -| deb | Service ssh | -+----------------------------+-------------------------------+ -| trust.example.com | /etc/ssh/shosts.equiv | -+----------------------------+-------------------------------+ +Note that we do not specify *how* a given entry should be managed, +only that it should be. The concrete specification of each entry will +be provided by a different plugin such as +:ref:`server-plugins-generators-cfg`, +:ref:`server-plugins-generators-rules`, or +:ref:`server-plugins-generators-packages`. + +Alternatively, you can use fully-bound entries in Bundler, which has +various uses. For instance: + + + + + + + + + + + + + +In this example, both Service tags and one Package tag are fully bound +-- i.e., all information required by the client to manage those +entries is provided in the bundle itself. + +.. _server-plugins-structures-bundler-magic: + +Bundle "Magic" +============== + +Bundles are collections of *related* entries. That point is very, +very important, because a bundle performs certain "magic" actions when +one or more entries in it are modified: + +* :xml:type:`Service ` entries whose ``restart`` + attribute is ``true`` (the default) will be restarted. +* :xml:type:`Action ` entries whose ``when`` attribute is + ``modified`` will be run. + +Because of these two magic actions, it's extremely important to +structure your bundles around Service and Action entries, rather than +around some loose idea of which entries are related. For instance, in +order to manage a Bcfg2 server, a number of packages, paths, services, +etc. must be managed. But not all of these entries would require +``bcfg2-server`` to be restarted, so to limit restarts it's wise to +split these entries into two bundles. See +:ref:`server-plugins-structures-bundler-bcfg2-server` for an example +of this. + +Disabling Magic +--------------- + +Disabling magic bundler actions can be done in one of two ways: + +* On a per-entry basis. Set ``restart="false"`` on a Service to + prevent it from being restarted when the bundle is modified. Set + ``when="always"`` on an Action to cause it to run every time, + regardless of whether or not the bundle was modified. +* On a per-bundle basis. Set ``independent="true"`` on the top-level + ``Bundle`` tag to signify that the bundle is a collection of + independent (i.e., unrelated) entries, and to prevent any magic + actions from being performed. (This is similar to the ``Base`` + plugin in older versions of Bcfg2.) This was added in Bcfg2 1.4. + +Service entries in independent bundles are never restarted, and Action +entries in independent bundles are only executed if ``when="always"``. +(I.e., an Action entry in an independent bundle with +``when="modified"`` is useless.) Genshi templates ================ diff --git a/doc/server/xml-common.txt b/doc/server/xml-common.txt index c2c3f34d4..96644571b 100644 --- a/doc/server/xml-common.txt +++ b/doc/server/xml-common.txt @@ -75,6 +75,89 @@ Or, more compactly: Else Manage the abstract service "bar" +As an example, consider the following :ref:`bundle +`: + +.. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +In this bundle, most of the entries are common to all systems. Clients +in group ``deb`` get one extra package and service, while clients in +group ``rpm`` get two extra packages and an extra service. In +addition, clients in group ``fedora`` *and* group ``rpm`` get one +extra package entries, unless they are not in the ``fedora14`` group, +in which case, they get an extra package. The client +``trust.example.com`` gets one extra file that is not distributed to +any other clients. + ++------------------------+-----------------------------------+ +| Group/Hostname | Entry | ++========================+===================================+ +| all | ``/etc/ssh/ssh_host_dsa_key`` | ++------------------------+-----------------------------------+ +| all | ``/etc/ssh/ssh_host_rsa_key`` | ++------------------------+-----------------------------------+ +| all | ``/etc/ssh/ssh_host_dsa_key.pub`` | ++------------------------+-----------------------------------+ +| all | ``/etc/ssh/ssh_host_rsa_key.pub`` | ++------------------------+-----------------------------------+ +| all | ``/etc/ssh/ssh_host_key`` | ++------------------------+-----------------------------------+ +| all | ``/etc/ssh/ssh_host_key.pub`` | ++------------------------+-----------------------------------+ +| all | ``/etc/ssh/sshd_config`` | ++------------------------+-----------------------------------+ +| all | ``/etc/ssh/ssh_config`` | ++------------------------+-----------------------------------+ +| all | ``/etc/ssh/ssh_known_hosts`` | ++------------------------+-----------------------------------+ +| ``rpm`` | Package ``openssh`` | ++------------------------+-----------------------------------+ +| ``rpm`` | Package ``openssh-askpass`` | ++------------------------+-----------------------------------+ +| ``rpm`` | Service ``sshd`` | ++------------------------+-----------------------------------+ +| ``rpm`` AND ``fedora`` | Package ``openssh-server`` | ++------------------------+-----------------------------------+ +| ``rpm`` AND ``fedora`` | Package ``openssh-clients`` | +| AND NOT ``fedora14`` | | ++------------------------+-----------------------------------+ +| ``deb`` | Package ``ssh`` | ++------------------------+-----------------------------------+ +| ``deb`` | Service ``ssh`` | ++------------------------+-----------------------------------+ +| ``trust.example.com`` | ``/etc/ssh/shosts.equiv`` | ++------------------------+-----------------------------------+ + .. _xml-genshi-templating: Genshi templating -- cgit v1.2.3-1-g7c22