From 391406c85d86dc931f3fdb2483a14d0f1e7e6355 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Tue, 9 Nov 2010 00:15:43 +0100 Subject: doc: Massive update --- doc/getting_started/index.txt | 268 +++++++++++++++++++++++++++++++++++------- 1 file changed, 228 insertions(+), 40 deletions(-) (limited to 'doc/getting_started/index.txt') diff --git a/doc/getting_started/index.txt b/doc/getting_started/index.txt index 2c05c5238..786c70290 100644 --- a/doc/getting_started/index.txt +++ b/doc/getting_started/index.txt @@ -2,57 +2,245 @@ .. _getting_started-index: -=========== -Using Bcfg2 -=========== +=============== +Getting started +=============== -These are many of the resources available to help new users get started. +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 :ref:`mailinglist` +or to drop in on our :ref:`ircchannel`. -* For the impatient there is the :ref:`quickstart-index` page. -* :ref:`help-index` has information when you are troubleshooting or need to ask a question. -* If you find anything wrong or missing please :ref:`report-a-bug` to let us know. +Get and Install Bcfg2 Server +============================ -.. toctree:: - :maxdepth: 2 +We recommend running the server on a Linux machine for ease of +deployment due to the availability of packages for the dependencies. - using-bcfg2-info - using-bcfg2-with-centos +First, you need to download and install Bcfg2. The section +:ref:`installation-index` 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). -Must Reads -========== +.. _Bcfg2 download page: http://trac.mcs.anl.gov/projects/bcfg2/wiki/Download +.. _Install page: http://trac.mcs.anl.gov/projects/bcfg2/wiki/Install + +Set up Repository +================= + +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, :: + + bcfg2-admin init -* `Documentation` -* `WritingSpecification` -* `Bcfg2 Architecture ` -* `ServerSideOverview` -* `UpgradeTesting` -* `Troubleshooting` -* `Bcfg2 Server Plugins ` +You will be presented with a series of questions that will build a +Bcfg2 configuration file in ``/etc/bcfg2.conf``, set up a skeleton +repository (in ``/var/lib/bcfg2`` by default), help you create ssl +certificates, and do any other similar tasks needed to get you +started. + +Once this process is done, you can start the Bcfg2 server:: + + /etc/init.d/bcfg2-server start + +You can try it out by running the Bcfg2 client on the same machine, +acting like it is your first client. + +.. note:: + + 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 changes 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. + +And now for the command:: + + bcfg2 -q -v -n -Misc/Others -=========== +That can be translated as "bcfg2 quick verbose no-op". The output +should be something similar to:: -* `Probes ` -* `AgentMode` -* `DynamicGroups` -* `Client Tool Drivers ` -* `Developing for Bcfg2 ` -* `Howtos` + Loaded tool drivers: + Chkconfig POSIX PostInstall RPM -Reporting -========= + 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 + +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 at the moment) that +still aren't managed. Your goal now is to migrate each of those plus +any it can't see up to the "Correct entries" line. + +Populate Repository +=================== + +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. + +After the above steps, you should have a toplevel repository structure +that looks like:: + + bcfg-server:~ # ls /var/lib/bcfg2 + Bundler/ Cfg/ Metadata/ Pkgmgr/ Rules/ SSHbase/ etc/ + +The place to start is the Metadata directory, which contains two +files: ``clients.xml`` and ``groups.xml``. Your current +``clients.xml`` will look pretty close to: + +.. code-block:: xml + + + + + +The ``clients.xml`` file is just a series of ```` 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 +``basic`` profile, is pingable, has a pingtime of ``0``, and has the +name ``bcfg-server.example.com``. 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 ``groups.xml`` file. + +Our simple ``groups.xml`` file looks like: + +.. code-block:: xml + + + + + + + + + + + + + +There are two types of groups in Bcfg: profile groups +(``profile='true'``) and non-profile groups +(``profile='false'``). 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 ``basic``, and that is the group that our first client bound +to. Our first client is a SuSE machine, so it contains the ``suse`` +group. Of course, ``bcfg2-admin`` isn't smart enough to fill out the +rest of your config, so the ``suse`` group further down is empty. + +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 + +.. code-block:: xml + + + +to the ``basic`` group. + +Next, we create a motd.xml file in the Bundler directory: + +.. code-block:: xml + + + + + +Now when we run the client, we get slightly different output:: + + Loaded tool drivers: + Chkconfig POSIX PostInstall RPM + 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 + +We now have an extra unmanaged entry, bringing our total number of +managed entries up to one. To manage it we need to copy ``/etc/motd`` +to ``/var/lib/bcfg2/Cfg/etc/motd/``. 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 ``/var/lib/bcfg2/Cfg/etc/motd/motd``. Copy your +real ``/etc/motd`` file to that location, run the client again, and +you will find that we now have a correct entry:: + + 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 + +Done! Now we just have 242 (or more) entries to take care of! + +:ref:`server-plugins-structures-bundler-index` is a relatively easy +directory to populate. You can find many samples of Bundles in the +`Bundle Repository`_, many of which can be used without editing. + +.. _Bundle Repository: http://trac.mcs.anl.gov/projects/bcfg2/wiki/Plugins/Bundler/examples + +Next Steps +========== -* :ref:`server-reports-index` +Several other utilities can help from this point on: -Examples -======== +``bcfg2-info`` is a utility that instantiates a copy of the Bcfg2 server +core (minus the networking code) for examination. From this, you can +directly query: -* `Demo Repository ` -* `Plugins/Bundler/examples` -* `Plugins/Probes/examples` -* `Plugins/TGenshi/examples` +* Client Metadata +* Which entries are provided by particular plugins +* Client Configurations -Man Pages -========= +Run ``bcfg2-info``, and type help and the prompt when it comes up. -* `Manual Pages ` +``bcfg2-admin`` can perform a variety of repository maintenance +tasks. Run ``bcfg2-admin`` help for details. -- cgit v1.2.3-1-g7c22