From 20479262fe2d860cddb3f1766e83d2a04b0b3a7f Mon Sep 17 00:00:00 2001 From: "Chris St. Pierre" Date: Wed, 9 May 2012 17:07:32 -0400 Subject: added support for validating Cfg file contents using external commands --- doc/server/plugins/generators/cfg.txt | 117 ++++++++++++++++++++++++---------- 1 file changed, 83 insertions(+), 34 deletions(-) (limited to 'doc') 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 + ` 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 ================ -- cgit v1.2.3-1-g7c22