<!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>Getting started — 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="Bcfg2 documentation 1.3.0" href="../contents.html" />
<link rel="next" title="Detailed Bcfg2 Architecture" href="../architecture/index.html" />
<link rel="prev" title="Distribution-specific notes" href="../installation/distributions.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="../architecture/index.html" title="Detailed Bcfg2 Architecture"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="../installation/distributions.html" title="Distribution-specific notes"
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" accesskey="U">Bcfg2 documentation 1.3.0</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="getting-started">
<span id="getting-started-index"></span><h1>Getting started<a class="headerlink" href="#getting-started" title="Permalink to this headline">¶</a></h1>
<p>The steps below should get you from just thinking about a configuration
management system to an operational installation of Bcfg2. If you get
stuck, be sure to check the <a class="reference internal" href="../help/mailinglist.html#help-mailinglist"><em>Mailing List</em></a> or to drop in on
our <a class="reference internal" href="../help/irc.html#help-irc"><em>IRC Channel</em></a>.</p>
<p>See the <a class="reference internal" href="#platform-specific-quickstart-notes">Platform-specific Quickstart Notes</a> at the end of this page
if you happen to be using one of the more common operating systems.</p>
<div class="section" id="get-and-install-bcfg2-server">
<h2>Get and Install Bcfg2 Server<a class="headerlink" href="#get-and-install-bcfg2-server" title="Permalink to this headline">¶</a></h2>
<p>We recommend running the server on a Linux machine for ease of
deployment due to the availability of packages for the dependencies.</p>
<p>First, you need to download and install Bcfg2. The section
<a class="reference internal" href="../installation/index.html#installation-index"><em>Installation</em></a> in this manual describes the steps to take.
To start, you will need to install the server on one machine and the
client on one or more machines. Yes, your server can also be a client
(and should be by the time your environment is fully managed).</p>
</div>
<div class="section" id="set-up-repository">
<h2>Set up Repository<a class="headerlink" href="#set-up-repository" title="Permalink to this headline">¶</a></h2>
<p>The next step after installing the Bcfg2 packages is to configure the
server. You can easily set up a personalized default configuration by
running, on the server,</p>
<div class="highlight-python"><pre>bcfg2-admin init</pre>
</div>
<p>You will be presented with a series of questions that will build a
Bcfg2 configuration file in <tt class="docutils literal"><span class="pre">/etc/bcfg2.conf</span></tt>, set up a skeleton
repository (in <tt class="docutils literal"><span class="pre">/var/lib/bcfg2</span></tt> by default), help you create ssl
certificates, and do any other similar tasks needed to get you
started.</p>
<p>Once this process is done, you can start the Bcfg2 server:</p>
<div class="highlight-python"><pre>/etc/init.d/bcfg2-server start</pre>
</div>
<p>You can try it out by running the Bcfg2 client on the same machine,
acting like it is your first client.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The following command will tell the client to run in no-op mode,
meaning it will only check the client against the repository and
report any differences it sees. It won’t make any changes (partially
because you haven’t populated the repository with any yet). However,
nobody is perfect. You can make a typo, our software can have bugs,
monkeys can break in and hit enter before you are done. Don’t run
this command on a production system if you don’t know what it does
and aren’t prepared for the consequences. We don’t know of anybody
having problems with it before, but it is better to be safe than sorry.</p>
</div>
<p>And now for the command:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">bcfg2</span> <span class="o">-</span><span class="n">q</span> <span class="o">-</span><span class="n">v</span> <span class="o">-</span><span class="n">n</span>
</pre></div>
</div>
<p>That can be translated as “bcfg2 quick verbose no-op”. The output
should be something similar to:</p>
<div class="highlight-python"><pre>Loaded tool drivers:
Chkconfig POSIX YUMng
Phase: initial
Correct entries: 0
Incorrect entries: 0
Total managed entries: 0
Unmanaged entries: 242
Phase: final
Correct entries: 0
Incorrect entries: 0
Total managed entries: 0
Unmanaged entries: 242</pre>
</div>
<p>Perfect! We have started out with an empty configuration, and none of
our configuration elements are correct. It doesn’t get much cleaner
than that. But what about those unmanaged entries? Those are the extra
configuration elements (probably all packages and services at the
moment) that still aren’t managed, but have been detected by the client
tools. Your goal now is to migrate each of those plus any it can’t see
up to the “Correct entries” line.</p>
</div>
<div class="section" id="populate-repository">
<h2>Populate Repository<a class="headerlink" href="#populate-repository" title="Permalink to this headline">¶</a></h2>
<p>Finally, you need to populate your repository. Unfortunately, from
here on out we can’t write up a simple recipe for you to follow to get
this done. It is very dependent on your local configuration, your
configuration management goals, the politics surrounding your
particular machines, and many other similar details. We can, however,
give you guidance.</p>
<p>After the above steps, you should have a toplevel repository structure
that looks like:</p>
<div class="highlight-python"><pre>bcfg-server:~ # ls /var/lib/bcfg2
Base/ Bundler/ Cfg/ Metadata/ Pkgmgr/ Rules/ SSHbase/ etc/</pre>
</div>
<p>The place to start is the Metadata directory, which contains two
files: <tt class="docutils literal"><span class="pre">clients.xml</span></tt> and <tt class="docutils literal"><span class="pre">groups.xml</span></tt>. Your current
<tt class="docutils literal"><span class="pre">clients.xml</span></tt> will look pretty close to:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><Clients</span> <span class="na">version=</span><span class="s">"3.0"</span><span class="nt">></span>
<span class="nt"><Client</span> <span class="na">profile=</span><span class="s">"basic"</span> <span class="na">pingable=</span><span class="s">"Y"</span> <span class="na">pingtime=</span><span class="s">"0"</span> <span class="na">name=</span><span class="s">"bcfg-server.example.com"</span><span class="nt">/></span>
<span class="nt"></Clients></span>
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">clients.xml</span></tt> file is just a series of <tt class="docutils literal"><span class="pre"><Client</span> <span class="pre">/></span></tt> tags, each
of which describe one host you manage. Right now we only manage one
host, the server machine we just created. This machine is bound to the
<tt class="docutils literal"><span class="pre">basic</span></tt> profile, is pingable, has a pingtime of <tt class="docutils literal"><span class="pre">0</span></tt>, and has the
name <tt class="docutils literal"><span class="pre">bcfg-server.example.com</span></tt>. The two “ping” parameters don’t
matter to us at the moment, but the other two do. The name parameter
is the fully qualified domain name of your host, and the profile
parameter maps that host into the <tt class="docutils literal"><span class="pre">groups.xml</span></tt> file.</p>
<p>Our simple <tt class="docutils literal"><span class="pre">groups.xml</span></tt> file looks like:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><Groups</span> <span class="na">version=</span><span class="s">'3.0'</span><span class="nt">></span>
<span class="nt"><Group</span> <span class="na">profile=</span><span class="s">'true'</span> <span class="na">public=</span><span class="s">'false'</span> <span class="na">name=</span><span class="s">'basic'</span><span class="nt">></span>
<span class="nt"><Group</span> <span class="na">name=</span><span class="s">'suse'</span><span class="nt">/></span>
<span class="nt"></Group></span>
<span class="nt"><Group</span> <span class="na">name=</span><span class="s">'ubuntu'</span> <span class="nt">/></span>
<span class="nt"><Group</span> <span class="na">name=</span><span class="s">'debian'</span> <span class="nt">/></span>
<span class="nt"><Group</span> <span class="na">name=</span><span class="s">'redhat'</span> <span class="nt">/></span>
<span class="nt"><Group</span> <span class="na">name=</span><span class="s">'suse'</span> <span class="nt">/></span>
<span class="nt"><Group</span> <span class="na">name=</span><span class="s">'mandrake'</span> <span class="nt">/></span>
<span class="nt"><Group</span> <span class="na">name=</span><span class="s">'solaris'</span> <span class="nt">/></span>
<span class="nt"></Groups></span>
</pre></div>
</div>
<p>There are two types of groups in Bcfg: profile groups (<tt class="docutils literal"><span class="pre">profile='true'</span></tt>)
and non-profile groups (<tt class="docutils literal"><span class="pre">profile='false'</span></tt>). Profile groups can act as
top-level groups to which clients can bind, while non-profile groups only
exist as members of other groups. In our simple starter case, we have
a profile group named <tt class="docutils literal"><span class="pre">basic</span></tt>, and that is the group that our first
client bound to. Our first client is a SuSE machine, so it contains the
<tt class="docutils literal"><span class="pre">suse</span></tt> group. Of course, <tt class="docutils literal"><span class="pre">bcfg2-admin</span></tt> isn’t smart enough to fill
out the rest of your config, so the <tt class="docutils literal"><span class="pre">suse</span></tt> group further down is empty.</p>
<p>Let’s say the first thing we want to set up on our machine is the
message of the day. To do this, we simply need to create a Bundle and
add that Bundle to an appropriate group. In this simple example, we
start out by adding</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><Bundle</span> <span class="na">name=</span><span class="s">'motd'</span><span class="nt">/></span>
</pre></div>
</div>
<p>to the <tt class="docutils literal"><span class="pre">basic</span></tt> group.</p>
<p>Next, we create a motd.xml file in the Bundler directory:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><Bundle</span> <span class="na">name=</span><span class="s">'motd'</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/motd'</span> <span class="nt">/></span>
<span class="nt"></Bundle></span>
</pre></div>
</div>
<p>Now when we run the client, we get slightly different output:</p>
<div class="highlight-python"><pre>Loaded tool drivers:
Chkconfig POSIX YUMng
Incomplete information for entry Path:/etc/motd; cannot verify
Phase: initial
Correct entries: 0
Incorrect entries: 1
Total managed entries: 1
Unmanaged entries: 242
In dryrun mode: suppressing entry installation for:
Path:/etc/motd
Phase: final
Correct entries: 0
Incorrect entries: 1
Total managed entries: 1
Unmanaged entries: 242</pre>
</div>
<p>We now have an extra unmanaged entry, bringing our total number of
managed entries up to one. To manage it we need to copy <tt class="docutils literal"><span class="pre">/etc/motd</span></tt>
to <tt class="docutils literal"><span class="pre">/var/lib/bcfg2/Cfg/etc/motd/</span></tt>. Note the layout of that path: all
plain-text config files live in the Cfg directory. The directory
structure under that directory directly mimics your real filesystem
layout, making it easy to find and add new files. The last directory
is the name of the file itself, so in this case the full path to the
motd file would be <tt class="docutils literal"><span class="pre">/var/lib/bcfg2/Cfg/etc/motd/motd</span></tt>. Copy your
real <tt class="docutils literal"><span class="pre">/etc/motd</span></tt> file to that location, run the client again, and
you will find that we now have a correct entry:</p>
<div class="highlight-python"><pre>Loaded tool drivers:
Chkconfig POSIX PostInstall RPM
Phase: initial
Correct entries: 1
Incorrect entries: 0
Total managed entries: 1
Unmanaged entries: 242
Phase: final
Correct entries: 1
Incorrect entries: 0
Total managed entries: 1
Unmanaged entries: 242</pre>
</div>
<p>Done! Now we just have 242 (or more) entries to take care of!</p>
<p><a class="reference internal" href="../server/plugins/structures/bundler/index.html#server-plugins-structures-bundler-index"><em>Bundler</em></a> is a
relatively easy directory to populate. You can find many
samples of Bundles in the <a class="reference internal" href="../server/plugins/structures/bundler/index.html#server-plugins-structures-bundler-index-examples"><em>Bundler Example Repository</em></a>, many of which can
be used without editing.</p>
</div>
<div class="section" id="next-steps">
<span id="getting-started-index-next-steps"></span><h2>Next Steps<a class="headerlink" href="#next-steps" title="Permalink to this headline">¶</a></h2>
<p>Several other utilities can help from this point on:</p>
<p><a class="reference internal" href="../server/bcfg2-info.html#server-bcfg2-info"><em>bcfg2-info</em></a> is a utility that
instantiates a copy of the Bcfg2 server core (minus the networking code)
for examination. From this, you can directly query:</p>
<ul class="simple">
<li>Client Metadata</li>
<li>Which entries are provided by particular plugins</li>
<li>Client Configurations</li>
</ul>
<p>Run <tt class="docutils literal"><span class="pre">bcfg2-info</span></tt>, and type help and the prompt when it comes up.</p>
<p><tt class="docutils literal"><span class="pre">bcfg2-admin</span></tt> can perform a variety of repository maintenance
tasks. Run <tt class="docutils literal"><span class="pre">bcfg2-admin</span></tt> help for details.</p>
<p>Once you have the server setup, you may be interested in
<a class="reference internal" href="../appendix/guides/bootstrap.html#appendix-guides-bootstrap"><em>bootstrapping</em></a> additional clients.</p>
</div>
<div class="section" id="platform-specific-quickstart-notes">
<h2>Platform-specific Quickstart Notes<a class="headerlink" href="#platform-specific-quickstart-notes" title="Permalink to this headline">¶</a></h2>
<ul class="simple">
<li><a class="reference internal" href="../appendix/guides/centos.html#appendix-guides-centos"><em>Quickstart for CentOS</em></a></li>
<li><a class="reference internal" href="../appendix/guides/ubuntu.html#appendix-guides-ubuntu"><em>Ubuntu</em></a></li>
<li><a class="reference internal" href="macosx/notes.html#getting-started-macosx-notes"><em>Setting up Bcfg2 From Scratch</em></a></li>
</ul>
</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="#">Getting started</a><ul>
<li><a class="reference internal" href="#get-and-install-bcfg2-server">Get and Install Bcfg2 Server</a></li>
<li><a class="reference internal" href="#set-up-repository">Set up Repository</a></li>
<li><a class="reference internal" href="#populate-repository">Populate Repository</a></li>
<li><a class="reference internal" href="#next-steps">Next Steps</a></li>
<li><a class="reference internal" href="#platform-specific-quickstart-notes">Platform-specific Quickstart Notes</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="../installation/distributions.html"
title="previous chapter">Distribution-specific notes</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="../architecture/index.html"
title="next chapter">Detailed Bcfg2 Architecture</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/getting_started/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="../architecture/index.html" title="Detailed Bcfg2 Architecture"
>next</a> |</li>
<li class="right" >
<a href="../installation/distributions.html" title="Distribution-specific notes"
>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>
</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
>
370
