From 34e5e12fd58ec4b0015abdf1a04a4f684c9194ba Mon Sep 17 00:00:00 2001 From: "Chris St. Pierre" Date: Wed, 11 May 2011 10:30:33 -0400 Subject: Added FileProbes plugin. --- doc/server/plugins/probes/index.txt | 57 +++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) (limited to 'doc') diff --git a/doc/server/plugins/probes/index.txt b/doc/server/plugins/probes/index.txt index 33ec6f444..b9f698a0f 100644 --- a/doc/server/plugins/probes/index.txt +++ b/doc/server/plugins/probes/index.txt @@ -143,3 +143,60 @@ Other examples :hidden: ohai + +.. _server-plugins-probes-fileprobes: + +FileProbes +========== + +The FileProbes plugin allows you to probe a client for a file, +which is then added to the :ref:`server-plugins-generators-cfg` +specification. If the file changes on the client, FileProbes can +either update it in the specification or allow Cfg to replace it. + +FileProbes will not probe a file if there's already a file in Cfg that +will apply to the client. So if, for instance, you have a generic +file in ``Cfg/etc/foo.conf/foo.conf`` that applies to all hosts, +FileProbes will not retrieve ``/etc/foo.conf`` from the client (unless +``update`` is enabled; see Configuration_ below). + +When a new config file is first probed, an ``info.xml`` file is also +written to enforce the permissions from that client. Subsequent +probes from other clients will not modify or overwrite the data in +``info.xml``. (This ensures that any manual changes you make to +``info.xml`` for that file are not circumvented.) + +Configuration +------------- + +FileProbes is configured in ``FileProbes/config.xml``, which might +look something like: + +.. code-block:: xml + + + + + + + + + + +This will result in ``/etc/foo.conf`` being retrieved from all +clients; if it changes on a client, it will be overwritten by the +version that was retrieved initially. + +Clients in the ``blah-servers`` group will be probed for +``/etc/blah.conf``; if it changes on a client, those changes will be +written into the Bcfg2 specification. If the file is deleted from a +client, it will be rewritten from Bcfg2. + +``bar.example.com`` will be probed for ``/var/lib/bar.gz``, which +contains non-ASCII characters and so needs to use base64 encoding when +transferring the file. + +The paths probed by FileProbes must also be included as Path entries +in your bundles in order to be handled properly by Cfg. Permissions +are handled as usual, with ``info.xml`` files in Cfg. -- cgit v1.2.3-1-g7c22 From 87aca88c41efaaa5a37fb415ced67cbbcfc34ff5 Mon Sep 17 00:00:00 2001 From: Sol Jerome Date: Sat, 14 May 2011 16:15:25 -0500 Subject: doc: Fix groups in centos guide (#1006) Signed-off-by: Sol Jerome --- doc/appendix/guides/centos.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'doc') diff --git a/doc/appendix/guides/centos.txt b/doc/appendix/guides/centos.txt index d788891de..0b5b83211 100644 --- a/doc/appendix/guides/centos.txt +++ b/doc/appendix/guides/centos.txt @@ -195,17 +195,17 @@ line of ``bcfg2.conf``. Then create Packages layout (as per - centos5.4 + centos-5.4 http://mrepo/centos5-x86_64/RPMS.os x86_64 - centos5.4 + centos-5.4 http://mrepo/centos5-x86_64/RPMS.updates x86_64 - centos5.4 + centos-5.4 http://mrepo/centos5-x86_64/RPMS.extras x86_64 @@ -227,9 +227,9 @@ file should look something like this - + - + -- cgit v1.2.3-1-g7c22 From fa3431d204add1baab2dd1e6ca5326f2bf1749fe Mon Sep 17 00:00:00 2001 From: Sol Jerome Date: Mon, 16 May 2011 11:19:17 -0500 Subject: doc: Better document PostInstall entries Signed-off-by: Sol Jerome --- doc/server/configurationentries.txt | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/server/configurationentries.txt b/doc/server/configurationentries.txt index 5602da189..91aed99b6 100644 --- a/doc/server/configurationentries.txt +++ b/doc/server/configurationentries.txt @@ -34,6 +34,22 @@ Non-POSIX entries | Service | System Services | name, type, status, target | +-------------+---------------------+-----------------------------+ +.. note:: + + PostInstall entries are deprecated in favor of Action entries. In + fact, a PostInstall entry is simply a specific type of Action. + Basically, the following are equivalent:: + + .. code-block:: xml + + + + and + + .. code-block:: xml + + + POSIX entries ============= @@ -48,7 +64,7 @@ will only contain a *name* attribute. The type will be added by the plugin that handles the entry in the case of `Cfg`_, `TGenshi`_, or `TCheetah`_. If the entry is handled by the `Rules`_ plugin (i.e. it is a device, directory, hardlink, symlink, etc), then you will specify both -the *type* and any other necessary attributes in `Rules`_. +the *type* and any other necessary attributes in `Rules`_. Running ``bcfg2-lint`` will check your configuration specification for the presence of any mandatory attributes that are necessary for the -- cgit v1.2.3-1-g7c22 From d94c449ed7d1e68ffa119572f1b53080523e74e5 Mon Sep 17 00:00:00 2001 From: "Chris St. Pierre" Date: Tue, 17 May 2011 10:20:46 -0400 Subject: added documentation about manually troubleshooting TGenshi and Bundler templates --- doc/server/plugins/generators/tgenshi/index.txt | 61 +++++++++++++++++++++++-- doc/server/plugins/structures/bundler/index.txt | 17 +++++++ 2 files changed, 74 insertions(+), 4 deletions(-) (limited to 'doc') diff --git a/doc/server/plugins/generators/tgenshi/index.txt b/doc/server/plugins/generators/tgenshi/index.txt index 0fc541b52..d7e0b3bf2 100644 --- a/doc/server/plugins/generators/tgenshi/index.txt +++ b/doc/server/plugins/generators/tgenshi/index.txt @@ -54,7 +54,10 @@ Inside of templates available when used in conjunction with the :ref:`server-plugins-connectors-properties` plugin) * **name** is the path name specified in bcfg -* **path** is the path to the TGenshi template +* **path** is the path to the TGenshi template. It starts with a + leading slash, and is relative to the Bcfg2 specification root. + E.g., ``/Cfg/etc/foo.conf/foo.conf.genshi`` or + ``/TGenshi/etc/foo.conf/template.newtxt.H_foo.example.com`` See the genshi `documentation `_ for examples of @@ -91,6 +94,56 @@ Produces: This flexibility provides the ability to build much more compact and succinct definitions of configuration contents than Cfg can. +Troubleshooting +=============== + +When developing a template, you can see what the template would +generate on a client with :ref:`bcfg2-info `:: + + bcfg2-info buildfile + +E.g.:: + + bcfg2-info buildfile /etc/foo.conf foo.example.com + +Sometimes, it's useful to be able to do more in-depth troubleshooting +by running the template manually. (This is also necessary if you want +to generate a template that depends on an :ref:`altsrc +` tag.) To do this, run ``bcfg2-info +debug``, and, once in the Python interpreter, run:: + + metadata = self.build_metadata("") + path = "" + bcfg2root = "" + +``path`` should be set to the path to the template file with a leading +slash, relative to the Bcfg2 specification root. See `Inside of +Templates`_ for examples. + +``bcfg2root`` should be set to the absolute path to the Bcfg2 +specification. (This is ``/var/lib/bcfg2`` by default.) + +Then, run:: + + import os + name = os.path.dirname(path[path.find('/', 1):]) + from genshi.template import TemplateLoader, NewTextTemplate + template = TemplateLoader().load(bcfg2root + path, cls=NewTextTemplate) + print template.generate(metadata=metadata, path=path, name=name).render() + +This gives you more fine-grained control over how your template is +rendered. + +You can also use this approach to render templates that depend on +:ref:`altsrc ` tags by setting +``path`` to the path to the template, and setting ``name`` to the path +to the file to be generated, e.g.:: + + metadata = self.build_metadata("foo.example.com") + path = "/Cfg/etc/sysconfig/network-scripts/ifcfg-template/ifcfg-template.genshi" + bcfg2root = "/var/lib/bcfg2" + name = "/etc/sysconfig/network-scripts/ifcfg-bond0" + File permissions ================ @@ -101,10 +154,10 @@ Permissions entry and a Path entry to handle the same file. Error handling ================ -Situations may arrise where a templated file cannot be generated due to +Situations may arise where a templated file cannot be generated due to missing or incomplete information. A TemplateError can be raised to -force a bind failure and prevent sending an incomplete file to the client. -For example, this template:: +force a bind failure and prevent sending an incomplete file to the +client. For example, this template:: {% python from genshi.template import TemplateError diff --git a/doc/server/plugins/structures/bundler/index.txt b/doc/server/plugins/structures/bundler/index.txt index 9fd897385..6b5c246aa 100644 --- a/doc/server/plugins/structures/bundler/index.txt +++ b/doc/server/plugins/structures/bundler/index.txt @@ -156,6 +156,23 @@ format is XML. A Genshi template looks much like a Bundler file, except the Bundle tag has an additional `xmlns:py` attribute. See the examples. +Troubleshooting +--------------- + +There is no :ref:`bcfg2-info ` command like +``buildfile`` for Bundler templates, so if you want to generate a +Bundler template for a given client, you have to do so manually by +first invoking ``bcfg2-info debug``, then run:: + + metadata = self.build_metadata("") + path = "" + from genshi.template import TemplateLoader, MarkupTemplate + template = TemplateLoader().load(path, cls=MarkupTemplate) + print template.generate(metadata=metadata).render('xml') + +``path`` needs to be the full path to the template file on the +filesystem, not just within the Bcfg2 repo. + Altsrc ====== -- cgit v1.2.3-1-g7c22 From 58e8891a16b31c23a09e019ae0de8bef7a37b6a5 Mon Sep 17 00:00:00 2001 From: Sol Jerome Date: Tue, 17 May 2011 11:10:58 -0500 Subject: doc: Fix formatting error Signed-off-by: Sol Jerome --- doc/server/configurationentries.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/server/configurationentries.txt b/doc/server/configurationentries.txt index 91aed99b6..10eccf6be 100644 --- a/doc/server/configurationentries.txt +++ b/doc/server/configurationentries.txt @@ -38,7 +38,7 @@ Non-POSIX entries PostInstall entries are deprecated in favor of Action entries. In fact, a PostInstall entry is simply a specific type of Action. - Basically, the following are equivalent:: + Basically, the following are equivalent: .. code-block:: xml -- cgit v1.2.3-1-g7c22 From 96d93d3c16c1e6cb0aa4748f8b392b84197a644a Mon Sep 17 00:00:00 2001 From: Sol Jerome Date: Tue, 17 May 2011 18:20:48 -0500 Subject: doc: Fix Cfg example Signed-off-by: Sol Jerome --- doc/server/plugins/generators/cfg.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'doc') diff --git a/doc/server/plugins/generators/cfg.txt b/doc/server/plugins/generators/cfg.txt index 612b14bec..1039ff556 100644 --- a/doc/server/plugins/generators/cfg.txt +++ b/doc/server/plugins/generators/cfg.txt @@ -132,16 +132,16 @@ server and we have the following configuration files:: motd.G01_web-server motd.G01_mail-server.cat motd.G02_file-server.cat - motd.H_foo.example.cat + motd.H_foo.example.com.cat -If our machine isn't *foo.example.com* then here's what would happen: +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: +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 -- cgit v1.2.3-1-g7c22 From 81eeff2a4a9381811d6f3d20ebd6bcf18bf83553 Mon Sep 17 00:00:00 2001 From: "Chris St. Pierre" Date: Tue, 24 May 2011 15:41:37 -0400 Subject: allow setting whitelist/blacklist mode in bcfg2.conf --- doc/server/plugins/generators/decisions.txt | 37 ++++++++++++++++++++--------- 1 file changed, 26 insertions(+), 11 deletions(-) (limited to 'doc') diff --git a/doc/server/plugins/generators/decisions.txt b/doc/server/plugins/generators/decisions.txt index ba01f7fc2..d75c298ef 100644 --- a/doc/server/plugins/generators/decisions.txt +++ b/doc/server/plugins/generators/decisions.txt @@ -22,6 +22,11 @@ should be corrected during the current run of the installation tool. The Decisions plugin is the only stock plugin that generates entries for client's whitelists or blacklists. +.. note:: If the client is not explicitly configured to run in + whitelist or blacklist mode, the list of entries is not + downloaded and decisions is not used. See ``Decision + Mode``_ below. + The Decisions plugin uses a directory in the Bcfg2 repository called Decisions. Files in the Decisions subdirectory are named similarly to files managed by Cfg, probes, TCheetah, and TGenshi (so you can use host- @@ -37,12 +42,6 @@ the following is an example. -.. note:: To add syntax highlighting in vim, you can add a modeline such as this: - - - This example, included as a whitelist due to its name, enables all services, and the path entry named ``/etc/apt/apt.conf``. All these entries must already be present in your repository, the Decisions plugin just references @@ -55,11 +54,27 @@ When a client asks for its whitelist or blacklist, all of the files pertaining to that client of the correct type are aggregated into a single list. This list is sent to the client. -.. note:: This list is only generated when a client is explicitly run with - the appropriate option (``-l (whitelist|blacklist)``); client - behavior is not controlled unless this option is used. If you do - not use Decisions, all your entries will be installed normally. -.. note:: Also, using this plugin does not present additional prompts or +.. note:: Using this plugin does not present additional prompts or safety nets to the administrator running the client, you have to control these via their respective options (``-I`` or ``-n``, for example). + +To add syntax highlighting to Decisions files in vim and emacs, you +can add comments such as this:: + + + + + +============= +Decision Mode +============= + +The whitelist or blacklist is only generated when a client is run in +whitelist or blacklist mode. This can either be set at the command +line with the appropriate option (``-l (whitelist|blacklist)``), or in +``bcfg2.conf`` by setting ``decision`` in the ``client`` section to +``whitelist`` or ``blacklist``). + +Client behavior is not controlled unless the decision mode is set. If +you do not use Decisions, all your entries will be installed normally. -- cgit v1.2.3-1-g7c22 From ac1e8e89733d1420afb69c8c7e96835243ffc323 Mon Sep 17 00:00:00 2001 From: Sol Jerome Date: Wed, 25 May 2011 22:18:59 -0500 Subject: doc: Fix inline literal reference Signed-off-by: Sol Jerome --- doc/server/plugins/generators/decisions.txt | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'doc') diff --git a/doc/server/plugins/generators/decisions.txt b/doc/server/plugins/generators/decisions.txt index d75c298ef..d75a9fede 100644 --- a/doc/server/plugins/generators/decisions.txt +++ b/doc/server/plugins/generators/decisions.txt @@ -22,10 +22,11 @@ should be corrected during the current run of the installation tool. The Decisions plugin is the only stock plugin that generates entries for client's whitelists or blacklists. -.. note:: If the client is not explicitly configured to run in - whitelist or blacklist mode, the list of entries is not - downloaded and decisions is not used. See ``Decision - Mode``_ below. +.. note:: + + If the client is not explicitly configured to run in whitelist or + blacklist mode, the list of entries is not downloaded and decisions + is not used. See `Decision Mode`_ below. The Decisions plugin uses a directory in the Bcfg2 repository called Decisions. Files in the Decisions subdirectory are named similarly to -- cgit v1.2.3-1-g7c22 From be72eb8b648672707822f891a103fc75ed54dbd2 Mon Sep 17 00:00:00 2001 From: Sol Jerome Date: Wed, 25 May 2011 22:19:40 -0500 Subject: POSIX: Clarify normalization error (Reported by Tim Goodaire) Signed-off-by: Sol Jerome --- doc/help/troubleshooting.txt | 54 ++++++++++++++++++++++++++++---------------- 1 file changed, 35 insertions(+), 19 deletions(-) (limited to 'doc') diff --git a/doc/help/troubleshooting.txt b/doc/help/troubleshooting.txt index 88a0febc5..010c80de5 100644 --- a/doc/help/troubleshooting.txt +++ b/doc/help/troubleshooting.txt @@ -109,46 +109,56 @@ be taken to remedy them. | authenticate the server with | | unable to verify | | | SSL. | | the server | | +------------------------------+----------+---------------------+--------------+ -| Failed to bind entry: | Server | The server was | [4]_ | +| GID normalization failed for | Client | The client is | [4]_ | +| FILENAME. Does group GROUP | | unable to convert | | +| exist? | | the group GROUP to | | +| | | a usable GID | | ++------------------------------+----------+---------------------+--------------+ +| UID normalization failed for | Client | The client is | [5]_ | +| FILENAME. Does owner OWNER | | unable to convert | | +| exist? | | the owner OWNER to | | +| | | a usable UID | | ++------------------------------+----------+---------------------+--------------+ +| Failed to bind entry: | Server | The server was | [6]_ | | | | unable to find a | | | | | suitable version of | | | | | entry for client. | | +------------------------------+----------+---------------------+--------------+ -| Failed to bind to socket | Server | The server was | [5]_ | +| Failed to bind to socket | Server | The server was | [7]_ | | | | unable to bind to | | | | | the tcp server | | | | | socket. | | +------------------------------+----------+---------------------+--------------+ -| Failed to load | Server | The server was | [6]_ | +| Failed to load | Server | The server was | [8]_ | | ssl key | | unable to read and | | | | | process the ssl key.| | +------------------------------+----------+---------------------+--------------+ -| Failed to read file | Server | The server failed | [7]_ | +| Failed to read file | Server | The server failed | [9]_ | | | | to read the | | | | | specified file | | +------------------------------+----------+---------------------+--------------+ -| Failed to parse file | Server | The server failed | [8]_ | +| Failed to parse file | Server | The server failed | [10]_ | | | | to parse the | | | | | specified XML file | | +------------------------------+----------+---------------------+--------------+ -| Client metadata resolution | Server | The server cannot | [9]_ | +| Client metadata resolution | Server | The server cannot | [11]_ | | error for | | resolve the client | | | | | hostname or the | | | | | client is | | | | | associated with a | | | | | non-profile group. | | +------------------------------+----------+---------------------+--------------+ -| Failed to decode | Server | The encoding being | [10]_ | +| Failed to decode | Server | The encoding being | [12]_ | | Please verify you are using | | used is unable to | | | the proper encoding | | decode the | | | | | character present | | | | | in this file. | | +------------------------------+----------+---------------------+--------------+ -| Got unknown entries | Server | The Packages plugin | [11]_ | +| Got unknown entries | Server | The Packages plugin | [13]_ | | [list of unknown entries] | | has no knowledge of | | | | | the listed entries | | +------------------------------+----------+---------------------+--------------+ -| Failed to import lxml | Server | The server cannot | [12]_ | +| Failed to import lxml | Server | The server cannot | [14]_ | | dependency. Shutting | | import lxml | | | down server. | | | | +------------------------------+----------+---------------------+--------------+ @@ -162,20 +172,26 @@ be taken to remedy them. .. [3] Copy the Bcfg2 server's CA certificate to the client and specify it using the **ca** option in the [communication] section of ``bcfg2.conf`` -.. [4] This entry is not being bound. Ensure that a version of this +.. [4] If the group doesn't exist, you need to specify the correct one + in an :ref:`info.xml ` file or set the default group + appropriately. +.. [5] If the owner doesn't exist, you need to specify the correct one + in an :ref:`info.xml ` file or set the default owner + appropriately. +.. [6] This entry is not being bound. Ensure that a version of this entry applies to this client. -.. [5] Ensure that another instance of the daemon (or any other process) +.. [7] Ensure that another instance of the daemon (or any other process) is not listening on the same port. -.. [6] Ensure that the key is readable by the user running the daemon +.. [8] Ensure that the key is readable by the user running the daemon and that it is well-formed. -.. [7] Ensure that this file still exists; a frequent cause is the +.. [9] Ensure that this file still exists; a frequent cause is the deletion of a temp file. -.. [8] Ensure that the file is properly formed XML. -.. [9] Fix hostname resolution for the client or ensure that the profile - group is properly setup. -.. [10] Ensure the correct encoding is specified in the [components] +.. [10] Ensure that the file is properly formed XML. +.. [11] Fix hostname resolution for the client or ensure that the profile + group is properly setup. +.. [12] Ensure the correct encoding is specified in the [components] section of ``bcfg2.conf``. -.. [11] For packages listed other than **gpg-pubkey**, this error means +.. [13] For packages listed other than **gpg-pubkey**, this error means that the Packages plugin is unable to find the package in any of the sources listed in ``Packages/config.xml``. The issue often arises when the client is not in one of the groups necessary for @@ -183,7 +199,7 @@ be taken to remedy them. ignore the message as the Packages plugin has no knowledge of these packages (however, note that this package is most often specified as a BoundPackage entry). -.. [12] Ensure that you have installed all the necessary +.. [14] Ensure that you have installed all the necessary :ref:`installation-prerequisites`. FAQs -- cgit v1.2.3-1-g7c22 From 99495c559da8bb432274e94248f98d9b34c2d205 Mon Sep 17 00:00:00 2001 From: Sol Jerome Date: Tue, 31 May 2011 10:36:15 -0500 Subject: Cfg: Fix traceback for non-ascii files Signed-off-by: Sol Jerome --- doc/help/troubleshooting.txt | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'doc') diff --git a/doc/help/troubleshooting.txt b/doc/help/troubleshooting.txt index 010c80de5..ecf53527c 100644 --- a/doc/help/troubleshooting.txt +++ b/doc/help/troubleshooting.txt @@ -162,6 +162,10 @@ be taken to remedy them. | dependency. Shutting | | import lxml | | | down server. | | | | +------------------------------+----------+---------------------+--------------+ +| You need to specify base64 | Server | The server cannot | [15]_ | +| encoding for | | send the file as | | +| | | ascii text | | ++------------------------------+----------+---------------------+--------------+ .. [1] This entry is not being bound. Ensure that a version of this @@ -201,6 +205,8 @@ be taken to remedy them. specified as a BoundPackage entry). .. [14] Ensure that you have installed all the necessary :ref:`installation-prerequisites`. +.. [15] You likely need to specify a base64 encoding using an + :ref:`server-info` file for this entry. FAQs ==== -- cgit v1.2.3-1-g7c22 From 368b34bcdd509d24bcc82ccbdbd056455bba7c37 Mon Sep 17 00:00:00 2001 From: Sol Jerome Date: Fri, 3 Jun 2011 19:10:18 -0500 Subject: Base: Deprecate Base in favor of Bundler Signed-off-by: Sol Jerome --- doc/server/plugins/structures/base.txt | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'doc') diff --git a/doc/server/plugins/structures/base.txt b/doc/server/plugins/structures/base.txt index 66d8062e1..03eae0573 100644 --- a/doc/server/plugins/structures/base.txt +++ b/doc/server/plugins/structures/base.txt @@ -6,6 +6,13 @@ 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. -- cgit v1.2.3-1-g7c22 From 129aa6d584765fba5b0ff686d5d8da62b5ae405c Mon Sep 17 00:00:00 2001 From: Sol Jerome Date: Mon, 6 Jun 2011 12:36:56 -0500 Subject: Validate: Create and use new error type for missing schemas Signed-off-by: Sol Jerome --- doc/help/troubleshooting.txt | 110 +++++++++++++++++++++++++------------------ 1 file changed, 64 insertions(+), 46 deletions(-) (limited to 'doc') diff --git a/doc/help/troubleshooting.txt b/doc/help/troubleshooting.txt index ecf53527c..5fe1500f4 100644 --- a/doc/help/troubleshooting.txt +++ b/doc/help/troubleshooting.txt @@ -81,121 +81,138 @@ Type `help` in bcfg2-info for more information. Error Messages ============== -This page describes error messages produced by Bcfg2 and steps that can +The tables below describe error messages produced by Bcfg2 and steps that can be taken to remedy them. +Client Errors +------------- + +------------------------------+----------+---------------------+--------------+ | Error | Location | Meaning | Repair | +==============================+==========+=====================+==============+ -| Incomplete information for | Client | The described entry | [1]_ | +| Incomplete information for | Client | The described entry | [c1]_ | | entry : | | is not fully | | | cannot verify | | specified by the | | | | | server, so no | | | | | verification can be | | | | | performed. | | +------------------------------+----------+---------------------+--------------+ -| Incomplete information for | Client | The described entry | [1]_ | +| Incomplete information for | Client | The described entry | [c1]_ | | entry : | | is not fully | | | cannot install | | specified by the | | | | | server, so no | | | | | verification can be | | | | | performed. | | +------------------------------+----------+---------------------+--------------+ -| The following entries are | Client | The client cannot | [2]_ | +| The following entries are | Client | The client cannot | [c2]_ | | not handled by any tool: | | figure out how to | | | : | | handle this entry. | | +------------------------------+----------+---------------------+--------------+ -| No ca is specified. Cannot | Client | The client is | [3]_ | +| No ca is specified. Cannot | Client | The client is | [c3]_ | | authenticate the server with | | unable to verify | | | SSL. | | the server | | +------------------------------+----------+---------------------+--------------+ -| GID normalization failed for | Client | The client is | [4]_ | +| GID normalization failed for | Client | The client is | [c4]_ | | FILENAME. Does group GROUP | | unable to convert | | | exist? | | the group GROUP to | | | | | a usable GID | | +------------------------------+----------+---------------------+--------------+ -| UID normalization failed for | Client | The client is | [5]_ | +| UID normalization failed for | Client | The client is | [c5]_ | | FILENAME. Does owner OWNER | | unable to convert | | | exist? | | the owner OWNER to | | | | | a usable UID | | +------------------------------+----------+---------------------+--------------+ -| Failed to bind entry: | Server | The server was | [6]_ | + + +.. [c1] This entry is not being bound. Ensure that a version of this + entry applies to this client. +.. [c2] It is possible that the type attribute for this generator entry + is undefined. You may need to add the appropriate type attribute + in the literal entry specification. +.. [c3] Copy the Bcfg2 server's CA certificate to the client and specify it + using the **ca** option in the [communication] section of + ``bcfg2.conf`` +.. [c4] If the group doesn't exist, you need to specify the correct one + in an :ref:`info.xml ` file or set the default group + appropriately. +.. [c5] If the owner doesn't exist, you need to specify the correct one + in an :ref:`info.xml ` file or set the default owner + appropriately. + +Server Errors +------------- + ++------------------------------+----------+---------------------+--------------+ +| Error | Location | Meaning | Repair | ++==============================+==========+=====================+==============+ +| Failed to bind entry: | Server | The server was | [s1]_ | | | | unable to find a | | | | | suitable version of | | | | | entry for client. | | +------------------------------+----------+---------------------+--------------+ -| Failed to bind to socket | Server | The server was | [7]_ | +| Failed to bind to socket | Server | The server was | [s2]_ | | | | unable to bind to | | | | | the tcp server | | | | | socket. | | +------------------------------+----------+---------------------+--------------+ -| Failed to load | Server | The server was | [8]_ | +| Failed to load | Server | The server was | [s3]_ | | ssl key | | unable to read and | | | | | process the ssl key.| | +------------------------------+----------+---------------------+--------------+ -| Failed to read file | Server | The server failed | [9]_ | +| Failed to read file | Server | The server failed | [s4]_ | | | | to read the | | | | | specified file | | +------------------------------+----------+---------------------+--------------+ -| Failed to parse file | Server | The server failed | [10]_ | +| Failed to parse file | Server | The server failed | [s5]_ | | | | to parse the | | | | | specified XML file | | +------------------------------+----------+---------------------+--------------+ -| Client metadata resolution | Server | The server cannot | [11]_ | +| Client metadata resolution | Server | The server cannot | [s6]_ | | error for | | resolve the client | | | | | hostname or the | | | | | client is | | | | | associated with a | | | | | non-profile group. | | +------------------------------+----------+---------------------+--------------+ -| Failed to decode | Server | The encoding being | [12]_ | +| Failed to decode | Server | The encoding being | [s7]_ | | Please verify you are using | | used is unable to | | | the proper encoding | | decode the | | | | | character present | | | | | in this file. | | +------------------------------+----------+---------------------+--------------+ -| Got unknown entries | Server | The Packages plugin | [13]_ | +| Got unknown entries | Server | The Packages plugin | [s8]_ | | [list of unknown entries] | | has no knowledge of | | | | | the listed entries | | +------------------------------+----------+---------------------+--------------+ -| Failed to import lxml | Server | The server cannot | [14]_ | +| Failed to import lxml | Server | The server cannot | [s9]_ | | dependency. Shutting | | import lxml | | | down server. | | | | +------------------------------+----------+---------------------+--------------+ -| You need to specify base64 | Server | The server cannot | [15]_ | +| You need to specify base64 | Server | The server cannot | [s10]_ | | encoding for | | send the file as | | | | | ascii text | | +------------------------------+----------+---------------------+--------------+ +| ERROR: Error reading file | Server | The server cannot | [s11]_ | +| '/path/to/schema': failed to | | find the schema | | +| load external entity | | file | | +| "/path/to/schema" | | | | ++------------------------------+----------+---------------------+--------------+ -.. [1] This entry is not being bound. Ensure that a version of this - entry applies to this client. -.. [2] It is possible that the type attribute for this generator entry - is undefined. You may need to add the appropriate type attribute - in the literal entry specification. -.. [3] Copy the Bcfg2 server's CA certificate to the client and specify it - using the **ca** option in the [communication] section of - ``bcfg2.conf`` -.. [4] If the group doesn't exist, you need to specify the correct one - in an :ref:`info.xml ` file or set the default group - appropriately. -.. [5] If the owner doesn't exist, you need to specify the correct one - in an :ref:`info.xml ` file or set the default owner - appropriately. -.. [6] This entry is not being bound. Ensure that a version of this - entry applies to this client. -.. [7] Ensure that another instance of the daemon (or any other process) - is not listening on the same port. -.. [8] Ensure that the key is readable by the user running the daemon - and that it is well-formed. -.. [9] Ensure that this file still exists; a frequent cause is the - deletion of a temp file. -.. [10] Ensure that the file is properly formed XML. -.. [11] Fix hostname resolution for the client or ensure that the profile +.. [s1] This entry is not being bound. Ensure that a version of this + entry applies to this client. +.. [s2] Ensure that another instance of the daemon (or any other process) + is not listening on the same port. +.. [s3] Ensure that the key is readable by the user running the daemon + and that it is well-formed. +.. [s4] Ensure that this file still exists; a frequent cause is the + deletion of a temp file. +.. [s5] Ensure that the file is properly formed XML. +.. [s6] Fix hostname resolution for the client or ensure that the profile group is properly setup. -.. [12] Ensure the correct encoding is specified in the [components] +.. [s7] Ensure the correct encoding is specified in the [components] section of ``bcfg2.conf``. -.. [13] For packages listed other than **gpg-pubkey**, this error means +.. [s8] For packages listed other than **gpg-pubkey**, this error means that the Packages plugin is unable to find the package in any of the sources listed in ``Packages/config.xml``. The issue often arises when the client is not in one of the groups necessary for @@ -203,10 +220,11 @@ be taken to remedy them. ignore the message as the Packages plugin has no knowledge of these packages (however, note that this package is most often specified as a BoundPackage entry). -.. [14] Ensure that you have installed all the necessary +.. [s9] Ensure that you have installed all the necessary :ref:`installation-prerequisites`. -.. [15] You likely need to specify a base64 encoding using an - :ref:`server-info` file for this entry. +.. [s10] You likely need to specify a base64 encoding using an + :ref:`server-info` file for this entry. +.. [s11] Verify that you have the proper prefix set in bcfg2.conf. FAQs ==== -- cgit v1.2.3-1-g7c22 From fdda835c1c6181589f1eb5fa889056ac26a09347 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Holger=20Wei=C3=9F?= Date: Tue, 7 Jun 2011 13:22:00 +0200 Subject: bcfg2-reports: Show modified entries bcfg2-reports now shows modified entries if it's called with --modifiedentry, -m, or -s. --- doc/reports/dynamic.txt | 52 +++++++++++++++++++++++++++---------------------- 1 file changed, 29 insertions(+), 23 deletions(-) (limited to 'doc') diff --git a/doc/reports/dynamic.txt b/doc/reports/dynamic.txt index 6e0ea8050..ecab980c6 100644 --- a/doc/reports/dynamic.txt +++ b/doc/reports/dynamic.txt @@ -188,29 +188,35 @@ displays:: Usage: python bcfg2-reports [option] ... Options and arguments (and corresponding environment variables): - -a : shows all hosts, including expired hosts - -b NAME : single-host mode - shows bad entries from the - current interaction of NAME - -c : shows only clean hosts - -d : shows only dirty hosts - -e NAME : single-host mode - shows extra entries from the - current interaction of NAME - -h : shows help and usage info about bcfg2-reports - -s NAME : single-host mode - shows bad and extra entries from - the current interaction of NAME - -x NAME : toggles expired/unexpired state of NAME - --badentry=KIND,NAME : shows only hosts whose current interaction has bad - entries in of KIND kind and NAME name; if a single - argument ARG1 is given, then KIND,NAME pairs will be - read from a file of name ARG1 - --extraentry=KIND,NAME : shows only hosts whose current interaction has extra - entries in of KIND kind and NAME name; if a single - argument ARG1 is given, then KIND,NAME pairs will be - read from a file of name ARG1 - --fields=ARG1,ARG2,... : only displays the fields ARG1,ARG2,... - (name,time,state) - --sort=ARG1,ARG2,... : sorts output on ARG1,ARG2,... (name,time,state) - --stale : shows hosts which haven't run in the last 24 hours + -a : shows all hosts, including expired hosts + -b NAME : single-host mode - shows bad entries from the + current interaction of NAME + -c : shows only clean hosts + -d : shows only dirty hosts + -e NAME : single-host mode - shows extra entries from the + current interaction of NAME + -h : shows help and usage info about bcfg2-reports + -m NAME : single-host mode - shows modified entries from the + current interaction of NAME + -s NAME : single-host mode - shows bad, modified, and extra + entries from the current interaction of NAME + -x NAME : toggles expired/unexpired state of NAME + --badentry=KIND,NAME : shows only hosts whose current interaction has bad + entries in of KIND kind and NAME name; if a single + argument ARG1 is given, then KIND,NAME pairs will be + read from a file of name ARG1 + --modifiedentry=KIND,NAME : shows only hosts whose current interaction has + modified entries in of KIND kind and NAME name; if a + single argument ARG1 is given, then KIND,NAME pairs + will be read from a file of name ARG1 + --extraentry=KIND,NAME : shows only hosts whose current interaction has extra + entries in of KIND kind and NAME name; if a single + argument ARG1 is given, then KIND,NAME pairs will be + read from a file of name ARG1 + --fields=ARG1,ARG2,... : only displays the fields ARG1,ARG2,... + (name,time,state) + --sort=ARG1,ARG2,... : sorts output on ARG1,ARG2,... (name,time,state) + --stale : shows hosts which haven't run in the last 24 hours Screenshots =========== -- cgit v1.2.3-1-g7c22 From 80929a6e73eeece44997b84f2beeb38eb3d7645d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Holger=20Wei=C3=9F?= Date: Wed, 8 Jun 2011 17:16:44 +0200 Subject: bcfg2-reports: Show total numbers of entries Add a "-t NAME" option which reports the total (and good) number of managed entries on the host NAME. Also, allow for specifying "total", "good", and "bad" fields via --fields and --sort. --- doc/reports/dynamic.txt | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/reports/dynamic.txt b/doc/reports/dynamic.txt index ecab980c6..4c75cce32 100644 --- a/doc/reports/dynamic.txt +++ b/doc/reports/dynamic.txt @@ -200,6 +200,8 @@ displays:: current interaction of NAME -s NAME : single-host mode - shows bad, modified, and extra entries from the current interaction of NAME + -t NAME : single-host mode - shows total number of managed and + good entries from the current interaction of NAME -x NAME : toggles expired/unexpired state of NAME --badentry=KIND,NAME : shows only hosts whose current interaction has bad entries in of KIND kind and NAME name; if a single @@ -214,8 +216,9 @@ displays:: argument ARG1 is given, then KIND,NAME pairs will be read from a file of name ARG1 --fields=ARG1,ARG2,... : only displays the fields ARG1,ARG2,... - (name,time,state) - --sort=ARG1,ARG2,... : sorts output on ARG1,ARG2,... (name,time,state) + (name,time,state,total,good,bad) + --sort=ARG1,ARG2,... : sorts output on ARG1,ARG2,... + (name,time,state,total,good,bad) --stale : shows hosts which haven't run in the last 24 hours Screenshots -- cgit v1.2.3-1-g7c22 From ac578f15ca785d9b1fcd0d42bfa3ffd017985e78 Mon Sep 17 00:00:00 2001 From: "Chris St. Pierre" Date: Wed, 15 Jun 2011 11:32:29 -0400 Subject: make Bcfg2 automatically handle JSON, XML, and YAML output from probes --- doc/server/plugins/probes/index.txt | 43 +++++++++++++++++++++++++++++++------ 1 file changed, 37 insertions(+), 6 deletions(-) (limited to 'doc') diff --git a/doc/server/plugins/probes/index.txt b/doc/server/plugins/probes/index.txt index b9f698a0f..d52e7bb95 100644 --- a/doc/server/plugins/probes/index.txt +++ b/doc/server/plugins/probes/index.txt @@ -85,10 +85,12 @@ file looks like:: #end if Any Probe script you run will store its output in -``$self.metadata.Probes["scriptname"]``, so we get to our `scratchlocal` -script's output as seen above. Note that we had to wrap the output in an -`int()` call; the script output is treated as a string, so it needs to -be converted before it can be tested numerically. +``$self.metadata.Probes["scriptname"]``, so we get to our +`scratchlocal` script's output as seen above. (See `Handling Probe +Output`_, below, for more information on how this is done.) Note that +we had to wrap the output in an `int()` call; the script output is +treated as a string, so it needs to be converted before it can be +tested numerically. With all of these pieces in place, the following series of events will happen when the client is run: @@ -110,8 +112,37 @@ is to add the ``/etc/auto.master`` to a Bundle: -Host and Group Specific probes -============================== +Handling Probe Output +===================== + +Bcfg2 stores output from probes in the ``Probes`` property of a +client's metadata object. To access this data in TGenshi, for +instance, you could do:: + + ${metadata.Probes['script-name']} + +This is not the full output of the probe; any lines that start with +"group:" have been stripped from the output. The data is a +string-like object that has some interesting and salient features: + +* If the data is a valid XML document, then + ``metadata.Probes['script-name'].xdata`` will be an + ``lxml.etree._Element`` object representing the XML data. +* If the data is a valid JSON document, and the Python ``json`` module + is installed (included in Python 2.6 onward), then + ``metadata.Probes['script-name'].json`` will be a data structure + representing the JSON data. +* If the data is a valid YAML document, and either the Python ``yaml`` + module or ``syck`` module is installed, then + ``metadata.Probes['script-name'].yaml`` will be a data structure + representing the YAML data. + +If these conditions are not met, then the named properties will be +``None``. In all other fashions, the probe data objects should act +like strings. + +Host- and Group-Specific probes +=============================== Bcfg2 has the ability to alter probes based on client hostname and group membership. These files work similarly to files in Cfg. -- cgit v1.2.3-1-g7c22 From eec6ed6c3295755d00abdd40d82b6cfd0a023c2e Mon Sep 17 00:00:00 2001 From: "Chris St. Pierre" Date: Wed, 15 Jun 2011 14:20:18 -0400 Subject: updated docs --- doc/server/plugins/connectors/properties.txt | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) (limited to 'doc') diff --git a/doc/server/plugins/connectors/properties.txt b/doc/server/plugins/connectors/properties.txt index 1cbc4cf65..3329f48bd 100644 --- a/doc/server/plugins/connectors/properties.txt +++ b/doc/server/plugins/connectors/properties.txt @@ -38,7 +38,7 @@ Usage Specific property files can be referred to in templates as ``metadata.Properties[]``. The -data attribute is an LXML element object. (Documented +``xdata`` attribute is an LXML element object. (Documented `here `_) Currently, only one access method is defined for this data, ``Match``. @@ -56,10 +56,21 @@ more details on how Group and Client tags are parsed.) For instance:: As we formulate more common use cases, we will add them to the !PropertyFile class as methods. This will simplify templates. +You can also access the XML data that comprises a property file +directly in one of several ways: + +* ``metadata.Properties['prop-file'].xdata`` is an lxml.etree._Element + object representing the top-level element in the file. +* ``metadata.Properties['prop-file'].data`` is the raw contents of the + property file as a string. +* ``metadata.Properties['prop-file'].entries`` is a list of + lxml.etree._Element objects representing the direct children of the + top-level element. (I.e., everything directly under the + ```` tag.) + Accessing Properties contents from TGenshi ========================================== Access contents of ``Properties/auth.xml``:: - - ${metadata.Properties['auth.xml'].data.find('file').find('bcfg2.key').text} + ${metadata.Properties['auth.xml'].xdata.find('file').find('bcfg2.key').text} -- cgit v1.2.3-1-g7c22 From e145b148dacc9420b2e4253310a0b2f0b07cbada Mon Sep 17 00:00:00 2001 From: Sol Jerome Date: Wed, 15 Jun 2011 15:02:34 -0500 Subject: doc: PY3K Make conf.py more portable Signed-off-by: Sol Jerome --- doc/conf.py | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) (limited to 'doc') diff --git a/doc/conf.py b/doc/conf.py index 77ab6fd94..4b13579d7 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -40,8 +40,13 @@ source_suffix = '.txt' master_doc = 'index' # General information about the project. -project = u'Bcfg2' -copyright = u'2009-%s, Narayan Desai' % time.strftime('%Y') +# py3k compatibility +if sys.hexversion >= 0x03000000: + project = 'Bcfg2' + copyright = '2009-%s, Narayan Desai' % time.strftime('%Y') +else: + project = u'Bcfg2' + copyright = u'2009-%s, Narayan Desai' % time.strftime('%Y') # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -174,10 +179,17 @@ latex_font_size = '11pt' # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass [howto/manual]). -latex_documents = [ - ('contents', 'bcfg2.tex', u'Bcfg2 Documentation', - u'Narayan Desai et al.', 'manual', True), -] +# py3k compatibility +if sys.hexversion >= 0x03000000: + latex_documents = [ + ('contents', 'bcfg2.tex', 'Bcfg2 Documentation', + 'Narayan Desai et al.', 'manual', True), + ] +else: + latex_documents = [ + ('contents', 'bcfg2.tex', u'Bcfg2 Documentation', + u'Narayan Desai et al.', 'manual', True), + ] # The name of an image file (relative to this directory) to place at the top of # the title page. -- cgit v1.2.3-1-g7c22 From e7c215f9f2ddc6936cd98b3ed8b6a391fa96076b Mon Sep 17 00:00:00 2001 From: Sol Jerome Date: Wed, 15 Jun 2011 21:20:27 -0500 Subject: doc: Mention important attribute for gpg-pubkey Paths Signed-off-by: Sol Jerome --- doc/appendix/guides/centos.txt | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'doc') diff --git a/doc/appendix/guides/centos.txt b/doc/appendix/guides/centos.txt index 0b5b83211..ce8e49703 100644 --- a/doc/appendix/guides/centos.txt +++ b/doc/appendix/guides/centos.txt @@ -497,6 +497,18 @@ Then add the files to Cfg:: mkdir -p Cfg/etc/pki/rpm-gpg/RPM-GPG-KEY-EPEL cp /etc/pki/rpm-gpg/RPM-GPG-KEY-EPEL !$/RPM-GPG-KEY-EPEL +You will also want to add an *important* attribute to these files so +that they are installed on the client prior to any attempts to install +the **gpg-pubkey** rpm packages. This is especially important during the +bootstrapping phase and can be accomplished using an :ref:`server-info` +file that looks like the following: + +.. code-block:: xml + + + + + Now, running the client shows only unmanaged Service entries. Woohoo! Manage services -- cgit v1.2.3-1-g7c22 From 3ec2fc27deefc647127c9e729221826a90fd7a96 Mon Sep 17 00:00:00 2001 From: "Chris St. Pierre" Date: Fri, 17 Jun 2011 08:03:26 -0400 Subject: Improved handling of JSON data from probes --- doc/server/plugins/probes/index.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'doc') diff --git a/doc/server/plugins/probes/index.txt b/doc/server/plugins/probes/index.txt index d52e7bb95..5b1f9e259 100644 --- a/doc/server/plugins/probes/index.txt +++ b/doc/server/plugins/probes/index.txt @@ -128,12 +128,12 @@ string-like object that has some interesting and salient features: * If the data is a valid XML document, then ``metadata.Probes['script-name'].xdata`` will be an ``lxml.etree._Element`` object representing the XML data. -* If the data is a valid JSON document, and the Python ``json`` module - is installed (included in Python 2.6 onward), then +* If the data is a valid JSON document, and either the Python ``json`` + or ``simplejson`` module is installed, then ``metadata.Probes['script-name'].json`` will be a data structure representing the JSON data. * If the data is a valid YAML document, and either the Python ``yaml`` - module or ``syck`` module is installed, then + or ``syck`` module is installed, then ``metadata.Probes['script-name'].yaml`` will be a data structure representing the YAML data. -- cgit v1.2.3-1-g7c22 From c358e339e79571db23f329304a470acfe2ec25e6 Mon Sep 17 00:00:00 2001 From: Sol Jerome Date: Fri, 17 Jun 2011 10:26:11 -0500 Subject: doc: Add warning about Group tags in Genshi Bundles Signed-off-by: Sol Jerome --- doc/server/plugins/structures/bundler/index.txt | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'doc') diff --git a/doc/server/plugins/structures/bundler/index.txt b/doc/server/plugins/structures/bundler/index.txt index 6b5c246aa..c74e13e9d 100644 --- a/doc/server/plugins/structures/bundler/index.txt +++ b/doc/server/plugins/structures/bundler/index.txt @@ -146,6 +146,16 @@ The `Genshi templating system`_ is used internally. Use --- +.. warning:: + + Group tags are not used inside of Genshi templates. You can get the + same logic (and more) using Genshi conditionals. + + .. code-xml:: + + + + Bcfg uses the Genshi API for templates, and performs a XML format stream rendering of the template into an lxml entry, which is included in the client configuration. :ref:`Client metadata ` -- cgit v1.2.3-1-g7c22 From 76366b0bf116b0d320ec4a7168de8f62cc50ec98 Mon Sep 17 00:00:00 2001 From: Sol Jerome Date: Sat, 18 Jun 2011 19:41:19 -0500 Subject: POSIX: Add recursive permissions (Ticket #871) This allows for a recursive='true' attribute such that the owner/group can be set recursively for a directory when using Path type='permissions'. Signed-off-by: Sol Jerome --- doc/server/configurationentries.txt | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/server/configurationentries.txt b/doc/server/configurationentries.txt index 10eccf6be..0c12ce9c9 100644 --- a/doc/server/configurationentries.txt +++ b/doc/server/configurationentries.txt @@ -107,8 +107,8 @@ Path type specified. | | | that should not | | | | | exist | | +-------------+----------------------+-----------------+--------------------------+ -| permissions | Replaces Permissions | Permissions of | name, owner, | -| | entries | POSIX entities | group, perms | +| permissions | Replaces Permissions | Permissions of | name, owner, group, | +| | entries | POSIX entities | perms, recursive | | | | | | +-------------+----------------------+-----------------+--------------------------+ | vcs | New | Create version | vcstype (git), | @@ -119,6 +119,19 @@ Path type specified. Keep in mind that permissions for files served up by Cfg/TGenshi/TCheetah are still handled via the traditional :ref:`server-info` mechanisms. +Additional information +---------------------- + +This section describes some additional behavior relating to POSIX entry +attributes. + +Recursive permissions +^^^^^^^^^^^^^^^^^^^^^ + +As per the request in ticket 871, Path type='permissions' entries allow you to +set a recursive attribute which allows the owner/group to be set recursively +for a directory. + .. _boundentries: Bound Entries -- cgit v1.2.3-1-g7c22 From 19586bc42aa90543cf27e33ec32bd7df222138e8 Mon Sep 17 00:00:00 2001 From: Sol Jerome Date: Mon, 20 Jun 2011 12:07:16 -0500 Subject: Cfg: Add support for perms='inherit' (Ticket #642) This feature allows you to use the on-disk permissions of the file in the Cfg repository rather than specifying them using the traditional means in info.xml. Note that this only works for the octal permissions of the file on disk since the owner/group may not exist on the destination machine. Signed-off-by: Sol Jerome --- doc/server/info.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'doc') diff --git a/doc/server/info.txt b/doc/server/info.txt index 231a83a52..f1154e665 100644 --- a/doc/server/info.txt +++ b/doc/server/info.txt @@ -41,6 +41,8 @@ possible fields in an info file are: | paranoid: | yes | no | Backup file before replacement? | no | +------------+-------------------+----------------------------------+---------+ | perms: | Numeric file mode | Sets the permissions of the file | 0644 | +| | | 'inherit' | (or inherits from the files on | | +| | | disk if set to inherit) | | +------------+-------------------+----------------------------------+---------+ A sample info file for CGI script on a web server might look like:: -- cgit v1.2.3-1-g7c22 From c6c8af67d58b7c653e2c70e2ac91bfca4cfbd9fe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Holger=20Wei=C3=9F?= Date: Wed, 22 Jun 2011 14:41:33 +0200 Subject: doc: Sort list of Generators alphabetically In the Server/Plugins overview, move TGenshi to the end of the list of Generators, so that this list is sorted alphabetically. --- doc/server/plugins/index.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/server/plugins/index.txt b/doc/server/plugins/index.txt index 8ef3d5af3..ca1cf459a 100644 --- a/doc/server/plugins/index.txt +++ b/doc/server/plugins/index.txt @@ -65,8 +65,8 @@ Literal Configuration (Generators) :maxdepth: 1 :glob: - generators/tgenshi/index generators/* + generators/tgenshi/index Each of these plugins has a corresponding subdirectory with the same name in the Bcfg2 repository. -- cgit v1.2.3-1-g7c22 From 1186eae0c62ba6810ea597083bd8e56d487811c0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Holger=20Wei=C3=9F?= Date: Wed, 22 Jun 2011 14:47:01 +0200 Subject: doc: Move Deps to the Structure plugins Deps is a Structure plugin, not a Generator. --- doc/server/plugins/generators/deps.txt | 61 ---------------------------------- doc/server/plugins/structures/deps.txt | 61 ++++++++++++++++++++++++++++++++++ 2 files changed, 61 insertions(+), 61 deletions(-) delete mode 100644 doc/server/plugins/generators/deps.txt create mode 100644 doc/server/plugins/structures/deps.txt (limited to 'doc') diff --git a/doc/server/plugins/generators/deps.txt b/doc/server/plugins/generators/deps.txt deleted file mode 100644 index 7c5861d06..000000000 --- a/doc/server/plugins/generators/deps.txt +++ /dev/null @@ -1,61 +0,0 @@ -.. -*- mode: rst -*- - -.. _server-plugins-generators-deps: - -==== -Deps -==== - -The Deps Plugin allows you to make a series of assertions like "Package -X requires Package Y (and optionally also Package Z etc). Note that only -configuration entries, like Package, Path, etc can be used. Groupings -(like Bundle) are not supported. - -Here are some examples: - -.. note:: - - These particular examples are not extremely useful when using the - Packages plugin as Packages will handle the dependency resolution for - you. However, there are certainly other use cases for the Deps plugin. - -Deps/bcfg2.xml -============== - -.. code-block:: xml - - - - - - - - -This basically causes any configuration specification that includes -Package bcfg2 to include python-lxml and isprelink, in a second base -clause. - -Deps/bcfg2-server.xml -===================== - -.. code-block:: xml - - - - - - - - - - - - - - - - - - -This states that the bcfg2-server package (it's a separate package on -some distros) depends on a long list of other packages. diff --git a/doc/server/plugins/structures/deps.txt b/doc/server/plugins/structures/deps.txt new file mode 100644 index 000000000..7c5861d06 --- /dev/null +++ b/doc/server/plugins/structures/deps.txt @@ -0,0 +1,61 @@ +.. -*- mode: rst -*- + +.. _server-plugins-generators-deps: + +==== +Deps +==== + +The Deps Plugin allows you to make a series of assertions like "Package +X requires Package Y (and optionally also Package Z etc). Note that only +configuration entries, like Package, Path, etc can be used. Groupings +(like Bundle) are not supported. + +Here are some examples: + +.. note:: + + These particular examples are not extremely useful when using the + Packages plugin as Packages will handle the dependency resolution for + you. However, there are certainly other use cases for the Deps plugin. + +Deps/bcfg2.xml +============== + +.. code-block:: xml + + + + + + + + +This basically causes any configuration specification that includes +Package bcfg2 to include python-lxml and isprelink, in a second base +clause. + +Deps/bcfg2-server.xml +===================== + +.. code-block:: xml + + + + + + + + + + + + + + + + + + +This states that the bcfg2-server package (it's a separate package on +some distros) depends on a long list of other packages. -- cgit v1.2.3-1-g7c22