.. -*- mode: rst -*-

.. _quickstart-ubuntu:

=====================
Quickstart for Ubuntu
=====================

.. note::

    This particular how to was done on lucid, but should apply to any
    other `stable`__ version of Ubuntu.

__ ubuntu-releases_
.. _ubuntu-releases: https://wiki.ubuntu.com/Releases

Install Bcfg2
=============

We first need to install the server. For this example, we will use the
bcfg2 server package from the bcfg2 `PPA`_ (note that there is also a
version available in the ubuntu archives, but it is not as up to date).

.. _PPA: https://launchpad.net/~bcfg2/+archive/ppa

Add the Ubuntu PPA listing to your APT sources
----------------------------------------------

See http://trac.mcs.anl.gov/projects/bcfg2/wiki/PrecompiledPackages#UbuntuLucid

Install bcfg2-server
--------------------
::

    aptitude install bcfg2-server

Remove the default configuration preseeded by the ubuntu package::

    root@lucid:~# rm -rf /etc/bcfg2* /var/lib/bcfg2

Initialize your repository
==========================

Now that you're done with the install, you need to intialize your
repository and setup your bcfg2.conf. bcfg2-admin init is a tool which
allows you to automate this process.::

    root@lucid:~# 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: [lucid]
    Input the server location [https://lucid: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
    : 5
    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=lucid
    Getting Private key
    Repository created successfuly in /var/lib/bcfg2


Of course, change responses as necessary.

Start the server
================

You are now ready to start your bcfg2 server for the first time.::

    root@lucid:~# /etc/init.d/bcfg2-server start
    root@lucid:~# tail /var/log/syslog
    Dec 17 22:07:02 lucid bcfg2-server[17523]: serving bcfg2-server at https://lucid:6789
    Dec 17 22:07:02 lucid bcfg2-server[17523]: serve_forever() [start]
    Dec 17 22:07:02 lucid bcfg2-server[17523]: Processed 16 fam events in 0.502 seconds. 0 coalesced

Run bcfg2 to be sure you are able to communicate with the server::

    root@lucid:~# bcfg2 -vqn
    Loaded tool drivers:
     APT      Action   DebInit  POSIX

    Phase: initial
    Correct entries:        0
    Incorrect entries:      0
    Total managed entries:  0
    Unmanaged entries:      382


    Phase: final
    Correct entries:        0
    Incorrect entries:      0
    Total managed entries:  0
    Unmanaged entries:      382

Bring your first machine under Bcfg2 control
============================================

Now it is time to get your first machine's configuration into your Bcfg2
repository. Let's start with the server itself.

Setup the `Packages`_ plugin
----------------------------

.. _Packages: http://trac.mcs.anl.gov/projects/bcfg2/wiki/Plugins/Packages

Replace Pkgmgr with Packages in the plugins line of ``bcfg2.conf``::

    root@lucid:~# cat /etc/bcfg2.conf
    [server]
    repository = /var/lib/bcfg2
    plugins = Base,Bundler,Cfg,Metadata,Packages,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.
    #<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 = secret
    certificate = /etc/bcfg2.crt
    key = /etc/bcfg2.key
    ca = /etc/bcfg2.crt

    [components]
    bcfg2 = https://lucid:6789

Create Packages layout (as per :ref:`packages-exampleusage`) in
``/var/lib/bcfg2``

.. code-block:: xml

    root@lucid:~# mkdir /var/lib/bcfg2/Packages
    root@lucid:~# cat /var/lib/bcfg2/Packages/config.xml
    <Sources>
      <APTSource>
        <Group>ubuntu-lucid</Group>
        <URL>http://us.archive.ubuntu.com/ubuntu</URL>
        <Version>lucid</Version>
        <Component>main</Component>
        <Component>multiverse</Component>
        <Component>restricted</Component>
        <Component>universe</Component>
        <Arch>amd64</Arch>
        <Arch>i386</Arch>
      </APTSource>
    </Sources>

Due to the `Magic Groups`_, we need to modify our Metadata. Let's add
an **ubuntu-lucid** group which inherits the **ubuntu** group already
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='ubuntu-lucid'/>
       </Group>
       <Group name='ubuntu-lucid'>
          <Group name='ubuntu'/>
       </Group>
       <Group name='ubuntu'/>
       <Group name='debian'/>
       <Group name='freebsd'/>
       <Group name='gentoo'/>
       <Group name='redhat'/>
       <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 last 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.

.. code-block:: sh

    root@lucid:~# grep plugins /etc/bcfg2.conf
    plugins = Base,Bundler,Cfg,Metadata,Packages,Probes,Rules,SSHbase
    root@lucid:~# mkdir /var/lib/bcfg2/Probes
    root@lucid:~# cat /var/lib/bcfg2/Probes/groups
    #!/bin/sh

    ARCH=`uname -m`
    case "$ARCH" in
        "x86_64")
            echo "group:amd64"
        ;;
        "i686")
            echo "group:i386"
        ;;
    esac

