How to setup britney

This document describes how to install, configure and run britney in your infrastructure.

Installing britney

At the moment, the preferred way to install britney is to clone the source repo and run britney directly from the git checkout.

Configuring britney

This is a very brief intro to the steps required to setup a Britney instance.

  • Copy britney.conf.template and edit it to suit your purpose

    • If you want Britney to bootstrap your target suite, you probably want to add all architectures to NEW_ARCHES and BREAK_ARCHES for a few runs

  • Create the following files (they can be empty):

    • $STATE_DIR/age-policy-dates

    • $STATE_DIR/age-policy-urgencies

    • $STATE_DIR/rc-bugs-unstable

    • $STATE_DIR/rc-bugs-testing

    • $STATE_DIR/piuparts-summary-testing.json

    • $STATE_DIR/piuparts-summary-unstable.json

  • Run ./britney.py -c $BRITNEY_CONF -v [--dry-run] to test the run

  • Setup a cron-/batch-job that:

    • (Optionally) Updates the rc-bugs files

    • (Optionally) Updates the $STATE_DIR/age-policy-urgencies

    • (Optionally) Updates the piuparts summary files

    • Runs Britney

    • Consume the results from Britney (See Using the results from Britney for more information)

hints - Configuring who can provide which hints

Britney reads all hints from a set of hints files. These files must be placed in the directory denoted by the HINTSDIR configuration. This is complimented with the HINTS_<NAME> configurations that defines a “hint file” and the related hint permissions for it.

For each HINTS_<NAME> configuration, britney will attempt to read <HINTSDIR>/<name>. Note that it lowercases <NAME> when looking for the file.

Configuration example:

HINTSDIR = /etc/britney2/hints
HINTS_ANNA = ALL
HINTS_JOHN = STANDARD
HINTS_FREEZE = block block-all block-udeb
HINTS_AUTO-REMOVALS = remove

In the above example, we have defined 4 hints files named anna, john, freeze and auto-removals. These must be placed in /etc/britney2/hints and be readable by britney. Furthermore, they must be writable by (only) the people that are allowed to use the particular hints file (apply chown, chmod and setfacl as necessary).

The values on the right hand side of the = decides which hints are permitted in the files. With the above definitions:

  • The file anna may use any known hint (including potentially dangerous ones like force and force-hint)

  • The file john may use most of the known hints. The set called STANDARD includes a lot of hints for overriding most policies when it can be done without (additional) side-effects. However, it excludes force and force-hint as they can cause unintentional results.

  • The file freeze can use any of the hints block, block-all and block-udeb.

  • The file auto-removals can only use the hint called remove.

There are no fixed rules for how to use hints files. Though usually, each person with permissions to give hints to britney will have their own hint file along with write permissions for that file. It can also make sense to create hint files for “roles”. Like in the above example there are two human hinters (anna and john) plus two non-human hinters (freeze and auto-removals).

Please see Hints for which hints are available and what they can do.

Using the results from Britney

Britney optionally generates a number of files that may be useful for further processing.

  • HEIDI_OUTPUT can be used with dak control-suite. Example:

    cut -d" " -f1-3 < ${HEIDI_OUTPUT} | dak control-suite --set ${TARGET_SUITE} [--britney]

  • HEIDI_DELTA_OUTPUT is a variant of HEIDI_OUTPUT that represent the result as a delta rather than a full selection.

  • EXCUSES_YAML_OUTPUT provides a machine-readable output about which packages comply with the active policies and which does not.