Debian Repository Format

This document is a work in progress that documents the structure of the official Debian repository and the format that is officially understood by clients. Its purpose is to define how a Debian repository should be structured, and how clients should interpret this.

Notice: This document still misses a license. A license is currently negotiated with all persons who have contributed to this document up to revision 49 for past and future revisions.

Overview

Debian package archives are primarily used to store and retrieve packages automatically.

Most if not all package managers use libapt for package retrieval from external media and the internet.

The sources.list man page specifies this package source format:

   deb uri distribution [component1] [component2] [...]

and gives an example:

   deb http://ftp.debian.org/debian squeeze main contrib non-free

Here deb specifies that this is source for binary packages, deb-src is for source packages.

An archive can have either source packages or binary packages or both but they have to be specified separately to apt.

The uri, in this case http://ftp.debian.org/debian specifies the root of the archive. Often Debian archives are in the debian/ directory on the server but can be anywhere else (many mirrors for example have it in a pub/linux/debian directory, for example.

The distribution part (squeeze in this case) specifies a subdirectory in $ARCHIVE_ROOT/dists. It can contain additional slashes to specify subdirectories nested deeper, eg. squeeze/updates. distribution typically corresponds to Suite or Codename specified in the Release files. FIXME is this enforced anyhow?

To download packages from a repository apt would download a InRelease or Release file from the $ARCHIVE_ROOT/dists/$DISTRIBUTION directory.

InRelease files are signed in-line while Release files should have an accompanying Release.gpg file.

The Release file lists the index files for the distribution and their hashes (the index file listed are relative to Release file location).

To download index of the main component apt would scan the Release file for hashes of files in the main directory. eg. http://ftp.cz.debian.org/debian/dists/testing/main/binary-i386/Packages.bz2 which would be listed in http://ftp.cz.debian.org/debian/dists/testing/main/Release as binary-i386/Packages.bz2

Binary package indices are in binary-$arch subdirectory of the component directories. Source indices are in source subdirectory.

Package indices list specific source or binary packages relative to the archive root.

To avoid file duplication binary and source packages are usually kept in the pool subdirectory of the archive root. The Packages and Sources indices can list any path relative to archive root, however. It is suggested that packages are placed in a subdirectory of archive root other than dists rather than directly in archive root. Placing packages directly in the archive root is not tested and some tools may fail to index or retrieva packages placed there.

The Contents and Translation indices are not architecture-specific and are placed in dists/$DISTRIBUTION/$COMPONENT directory, not architecture subdirectory.

Compression of indices

Unless a compression is indicated by the filename of the indices below, and index may be compressed in one or multiple of the following formats:

Some clients may also support other compression formats, such as:

Those are not used by official archives and should not be used by anyone.

"Release" files

The file "dists/$DIST/InRelease" shall contain meta-information about the distribution and checksums for the indices, possibly signed with a GPG cleansign signature (for example created by "gpg -a -s --clearsign"). For older clients there can also be a "dists/$DIST/Release" file without any signature and the file "dists/$DIST/Release.gpg" with a detached GPG signature of the "Release" file, compatible with the format used by the GPG options "-a -b -s".

The following fields have a well defined meaning:

Servers shall provide the InRelease file, and might provide a Release files and its signed counterparts with at least the following keys:

Still having a unsigned Release file and MD5Sum is currently highly recommended.

Clients may accept missing Release files, and Release files without the fields required for servers. They might reject Release files that do not contain at least one of the fields defined herein.

Architectures

Whitespace separated unique single words identifying Debian machine architectures as described in Architecture specification strings, Section 11.1. Clients should ignore Architectures they do not know about.

Origin

Optional field indicating the origin of the repository, a single line of free form text.

Label

Optional field including some kind of label, a single line of free form text.

Typically used extensively in repositories split over multiple media such as repositories stored on CDs.

Suite

The Suite field may describe the suite. A suite is a single word consisting. In Debian, this shall be one of oldstable, stable, testing, unstable, or experimental; with optional suffixes such as -updates.

Example:

Suite: stable

Codename

The Codename field shall describe the codename of the release. A codename is a single word. Debian releases are codenamed after Toy Story Characters, and the unstable suite has the codename sid, the experimental suite has the codename experimental.

Example:

   Codename: squeeze

Version

The Version field, if specified, shall be the version of the release. This is usually a sequence of integers separated by the character . (full stop).

Example:

   Version: 6.0

Date,Valid-Until

The Date field shall specify the time at which the Release file was created. The Valid-Until field may specify at which time the Release file should be considered expired by the client. Client behaviour on expired Release files is unspecified.

