From 391406c85d86dc931f3fdb2483a14d0f1e7e6355 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Tue, 9 Nov 2010 00:15:43 +0100 Subject: doc: Massive update --- doc/appendix/guides/fedora.txt | 477 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 477 insertions(+) create mode 100644 doc/appendix/guides/fedora.txt (limited to 'doc/appendix/guides/fedora.txt') diff --git a/doc/appendix/guides/fedora.txt b/doc/appendix/guides/fedora.txt new file mode 100644 index 000000000..f3a5a3929 --- /dev/null +++ b/doc/appendix/guides/fedora.txt @@ -0,0 +1,477 @@ +.. -*- mode: rst -*- + +.. This guide is based on the Centos guide. + +.. _guide-fedora: + +====== +Fedora +====== + +This guide is work in progess. + + +This is a complete getting started guide for Fedora. With this +document you should be able to install a Bcfg2 server, a Bcfg2 client, +and change the ``/etc/motd`` file on the client. + +Install Bcfg2 From RPM +====================== + +The fastest way to get Bcfg2 onto your system is to use ``yum`` +or PackageKit. `` +um`` will pull all dependencies of Bcfg2 +automatically in. :: + + $ su -c '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: + +.. code-block:: sh + + # bcfg2-admin init + Store bcfg2 configuration in [/etc/bcfg2.conf]: + Location of bcfg2 repository [/var/lib/bcfg2]: + Directory /var/lib/bcfg2 exists. Overwrite? [y/N]:y + Input password used for communication verification (without echoing; leave blank for a random): + What is the server's hostname: [config01.local.net] + Input the server location [https://config01.local.net: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 1024 bit RSA private key + .......................................................++++++ + .....++++++ + writing new private key to '/etc/bcfg2.key' + ----- + Signature ok + subject=/C=US/ST=Illinois/L=Argonne/CN=config01.local.net + 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:: + + $ su -c '/etc/init.d/bcfg2-server start' + Starting Configuration Management Server: bcfg2-server [ OK ] + +To verify that everything started ok, look for the running daemon and +check the logs: + +.. code-block:: sh + + $ su -c 'tail /var/log/messages' + May 16 14:14:57 config01 bcfg2-server[2746]: service available at https://config01.local.net:6789 + May 16 14:14:57 config01 bcfg2-server[2746]: serving bcfg2-server at https://config01.local.net:6789 + May 16 14:14:57 config01 bcfg2-server[2746]: serve_forever() [start] + May 16 14:14:57 config01 bcfg2-server[2746]: Handled 16 events in 0.009s + + +Run ``bcfg2`` to be sure you are able to communicate with the server: + +.. code-block:: sh + + $ su -c 'bcfg2 -vqne' + + /usr/lib/python2.6/site-packages/Bcfg2/Client/Tools/rpmtools.py:23: DeprecationWarning: the md5 module is deprecated; use hashlib instead + import md5 + Loaded plugins: presto, refresh-packagekit + Loaded tool drivers: + Action Chkconfig POSIX YUMng + Extra Package imsettings-libs 0.108.0-2.fc13.i686. + Extra Package PackageKit-device-rebind 0.6.4-1.fc13.i686. + ... + Extra Package newt-python 0.52.11-2.fc13.i686. + Extra Package pulseaudio-gdm-hooks 0.9.21-6.fc13.i686. + + Phase: initial + Correct entries: 0 + Incorrect entries: 0 + Total managed entries: 0 + Unmanaged entries: 1314 + + + Phase: final + Correct entries: 0 + Incorrect entries: 0 + Total managed entries: 0 + Unmanaged entries: 1314 + Package:ConsoleKit Package:jasper-libs Package:pcsc-lite-libs + Package:ConsoleKit-libs Package:java-1.5.0-gcj Package:perf + ... + Package:iw Package:pcre Service:sshd + Package:jack-audio-connection-kit Package:pcsc-lite Service:udev-post + +The ``bcfg2.conf`` file contains only standard plugins so far. + +.. code-block:: sh + + $ su -c 'cat /etc/bcfg2.conf' + + [server] + repository = /var/lib/bcfg2 + plugins = Base,Bundler,Cfg,Metadata,Pkgmgr,Rules,SSHbase + + [statistics] + sendmailpath = /usr/lib/sendmail + database_engine = sqlite3 + # 'postgresql', 'mysql', 'mysql_old', 'sqlite3' or 'ado_mssql'. + database_name = + # Or path to database file if using sqlite3. + #/etc/brpt.sqlite is default path if left empty + database_user = + # Not used with sqlite3. + database_password = + # Not used with sqlite3. + database_host = + # Not used with sqlite3. + database_port = + # Set to empty string for default. Not used with sqlite3. + web_debug = True + + [communication] + protocol = xmlrpc/ssl + password = test1234 + certificate = /etc/bcfg2.crt + key = /etc/bcfg2.key + ca = /etc/bcfg2.crt + + [components] + bcfg2 = https://config01.local.net:6789 + + +Add the machines to Bcfg2 +------------------------- + +``bcfg2-admin`` can be used to add a machine to Bcfg2 easily. You +need to know the Fully Qualified Domain Name (FQDN) of ever system +you want to control through Bcfg2. :: + + bcfg2-admin client add + +Bring your first machine under Bcfg2 control +-------------------------------------------- + +Now it is time to get the first machine's configuration into the +Bcfg2 repository. The server will be the first machine. It's +already in the ``Metadata/client.xml``. + + +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/` directory in +``/var/lib/bcfg2`` :: + + $ su -c 'mkdir /var/lib/bcfg2/Packages' + +Create a ``config.xml`` file for the packages in +``/var/lib/bcfg2/Packages`` with the following content. Choose a +mirror near your location according the `Mirror list`_ . + +.. _Mirror list: http://mirrors.fedoraproject.org/publiclist/ + +.. code-block:: xml + + + + fedora-13 + ftp://fedora.tu-chemnitz.de/pub/linux/fedora/linux/releases/ + 13 + Fedora + i386 + x86_64 + + + +.. _Magic Groups: http://trac.mcs.anl.gov/projects/bcfg2/wiki/Plugins/Packages#MagicGroups + +Due to the `Magic Groups`_, we need to modify our Metadata. Let's +add a **fedora13** group which inherits a **fedora** group +(this should replace the existing **redhat** group) present in +``/var/lib/bcfg2/Metadata/groups.xml``. The resulting file should look +something like this + +.. code-block:: xml + + + + + + + + + + + + + + + + + +.. note:: + When editing your xml files by hand, it is useful to occasionally + run ``bcfg2-repo-validate`` to ensure that your xml validates + properly. + +Add a probe ++++++++++++ + +The next step for the client will be to have the proper +arch group membership. For this, we will make use of the +:ref:`server-plugins-grouping-dynamic_groups` capabilities of +the Probes plugin. Add **Probes** to your plugins line in ``bcfg2.conf`` +and create the Probe: + +.. code-block:: sh + + $ su -c 'mkdir /var/lib/bcfg2/Probes' + $ su -c 'cat /var/lib/bcfg2/Probes/groups' + #!/bin/sh + + echo "group:`uname -m`" + +Now a restart of ``bcfg2-server`` is needed:: + + $ su -c '/etc/init.d/bcfg2-server restart' + +To test the Probe just run ``bcfg2 -vqn``. + +.. code-block:: xml + + $ su -c 'bcfg2 -vqn' + Running probe group + Probe group has result: + group:i686 + ... + +Start managing packages ++++++++++++++++++++++++ + +Add a base-packages bundle. Let's see what happens when we just populate +it with the *yum* package. Create the ``base-packages.xml`` in your +``Bundler/`` directory with a entry for ``yum``. + +.. code-block:: xml + + $ cat /var/lib/bcfg2/Bundler/base-packages.xml + + + + +You need to reference the bundle from your ``group.xml``. 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.:: + + output + +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?:: + + output + +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:: + + outout + +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 + + + + + + + + + + + + + + + + + + + + + + + +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 + +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! :: + + $ su -c 'bcfg2 -veqn' + + +Adding Plugins +++++++++++++++ + +Git +--- + +.. _Git tutorial: http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html + +Adding the :ref:`server-plugins-version-git` plugins can preserve +versioning information. The first step is to add *Git* to your +plugin line:: + + plugins = Base,Bundler,Cfg,...,Git + +For tracking the configuration files in the ``/var/lib/bcfg2`` +directory a git repository need to be established:: + + git init + +For more detail about the setup of git please refer to a `git tutorial`_. +The first commit can be the empty or the allready populated directory:: + + git add . && git commit -a + +While running ``bcfg2-info`` the following line will show up:: + + Initialized git plugin with git directory = /var/lib/bcfg2/.git + + + + + -- cgit v1.2.3-1-g7c22