path: root/doc/appendix/guides/fedora.txt

.. -*- 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.

Prerequisites
=============

To setup a configuration management system based on Bcfg2 only a few
prerequisites need to be fullfilled.

* A server machine that can host the Bcfg2
* Internet access for the installation process
* A working network with DNS


Install Bcfg2 From RPM
======================

The fastest way to get Bcfg2 onto your system is to use ``yum``
or PackageKit. ``yum`` 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: Red Hat/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 = SSHbase,Cfg,Pkgmgr,Rules,Metadata,Base,Bundler

    [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.
    #<repository>/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 <FQDN machine>

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

	<Sources>
	    <YUMSource>
	    <Group>fedora-13</Group>
	    <URL>ftp://fedora.tu-chemnitz.de/pub/linux/fedora/linux/releases/</URL>
	    <Version>13</Version>
	    <Component>Fedora</Component>
	    <Arch>i386</Arch>
	    <Arch>x86_64</Arch>
	    </YUMSource>
	</Sources>

.. _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

   <Groups version='3.0'>
       <Group profile='true' public='true' default='true' name='basic'>
          <Group name='fedora13'/>
       </Group>
       <Group name='fedora13'/>
          <Group name='fedora'/>
       <Group name='ubuntu'/>
       <Group name='debian'/>
       <Group name='freebsd'/>
       <Group name='gentoo'/>
       <Group name='fedora'/>
       <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.

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:`unsorted-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
    <Bundle name='base-packages'>
            <Package name='yum'/>
    </Bundle>

You need to reference the bundle from your ``group.xml``. 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='fedora13'/>
    </Group>

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

    <Bundle name='base-packages'>

    </Bundle>

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 <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! ::

    $ 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