
                                  APT Files


-----------------------------------------------------------------------------
                                      
                               Jason Gunthorpe

                              <jgg@debian.org>

                                Version 3.2.0

-----------------------------------------------------------------------------

Copyright © 1998-1999 Jason Gunthorpe

License Notice

    "APT" and this document are free software; you can redistribute them and/
    or modify them under the terms of the GNU General Public License as
    published by the Free Software Foundation; either version 2 of the
    License, or (at your option) any later version.

    For more details, on Debian systems, see the file /usr/share/
    common-licenses/GPL for the full license.

Abstract

This document describes the complete implementation and format of the
installed APT directory structure. It also serves as guide to how APT views
the Debian archive.

-----------------------------------------------------------------------------

Table of Contents

1. Introduction
    1.1. General
2. Files
    2.1. Files and fragment directories in /etc/apt
    2.2. Distribution Source list (sources.list)
        2.2.1. Hashing the URI
    2.3. Extended States File (extended_states)
    2.4. Binary Package Cache (srcpkgcache.bin and pkgcache.bin)
    2.5. Downloads Directory (archives)
    2.6. The Methods Directory (/usr/lib/apt/methods)
    2.7. The Configuration File (/etc/apt/apt.conf)
    2.8. The trusted.gpg File (/etc/apt/trusted.gpg)
    2.9. The Release File

Chapter 1. Introduction

Table of Contents

1.1. General

1.1. General

    This document serves two purposes. The first is to document the installed
    directory structure and the format and purpose of each file. The second
    purpose is to document how APT views the Debian archive and deals with
    multiple package files.

    The var directory structure is as follows:

      /var/lib/apt/
                    lists/
                           partial/
                    periodic/
                    extended_states
                    cdroms.list
      /var/cache/apt/
                      archives/
                              partial/
                      pkgcache.bin
                      srcpkgcache.bin
      /etc/apt/
                sources.list.d/
                apt.conf.d/
                preferences.d/
                trusted.gpg.d/
                sources.list
                apt.conf
                apt_preferences
                trusted.gpg
      /usr/lib/apt/
                    methods/
                             bzip2
                             cdrom
                             copy
                             file
                             gpgv
                             gzip
                             http
                             https
                             lzma
                             rred

    As is specified in the FHS 2.1 /var/lib/apt is used for application data
    that is not expected to be user modified. /var/cache/apt is used for
    regeneratable data and is where the package cache and downloaded .debs
    go. /etc/apt is the place where configuration should happen and /usr/lib/
    apt is the place where the apt and other packages can place binaries
    which can be used by the acquire system of APT.

Chapter 2. Files

Table of Contents

2.1. Files and fragment directories in /etc/apt
2.2. Distribution Source list (sources.list)
    2.2.1. Hashing the URI
2.3. Extended States File (extended_states)
2.4. Binary Package Cache (srcpkgcache.bin and pkgcache.bin)
2.5. Downloads Directory (archives)
2.6. The Methods Directory (/usr/lib/apt/methods)
2.7. The Configuration File (/etc/apt/apt.conf)
2.8. The trusted.gpg File (/etc/apt/trusted.gpg)
2.9. The Release File

2.1. Files and fragment directories in /etc/apt

    All files in /etc/apt are used to modify specific aspects of APT. To
    enable other packages to ship needed configuration herself all these
    files have a fragment directory packages can place their files in instead
    of mangling with the main files. The main files are therefore considered
    to be only used by the user and not by a package. The documentation omits
    this directories most of the time to be easier readable, so every time
    the documentation includes a reference to a main file it really means the
    file or the fragment directories.

2.2. Distribution Source list (sources.list)

    The distribution source list is used to locate archives of the debian
    distribution. It is designed to support any number of active sources and
    to support a mix of source media. The file lists one source per line,
    with the fastest source listed first. The format of each line is:

    type uri args

    The first item, type, indicates the format for the remainder of the line.
    It is designed to indicate the structure of the distribution the line is
    talking about. Currently the only defined values are deb and deb-src
    which indicate a standard debian (source) archive with a dists directory.
    More about these types and the URI specification can be found in the
    sources.list manpage.

2.2.1. Hashing the URI

    All permanent information acquired from any of the sources is stored in
    the lists directory. Thus, there must be a way to relate the filename in
    the lists directory to a line in the sourcelist. To simplify things this
    is done by quoting the URI and treating _'s as quoteable characters and
    converting / to _. The URI spec says this is done by converting a
    sensitive character into %xx where xx is the hexadecimal representation
    from the ASCII character set. Examples:

    http://www.debian.org/archive/dists/stable/binary-i386/Packages
    /var/lib/apt/lists/www.debian.org_archive_dists_stable_binary-i386_Packages
   
    cdrom:Debian 1.3/debian/Packages
    /var/lib/apt/info/Debian%201.3_debian_Packages

    The other alternative that was considered was to use a deep directory
    structure but this poses two problems, it makes it very difficult to
    prune directories back when sources are no longer used and complicates
    the handling of the partial directory. This gives a very simple way to
    deal with all of the situations that can arise. Also note that the same
    rules described in the Archive Directory section regarding the partial
    sub dir apply here as well.

