.. -*- mode: rst -*- .. _EPEL: http://fedoraproject.org/wiki/EPEL .. _appendix-guides-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 `_ 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 :ref:`server-plugins-generators-packages` plugin ---------------------------------------------------------- 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 centos-5.4 http://mrepo/centos5-x86_64/RPMS.os x86_64 centos-5.4 http://mrepo/centos5-x86_64/RPMS.updates x86_64 centos-5.4 http://mrepo/centos5-x86_64/RPMS.extras x86_64 Due to the :ref:`server-plugins-generators-packages-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 .. note:: The reason we are creating a release-specific group in this case is that the YUMSource above is specific to the 5.4 release of centos. That is, it should not apply to other releases (5.1, 5.3, etc). .. code-block:: xml .. note:: When editing your xml files by hand, it is useful to occasionally run `bcfg2-lint` 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,...,Probes [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 now ``tail -f /var/log/messages``, 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 You need to reference the bundle from your Metadata. The resulting profile group might look something like this .. code-block:: xml 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 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 `. 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 .. 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 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 You will also want to add an *important* attribute to these files so that they are installed on the client prior to any attempts to install the **gpg-pubkey** rpm packages. This is especially important during the bootstrapping phase and can be accomplished using an :ref:`server-info` file that looks like the following: .. code-block:: xml 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 ...and bind them in Rules .. code-block:: xml [root@centos ~]# cat /var/lib/bcfg2/Rules/services.xml 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 .. warning:: This basic bundle is created mainly for the purposes of getting you to a completely managed client. It is recommended that you create bundles for appropriate services due to the way bundle updates are managed. Please see :ref:`unsorted-writing_specification` for more details. Dynamic (web) reports ===================== See installation instructions at :ref:`reports-dynamic` Next Steps ========== :ref:`getting_started-index-next-steps`