<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Chapter 2. Files</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"/>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<link rel="home" href="index.html" title="APT Files"/>
<link rel="up" href="index.html" title="APT Files"/>
<link rel="prev" href="ch1.html" title="Chapter 1. Introduction"/>
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">Chapter 2. Files</th>
</tr>
<tr>
<td align="left"><a accesskey="p" href="ch1.html">Prev</a> </td>
<th width="60%" align="center"> </th>
<td align="right"> </td>
</tr>
</table>
<hr/>
</div>
<div class="chapter">
<div class="titlepage">
<div>
<div>
<h1 class="title"><a id="ch2"/>Chapter 2. Files</h1>
</div>
</div>
</div>
<div class="toc">
<p>
<strong>Table of Contents</strong>
</p>
<dl class="toc">
<dt>
<span class="section">
<a href="ch2.html#s2.1">2.1. Files and fragment directories in /etc/apt</a>
</span>
</dt>
<dt>
<span class="section">
<a href="ch2.html#s2.2">2.2. Distribution Source list (sources.list)</a>
</span>
</dt>
<dt>
<span class="section">
<a href="ch2.html#s2.3">2.3. Extended States File (extended_states)</a>
</span>
</dt>
<dt>
<span class="section">
<a href="ch2.html#s2.4">2.4. Binary Package Cache (srcpkgcache.bin and pkgcache.bin)</a>
</span>
</dt>
<dt>
<span class="section">
<a href="ch2.html#s2.5">2.5. Downloads Directory (archives)</a>
</span>
</dt>
<dt>
<span class="section">
<a href="ch2.html#s2.6">2.6. The Methods Directory (/usr/lib/apt/methods)</a>
</span>
</dt>
<dt>
<span class="section">
<a href="ch2.html#s2.7">2.7. The Configuration File (/etc/apt/apt.conf)</a>
</span>
</dt>
<dt>
<span class="section">
<a href="ch2.html#s2.8">2.8. The trusted.gpg File (/etc/apt/trusted.gpg)</a>
</span>
</dt>
<dt>
<span class="section">
<a href="ch2.html#s2.9">2.9. The Release File</a>
</span>
</dt>
</dl>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title"><a id="s2.1"/>2.1. Files and fragment directories in /etc/apt</h2>
</div>
</div>
</div>
<p>
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.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title"><a id="s2.2"/>2.2. Distribution Source list (sources.list)</h2>
</div>
</div>
</div>
<p>
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:
</p>
<p>
<em class="replaceable"><code>type uri args</code></em>
</p>
<p>
The first item, <em class="replaceable"><code>type</code></em>, 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
<span class="emphasis"><em>deb</em></span> and <span class="emphasis"><em>deb-src</em></span> 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.
</p>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="s2.2.1"/>2.2.1. Hashing the URI</h3>
</div>
</div>
</div>
<p>
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:
</p>
<pre class="screen">
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
</pre>
<p>
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
<span class="emphasis"><em>Archive Directory</em></span> section regarding the partial sub dir
apply here as well.
</p>
</div>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title"><a id="s2.3"/>2.3. Extended States File (extended_states)</h2>
</div>
</div>
</div>
<p>
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:
</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">Auto-Installed</span>
</dt>
<dd>
<p>
The Auto flag can be 1 (Yes) or 0 (No) and controls whether the package was
automatical installed to satisfy a dependency or if the user requested the
installation
</p>
</dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title"><a id="s2.4"/>2.4. Binary Package Cache (srcpkgcache.bin and pkgcache.bin)</h2>
</div>
</div>
</div>
<p>
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. <span class="emphasis"><em>srcpkgcache.bin</em></span> contains a cache of all of the
package, release files in the source list. In comparison to <span class="emphasis"><em>pkgcache.bin</em></span>, 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.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title"><a id="s2.5"/>2.5. Downloads Directory (archives)</h2>
</div>
</div>
</div>
<p>
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.
</p>
<p>
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..
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title"><a id="s2.6"/>2.6. The Methods Directory (/usr/lib/apt/methods)</h2>
</div>
</div>
</div>
<p>
The Methods directory is more fully described in the APT Methods interface
document.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title"><a id="s2.7"/>2.7. The Configuration File (/etc/apt/apt.conf)</h2>
</div>
</div>
</div>
<p>
The configuration file (and the associated fragments directory
/etc/apt/apt.conf.d/) is described in the apt.conf manpage.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title"><a id="s2.8"/>2.8. The trusted.gpg File (/etc/apt/trusted.gpg)</h2>
</div>
</div>
</div>
<p>
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.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title"><a id="s2.9"/>2.9. The Release File</h2>
</div>
</div>
</div>
<p>
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.
</p>
<p>
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'.
</p>
<p>
The file is formed as the package file (RFC-822) with the following tags
defined:
</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">Archive</span>
</dt>
<dd>
<p>
This is the common name we give our archives, such as
<span class="emphasis"><em>stable</em></span> or <span class="emphasis"><em>unstable</em></span>.
</p>
</dd>
<dt>
<span class="term">Component</span>
</dt>
<dd>
<p>
Refers to the sub-component of the archive, <span class="emphasis"><em>main</em></span>,
<span class="emphasis"><em>contrib</em></span> etc. Component may be omitted if there are no
components for this archive.
</p>
</dd>
<dt>
<span class="term">Version</span>
</dt>
<dd>
<p>
This is a version string with the same properties as in the Packages file. It
represents the release level of the archive.
</p>
</dd>
<dt>
<span class="term">Origin</span>
</dt>
<dd>
<p>
This specifies who is providing this archive. In the case of Debian the string
will read 'Debian'. Other providers may use their own string
</p>
</dd>
<dt>
<span class="term">Label</span>
</dt>
<dd>
<p>
This carries the encompassing name of the distribution. For Debian proper this
field reads 'Debian'. For derived distributions it should contain their proper
name.
</p>
</dd>
<dt>
<span class="term">Architecture</span>
</dt>
<dd>
<p>
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 <span class="emphasis"><em>mixed</em></span>.
</p>
</dd>
<dt>
<span class="term">NotAutomatic</span>
</dt>
<dd>
<p>
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.
</p>
</dd>
<dt>
<span class="term">Description</span>
</dt>
<dd>
<p>
Description is used to describe the release. For instance experimental would
contain a warning that the packages have problems.
</p>
</dd>
</dl>
</div>
<p>
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
</p>
<pre class="screen">
Archive: stable
Component: main
Version: 1.3.1r6
Origin: Debian
Label: Debian
Architecture: i386
</pre>
<p>
This is an example of experimental,
</p>
<pre class="screen">
Archive: experimental
Version: 0
Origin: Debian
Label: Debian
Architecture: mixed
NotAutomatic: Yes
</pre>
<p>
And unstable,
</p>
<pre class="screen">
Archive: unstable
Component: main
Version: 2.1
Origin: Debian
Label: Debian
Architecture: i386
</pre>
</div>
</div>
<div class="navfooter">
<hr/>
<table width="100%" summary="Navigation footer">
<tr>
<td align="left"><a accesskey="p" href="ch1.html">Prev</a> </td>
<td align="center"> </td>
<td align="right"> </td>
</tr>
<tr>
<td align="left" valign="top">Chapter 1. Introduction </td>
<td align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td align="right" valign="top"> </td>
</tr>
</table>
</div>
</body>
</html>
