doc: Massive update

1 files changed, 565 insertions, 0 deletions

diff --git a/doc/appendix/guides/centos.txt b/doc/appendix/guides/centos.txt
new file mode 100644
index 000000000..91c1f268f
--- /dev/null
+++ b/doc/appendix/guides/centos.txt
@@ -0,0 +1,565 @@
+.. -*- mode: rst -*-
+
+.. _EPEL: http://fedoraproject.org/wiki/EPEL
+
+.. _guide-centos:
+
+=====================
+Quickstart for CentOS
+=====================
+
+This is a complete getting started guide for CentOS. With this document
+you should be able to install a Bcfg2 server and a Bcfg2 client.
+
+Install Bcfg2
+=============
+
+The fastest way to get Bcfg2 onto your system is to use Yum or
+your preferred package management tool. We'll be using the ones
+that are distributed through EPEL_, but depending on your aversion
+to risk you could download an RPM from other places as well.  See
+:ref:`getting_started-using_bcfg2-with-centos` for information about
+building Bcfg2 from source and making your own packages.
+
+Using EPEL
+----------
+
+Make sure EPEL_ is a valid repository on your server. The `instructions
+<http://fedoraproject.org/wiki/EPEL/FAQ#howtouse>`_ on how to do this
+basically say::
+
+    [root@centos ~]# rpm -Uvh http://download.fedora.redhat.com/pub/epel/5/x86_64/epel-release-5-4.noarch.rpm
+
+.. note::
+
+    You will have to adjust this command to match your architecture and
+    the current EPEL release.
+
+Install the bcfg2-server and bcfg2 RPMs::
+
+    [root@centos ~]# yum install bcfg2-server bcfg2
+
+Your system should now have the necessary software to use Bcfg2. The
+next step is to set up your Bcfg2 :term:`repository`.
+
+Initialize your repository
+==========================
+
+Now that you're done with the install, you need to initialize your
+repository and setup your ``/etc/bcfg2.conf``. ``bcfg2-admin init``
+is a tool which allows you to automate this::
+
+    [root@centos ~]# bcfg2-admin init
+    Store bcfg2 configuration in [/etc/bcfg2.conf]:
+    Location of bcfg2 repository [/var/lib/bcfg2]:
+    Input password used for communication verification (without echoing; leave blank for a random):
+    What is the server's hostname: [centos]
+    Input the server location [https://centos:6789]:
+    Input base Operating System for clients:
+    1: Redhat/Fedora/RHEL/RHAS/Centos
+    2: SUSE/SLES
+    3: Mandrake
+    4: Debian
+    5: Ubuntu
+    6: Gentoo
+    7: FreeBSD
+    : 1
+    Generating a 2048 bit RSA private key
+    .........................+++
+    ..................+++
+    writing new private key to '/etc/bcfg2.key'
+    -----
+    Signature ok
+    subject=/C=US=ST=Illinois/L=Argonne/CN=centos
+    Getting Private key
+    Repository created successfuly in /var/lib/bcfg2
+
+Change responses as necessary.
+
+Start the server
+================
+
+You are now ready to start your bcfg2 server for the first time::
+
+    [root@centos ~]# /sbin/service bcfg2-server start
+
+To verify that everything started ok, look for the running daemon and check the logs::
+
+    [root@centos ~]# /etc/init.d/service bcfg2-server status
+    [root@centos ~]# tail /var/log/messages
+    Mar 29 12:42:26 centos bcfg2-server[5093]: service available at https://centos:6789
+    Mar 29 12:42:26 centos bcfg2-server[5093]: serving bcfg2-server at https://centos:6789
+    Mar 29 12:42:26 centos bcfg2-server[5093]: serve_forever() [start]
+    Mar 29 12:42:41 centos bcfg2-server[5093]: Handled 16 events in 0.007s
+
+Run bcfg2 to be sure you are able to communicate with the server::
+
+    [root@centos ~]# bcfg2 -vqn
+    No ca is specified. Cannot authenticate the server with SSL.
+    No ca is specified. Cannot authenticate the server with SSL.
+    Loaded plugins: fastestmirror
+    Loading mirror speeds from cached hostfile
+    Excluding Packages in global exclude list
+    Finished
+    Loaded tool drivers:
+     Action       Chkconfig  POSIX        YUMng
+
+    Phase: initial
+    Correct entries:        0
+    Incorrect entries:      0
+    Total managed entries:  0
+    Unmanaged entries:      208
+
+
+    Phase: final
+    Correct entries:        0
+    Incorrect entries:      0
+    Total managed entries:  0
+    Unmanaged entries:      208
+
+    No ca is specified. Cannot authenticate the server with SSL.
+
+The ca message is just a warning, meaning that the client does not
+have sufficient information to verify that it is talking to the
+correct server. This can be fixed by distributing the ca certificate
+from the server to all clients. By default, this file is available in
+``/etc/bcfg2.crt`` on the server. Copy this file to the client (with a
+bundle) and add the ca option to ``bcfg2.conf`` pointing at the file,
+and the client will be able to verify it is talking to the correct server
+upon connection::
+
+    [root@centos ~]# cat /etc/bcfg2.conf
+
+
+    [communication]
+    protocol = xmlrpc/ssl
+    password = N41lMNeW
+    ca = /etc/bcfg2.crt
+
+    [components]
+    bcfg2 = https://centos:6789
+
+Now if you run the client, no more warning::
+
+    [root@centos ~]# bcfg2 -vqn
+    Loaded plugins: fastestmirror
+    Loading mirror speeds from cached hostfile
+    Excluding Packages in global exclude list
+    Finished
+    Loaded tool drivers:
+     Action       Chkconfig  POSIX        YUMng
+
+    Phase: initial
+    Correct entries:        0
+    Incorrect entries:      0
+    Total managed entries:  0
+    Unmanaged entries:      208
+
+
+    Phase: final
+    Correct entries:        0
+    Incorrect entries:      0
+    Total managed entries:  0
+    Unmanaged entries:      208
+
+Bring your first machine under Bcfg2 control
+============================================
+
+Now it is time to get your first machine's configuration into your
+Bcfg2 :term:`repository`. Let's start with the server itself.
+
+
+Setup the `Packages`_ plugin
+----------------------------
+
+.. _Packages: http://trac.mcs.anl.gov/projects/bcfg2/wiki/Plugins/Packages
+
+First, replace **Pkgmgr** with **Packages** in the plugins
+line of ``bcfg2.conf``.  Then create Packages layout (as per
+:ref:`packages-exampleusage`) in ``/var/lib/bcfg2``
+
+.. note:: I am using the RawURL syntax here since we are using `mrepo`_
+          to manage our yum mirrors.
+
+.. _mrepo: http://dag.wieers.com/home-made/mrepo/
+
+.. code-block:: xml
+
+    <Sources>
+            <!-- CentOS (5.4) sources -->
+            <YUMSource>
+                    <Group>centos5.4</Group>
+                    <RawURL>http://mrepo/centos5-x86_64/RPMS.os</RawURL>
+                    <Arch>x86_64</Arch>
+            </YUMSource>
+            <YUMSource>
+                    <Group>centos5.4</Group>
+                    <RawURL>http://mrepo/centos5-x86_64/RPMS.updates</RawURL>
+                    <Arch>x86_64</Arch>
+            </YUMSource>
+            <YUMSource>
+                    <Group>centos5.4</Group>
+                    <RawURL>http://mrepo/centos5-x86_64/RPMS.extras</RawURL>
+                    <Arch>x86_64</Arch>
+            </YUMSource>
+    </Sources>
+
+Due to the `Magic Groups`_, we need to modify our Metadata. Let's
+add a **centos5.4** group which inherits a **centos** group
+(this should replace the existing **redhat** group) present in
+``/var/lib/bcfg2/Metadata/groups.xml``. The resulting file should look
+something like this
+
+.. _Magic Groups: http://trac.mcs.anl.gov/projects/bcfg2/wiki/Plugins/Packages#MagicGroups
+
+.. code-block:: xml
+
+    <Groups version='3.0'>
+       <Group profile='true' public='true' default='true' name='basic'>
+          <Group name='centos5.4'/>
+       </Group>
+       <Group name='centos5.4'>
+          <Group name='centos'/>
+       </Group>
+       <Group name='ubuntu'/>
+       <Group name='debian'/>
+       <Group name='freebsd'/>
+       <Group name='gentoo'/>
+       <Group name='centos'/>
+       <Group name='suse'/>
+       <Group name='mandrake'/>
+       <Group name='solaris'/>
+    </Groups>
+
+.. note::
+    When editing your xml files by hand, it is useful to occasionally run
+    `bcfg2-repo-validate` to ensure that your xml validates properly.
+
+The final thing we need is for the client to have the proper
+arch group membership. For this, we will make use of the
+:ref:`unsorted-dynamic_groups` capabilities of the Probes plugin. Add
+Probes to your plugins line in ``bcfg2.conf`` and create the Probe.::
+
+    [root@centos ~]# grep plugins /etc/bcfg2.conf
+    plugins = Base,Bundler,Cfg,Metadata,Packages,Probes,Rules,SSHbase
+    [root@centos ~]# mkdir /var/lib/bcfg2/Probes
+    [root@centos ~]# cat /var/lib/bcfg2/Probes/groups
+    #!/bin/sh
+
+    echo "group:`uname -m`"
+
+Now we restart the bcfg2-server::
+
+    [root@centos ~]# /etc/init.d/bcfg2-server restart
+
+If you tail ``/var/log/syslog`` now, you will see the Packages plugin in
+action, updating the cache.
+
+Start managing packages
+-----------------------
+
+Add a base-packages bundle. Let's see what happens when we just populate
+it with the *yum* package.
+
+.. code-block:: xml
+
+    [root@centos ~]# cat /var/lib/bcfg2/Bundler/base-packages.xml
+    <Bundle name='base-packages'>
+            <Package name='yum'/>
+    </Bundle>
+
+You need to reference the bundle from your Metadata. The resulting
+profile group might look something like this
+
+.. code-block:: xml
+
+    <Group profile='true' public='true' default='true' name='basic'>
+       <Bundle name='base-packages'/>
+       <Group name='centos5.4'/>
+    </Group>
+
+Now if we run the client, we can see what this has done for us.::
+
+    [root@centos ~]# bcfg2 -vqn
+    Running probe groups
+    Probe groups has result:
+    x86_64
+    Loaded plugins: fastestmirror
+    Loading mirror speeds from cached hostfile
+    Excluding Packages in global exclude list
+    Finished
+    Loaded tool drivers:
+     Action       Chkconfig  POSIX        YUMng
+            Package pam failed verification.
+
+    Phase: initial
+    Correct entries:        94
+    Incorrect entries:      1
+    Total managed entries:  95
+    Unmanaged entries:      113
+
+    In dryrun mode: suppressing entry installation for:
+      Package:pam
+
+    Phase: final
+    Correct entries:        94
+    Incorrect entries:      1
+     Package:pam
+    Total managed entries:  95
+    Unmanaged entries:      113
+
+Interesting, our **pam** package failed verification. What does this
+mean? Let's have a look::
+
+    [root@centos ~]# rpm --verify pam
+    ....L...  c /etc/pam.d/system-auth
+
+Sigh, it looks like the default RPM install for pam fails to verify
+using its own verification process (trust me, it's not the only one). At
+any rate, I was able to get rid of this particular issue by removing the
+symlink and running ``yum reinstall pam``.
+
+As you can see, the Packages plugin has generated the dependencies
+required for the yum package automatically. The ultimate goal should
+be to move all the packages from the **Unmanaged** entries section to
+the **Managed** entries section. So, what exactly *are* those Unmanaged
+entries?::
+
+    [root@centos ~]# bcfg2 -veqn
+    Running probe groups
+    Probe groups has result:
+    x86_64
+    Loaded plugins: fastestmirror
+    Loading mirror speeds from cached hostfile
+    Excluding Packages in global exclude list
+    Finished
+    Loaded tool drivers:
+     Action       Chkconfig  POSIX        YUMng
+    Extra Package openssh-clients 4.3p2-36.el5_4.4.x86_64.
+    Extra Package libuser 0.54.7-2.1el5_4.1.x86_64.
+    ...
+
+    Phase: initial
+    Correct entries:        95
+    Incorrect entries:      0
+    Total managed entries:  95
+    Unmanaged entries:      113
+
+
+    Phase: final
+    Correct entries:        95
+    Incorrect entries:      0
+    Total managed entries:  95
+    Unmanaged entries:      113
+     Package:at
+     Package:avahi
+     Package:avahi-compat-libdns_sd
+     ...
+
+Now you can go through these and continue adding the packages you want
+to your Bundle. After a while, I ended up with a minimal bundle that
+looks like this
+
+.. code-block:: xml
+
+    <Bundle name='base-packages'>
+            <Package name='bcfg2-server'/>
+            <Package name='exim'/>
+            <Package name='grub'/>
+            <Package name='kernel'/>
+            <Package name='krb5-workstation'/>
+            <Package name='m2crypto'/>
+            <Package name='openssh-clients'/>
+            <Package name='openssh-server'/>
+            <Package name='prelink'/>
+            <Package name='redhat-lsb'/>
+            <Package name='rpm-build'/>
+            <Package name='rsync'/>
+            <Package name='sysklogd'/>
+            <Package name='vim-enhanced'/>
+            <Package name='yum'/>
+    </Bundle>
+
+Now when I run the client, you can see I have only one unmanaged
+package::
+
+    [root@centos ~]# bcfg2 -veqn
+    Running probe groups
+    Probe groups has result:
+    x86_64
+    Loaded plugins: fastestmirror
+    Loading mirror speeds from cached hostfile
+    Excluding Packages in global exclude list
+    Finished
+    Loaded tool drivers:
+     Action       Chkconfig  POSIX        YUMng
+    Extra Package gpg-pubkey e8562897-459f07a4.None.
+    Extra Package gpg-pubkey 217521f6-45e8a532.None.
+
+    Phase: initial
+    Correct entries:        187
+    Incorrect entries:      0
+    Total managed entries:  187
+    Unmanaged entries:      16
+
+
+    Phase: final
+    Correct entries:        187
+    Incorrect entries:      0
+    Total managed entries:  187
+    Unmanaged entries:      16
+     Package:gpg-pubkey
+     Service:atd
+     Service:avahi-daemon
+     Service:bcfg2-server
+     ...
+
+The gpg-pubkey packages are special in that they are not really
+packages. Currently, the way to manage them is using :ref:`BoundEntries
+<boundentries>`. So, after adding them, our Bundle now looks like this
+
+.. note:: This does not actually control the contents of the files,
+          you will need to do this part separately (see below).
+
+.. code-block:: xml
+
+    <Bundle name='base-packages'>
+            <BoundPackage name="gpg-pubkey" type="rpm">
+                            <Instance simplefile="/etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-5" version="e8562897" release="459f07a4"/>
+                            <Instance simplefile="/etc/pki/rpm-gpg/RPM-GPG-KEY-EPEL" version="217521f6" release="45e8a532"/>
+            </BoundPackage>
+            <Package name='bcfg2-server'/>
+            <Package name='exim'/>
+            <Package name='grub'/>
+            <Package name='kernel'/>
+            <Package name='krb5-workstation'/>
+            <Package name='m2crypto'/>
+            <Package name='openssh-clients'/>
+            <Package name='openssh-server'/>
+            <Package name='prelink'/>
+            <Package name='redhat-lsb'/>
+            <Package name='rpm-build'/>
+            <Package name='rsync'/>
+            <Package name='sysklogd'/>
+            <Package name='vim-enhanced'/>
+            <Package name='yum'/>
+    </Bundle>
+
+To actually push the gpg keys out via Bcfg2, you will need to manage the
+files as well. This can be done by adding Path entries for each of the
+gpg keys you want to manage
+
+.. code-block:: xml
+
+    <Bundle name='base-packages'>
+            <Path name='/etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-5'/>
+            <Path name='/etc/pki/rpm-gpg/RPM-GPG-KEY-EPEL'/>
+            <BoundPackage name="gpg-pubkey" type="rpm">
+                            <Instance simplefile="/etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-5" version="e8562897" release="459f07a4"/>
+                            <Instance simplefile="/etc/pki/rpm-gpg/RPM-GPG-KEY-EPEL" version="217521f6" release="45e8a532"/>
+            </BoundPackage>
+            <Package name='bcfg2-server'/>
+            <Package name='exim'/>
+            <Package name='grub'/>
+            <Package name='kernel'/>
+            <Package name='krb5-workstation'/>
+            <Package name='m2crypto'/>
+            <Package name='openssh-clients'/>
+            <Package name='openssh-server'/>
+            <Package name='prelink'/>
+            <Package name='redhat-lsb'/>
+            <Package name='rpm-build'/>
+            <Package name='rsync'/>
+            <Package name='sysklogd'/>
+            <Package name='vim-enhanced'/>
+            <Package name='yum'/>
+    </Bundle>
+
+Then add the files to Cfg::
+
+    mkdir -p Cfg/etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-5
+    cp /etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-5 !$/RPM-GPG-KEY-CentOS-5
+    mkdir -p Cfg/etc/pki/rpm-gpg/RPM-GPG-KEY-EPEL
+    cp /etc/pki/rpm-gpg/RPM-GPG-KEY-EPEL !$/RPM-GPG-KEY-EPEL
+
+Now, running the client shows only unmanaged Service entries. Woohoo!
+
+Manage services
+---------------
+
+Now let's clear up the unmanaged service entries by adding the following
+entries to our bundle.
+
+.. code-block:: xml
+
+    <!-- basic services -->
+    <Service name='atd'/>
+    <Service name='avahi-daemon'/>
+    <Service name='bcfg2-server'/>
+    <Service name='crond'/>
+    <Service name='cups'/>
+    <Service name='gpm'/>
+    <Service name='lvm2-monitor'/>
+    <Service name='mcstrans'/>
+    <Service name='messagebus'/>
+    <Service name='netfs'/>
+    <Service name='network'/>
+    <Service name='postfix'/>
+    <Service name='rawdevices'/>
+    <Service name='sshd'/>
+    <Service name='syslog'/>
+
+...and bind them in Rules
+
+.. code-block:: xml
+
+    [root@centos ~]# cat /var/lib/bcfg2/Rules/services.xml
+    <Rules priority='1'>
+            <!-- basic services -->
+            <Service type='chkconfig' status='on' name='atd'/>
+            <Service type='chkconfig' status='on' name='avahi-daemon'/>
+            <Service type='chkconfig' status='on' name='bcfg2-server'/>
+            <Service type='chkconfig' status='on' name='crond'/>
+            <Service type='chkconfig' status='on' name='cups'/>
+            <Service type='chkconfig' status='on' name='gpm'/>
+            <Service type='chkconfig' status='on' name='lvm2-monitor'/>
+            <Service type='chkconfig' status='on' name='mcstrans'/>
+            <Service type='chkconfig' status='on' name='messagebus'/>
+            <Service type='chkconfig' status='on' name='netfs'/>
+            <Service type='chkconfig' status='on' name='network'/>
+            <Service type='chkconfig' status='on' name='postfix'/>
+            <Service type='chkconfig' status='on' name='rawdevices'/>
+            <Service type='chkconfig' status='on' name='sshd'/>
+            <Service type='chkconfig' status='on' name='syslog'/>
+    </Rules>
+
+Now we run the client and see there are no more unmanaged entries! ::
+
+    [root@centos ~]# bcfg2 -veqn
+    Running probe groups
+    Probe groups has result:
+    x86_64
+    Loaded plugins: fastestmirror
+    Loading mirror speeds from cached hostfile
+    Excluding Packages in global exclude list
+    Finished
+    Loaded tool drivers:
+     Action       Chkconfig  POSIX        YUMng
+
+    Phase: initial
+    Correct entries:        205
+    Incorrect entries:      0
+    Total managed entries:  205
+    Unmanaged entries:      0
+
+
+    Phase: final
+    Correct entries:        205
+    Incorrect entries:      0
+    Total managed entries:  205
+    Unmanaged entries:      0
+
+Dynamic (web) reports
+=====================
+
+See installation instructions at :ref:`server-reports-install`