summaryrefslogtreecommitdiffstats
path: root/doc/appendix/guides/centos.txt
diff options
context:
space:
mode:
authorFabian Affolter <fabian@bernewireless.net>2010-11-09 00:15:43 +0100
committerFabian Affolter <fabian@bernewireless.net>2010-11-09 00:15:43 +0100
commit391406c85d86dc931f3fdb2483a14d0f1e7e6355 (patch)
tree97fe00f6a9dcf5d821139766b213418d57b5d31b /doc/appendix/guides/centos.txt
parent553c693618321fad2a88030b16d42d3253befaec (diff)
downloadbcfg2-391406c85d86dc931f3fdb2483a14d0f1e7e6355.tar.gz
bcfg2-391406c85d86dc931f3fdb2483a14d0f1e7e6355.tar.bz2
bcfg2-391406c85d86dc931f3fdb2483a14d0f1e7e6355.zip
doc: Massive update
Diffstat (limited to 'doc/appendix/guides/centos.txt')
-rw-r--r--doc/appendix/guides/centos.txt565
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`