The format of the dates is the same as for the Date field in .changes files; and as used in debian/changelog files, and documented in Policy 4.4 ( Debian changelog: debian/changelog)

Components

A whitespace separated list of areas.

Example:

    Components: main contrib non-free

MD5Sum, SHA1, SHA256

These fields are used for two purposes:

  1. describe what package index files are present
  2. when release signature is available it certifies that listed index files and files referenced by those index files are genuine

Those fields shall be multi-line fields containing multiple lines of whitespace separated data. Each line shall contain

  1. The checksum of the file in the format corresponding to the field
  2. The size of the file (integer >= 0)

  3. The filename relative to the directory of the Release file

Each datum must be seperated by one or more whitespace characters.

Server requirements:

Client behaviour:

NotAutomatic and ButAutomaticUpgrades

The NotAutomatic and ButAutomaticUpgrades fields are optional boolean fields instructing the package manager. They may contain the values "yes" and "no". If one the fields is not specified, this has the same meaning as a value of "no".

If a value of "yes" is specified for the NotAutomatic field, a package manager should not install packages (or upgrade to newer versions) from this repository without explicit user consent (APT assigns priority 1 to this) If the field ButAutomaticUpgrades is specified as well and has the value "yes", the package manager should automatically install package upgrades from this repository, if the installed version of the package is higher than the version of the package in other sources (APT assigns priority 100).

Specifying "yes" for ButAutomaticUpgrades without specifying "yes" for NotAutomatic is invalid.

"Packages" Indices

The files dists/$DIST/$COMP/binary-$ARCH/Packages (and dists/$DIST/$COMP/debian-installer/binary-$ARCH/Packages for udebs) are called Binary Packages Indices. They consist of multiple paragraphs, where each paragraph has the format defined in Policy 5.3 (Binary package control files -- DEBIAN/control), and the additional fields defined in this section, precisely:

Note that the control file of .deb files may contain additional fields not yet documented by policy or not yet documented by policy which then might also be found in this file.

Filename

The mandatory Filename field shall list the path of the package archive relative to the base directory of the repository.

Example:

    Filename: pool/main/a/apt/apt_0.9.3_amd64.deb

Size

The mandatory size field shall give the size of the package file, in bytes.

Example:

    Size: 1158196

MD5sum, SHA1, SHA256

Checksums for the package. They shall be represented in hexadecimal notation. All fields should be provided, but are optional. A client should use the most secure checksum that it supports and that is specified for a file to verify that file.

Example:

    MD5sum: 2519c8c1afd27e70cf4ac10a5fa46e32
    SHA1: 646eda5b6d51190181c15f5537428161f6f04c1d
    SHA256: 3183eff291d1e9d905e78a6b467bbfb90b20fc2808d50b5e91bf55158b4c18be

Description-md5

An MD5 checksum of the complete English language description. If not specified, the checksum can be computed starting with the second byte after the colon following the field name containing the English language description (Description in the binary package) and includes the trailing newline of the field. The field value is processed as-is, without any formatting such as removing the indentation done.

In the example given below, the checksum is calculated starting from the c in commandline up to (and including) the newline character before Description-md5.

Example:

Description: commandline package manager
 This package provides commandline tools for searching and
 managing as well as querying information about packages
 as a low-level access to all features of the libapt-pkg library.
 .
 These include:
  * apt-get for retrieval of packages and information about them
    from authenticated sources and for installation, upgrade and
    removal of packages together with their dependencies
  * apt-cache for querying available information about installed
    as well as installable packages
  * apt-cdrom to use removable media as a source for packages
  * apt-config as an interface to the configuration settings
  * apt-key as an interface to manage authentication keys
Description-md5: 9fb97a88cb7383934ef963352b53b4a7

Description

As an exception to Policy 5.6.13 (Description), the value of the Description field may omit the long description if the Description-md5 field is defined. In such a case, the description is found in the Translation-en.

"Sources" Indices

The files dists/$DIST/$COMP/source/Sources are called Sources indices. They consist of multiple paragraphs, where each paragraph has the format defined in Policy 5.5 (5.4 Debian source control files -- .dsc), with the following changes and additional fields. The changes are:

(Note that any fields present in .dsc files can end here as well, even if they are not documented by Debian policy, or not yet documented yet).

Directory

The directory field shall list the location of the source package in the repository, relative to the base directory of the repository.

Example:

    Directory: pool/main/a/apt

Priority

Shall contain one of the values specified in Policy 2.5 (Priorities), or the value "source". Implementation Notes: dak currently uses "source", reprepro uses one of the normal priority values.

Example:

    Priority: source

Section

Shall contain the section specified for the source package?? FIXME

Example:

    Section: admin

"Contents" indices

