diff options
Diffstat (limited to 'doc/quickstart/centos.txt')
| -rw-r--r-- | doc/quickstart/centos.txt | 567 |
1 files changed, 0 insertions, 567 deletions
diff --git a/doc/quickstart/centos.txt b/doc/quickstart/centos.txt deleted file mode 100644 index 4a702683e..000000000 --- a/doc/quickstart/centos.txt +++ /dev/null @@ -1,567 +0,0 @@ -.. -*- mode: rst -*- - -.. _EPEL: http://fedoraproject.org/wiki/EPEL - -.. _quickstart-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="yum" version="foo"> - <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> - -.. note:: version="foo" is just a dummy attribute for the gpg-pubkey Package - -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` |