2.3. Extended States File (extended_states)

    The extended_states file serves the same purpose as the normal dpkg
    status file (/var/lib/dpkg/status) except that it stores information
    unique to apt. This includes currently only the autoflag but is open to
    store more unique data that come up over time. It duplicates nothing from
    the normal dpkg status file. Please see other APT documentation for a
    discussion of the exact internal behavior of these fields. The Package
    and the Architecture field are placed directly before the new fields to
    indicate which package they apply to. The new fields are as follows:

    Auto-Installed

        The Auto flag can be 1 (Yes) or 0 (No) and controls whether the
        package was automatically installed to satisfy a dependency or if the
        user requested the installation

2.4. Binary Package Cache (srcpkgcache.bin and pkgcache.bin)

    Please see cache.sgml for a complete description of what this file is.
    The cache file is updated whenever the Packages or Release files of the
    lists directory or the dpkg status file changes. If the cache is erased,
    corrupted or of a non-matching version it will be automatically rebuilt
    by all of the tools that need it. srcpkgcache.bin contains a cache of all
    of the package, release files in the source list. In comparison to 
    pkgcache.bin, it does not include the /var/lib/dpkg/status file. This
    allows regeneration of the cache when the status files change to use a
    prebuilt version for greater speed.

2.5. Downloads Directory (archives)

    The archives directory is where all downloaded .deb archives go. When the
    file transfer is initiated the deb is placed in partial. Once the file is
    fully downloaded and its MD5 hash and size are verified it is moved from
    partial into archives/. Any files found in archives/ can be assumed to be
    verified.

    No directory structure is transferred from the receiving site and all
    .deb file names conform to debian conventions. No short (msdos) filename
    should be placed in archives. If the need arises .debs should be
    unpacked, scanned and renamed to their correct internal names. This is
    mostly to prevent file name conflicts but other programs may depend on
    this if convenient. A conforming .deb is one of the form,
    name_version_arch.deb. Our archive scripts do not handle epochs, but they
    are necessary and should be re-inserted. If necessary _'s and :'s in the
    fields should be quoted using the % convention. It must be possible to
    extract all 3 fields by examining the file name. Downloaded .debs must be
    found in one of the package lists with an exact name + version match..

2.6. The Methods Directory (/usr/lib/apt/methods)

    The Methods directory is more fully described in the APT Methods
    interface document.

2.7. The Configuration File (/etc/apt/apt.conf)

    The configuration file (and the associated fragments directory /etc/apt/
    apt.conf.d/) is described in the apt.conf manpage.

2.8. The trusted.gpg File (/etc/apt/trusted.gpg)

    The trusted.gpg file (and the files in the associated fragments directory
    /etc/apt/trusted.gpg.d/) is a binary file including the keyring used by
    apt to validate that the information (e.g. the Release file) it downloads
    are really from the distributor it clams to be and is unmodified and is
    therefore the last step in the chain of trust between the archive and the
    end user. This security system is described in the apt-secure manpage.

2.9. The Release File

    This file plays an important role in how APT presents the archive to the
    user. Its main purpose is to present a descriptive name for the source of
    each version of each package. It also is used to detect when new versions
    of debian are released. It augments the package file it is associated
    with by providing meta information about the entire archive which the
    Packages file describes.

    The full name of the distribution for presentation to the user is formed
    as 'label version archive', with a possible extended name being 'label
    version archive component'.

    The file is formed as the package file (RFC-822) with the following tags
    defined:

    Archive

        This is the common name we give our archives, such as stable or 
        unstable.

    Component

        Refers to the sub-component of the archive, main, contrib etc.
        Component may be omitted if there are no components for this archive.

    Version

        This is a version string with the same properties as in the Packages
        file. It represents the release level of the archive.

    Origin

        This specifies who is providing this archive. In the case of Debian
        the string will read 'Debian'. Other providers may use their own
        string

    Label

        This carries the encompassing name of the distribution. For Debian
        proper this field reads 'Debian'. For derived distributions it should
        contain their proper name.

    Architecture

        When the archive has packages for a single architecture then the
        Architecture is listed here. If a mixed set of systems are
        represented then this should contain the keyword mixed.

    NotAutomatic

        A Yes/No flag indicating that the archive is extremely unstable and
        its version's should never be automatically selected. This is to be
        used by experimental.

    Description

        Description is used to describe the release. For instance
        experimental would contain a warning that the packages have problems.

    The location of the Release file in the archive is very important, it
    must be located in the same location as the packages file so that it can
    be located in all situations. The following is an example for the current
    stable release, 1.3.1r6

    Archive: stable
    Component: main
    Version: 1.3.1r6
    Origin: Debian
    Label: Debian
    Architecture: i386

    This is an example of experimental,

    Archive: experimental
    Version: 0
    Origin: Debian
    Label: Debian
    Architecture: mixed
    NotAutomatic: Yes

    And unstable,

    Archive: unstable
    Component: main
    Version: 2.1
    Origin: Debian
    Label: Debian
    Architecture: i386

