Differences between revisions 9 and 10
Revision 9 as of 2012-05-18 16:09:04
Size: 11016
Editor: ?MichalSuchanek
Comment:
Revision 10 as of 2012-05-18 16:12:44
Size: 12495
Comment:
Deletions are marked like this. Additions are marked like this.
Line 266: Line 266:
The files dists/$DIST/$COMP/Contents-$SARCH.gz are so called Contents indices. The variable $SARCH means either a binary architecture or the pseudo-architecture "source" that represents source packages. The files dists/$DIST/$COMP/Contents-$SARCH.gz 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.
Line 277: Line 277:

Line 280: Line 278:

For each of the indices previously defined, repositories may also provide diff indices, 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:

 * Index
 * Compressed Difference files in the format "%Y-%m-%d-%H%M.%S.gz"

=== .diff/Index files ===
The index file shall be a file with the following fields:

 - SHA1-Current
 - SHA1-History
 - SHA1-Patches

==== SHA1-Current ====
The SHA1 of the current index $I.

==== 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
}}}



=== .diff/%Y-%m-%d-%H%M.%S files ===

Those files are in a format that is a subset of the "patch --ed" format.

FIXME: Explain

Debian Repository Format

This documents a subset of the Debian repository format. This is a work in progress.

Overview

FIXME

  • some general description of what goes where and why
  • relationship of Codename/Suite and dists/*

"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:

  • These fields are optional. They may be displayed to the user by package management tool or used for pinning. It is suggested that any repository published for other users to use fills meaningful information in these fields so that the user can tell apart different repositories.
    • Description
    • Origin
    • Label
    • Suite
  • These fields determine layout of the repository and should contain something meaningful to the user.
    • Codename
    • Components
    • Architectures
  • These optional fields are purely functional and used mostly internally by packaging tools.
    • Date
    • Valid-Until
    • MD5Sum, SHA1, SHA256 (note the upper-case Sum in MD5Sum)
    • ?NotAutomatic and ?ButAutomaticUpgrades

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

  • SHA256
  • Suite and/or Codename
  • Architectures
  • Components

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.

Label

Optional field including some kind of label.

Suite

The Suite field may describe the suite. In Debian, this shall be one of oldstable, stable, testing, unstable, or experimental; with optional suffixes separated by "-" (such as "stable-updates").

Codename

The Suite field shall describe the codename of the release. This is mostly a free-form string used to give a name to a release. (TODO: it's not really free-form, document the requirements).

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.

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:

  • The checksum and sizes shall match the actual existing files. When indexes are compressed checksum data should be provided for uncompressed files as well, even if not present on the server. Previously it was possible to supply a compressed file and checksum of uncompressed file only but this is no longer supported. Clients supporting multiple compression methods cannot infer the compressed file name when the release file contains uncompressed file checksum.

Client behaviour:

  • Any file should be checked at least once, either in compressed or uncompressed form, depending on which data is available. If a file has no associated data, the client shall inform the user about this under possibly dangerous situations (such as installing a package from that repository). If a file does not match the data specified in the release file, the client shall not use any information from that file, inform the user, and might use old information (such as the previous locally kept information) instead.

NotAutomatic and ButAutomaticUpgrades

The ?NotAutomatic and ?ButAutomaticUpgrades fields are boolean fields instructing the package manager. They may contain the values "yes" and "no".

If "?NotAutomatic: yes" is specified, the client should prevent installation of packages from this repository unless explicitely requested (APT will assign priority 1 to that repository).

If "?ButAutomaticUpgrades: yes" is specified in addition to "?NotAutomatic: yes", the client should cause upgrades to packages from that repository to be installed automatically (APT will assign priority 100 to that repository).

If both are either missing or set to "No", the repository should behave like any other repository (APT will assign either priority 500 or 990 by default, depending on whether the release is it's target release).

Other combinations are undefined.

"Packages" Indices

The files dists/$DIST/$COMP/binary-$ARCH/Packages 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.

Filename

The 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

Required: yes

Size

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

Example:

  • Size: 1158196

Required: yes

MD5sum, SHA1, SHA256, SHA512

Checksums for the package. They shall be represented in hexadecimal notation. The SHA512 field is not in active use prior to this specification, the MD5sum and SHA1 fields should be considered deprecated, but should still be provided.

Examples:

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

Server requirements: SHA256 shall be available Client requirements: Shall accept files without any such fields, should warn

  • if those fields are missing and a package is used.

Description-md5

An md5sum of the english description. This will be used to lookup the translations in the translation indices. If this field is not defined, the md5sum shall be calculated from the Description field.

Server requirements:

  • Either Description or Description-md5 shall be specified.

Client requirements:

  • If neither Description, nor Description-MD5 is defined, the result shall be the same as if an empty description was specified for all languages. If Description-md5 is defined, the long description shall be looked up via translation indices if requested.

Example:

  • Description-md5: 9fb97a88cb7383934ef963352b53b4a7

Description

The Description field shall contain the complete package description, if Description-md5 is not defined; or only the short description of the package, if Description-md5 is defined.

"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:

  • The "Source" field is renamed to "Package"
  • A new mandatory field "Package-List"
  • A new mandatory field "Directory"
  • A new optional field "Priority"
  • A new optional field "Section"

Package-List

The Package-List field shall contain multiple lines of package information, where each line begins with a whitespace and has the following format:

  • $PKGNAME $TYPE $SECTION $PRIORITY

$PKGNAME is the name of the package, $TYPE is "deb" or "udeb", $SECTION is the section of the package, and $PRIORITY is the priority of the package.

Example:

  • Package-List:
    • apt deb admin important apt-doc deb doc optional apt-transport-https deb admin optional apt-utils deb admin important libapt-inst1.5 deb admin important libapt-pkg-dev deb libdevel optional libapt-pkg-doc deb doc optional libapt-pkg4.12 deb admin important

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 the value "source".

Example:

  • Priority: source

Section

Shall contain the section specified for the source package??

Example:

  • Section: admin

"Contents" indices

The files dists/$DIST/$COMP/Contents-$SARCH.gz 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.

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.

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.

incremantal "diff" indices

For each of the indices previously defined, repositories may also provide diff indices, 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:

  • Index
  • Compressed Difference files in the format "%Y-%m-%d-%H%M.%S.gz"

.diff/Index files

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

  • - SHA1-Current - SHA1-History - SHA1-Patches

SHA1-Current

The SHA1 of the current index $I.

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

.diff/%Y-%m-%d-%H%M.%S files

Those files are in a format that is a subset of the "patch --ed" format.

FIXME: Explain

  • FIXME
    • optional
    • optimize index download size for large archives with few changes