Now we restart the bcfg2-server::

    root@lucid:~# /etc/init.d/bcfg2-server restart
    Stopping Configuration Management Server:  * bcfg2-server
    Starting Configuration Management Server:  * bcfg2-server
    root@lucid:~# tail /var/log/syslog
    Dec 17 22:36:47 lucid bcfg2-server[17937]: Packages: File read failed; falling back to file download
    Dec 17 22:36:47 lucid bcfg2-server[17937]: Packages: Updating http://us.archive.ubuntu.com/ubuntu//dists/lucid/main/binary-amd64/Packages.gz
    Dec 17 22:36:54 lucid bcfg2-server[17937]: Packages: Updating http://us.archive.ubuntu.com/ubuntu//dists/lucid/multiverse/binary-amd64/Packages.gz
    Dec 17 22:36:55 lucid bcfg2-server[17937]: Packages: Updating http://us.archive.ubuntu.com/ubuntu//dists/lucid/restricted/binary-amd64/Packages.gz
    Dec 17 22:36:56 lucid bcfg2-server[17937]: Packages: Updating http://us.archive.ubuntu.com/ubuntu//dists/lucid/universe/binary-amd64/Packages.gz
    Dec 17 22:37:27 lucid bcfg2-server[17937]: Failed to read file probed.xml
    Dec 17 22:37:27 lucid bcfg2-server[17937]: Loading experimental plugin(s): Packages
    Dec 17 22:37:27 lucid bcfg2-server[17937]: NOTE: Interfaces subject to change
    Dec 17 22:37:27 lucid bcfg2-server[17937]: service available at https://lucid:6789
    Dec 17 22:37:27 lucid bcfg2-server[17937]: serving bcfg2-server at https://lucid:6789
    Dec 17 22:37:27 lucid bcfg2-server[17937]: serve_forever() [start]
    Dec 17 22:37:28 lucid bcfg2-server[17937]: Processed 17 fam events in 0.502 seconds. 0 coalesced

Start managing packages
-----------------------

Add a base-packages bundle. Let's see what happens when we just populate
it with the ubuntu-standard package.

.. code-block:: xml

    root@lucid:~# cat /var/lib/bcfg2/Bundler/base-packages.xml
    <Bundle name='base-packages'>
            <Package name='ubuntu-standard'/>
    </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='ubuntu-lucid'/>
    </Group>

Now if we run the client in debug mode (-d), we can see what this has
done for us.::

    root@lucid:~# bcfg2 -vqdn
    Running probe groups
    Probe groups has result:
    amd64
    Loaded tool drivers:
     APT      Action   DebInit  POSIX
    The following packages are specified in bcfg2:
     ubuntu-standard
    The following packages are prereqs added by Packages:
     adduser             debconf             hdparm              libdevmapper1.02.1  libk5crypto3        libparted1.8-12     libxml2             passwd              upstart
     apt                 debianutils         info                libdns53            libkeyutils1        libpci3             logrotate           pciutils            usbutils
     aptitude            dmidecode           install-info        libelf1             libkrb5-3           libpopt0            lsb-base            perl-base           wget
     at                  dnsutils            iptables            libept0             libkrb5support0     libreadline5        lshw                popularity-contest  zlib1g
     base-files          dosfstools          libacl1             libgcc1             liblwres50          libreadline6        lsof                psmisc
     base-passwd         dpkg                libattr1            libgdbm3            libmagic1           libselinux1         ltrace              readline-common
     bsdmainutils        ed                  libbind9-50         libgeoip1           libmpfr1ldbl        libsigc++-2.0-0c2a  man-db              rsync
     bsdutils            file                libc-bin            libgmp3c2           libncurses5         libssl0.9.8         memtest86+          sed
     cpio                findutils           libc6               libgssapi-krb5-2    libncursesw5        libstdc++6          mime-support        sensible-utils
     cpp                 ftp                 libcap2             libisc50            libpam-modules      libusb-0.1-4        ncurses-bin         strace
     cpp-4.4             gcc-4.4-base        libcomerr2          libisccc50          libpam-runtime      libuuid1            netbase             time
     cron                groff-base          libcwidget3         libisccfg50         libpam0g            libxapian15         parted              tzdata

    Phase: initial
    Correct entries:        101
    Incorrect entries:      0
    Total managed entries:  101
    Unmanaged entries:      281


    Phase: final
    Correct entries:        101
    Incorrect entries:      0
    Total managed entries:  101
    Unmanaged entries:      281

