diff options
Diffstat (limited to 'doc/appendix/guides/centos.txt')
| -rw-r--r-- | doc/appendix/guides/centos.txt | 565 |
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` |