diff options
Diffstat (limited to 'doc/getting_started/index.txt')
| -rw-r--r-- | doc/getting_started/index.txt | 268 |
1 files changed, 228 insertions, 40 deletions
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 <Doc/Architecture>` -* `ServerSideOverview` -* `UpgradeTesting` -* `Troubleshooting` -* `Bcfg2 Server Plugins <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 <Plugins/Probes>` -* `AgentMode` -* `DynamicGroups` -* `Client Tool Drivers <ClientTools>` -* `Developing for Bcfg2 <DevelopingForBcfg2>` -* `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 + + <Clients version="3.0"> + <Client profile="basic" pingable="Y" pingtime="0" name="bcfg-server.example.com"/> + </Clients> + +The ``clients.xml`` file is just a series of ``<Client />`` 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 + + <Groups version='3.0'> + <Group profile='true' public='false' name='basic'> + <Group name='suse'/> + </Group> + <Group name='ubuntu' toolset='debian'/> + <Group name='debian' toolset='debian'/> + <Group name='redhat' toolset='rh'/> + <Group name='suse' toolset='rh'/> + <Group name='mandrake' toolset='rh'/> + <Group name='solaris' toolset='solaris'/> + </Groups> + +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 + + <Bundle name='motd'/> + +to the ``basic`` group. + +Next, we create a motd.xml file in the Bundler directory: + +.. code-block:: xml + + <Bundle name='motd' version='2.0'> + <Path name='/etc/motd' /> + </Bundle> + +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 <GroupNames>` -* `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 <ManualPages>` +``bcfg2-admin`` can perform a variety of repository maintenance +tasks. Run ``bcfg2-admin`` help for details. |