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

New in version 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.:

binpkgonly = false

Package Repository

You’ll need (to make) at least one archive of binary packages. The Portage driver calls emerge with the --getbinpkgonly option. See make.conf(5) and emerge(1) manpages, specifically the 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:

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:

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

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

<PackageList uri='' 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'/>

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:

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}'/>"

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.



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.