diff options
author | Chris St. Pierre <chris.a.st.pierre@gmail.com> | 2013-12-09 09:38:04 -0500 |
---|---|---|
committer | Chris St. Pierre <chris.a.st.pierre@gmail.com> | 2013-12-09 09:38:04 -0500 |
commit | 7497f20a4821515fc9c8dadf85d3c4f3b47245eb (patch) | |
tree | be129aa775852ed70bac6be82af719b9bfc7901f /doc | |
parent | eff366a0c3b9ba87f3ee06f90dccdd242579b7b1 (diff) | |
parent | bf2ee31f956447fa42ae85dc69820405eda8c490 (diff) | |
download | bcfg2-7497f20a4821515fc9c8dadf85d3c4f3b47245eb.tar.gz bcfg2-7497f20a4821515fc9c8dadf85d3c4f3b47245eb.tar.bz2 bcfg2-7497f20a4821515fc9c8dadf85d3c4f3b47245eb.zip |
Merge branch 'maint'
Conflicts:
doc/appendix/guides/fedora.txt
misc/bcfg2.spec
schemas/types.xsd
src/lib/Bcfg2/Encryption.py
src/lib/Bcfg2/Options.py
src/lib/Bcfg2/Server/Admin/Client.py
src/lib/Bcfg2/Server/Core.py
src/lib/Bcfg2/Server/Lint/Validate.py
src/lib/Bcfg2/Server/Plugin/helpers.py
src/lib/Bcfg2/Server/Plugins/Bundler.py
src/lib/Bcfg2/Server/Plugins/Cfg/CfgEncryptedGenerator.py
src/lib/Bcfg2/Server/Plugins/Probes.py
src/sbin/bcfg2-crypt
testsuite/Testsrc/Testlib/TestServer/TestPlugin/Testhelpers.py
testsuite/Testsrc/Testlib/TestServer/TestPlugins/TestCfg/TestCfgEncryptedGenerator.py
testsuite/Testsrc/Testlib/TestServer/TestPlugins/TestProbes.py
testsuite/common.py
testsuite/install.sh
Diffstat (limited to 'doc')
-rw-r--r-- | doc/appendix/guides/centos.txt | 9 | ||||
-rw-r--r-- | doc/appendix/guides/ubuntu.txt | 9 | ||||
-rw-r--r-- | doc/client/tools/augeas.txt | 72 | ||||
-rw-r--r-- | doc/installation/prerequisites.txt | 21 | ||||
-rw-r--r-- | doc/server/plugins/generators/rules.txt | 14 | ||||
-rw-r--r-- | doc/server/plugins/probes/index.txt | 42 | ||||
-rw-r--r-- | doc/unsorted/bcfg2.conf-options.txt | 19 | ||||
-rw-r--r-- | doc/unsorted/dynamic_groups.txt | 27 | ||||
-rw-r--r-- | doc/unsorted/howtos.txt | 2 |
9 files changed, 155 insertions, 60 deletions
diff --git a/doc/appendix/guides/centos.txt b/doc/appendix/guides/centos.txt index 3a35627a8..af097fbac 100644 --- a/doc/appendix/guides/centos.txt +++ b/doc/appendix/guides/centos.txt @@ -230,10 +230,11 @@ should look something like this When editing your xml files by hand, it is useful to occasionally run `bcfg2-lint` to ensure that your xml validates properly. -The final thing we need is for the client to have the proper -arch group membership. For this, we will make use of the -:ref:`unsorted-dynamic_groups` capabilities of the Probes plugin. Add -Probes to your plugins line in ``bcfg2.conf`` and create the Probe.:: +The final thing we need is for the client to have the proper arch +group membership. For this, we will make use of the +:ref:`server-plugins-probes-dynamic-groups` capabilities of the Probes +plugin. Add Probes to your plugins line in ``bcfg2.conf`` and create +the Probe.:: [root@centos ~]# grep plugins /etc/bcfg2.conf plugins = Bundler,Cfg,...,Probes diff --git a/doc/appendix/guides/ubuntu.txt b/doc/appendix/guides/ubuntu.txt index 60f8e3a41..abb894465 100644 --- a/doc/appendix/guides/ubuntu.txt +++ b/doc/appendix/guides/ubuntu.txt @@ -253,10 +253,11 @@ that our client is able to obtain these sources. When editing your xml files by hand, it is useful to occasionally run ``bcfg2-lint -v`` to ensure that your xml validates properly. -The last thing we need is for the client to have the proper -arch group membership. For this, we will make use of the -:ref:`unsorted-dynamic_groups` capabilities of the Probes plugin. Add -Probes to your plugins line in ``bcfg2.conf`` and create the Probe. +The last thing we need is for the client to have the proper arch group +membership. For this, we will make use of the +:ref:`server-plugins-probes-dynamic-groups` capabilities of the Probes +plugin. Add Probes to your plugins line in ``bcfg2.conf`` and create +the Probe. .. code-block:: sh diff --git a/doc/client/tools/augeas.txt b/doc/client/tools/augeas.txt new file mode 100644 index 000000000..94ed9066f --- /dev/null +++ b/doc/client/tools/augeas.txt @@ -0,0 +1,72 @@ +.. -*- mode: rst -*- + +.. _client-tools-augeas: + +======== + Augeas +======== + +The Augeas tool provides a way to use `Augeas +<http://www.augeas.net>`_ to edit files that may not be completely +managed. + +In the simplest case, you simply tell Augeas which path to edit, and +give it a sequence of commands: + +.. code-block:: xml + + <Path type="augeas" name="/etc/hosts" owner="root" group="root" + mode="0644"> + <Set path="01/ipaddr" value="192.168.0.1"/> + <Set path="01/canonical" value="pigiron.example.com"/> + <Set path="01/alias[1]" value="pigiron"/> + <Set path="01/alias[2]" value="piggy"/> + </Path> + +The commands are run in document order. There's no need to do an +explicit ``save`` at the end. + +Each of these commands will only be run if the path does not already +have the given setting. That is, the ip address for the first host +record will only be set to ``192.168.0.1`` if it's not set to that +value already. Its canonical name will only be set to +``pigiron.example.com`` if it's not that already; and so on. + +The Augeas paths are all relative to ``/files/etc/hosts``. + +The Augeas tool understands a subset of ``augtool`` commands. Valid +tags are: ``Remove``, ``Move``, ``Set``, ``Clear``, ``SetMulti``, and +``Insert``. Refer to the official Augeas docs or the `Schema`_ below +for details on the commands. + +Editing files outside the default load path +=========================================== + +If you're using Augeas to edit files outside of its default load path, +you must manually specify the lens. For instance: + +.. code-block:: xml + + <Path type="augeas" name="/opt/jenkins/home/config.xml" lens="Xml" + owner="jenkins" group="jenkins" mode="0640"> + <Set path="hudson/systemMessage/#text" + value="This is a Jenkins server."/> + </Path> + +Note that there's no need to manually modify the load path by setting +``/augeas/load/<lens>/incl``, nor do you have to call ``load`` +explicitly. + +Schema +====== + +.. xml:group:: augeasCommands + + +Performance +=========== + +The Augeas tool is quite slow to initialize. For each ``<Path +type="augeas" ... >`` entry you have, it creates a new Augeas object +internally, which can take several seconds. It's thus important to +use this tool sparingly. diff --git a/doc/installation/prerequisites.txt b/doc/installation/prerequisites.txt index 81ac12632..e3434edd3 100644 --- a/doc/installation/prerequisites.txt +++ b/doc/installation/prerequisites.txt @@ -21,7 +21,7 @@ Bcfg2 Client +----------------------------+------------------------+--------------------------------+ | libxslt (if lxml is used) | Any | libxml2 | +----------------------------+------------------------+--------------------------------+ -| python | 2.4 and greater [#f1] | | +| python | 2.4 and greater [#f1]_ | | +----------------------------+------------------------+--------------------------------+ | lxml or elementtree [#f2]_ | Any | lxml: libxml2, libxslt, python | +----------------------------+------------------------+--------------------------------+ @@ -54,10 +54,21 @@ Bcfg2 Server +-------------------------------+----------+--------------------------------+ | python-gamin or pyinotify | Any | gamin or inotify, python | +-------------------------------+----------+--------------------------------+ -| M2crypto or python-ssl (note | Any | python, openssl | -| that the ssl module is | | | -| included in python versions | | | -| 2.6 and later | | | +| python-ssl (note | Any | python, backported ssl module | ++-------------------------------+----------+--------------------------------+ + +Bcfg2 Reporting +--------------- + +A webserver capabable of running wsgi applications is required for web +reporting, such as Apache + mod_wsgi or nginx. + ++-------------------------------+----------+--------------------------------+ +| Software | Version | Requires | ++===============================+==========+================================+ +| django | 1.2.0+ | | ++-------------------------------+----------+--------------------------------+ +| south | 0.7.0+ | | +-------------------------------+----------+--------------------------------+ Bcfg2 Reporting diff --git a/doc/server/plugins/generators/rules.txt b/doc/server/plugins/generators/rules.txt index 64dbc8597..c5ff699a7 100644 --- a/doc/server/plugins/generators/rules.txt +++ b/doc/server/plugins/generators/rules.txt @@ -118,6 +118,20 @@ Attributes common to all Path tags: :onlyattrs: name,type +augeas +^^^^^^ + +Run `Augeas <http://www.augeas.net>`_ commands. See +:ref:`client-tools-augeas` for more details. + +.. xml:type:: PathType + :nochildren: + :noattributegroups: + :nodoc: + :notext: + :onlyattrs: owner,group,mode,secontext,lens + :requiredattrs: owner,group,mode + device ^^^^^^ diff --git a/doc/server/plugins/probes/index.txt b/doc/server/plugins/probes/index.txt index 306a752b6..2e23c31d5 100644 --- a/doc/server/plugins/probes/index.txt +++ b/doc/server/plugins/probes/index.txt @@ -13,6 +13,9 @@ the system disk, you would want to know this information to correctly generate an `/etc/auto.master` autofs config file for each type. Here we will look at how to do this. +Probes also allow dynamic group assignment for clients, see +:ref:`_server-plugins-probes-dynamic-groups`. + First, create a ``Probes`` directory in our toplevel repository location:: @@ -119,6 +122,45 @@ is to add the ``/etc/auto.master`` to a Bundle: <Path name='/etc/auto.master'/> +.. _server-plugins-probes-dynamic-groups: + +Dynamic Group Assignment +======================== + +The output lines of the probe matching "group:" are used to +dynamically assign hosts to groups. These dynamic groups need not already +exist in ``Metadata/groups.xml``. If a dynamic group is defined in +``Metadata/groups.xml``, clients that include this group will also get +all included groups and bundles. + +Consider the following output of a probe:: + + group:debian-wheezy + group:amd64 + +This assigns the client to the groups debian-wheezy and amd64. + +To prevent clients from manipulating the probe output and choosing +unexpected groups (and receiving their potential sensitive files) you +can use the ``allowed_groups`` option in the ``[probes]`` section of +``bcfg2.conf`` on the server. This whitespace-separated list of +anchored regular expressions (must match the complete group name) +controls dynamic group assignments. Only matching groups are +allowed. The default allows all groups. + +.. versionadded:: 1.3.4 + +Example: + +.. code-block:: ini + + [probes] + allowed_groups = debian-(squeeze|wheezy|sid) i386 + +This allows the groups `debian-squeeze`, `debian-wheezy`, `debian-sid` +and `i386`. With the probe output from above, this setting would +disallow the group `amd64`. + Handling Probe Output ===================== diff --git a/doc/unsorted/bcfg2.conf-options.txt b/doc/unsorted/bcfg2.conf-options.txt deleted file mode 100644 index 57e26cbd2..000000000 --- a/doc/unsorted/bcfg2.conf-options.txt +++ /dev/null @@ -1,19 +0,0 @@ -.. -*- mode: rst -*- - -.. _unsorted-bcfg2.conf-options: - -========== -bcfg2.conf -========== - -This page documents the various options available in bcfg2.conf. The -various sections correspond to the sections in the file itself. - -components -========== - -logging -------- - -Specify an alternate path for the lockfile used by the bcfg2 client. -Default value is ``/var/lock/bcfg2.run`` diff --git a/doc/unsorted/dynamic_groups.txt b/doc/unsorted/dynamic_groups.txt deleted file mode 100644 index 11535dc8b..000000000 --- a/doc/unsorted/dynamic_groups.txt +++ /dev/null @@ -1,27 +0,0 @@ -.. -*- mode: rst -*- - -.. _unsorted-dynamic_groups: - -============== -Dynamic Groups -============== - -Bcfg2 supports the use of dynamic groups. These groups are not included -in a client's profile group, but instead are derived from the results -of probes executed on the client. These dynamic groups need not already -exist in ``Metadata/groups.xml``. If a dynamic group is defined in -``Metadata/groups.xml``, clients that include this group will also get -all included groups and bundles. - -Setting up dynamic groups -========================= - -In order to define a dynamic group, setup a probe that outputs the text -based on system properties:: - - group:groupname - -This output is processed by the Bcfg2 server, and results in dynamic -group membership in groupname for the client. See the :ref:`Probes -<server-plugins-probes-index>` page for a more thorough description -of probes. diff --git a/doc/unsorted/howtos.txt b/doc/unsorted/howtos.txt index 0c5b482d9..cef64a394 100644 --- a/doc/unsorted/howtos.txt +++ b/doc/unsorted/howtos.txt @@ -14,5 +14,5 @@ Here are several howtos that describe different aspects of Bcfg2 deployment * :ref:`appendix-guides-gentoo` - Issues specific to running Bcfg2 on Gentoo * :ref:`server-plugins-probes-index` - How to use Probes to gather information from a client machine. * :ref:`client-tools-actions` - How to use Actions -* :ref:`unsorted-dynamic_groups` - Using dynamic groups +* :ref:`server-plugins-probes-dynamic-groups` - Using dynamic groups * :ref:`client-modes-paranoid` - How to run an update in paranoid mode |