The files dists/$DIST/$COMP/Contents-$SARCH.gz (and dists/$DIST/$COMP/Contents-udeb-$SARCH.gz for udebs) are so called Contents indices. The variable $SARCH means either a binary architecture or the pseudo-architecture "source" that represents source packages. They are optional indices describing which files can be found in which packages. Prior to Debian wheezy, the files where located below "dists/$DIST/Contents-$SARCH.gz".

Contents indices begin with zero or more lines of free form text followed by a table mapping filenames to one or more packages. The table SHALL have two columns, separated by one or more spaces. The first row of the table SHOULD have the columns "FILE" and "LOCATION", the following rows shall have the following columns:

  1. A filename relative to the root directory, without leading .
  2. A list of qualified package names, separated by comma, where a qualified package name has the format "SECTION/NAME". The "SECTION/" part is optional for "Contents-source" indices; prior to wheezy, the per-release Contents files may have qualified names of the form "AREA/SECTION/NAME" as well, for packages in archive areas different than main.

The right column does not have white space characters, whereas a file name may have white space characters. A client should handle this.

Clients should ignore lines they do not understand. This takes care of the header, and also possibly in-between data created by third-party repositories.

"Translation" indices

The directory dists/$DIST/$COMP/i18n/ contains the file index, with a SHA1 field listing the description indices in that directory, in the same format as used for Release files, and one or more description indices.

Each description index has the format Translation-$LANG.bz2, where $LANG is a language code corresponding to a locale.

A Translation index is like a Packages index, but has the following fields only:

The Package and Description-md5 fields have the same meaning as for Packages indices. The Description-$LANG field, where $LANG is the same value as that of $LANG in the filename, shall be a description as described in Policy 5.6.13 Description, localized for that language.

The file Translation-en.bz2 contains the English language descriptions, if those are not supplied in the Packages index.

Example:

Package: aspell-ca
Description-md5: ac1a5e69d940eb04be1942837e419d62
Description-ca: Diccionari català per aspell
 Aquest paquet conté tots els fitxers necessaris per afegir suport per
 l'idioma català pel corrector ortogràfic GNU Aspell.
 .
 Va ser recollit per en Joan Moratinos utilitzant dades de diverses fonts.

indices difference files (diffs)

For each of the indices previously defined, repositories may also provide indices difference files, that contain the differences to previous versions of the index.

If an (uncompressed) index is located at the path $I, then a directory called $I.diff can exist. This directory contains the following files:

.diff/Index files

The index file shall be a file with the following fields:

SHA1-Current

The SHA1 of the current index $I. This is the same one as listed in a SHA1 field of the Release file to make sure it is the right diff file.

SHA1-History and SHA1-Patches

The SHA1-History and SHA1-Patches field are multi-line fields, where each line consists of the following columns, separated by a single space:

  1. A SHA1 checksum
  2. A size
  3. The name of a patch file

For SHA1-History, the SHA1 and the size describe the index to which the patch applies. For SHA1-Patches, the SHA1 and the size refer to the uncompressed patch file.

Example:

SHA1-Current: 8d190506d0c20b20b3cee06956e2061f3c083281 29137603
SHA1-History:
 a3cc0e588a41662db61e432f8c174a0d29aa4a9b 29086963 2012-05-04-2025.35
SHA1-Patches:
 351c97e091e10313eb7e2aeb8a1dd8088726cf20   91134 2012-05-04-2025.35

Each patch applied to the old version of the index file listed in SHA1-History creates a new file that either is the file looked for or some other old version that is also listed in SHA1-History.

DAK currently creates patches to be applied one by one. reprepro creates patches directly resulting in the final file. reprepro also adds a line

X-Patch-Precedence: merged

so clients wishing to optimize for one-by-one applying know that this is not possible.

Those files are in a format that is a subset of the "patch --ed" format. The supported ed commands are c (change), a (add), and d (delete). The records must be reverse sorted by line number and may not overlap. According to APT documentation, diff seems to produce this format, but no guarantee is made.

Debian installer files - udeb packages

The main repository also contains Debian installer files (.udeb packages) and their indices.

These are used only by the Debian installer and are not installed on a Debian system under normal circumstances.

Flat Repository Format

A flat repository does not use the dists hierarchy of directories, and instead places meta index and indices directly into the archive root (or some part below it) In sources.list syntax, a flat repository is specified like this:

   deb uri directory/

Where uri specifies the archive root, and directory specifies the position of the meta index and the indices relative to the archive root. In Flat repositories, the following indices are supported:

InRelease, Release, Release.gpg meta-information are supported as well. Diffs, Translations, and Contents indices are not defined for that repository format. Indices may be compressed just like in the standard Debian repository format.