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 ++++++++++++++++++++---- doc/getting_started/using-bcfg2-info.txt | 132 ------------ doc/getting_started/using-bcfg2-with-centos.txt | 79 ------- 3 files changed, 228 insertions(+), 251 deletions(-) delete mode 100644 doc/getting_started/using-bcfg2-info.txt delete mode 100644 doc/getting_started/using-bcfg2-with-centos.txt (limited to 'doc/getting_started') 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. diff --git a/doc/getting_started/using-bcfg2-info.txt b/doc/getting_started/using-bcfg2-info.txt deleted file mode 100644 index 1fab0ea07..000000000 --- a/doc/getting_started/using-bcfg2-info.txt +++ /dev/null @@ -1,132 +0,0 @@ -.. -*- mode: rst -*- - -.. _getting_started-using_bcfg2_info: - -================ -Using bcfg2-info -================ - -*bcfg2-info* is a tool for introspecting server functions. It is -useful for understanding how the server is interpreting your -repository. It consists of the same logic executed by the server to -process the repository and produce configuration specifications, just -without all of the network communication code. Think of *bcfg2-info* -as *bcfg2-server* on a stick. It is a useful location to do testing -and staging of new configuration rules, prior to deployment. This is -particularly useful when developing templates, or developing Bcfg2 -plugins. - -Getting Started -=============== - -First, fire up the bcfg2-info interpreter. - -.. code-block:: none - - [0:464] bcfg2-info - Loading experimental plugin(s): Packages - NOTE: Interfaces subject to change - Handled 8 events in 0.006s - Handled 4 events in 0.035s - Welcome to bcfg2-info - Type "help" for more information - > - -At this point, the server core has been loaded up, all plugins have -been loaded, and the *bcfg2-info* has both read the initial state of -the Bcfg2 repository, as well as begun monitoring it for changes. Like -*bcfg2-server*, *bcfg2-info* monitors the repository for changes, -however, unlike *bcfg2-server*, it does not process change events -automatically. File modification events can be processed by explicitly -calling the **update** command. This will process the events, -displaying the number of events processed and the amount of time taken -by this processing. If no events are available, no message will be -displayed. For example, after a change to a file in the repository: - -.. code-block:: none - - >update - Handled 1 events in 0.001s - > update - > - -This explicit update process allows you to control the update process, -as well as see the precise changes caused by repository -modifications. - -*bcfg2-info* has several builtin commands that display the state of -various internal server core state. These are most useful for -examining the state of client metadata, either for a single client, or -for clients overall. - -**clients** - displays a list of clients, along with their profile groups -**groups** - displays a list of groups, the inheritance hierarchy, profile - status, and category name, if there is one. -**showclient** - displays full metadata information for a client, including - profile group, group memberships, bundle list, and any connector - data, like Probe values or Property info. - -Debugging Configuration Rules -============================= - -In addition to the commands listed above for viewing client metadata, -there are also commands which can shed light on the configuration -generation process. Recall that configuration generation occurs in -three major steps: - -1) Resolve client metadata -2) Build list of entries for the configuration -3) Bind host-specific version of each entry - -Step *1* can be viewed with the commands presented in the previous -section. The latter two steps can be examined using the following -commands. - -**showentries** - displays a list of entries (optionally filtered by type) that - appear in a client's configuration specification - -**buildfile** - Perform the entry binding process on a single entry, displaying - its results. This command is very useful when developing - configuration file templates. - -**build** - Build the full configuration specification and write it to a - file. - -**mappings** - displays the entries handled by the plugins loaded by the server - core. This command is useful when the server reports a bind - failure for an entry. - -Debugging and Developing Bcfg2 -============================== - -*bcfg2-info* loads a full Bcfg2 server core, so it provides the ideal -environment for developing and debugging Bcfg2. Because it is hard to -automate this sort of process, we have only implemented two commands -in *bcfg2-info* to aid in the process. - -**profile** - The profile command produces python profiling information for - other *bcfg2-info* commands. This can be used to track - performance problems in configuration generation. - -**debug** - The debug command exits the *bcfg2-info* interpreter loop and drops - to a python interpreter prompt. The Bcfg2 server core is available - in this namespace as "self". Full documentation for the server core - is out of scope for this document. This capability is most useful - to call into plugin methods, often with setup calls or the enabling - of diagnostics. - - It is possible to return to the *bcfg2-info* command loop by - exiting the python interpreter with ^D. - - There is built-in support for IPython in *bcfg2-info*. If IPython - is installed, dropping into debug mode in *bcfg2-info* will use - the IPython interpreter by default. diff --git a/doc/getting_started/using-bcfg2-with-centos.txt b/doc/getting_started/using-bcfg2-with-centos.txt deleted file mode 100644 index 93875d4c5..000000000 --- a/doc/getting_started/using-bcfg2-with-centos.txt +++ /dev/null @@ -1,79 +0,0 @@ -.. -*- mode: rst -*- - -.. _EPEL: http://fedoraproject.org/wiki/EPEL -.. _RPMForge: https://rpmrepo.org/RPMforge - -.. _getting_started-using_bcfg2-with-centos: - -======================= -Using Bcfg2 With CentOS -======================= - -This section covers specific topics for using Bcfg2 with CentOS. Most -likely the tips on this page also apply to other members of the Red Hat -family of Linux operating systems. - -From Source -+++++++++++ - -Install Prerequisities -###################### - -While you can go about building all these things from source, this -how to will try and meet the dependencies using packages from EPEL_ -or RPMforge_. The *el5* package should be compatible with CentOS 5.x. - -EPEL_:: - - [root@centos ~]# rpm -Uvh http://download.fedora.redhat.com/pub/epel/5/i386/epel-release-5-3.noarch.rpm - -RPMforge_:: - - [root@centos ~]# rpm -Uvh http://dag.wieers.com/rpm/packages/rpmforge-release/rpmforge-release-0.3.6-1.el5.rf.x86_64.rpm - -.. note:: - - Be careful with `mixing package repositories - `_. - -Now you can install the rest of the prerequisites:: - - [root@centos ~]# yum install python-genshi python-cheetah python-lxml - -Build Packages from source -########################## - -* After installing git, clone the master branch:: - - [root@centos redhat]# git clone git://git.mcs.anl.gov/bcfg2.git - -* Install the ``fedora-packager`` package :: - - [root@centos ~]# yum install fedora-packager - -* A directory structure for the RPM build process has to be established. :: - - [you@centos ~]$ rpmdev-setuptree - -* Change to the *redhat* directory of the checked out Bcfg2 source:: - - [you@centos ~]$ cd bcfg2/redhat/ - -* In the particular directory is a Makefile which will do the job of building the RPM packages. You can do this as root, but it's not recommanded:: - - [you@centos redhat]$ make - -* Now the new RPM package can be installed. Please adjust the path to your RPM package:: - - [root@centos ~]# rpm -ihv /home/YOU/rpmbuild/RPMS/noarch/bcfg2-server-1.0.0-0.2r5835.noarch.rpm - -Install Packages from Package repository -######################################## - -To install the bcfg2-server and bcfg2 from a package repository, just -use Yum to do it:: - - [root@centos ~]# yum install bcfg2-server bcfg2 - -.. toctree:: - :hidden: -- cgit v1.2.3-1-g7c22