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).

Version

Origin

Suite

Codename

Label

Sam's comment

Debian stretch

9.4

Debian

stable

stretch

Debian

Debian stretch-updates

Debian

stable-updates

stretch-updates

Debian

Debian stretch-backports

Debian

stretch-backports

stretch-backports

Debian Backports

Debian stretch security

9

Debian

stable

stretch

Debian-Security

tel.red

1.0

TEL.RED LLC

testing

stretch

TEL.RED software repository

Ah, the evergreen 1.0 release! And the Suite is outdated, just drop it

Skype

. stable

stable

stable

. stable

Skype sure is . stable, isn't it!

ownCloud

obs://build.opensuse.org/isv:ownCloud:desktop/Debian_9.0

Debian_9.0

Debian_9.0

isv:ownCloud:desktop

This actually almost gets it right, even though it's a bit verbose, but for some reason invents its own nomenclature for stretch, and doesn't use Version

irods

xenial

xenial

Almost right, but provide Version and Origin and drop Suite (to be fair, Suite == Codename appears normal in the Ubuntu world

Docker

Docker

stretch

Docker CE

Not bad, but again stretch is a Codename, not a Suite...

grafana

1

packagecloud.io/grafana/stable

stretch

stretch

stable

Drop Version/suite. And provide a useful Label or drop it


CategoryTechnote

robots.org.uk: DebianReleaseFileFields (last edited 2018-03-27 10:14:49 by sam)

© Sam Morris <sam@robots.org.uk>.
Content may be distributed and modified providing this notice is preserved.