Debian Archive Model

Debian Archive Model defines the structure, organization, and metadata of the Debian package repository. It describes how Debian packages and their associated files are stored, indexed, and presented to users and tools such as APT and dpkg. The model ensures consistency, integrity, and efficient access to packages across various architectures, distributions, and components.

Archive Structure

The Debian archive is organized hierarchically into suites, components, architectures, and packages.

Suites

Suites represent distribution states or releases. Common suite names include:

• stable: The current stable release.
• testing: The upcoming release under testing.
• unstable: The development branch (also called sid).
• oldstable: The previous stable release.
• experimental: For highly experimental packages.

Suites can also be named after codenames (e.g., bullseye, bookworm) corresponding to specific releases.

Components

Each suite is subdivided into components that categorize packages by their licensing and purpose:

• main: Officially supported free software packages.
• contrib: Free software packages that depend on non-free packages.
• non-free: Packages that do not comply fully with the Debian Free Software Guidelines.

Architectures

Packages are built for specific hardware architectures such as amd64, i386, arm64, etc. The archive stores packages separately per architecture under the components.

Repository Layout

The Debian archive repository typically resides under a base URL (mirror), with a directory structure reflecting the suite, component, and architecture:

/dists/<suite>/<component>/binary-<architecture>/

For example:

dists/stable/main/binary-amd64/

This directory contains package metadata files and indexes.

Package Files and Metadata

Each architecture/component/suite combination contains several important files that describe the packages:

Packages and Sources

• Packages: Lists of binary packages, including metadata such as name, version, dependencies, description, file size, and checksums.
• Sources: Lists of source packages, mirroring the information about source tarballs and their metadata.

Release Files

The Release file summarizes the entire suite and component contents. It contains checksums for all included index files, allowing clients to verify integrity.

InRelease and Release.gpg

• InRelease: A signed version of the Release file, combining signature and content, used for secure verification.
• Release.gpg: A detached GPG signature for the Release file.

Index Files

• Packages.gz / Packages.xz: Compressed versions of the Packages file.
• Sources.gz / Sources.xz: Compressed source package indexes.

These indexes are parsed by package managers to resolve dependencies and package versions.

Package Naming and Versions

Each package in the archive is uniquely identified by its name, version, and architecture. Versions follow Debian versioning rules which include upstream version, Debian revision, and epoch.

Packages are stored as .deb files for binary packages and .dsc files plus tarballs for source packages.

Mirror and Synchronization

Debian archives are mirrored worldwide to distribute load and improve access speed. Mirrors replicate the entire archive structure and metadata, ensuring consistency through checksums and signed release files.

Synchronization tools like rsync and apt-mirror are used to keep mirrors up to date.

Metadata Roles in Package Management

The archive metadata supports:

• Dependency resolution: Specifying package requirements, conflicts, and replacements.
• Version selection: Enabling upgrades and downgrades.
• Architecture filtering: Allowing clients to retrieve only relevant packages.
• Component filtering: Distinguishing free and non-free software.

Clients like APT use this metadata to build a local package cache and manage installations efficiently.

Summary of Key Files and Directories

Pool Directory

Unlike the dists/ directory which holds metadata, the actual package files reside in the pool/ directory. It is organized by the first letter of the package name for efficient storage and retrieval.

Example structure:

pool/main/a/apt/apt_2.4.0_amd64.deb
pool/non-free/n/nvidia-driver/nvidia-driver_470.82.01_amd64.deb

This structure decouples package storage from the release structure, allowing reuse of packages across multiple suites without duplication.

Integrity and Security

The Debian Archive Model incorporates cryptographic signatures and checksums to guarantee the authenticity and integrity of packages and metadata. This prevents tampering and ensures users download trusted software.

• SHA256/SHA512 checksums are included for all package files.
• GPG signatures on Release and InRelease files authenticate the source.

Handling Multiple Architectures and Multi-Arch

The archive supports multiple architectures by maintaining separate binary package indexes for each architecture under each component and suite. Additionally, the Debian multi-arch initiative allows installing packages from multiple architectures on the same system, supported by metadata fields indicating multi-arch compatibility.

Summary

The Debian Archive Model is a comprehensive framework defining how Debian packages are structured, indexed, and delivered via official repositories. It balances the needs of maintainers, mirror operators, and end-users by organizing packages into suites, components, and architectures, providing detailed metadata, ensuring security, and enabling efficient package management operations.