.. -*- mode: rst -*-

.. _appendix-guides-gentoo:

======
Gentoo
======

This document tries to lay out anything Gentoo-specific that you need
to know in order to use Bcfg2. Mostly that has to do with getting it
to cooperate with the various pieces of Portage. Services, all things
POSIX, and just about anything else that Bcfg2 does will work the same
on Gentoo as on any other distribution.  Bcfg2 is new on Gentoo; please
let the list know if you find errors or omissions.

Installing Bcfg2
================

Early in July 2008, Bcfg2 was added to the Gentoo portage tree.

If you don't use portage to install Bcfg2, you'll want to make sure you
have all the prerequisites installed first. For a server, you'll need:

* ``dev-libs/libgamin[python]``
* ``dev-python/lxml``

Clients will need at least:

* ``app-portage/gentoolkit``

Portage installs from source
============================

.. versionadded:: 1.3.0

By default the client will run with the ``--gitbinpkgonly`` option. If
you want your client to install packages from source (rather than
having a binary build host as seen below), you can set the following in
``/etc/bcfg2.conf``.::

    [Portage]
    binpkgonly = false

Package Repository
==================

.. note: This is only necessary for using binary packages.

You’ll need (to make) at least one archive of binary packages. The
Portage driver calls ``emerge`` with the ``--getbinpkgonly`` option. See
:manpage:`make.conf(5)` and :manpage:`emerge(1)` manpages, specifically
the :envvar:`PORTAGE_BINHOST` environment variable.

Time Saver: quickpkg
--------------------

If you have a standing Gentoo machine that you want to preserve or
propagate, you can generate a complete package archive based on the
present state of the system by using the quickpkg utility. For example:

.. code-block:: sh

    for pkg in `equery -q l` ; do quickpkg "=$pkg" ; done

...will leave you with a complete archive of all the packages on your
system in ``/usr/portage/packages/All``, which you can then move to your
ftp server.

Cataloging Packages In Your Repository
--------------------------------------

Once you have a set of packages, you will need to create a catalog for
them in ``/var/lib/bcfg2/Pkgmgr``. Here's a template:

.. code-block:: xml

    <PackageList uri='' type='portage' priority=''>
      <Group name=''>
        <Package name='' version=''/>
      </Group>
    </PackageList>

...and a partially filled-out example, for our local Gentoo/VMware build:

.. code-block:: xml

    <PackageList uri='ftp://filthy.uchicago.edu/200701-vmware/' type='portage' priority='0'>
      <Group name='gentoo-200701-vmware'>
        <Package name='app-admin/bcfg2' version='0.9.1_pre1'/>
        [...]
        <Package name='x11-wm/twm' version='1.0.1'/>
      </Group>
    </PackageList>

The `<Group>` name (in our example, "gentoo-200701-vmware") should
be included by any host which will draw its packages from this list. Our
collection of packages for this class of machines is at the listed URI,
and we only have one collection of packages for this batch of machines so
in our case the `priority` doesn’t really matter, we've set it to `0`.

Notice that package name fields are in `CAT/TITLE` format.

Here is a hack which will generate a list of Package lines from
a system's database of installed packages, especially useful in
conjunction with the ``quickpkg`` example above:

.. code-block:: sh

    #!/bin/bash
    for pkg in `equery -q l` ; do
       title=`echo $pkg | sed -e 's/\(.*\)-\([0-9].*\)/\1/'`
       version=`echo $pkg | sed -e 's/\(.*\)-\([0-9].*\)/\2/'`
       echo "    <Package name='${title}' version='${version}'/>"
    done

Configuring Client Machines
===========================

Set up ``/etc/bcfg2.conf`` the way you would for any other Bcfg2 client.

In ``make.conf``, set *PORTAGE_BINHOST* to point to the URI of
your package repository. You may want to create versions of
``make.conf`` for each package repository you maintain, with
appropriate *PORTAGE_BINHOST* URI's in each, and associated with
that package archive's group under ``Cfg`` -- for example, we have
``Cfg/etc/make.conf/make.conf.G99_gentoo-200701-vmware``. If a client
host switches groups, and the new group needs a different set of packages,
everything should just fall into place.

Pitfalls
========

/boot
-----

Gentoo as well as some other distros recommend leaving ``/boot`` unmounted
during normal runtime. This can lead to trouble during verification and
package installation, for example when ``/boot/grub/grub.conf`` turns
up missing. The simplest way around this might just be to ensure that
``/boot`` is mounted whenever you run Bcfg2, possibly wrapping Bcfg2
in a script for the purpose. I've also thought about adding *Action*
clauses to bundles for grub and our kernel packages, which would mount
``/boot`` before the bundle installs and unmount it afterward, but this
doesn't get around the problem of those packages flunking verification.