doc: Massive update

1 files changed, 177 insertions, 0 deletions

diff --git a/doc/appendix/guides/gentoo.txt b/doc/appendix/guides/gentoo.txt
new file mode 100644
index 000000000..023e6ac24
--- /dev/null
+++ b/doc/appendix/guides/gentoo.txt
@@ -0,0 +1,177 @@
+.. -*- mode: rst -*-
+
+.. _guide-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.  So far
+it's only keyworded for ~x86, but we hope to see it soon in the amd64 and
+x64-solaris ports.  If you're using Gentoo on some other architecture, it
+should still work provided that you have a reasonably up to date Python;
+try adding `app-admin/bcfg2 ~*` to your `/etc/portage/package.keywords`
+file.
+
+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:
+
+* ``app-admin/gamin`` or ``app-admin/fam``
+* ``dev-python/lxml``
+
+Clients will need at least:
+
+* ``app-portage/gentoolkit``
+
+Package Repository
+==================
+
+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 *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
+========
+
+Package Verification Issues
+---------------------------
+
+As of this writing (2007/01/31), we’re aware of a number of packages
+marked stable in the Gentoo x86 tree which, for one reason or another,
+consistently fail to verify cleanly under `equery check`. In some cases
+(pam, openldap), files which don’t (ever) exist on the system are
+nonetheless recorded in the package database; in some (python, Bcfg2,
+ahem), whole classes of files (.pyc and .pyo files) consistently fail
+their md5sum checks; and in others, the problem appears to be a
+discrepancy in the way that symlinks are created vs. the way they’re
+recorded in the database. For example, in the OpenSSH package,
+/usr/bin/slogin is a symlink to ./ssh, but equery expects it to point to
+an unadorned ssh. An analogous situation exists with their manpages,
+leading to noise like this::
+
+    # equery check openssh
+    [ Checking net-misc/openssh-4.5_p1 ]
+    !!! /etc/ssh/sshd_config has incorrect md5sum
+    !!! /usr/bin/slogin does not point to ssh
+    !!! /usr/share/man/man1/slogin.1.gz does not point to ssh.1.gz
+    !!! /etc/ssh/ssh_config has incorrect md5sum
+     * 62 out of 66 files good
+
+We can ignore the lines for ``ssh_config`` and ``sshd_config``; those will
+be caught by Bcfg2 as registered config files and handled appropriately.
+
+Because Bcfg2 relies on the client system’s native package reporting
+tool to judge the state of installed packages, complaints like these
+about trivial or intractable verification failures can trigger unnecessary
+bundle reinstalls when the Bcfg2 client runs. Bcfg2 will catch on after a
+pass or two that the situation isn’t getting any better with repeated
+package installs, stop trying, and list those packages as “bad” in
+the client system’s statistics.
+
+Aside from filing bugs with the Gentoo package maintainers, your narrator
+has been unable to come up with a good approach to this. Maybe write a
+series of ``Rules`` definitions according to what the package database
+thinks it should find, and/or stage copies of affected files under
+``Cfg``, and associate those rules and files with the affected package in
+a bundle? Annoying but possibly necessary if you want your stats file
+to look good.
+
+/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.