NOTE: Staring July 2004, this is still a draft, needs to be expanded a lot. Additions and corrections welcome.
Author: Elmar Heeb (heeb@phys.ethz.ch) and (elmar@heebs.ch)

Backport HOWTO for Debian

1. Introduction

1.1 Why do backports

It has become quite common now to use backported packages with the Debian GNU/Linux distribution. However, for a production environment it make sense to ask why one wants to install a backported package. This also leads to some criteria on when to use a backport and also which packages we can trust.

The main reason why there is such a backport activity at all is the relatively slow release mechanism of Debian. While there are many valid arguments for quicker releases, the current scheme has its reasons. The most important factor is to have a maintainable environment where all packages are properly interconnected by dependencies, provides, conflicts, etc. This environment is being maintained properly for all security relevant issues and other than that will not undergo feature changes that require new configurations. It is important to realize that "stability" as far as Debian releases are concerned are a matter of keeping the version number stable. The version available in "testing" or "unstable" may in fact be more "stable" in terms of program crashes.

By using a backport you will loose the advantage of having a stable version. I.e., you will need to backport security fixes for some chosen version of a package or face the burden of updating the package configuration in a production environment. How much configuration changes you can tolerate determines whether you should run a pure "stable" release, a stable release with a few backported packages, or a setup upgraded to the "testing" or "unstable" release.

When using backports the rule-of-thumb should be to use as few as possible to fulfill you requirements and to get your work done.

1.2 Building your own backports or using other peoples' packages

1.2.1 Self Made

The obvious advantage with self made backports is that you get to choose which packages and which versions are backported. For some packages it is your only choice as there may not be a backported version available. If you are successful at backporting you may consider contributing your package. Of course, for your self made backports you assume some (at least a moral) responsibility for security fixes. With a contributed backport this responsibility may be higher, but you may also get more help from the community.

1.2.2 Publicly Available Backports

The advantage to publicly available backports is of course that somebody else did the work. However, you will want to make sure that a package is properly supported. If you can find a high quality backport of a package it may be better to use it instead of making your own.

At the time of this writing some of the most serious effort for backported packages is being done at www.backports.org Some other backports you can find through www.apt-get.org.

1.3 Alternatives to Backports

1.3.1 Use "unstable" or "testing"

[FIXME: depending on your needs, the unstable or testing version of Debian may be acceptable and easier to use than using backports]

1.3.2 Pinning

[FIXME: with pinning you can mix-and-match your own collection of packages. Interesting concept, although with its own problems.]

2. The Build Environment

The Debian project already has elaborate build environments. However, these are meant to work within a particular Release. You would be compiling woody packages within a pure woody system, or sarge packages within a sarge system.

When doing backports, we want to make sure that we control the packages used. We want to do backports with the minimal dependencies on packages outside the stable distribution. Therefore we create our own build environment, albeit with much the same ideas used in the automatic build environments of the Debian project.

2.1 using chroot

You can use a prepared build environment in which case you should download the following three files:

If you want to build your own or just now how this is done you can use the following receipe:

Use debootstrap to generate a pristine Debian environment:

# mkdir woody-buildenv
# debootstrap woody woody-buildenv http://debian.ethz.ch/mirror/debian
I: Retrieving http://debian.ethz.ch/mirror/debian/dists/woody/Release
I: Validating /root/backport/woody-buildenv/var/lib/apt/lists/debootstrap.invalid_dists_woody_Release
[...]
I: Base system installed successfully.

Prepare the new Debian environment to allow chroot, i.e., mount the proc filesystem and provide appropriate resolv.conf, hosts, and .bashrc files:

# mount -t proc none woody-buildenv/proc
# rm woody-buildenv/etc/resolv.conf
# cp /etc/resolv.conf woody-buildenv/etc/resolv.conf
# cp /etc/hosts woody-buildenv/etc/hosts
# cat > woody-buildenv/root/.bashrc << EOF
export PS1='backports:\w\\$ '
umask 022
EOF

Enter the Debian environment with chroot and finish the setup. For a build environment we want the simplest mail-transport-agent possible (it will not be used but has to be there because it belongs in a Debian base system). We also want debconf to be non-interactive for the build scripts we are running in this environment. Furthermore we want to have packages installed with their default settings so that they work in a generic Debian environment. We also want to remove all optional packages. For a build environment we need the package build-essential.

# chroot woody-buildenv
backports:/# cd
backports:~# base-config
Answer sensibly, tend towards default answers but do not run tasksel or dselect. We want to have as pure a woody system as possible. Therefore do not include non-free packages either. If you need some for build dependencies you should load them later for the respective backport only.
With exim you can choose option (5). We will replace it below.

backports:~# apt-get -y install nullmailer
backports:~# cat > debconf-set << EOF
#!/bin/sh
. /usr/share/debconf/confmodule
db_set debconf/priority critical
db_set debconf/frontend noninteractive
EOF

backports:~# chmod +x debconf-set
backports:~# ./debconf-set
backports:~# rm debconf-set
backports:~# apt-get install build-essential
backports:~# apt-get clean
backports:~# exit
# umount woody-buildenv/proc

Clean up a bit and put all in a tar file:

# rm woody-buildenv/root/.bash_history
# tar czf woody-buildenv.tar.gz woody-buildenv
# rm -r woody-buildenv

If you haven't done so above you should download the do-woody-buildenv and the Build scripts:

# wget http://debian.ethz.ch/pub/debian-backports/utils/do-woody-buildenv
# chmod +x do-woody-buildenv
# wget http://debian.ethz.ch/pub/debian-backports/utils/Build
# chmod +x Build

You can now start a new clean woody build environment with the command

# ./do-woody-buildenv
backports:/# cd
backports:~#

If you give do-woody-buildenv a name of a package as an argument it will set up a new directory with a build script template for a new backport as explained below.

2.2 backporting a package

2.2.1 choosing the package version

FIXME: make sure you use sources with an upstream version not higher than what is available in testing.

2.2.1 resolving dependencies

FIXME: 4 kinds of dependencies:

3. Publish package in debian tree

FIXME: upload to your repository and make sure you can install the package with all its dependencies.

use a repository tree where you can choose packages individually so that you do not have to install all backported packages.

Structure:
.
|-- dists
|   |-- stable -> woody
|   `-- woody
|       `-- backports
|           |-- package-a
|           |   |-- binary-all
|           |   |   ...
|           |   |-- binary-i386
|           |   |   ...
|           |   `-- source
|           |       ...
|           `-- package-b
|               |-- binary-all
|               |   ...
|               |-- binary-i386
|               |   ...
|               `-- source
|                   ...
`-- pool
    `-- main
        |-- a
	|   ...
	|-- p
	|   |-- package-a
	|   `-- package-b
	|   ...
	`-- z

Elmar Heeb
Last modified: Fri Nov 12 18:00:58 CET 2004