<!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>Bundler — 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="altsrc" href="../altsrc.html" /> <link rel="prev" title="Metadata" href="../../grouping/metadata.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="../altsrc.html" title="altsrc" accesskey="N">next</a> |</li> <li class="right" > <a href="../../grouping/metadata.html" title="Metadata" 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="bundler"> <span id="server-plugins-structures-bundler-index"></span><h1>Bundler<a class="headerlink" href="#bundler" title="Permalink to this headline">¶</a></h1> <p>Bundler is used to describe groups of inter-dependent configuration entries, such as the combination of packages, configuration files, and service activations that comprise typical Unix daemons. Bundles are used to add groups of configuration entries to the inventory of client configurations, as opposed to describing particular versions of those entries. For example, a bundle could say that the configuration file <tt class="docutils literal"><span class="pre">/etc/passwd</span></tt> should be included in a configuration, but will not describe the particular version of <tt class="docutils literal"><span class="pre">/etc/passwd</span></tt> that a given client will receive.</p> <p>Group and Client tags can be used inside of bundles to differentiate which entries particular clients will recieve; this is useful for the case where entries are named differently across systems; for example, one linux distro may have a package called openssh while another uses the name ssh. Configuration entries nested inside of Group elements only apply to clients who are a member of those groups; multiple nested groups must all apply. Also, groups may be negated; entries included in such groups will only apply to clients who are not a member of said group. The same applies to Client elements.</p> <p>The following is an annotated copy of a bundle:</p> <div class="highlight-xml"><div class="highlight"><pre><span class="nt"><Bundle</span> <span class="na">name=</span><span class="s">'ssh'</span> <span class="na">version=</span><span class="s">'2.0'</span><span class="nt">></span> <span class="nt"><Path</span> <span class="na">name=</span><span class="s">'/etc/ssh/ssh_host_dsa_key'</span><span class="nt">/></span> <span class="nt"><Path</span> <span class="na">name=</span><span class="s">'/etc/ssh/ssh_host_rsa_key'</span><span class="nt">/></span> <span class="nt"><Path</span> <span class="na">name=</span><span class="s">'/etc/ssh/ssh_host_dsa_key.pub'</span><span class="nt">/></span> <span class="nt"><Path</span> <span class="na">name=</span><span class="s">'/etc/ssh/ssh_host_rsa_key.pub'</span><span class="nt">/></span> <span class="nt"><Path</span> <span class="na">name=</span><span class="s">'/etc/ssh/ssh_host_key'</span><span class="nt">/></span> <span class="nt"><Path</span> <span class="na">name=</span><span class="s">'/etc/ssh/ssh_host_key.pub'</span><span class="nt">/></span> <span class="nt"><Path</span> <span class="na">name=</span><span class="s">'/etc/ssh/sshd_config'</span><span class="nt">/></span> <span class="nt"><Path</span> <span class="na">name=</span><span class="s">'/etc/ssh/ssh_config'</span><span class="nt">/></span> <span class="nt"><Path</span> <span class="na">name=</span><span class="s">'/etc/ssh/ssh_known_hosts'</span><span class="nt">/></span> <span class="nt"><Group</span> <span class="na">name=</span><span class="s">'rpm'</span><span class="nt">></span> <span class="nt"><Package</span> <span class="na">name=</span><span class="s">'openssh'</span><span class="nt">/></span> <span class="nt"><Package</span> <span class="na">name=</span><span class="s">'openssh-askpass'</span><span class="nt">/></span> <span class="nt"><Service</span> <span class="na">name=</span><span class="s">'sshd'</span><span class="nt">/></span> <span class="nt"><Group</span> <span class="na">name=</span><span class="s">'fedora'</span> <span class="nt">></span> <span class="nt"><Group</span> <span class="na">name=</span><span class="s">'fc14'</span> <span class="na">negate=</span><span class="s">'true'</span><span class="nt">></span> <span class="nt"><Package</span> <span class="na">name=</span><span class="s">'openssh-clients'</span><span class="nt">/></span> <span class="nt"></Group></span> <span class="nt"><Package</span> <span class="na">name=</span><span class="s">'openssh-server'</span><span class="nt">/></span> <span class="nt"></Group></span> <span class="nt"></Group></span> <span class="nt"><Group</span> <span class="na">name=</span><span class="s">'deb'</span><span class="nt">></span> <span class="nt"><Package</span> <span class="na">name=</span><span class="s">'ssh'</span><span class="nt">/></span> <span class="nt"><Service</span> <span class="na">name=</span><span class="s">'ssh'</span><span class="nt">/></span> <span class="nt"></Group></span> <span class="nt"><Client</span> <span class="na">name=</span><span class="s">'trust.example.com'</span><span class="nt">></span> <span class="nt"><Path</span> <span class="na">name=</span><span class="s">'/etc/ssh/shosts.equiv'</span><span class="nt">/></span> <span class="nt"></Client></span> <span class="nt"></Bundle></span> </pre></div> </div> <p>In this bundle, most of the entries are common to all systems. Clients in group <strong>deb</strong> get one extra package and service, while clients in group <strong>rpm</strong> get two extra packages and an extra service. In addition, clients in group <strong>fedora</strong> <em>and</em> group <strong>rpm</strong> get one extra package entries, unless they are not in the <strong>fc14</strong> group, in which case, they get an extra package. The client <strong>trust.example.com</strong> gets one extra file that is not distributed to any other clients. Notice that this file doesn’t describe which versions of these entries that clients should get, only that they should get them. (Admittedly, this example is slightly contrived, but demonstrates how group entries can be used in bundles)</p> <table border="1" class="docutils"> <colgroup> <col width="47%" /> <col width="53%" /> </colgroup> <thead valign="bottom"> <tr class="row-odd"><th class="head">Group/Hostname</th> <th class="head">Entry</th> </tr> </thead> <tbody valign="top"> <tr class="row-even"><td>all</td> <td>/etc/ssh/ssh_host_dsa_key</td> </tr> <tr class="row-odd"><td>all</td> <td>/etc/ssh/ssh_host_rsa_key</td> </tr> <tr class="row-even"><td>all</td> <td>/etc/ssh/ssh_host_dsa_key.pub</td> </tr> <tr class="row-odd"><td>all</td> <td>/etc/ssh/ssh_host_rsa_key.pub</td> </tr> <tr class="row-even"><td>all</td> <td>/etc/ssh/ssh_host_key</td> </tr> <tr class="row-odd"><td>all</td> <td>/etc/ssh/ssh_host_key.pub</td> </tr> <tr class="row-even"><td>all</td> <td>/etc/ssh/sshd_config</td> </tr> <tr class="row-odd"><td>all</td> <td>/etc/ssh/ssh_config</td> </tr> <tr class="row-even"><td>all</td> <td>/etc/ssh/ssh_known_hosts</td> </tr> <tr class="row-odd"><td>rpm</td> <td>Package openssh</td> </tr> <tr class="row-even"><td>rpm</td> <td>Package openssh-askpass</td> </tr> <tr class="row-odd"><td>rpm</td> <td>Service sshd</td> </tr> <tr class="row-even"><td>rpm and fedora</td> <td>Package openssh-server</td> </tr> <tr class="row-odd"><td>rpm and fedora and not fc4</td> <td>Package openssh-clients</td> </tr> <tr class="row-even"><td>deb</td> <td>Package ssh</td> </tr> <tr class="row-odd"><td>deb</td> <td>Service ssh</td> </tr> <tr class="row-even"><td>trust.example.com</td> <td>/etc/ssh/shosts.equiv</td> </tr> </tbody> </table> <div class="section" id="genshi-templates"> <h2>Genshi templates<a class="headerlink" href="#genshi-templates" title="Permalink to this headline">¶</a></h2> <p>Genshi XML templates allow you to use the <a class="reference external" href="http://genshi.edgewall.org">Genshi</a> templating system to dynamically generate a bundle. Genshi templates can be specified one of two ways:</p> <ol class="arabic simple"> <li>Add an XML-style genshi template to the Bundler directory with a <tt class="docutils literal"><span class="pre">.genshi</span></tt> and the associated namespace attribute.</li> <li>Simply add the appropriate namespace attribute to your existing XML bundle.</li> </ol> <p>The top-level Bundle tag should look like the following:</p> <div class="highlight-python"><pre><Bundle name="foo" xmlns:py="http://genshi.edgewall.org/"></pre> </div> <p>Several variables are pre-defined inside templates:</p> <table border="1" class="docutils"> <colgroup> <col width="19%" /> <col width="81%" /> </colgroup> <thead valign="bottom"> <tr class="row-odd"><th class="head">Name</th> <th class="head">Description</th> </tr> </thead> <tbody valign="top"> <tr class="row-even"><td>metadata</td> <td><a class="reference internal" href="../../grouping/metadata.html#server-plugins-grouping-metadata-clientmetadata"><em>Client metadata</em></a></td> </tr> <tr class="row-odd"><td>repo</td> <td>The path to the Bcfg2 repository on the filesystem</td> </tr> </tbody> </table> <div class="admonition note"> <p class="first admonition-title">Note</p> <p><tt class="docutils literal"><span class="pre"><Group></span></tt> and <tt class="docutils literal"><span class="pre"><Client></span></tt> tags are allowed inside of Genshi templates as of Bcfg2 1.2. However, they do not behave the same as using a Genshi conditional, e.g.:</p> <div class="highlight-python"><pre><py:if test="'groupname' in metadata.groups"> </py:if></pre> </div> <p class="last">The conditional is evaluated when the template is rendered, so code inside the conditional is not executed if the conditional fails. A <tt class="docutils literal"><span class="pre"><Group></span></tt> tag is evaluated <em>after</em> the template is rendered, so code inside the tag is always executed. This is an important distinction: if you have code that will fail on some groups, you <em>must</em> use a Genshi conditional, not a <tt class="docutils literal"><span class="pre"><Group></span></tt> tag. The same caveats apply to <tt class="docutils literal"><span class="pre"><Client></span></tt> tags.</p> </div> <p>See also the <a class="reference internal" href="../../../genshi-xml.html#xml-genshi-reference"><em>Genshi XML Template Reference</em></a>.</p> <div class="section" id="troubleshooting"> <h3>Troubleshooting<a class="headerlink" href="#troubleshooting" title="Permalink to this headline">¶</a></h3> <p>To render a bundle for a given client, you can run:</p> <div class="highlight-python"><pre>bcfg2-info buildbundle <bundle name> <hostname></pre> </div> <p>This will render the template; it will not fully bind all of the entries in the bundle.</p> <p>See <a class="reference internal" href="../../../bcfg2-info.html#server-bcfg2-info"><em>bcfg2-info</em></a> for more details.</p> </div> </div> <div class="section" id="altsrc"> <h2>Altsrc<a class="headerlink" href="#altsrc" title="Permalink to this headline">¶</a></h2> <div class="toctree-wrapper compound"> <ul> <li class="toctree-l1"><a class="reference internal" href="../altsrc.html">altsrc</a></li> </ul> </div> </div> <div class="section" id="examples"> <h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2> <p>In some cases, configuration files need to include the client’s hostname in their name. The following template produces such a config file entry.</p> <div class="highlight-xml"><div class="highlight"><pre><span class="nt"><Bundle</span> <span class="na">name=</span><span class="s">'foo'</span> <span class="na">xmlns:py=</span><span class="s">"http://genshi.edgewall.org/"</span><span class="nt">></span> <span class="nt"><Path</span> <span class="na">name=</span><span class="s">'/etc/package-${metadata.hostname}'</span><span class="nt">/></span> <span class="nt"></Bundle></span> </pre></div> </div> <p>Depending on the circumstance, these configuration files can either be handled by individual entries in <a class="reference internal" href="../../generators/cfg.html#server-plugins-generators-cfg"><em>Cfg</em></a>, or can be mapped to a single entry by using the <a class="reference internal" href="../altsrc.html#server-plugins-structures-altsrc"><em>altsrc</em></a> feature.</p> <p>In this example, configuration file names are built using probed results from the client. getmac is a probe that gathers client MAC addresses and returns them in a newline delimited string.</p> <div class="highlight-xml"><div class="highlight"><pre><span class="nt"><Bundle</span> <span class="na">name=</span><span class="s">"networkinterfaces"</span> <span class="na">xmlns:py=</span><span class="s">"http://genshi.edgewall.org/"</span><span class="nt">></span> <span class="cp"><?python</span> <span class="cp"> files = metadata.Probes["getmacs"].split("\n")</span> <span class="cp"> ?></span> <span class="nt"><Path</span> <span class="na">py:for=</span><span class="s">"file in files"</span> <span class="na">name=</span><span class="s">"/etc/sysconfig/network/ifcfg-eth-${file}"</span> <span class="na">altsrc=</span><span class="s">"/etc/ifcfg-template"</span><span class="nt">/></span> <span class="nt"></Bundle></span> </pre></div> </div> <div class="admonition note"> <p class="first admonition-title">Note</p> <ul class="last simple"> <li>The use of the altsrc directive causes all ifcfg files to be handled by the same plugin and entry.</li> <li>The <?python ?> blocks have only been available in genshi since 0.4 (<a class="reference external" href="http://genshi.edgewall.org/ticket/84">http://genshi.edgewall.org/ticket/84</a>)</li> </ul> </div> <p>If you want a file to be only on a per-client basis, you can use an if declaration.</p> <div class="highlight-xml"><div class="highlight"><pre><span class="nt"><Bundle</span> <span class="na">name=</span><span class="s">'bacula'</span> <span class="na">xmlns:py=</span><span class="s">"http://genshi.edgewall.org/"</span><span class="nt">></span> <span class="nt"><Path</span> <span class="na">name=</span><span class="s">"/etc/bacula/bconsole.conf"</span><span class="nt">/></span> <span class="nt"><Path</span> <span class="na">name=</span><span class="s">"/etc/bacula/bacula-fd.conf"</span><span class="nt">/></span> <span class="nt"><Path</span> <span class="na">name=</span><span class="s">"/etc/bacula/bacula-sd.conf"</span><span class="nt">/></span> <span class="nt"><Path</span> <span class="na">py:if=</span><span class="s">"metadata.hostname == 'foo.bar.com'"</span> <span class="na">name=</span><span class="s">"/etc/bacula/bacula-dir.conf"</span><span class="nt">/></span> <span class="nt"></Bundle></span> </pre></div> </div> <p>or alternately</p> <div class="highlight-xml"><pre><Bundle name='bacula' xmlns:py="http://genshi.edgewall.org/"> <Path name="/etc/bacula/bconsole.conf"/> <Path name="/etc/bacula/bacula-fd.conf"/> <Path name="/etc/bacula/bacula-sd.conf"/> <py:if="metadata.hostname == 'foo.bar.com'"> <Path name="/etc/bacula/bacula-dir.conf"/> </py:if> </Bundle></pre> </div> <p>or yet another way</p> <div class="highlight-xml"><div class="highlight"><pre><span class="nt"><Bundle</span> <span class="na">name=</span><span class="s">'bacula'</span> <span class="na">xmlns:py=</span><span class="s">"http://genshi.edgewall.org/"</span><span class="nt">></span> <span class="nt"><Path</span> <span class="na">name=</span><span class="s">"/etc/bacula/bconsole.conf"</span><span class="nt">/></span> <span class="nt"><Path</span> <span class="na">name=</span><span class="s">"/etc/bacula/bacula-fd.conf"</span><span class="nt">/></span> <span class="nt"><Path</span> <span class="na">name=</span><span class="s">"/etc/bacula/bacula-sd.conf"</span><span class="nt">/></span> <span class="nt"><Client</span> <span class="na">name=</span><span class="s">"foo.bar.com"</span><span class="nt">></span> <span class="nt"><Path</span> <span class="na">name=</span><span class="s">"/etc/bacula/bacula-dir.conf"</span><span class="nt">/></span> <span class="nt"></Client></span> <span class="nt"></Bundle></span> </pre></div> </div> <p>The final form is preferred if there is no code inside the block that would fail on other clients.</p> <p>While these examples are simple, the test in the if block can in fact be any python statement.</p> </div> <div class="section" id="other-examples"> <span id="server-plugins-structures-bundler-index-examples"></span><h2>Other examples<a class="headerlink" href="#other-examples" title="Permalink to this headline">¶</a></h2> <p>Some simple examples of Bundles can be found in the <a class="reference external" href="https://github.com/solj/bcfg2-repo">Bcfg2 example repository</a>.</p> <p>In addition to the example repository, the following is a list of some more complex example Bundles.</p> <div class="toctree-wrapper compound"> <ul> <li class="toctree-l1"><a class="reference internal" href="kernel.html">kernel</a></li> <li class="toctree-l1"><a class="reference internal" href="moab.html">moab</a></li> <li class="toctree-l1"><a class="reference internal" href="nagios.html">nagios</a></li> <li class="toctree-l1"><a class="reference internal" href="ntp.html">ntp</a></li> <li class="toctree-l1"><a class="reference internal" href="snmpd.html">snmpd</a></li> <li class="toctree-l1"><a class="reference internal" href="torque.html">torque</a></li> <li class="toctree-l1"><a class="reference internal" href="yp.html">yp</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="#">Bundler</a><ul> <li><a class="reference internal" href="#genshi-templates">Genshi templates</a><ul> <li><a class="reference internal" href="#troubleshooting">Troubleshooting</a></li> </ul> </li> <li><a class="reference internal" href="#altsrc">Altsrc</a><ul> </ul> </li> <li><a class="reference internal" href="#examples">Examples</a></li> <li><a class="reference internal" href="#other-examples">Other examples</a><ul> </ul> </li> </ul> </li> </ul> <h4>Previous topic</h4> <p class="topless"><a href="../../grouping/metadata.html" title="previous chapter">Metadata</a></p> <h4>Next topic</h4> <p class="topless"><a href="../altsrc.html" title="next chapter">altsrc</a></p> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="../../../../_sources/server/plugins/structures/bundler/index.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="../altsrc.html" title="altsrc" >next</a> |</li> <li class="right" > <a href="../../grouping/metadata.html" title="Metadata" >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>