<!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>