.. -*- mode: rst -*-

.. _plugins-generators-tgenshi:

=======
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
<http://genshi.edgewall.org>`_ 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 5, 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::

    generators = SSHbase,Cfg,Pkgmgr,Svcmgr,Rules,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
<http://genshi.edgewall.org/wiki/Documentation/0.5.x/text-templates.html>`_
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 metadata
* properties.properties is an xml document of unstructured data

See the genshi `documentation
<http://genshi.edgewall.org/wiki/Documentation>`_ for examples of
Genshi syntax.

Examples
========

See [wiki:Plugins/TGenshi/examples] for some TGenshi template examples, including the great starting point [wiki:Plugins/TGenshi/examples/motd /etc/motd]. They will use the new style of Genshi syntax, unless noted otherwise.

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

    <Path type="file" name="/bar.conf" owner="root" perms="0644" group="root">client is ypbound workstation
    client is a desktop, but not an ubuntu desktop
    </Path>

This flexibility provides the ability to build much more compact and succinct definitions of configuration contents than Cfg can.

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
<http://genshi.edgewall.org/ticket/282>`_ and `#283: Allow for
redefinition of template syntax per-file
<http://genshi.edgewall.org/ticket/283>`_.