Debian Release file fields

... and what they are actually used for!

The fields of a Release file are documented but there's not much information accessible to non-Debian experts that actually explains what these fields are used for and where they are displayed. This has resulted in a number of third-party package repositories containing overly generic or specific values, which are not actually useful for users of the repositories.

The following sections describe how these fields are used by different parts of the Debian packaging ecosystem, giving the reader an idea of what values it is helpful for them to provide in their Release files.

unattended-upgrades

By default, unattended-upgrades will automatically upgrade packages that are installed from sources that match the following fields:

Unattended-Upgrade::Origins-Pattern {
    "origin=Debian,codename=${distro_codename},label=Debian";
    "origin=Debian,codename=${distro_codename},label=Debian-Security";
}

Where ${distro_codename} is the current distro as output by lsb_release -c -s.

Pinning

Pinning allows the user to control which repository a package will be installed from, in the case that the package is available in multiple repositories. The current pinning configuration can be dumped by running apt-cache policy:

 500 http://tel.red/repos/debian stretch/non-free amd64 Packages
     release v=1.0,o=TEL.RED LLC,a=testing,n=stretch,l=TEL.RED software repository,c=non-free,b=amd64
     origin tel.red
 500 https://repo.skype.com/deb stable/main amd64 Packages
     release o=. stable,a=stable,n=stable,l=. stable,c=main,b=amd64
     origin repo.skype.com
 570 http://deb.debian.org/debian buster/main amd64 Packages
     release o=Debian,a=testing,n=buster,l=Debian,c=main,b=amd64
     origin deb.debian.org

The mapping between the short labels used when pinning and the fields in the Release file are described in apt_preferences(5).

Display

When running apt-get --dry-run upgrade, one can see which packages would be upgraded, as well as which repository they come from:

# apt-get -s upgrade | grep ^Inst
Inst base-files [9.9+deb9u3] (9.9+deb9u4 Debian:9.4/stable [amd64])
Inst bsdutils [1:2.29.2-1] (1:2.29.2-1+deb9u1 Debian-Security:9/stable [amd64])
Inst grafana [5.0.0] (5.0.1 stable:1/stretch [amd64])

The format is defined in apt-pkg/pkgcache.cc as Label/Version:Archive, assuming all those fields are present in the Release file.

Field Examples

Some repositories have chosen interesting values for these fields.

It's most useful to provide a useful Origin (who you are) and Label (what's in your "release", by which I mean, what set of packages are contained by the compoments referenced in your Release file). e.g., Microsoft and Skype. By way of example, Debian uses Debian-Security for the separate security update repository, even though the Origin remains Debian.

It probably makes sense to specify the Version (without point release) and Codename of the Debian release that your builds are targetting. That way, a user can usefully pin all packages that target a particular Debian release, be they from Debian or another origin. The same does not apply for Suite, because the provided value will become stale as the specified release's state changes from testing to stable to oldstable over time (Ubuntu went their own way here, and specify the codename for Suite, so doing that is fine if you're targetting Ubuntu).

CategoryTechnote