Explanation of the DEB822 Source Format¶

The sources described in /etc/apt/sources.list.d/ on a Debian-based OS are designed to support any number of different active and inactive sources, as well as a large variety of source media and transport protocols. The files describe one or more sources each and contain multiline stanzas defining one or more sources per stanza, with the most preferred source listed first. Information about available packages and versions from each source is fetched using the apt update command, or with an equivalent command from a different frontend.

sources.list.d¶

APT source information is stored locally within the /etc/apt/sources.list.d directory. In this directory are one or more files describing one or more sources each. For Deb822-style Format sources, each file needs to have the .sources extension. The filenames may only contain letters, digits, underscore, hyphen, and period characters. Files with other characters in their filenames will cause APT to rint a notice that it has ignore that file (unless the file matches a pattern in the Dir::Ignore-Files-Silently configuration list, which will force APT to silently ignore the file.

One-Line-Style Format¶

In order to understand some of the decisions behind using the Deb822-style Format sources, it is helpful to understand the older One-Line-Style Format.

One-Line-Style Format sources occupy one line in a file ending in .list. The line begins with a type (i.e. deb or deb-src followed by options and arguments for this type. Individual entries cannot be continued onto multiple lines (hence the “one-line” portion of this format’s name). Empty lines in .list files are ignored, and a # character anywhere on the line signifies that the remainder of that line is a comment. Consequently an entry can be disabled by commenting out that entire line (prefixing it with a #). If options are provided, they are space-separated and all together are enclosed within square brackets ( [] ). Options allowing multiple values should separate each value with a comma ( , ) and each option name is separated from its values by an equals sign ( = ).

This is the traditional format and is supported by all current APT versions. It has the advantage of being relatively compact for single-sources and relatively easy for humans to parse.

Disadvantages¶

Problems with the One-Line-Style Format begin when parsing entries via machine. Traditional, optionless entries are relatively simple to parse, as each different portion of the entry is separated with a space. With options, however, this is no longer the case. The presence of options causes there to be no, 1, or multiple segments of configuration between the type declaration and the URI. Additionally, APT sources support a variety of URI schemas, with the capability for extensions to add additional schemas on certain configurations. Thus, supporting modern, optioned One-Line-Style Format source entries requires use of either regular expressions or multi-level parsing in order to adequately parse the entry. Further compounding this support is the fact that One-Line-Style Format entries can have one or more components, preventing parsing of sources backwards from the end towards the front.

Consider the following examples:

deb [] http://example.com.ubuntu disco main restricted multiverse universe
deb [ arch=amd64 ] http://example.com/ubuntu disco main nonfree
deb [lang=en_US] http://example.com/ubuntu disco main restricted universe multiverse
deb [ arch=amd64,armel lang=en_US,en_CA ] http://example.com/ubuntu disco main

Each of these entries are syntactically valid source entries, each cleanly splits into eight segments when splitting on spaces. Depending on which entry being parsed, the URI portion of the entry may be in index 2, 4, or 5 while options (where present) may be in index 1, 2, or 3. If we want to work backwards, then the URI is in either index -3, -4, or -6. The only segments guaranteed to be present at any given index is the type. The situation is even more complicated when considering that entries may have at a minimum 3 elements, and at a maximum 12 or more elements.

In addition to parsing difficulty, One-Line-Style Format entries may only specify a single suite and URI per entry, meaning that having two active mirrors for a given source requires doubling the number of entries configured. You must also create an extra set of duplicated entries for each suite you want to configure. This can make tracking down duplicated entries difficult for users and leads to longer-than-necessary configuration.

Deb822-style Format¶

This format addresses the file-length, duplication, and machine-parsability issues present in the One-Line-Style Format. Each source is configured in a single stanza of configuration, with lines explicitly describing their function for the source. They also allow for lists of values for most options, meaning that mirrors or multiple suites can be defined within a single source. A # character at the beginning of a line marks the entire line as a comment. Entries can again be disabled by commenting out each line within the stanza; however, as a convenience this format also brings an Enabled: field which, when set to no disables the entry as well. Removing this field or setting it to yes re-enables it. Options have the same format as every other field, thus a stanza may be parsed by checking the beginning of each line for a fixed substring, and if the line doesn’t match a known substring, it can be assumed the line is an option and the line can be ignored. Unknown options are ignored by all versions of APT. This has the unintentional side effect of adding extensibility to the source; by selecting a carefully namespaced field name, third-party applications and libraries can add their own fields to sources without causing breakage by APT. This can include comments, version information, and (as is the case with RepoLib, pretty, human-readable names.

From the sources.list(5) manual page:

This is a new format supported by apt itself since version 1.1. Previous versions ignore such files with a notice message as described earlier. It is intended to make this format gradually the default format, deprecating the previously described one-line-style format, as it is easier to create, extend and modify for humans and machines alike especially if a lot of sources and/or options are involved.

DEB822 Source Format Specifications¶

Following is a description of each field in the deb822 source format.

Enabled:¶

Enabled: (value: “yes” or “no”, required: No, default: “yes”): Tells APT whether the source is enabled or not. Disabled sources are not queried for package lists, effectively removing them from the system sources while still allowing reference or re-enabling at any time.

Types:¶

Types: (value: “deb” or “deb-src”, required: Yes): Defines which types of packages to look for from a given source; either binary: deb or source code: deb-src. The deb type references a typical two-level Debian archive providing packages containing pre-compiled binary data intended for execution on user machines. The deb-src type references a Debian distribution’s source code in the same form as the deb type. A deb-src line is required to fetch source pacakge indices.

URIs:¶

URIs: (value: string(s), required: Yes)

The URI must specify the base of the Debian distribution archive, from which APT finds the information it needs. There must be a URI component present in order for the source to be valid; multipls URIs can be configured simultaneously by adding a space-separated list of URIs.

A list of the current built-in URI Schemas supported by APT is available at the Debian sources.list manpage.

Suites:¶

Suites: (value: strings(s), required: Yes): The Suite can specify an exact path in relation to the URI(s) provided, in which case the Components: must be omitted and suite must end with a slash ( / ). Alternatively, it may take the form of a distribution version (e.g. a version codename like disco or artful ). If the suite does not specify a path, at least one deb822-field-component must be present.

Components:¶

Components: (value: string(s), required: see Suites:): Components specify different sections of one distribution version present in a Suite. If Suites: specifies an exact path, then no Components may be specified. Otherwise, a component must be present.

Options¶

Sources may specify a number of options. These options and their values will generally narrow a set of software to be available from the source or in some other way control what software is downloaded from it. An exhaustive list of options can be found at the Debian sources.list manpage.

RepoLib-Specific Deb822 Fields¶

RepoLib presently defines a single internal-use fields which it adds to deb822 sources that it modifies.

X-Repolib-Name:¶

X-Repolib-Name: (value: string, required: no, default: filename): This field defines a formatted name for the source which is suitable for inclusion within a graphical UI or other interface which presents source information to an end-user. As a RepoLib specific field, this is silently ignored by APT and other tools operating with deb822 sources and is only intended to be utilized by RepoLib itself.

Examples¶

The following specifies a binary and source-code source fetching from the primary Ubuntu archive with multiple suites for updates as well as several components:

Enabled: yes
Types: deb deb-src
URIs: http://archive.ubuntu.com/ubuntu
Suites: disco disco-updates disco-security disco-backports
Components: main universe multiverse restricted

This is a source for fetching Google’s Chrome browser, which specifies a CPU architecture option and a RepoLib Name:

X-Repolib-Name: Google Chrome
Enabled: yes
URIs: http://dl.google.com/linux/chrome/deb
Suites: stable
Components: main
Architectures: amd64

This specifies a source for downloading packages for System76’s Pop!_OS:

X-Repolib-Name: Pop!_OS PPA
Enabled: yes
Types: deb
URIs: http://ppa.launchpad.net/system76/pop/ubuntu
Suites: disco
Components: main

Following is a PPA source which has been disabled:

X-Repolib-Name: ZNC Stable
Enabled: no
Types: deb
URIs: http://ppa.launchpad.net/teward/znc/ubuntu
Suites: disco
Components: main