<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>TGenshi — Bcfg2 1.3.0 documentation</title>
<link rel="stylesheet" href="../../../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../../../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../../../',
VERSION: '1.3.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../../../_static/jquery.js"></script>
<script type="text/javascript" src="../../../_static/underscore.js"></script>
<script type="text/javascript" src="../../../_static/doctools.js"></script>
<script type="text/javascript" src="../../../_static/sidebar.js"></script>
<link rel="shortcut icon" href="../../../_static/favicon.ico"/>
<link rel="top" title="Bcfg2 1.3.0 documentation" href="../../../index.html" />
<link rel="up" title="Plugins" href="../index.html" />
<link rel="next" title="bcfg2-cron" href="examples/genshi/bcfg2-cron.html" />
<link rel="prev" title="TCheetah" href="tcheetah.html" />
<link rel="stylesheet" href="../../../_static/bcfg2.css" type=""/>
</head>
<body>
<div style="text-align: left; padding: 10px 10px 15px 15px">
<a href="../../../index.html"><img src="../../../_static/bcfg2_logo.png" border="0" alt="sampledoc"/></a>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../../../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../../../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="examples/genshi/bcfg2-cron.html" title="bcfg2-cron"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="tcheetah.html" title="TCheetah"
accesskey="P">previous</a> |</li>
<li><a href="../../../index.html">home</a> | </li>
<!--<li><a href="../../../search.html">search</a> | </li>-->
<li><a href="../../../help/index.html">help</a> | </li>
<li><a href="../../../contents.html">documentation </a> »</li>
<li><a href="../../../contents.html" >Bcfg2 documentation 1.3.0</a> »</li>
<li><a href="../../index.html" >The Bcfg2 Server</a> »</li>
<li><a href="../index.html" accesskey="U">Plugins</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="tgenshi">
<span id="server-plugins-generators-tgenshi-index"></span><h1>TGenshi<a class="headerlink" href="#tgenshi" title="Permalink to this headline">¶</a></h1>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">The TGenshi plugin is deprecated. You should instead use
<a class="reference internal" href="cfg.html#server-plugins-generators-cfg-genshi"><em>Genshi Templates</em></a> in the Cfg plugin.</p>
</div>
<p>This page documents the TGenshi plugin. This plugin works with version
0.4 and newer of the genshi library.</p>
<p>The TGenshi plugin allows you to use the <a class="reference external" href="http://genshi.edgewall.org">Genshi</a> 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.</p>
<p>To begin, you will need to download and install the Genshi templating engine.</p>
<p>To install on CentOS or RHEL, run:</p>
<div class="highlight-python"><pre>sudo yum install python-genshi</pre>
</div>
<p>Once it is installed, you can enable it by adding <tt class="docutils literal"><span class="pre">TGenshi</span></tt> to the
generators line in <tt class="docutils literal"><span class="pre">/etc/bcfg2.conf</span></tt> on your Bcfg server. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">plugins</span> <span class="o">=</span> <span class="n">Base</span><span class="p">,</span><span class="n">Bundler</span><span class="p">,</span><span class="n">Cfg</span><span class="p">,</span><span class="o">...</span><span class="p">,</span><span class="n">TGenshi</span>
</pre></div>
</div>
<p>The TGenshi plugin makes use of a Cfg-like directory structure
located in in a TGenshi subdirectory of your repository, usually
<tt class="docutils literal"><span class="pre">/var/lib/bcfg2/TGenshi</span></tt>. 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.</p>
<p>If used with Genshi 0.5 or later the plugin also supports the <a class="reference external" href="http://genshi.edgewall.org/wiki/Documentation/0.5.x/text-templates.html">new
style</a>
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.</p>
<p>Only one template format may be used per file served. Info files are
identical to those used in <tt class="docutils literal"><span class="pre">Cfg</span></tt>, and <tt class="docutils literal"><span class="pre">info.xml</span></tt> files are
supported.</p>
<div class="section" id="inside-of-templates">
<h2>Inside of templates<a class="headerlink" href="#inside-of-templates" title="Permalink to this headline">¶</a></h2>
<ul>
<li><p class="first"><strong>metadata</strong> is the client’s <a class="reference internal" href="../grouping/metadata.html#server-plugins-grouping-metadata-clientmetadata"><em>metadata</em></a></p>
</li>
<li><p class="first"><strong>metadata.Properties</strong> is an xml document of unstructured data (only
available when used in conjunction with the
<a class="reference internal" href="../connectors/properties.html#server-plugins-connectors-properties"><em>Properties</em></a> plugin)</p>
</li>
<li><p class="first"><strong>name</strong> is the path name specified in bcfg</p>
</li>
<li><dl class="first docutils">
<dt><strong>path</strong> is the path to the TGenshi template. It starts with a</dt>
<dd><p class="first last">leading slash, and is relative to the Bcfg2 specification root.
E.g., <tt class="docutils literal"><span class="pre">/Cfg/etc/foo.conf/foo.conf.genshi</span></tt> or
<tt class="docutils literal"><span class="pre">/TGenshi/etc/foo.conf/template.newtxt.H_foo.example.com</span></tt></p>
</dd>
</dl>
</li>
</ul>
<p>See the genshi <a class="reference external" href="http://genshi.edgewall.org/wiki/Documentation">documentation</a> for examples of
Genshi syntax.</p>
<div class="section" id="examples-old-genshi-syntax">
<h3>Examples: Old Genshi Syntax<a class="headerlink" href="#examples-old-genshi-syntax" title="Permalink to this headline">¶</a></h3>
<p>Genshi’s web pages recommend against using this syntax, as it may
disappear from future releases.</p>
<div class="section" id="group-negation">
<h4>Group Negation<a class="headerlink" href="#group-negation" title="Permalink to this headline">¶</a></h4>
<p>Templates are also useful for cases where more sophisticated boolean
operations than those supported by Cfg are needed. For example, the
template:</p>
<div class="highlight-python"><pre>#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</pre>
</div>
<p>Produces:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><Path</span> <span class="na">type=</span><span class="s">"file"</span> <span class="na">name=</span><span class="s">"/bar.conf"</span> <span class="na">owner=</span><span class="s">"root"</span> <span class="na">mode=</span><span class="s">"0644"</span> <span class="na">group=</span><span class="s">"root"</span><span class="nt">></span>client is ypbound workstation
client is a desktop, but not an ubuntu desktop
<span class="nt"></Path></span>
</pre></div>
</div>
<p>This flexibility provides the ability to build much more compact and
succinct definitions of configuration contents than Cfg can.</p>
</div>
</div>
</div>
<div class="section" id="troubleshooting">
<h2>Troubleshooting<a class="headerlink" href="#troubleshooting" title="Permalink to this headline">¶</a></h2>
<p>When developing a template, you can see what the template would
generate on a client with <a class="reference internal" href="../../bcfg2-info.html#server-bcfg2-info"><em>bcfg2-info</em></a>:</p>
<div class="highlight-python"><pre>bcfg2-info buildfile <path> <hostname></pre>
</div>
<p>E.g.:</p>
<div class="highlight-python"><pre>bcfg2-info buildfile /etc/foo.conf foo.example.com</pre>
</div>
<p>To generate a file with an altsrc attribute, you can run:</p>
<div class="highlight-python"><pre>bcfg2-info buildfile /etc/foo/foo.conf --altsrc=/etc/foo.conf \
foo.example.com</pre>
</div>
<p>Sometimes, it’s useful to be able to do more in-depth troubleshooting
by running the template manually. To do this, run <tt class="docutils literal"><span class="pre">bcfg2-info</span>
<span class="pre">debug</span></tt>, and, once in the Python interpreter, run:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">metadata</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">build_metadata</span><span class="p">(</span><span class="s">"<hostname>"</span><span class="p">)</span>
<span class="n">path</span> <span class="o">=</span> <span class="s">"<relative path to template (see note below)>"</span>
</pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">path</span></tt> should be set to the path to the template file with a leading
slash, relative to the Bcfg2 specification root. See <a class="reference internal" href="#inside-of-templates">Inside of
Templates</a> for examples.</p>
<p>Then, run:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">os</span><span class="o">,</span> <span class="nn">Bcfg2.Options</span>
<span class="kn">from</span> <span class="nn">genshi.template</span> <span class="kn">import</span> <span class="n">TemplateLoader</span><span class="p">,</span> <span class="n">NewTextTemplate</span>
<span class="n">name</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">dirname</span><span class="p">(</span><span class="n">path</span><span class="p">[</span><span class="n">path</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="s">'/'</span><span class="p">,</span> <span class="mi">1</span><span class="p">):])</span>
<span class="n">setup</span> <span class="o">=</span> <span class="n">Bcfg2</span><span class="o">.</span><span class="n">Options</span><span class="o">.</span><span class="n">OptionParser</span><span class="p">({</span><span class="s">'repo'</span><span class="p">:</span>
<span class="n">Bcfg2</span><span class="o">.</span><span class="n">Options</span><span class="o">.</span><span class="n">SERVER_REPOSITORY</span><span class="p">})</span>
<span class="n">setup</span><span class="o">.</span><span class="n">parse</span><span class="p">(</span><span class="s">'--'</span><span class="p">)</span>
<span class="n">template</span> <span class="o">=</span> <span class="n">TemplateLoader</span><span class="p">()</span><span class="o">.</span><span class="n">load</span><span class="p">(</span><span class="n">setup</span><span class="p">[</span><span class="s">'repo'</span><span class="p">]</span> <span class="o">+</span> <span class="n">path</span><span class="p">,</span> <span class="n">cls</span><span class="o">=</span><span class="n">NewTextTemplate</span><span class="p">)</span>
<span class="k">print</span> <span class="n">template</span><span class="o">.</span><span class="n">generate</span><span class="p">(</span><span class="n">metadata</span><span class="o">=</span><span class="n">metadata</span><span class="p">,</span> <span class="n">path</span><span class="o">=</span><span class="n">path</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="n">name</span><span class="p">)</span><span class="o">.</span><span class="n">render</span><span class="p">()</span>
</pre></div>
</div>
<p>This gives you more fine-grained control over how your template is
rendered.</p>
<p>You can also use this approach to render templates that depend on
<a class="reference internal" href="../structures/altsrc.html#server-plugins-structures-altsrc"><em>altsrc</em></a> tags by setting
<tt class="docutils literal"><span class="pre">path</span></tt> to the path to the template, and setting <tt class="docutils literal"><span class="pre">name</span></tt> to the path
to the file to be generated, e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">metadata</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">build_metadata</span><span class="p">(</span><span class="s">"foo.example.com"</span><span class="p">)</span>
<span class="n">path</span> <span class="o">=</span> <span class="s">"/Cfg/etc/sysconfig/network-scripts/ifcfg-template/ifcfg-template.genshi"</span>
<span class="n">name</span> <span class="o">=</span> <span class="s">"/etc/sysconfig/network-scripts/ifcfg-bond0"</span>
</pre></div>
</div>
</div>
<div class="section" id="file-permissions">
<h2>File permissions<a class="headerlink" href="#file-permissions" title="Permalink to this headline">¶</a></h2>
<p>File permissions for entries handled by TGenshi are controlled via the
use of <a class="reference internal" href="../../info.html#server-info"><em>info.xml</em></a> files. Note that you <strong>cannot</strong> use both a
Permissions entry and a Path entry to handle the same file.</p>
</div>
<div class="section" id="error-handling">
<h2>Error handling<a class="headerlink" href="#error-handling" title="Permalink to this headline">¶</a></h2>
<p>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:</p>
<div class="highlight-python"><pre>{% 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"
%}\</pre>
</div>
<p>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:</p>
<div class="highlight-python"><pre>bcfg2-server[5957]: Genshi template error: Missing group
bcfg2-server[5957]: Failed to bind entry: Path /etc/ganglia/gmond.conf</pre>
</div>
<p>indicating the bind failure and message raised with the TemplateError.</p>
</div>
<div class="section" id="faqs">
<h2>FAQs<a class="headerlink" href="#faqs" title="Permalink to this headline">¶</a></h2>
<p><strong>Question</strong></p>
<p>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).</p>
<p><strong>Answer</strong></p>
<p>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 <a class="reference external" href="http://genshi.edgewall.org/ticket/282">#282: Document $$ escape
convention</a> and
<a class="reference external" href="http://genshi.edgewall.org/ticket/283">#283: Allow for redefinition of template syntax per-file</a>.</p>
</div>
<div class="section" id="examples">
<h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="examples/genshi/bcfg2-cron.html">bcfg2-cron</a></li>
<li class="toctree-l1"><a class="reference internal" href="examples/genshi/clientsxml.html">clients.xml</a></li>
<li class="toctree-l1"><a class="reference internal" href="examples/genshi/ganglia.html">ganglia</a></li>
<li class="toctree-l1"><a class="reference internal" href="examples/genshi/grubconf.html">grub.conf</a></li>
<li class="toctree-l1"><a class="reference internal" href="examples/genshi/hosts.html">hosts</a></li>
<li class="toctree-l1"><a class="reference internal" href="examples/genshi/iptables.html">iptables</a></li>
<li class="toctree-l1"><a class="reference internal" href="examples/genshi/motd.html">motd</a></li>
<li class="toctree-l1"><a class="reference internal" href="examples/genshi/mycnf.html">my.cnf</a></li>
<li class="toctree-l1"><a class="reference internal" href="examples/genshi/test.html">test</a></li>
</ul>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../../../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">TGenshi</a><ul>
<li><a class="reference internal" href="#inside-of-templates">Inside of templates</a><ul>
<li><a class="reference internal" href="#examples-old-genshi-syntax">Examples: Old Genshi Syntax</a><ul>
<li><a class="reference internal" href="#group-negation">Group Negation</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#troubleshooting">Troubleshooting</a></li>
<li><a class="reference internal" href="#file-permissions">File permissions</a></li>
<li><a class="reference internal" href="#error-handling">Error handling</a></li>
<li><a class="reference internal" href="#faqs">FAQs</a></li>
<li><a class="reference internal" href="#examples">Examples</a><ul>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="tcheetah.html"
title="previous chapter">TCheetah</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="examples/genshi/bcfg2-cron.html"
title="next chapter">bcfg2-cron</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../../../_sources/server/plugins/generators/tgenshi.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../../../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../../../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../../../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="examples/genshi/bcfg2-cron.html" title="bcfg2-cron"
>next</a> |</li>
<li class="right" >
<a href="tcheetah.html" title="TCheetah"
>previous</a> |</li>
<li><a href="../../../index.html">home</a> | </li>
<!--<li><a href="../../../search.html">search</a> | </li>-->
<li><a href="../../../help/index.html">help</a> | </li>
<li><a href="../../../contents.html">documentation </a> »</li>
<li><a href="../../../contents.html" >Bcfg2 documentation 1.3.0</a> »</li>
<li><a href="../../index.html" >The Bcfg2 Server</a> »</li>
<li><a href="../index.html" >Plugins</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2009-2013, Narayan Desai.
Last updated on Mar 20, 2013.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
distrib
>
Fedora
>
17
>
i386
>
media
>
updates
>
by-pkgid
>
b50d8ee6d7871fcc13c0677a9364ed59
>
files
>
471
