From 552fa7b683dcdcbbc58dc2871e31f54d8db14a64 Mon Sep 17 00:00:00 2001 From: "Chris St. Pierre" Date: Wed, 26 Sep 2012 12:18:23 -0400 Subject: rolled genshi/cheetah docs into cfg, deprecated old tgenshi/tcheetah docs --- doc/appendix/guides/authentication.txt | 5 +- doc/getting_started/index.txt | 1 + doc/getting_started/macosx/notes.txt | 111 ++++---- doc/glossary.txt | 2 +- doc/help/troubleshooting.txt | 2 +- doc/server/configurationentries.txt | 109 +------- doc/server/info.txt | 11 +- doc/server/plugins/connectors/properties.txt | 4 +- doc/server/plugins/generators/cfg.txt | 170 +++++++++++- doc/server/plugins/generators/decisions.txt | 8 +- .../generators/examples/cheetah/crontab.txt | 26 ++ .../plugins/generators/examples/cheetah/simple.txt | 53 ++++ .../generators/examples/genshi/bcfg2-cron.txt | 23 ++ .../generators/examples/genshi/clientsxml.txt | 90 ++++++ .../plugins/generators/examples/genshi/ganglia.txt | 172 ++++++++++++ .../generators/examples/genshi/grubconf.txt | 33 +++ .../plugins/generators/examples/genshi/hosts.txt | 19 ++ .../generators/examples/genshi/iptables.txt | 300 ++++++++++++++++++++ .../plugins/generators/examples/genshi/motd.txt | 98 +++++++ .../plugins/generators/examples/genshi/mycnf.txt | 31 +++ .../plugins/generators/examples/genshi/test.txt | 144 ++++++++++ doc/server/plugins/generators/packages.txt | 17 +- doc/server/plugins/generators/pkgmgr.txt | 6 +- doc/server/plugins/generators/sslca.txt | 3 +- doc/server/plugins/generators/tcheetah.txt | 5 + doc/server/plugins/generators/tgenshi.txt | 213 ++++++++++++++ .../plugins/generators/tgenshi/bcfg2-cron.txt | 25 -- .../plugins/generators/tgenshi/clientsxml.txt | 94 ------- doc/server/plugins/generators/tgenshi/ganglia.txt | 174 ------------ doc/server/plugins/generators/tgenshi/grubconf.txt | 35 --- doc/server/plugins/generators/tgenshi/hosts.txt | 21 -- doc/server/plugins/generators/tgenshi/index.txt | 215 --------------- doc/server/plugins/generators/tgenshi/iptables.txt | 306 --------------------- doc/server/plugins/generators/tgenshi/motd.txt | 169 ------------ doc/server/plugins/generators/tgenshi/mycnf.txt | 34 --- doc/server/plugins/generators/tgenshi/test.txt | 159 ----------- doc/server/plugins/grouping/metadata.txt | 75 +++-- doc/server/plugins/index.txt | 1 - doc/server/plugins/probes/index.txt | 29 +- doc/server/plugins/structures/altsrc.txt | 35 +-- doc/server/plugins/structures/bundler/index.txt | 5 +- doc/unsorted/howtos.txt | 2 - doc/unsorted/windows.txt | 2 +- doc/unsorted/writing_specification.txt | 2 +- 44 files changed, 1544 insertions(+), 1495 deletions(-) create mode 100644 doc/server/plugins/generators/examples/cheetah/crontab.txt create mode 100644 doc/server/plugins/generators/examples/cheetah/simple.txt create mode 100644 doc/server/plugins/generators/examples/genshi/bcfg2-cron.txt create mode 100644 doc/server/plugins/generators/examples/genshi/clientsxml.txt create mode 100644 doc/server/plugins/generators/examples/genshi/ganglia.txt create mode 100644 doc/server/plugins/generators/examples/genshi/grubconf.txt create mode 100644 doc/server/plugins/generators/examples/genshi/hosts.txt create mode 100644 doc/server/plugins/generators/examples/genshi/iptables.txt create mode 100644 doc/server/plugins/generators/examples/genshi/motd.txt create mode 100644 doc/server/plugins/generators/examples/genshi/mycnf.txt create mode 100644 doc/server/plugins/generators/examples/genshi/test.txt create mode 100644 doc/server/plugins/generators/tgenshi.txt delete mode 100644 doc/server/plugins/generators/tgenshi/bcfg2-cron.txt delete mode 100644 doc/server/plugins/generators/tgenshi/clientsxml.txt delete mode 100644 doc/server/plugins/generators/tgenshi/ganglia.txt delete mode 100644 doc/server/plugins/generators/tgenshi/grubconf.txt delete mode 100644 doc/server/plugins/generators/tgenshi/hosts.txt delete mode 100644 doc/server/plugins/generators/tgenshi/index.txt delete mode 100644 doc/server/plugins/generators/tgenshi/iptables.txt delete mode 100644 doc/server/plugins/generators/tgenshi/motd.txt delete mode 100644 doc/server/plugins/generators/tgenshi/mycnf.txt delete mode 100644 doc/server/plugins/generators/tgenshi/test.txt diff --git a/doc/appendix/guides/authentication.txt b/doc/appendix/guides/authentication.txt index 68a232f6f..3fd0e1e2d 100644 --- a/doc/appendix/guides/authentication.txt +++ b/doc/appendix/guides/authentication.txt @@ -32,8 +32,9 @@ Scenarios Building bcfg2.conf automatically ================================= -This is a TCheetah template that automatically constructs per-client -bcfg2.conf from the per-client metadata:: +This is a :ref:`Cheetah template +` that automatically constructs +per-client bcfg2.conf from the per-client metadata:: [communication] protocol = xmlrpc/ssl diff --git a/doc/getting_started/index.txt b/doc/getting_started/index.txt index 034584014..a9e91e6b8 100644 --- a/doc/getting_started/index.txt +++ b/doc/getting_started/index.txt @@ -256,3 +256,4 @@ Platform-specific Quickstart Notes * :ref:`appendix-guides-centos` * :ref:`appendix-guides-ubuntu` +* :ref:`getting_started-macosx-notes` diff --git a/doc/getting_started/macosx/notes.txt b/doc/getting_started/macosx/notes.txt index 88178fee9..4527f11fc 100644 --- a/doc/getting_started/macosx/notes.txt +++ b/doc/getting_started/macosx/notes.txt @@ -1,76 +1,93 @@ -= Setting up Bcfg2 From Scratch = +.. -*- mode: rst -*- -Ala [[http://blog.conpocococo.org/post/6079832974/managing-etc-motd-with-bcfg2-starting-from-an-empty-vm|Managing /etc/motd with Bcfg2 Starting From an Empty VM]], I'll be setting up a fresh OS X 10.6 machine to be managed by [[http://bcfg2.org|Bcfg2]]. +.. _getting_started-macosx-notes: -== Get OS X 10.6 Running == +=============================== + Setting up Bcfg2 From Scratch +=============================== -Use your favorite provisioning method (e.g. open-box-then-push-power-button, DVD, [[http://www.deploystudio.com/Home.html|DeplyStudio]], etc) to get your operating system running and fully patched. +Ala `Managing /etc/motd with Bcfg2 Starting From an Empty VM +`_, +I'll be setting up a fresh OS X 10.6 machine to be managed by Bcfg2. + +Get OS X 10.6 Running +===================== + +Use your favorite provisioning method to get your operating system +running and fully patched. For this hands on, I'm running OS X 10.6.8 (Build 10K540) with the -supplied python 2.6.1. I've also turned on Remote Login (i.e. ssh) so I -can use my client to write this document going through the steps; having -ssh on is not a requirement for this howto. +supplied python 2.6.1. I've also turned on Remote Login (i.e. ssh) so +I can use my client to write this document going through the steps; +having ssh on is not a requirement for this howto. + +Get bcfg2-server Working +======================== -== Get bcfg2-server Working == +Get bcfg2 package +----------------- -=== Get bcfg2 package === +You might be able to get a package already built for you, but it is +not hard to build it from the source. You'll need git (via +`git-osx-installer `_ or +`homebrew `_; the former is +easier, the later more developer friendly) and Apple's `XCode +`_. -You might be able to get a package already built for you, but it is not hard to build it from the source. You'll need git (via [[https://code.google.com/p/git-osx-installer/|git-osx-installer]] or [[https://github.com/mxcl/homebrew|homebrew]] the former is easier, the later more developer friendly) and Apple's [[http://developer.apple.com/xcode/|xcode]]. +The first step is to clone the bcfg2 repository into a working +directory: -The first step is to clone the bcfg2 repository into a working directory: +.. code-block: bash -{{{#!highlight bash -cd ~/Devloper -git clone git://git.mcs.anl.gov/bcfg2.git -cd bcfg2 -}}} + cd ~/Developer + git clone https://github.com/Bcfg2/bcfg2.git + cd bcfg2 -At this point you will probably want to checkout a release tag (`git tag -l` to -see a list of them). This test is using v1.2.0pre4. Once you've done -that you can build the server. +At this point you will probably want to checkout a release tag (`git +tag -l` to see a list of them). This test is using v1.2.0pre4. Once +you've done that you can build the server. -{{{#!highlight bash -git checkout v1.2.0pre4 -cd osx -make server -}}} +.. code-block: bash -The server package contains both the client and the server. The package -is located at ./osx/bcfg2-VERSION.pkg. Copy it to the machine you want -to set up from scratch and install it. + git checkout v1.2.0pre4 + cd osx + make server + +The server package contains both the client and the server. The +package is located at ``./osx/bcfg2-VERSION.pkg``. Copy it to the machine +you want to set up from scratch and install it. THIS NEEDS TO VERIFIED -Some of the differences between bcfg2 on Mac OS X and Debian is that the -libraries are stored at + +Some of the differences between bcfg2 on Mac OS X and Debian is that +the libraries are stored at `/Library/Frameworks/Python.framework/Versions/Current/share/bcfg2/` -`/Library/Python/site-packages/Bcfg2/` -instead of `/usr/lib/pymodules/` and `/usr/share/pyshare/Bcfg2. Also, -instead of cron and init.d, -`/Library/LaunchDaemons/gov.anl.mcs.bcfg2-daily.plist` controls peridic -runs and starts and stops. The runtime files are stored in +`/Library/Python/site-packages/Bcfg2/` instead of +`/usr/lib/pymodules/` and `/usr/share/pyshare/Bcfg2. Also, instead of +cron and init.d, +`/Library/LaunchDaemons/gov.anl.mcs.bcfg2-daily.plist` controls +peridic runs and starts and stops. The runtime files are stored in `/usr/local/bin` under Mac OS X instead of /usr/sbin/ for Debian. -VERIFY -Error: bcfg2-admin init -""" -10.6_client :~ user$ sudo /usr/local/bin/bcfg2-admin init -Failed to import lxml dependency. Shutting down server. -""" +VERIFY:: + + 10.6_client :~ user$ sudo /usr/local/bin/bcfg2-admin init + Failed to import lxml dependency. Shutting down server. -Try: sudo easy_install lxml. If you don't have gcc-4.2 installed, you'll -need to install it on a machine that does. Then move +Try: sudo easy_install lxml. If you don't have gcc-4.2 installed, +you'll need to install it on a machine that does. Then move `/Library/Python/2.6/sites-packages/lxml-2.3-py2.6-macosx-10.6-universal.egg` to the client and add the line "./lxml-2.3-py2.6-macosx-10.6-universal.egg" to `/Library/Python/2.6/site-packages/easy-install.pth`. -getting a new error: +Getting a new error:: -$ sudo /usr/local/bin/bcfg2-admin init -Interactively initialize a new repository. + $ sudo /usr/local/bin/bcfg2-admin init + Interactively initialize a new repository. -bcfg2-admin init -$ + bcfg2-admin init + $ So what is lxml easy_install fully installing? Need to make a package (Lettuce to the rescue!) diff --git a/doc/glossary.txt b/doc/glossary.txt index 06f67dab9..2f88d3a8c 100644 --- a/doc/glossary.txt +++ b/doc/glossary.txt @@ -15,7 +15,7 @@ Glossary generator A type of plugin which provides file contents. For example :ref:`server-plugins-generators-cfg` or - :ref:`server-plugins-generators-tgenshi-index`. + :ref:`server-plugins-generators-sshbase`. Genshi A Python-based templating engine. `Genshi Homepage`_. diff --git a/doc/help/troubleshooting.txt b/doc/help/troubleshooting.txt index d32e2c063..8a8d00970 100644 --- a/doc/help/troubleshooting.txt +++ b/doc/help/troubleshooting.txt @@ -56,7 +56,7 @@ system. In the ticket, include: seconds" appeared between the modification event and the client configuration generation request appeared in the server log * which plugin handled the file in the repostiory (Cfg, Rules, Packages, - TCheetah, TGenshi, Metadata) + SSHbase, Metadata, etc.) * if a touch of the file after the modification causes the problem to go away diff --git a/doc/server/configurationentries.txt b/doc/server/configurationentries.txt index fb1589926..66ff617c0 100644 --- a/doc/server/configurationentries.txt +++ b/doc/server/configurationentries.txt @@ -32,107 +32,10 @@ Example: -Fun and Profit using altsrc -=========================== +altsrc +====== -Altsrc is a generic, bcfg2-server-side mechanism for performing -configuration entry name remapping for the purpose of data binding. - -Use Cases ---------- - -* Equivalent configuration entries on different architectures with - different names - -* Mapping entries with the same name to different bind results in a - configuration (two packages with the same name but different types) - -* A single configuration entry across multiple specifications - (multi-plugin, or multi-repo) - -Examples --------- - -* Consider the case of ``/etc/hosts`` on linux and ``/etc/inet/hosts`` - on solaris. These files contain the same data in the same format, - and should typically be synchronized, however, exist in different - locations. Classically, one would need to create one entry for each - in :ref:`server-plugins-generators-cfg` or - :ref:`server-plugins-generators-tcheetah` and perform manual - synchronization. Or, you could use symlinks and pray. Altsrc is - driven from the bundle side. For example: - - .. code-block:: xml - - - - - - - - - - - In this case, when a solaris host gets the 'netinfo' bundle, it will - get the first Path entry, which includes an altsrc parameter. This - will cause the server to bind the entry as if it were a Path - called ``/etc/hosts``. This configuration entry is still called - ``/etc/inet/hosts``, and is installed as such. - -* On encap systems, frequently multiple packages of the same name, but - of different types will exist. For example, there might be an openssl - encap package, and an openssl rpm package. This can be dealt with - using a bundle like: - - .. code-block:: xml - - - - - - - This bundle will bind data for the packages "openssl-encap" and - "openssl-rpm", but will be delivered to the client with both packages - named "openssl" with different types. - -* Finally, consider the case where there exist complicated, but - completely independent specifications for the same configuration - entry but different groups of clients. The following bundle will - allow the use of two different - :ref:`server-plugins-generators-tcheetah` templates - ``/etc/firewall-rules-external`` and - ``/etc/firewall-rules-internal`` for different clients based on - their group membership. - - .. code-block:: xml - - - ... - - - - - - - - -* Consider the case where a variety of files can be constructed by a - single template (:ref:`server-plugins-generators-tcheetah` or - :ref:`server-plugins-generators-tgenshi-index`). It would be - possible to copy this template into the proper location for each - file, but that requires proper synchronization upon modification and - knowing up front what the files will all be called. Instead, the - following bundle allows the use of a single template for all proper - config file instances. - - .. code-block:: xml - - - - - - - - altsrc can be used as a parameter for any entry type, and can be - used in any structure, including - :ref:`server-plugins-structures-bundler-index`. +The ``altsrc`` attribute lets you remap configuration entry names on +the server side so you can reuse a single concrete representation for +multiple abstract entries. See +:ref:`server-plugins-structures-altsrc` for more details. diff --git a/doc/server/info.txt b/doc/server/info.txt index 5c2279b73..69f926aad 100644 --- a/doc/server/info.txt +++ b/doc/server/info.txt @@ -6,12 +6,11 @@ Info ==== -Various file properties for entries served by the :ref:`Cfg -`, :ref:`TGenshi -`, :ref:`TCheetah -`, and :ref:`SSHbase -` plugins are controlled through -the use of ``info.xml`` files. +Various file properties for entries served by most generator plugins, +including :ref:`server-plugins-generators-cfg`, +:ref:`server-plugins-generators-sslca`, and +:ref:`server-plugins-generators-sshbase`, are controlled through the +use of ``info.xml`` files. By default, these plugins are set to write files to the filesystem with owner **root**, group **root**, and mode **644** (read and write diff --git a/doc/server/plugins/connectors/properties.txt b/doc/server/plugins/connectors/properties.txt index 0fb7e8511..e10b90df9 100644 --- a/doc/server/plugins/connectors/properties.txt +++ b/doc/server/plugins/connectors/properties.txt @@ -208,8 +208,8 @@ See :ref:`server-encryption` for more details on encryption in Bcfg2 in general. -Accessing Properties contents from TGenshi -========================================== +Accessing Properties contents from Genshi Templates +=================================================== Access contents of ``Properties/auth.xml``:: diff --git a/doc/server/plugins/generators/cfg.txt b/doc/server/plugins/generators/cfg.txt index 2987e21b9..fce0439b5 100644 --- a/doc/server/plugins/generators/cfg.txt +++ b/doc/server/plugins/generators/cfg.txt @@ -20,7 +20,7 @@ repository location of ``/var/lib/bcfg2``. The contents of this directory are a series of directories corresponding to the real-life locations of the files on your clients, starting at the root level. For example:: - lueningh@tg-prez:~/bcfg2/repository> ls Cfg + % ls Cfg bin/ boot/ etc/ opt/ root/ usr/ var/ Specific config files go in like-named directories in this @@ -96,19 +96,175 @@ classes. Templates ========= +.. _server-plugins-generators-cfg-genshi: + 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). +Genshi templates allow you to use the `Genshi +`_ templating system. This is similar to +the deprecated :ref:`server-plugins-generators-tgenshi-index` plugin. +Genshi templates should be named with a ``.genshi`` extension, e.g.:: + + % ls Cfg/etc/motd + info.xml motd.genshi + +See the genshi `documentation +`_ for examples of +Genshi syntax. + +Inside Genshi Templates +~~~~~~~~~~~~~~~~~~~~~~~ + +Several variables are pre-defined inside templates: + +* **metadata** is the client's :ref:`metadata + ` +* **name** is the path name specified in Bcfg2 +* **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`` + +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 + +To generate a file with an altsrc attribute, you can run:: + + bcfg2-info buildfile /etc/foo/foo.conf --altsrc=/etc/foo.conf \ + foo.example.com + +Sometimes, it's useful to be able to do more in-depth troubleshooting +by running the template manually. To do this, run ``bcfg2-info +debug``, and, once in the Python interpreter, run:: + + metadata = self.build_metadata("") + path = "" + +``path`` should be set to the path to the template file with a leading +slash, relative to the Bcfg2 specification root. See `Inside Genshi +Templates`_ for examples. + +Then, run:: + + import os, Bcfg2.Options + from genshi.template import TemplateLoader, NewTextTemplate + name = os.path.dirname(path[path.find('/', 1):]) + setup = Bcfg2.Options.OptionParser({'repo': + Bcfg2.Options.SERVER_REPOSITORY}) + setup.parse('--') + template = TemplateLoader().load(setup['repo'] + 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" + name = "/etc/sysconfig/network-scripts/ifcfg-bond0" + +Error handling +~~~~~~~~~~~~~~ + +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:: + + {% python + from genshi.template import TemplateError + grp = None + for g in metadata.groups: + if g.startswith('ganglia-gmond-'): + grp = g + break + else: + raise TemplateError, "Missing group" + %}\ + +will fail to bind if the client is not a member of a group starting with +"ganglia-gmond-". The syslogs on the server will contain this message:: + + bcfg2-server[5957]: Genshi template error: Missing group + bcfg2-server[5957]: Failed to bind entry: Path /etc/ganglia/gmond.conf + +...indicating the bind failure and message raised with the TemplateError. + +Handling Dollar Signs +~~~~~~~~~~~~~~~~~~~~~ + +In a Genshi template, ``$`` is a special character and must be escaped +by doubling, i.e., ``$$``. For instance, to embed the Subversion +``$Id$`` keyword in a Genshi template, you would have to do ``$$Id$$``. + +Examples +~~~~~~~~ + +.. toctree:: + :glob: + :maxdepth: 1 + + examples/genshi/* + +.. _server-plugins-generators-cfg-cheetah: 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. +Cheetah templates allow you to use the `cheetah templating system +`_. This is similar to +the deprecated :ref:`server-plugins-generators-tcheetah` plugin. +Cheetah templates should be named with a ``.cheetah`` extension, e.g.:: + + % ls Cfg/etc/motd + info.xml motd.cheetah + +Inside Cheetah Templates +~~~~~~~~~~~~~~~~~~~~~~~~ + +Several variables are pre-defined inside templates: + +* **self.metadata** is the client's :ref:`metadata + ` +* **self.path** is the path name specified in Bcfg2 +* **self.source_path** is the path to the Genshi template on the filesystem. + +Examples +~~~~~~~~ + +.. toctree:: + :glob: + :maxdepth: 1 + + examples/cheetah/* + +Comments and Cheetah +~~~~~~~~~~~~~~~~~~~~ + +As Cheetah processes your templates it will consider hash "#" style +comments to be actual comments in the template and will strip them +from the final config file. If you would like to preserve the comment +in the final config file you need to escape the hash character '\#' +which will tell Cheetah (and Python) that you do in fact want the +comment to appear in the final config file.:: + + # This is a comment in my template which will be stripped when it's processed through Cheetah + \# This comment will appear in the generated config file. + Notes on Using Templates ------------------------ diff --git a/doc/server/plugins/generators/decisions.txt b/doc/server/plugins/generators/decisions.txt index acb1de6ee..9a40ab8fd 100644 --- a/doc/server/plugins/generators/decisions.txt +++ b/doc/server/plugins/generators/decisions.txt @@ -30,10 +30,10 @@ client's whitelists or blacklists. 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- -and group-specific files and the like after their basename). File basenames -are either ``whitelist`` or ``blacklist``. These files have a simple format; -the following is an example. +files managed by Cfg and Probes, so you can use host- and +group-specific files and the like after their basename. File basenames +are either ``whitelist`` or ``blacklist``. These files have a simple +format; the following is an example. .. code-block:: xml diff --git a/doc/server/plugins/generators/examples/cheetah/crontab.txt b/doc/server/plugins/generators/examples/cheetah/crontab.txt new file mode 100644 index 000000000..4fe5485c3 --- /dev/null +++ b/doc/server/plugins/generators/examples/cheetah/crontab.txt @@ -0,0 +1,26 @@ +.. -*- mode: rst -*- + +============================ +Writing crontab with Cheetah +============================ + +This example randomizes the time of cron.daily +execution with a stable result. Cron.daily is run at a consistent, +randomized time between midnight and 7am.:: + + #import random + #silent random.seed($self.metadata.hostname) + + # /etc/crontab: system-wide crontab + # Unlike any other crontab you don't have to run the `crontab` + # command to install the new version when you edit this file. + # This file also has a username field, that none of the other crontabs do. + + SHELL=/bin/sh + PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin://bin + + # m h dom mon dow user command + 17 * * * * root run-parts --report /etc/cron.hourly + $random.randrange(0,59) $random.randrange(0,6) * * * root test -x /usr/sbin/anacron || run-parts --report /etc/cron.daily + 47 6 * * 7 root test -x /usr/sbin/anacron || run-parts --report /etc/cron.weekly + 52 6 1 * * root test -x /usr/sbin/anacron || run-parts --report /etc/cron.monthly. diff --git a/doc/server/plugins/generators/examples/cheetah/simple.txt b/doc/server/plugins/generators/examples/cheetah/simple.txt new file mode 100644 index 000000000..fd6048e84 --- /dev/null +++ b/doc/server/plugins/generators/examples/cheetah/simple.txt @@ -0,0 +1,53 @@ +.. -*- mode: rst -*- + +========================= + Basic Cheetah Templates +========================= + +This simple example demonstrates basic usage of Cheetah templates. + +``/var/lib/bcfg2/Cfg/foo/foo.cheetah`` + +.. code-block:: none + + Hostname is $self.metadata.hostname + Filename is $self.path + Template is $self.source_path + Groups: + #for $group in $self.metadata.groups: + * $group + #end for + Categories: + #for $category in $self.metadata.categories: + * $category -- $self.metadata.categories[$category] + #end for + + Probes: + #for $probe in $self.metadata.Probes: + * $probe -- $self.metadata.Probes[$probe] + #end for + +Output +====== + +.. code-block:: xml + + + Hostname is topaz.mcs.anl.gov + Filename is /foo + Template is /var/lib/bcfg2/Cfg/foo/foo.cheetah + Groups: + * desktop + * mcs-base + * ypbound + * workstation + * xserver + * debian-sarge + * debian + * a + Categories: + * test -- a + + Probes: + * os -- debian + diff --git a/doc/server/plugins/generators/examples/genshi/bcfg2-cron.txt b/doc/server/plugins/generators/examples/genshi/bcfg2-cron.txt new file mode 100644 index 000000000..1c4bd3a3c --- /dev/null +++ b/doc/server/plugins/generators/examples/genshi/bcfg2-cron.txt @@ -0,0 +1,23 @@ +.. -*- mode: rst -*- + +bcfg2-cron +========== + +As submitted by Kamil Kisiel + +The following is my ``/etc/cron.d/bcfg2`` file. It uses the python random +module seeded with the client hostname to generate a random time for the +client to check in. The hostname seed ensures the generated file is the +same each time the client checks in. This cron file helps to distribute +the load on the Bcfg2 server since not all machines are checking in at +the same time.:: + + {% python + from genshi.builder import tag + import random + random.seed(metadata.hostname) + %}\ + ${random.randint(0,60)} * * * * root /usr/sbin/bcfg2 &> /dev/null + +You can apply the same concept to the other time fields by adding another +``${random.randint()}`` call. diff --git a/doc/server/plugins/generators/examples/genshi/clientsxml.txt b/doc/server/plugins/generators/examples/genshi/clientsxml.txt new file mode 100644 index 000000000..548c388d2 --- /dev/null +++ b/doc/server/plugins/generators/examples/genshi/clientsxml.txt @@ -0,0 +1,90 @@ +.. -*- mode: rst -*- + +clients.xml +=========== + +As submitted by dclark + +Here is an example of maintaining the bcfg2 server's +``/var/lib/bcfg2/Metadata/clients.xml`` file using Genshi templates. + +There are two main advantages: + +#. Password storage is centralized in the ``Properties/passwords.xml`` + file this helps maintain consistency, makes changing passwords + easier, and also makes it easier to share your configurations with + other sites/people. +#. You can template the file using Genshi's `{% def %}` syntax, + which makes `clients.xml` much more readable. An important + thing to note is how the `name` variable is handled - when + just referring to it the standard `${name}` syntax is used, but + when it is used as a variable in the expression to get the password, + `password="${metadata.Properties['passwords.xml'].xdata.find('password').find('bcfg2-client').find(name).text}"`, + it is just referred to as `name`. + +There is the disadvantage that sometimes 2 passes will be needed to get +to a consistent state. + +Possible improvements: + +#. Wrapper for bcfg2 client runs on the bcfg2 server, perhaps using a call + to `bcfg2-info buildfile`, so clients.xml is always generated before + everything else happens (since the state of clients.xml can influence + everything else bcfg2-server does). + +#. We really don't care what the client passwords are, just that they + exist, so instead of listing them a master password combined with + some kind of one-way hash based on the `name` might make more sense, + and make ``Properties/passwords.xml`` easier to maintain. + + * Cfg/var/lib/bcfg2/Metadata/clients.xml/clients.xml.genshi: + + .. code-block:: xml + + + + {# Doc: http://bcfg2.org/wiki/Authentication #}\ + {% def static(profile,name,address) %} + \ + {% end %}\ + {% def dynamic(profile,name) %} + \ + {% end %}\ + \ + ${static('group-server-collab','campaigns.example.com','192.168.111.1')} + ${static('group-server-collab','info.office.example.com','192.168.111.2')} + ${static('group-server-config','config.example.com','192.168.111.3')} + ${dynamic('group-project-membercard','membercard')} + ${dynamic('group-person-somename','somename.office.example.com')} + + + * Properties/passwords.xml snippit: + + .. code-block:: xml + + + + + FAKEpassword1 + FAKEpassword2 + FAKEpassword3 + FAKEpassword4 + FAKEpassword5 + + + diff --git a/doc/server/plugins/generators/examples/genshi/ganglia.txt b/doc/server/plugins/generators/examples/genshi/ganglia.txt new file mode 100644 index 000000000..3a20fde92 --- /dev/null +++ b/doc/server/plugins/generators/examples/genshi/ganglia.txt @@ -0,0 +1,172 @@ +.. -*- mode: rst -*- + +ganglia +======= + +Another interesting example of Genshi templating is to automatically +generate ``gmond``/``gmetad`` configuration files. The idea is that +each cluster is headless: it communicates with the rest of the cluster +members on an isolated multicast IP address and port. Any of the +cluster members is therefore isolated on that particular ip/port +pair. Additionally, each ``gmond`` instance **also** listens on +UDP. This allows for any of the cluster members to be polled for +information on the entire cluster! + +The second part of the trick is in ``gmetad.conf``. Here, we +dynamically generate a list of clusters (based on profiles names) and +a list of members to poll (based on the clients in said profiles). As +the number of profiles and client grows, this list will grow +automatically as well. When a new host is added, ``gmetad`` will +receive an updated configuration and act accordingly. + +There **is** one caveat though. The ``gmetad.conf`` parser is hard +coded to read 16 arguments per ``data_source`` line. If you have more +than 15 nodes in a cluster, you will see a warning in the logs. You +can either ignore it, or truncate the list to the first 15 members. + +In our environment, a profile is a one to one match with the role of +that particular host. You can also do this based on groups, or any +other client property. + +Bundler/ganglia.xml +------------------- + +.. code-block:: xml + + + + + + + + + + + + + + + + + +Rules/services-ganglia.xml +-------------------------- + +.. code-block:: xml + + + + + + + + +Cfg/etc/ganglia/gmetad.conf/gmetad.conf.genshi +---------------------------------------------- + +.. code-block:: none + + {% python + client_metadata = metadata.query.all() + profile_array = {} + seen = [] + for item in client_metadata: + if item.profile not in seen: + seen.append(item.profile) + profile_array[item.profile]=[] + profile_array[item.profile].append(item.hostname) + seen.sort() + %}\ + + gridname "Our Grid" + + {% for profile in seen %} + data_source "${profile}" \ + {% for host in profile_array[profile] %}\ + ${host} \ + {% end %}\ + {% end %} + + rrd_rootdir "/var/lib/ganglia/rrds" + +Cfg/etc/ganglia/gmond.conf/gmod.conf.genshi +------------------------------------------- + +.. code-block:: none + + {% python + import random + random.seed(metadata.profile) + last_octet=random.randint(2,254) + %}\ + /* + $$Id$$ + $$HeadURL$$ + */ + + /* This configuration is as close to 2.5.x default behavior as possible + The values closely match ./gmond/metric.h definitions in 2.5.x */ + globals { + daemonize = yes + setuid = yes + user = nobody + debug_level = 0 + max_udp_msg_len = 1472 + mute = no + deaf = no + host_dmax = 1800 /* 30 minutes */ + cleanup_threshold = 604800 /*secs=1 week */ + gexec = no + send_metadata_interval = 0 + } + + /* If a cluster attribute is specified, then all gmond hosts are wrapped inside + * of a tag. If you do not specify a cluster tag, then all will + * NOT be wrapped inside of a tag. */ + cluster { + name = "${metadata.profile}" + owner = "user@company.net" + latlong = "unspecified" + url = "unspecified" + } + + /* The host section describes attributes of the host, like the location */ + host { + location = "unspecified" + } + + /* Feel free to specify as many udp_send_channels as you like. Gmond + used to only support having a single channel */ + udp_send_channel { + host = ${metadata.hostname} + port = 8649 + } + udp_send_channel { + mcast_join = 239.2.11.${last_octet} + port = 8649 + ttl = 1 + } + + /* You can specify as many udp_recv_channels as you like as well. */ + udp_recv_channel { + port = 8649 + bind = ${metadata.hostname} + } + udp_recv_channel { + mcast_join = 239.2.11.${last_octet} + bind = 239.2.11.${last_octet} + port = 8649 + } + + /* You can specify as many tcp_accept_channels as you like to share + an xml description of the state of the cluster */ + tcp_accept_channel { + port = 8649 + } + + /* Each metrics module that is referenced by gmond must be specified and + loaded. If the module has been statically linked with gmond, it does not + require a load path. However all dynamically loadable modules must include + a load path. */ + modules { + /* [snip] */ diff --git a/doc/server/plugins/generators/examples/genshi/grubconf.txt b/doc/server/plugins/generators/examples/genshi/grubconf.txt new file mode 100644 index 000000000..11dc7e974 --- /dev/null +++ b/doc/server/plugins/generators/examples/genshi/grubconf.txt @@ -0,0 +1,33 @@ +.. -*- mode: rst -*- + +grub.conf +========= + +Automate the build of grub.conf based on probe data. In this case, we take +the results from three probes, serial-console-speed, grub-serial-order, +and current-kernel to fill in a few variables. In addition, we want +at least two entries set up for the kernel: a multiuser and a single +user option. + +.. code-block:: none + + # grub.conf generated by Bcfg2 + # + # Note that you do not have to rerun grub after making changes to this file + # NOTICE: You have a /boot partition. This means that + # all kernel and initrd paths are relative to /boot/, eg. + # root (hd0,0) + # kernel /vmlinuz-version ro root=/dev/VolGroup00/LogVol00 + # initrd /initrd-version.img + #boot=/dev/sda + default=0 + timeout=5 + serial --unit=0 --speed=${metadata.Probes['serial-console-speed']} + terminal --timeout=5 ${metadata.Probes['grub-serial-order']} + + {% for kernbootoption in ["", "single"] %}\ + title Red Hat Enterprise Linux Server (${metadata.Probes['current-kernel']})) ${kernbootoption} + root (hd0,0) + kernel /vmlinuz-${metadata.Probes['current-kernel']} ro root=/dev/VolGroup00/LogVol00 console=ttyS0,${metadata.Probes['serial-console-speed']}n8 console=tty0 rhgb quiet ${kernbootoption} + initrd /initrd-${metadata.Probes['current-kernel']}.img + {% end %}\ diff --git a/doc/server/plugins/generators/examples/genshi/hosts.txt b/doc/server/plugins/generators/examples/genshi/hosts.txt new file mode 100644 index 000000000..144816e65 --- /dev/null +++ b/doc/server/plugins/generators/examples/genshi/hosts.txt @@ -0,0 +1,19 @@ +.. -*- mode: rst -*- + +hosts +===== + +This is an example of creating ``/etc/hosts`` based on metadata.hostname:: + + # Do not remove the following line, or various programs + # that require network functionality will fail. + 127.0.0.1 localhost.localdomain localhost + ::1 localhost6.localdomain6 localhost6 + {% python + import socket + import re + ip = socket.gethostbyname(metadata.hostname) + + shortname = re.split("\.", metadata.hostname) + %}\ + ${ip} ${metadata.hostname} ${shortname[0]} diff --git a/doc/server/plugins/generators/examples/genshi/iptables.txt b/doc/server/plugins/generators/examples/genshi/iptables.txt new file mode 100644 index 000000000..b9b3f6904 --- /dev/null +++ b/doc/server/plugins/generators/examples/genshi/iptables.txt @@ -0,0 +1,300 @@ +.. -*- mode: rst -*- + +========== + iptables +========== + +* Setup a Genshi base iptables file that contains the basic rules you + want every host to have +* To be safe you should have a client side IptablesDeadmanScript if you + intend on having bcfg2 bounce iptables upon rule updates + +.. note:: When updating files in the ``includes`` directory, you will + need to `touch` the Genshi template to regenerate the + template contents. + +/repository/Cfg/etc/sysconfig/iptables/iptables.genshi +====================================================== + +.. code-block:: none + + {% python + from genshi.builder import tag + import os,sys + import Bcfg2.Options + + opts = { 'repo': Bcfg2.Options.SERVER_REPOSITORY } + setup = Bcfg2.Options.OptionParser(opts) + setup.parse('--') + repo = setup['repo'] + basedir = '%s' % (repo) + + # for instance: + bcfg2BaseDir = basedir + name + '/' + + def checkHostFile(hostName, type): + fileName = bcfg2BaseDir + type + '.H_' + hostName + if os.path.isfile(fileName)==True : + return fileName + else: + return fileName + + def checkGroupFile(groupName, type): + fileName = bcfg2BaseDir + type + '.G_' + groupName + if os.path.isfile(fileName)==True : + return fileName + else: + return fileName + + %}\ + # BCFG2 GENERATED IPTABLES + # DO NOT CHANGE THIS + # $$Id$$ + # Templates live in ${bcfg2BaseDir} + # Manual customization of this file will get reverted. + # ----------------------------- FILTER --------------------------------- # + # Default CHAINS for FILTER: + *filter + :INPUT DROP [0:0] + :FORWARD DROP [0:0] + :OUTPUT ACCEPT [0:0] + :NO-SMTP - [0:0] + + #Default rules + #discard malicious packets + -A INPUT -p tcp --tcp-flags ALL ACK,RST,SYN,FIN -j DROP + -A INPUT -p tcp --tcp-flags SYN,FIN SYN,FIN -j DROP + -A INPUT -p tcp --tcp-flags SYN,RST SYN,RST -j DROP + #Allow incoming ICMP + -A INPUT -p icmp -m icmp -j ACCEPT + #Accept localhost traffic + -A INPUT -i lo -j ACCEPT + # Allow already established sessions to remain + -A INPUT -m state --state RELATED,ESTABLISHED -j ACCEPT + + # Deny inbound SMTP delivery (still allows outbound connections) + -A INPUT -m state --state NEW -m tcp -p tcp --tcp-flags FIN,SYN,RST,ACK SYN --dport 25 -j NO-SMTP + -A NO-SMTP -j LOG --log-prefix " Incoming SMTP (denied) " + -A NO-SMTP -j DROP + + # Allow SSH Access + :SSH - [0:0] + -A INPUT -p tcp -m state --state NEW -m tcp --tcp-flags FIN,SYN,RST,ACK SYN --dport 22 -j SSH + -A SSH -s 192.168.0.0/255.255.0.0 -j ACCEPT + + # Allow Ganglia Access + -A INPUT -m state --state NEW -m tcp -p tcp --tcp-flags FIN,SYN,RST,ACK SYN --src 192.168.1.1 --dport 8649 -j ACCEPT + # Gmetad access to gmond + -A INPUT -m state --state NEW -m tcp -p tcp --tcp-flags FIN,SYN,RST,ACK SYN --src 192.168.1.1 --dport 8649 -j ACCEPT + # Gmond UDP multicast + -A INPUT -m state --state NEW -m udp -p udp --dport 8649 -j ACCEPT + + {% if metadata.groups %}\ + # group custom FILTER rules: + {% for group in metadata.groups %}\ + {% include ${checkGroupFile(group,'custom-filter')} %}\ + {% end %}\ + {% end %}\ + + # host-specific FILTER rules: + {% include ${checkHostFile(metadata.hostname, 'custom-filter')} %}\ + + COMMIT + # ------------------------------- NAT ---------------------------------- # + *nat + + # Default CHAINS for NAT: + :PREROUTING ACCEPT [0:0] + :OUTPUT ACCEPT [0:0] + :POSTROUTING ACCEPT [0:0] + + {% if metadata.groups %}\ + # group NAT for PREROUTING: + {% for group in metadata.groups %}\ + {% include ${checkGroupFile(group,'nat-prerouting')} %}\ + {% end %}\ + {% end %}\ + + {% if metadata.groups %}\ + # group NAT for OUTPUT: + {% for group in metadata.groups %}\ + {% include ${checkGroupFile(group,'nat-output')} %}\ + {% end %}\ + {% end %}\ + + {% if metadata.groups %}\ + # group NAT for POSTROUTING: + {% for group in metadata.groups %}\ + {% include ${checkGroupFile(group,'nat-postrouting')} %}\ + {% end %}\ + {% end %}\ + + {% if metadata.groups %}\ + # group custom NAT rules: + {% for group in metadata.groups %}\ + {% include ${checkGroupFile(group,'custom-nat')} %}\ + {% end %}\ + {% end %}\ + + # host-specific NAT ruls: + {% include ${checkHostFile(metadata.hostname, 'custom-nat')} %}\ + COMMIT + # ----------------------------- MANGLE -------------------------------- # + *mangle + + # Default CHAINS for MANGLE: + :PREROUTING ACCEPT [0:0] + :INPUT ACCEPT [0:0] + :FORWARD ACCEPT [0:0] + :OUTPUT ACCEPT [0:0] + :POSTROUTING ACCEPT [0:0] + + {% if metadata.groups %}\ + # group MANGLE for PREROUTING: + {% for group in metadata.groups %}\ + {% include ${checkGroupFile(group,'mangle-prerouting')} %}\ + {% end %}\ + {% end %}\ + + {% if metadata.groups %}\ + # group MANGLE for INPUT: + {% for group in metadata.groups %}\ + {% include ${checkGroupFile(group,'mangle-input')} %}\ + {% end %}\ + {% end %}\ + + {% if metadata.groups %}\ + # group MANGLE for FORWARD: + {% for group in metadata.groups %}\ + {% include ${checkGroupFile(group,'mangle-forward')} %}\ + {% end %}\ + {% end %}\ + + {% if metadata.groups %}\ + # group MANGLE for OUTPUT: + {% for group in metadata.groups %}\ + {% include ${checkGroupFile(group,'mangle-output')} %}\ + {% end %}\ + {% end %}\ + + {% if metadata.groups %}\ + # group MANGLE for POSTROUTING rules: + {% for group in metadata.groups %}\ + {% include ${checkGroupFile(group,'mangle-postrouting')} %}\ + {% end %}\ + {% end %}\ + + {% if metadata.groups %}\ + # group custom MANGLE rules: + {% for group in metadata.groups %}\ + {% include ${checkGroupFile(group,'custom-mangle')} %}\ + {% end %}\ + {% end %}\ + + # host-specific MANGLE rules: + {% include ${checkHostFile(metadata.hostname, 'custom-mangle')} %}\ + COMMIT + +Cfg/etc/sysconfig/iptables/custom-filter.G_mysql-server +------------------------------------------------------- + +.. code-block:: none + + :MYSQL - [0:0] + -A INPUT -p tcp -m state --state NEW -m tcp --dport 3306 --tcp-flags FIN,SYN,RST,ACK SYN -j MYSQL + -A MYSQL -s 192.168.0.0/255.255.0.0 -j ACCEPT + +For a host that is in the mysql-server group you get an iptables file +that looks like the following:: + + # BCFG2 GENERATED IPTABLES + # DO NOT CHANGE THIS + # $Id: template.newtxt 5402 2009-08-19 22:50:06Z unixmouse$ + # Templates live in /var/lib/bcfg2/Cfg/etc/sysconfig/iptables/ + # Manual customization of this file will get reverted. + # ----------------------------- FILTER --------------------------------- # + # Default CHAINS for FILTER: + *filter + :INPUT DROP [0:0] + :FORWARD DROP [0:0] + :OUTPUT ACCEPT [0:0] + :NO-SMTP - [0:0] + + #Default rules + #discard malicious packets + -A INPUT -p tcp --tcp-flags ALL ACK,RST,SYN,FIN -j DROP + -A INPUT -p tcp --tcp-flags SYN,FIN SYN,FIN -j DROP + -A INPUT -p tcp --tcp-flags SYN,RST SYN,RST -j DROP + # Allow incoming ICMP + -A INPUT -p icmp -m icmp -j ACCEPT + # Accept localhost traffic + -A INPUT -i lo -j ACCEPT + # Allow already established sessions to remain + -A INPUT -m state --state RELATED,ESTABLISHED -j ACCEPT + + # Deny inbound SMTP delivery (still allows outbound connections) + -A INPUT -m state --state NEW -m tcp -p tcp --tcp-flags FIN,SYN,RST,ACK SYN --dport 25 -j NO-SMTP + -A NO-SMTP -j LOG --log-prefix " Incoming SMTP (denied) " + -A NO-SMTP -j DROP + + # Allow SSH Access + :SSH - [0:0] + -A INPUT -p tcp -m state --state NEW -m tcp --tcp-flags FIN,SYN,RST,ACK SYN --dport 22 -j SSH + -A SSH -s 192.168.0.0/255.255.0.0 -j ACCEPT + + # Allow Ganglia Access + -A INPUT -m state --state NEW -m tcp -p tcp --tcp-flags FIN,SYN,RST,ACK SYN --src 192.168.1.1 --dport 8649 -j ACCEPT + #Gmetad access to gmond + -A INPUT -m state --state NEW -m tcp -p tcp --tcp-flags FIN,SYN,RST,ACK SYN --src 192.168.1.1 --dport 8649 -j ACCEPT + #Gmond UDP multicast + -A INPUT -m state --state NEW -m udp -p udp --dport 8649 -j ACCEPT + + # group custom FILTER rules: + :MYSQL - [0:0] + -A INPUT -p tcp -m state --state NEW -m tcp --dport 3306 --tcp-flags FIN,SYN,RST,ACK SYN -j MYSQL + -A MYSQL -s 192.168.0.0/255.255.0.0 -j ACCEPT + + # host-specific FILTER rules: + + COMMIT + # ------------------------------- NAT ---------------------------------- # + *nat + + # Default CHAINS for NAT: + :PREROUTING ACCEPT [0:0] + :OUTPUT ACCEPT [0:0] + :POSTROUTING ACCEPT [0:0] + + # group NAT for PREROUTING: + + # group NAT for OUTPUT: + + # group NAT for POSTROUTING: + + # group custom NAT rules: + + # host-specific NAT rules: + COMMIT + # ----------------------------- MANGLE -------------------------------- # + *mangle + + # Default CHAINS for MANGLE: + :PREROUTING ACCEPT [0:0] + :INPUT ACCEPT [0:0] + :FORWARD ACCEPT [0:0] + :OUTPUT ACCEPT [0:0] + :POSTROUTING ACCEPT [0:0] + + # group MANGLE for PREROUTING: + + # group MANGLE for INPUT: + # group MANGLE for FORWARD: + + # group MANGLE for OUTPUT: + + # group MANGLE for POSTROUTING rules: + + # group custom MANGLE rules: + + # host-specific MANGLE rules: + COMMIT diff --git a/doc/server/plugins/generators/examples/genshi/motd.txt b/doc/server/plugins/generators/examples/genshi/motd.txt new file mode 100644 index 000000000..6f4a891d1 --- /dev/null +++ b/doc/server/plugins/generators/examples/genshi/motd.txt @@ -0,0 +1,98 @@ +.. -*- mode: rst -*- + +====== + motd +====== + +The following template automatically generates a MOTD (message of the +day) file that describes the system in terms of its Bcfg2 metadata +and probe responses. It conditionally displays groups, categories, +and probe responses, if there exists any data for them. + +Cfg/etc/motd/motd.genshi +======================== + +.. code-block:: none + + ------------------------------------------------------------------------ + GOALS FOR SERVER MANGED BY BCFG2 + ------------------------------------------------------------------------ + Hostname is ${metadata.hostname} + + Groups: + {% for group in metadata.groups %}\ + * ${group} + {% end %}\ + + {% if metadata.categories %}\ + Categories: + {% for category in metadata.categories %}\ + * ${category} + {% end %}\ + {% end %}\ + + + {% if metadata.Probes %}\ + Probes: + {% for probe, value in metadata.Probes.iteritems() %}\ + * ${probe} \ + ${value} + {% end %}\ + {% end %}\ + + ------------------------------------------------------------------------- + ITOPS MOTD + ------------------------------------------------------------------------- + Please create a Ticket for any system level changes you need from IT. + +This template gets the hostname, groups membership of the host, categories +of the host (if any), and result of probes on the host (if any). The +template formats this in with a header and footer that makes it visually +more appealing. + + +Output +====== + +One possible output of this template would be the following:: + + ------------------------------------------------------------------------ + GOALS FOR SERVER MANGED BY BCFG2 + ------------------------------------------------------------------------ + Hostname is cobra.example.com + + Groups: + * oracle-server + * centos5-5.2 + * centos5 + * redhat + * x86_64 + * sys-vmware + + Categories: + * os-variant + * os + * database-server + * os-version + + + Probes: + * arch x86_64 + * network intranet_network + * diskspace Filesystem Size Used Avail Use% Mounted on + /dev/mapper/VolGroup00-LogVol00 + 18G 2.1G 15G 13% / + /dev/sda1 99M 13M 82M 13% /boot + tmpfs 3.8G 0 3.8G 0% /dev/shm + /dev/mapper/mhcdbo-clear + 1.5T 198M 1.5T 1% /mnt/san-oracle + * virtual vmware + + ------------------------------------------------------------------------- + IT MOTD + ------------------------------------------------------------------------- + Please create a Ticket for any system level changes you need from IT. + +One way to make this even more useful, is to only include the result of +certain probes. It would also be a nice feature to be able to include +customer messages on a host or group level. diff --git a/doc/server/plugins/generators/examples/genshi/mycnf.txt b/doc/server/plugins/generators/examples/genshi/mycnf.txt new file mode 100644 index 000000000..76e2fc2bb --- /dev/null +++ b/doc/server/plugins/generators/examples/genshi/mycnf.txt @@ -0,0 +1,31 @@ +.. -*- mode: rst -*- + +my.cnf +====== + +The following template generates a ``server-id`` based on the last two +numeric parts of the IP address. The "slave" portion of the configuration +only applies to machines in the "slave" group:: + + {% python + import socket + parts = socket.gethostbyname(metadata.hostname).split('.') + server_id = parts[2] + parts[3] + %}\ + [mysqld] + + # [snip] + + server-id = ${server_id} + + # Replication configuration + + {% if "slave" in metadata.groups %}\ + relay-log = /data01/mysql/log/mysql-relay-bin + log-slave-updates = 1 + {% end %}\ + sync-binlog = 1 + #read-only = 1 + #report-host = + + # [snip] diff --git a/doc/server/plugins/generators/examples/genshi/test.txt b/doc/server/plugins/generators/examples/genshi/test.txt new file mode 100644 index 000000000..03d0becd9 --- /dev/null +++ b/doc/server/plugins/generators/examples/genshi/test.txt @@ -0,0 +1,144 @@ +.. -*- mode: rst -*- + +test +==== + +As submitted by dclark + +This file just shows you what's available. It assumes a +``/var/lib/bcfg2/Properties/test.xml`` file with an entry like this: + +.. code-block:: xml + + + + fakeBCFG2password + + + +:: + + Hostname is ${metadata.hostname} + + Groups: + {% for group in metadata.groups %}\ + ${group} \ + {% end %}\ + + {% if metadata.categories %}\ + Categories: + {% for category in metadata.categories %}\ + ${category} \ + {% end %}\ + {% end %}\ + + {% if metadata.Probes %}\ + Probes: + {% for probe, value in metadata.Probes.iteritems() %}\ + $probe $value + {% end %}\ + {% end %}\ + + Two main ways to get the same property value: + ${metadata.Properties['test.xml'].xdata.find('password').find('bcfg2').text} + ${metadata.Properties['test.xml'].xdata.xpath('password/bcfg2')[0].text} + + One way to get information about metadata and properties: + + dir(metadata): + {% for var in dir(metadata) %}\ + ${var} \ + {% end %} + + dir(metadata.Properties.xdata): + {% for var in dir(metadata.Properties.xdata) %}\ + ${var} \ + {% end %} + + dir(metadata.Properties.xdata.entries): + {% for var in dir(metadata.Properties.xdata.entries) %}\ + ${var} \ + {% end %} + + dir(metadata.Properties.xdata.label): + {% for var in dir(metadata.Properties.xdata.label) %}\ + ${var} \ + {% end %} + + dir(metadata.Properties.xdata.name): + {% for var in dir(metadata.Properties.xdata.name) %}\ + ${var} \ + {% end %} + + dir(metadata.Properties.xdata.properties): + {% for var in dir(metadata.Properties.xdata.properties) %}\ + ${var} \ + {% end %} + +When the above file is saved as ``Cfg/test/test.genshi`` and generated +with ``bcfg2-info buildfile /test test.hostname.org``, the results +look like this (below reformatted a little bit to fit in 80 columns):: + + + Hostname is test.hostname.org + + Groups: + bcfg2-server + + + Two main ways to get the same property value: + fakeBCFG2password + fakeBCFG2password + + One way to get information about metadata and properties: + + dir(metadata): + __class__ __delattr__ __dict__ __doc__ __getattribute__ __hash__ __init__ + __module__ __new__ __reduce__ __reduce_ex__ __repr__ __setattr__ __str__ + __weakref__ all bundles categories get_clients_by_group get_clients_by_profile + groups hostname inGrouppassword probes uuid + + dir(metadata.Properties.xdata): + HandleEvent Index __class__ __delattr__ __dict__ __doc__ __getattribute__ + __hash__ __identifier__ __init__ __iter__ __module__ __new__ __reduce__ + __reduce_ex__ __repr__ __setattr__ __str__ __weakref__ entries label name + properties + + dir(metadata.Properties.xdata.entries): + __add__ __class__ __contains__ __delattr__ __delitem__ __delslice__ __doc__ + __eq__ __ge__ __getattribute__ __getitem__ __getslice__ __gt__ __hash__ + __iadd__ __imul__ __init__ __iter__ __le__ __len__ __lt__ __mul__ __ne__ + __new__ __reduce__ __reduce_ex__ __repr__ __reversed__ __rmul__ __setattr__ + __setitem__ __setslice__ __str__ append count extend index insert pop remove + reverse sort + + dir(metadata.Properties.xdata.label): + __add__ __class__ __contains__ __delattr__ __doc__ __eq__ __ge__ + __getattribute__ __getitem__ __getnewargs__ __getslice__ __gt__ __hash__ + __init__ __le__ __len__ __lt__ __mod__ __mul__ __ne__ __new__ __reduce__ + __reduce_ex__ __repr__ __rmod__ __rmul__ __setattr__ __str__ capitalize center + count decode encode endswith expandtabs find index isalnum isalpha isdigit + islower isspace istitle isupper join ljust lower lstrip partition replace + rfind rindex rjust rpartition rsplit rstrip split splitlinesstartswith strip + swapcase title translate upper zfill + + dir(metadata.Properties.xdata.name): + __add__ __class__ __contains__ __delattr__ __doc__ __eq__ __ge__ + __getattribute__ __getitem__ __getnewargs__ __getslice__ __gt__ __hash__ + __init__ __le__ __len__ __lt__ __mod__ __mul__ __ne__ __new__ __reduce__ + __reduce_ex__ __repr__ __rmod__ __rmul__ __setattr__ __str__ capitalize center + count decode encode endswith expandtabs find index isalnum isalpha isdigit + islower isspace istitle isupper join ljust lower lstrip partition replace + rfind rindex rjust rpartition rsplit rstrip split splitlinesstartswith strip + swapcase title translate upper zfill + + dir(metadata.Properties.xdata.properties): + __class__ __contains__ __copy__ __deepcopy__ __delattr__ __delitem__ + __delslice__ __doc__ __getattribute__ __getitem__ __getslice__ __hash__ + __init__ __iter__ __len__ __new__ __nonzero__ __reduce__ __reduce_ex__ + __repr__ __reversed__ __setattr__ __setitem__ __setslice__ __str__ _init + addnext addprevious append attrib clear extend find findall findtext get + getchildren getiterator getnext getparent getprevious getroottree index insert + items iterancestors iterchildren iterdescendants itersiblings keys makeelement + nsmap prefix remove replace set sourceline tag tail text values xpath + diff --git a/doc/server/plugins/generators/packages.txt b/doc/server/plugins/generators/packages.txt index 0315354a8..f0abf4af2 100644 --- a/doc/server/plugins/generators/packages.txt +++ b/doc/server/plugins/generators/packages.txt @@ -36,12 +36,14 @@ source to which they apply (based on group memberships, as described above). Packages and dependencies are resolved from all applicable sources. -.. note:: To recap, a client needs to be a member of the - **Architecture** group and any other groups defined in your - ``Packages/sources.xml`` file in order for the client to be - associated to the proper sources. If you are using - :ref:`server-plugins-generators-packages-magic-groups`, then - a client must also be a member of the appropriate OS group. +.. note:: + + To recap, a client needs to be a member of the **Architecture** + group and any other groups defined in your + ``Packages/sources.xml`` file in order for the client to be + associated to the proper sources. If you are using + :ref:`server-plugins-generators-packages-magic-groups`, then a + client must also be a member of the appropriate OS group. .. _server-plugins-generators-packages-magic-groups: @@ -458,7 +460,8 @@ See :ref:`configuration` for more details on these options. Support for generating Yum configs was added in 1.2.0, and Apt configs was added in 1.3.0. Before that, you could use - :doc:`./tgenshi/index` or :doc:`./tcheetah` to generate your + :ref:`server-plugins-generators-cfg-genshi` or + :ref:`server-plugins-generators-cfg-cheetah` to generate your configs. .. _native-yum-libraries: diff --git a/doc/server/plugins/generators/pkgmgr.txt b/doc/server/plugins/generators/pkgmgr.txt index 76a8ec1a5..0d992685c 100644 --- a/doc/server/plugins/generators/pkgmgr.txt +++ b/doc/server/plugins/generators/pkgmgr.txt @@ -310,7 +310,7 @@ Altogether, this should move policy decisions about package architectures to bundles/base. Automated Generation of Pkgmgr Configuration Files --------------------------------------------------- +================================================== The two utilities detailed below are provided in the tools directory of the source tarball. @@ -373,7 +373,7 @@ containing RPMs or from a list of YUM repositories.:: .. note:: The startdate and enddate options are not yet implemented. pkgmgr_update.py ----------------- +^^^^^^^^^^^^^^^^ pkgmgr_update will update the release (meaning the epoch, version and release) information in an existing Pkgrmgr file from a list of @@ -398,7 +398,7 @@ and other attributes in the existing file will remain unchanged.:: NOTE: Each URL must end in a '/' character. Pkgmgr Configuration Examples ------------------------------ +============================= verify_flags ^^^^^^^^^^^^ diff --git a/doc/server/plugins/generators/sslca.txt b/doc/server/plugins/generators/sslca.txt index 36245cbf5..4c1845406 100644 --- a/doc/server/plugins/generators/sslca.txt +++ b/doc/server/plugins/generators/sslca.txt @@ -9,7 +9,8 @@ SSLCA SSLCA is a generator plugin designed to handle creation of SSL private keys and certificates on request. -Borrowing ideas from the TGenshi and SSHbase plugins, SSLCA automates +Borrowing ideas from :ref:`server-plugins-generators-cfg-genshi` and +the :ref:`server-plugins-generators-sshbase` plugin, SSLCA automates the generation of SSL certificates by allowing you to specify key and certificate definitions. Then, when a client requests a Path that contains such a definition within the SSLCA repository, the matching diff --git a/doc/server/plugins/generators/tcheetah.txt b/doc/server/plugins/generators/tcheetah.txt index ae56e4d02..894b35d31 100644 --- a/doc/server/plugins/generators/tcheetah.txt +++ b/doc/server/plugins/generators/tcheetah.txt @@ -6,6 +6,11 @@ TCheetah ======== +.. warning:: + + TCheetah is deprecated. You should instead use + :ref:`server-plugins-generators-cfg-cheetah` in the Cfg plugin. + This document reflects the ``TCheetah`` plugin. The ``TCheetah`` plugin allows you to use the `cheetah templating system diff --git a/doc/server/plugins/generators/tgenshi.txt b/doc/server/plugins/generators/tgenshi.txt new file mode 100644 index 000000000..5e0a7f1b5 --- /dev/null +++ b/doc/server/plugins/generators/tgenshi.txt @@ -0,0 +1,213 @@ +.. -*- mode: rst -*- + +.. _server-plugins-generators-tgenshi-index: + +======= +TGenshi +======= + +.. warning:: + + The TGenshi plugin is deprecated. You should instead use + :ref:`server-plugins-generators-cfg-genshi` in the Cfg plugin. + +This page documents the TGenshi plugin. This plugin works with version +0.4 and newer of the genshi library. + +The TGenshi plugin allows you to use the `Genshi +`_ templating system to create files, +instead of the various diff-based methods offered by the Cfg +plugin. It also allows you to include the results of probes executed +on the client in the created files. + +To begin, you will need to download and install the Genshi templating engine. + +To install on CentOS or RHEL, run:: + + sudo yum install python-genshi + +Once it is installed, you can enable it by adding ``TGenshi`` to the +generators line in ``/etc/bcfg2.conf`` on your Bcfg server. For example:: + + plugins = Base,Bundler,Cfg,...,TGenshi + +The TGenshi plugin makes use of a Cfg-like directory structure +located in in a TGenshi subdirectory of your repository, usually +``/var/lib/bcfg2/TGenshi``. Each file has a directory containing two file +types, template and info. Templates are named according to the genshi +format used; template.txt uses the genshi text format, and template.xml +uses the XML format. + +If used with Genshi 0.5 or later the plugin also supports the `new +style +`_ +text template format for files named template.newtxt. One of the +advantages of the new format is that it does not use # as a command +delimiter, making it easier to utilize for configuration files that +use # as a comment character. + +Only one template format may be used per file served. Info files are +identical to those used in ``Cfg``, and ``info.xml`` files are +supported. + +Inside of templates +=================== + +* **metadata** is the client's :ref:`metadata + ` +* **metadata.Properties** is an xml document of unstructured data (only + 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. 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 +Genshi syntax. + +Examples: Old Genshi Syntax +--------------------------- + +Genshi's web pages recommend against using this syntax, as it may +disappear from future releases. + +Group Negation +^^^^^^^^^^^^^^ + +Templates are also useful for cases where more sophisticated boolean +operations than those supported by Cfg are needed. For example, the +template:: + + #if "ypbound" in metadata.groups and "workstation" in metadata.groups + client is ypbound workstation + #end + #if "ubuntu" not in metadata.groups and "desktop" in metadata.groups + client is a desktop, but not an ubuntu desktop + #end + +Produces: + +.. code-block:: xml + + client is ypbound workstation + client is a desktop, but not an ubuntu desktop + + +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 + +To generate a file with an altsrc attribute, you can run:: + + bcfg2-info buildfile /etc/foo/foo.conf --altsrc=/etc/foo.conf \ + foo.example.com + +Sometimes, it's useful to be able to do more in-depth troubleshooting +by running the template manually. To do this, run ``bcfg2-info +debug``, and, once in the Python interpreter, run:: + + metadata = self.build_metadata("") + path = "" + +``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. + +Then, run:: + + import os, Bcfg2.Options + from genshi.template import TemplateLoader, NewTextTemplate + name = os.path.dirname(path[path.find('/', 1):]) + setup = Bcfg2.Options.OptionParser({'repo': + Bcfg2.Options.SERVER_REPOSITORY}) + setup.parse('--') + template = TemplateLoader().load(setup['repo'] + 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" + name = "/etc/sysconfig/network-scripts/ifcfg-bond0" + +File permissions +================ + +File permissions for entries handled by TGenshi are controlled via the +use of :ref:`server-info` files. Note that you **cannot** use both a +Permissions entry and a Path entry to handle the same file. + +Error handling +================ + +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:: + + {% python + from genshi.template import TemplateError + grp = None + for g in metadata.groups: + if g.startswith('ganglia-gmond-'): + grp = g + break + else: + raise TemplateError, "Missing group" + %}\ + +will fail to bind if the client is not a member of a group starting with +"ganglia-gmond-". The syslogs on the server will contain this message:: + + bcfg2-server[5957]: Genshi template error: Missing group + bcfg2-server[5957]: Failed to bind entry: Path /etc/ganglia/gmond.conf + +indicating the bind failure and message raised with the TemplateError. + +FAQs +==== + +**Question** + +How do I escape the $ (dollar sign) in a TGenshi text template? For +example, if I want to include SVN (subversion) keywords like $Id$ or +$HeadURL$ in TGenshi-generated files, or am templating a bourne shell +(sh/bash) script or Makefile (make). + +**Answer** + +Use $$ (double dollar sign) to output a literal $ (dollarsign) +in a TGenshi text template. So instead of $Id$, you'd use +$$Id$$. See also Genshi tickets `#282: Document $$ escape +convention `_ and +`#283: Allow for redefinition of template syntax per-file +`_. + +Examples +======== + +.. toctree:: + :glob: + :maxdepth: 1 + + examples/genshi/* diff --git a/doc/server/plugins/generators/tgenshi/bcfg2-cron.txt b/doc/server/plugins/generators/tgenshi/bcfg2-cron.txt deleted file mode 100644 index 56def1e3d..000000000 --- a/doc/server/plugins/generators/tgenshi/bcfg2-cron.txt +++ /dev/null @@ -1,25 +0,0 @@ -.. -*- mode: rst -*- - -.. _server-plugins-generators-tgenshi-bcfg2-cron: - -bcfg2-cron -========== - -As submitted by Kamil Kisiel - -The following is my ``/etc/cron.d/bcfg2`` file. It uses the python random -module seeded with the client hostname to generate a random time for the -client to check in. The hostname seed ensures the generated file is the -same each time the client checks in. This cron file helps to distribute -the load on the Bcfg2 server since not all machines are checking in at -the same time.:: - - {% python - from genshi.builder import tag - import random - random.seed(metadata.hostname) - %}\ - ${random.randint(0,60)} * * * * root /usr/sbin/bcfg2 &> /dev/null - -You can apply the same concept to the other time fields by adding another -``${random.randint()}`` call. diff --git a/doc/server/plugins/generators/tgenshi/clientsxml.txt b/doc/server/plugins/generators/tgenshi/clientsxml.txt deleted file mode 100644 index 87d6d728a..000000000 --- a/doc/server/plugins/generators/tgenshi/clientsxml.txt +++ /dev/null @@ -1,94 +0,0 @@ -.. -*- mode: rst -*- - -.. _server-plugins-generators-tgenshi-clientsxml: - -clientsxml -========== - -As submitted by dclark - -Here is an example of maintaining the bcfg2 server's -``/var/lib/bcfg2/Metadata/clients.xml`` file using TGenshi. - -There are two main advantages: - -#. Password storage is centralized in the ``Properties/passwords.xml`` - file this helps maintain consistency, makes changing passwords - easier, and also makes it easier to share your configurations with - other sites/people. - -#. You can template the file using Genshi's `{% def %}` syntax, - which makes `clients.xml` much more readable. An important - thing to note is how the `name` variable is handled - when - just referring to it the standard `${name}` syntax is used, but - when it is used as a variable in the expression to get the password, - `password="${metadata.Properties['passwords.xml'].xdata.find('password').find('bcfg2-client').find(name).text}"`, - it is just referred to as `name`. - -There is the disadvantage that sometimes 2 passes will be needed to get -to a consistent state. - -Possible improvements: - -#. Wrapper for bcfg2 client runs on the bcfg2 server, perhaps using a call - to `bcfg2-info buildfile`, so clients.xml is always generated before - everything else happens (since the state of clients.xml can influence - everything else bcfg2-server does). - -#. We really don't care what the client passwords are, just that they - exist, so instead of listing them a master password combined with - some kind of one-way hash based on the `name` might make more sense, - and make ``Properties/passwords.xml`` easier to maintain. - - * TGenshi/var/lib/bcfg2/Metadata/clients.xml/template.newtxt: - - .. code-block:: xml - - - - - {# Doc: http://bcfg2.org/wiki/Authentication #}\ - {% def static(profile,name,address) %} - \ - {% end %}\ - {% def dynamic(profile,name) %} - \ - {% end %}\ - \ - ${static('group-server-collab','campaigns.example.com','192.168.111.1')} - ${static('group-server-collab','info.office.example.com','192.168.111.2')} - ${static('group-server-config','config.example.com','192.168.111.3')} - ${dynamic('group-project-membercard','membercard')} - ${dynamic('group-person-somename','somename.office.example.com')} - - - * Properties/passwords.xml snippit: - - .. code-block:: xml - - - - - FAKEpassword1 - FAKEpassword2 - FAKEpassword3 - FAKEpassword4 - FAKEpassword5 - - - diff --git a/doc/server/plugins/generators/tgenshi/ganglia.txt b/doc/server/plugins/generators/tgenshi/ganglia.txt deleted file mode 100644 index 3b844afda..000000000 --- a/doc/server/plugins/generators/tgenshi/ganglia.txt +++ /dev/null @@ -1,174 +0,0 @@ -.. -*- mode: rst -*- - -.. _server-plugins-generators-tgenshi-ganglia: - -ganglia -======= - -Another interesting example of **TGenshi** templating is to automatically -generate ``gmond``/``gmetad`` configuration files. The idea is that each -cluster is headless: it communicates with the rest of the cluster members -on an isolated multicast IP address and port. Any of the cluster members -is therefore isolated on that particular ip/port pair. Additionally, -each ``gmond`` instance **also** listens on UDP. This allows for any of -the cluster members to be polled for information on the entire cluster! - -The second part of the trick is in ``gmetad.conf``. Here, we dynamically -generate a list of clusters (based on profiles names) and a list of -members to poll (based on the clients in said profiles). As the number of -profiles and client grows, this list will grow automatically as well. When -a new host is added, ``gmetad`` will receive an updated configuration and -act accordingly. - -There **is** one caveat though. The ``gmetad.conf`` parser is hard coded -to read 16 arguments per ``data_source`` line. If you have more than 15 -nodes in a cluster, you will see a warning in the logs. You can either -ignore it, or truncate the list to the first 15 members. - -In our environment, a profile is a one to one match with the role of -that particular host. You can also do this based on groups, or any other -client property. - -Bundler/ganglia.xml -------------------- - -.. code-block:: xml - - - - - - - - - - - - - - - - - -Rules/services-ganglia.xml --------------------------- - -.. code-block:: xml - - - - - - - - -TGenshi/etc/ganglia/gmetad.conf/template.newtxt ------------------------------------------------ - -:: - - {% python - client_metadata = metadata.query.all() - profile_array = {} - seen = [] - for item in client_metadata: - if item.profile not in seen: - seen.append(item.profile) - profile_array[item.profile]=[] - profile_array[item.profile].append(item.hostname) - seen.sort() - %}\ - - gridname "Our Grid" - - {% for profile in seen %} - data_source "${profile}" \ - {% for host in profile_array[profile] %}\ - ${host} \ - {% end %}\ - {% end %} - - rrd_rootdir "/var/lib/ganglia/rrds" - -TGenshi/etc/ganglia/gmond.conf/template.newtxt ----------------------------------------------- - -:: - - {% python - from genshi.builder import tag - import random - random.seed(metadata.profile) - last_octet=random.randint(2,254) - %}\ - /* - $$Id$$ - $$HeadURL$$ - */ - - /* This configuration is as close to 2.5.x default behavior as possible - The values closely match ./gmond/metric.h definitions in 2.5.x */ - globals { - daemonize = yes - setuid = yes - user = nobody - debug_level = 0 - max_udp_msg_len = 1472 - mute = no - deaf = no - host_dmax = 1800 /* 30 minutes */ - cleanup_threshold = 604800 /*secs=1 week */ - gexec = no - send_metadata_interval = 0 - } - - /* If a cluster attribute is specified, then all gmond hosts are wrapped inside - * of a tag. If you do not specify a cluster tag, then all will - * NOT be wrapped inside of a tag. */ - cluster { - name = "${metadata.profile}" - owner = "user@company.net" - latlong = "unspecified" - url = "unspecified" - } - - /* The host section describes attributes of the host, like the location */ - host { - location = "unspecified" - } - - /* Feel free to specify as many udp_send_channels as you like. Gmond - used to only support having a single channel */ - udp_send_channel { - host = ${metadata.hostname} - port = 8649 - } - udp_send_channel { - mcast_join = 239.2.11.${last_octet} - port = 8649 - ttl = 1 - } - - /* You can specify as many udp_recv_channels as you like as well. */ - udp_recv_channel { - port = 8649 - bind = ${metadata.hostname} - } - udp_recv_channel { - mcast_join = 239.2.11.${last_octet} - bind = 239.2.11.${last_octet} - port = 8649 - } - - /* You can specify as many tcp_accept_channels as you like to share - an xml description of the state of the cluster */ - tcp_accept_channel { - port = 8649 - } - - /* Each metrics module that is referenced by gmond must be specified and - loaded. If the module has been statically linked with gmond, it does not - require a load path. However all dynamically loadable modules must include - a load path. */ - modules { - /* [snip] */ diff --git a/doc/server/plugins/generators/tgenshi/grubconf.txt b/doc/server/plugins/generators/tgenshi/grubconf.txt deleted file mode 100644 index d4381f10b..000000000 --- a/doc/server/plugins/generators/tgenshi/grubconf.txt +++ /dev/null @@ -1,35 +0,0 @@ -.. -*- mode: rst -*- - -.. _server-plugins-generators-tgenshi-grubconf: - -grubconf -======== - -Automate the build of grub.conf based on probe data. In this case, we take -the results from three probes, serial-console-speed, grub-serial-order, -and current-kernel to fill in a few variables. In addition, we want -at least two entries set up for the kernel: a multiuser and a single -user option. - -:: - - # grub.conf generated by anaconda - # - # Note that you do not have to rerun grub after making changes to this file - # NOTICE: You have a /boot partition. This means that - # all kernel and initrd paths are relative to /boot/, eg. - # root (hd0,0) - # kernel /vmlinuz-version ro root=/dev/VolGroup00/LogVol00 - # initrd /initrd-version.img - #boot=/dev/sda - default=0 - timeout=5 - serial --unit=0 --speed=${metadata.Probes['serial-console-speed']} - terminal --timeout=5 ${metadata.Probes['grub-serial-order']} - - {% for kernbootoption in ["", "single"] %}\ - title Red Hat Enterprise Linux Server (${metadata.Probes['current-kernel']})) ${kernbootoption} - root (hd0,0) - kernel /vmlinuz-${metadata.Probes['current-kernel']} ro root=/dev/VolGroup00/LogVol00 console=ttyS0,${metadata.Probes['serial-console-speed']}n8 console=tty0 rhgb quiet ${kernbootoption} - initrd /initrd-${metadata.Probes['current-kernel']}.img - {% end %}\ diff --git a/doc/server/plugins/generators/tgenshi/hosts.txt b/doc/server/plugins/generators/tgenshi/hosts.txt deleted file mode 100644 index fd3446df8..000000000 --- a/doc/server/plugins/generators/tgenshi/hosts.txt +++ /dev/null @@ -1,21 +0,0 @@ -.. -*- mode: rst -*- - -.. _server-plugins-generators-tgenshi-hosts: - -hosts -===== - -This is an example of creating ``/etc/hosts`` based on metadata.hostname:: - - # Do not remove the following line, or various programs - # that require network functionality will fail. - 127.0.0.1 localhost.localdomain localhost - ::1 localhost6.localdomain6 localhost6 - {% python - import socket - import re - ip = socket.gethostbyname(metadata.hostname) - - shortname = re.split("\.", metadata.hostname) - %}\ - ${ip} ${metadata.hostname} ${shortname[0]} diff --git a/doc/server/plugins/generators/tgenshi/index.txt b/doc/server/plugins/generators/tgenshi/index.txt deleted file mode 100644 index 0d4a7ffb0..000000000 --- a/doc/server/plugins/generators/tgenshi/index.txt +++ /dev/null @@ -1,215 +0,0 @@ -.. -*- mode: rst -*- - -.. _server-plugins-generators-tgenshi-index: - -======= -TGenshi -======= - -This page documents the TGenshi plugin. This plugin works with version -0.4 and newer of the genshi library. - -The TGenshi plugin allows you to use the `Genshi -`_ templating system to create files, -instead of the various diff-based methods offered by the Cfg -plugin. It also allows you to include the results of probes executed -on the client in the created files. - -To begin, you will need to download and install the Genshi templating engine. - -To install on CentOS or RHEL, run:: - - sudo yum install python-genshi - -Once it is installed, you can enable it by adding ``TGenshi`` to the -generators line in ``/etc/bcfg2.conf`` on your Bcfg server. For example:: - - plugins = Base,Bundler,Cfg,...,TGenshi - -The TGenshi plugin makes use of a Cfg-like directory structure -located in in a TGenshi subdirectory of your repository, usually -``/var/lib/bcfg2/TGenshi``. Each file has a directory containing two file -types, template and info. Templates are named according to the genshi -format used; template.txt uses the genshi text format, and template.xml -uses the XML format. - -If used with Genshi 0.5 or later the plugin also supports the `new -style -`_ -text template format for files named template.newtxt. One of the -advantages of the new format is that it does not use # as a command -delimiter, making it easier to utilize for configuration files that -use # as a comment character. - -Only one template format may be used per file served. Info files are -identical to those used in ``Cfg``, and ``info.xml`` files are -supported. - -Inside of templates -=================== - -* **metadata** is the client's :ref:`metadata - ` -* **metadata.Properties** is an xml document of unstructured data (only - 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. 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 -Genshi syntax. - -Examples: Old Genshi Syntax ---------------------------- - -Genshi's web pages recommend against using this syntax, as it may -disappear from future releases. - -Group Negation -^^^^^^^^^^^^^^ - -Templates are also useful for cases where more sophisticated boolean -operations than those supported by Cfg are needed. For example, the -template:: - - #if "ypbound" in metadata.groups and "workstation" in metadata.groups - client is ypbound workstation - #end - #if "ubuntu" not in metadata.groups and "desktop" in metadata.groups - client is a desktop, but not an ubuntu desktop - #end - -Produces: - -.. code-block:: xml - - client is ypbound workstation - client is a desktop, but not an ubuntu desktop - - -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 - -To generate a file with an altsrc attribute, you can run:: - - bcfg2-info buildfile /etc/foo/foo.conf --altsrc=/etc/foo.conf \ - foo.example.com - -Sometimes, it's useful to be able to do more in-depth troubleshooting -by running the template manually. To do this, run ``bcfg2-info -debug``, and, once in the Python interpreter, run:: - - metadata = self.build_metadata("") - path = "" - -``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. - -Then, run:: - - import os, Bcfg2.Options - from genshi.template import TemplateLoader, NewTextTemplate - name = os.path.dirname(path[path.find('/', 1):]) - setup = Bcfg2.Options.OptionParser({'repo': - Bcfg2.Options.SERVER_REPOSITORY}) - setup.parse('--') - template = TemplateLoader().load(setup['repo'] + 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" - name = "/etc/sysconfig/network-scripts/ifcfg-bond0" - -File permissions -================ - -File permissions for entries handled by TGenshi are controlled via the -use of :ref:`server-info` files. Note that you **cannot** use both a -Permissions entry and a Path entry to handle the same file. - -Error handling -================ - -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:: - - {% python - from genshi.template import TemplateError - grp = None - for g in metadata.groups: - if g.startswith('ganglia-gmond-'): - grp = g - break - else: - raise TemplateError, "Missing group" - %}\ - -will fail to bind if the client is not a member of a group starting with -"ganglia-gmond-". The syslogs on the server will contain this message:: - - bcfg2-server[5957]: Genshi template error: Missing group - bcfg2-server[5957]: Failed to bind entry: Path /etc/ganglia/gmond.conf - -indicating the bind failure and message raised with the TemplateError. - -FAQs -==== - -**Question** - -How do I escape the $ (dollar sign) in a TGenshi text template? For -example, if I want to include SVN (subversion) keywords like $Id$ or -$HeadURL$ in TGenshi-generated files, or am templating a bourne shell -(sh/bash) script or Makefile (make). - -**Answer** - -Use $$ (double dollar sign) to output a literal $ (dollarsign) -in a TGenshi text template. So instead of $Id$, you'd use -$$Id$$. See also Genshi tickets `#282: Document $$ escape -convention `_ and -`#283: Allow for redefinition of template syntax per-file -`_. - -Examples -======== - -.. toctree:: - :maxdepth: 1 - - bcfg2-cron - clientsxml - ganglia - grubconf - hosts - iptables - motd - mycnf - test diff --git a/doc/server/plugins/generators/tgenshi/iptables.txt b/doc/server/plugins/generators/tgenshi/iptables.txt deleted file mode 100644 index 310f9ffab..000000000 --- a/doc/server/plugins/generators/tgenshi/iptables.txt +++ /dev/null @@ -1,306 +0,0 @@ -.. -*- mode: rst -*- - -.. _server-plugins-generators-tgenshi-iptables: - -iptables -======== - -* Setup a TGenshi base iptables file that contains the basic rules you - want every host to have -* Create a custom dir that has group and host specific rules you want - to apply -* To be safe you should have a client side IptablesDeadmanScript if you - intend on having bcfg2 bounce iptables upon rule updates - -.. note:: When updating files in the ``includes`` directory, you will - need to `touch` the TGenshi template to regenerate the - template contents. - -/repository/TGenshi/etc/sysconfig/iptables/template.newtxt ----------------------------------------------------------- - -:: - - {% python - from genshi.builder import tag - import os,sys - import Bcfg2.Options - - opts = { 'repo': Bcfg2.Options.SERVER_REPOSITORY } - setup = Bcfg2.Options.OptionParser(opts) - setup.parse('--') - repo = setup['repo'] - basedir = '%s' % (repo) - - # for instance: /var/lib/bcfg2/custom/etc/sysconfig/iptables/ - bcfg2BaseDir = basedir + '/includes' + name + '/' - - - def checkHostFile(hostName, type): - fileName = bcfg2BaseDir + type + '.H_' + hostName - if os.path.isfile(fileName)==True : - return fileName - else: - return fileName - - def checkGroupFile(groupName, type): - fileName = bcfg2BaseDir + type + '.G_' + groupName - if os.path.isfile(fileName)==True : - return fileName - else: - return fileName - - %}\ - # BCFG2 GENERATED IPTABLES - # DO NOT CHANGE THIS - # $$Id$$ - # $$HeadURL$$ - # Templates live in ${bcfg2BaseDir} - # Manual customization of this file will get reverted. - # ----------------------------- FILTER --------------------------------- # - # Default CHAINS for FILTER: - *filter - :INPUT DROP [0:0] - :FORWARD DROP [0:0] - :OUTPUT ACCEPT [0:0] - :NO-SMTP - [0:0] - - #Default rules - #discard malicious packets - -A INPUT -p tcp --tcp-flags ALL ACK,RST,SYN,FIN -j DROP - -A INPUT -p tcp --tcp-flags SYN,FIN SYN,FIN -j DROP - -A INPUT -p tcp --tcp-flags SYN,RST SYN,RST -j DROP - #Allow incoming ICMP - -A INPUT -p icmp -m icmp -j ACCEPT - #Accept localhost traffic - -A INPUT -i lo -j ACCEPT - # Allow already established sessions to remain - -A INPUT -m state --state RELATED,ESTABLISHED -j ACCEPT - - # Deny inbound SMTP delivery (still allows outbound connections) - -A INPUT -m state --state NEW -m tcp -p tcp --tcp-flags FIN,SYN,RST,ACK SYN --dport 25 -j NO-SMTP - -A NO-SMTP -j LOG --log-prefix " Incoming SMTP (denied) " - -A NO-SMTP -j DROP - - # Allow SSH Access - :SSH - [0:0] - -A INPUT -p tcp -m state --state NEW -m tcp --tcp-flags FIN,SYN,RST,ACK SYN --dport 22 -j SSH - -A SSH -s 192.168.0.0/255.255.0.0 -j ACCEPT - - # Allow Ganglia Access - -A INPUT -m state --state NEW -m tcp -p tcp --tcp-flags FIN,SYN,RST,ACK SYN --src 192.168.1.1 --dport 8649 -j ACCEPT - # Gmetad access to gmond - -A INPUT -m state --state NEW -m tcp -p tcp --tcp-flags FIN,SYN,RST,ACK SYN --src 192.168.1.1 --dport 8649 -j ACCEPT - # Gmond UDP multicast - -A INPUT -m state --state NEW -m udp -p udp --dport 8649 -j ACCEPT - - {% if metadata.groups %}\ - # group custom FILTER rules: - {% for group in metadata.groups %}\ - {% include ${checkGroupFile(group,'custom-filter')} %}\ - {% end %}\ - {% end %}\ - - # host-specific FILTER rules: - {% include ${checkHostFile(metadata.hostname, 'custom-filter')} %}\ - - COMMIT - # ------------------------------- NAT ---------------------------------- # - *nat - - # Default CHAINS for NAT: - :PREROUTING ACCEPT [0:0] - :OUTPUT ACCEPT [0:0] - :POSTROUTING ACCEPT [0:0] - - {% if metadata.groups %}\ - # group NAT for PREROUTING: - {% for group in metadata.groups %}\ - {% include ${checkGroupFile(group,'nat-prerouting')} %}\ - {% end %}\ - {% end %}\ - - {% if metadata.groups %}\ - # group NAT for OUTPUT: - {% for group in metadata.groups %}\ - {% include ${checkGroupFile(group,'nat-output')} %}\ - {% end %}\ - {% end %}\ - - {% if metadata.groups %}\ - # group NAT for POSTROUTING: - {% for group in metadata.groups %}\ - {% include ${checkGroupFile(group,'nat-postrouting')} %}\ - {% end %}\ - {% end %}\ - - {% if metadata.groups %}\ - # group custom NAT rules: - {% for group in metadata.groups %}\ - {% include ${checkGroupFile(group,'custom-nat')} %}\ - {% end %}\ - {% end %}\ - - # host-specific NAT ruls: - {% include ${checkHostFile(metadata.hostname, 'custom-nat')} %}\ - COMMIT - # ----------------------------- MANGLE -------------------------------- # - *mangle - - # Default CHAINS for MANGLE: - :PREROUTING ACCEPT [0:0] - :INPUT ACCEPT [0:0] - :FORWARD ACCEPT [0:0] - :OUTPUT ACCEPT [0:0] - :POSTROUTING ACCEPT [0:0] - - {% if metadata.groups %}\ - # group MANGLE for PREROUTING: - {% for group in metadata.groups %}\ - {% include ${checkGroupFile(group,'mangle-prerouting')} %}\ - {% end %}\ - {% end %}\ - - {% if metadata.groups %}\ - # group MANGLE for INPUT: - {% for group in metadata.groups %}\ - {% include ${checkGroupFile(group,'mangle-input')} %}\ - {% end %}\ - {% end %}\ - - {% if metadata.groups %}\ - # group MANGLE for FORWARD: - {% for group in metadata.groups %}\ - {% include ${checkGroupFile(group,'mangle-forward')} %}\ - {% end %}\ - {% end %}\ - - {% if metadata.groups %}\ - # group MANGLE for OUTPUT: - {% for group in metadata.groups %}\ - {% include ${checkGroupFile(group,'mangle-output')} %}\ - {% end %}\ - {% end %}\ - - {% if metadata.groups %}\ - # group MANGLE for POSTROUTING rules: - {% for group in metadata.groups %}\ - {% include ${checkGroupFile(group,'mangle-postrouting')} %}\ - {% end %}\ - {% end %}\ - - {% if metadata.groups %}\ - # group custom MANGLE rules: - {% for group in metadata.groups %}\ - {% include ${checkGroupFile(group,'custom-mangle')} %}\ - {% end %}\ - {% end %}\ - - # host-specific MANGLE rules: - {% include ${checkHostFile(metadata.hostname, 'custom-mangle')} %}\ - COMMIT - -/var/lib/bcfg2/custom/etc/sysconfig/iptables/custom-filter.G_mysql-server -------------------------------------------------------------------------- - -:: - - :MYSQL - [0:0] - -A INPUT -p tcp -m state --state NEW -m tcp --dport 3306 --tcp-flags FIN,SYN,RST,ACK SYN -j MYSQL - -A MYSQL -s 192.168.0.0/255.255.0.0 -j ACCEPT - -For a host that is in the mysql-server group you get an iptables file -that looks like the following:: - - # BCFG2 GENERATED IPTABLES - # DO NOT CHANGE THIS - # $Id: template.newtxt 5402 2009-08-19 22:50:06Z unixmouse$ - # $HeadURL: https://svn.fakecompany.net/bcfg2/trunk/repository/TGenshi/etc/sysconfig/iptables/template.newtxt $ - # Templates live in /var/lib/bcfg2/custom/etc/sysconfig/iptables/ - # Manual customization of this file will get reverted. - # ----------------------------- FILTER --------------------------------- # - # Default CHAINS for FILTER: - *filter - :INPUT DROP [0:0] - :FORWARD DROP [0:0] - :OUTPUT ACCEPT [0:0] - :NO-SMTP - [0:0] - - #Default rules - #discard malicious packets - -A INPUT -p tcp --tcp-flags ALL ACK,RST,SYN,FIN -j DROP - -A INPUT -p tcp --tcp-flags SYN,FIN SYN,FIN -j DROP - -A INPUT -p tcp --tcp-flags SYN,RST SYN,RST -j DROP - # Allow incoming ICMP - -A INPUT -p icmp -m icmp -j ACCEPT - # Accept localhost traffic - -A INPUT -i lo -j ACCEPT - # Allow already established sessions to remain - -A INPUT -m state --state RELATED,ESTABLISHED -j ACCEPT - - # Deny inbound SMTP delivery (still allows outbound connections) - -A INPUT -m state --state NEW -m tcp -p tcp --tcp-flags FIN,SYN,RST,ACK SYN --dport 25 -j NO-SMTP - -A NO-SMTP -j LOG --log-prefix " Incoming SMTP (denied) " - -A NO-SMTP -j DROP - - # Allow SSH Access - :SSH - [0:0] - -A INPUT -p tcp -m state --state NEW -m tcp --tcp-flags FIN,SYN,RST,ACK SYN --dport 22 -j SSH - -A SSH -s 192.168.0.0/255.255.0.0 -j ACCEPT - - # Allow Ganglia Access - -A INPUT -m state --state NEW -m tcp -p tcp --tcp-flags FIN,SYN,RST,ACK SYN --src 192.168.1.1 --dport 8649 -j ACCEPT - #Gmetad access to gmond - -A INPUT -m state --state NEW -m tcp -p tcp --tcp-flags FIN,SYN,RST,ACK SYN --src 192.168.1.1 --dport 8649 -j ACCEPT - #Gmond UDP multicast - -A INPUT -m state --state NEW -m udp -p udp --dport 8649 -j ACCEPT - - # group custom FILTER rules: - :MYSQL - [0:0] - -A INPUT -p tcp -m state --state NEW -m tcp --dport 3306 --tcp-flags FIN,SYN,RST,ACK SYN -j MYSQL - -A MYSQL -s 192.168.0.0/255.255.0.0 -j ACCEPT - - # host-specific FILTER rules: - - COMMIT - # ------------------------------- NAT ---------------------------------- # - *nat - - # Default CHAINS for NAT: - :PREROUTING ACCEPT [0:0] - :OUTPUT ACCEPT [0:0] - :POSTROUTING ACCEPT [0:0] - - # group NAT for PREROUTING: - - # group NAT for OUTPUT: - - # group NAT for POSTROUTING: - - # group custom NAT rules: - - # host-specific NAT rules: - COMMIT - # ----------------------------- MANGLE -------------------------------- # - *mangle - - # Default CHAINS for MANGLE: - :PREROUTING ACCEPT [0:0] - :INPUT ACCEPT [0:0] - :FORWARD ACCEPT [0:0] - :OUTPUT ACCEPT [0:0] - :POSTROUTING ACCEPT [0:0] - - # group MANGLE for PREROUTING: - - # group MANGLE for INPUT: - # group MANGLE for FORWARD: - - # group MANGLE for OUTPUT: - - # group MANGLE for POSTROUTING rules: - - # group custom MANGLE rules: - - # host-specific MANGLE rules: - COMMIT diff --git a/doc/server/plugins/generators/tgenshi/motd.txt b/doc/server/plugins/generators/tgenshi/motd.txt deleted file mode 100644 index 1e2f3e4b9..000000000 --- a/doc/server/plugins/generators/tgenshi/motd.txt +++ /dev/null @@ -1,169 +0,0 @@ -.. -*- mode: rst -*- - -.. _server-plugins-generators-tgenshi-motd: - -motd -==== - -The following template automatically generates a MOTD (message of the -day) file that describes the system in terms of its Bcfg2 metadata -and probe responses. It conditionally displays groups, categories, -and probe responses, if there exists any data for them. - -New Style of TGenshi --------------------- - -This is the preferred way of creating TGenshi contents. It requires -Genshi 0.5 or later. - -On the Bcfg2 server -^^^^^^^^^^^^^^^^^^^ - -Where, **$bcfg2** is your Bcfg2 repository on your Bcfg2 server, the -following files need to be created: - -:: - - $bcfg2/TGenshi/etc/motd/info.xml - $bcfg2/TGenshi/etc/motd/template.newtxt - -The contents of ``motd/template.newtxt`` could be something like this:: - - ------------------------------------------------------------------------ - GOALS FOR SERVER MANGED BY BCFG2 - ------------------------------------------------------------------------ - Hostname is ${metadata.hostname} - - Groups: - {% for group in metadata.groups %}\ - * ${group} - {% end %}\ - - {% if metadata.categories %}\ - Categories: - {% for category in metadata.categories %}\ - * ${category} - {% end %}\ - {% end %}\ - - - {% if metadata.Probes %}\ - Probes: - {% for probe, value in metadata.Probes.iteritems() %}\ - * ${probe} \ - ${value} - {% end %}\ - {% end %}\ - - ------------------------------------------------------------------------- - ITOPS MOTD - ------------------------------------------------------------------------- - Please create a Ticket for any system level changes you need from IT. - -This template gets the hostname, groups membership of the host, categories -of the host (if any), and result of probes on the host (if any). The -template formats this in with a header and footer that makes it visually -more appealing. - -A ``motd/info.xml`` file isn't strictly needed, because ``/etc/motd`` -has the Bcfg2 default permissions (i.e. root:root 0644), but it can be -included for completeness. - -Output -^^^^^^ - -One possible output of this template would be the following:: - - ------------------------------------------------------------------------ - GOALS FOR SERVER MANGED BY BCFG2 - ------------------------------------------------------------------------ - Hostname is cobra.example.com - - Groups: - * oracle-server - * centos5-5.2 - * centos5 - * redhat - * x86_64 - * sys-vmware - - Categories: - * os-variant - * os - * database-server - * os-version - - - Probes: - * arch x86_64 - * network intranet_network - * diskspace Filesystem Size Used Avail Use% Mounted on - /dev/mapper/VolGroup00-LogVol00 - 18G 2.1G 15G 13% / - /dev/sda1 99M 13M 82M 13% /boot - tmpfs 3.8G 0 3.8G 0% /dev/shm - /dev/mapper/mhcdbo-clear - 1.5T 198M 1.5T 1% /mnt/san-oracle - * virtual vmware - - ------------------------------------------------------------------------- - IT MOTD - ------------------------------------------------------------------------- - Please create a Ticket for any system level changes you need from IT. - -Taking it to the next level -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -One way to make this even more useful, is to only include the result of -certain probes. It would also be a nice feature to be able to include -customer messages on a host or group level. - -Old Style of TGenshi --------------------- - -The following is a way to do the same thing using the older, -it-may-be-depreciated, style of Genshi (pre-0.5).:: - - Hostname is $metadata.hostname - - Groups: - #for group in metadata.groups - * $group - #end - - #if metadata.categories - Categories: - #for category in metadata.categories - * $category - #end - #end - - #if metadata.probes - Probes: - #for probe, value in metadata.probes.iteritems() - * $probe $value - #end - #end - -This template results in:: - - > buildfile /bar.conf ubik3 - Hostname is ubik3 - - Groups: - * desktop - * computeserver - * mcs-base - * ypbound - * workstation - * mysql-4 - * debian-sarge-base - * debian-sarge - * base - * debian - - Categories: - * noyp - * mysql - - diff --git a/doc/server/plugins/generators/tgenshi/mycnf.txt b/doc/server/plugins/generators/tgenshi/mycnf.txt deleted file mode 100644 index 7cf48ece0..000000000 --- a/doc/server/plugins/generators/tgenshi/mycnf.txt +++ /dev/null @@ -1,34 +0,0 @@ -.. -*- mode: rst -*- - -.. _server-plugins-generators-tgenshi-mycnf: - -mycnf -===== - -The following template generates a ``server-id`` based on the last two -numeric parts of the IP address. The "slave" portion of the configuration -only applies to machines in the "slave" group.:: - - {% python - from genshi.builder import tag - import socket - parts = socket.gethostbyname(metadata.hostname).split('.') - server_id = parts[2] + parts[3] - %}\ - [mysqld] - - # [snip] - - server-id = ${server_id} - - # Replication configuration - - {% if "slave" in metadata.groups %}\ - relay-log = /data01/mysql/log/mysql-relay-bin - log-slave-updates = 1 - {% end %}\ - sync-binlog = 1 - #read-only = 1 - #report-host = - - # [snip] diff --git a/doc/server/plugins/generators/tgenshi/test.txt b/doc/server/plugins/generators/tgenshi/test.txt deleted file mode 100644 index c047b88d0..000000000 --- a/doc/server/plugins/generators/tgenshi/test.txt +++ /dev/null @@ -1,159 +0,0 @@ -.. -*- mode: rst -*- - -.. _server-plugins-generators-tgenshi-test: - -test -==== - -FIXME: This example needs to be retested with new Properties plugin. - -As submitted by dclark - -This file just shows you what's available. It assumes a -``/var/lib/bcfg2/Properties/test.xml`` file with an entry like this: - -.. code-block:: xml - - #!text/xml - - - fakeBCFG2password - - - -:: - - Hostname is ${metadata.hostname} - - Groups: - {% for group in metadata.groups %}\ - ${group} \ - {% end %}\ - - {% if metadata.categories %}\ - Categories: - {% for category in metadata.categories %}\ - ${category} \ - {% end %}\ - {% end %}\ - - {% if metadata.Probes %}\ - Probes: - {% for probe, value in metadata.Probes.iteritems() %}\ - $probe $value - {% end %}\ - {% end %}\ - - Two main ways to get the same property value: - ${metadata.Properties['test.xml'].xdata.find('password').find('bcfg2').text} - ${metadata.Properties['test.xml'].xdata.xpath('password/bcfg2')[0].text} - - One way to get information about metadata and properties: - - dir(metadata): - {% for var in dir(metadata) %}\ - ${var} \ - {% end %} - - dir(metadata.Properties.xdata): - {% for var in dir(metadata.Properties.xdata) %}\ - ${var} \ - {% end %} - - dir(metadata.Properties.xdata.entries): - {% for var in dir(metadata.Properties.xdata.entries) %}\ - ${var} \ - {% end %} - - dir(metadata.Properties.xdata.label): - {% for var in dir(metadata.Properties.xdata.label) %}\ - ${var} \ - {% end %} - - dir(metadata.Properties.xdata.name): - {% for var in dir(metadata.Properties.xdata.name) %}\ - ${var} \ - {% end %} - - dir(metadata.Properties.xdata.properties): - {% for var in dir(metadata.Properties.xdata.properties) %}\ - ${var} \ - {% end %} - -When the above file is saved as -``/var/lib/bcfg2/TGenshi/test/template.newtxt`` and generated with -``bcfg2-info buildfile /test test.hostname.org``, the results look like -this (below reformatted a little bit to fit in 80 columns):: - - Failed to read file probed.xml - Processed 44 gamin events in 0.108 seconds. 0 collapsed - Processed 17 gamin events in 0.245 seconds. 0 collapsed - Processed 17 gamin events in 0.163 seconds. 0 collapsed - Processed 21 gamin events in 0.197 seconds. 0 collapsed - Processed 0 gamin events in 0.100 seconds. 0 collapsed - Processed 12 gamin events in 0.105 seconds. 0 collapsed - Processed 0 gamin events in 0.100 seconds. 0 collapsed - - - Hostname is test.hostname.org - - Groups: - bcfg2-server - - - Two main ways to get the same property value: - fakeBCFG2password - fakeBCFG2password - - One way to get information about metadata and properties: - - dir(metadata): - __class__ __delattr__ __dict__ __doc__ __getattribute__ __hash__ __init__ - __module__ __new__ __reduce__ __reduce_ex__ __repr__ __setattr__ __str__ - __weakref__ all bundles categories get_clients_by_group get_clients_by_profile - groups hostname inGrouppassword probes uuid - - dir(metadata.Properties.xdata): - HandleEvent Index __class__ __delattr__ __dict__ __doc__ __getattribute__ - __hash__ __identifier__ __init__ __iter__ __module__ __new__ __reduce__ - __reduce_ex__ __repr__ __setattr__ __str__ __weakref__ entries label name - properties - - dir(metadata.Properties.xdata.entries): - __add__ __class__ __contains__ __delattr__ __delitem__ __delslice__ __doc__ - __eq__ __ge__ __getattribute__ __getitem__ __getslice__ __gt__ __hash__ - __iadd__ __imul__ __init__ __iter__ __le__ __len__ __lt__ __mul__ __ne__ - __new__ __reduce__ __reduce_ex__ __repr__ __reversed__ __rmul__ __setattr__ - __setitem__ __setslice__ __str__ append count extend index insert pop remove - reverse sort - - dir(metadata.Properties.xdata.label): - __add__ __class__ __contains__ __delattr__ __doc__ __eq__ __ge__ - __getattribute__ __getitem__ __getnewargs__ __getslice__ __gt__ __hash__ - __init__ __le__ __len__ __lt__ __mod__ __mul__ __ne__ __new__ __reduce__ - __reduce_ex__ __repr__ __rmod__ __rmul__ __setattr__ __str__ capitalize center - count decode encode endswith expandtabs find index isalnum isalpha isdigit - islower isspace istitle isupper join ljust lower lstrip partition replace - rfind rindex rjust rpartition rsplit rstrip split splitlinesstartswith strip - swapcase title translate upper zfill - - dir(metadata.Properties.xdata.name): - __add__ __class__ __contains__ __delattr__ __doc__ __eq__ __ge__ - __getattribute__ __getitem__ __getnewargs__ __getslice__ __gt__ __hash__ - __init__ __le__ __len__ __lt__ __mod__ __mul__ __ne__ __new__ __reduce__ - __reduce_ex__ __repr__ __rmod__ __rmul__ __setattr__ __str__ capitalize center - count decode encode endswith expandtabs find index isalnum isalpha isdigit - islower isspace istitle isupper join ljust lower lstrip partition replace - rfind rindex rjust rpartition rsplit rstrip split splitlinesstartswith strip - swapcase title translate upper zfill - - dir(metadata.Properties.xdata.properties): - __class__ __contains__ __copy__ __deepcopy__ __delattr__ __delitem__ - __delslice__ __doc__ __getattribute__ __getitem__ __getslice__ __hash__ - __init__ __iter__ __len__ __new__ __nonzero__ __reduce__ __reduce_ex__ - __repr__ __reversed__ __setattr__ __setitem__ __setslice__ __str__ _init - addnext addprevious append attrib clear extend find findall findtext get - getchildren getiterator getnext getparent getprevious getroottree index insert - items iterancestors iterchildren iterdescendants itersiblings keys makeelement - nsmap prefix remove replace set sourceline tag tail text values xpath - diff --git a/doc/server/plugins/grouping/metadata.txt b/doc/server/plugins/grouping/metadata.txt index 4e716bc1b..0a7d1780b 100644 --- a/doc/server/plugins/grouping/metadata.txt +++ b/doc/server/plugins/grouping/metadata.txt @@ -366,44 +366,43 @@ the caching features available. ClientMetadata ============== -A special client metadata class is available to the -:ref:`TGenshi ` and -:ref:`TCheetah ` plugins. - -+----------------------+------------------------------------------------+-------------------+ -| Attribute | Description | Value | -+======================+================================================+===================+ -| hostname | Client hostname | String | -+----------------------+------------------------------------------------+-------------------+ -| profile | Client profile | String | -+----------------------+------------------------------------------------+-------------------+ -| aliases | Client aliases | List | -+----------------------+------------------------------------------------+-------------------+ -| addresses | Adresses this client is known by | List | -+----------------------+------------------------------------------------+-------------------+ -| groups | Groups this client is a member of | List | -+----------------------+------------------------------------------------+-------------------+ -| categories | Categories of this clients groups | List | -+----------------------+------------------------------------------------+-------------------+ -| uuid | uuid identifier for this client | String | -+----------------------+------------------------------------------------+-------------------+ -| password | bcfg password for this client | String | -+----------------------+------------------------------------------------+-------------------+ -| connectors | connector plugins known to this client | List | -+----------------------+------------------------------------------------+-------------------+ -| query | MetadataQuery object | MetadataQuery | -+----------------------+------------------------------------------------+-------------------+ - -| - -+------------------------------+------------------------------------------------+-------------------+ -| Method | Description | Value | -+==============================+================================================+===================+ -| inGroup(group) | True if this client is a memnber of 'group' | Boolean | -+------------------------------+------------------------------------------------+-------------------+ -| group_in_category(category) | Returns the group in 'category' if the client | String | -| | is a member of 'category', otherwise '' | | -+------------------------------+------------------------------------------------+-------------------+ +A special client metadata class is available to +:ref:`server-plugins-generators-cfg-genshi` and +:ref:`server-plugins-generators-cfg-cheetah`. + ++------------+------------------------------------------------+---------------+ +| Attribute | Description | Value | ++============+================================================+===============+ +| hostname | Client hostname | String | ++------------+------------------------------------------------+---------------+ +| profile | Client profile | String | ++------------+------------------------------------------------+---------------+ +| aliases | Client aliases | List | ++------------+------------------------------------------------+---------------+ +| addresses | Adresses this client is known by | List | ++------------+------------------------------------------------+---------------+ +| groups | Groups this client is a member of | List | ++------------+------------------------------------------------+---------------+ +| categories | Categories of this clients groups | List | ++------------+------------------------------------------------+---------------+ +| uuid | uuid identifier for this client | String | ++------------+------------------------------------------------+---------------+ +| password | bcfg password for this client | String | ++------------+------------------------------------------------+---------------+ +| connectors | connector plugins known to this client | List | ++------------+------------------------------------------------+---------------+ +| query | MetadataQuery object | MetadataQuery | ++------------+------------------------------------------------+---------------+ + + ++-----------------------------+------------------------------------------------+-------------------+ +| Method | Description | Value | ++=============================+================================================+===================+ +| inGroup(group) | True if this client is a memnber of 'group' | Boolean | ++-----------------------------+------------------------------------------------+-------------------+ +| group_in_category(category) | Returns the group in 'category' if the client | String | +| | is a member of 'category', otherwise '' | | ++-----------------------------+------------------------------------------------+-------------------+ MetadataQuery ------------- diff --git a/doc/server/plugins/index.txt b/doc/server/plugins/index.txt index ca1cf459a..a98c95e8a 100644 --- a/doc/server/plugins/index.txt +++ b/doc/server/plugins/index.txt @@ -66,7 +66,6 @@ Literal Configuration (Generators) :glob: generators/* - generators/tgenshi/index Each of these plugins has a corresponding subdirectory with the same name in the Bcfg2 repository. diff --git a/doc/server/plugins/probes/index.txt b/doc/server/plugins/probes/index.txt index 26c656374..3c19ced55 100644 --- a/doc/server/plugins/probes/index.txt +++ b/doc/server/plugins/probes/index.txt @@ -13,16 +13,7 @@ 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. -For the purposes of this example, you will need to set up the TCheetah -plugin, as described on the :ref:`server-plugins-generators-tcheetah` -page. - -.. note:: - - This does **not** mean that TCheetah is required in order for Probes - to operate properly. - -Next, we need to create a ``Probes`` directory in our toplevel repository +First, create a ``Probes`` directory in our toplevel repository location:: mkdir /var/lib/bcfg2/Probes @@ -69,12 +60,15 @@ it also counts the controller as a device. To differentiate between the two classes of machines we care about, we just need to check the output of this script for numbers greater than 2. We do this in the template. -The ``TCheetah/`` directory is laid out much like the ``Cfg/`` directory. -For this example we will want to create a ``TCheetah/etc/auto.master`` +This example uses :ref:`server-plugins-generators-cfg-cheetah`, but +Cheetah templates are **not** required in order for Probes to operate +properly. + +For the template we will want to create a ``Cfg/etc/auto.master`` directory to hold the template of the file in question. Inside of this -template we will need to check the result of the Probe script that -got run and act accordingly. The ``TCheetah/etc/auto.master/template`` -file looks like:: +template we will need to check the result of the Probe script that got +run and act accordingly. The +``Cfg/etc/auto.master/auto.master.cheetah`` file looks like:: /software /etc/auto.software --timeout 3600 /home /etc/auto.home --timeout 3600 @@ -116,8 +110,9 @@ 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:: +client's metadata object. To access this data in +:ref:`server-plugins-generators-cfg-genshi`, for instance, you could +do:: ${metadata.Probes['script-name']} diff --git a/doc/server/plugins/structures/altsrc.txt b/doc/server/plugins/structures/altsrc.txt index bed170b9c..1268a8584 100644 --- a/doc/server/plugins/structures/altsrc.txt +++ b/doc/server/plugins/structures/altsrc.txt @@ -26,12 +26,13 @@ Use Cases Examples ======== -* Consider the case of /etc/hosts on linux and /etc/inet/hosts - on solaris. These files contain the same data in the same format, - and should typically be synchronized, however, exist in different - locations. Classically, one would need to create one entry for each in - Cfg or TCheetah and perform manual synchronization. Or, you could use - symlinks and pray. Altsrc is driven from the bundle side. For example: +* Consider the case of /etc/hosts on linux and /etc/inet/hosts on + solaris. These files contain the same data in the same format, and + should typically be synchronized, however, exist in different + locations. Classically, one would need to create one entry for each + in Cfg and perform manual synchronization. Or, you could use + symlinks and pray. Altsrc is driven from the bundle side. For + example: .. code-block:: xml @@ -66,11 +67,11 @@ Examples "openssl-rpm", but will be delivered to the client with both packages named "openssl" with different types. -* Finally, consider the case where there exist complicated, but - completely independent specifications for the same configuration entry - but different groups of clients. The following bundle will allow the - use of two different TCheetah templates /etc/firewall-rules-external - and /etc/firewall-rules-internal for different clients based on their +* Consider the case where there exist complicated, but completely + independent specifications for the same configuration entry but + different groups of clients. The following bundle will allow the use + of two different templates /etc/firewall-rules-external and + /etc/firewall-rules-internal for different clients based on their group membership. .. code-block:: xml @@ -86,11 +87,13 @@ Examples * Consider the case where a variety of files can be constructed by a - single template (TCheetah or TGenshi). It would be possible to copy - this template into the proper location for each file, but that requires - proper synchronization upon modification and knowing up front what - the files will all be called. Instead, the following bundle allows - the use of a single template for all proper config file instances. + single :ref:`Genshi ` or + :ref:`Cheetah ` template. It + would be possible to copy this template into the proper location for + each file, but that requires proper synchronization upon + modification and knowing up front what the files will all be + called. Instead, the following bundle allows the use of a single + template for all proper config file instances. .. code-block:: xml diff --git a/doc/server/plugins/structures/bundler/index.txt b/doc/server/plugins/structures/bundler/index.txt index 3184fe6eb..528df79db 100644 --- a/doc/server/plugins/structures/bundler/index.txt +++ b/doc/server/plugins/structures/bundler/index.txt @@ -207,9 +207,8 @@ in their name. The following template produces such a config file entry. Depending on the circumstance, these configuration files can either be handled by individual entries in :ref:`server-plugins-generators-cfg`, -:ref:`server-plugins-generators-tcheetah`, or -:ref:`server-plugins-generators-tgenshi-index`, or can be mapped to a -single entry by using the :ref:`server-plugins-structures-altsrc` feature. +or can be mapped to a single entry by using the +:ref:`server-plugins-structures-altsrc` feature. In this example, configuration file names are built using probed results from the client. getmac is a probe that gathers client MAC addresses diff --git a/doc/unsorted/howtos.txt b/doc/unsorted/howtos.txt index 4347632f6..0c5b482d9 100644 --- a/doc/unsorted/howtos.txt +++ b/doc/unsorted/howtos.txt @@ -12,8 +12,6 @@ Here are several howtos that describe different aspects of Bcfg2 deployment * AnnotatedExamples - a description of basic Bcfg2 specification operations * BuildingDebianPackages - How to build debian packages * :ref:`appendix-guides-gentoo` - Issues specific to running Bcfg2 on Gentoo -* :ref:`server-plugins-generators-tcheetah` - Howto use the TCheetah template plugin -* :ref:`server-plugins-generators-hostbase` - How to use the Hostbase plugin and web interface * :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 diff --git a/doc/unsorted/windows.txt b/doc/unsorted/windows.txt index 128bc52d6..6da274724 100644 --- a/doc/unsorted/windows.txt +++ b/doc/unsorted/windows.txt @@ -21,7 +21,7 @@ be pretty trivial; it would differ from \*nix services in that it would be done Registry ======== -The best way of handling the registry may be to map it into a file-based representation on the server end. The Cfg and TCheetah plugins could then be used to set registry values as needed. +The best way of handling the registry may be to map it into a file-based representation on the server end. The Cfg plugin could then be used to set registry values as needed. Files ===== diff --git a/doc/unsorted/writing_specification.txt b/doc/unsorted/writing_specification.txt index 4fec9d9e9..5a6eec231 100644 --- a/doc/unsorted/writing_specification.txt +++ b/doc/unsorted/writing_specification.txt @@ -374,6 +374,6 @@ How the groups are configured is specific to the plugin, but here are two common methods: * xml configuration file (Pkgmgr, Rules) -* file name encoding (Cfg, TCheetah, SSHBase) +* file name encoding (Cfg, SSHBase) Details are included on each plugin's page. -- cgit v1.2.3-1-g7c22