From d8bbfbdf8b503538fff01bff80c5e6e12bfb44b3 Mon Sep 17 00:00:00 2001 From: Simon Ruderich Date: Tue, 12 Nov 2013 23:48:25 +0100 Subject: Add probes.allowed_groups option to restrict group assignments. --- doc/server/plugins/probes/index.txt | 40 +++++++++++++++++++++++++++++++++++++ doc/unsorted/dynamic_groups.txt | 27 ------------------------- 2 files changed, 40 insertions(+), 27 deletions(-) delete mode 100644 doc/unsorted/dynamic_groups.txt (limited to 'doc') diff --git a/doc/server/plugins/probes/index.txt b/doc/server/plugins/probes/index.txt index 306a752b6..6f745e359 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,43 @@ is to add the ``/etc/auto.master`` to a Bundle: +.. _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:: TODO + +Example:: + + [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/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 -` page for a more thorough description -of probes. -- cgit v1.2.3-1-g7c22 From 41d5f9d8275690a96c8cd4fc5443bad3b1b72e73 Mon Sep 17 00:00:00 2001 From: "Chris St. Pierre" Date: Thu, 14 Nov 2013 09:43:06 -0500 Subject: doc: defined when probes allowed_groups setting was added --- doc/server/plugins/probes/index.txt | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) (limited to 'doc') diff --git a/doc/server/plugins/probes/index.txt b/doc/server/plugins/probes/index.txt index 6f745e359..2e23c31d5 100644 --- a/doc/server/plugins/probes/index.txt +++ b/doc/server/plugins/probes/index.txt @@ -143,21 +143,23 @@ 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. +``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:: TODO +.. versionadded:: 1.3.4 -Example:: +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. +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 ===================== -- cgit v1.2.3-1-g7c22 From 6c3a7d01bd4a68db1ce1048cdfd6994462fbb11f Mon Sep 17 00:00:00 2001 From: Sol Jerome Date: Thu, 14 Nov 2013 11:00:01 -0600 Subject: doc: Remove unkept bcfg2.conf page The man pages are stored in our documentation now so this is obsolete. Signed-off-by: Sol Jerome --- doc/unsorted/bcfg2.conf-options.txt | 19 ------------------- 1 file changed, 19 deletions(-) delete mode 100644 doc/unsorted/bcfg2.conf-options.txt (limited to 'doc') 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`` -- cgit v1.2.3-1-g7c22 From f4dc3f33579584924243ac2e89f6f68ed195ec79 Mon Sep 17 00:00:00 2001 From: Sol Jerome Date: Wed, 20 Nov 2013 10:16:26 -0600 Subject: doc: Update prerequisites Signed-off-by: Sol Jerome --- doc/installation/prerequisites.txt | 25 ++++++++++++++++++------- 1 file changed, 18 insertions(+), 7 deletions(-) (limited to 'doc') diff --git a/doc/installation/prerequisites.txt b/doc/installation/prerequisites.txt index 0cb721bb9..e920f955b 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 | +----------------------------+------------------------+--------------------------------+ @@ -50,12 +50,23 @@ Bcfg2 Server +-------------------------------+----------+--------------------------------+ | lxml | 0.9+ | lxml: libxml2, libxslt, python | +-------------------------------+----------+--------------------------------+ -| gamin or fam | Any | | +| gamin or inotify | Any | | +-------------------------------+----------+--------------------------------+ -| python-gamin or python-fam | Any | gamin or fam, python | +| 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+ | | +-------------------------------+----------+--------------------------------+ -- cgit v1.2.3-1-g7c22 From 53f8eb67378f6a8054cb107e72b094f070d40c83 Mon Sep 17 00:00:00 2001 From: "Chris St. Pierre" Date: Thu, 5 Dec 2013 09:58:18 -0500 Subject: Tools: new Augeas driver --- doc/client/tools/augeas.txt | 72 +++++++++++++++++++++++++++++++++ doc/server/plugins/generators/rules.txt | 14 +++++++ 2 files changed, 86 insertions(+) create mode 100644 doc/client/tools/augeas.txt (limited to 'doc') 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 +`_ 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 + + + + + + + + +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 + + + + + +Note that there's no need to manually modify the load path by setting +``/augeas/load//incl``, nor do you have to call ``load`` +explicitly. + +Schema +====== + +.. xml:group:: augeasCommands + + +Performance +=========== + +The Augeas tool is quite slow to initialize. For each ```` 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/server/plugins/generators/rules.txt b/doc/server/plugins/generators/rules.txt index 9ba70238d..a21dd217f 100644 --- a/doc/server/plugins/generators/rules.txt +++ b/doc/server/plugins/generators/rules.txt @@ -136,6 +136,20 @@ Attributes common to all Path tags: :onlyattrs: name,type +augeas +^^^^^^ + +Run `Augeas `_ 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 ^^^^^^ -- cgit v1.2.3-1-g7c22 From abb1c51462d35b501bbf33bc8e91352208df1c8d Mon Sep 17 00:00:00 2001 From: "Chris St. Pierre" Date: Thu, 5 Dec 2013 10:00:14 -0500 Subject: doc: fixed links to dynamic probe groups docs, which were moved in d8bbfbdf --- doc/appendix/guides/centos.txt | 9 +++++---- doc/appendix/guides/fedora.txt | 9 +++++---- doc/appendix/guides/ubuntu.txt | 9 +++++---- doc/unsorted/howtos.txt | 2 +- 4 files changed, 16 insertions(+), 13 deletions(-) (limited to 'doc') diff --git a/doc/appendix/guides/centos.txt b/doc/appendix/guides/centos.txt index febdf5769..19354b709 100644 --- a/doc/appendix/guides/centos.txt +++ b/doc/appendix/guides/centos.txt @@ -231,10 +231,11 @@ file 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 = Base,Bundler,Cfg,...,Probes diff --git a/doc/appendix/guides/fedora.txt b/doc/appendix/guides/fedora.txt index 1e49084ef..f89daaf0b 100644 --- a/doc/appendix/guides/fedora.txt +++ b/doc/appendix/guides/fedora.txt @@ -256,10 +256,11 @@ file should look something like this Add a probe +++++++++++ -The next step for the client will be 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 next step for the client will be 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/appendix/guides/ubuntu.txt b/doc/appendix/guides/ubuntu.txt index f68c8b9ad..9bf851632 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/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 -- cgit v1.2.3-1-g7c22