As you can see, the Packages plugin has generated the dependencies
required for the ubuntu-standard package for us 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@lucid:~# bcfg2 -vqen
    Running probe groups
    Probe groups has result:
    amd64
    Loaded tool drivers:
     APT      Action   DebInit  POSIX

    Phase: initial
    Correct entries:        101
    Incorrect entries:      0
    Total managed entries:  101
    Unmanaged entries:      281


    Phase: final
    Correct entries:        101
    Incorrect entries:      0
    Total managed entries:  101
    Unmanaged entries:      281
     Package:apparmor
     Package:apparmor-utils
     Package:apport
     ...

Now you can go through these and continue adding the packages you want to
your Bundle. Note that ``aptitude why`` is useful when trying to figure
out the reason for a package being installed. Also, deborphan is helpful
for removing leftover dependencies which are no longer needed. After a
while, I ended up with a minimal bundle that looks like this

.. code-block:: xml

    <Bundle name='base-packages'>
            <Package name='bash-completion'/>
            <Package name='bcfg2-server'/>
            <Package name='debconf-i18n'/>
            <Package name='deborphan'/>
            <Package name='diffutils'/>
            <Package name='e2fsprogs'/>
            <Package name='fam'/>
            <Package name='grep'/>
            <Package name='grub-pc'/>
            <Package name='gzip'/>
            <Package name='hostname'/>
            <Package name='krb5-config'/>
            <Package name='krb5-user'/>
            <Package name='language-pack-en-base'/>
            <Package name='linux-generic'/>
            <Package name='linux-headers-generic'/>
            <Package name='login'/>
            <Package name='manpages'/>
            <Package name='mlocate'/>
            <Package name='ncurses-base'/>
            <Package name='openssh-server'/>
            <Package name='python-fam'/>
            <Package name='tar'/>
            <Package name='ubuntu-minimal'/>
            <Package name='ubuntu-standard'/>
            <Package name='vim'/>
            <Package name='vim-runtime'/>

            <!-- PreDepends -->
            <Package name='dash'/>
            <Package name='initscripts'/>
            <Package name='libdbus-1-3'/>
            <Package name='libnih-dbus1'/>
            <Package name='lzma'/>
            <Package name='mountall'/>
            <Package name='sysvinit-utils'/>
            <Package name='sysv-rc'/>

            <!-- vim dependencies -->
            <Package name='libgpm2'/>
            <Package name='libpython2.6'/>
    </Bundle>

As you can see below, I no longer have any unmanaged packages. ::

    root@lucid:~# bcfg2 -vqen
    Running probe groups
    Probe groups has result:
    amd64
    Loaded tool drivers:
     APT      Action   DebInit  POSIX

    Phase: initial
    Correct entries:        247
    Incorrect entries:      0
    Total managed entries:  247
    Unmanaged entries:      10


    Phase: final
    Correct entries:        247
    Incorrect entries:      0
    Total managed entries:  247
    Unmanaged entries:      10
     Service:bcfg2         Service:fam           Service:killprocs     Service:rc.local      Service:single
     Service:bcfg2-server  Service:grub-common   Service:ondemand      Service:rsync         Service:ssh

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='bcfg2'/>
    <Service name='bcfg2-server'/>
    <Service name='fam'/>
    <Service name='grub-common'/>
    <Service name='killprocs'/>
    <Service name='ondemand'/>
    <Service name='rc.local'/>
    <Service name='rsync'/>
    <Service name='single'/>
    <Service name='ssh'/>


...and bind them in Rules

.. code-block:: xml

    root@lucid:~# cat /var/lib/bcfg2/Rules/services.xml
    <Rules priority='1'>
            <!-- basic services -->
            <Service type='deb' status='on' name='bcfg2'/>
            <Service type='deb' status='on' name='bcfg2-server'/>
            <Service type='deb' status='on' name='fam'/>
            <Service type='deb' status='on' name='grub-common'/>
            <Service type='deb' status='on' name='killprocs'/>
            <Service type='deb' status='on' name='ondemand'/>
            <Service type='deb' status='on' name='rc.local'/>
            <Service type='deb' status='on' name='rsync'/>
            <Service type='deb' status='on' name='single'/>
            <Service type='deb' status='on' name='ssh'/>
    </Rules>

Now we run the client and see there are no more unmanaged entries! ::

    root@lucid:~# bcfg2 -vqn
    Running probe groups
    Probe groups has result:
    amd64
    Loaded tool drivers:
     APT      Action   DebInit  POSIX

    Phase: initial
    Correct entries:        257
    Incorrect entries:      0
    Total managed entries:  257
    Unmanaged entries:      0

    All entries correct.

    Phase: final
    Correct entries:        257
    Incorrect entries:      0
    Total managed entries:  257
    Unmanaged entries:      0

    All entries correct.

Dynamic (web) reports
=====================

See installation instructions at :ref:`server-reports-install`