summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorChris St. Pierre <chris.a.st.pierre@gmail.com>2012-05-09 17:07:32 -0400
committerChris St. Pierre <chris.a.st.pierre@gmail.com>2012-05-09 17:07:32 -0400
commit20479262fe2d860cddb3f1766e83d2a04b0b3a7f (patch)
treefd9f6e8cb335ccc2e6d63e0b2d92945b5c74adeb /doc
parent148a01651bbdf627e4848f1b455ccfe79b8b5902 (diff)
downloadbcfg2-20479262fe2d860cddb3f1766e83d2a04b0b3a7f.tar.gz
bcfg2-20479262fe2d860cddb3f1766e83d2a04b0b3a7f.tar.bz2
bcfg2-20479262fe2d860cddb3f1766e83d2a04b0b3a7f.zip
added support for validating Cfg file contents using external commands
Diffstat (limited to 'doc')
-rw-r--r--doc/server/plugins/generators/cfg.txt117
1 files changed, 83 insertions, 34 deletions
diff --git a/doc/server/plugins/generators/cfg.txt b/doc/server/plugins/generators/cfg.txt
index 1c8f6f11a..ba02b929d 100644
--- a/doc/server/plugins/generators/cfg.txt
+++ b/doc/server/plugins/generators/cfg.txt
@@ -93,9 +93,65 @@ classes.
one. That way if a hostname changes or an extra copy of a particular
client is built, it will get the same changes as the original.
+Templates
+=========
+
+Genshi Templates
+----------------
+
+Genshi templates maybe used for entries as well. Any file ending in .genshi
+will be processed using the new template style (like .newtxt in the TGenshi
+plugin).
+
+Cheetah Templates
+-----------------
+
+Cheetah templates maybe used for entries as well. Simply name your file
+with a .cheetah extenstion and it will be processed like the TCheetah
+plugin.
+
+Notes on Using Templates
+------------------------
+
+Templates can be host and group specific as well. Deltas will not be
+processed for any genshi or cheetah base file.
+
+.. note::
+
+ If you are using templating in combination with host-specific
+ or group-specific files, you will need to ensure that the ``.genshi``
+ or ``.cheetah`` extension is at the **end** of the filename. Using the
+ examples from above for *host.example.com* and group *server* you would
+ have the following (using genshi only)::
+
+ Cfg/etc/fstab/fstab.H_host.example.com.genshi
+ Cfg/etc/fstab/fstab.G50_server.genshi
+
+Genshi templates take precence over cheetah templates. For example, if
+two files exist named
+
+ Cfg/etc/fstab/fstab.genshi
+ Cfg/etc/fstab/fstab.cheetah
+
+the cheetah template is ignored. But you can mix genshi and cheetah when
+using different host-specific or group-specific files. For example:
+
+ Cfg/etc/fstab/fstab.H_host.example.com.genshi
+ Cfg/etc/fstab/fstab.G50_server.cheetah
+
Deltas
======
+.. note::
+
+ In Bcfg2 1.3 and newer, deltas are deprecated. It is recommended
+ that you use templates instead. The
+ :ref:`TemplateHelper plugin
+ <server-plugins-connectors-templatehelper>` comes with an example
+ helper that can be used to include other files easily, a subset of
+ cat file functionality. ``bcfg2-lint`` checks for deltas and
+ warns about them.
+
Bcfg2 has finer grained control over how to deliver configuration
files to a host. Let's say we have a Group named file-server. Members
of this group need the exact same ``/etc/motd`` as all other hosts except
@@ -150,51 +206,44 @@ file. The reason the other deltas aren't applied to *foo.example.com*
is because a **.H_** delta is more specific than a **.G##_** delta. Bcfg2
applies all the deltas at the most specific level.
-Templates
-=========
-
-Genshi Templates
-----------------
-
-Genshi templates maybe used for entries as well. Any file ending in .genshi
-will be processed using the new template style (like .newtxt in the TGenshi
-plugin).
+Content Validation
+==================
-Cheetah Templates
------------------
+To ensure that files with invalid content are not pushed out, you can
+provide a content validation script that will be run against each
+file. Create a file called ``:test`` inside the directory for the
+file you want to test. For example::
-Cheetah templates maybe used for entries as well. Simply name your file
-with a .cheetah extenstion and it will be processed like the TCheetah
-plugin.
+ Cfg/etc/sudoers/:test
-Notes on Using Templates
-------------------------
+You can also create host- and group-specific validators::
-Templates can be host and group specific as well. Deltas will not be
-processed for any genshi or cheetah base file.
+ Cfg/etc/sudoers/:test.G80_foogroup
+ Cfg/etc/sudoers/:test.H_bar.example.com
-.. note::
+A validator script has the following attributes:
- If you are using templating in combination with host-specific
- or group-specific files, you will need to ensure that the ``.genshi``
- or ``.cheetah`` extension is at the **end** of the filename. Using the
- examples from above for *host.example.com* and group *server* you would
- have the following (using genshi only)::
+* It must be executable, or specify a valid bangpath;
+* The entire content of the file is passed to the validator on
+ stdin;
+* The validator is not called with any flags or arguments;
+* The validator must return 0 on success and non-zero on failure; and
+* The validator must output a sensible error message on failure.
- Cfg/etc/fstab/fstab.H_host.example.com.genshi
- Cfg/etc/fstab/fstab.G50_server.genshi
+For ``sudoers``, a very simple validator is::
-Genshi templates take precence over cheetah templates. For example, if
-two files exist named
+ #!/bin/sh
+ visudo -cf -
- Cfg/etc/fstab/fstab.genshi
- Cfg/etc/fstab/fstab.cheetah
+This uses the ``visudo`` command's built-in validation.
-the cheetah template is ignored. But you can mix genshi and cheetah when
-using different host-specific or group-specific files. For example:
+.. note:
- Cfg/etc/fstab/fstab.H_host.example.com.genshi
- Cfg/etc/fstab/fstab.G50_server.cheetah
+ Before 1.3 is released, it will be possible to disable validation
+ in the configuration, but enable it for ``bcfg2-test``. This is
+ recommended for heavily-used servers, since running an external
+ command is fairly resource intensive and could quickly exhaust the
+ file descriptors of a server.
File permissions
================