doc/files.sgml

   1 <!-- -*- mode: sgml; mode: fold -*- -->
   2 <!doctype debiandoc  PUBLIC  "-//DebianDoc//DTD DebianDoc//EN">
   3 <book>
   4 <title>APT Files</title>
   5
   6 <author>Jason Gunthorpe <email>jgg@debian.org</email></author>
   7 <version>$Id: files.sgml,v 1.12 2003/04/26 23:26:13 doogie Exp $</version>
   8
   9 <abstract>
  10 This document describes the complete implementation and format of the
  11 installed APT directory structure. It also serves as guide to how APT
  12 views the Debian archive.
  13 </abstract>
  14
  15 <copyright>
  16 Copyright &copy; Jason Gunthorpe, 1998-1999.
  17 <p>
  18 "APT" and this document are free software; you can redistribute them and/or
  19 modify them under the terms of the GNU General Public License as published
  20 by the Free Software Foundation; either version 2 of the License, or (at your
  21 option) any later version.
  22
  23 <p>
  24 For more details, on Debian systems, see the file
  25 /usr/share/common-licenses/GPL for the full license.
  26 </copyright>
  27
  28 <toc sect>
  29
  30 <chapt>Introduction
  31 <!-- General                                                           {{{ -->
  32 <!-- ===================================================================== -->
  33 <sect>General
  34
  35 <p>
  36 This document serves two purposes. The first is to document the installed
  37 directory structure and the format and purpose of each file. The second
  38 purpose is to document how APT views the Debian archive and deals with
  39 multiple package files.
  40
  41 <p>
  42 The var directory structure is as follows:
  43 <example>
  44   /var/lib/apt/
  45                 lists/
  46                        partial/
  47                 periodic/
  48                 extended_states
  49                 cdroms.list
  50   /var/cache/apt/
  51                   archives/
  52                           partial/
  53                   pkgcache.bin
  54                   srcpkgcache.bin
  55   /etc/apt/
  56             sources.list.d/
  57             apt.conf.d/
  58             preferences.d/
  59             trusted.gpg.d/
  60             sources.list
  61             apt.conf
  62             apt_preferences
  63             trusted.gpg
  64   /usr/lib/apt/
  65                 methods/
  66                          bzip2
  67                          cdrom
  68                          copy
  69                          file
  70                          ftp
  71                          gpgv
  72                          gzip
  73                          http
  74                          https
  75                          lzma
  76                          rred
  77                          rsh
  78                          ssh
  79 </example>
  80
  81 <p>
  82 As is specified in the FHS 2.1 /var/lib/apt is used for application
  83 data that is not expected to be user modified. /var/cache/apt is used
  84 for regeneratable data and is where the package cache and downloaded .debs
  85 go. /etc/apt is the place where configuration should happen and
  86 /usr/lib/apt is the place where the apt and other packages can place
  87 binaries which can be used by the acquire system of APT.
  88 </sect>
  89                                                                   <!-- }}} -->
  90
  91 <chapt>Files
  92 <!-- Distribution Source List                                          {{{ -->
  93 <!-- ===================================================================== -->
  94 <sect>Files and fragment directories in /etc/apt
  95
  96 <p>
  97 All files in /etc/apt are used to modify specific aspects of APT. To enable
  98 other packages to ship needed configuration herself all these files have
  99 a fragment directory packages can place their files in instead of mangling
 100 with the main files. The main files are therefore considered to be only
 101 used by the user and not by a package. The documentation omits this directories
 102 most of the time to be easier readable, so every time the documentation includes
 103 a reference to a main file it really means the file or the fragment directories.
 104
 105 </sect>
 106
 107 <sect>Distribution Source list (sources.list)
 108
 109 <p>
 110 The distribution source list is used to locate archives of the debian
 111 distribution. It is designed to support any number of active sources and to
 112 support a mix of source media. The file lists one source per line, with the
 113 fastest source listed first. The format of each line is:
 114
 115 <p>
 116 <var>type uri args</var>
 117
 118 <p>
 119 The first item, <var>type</var>, indicates the format for the remainder
 120 of the line. It is designed to indicate the structure of the distribution
 121 the line is talking about. Currently the only defined values are <em>deb</em>
 122 and <em>deb-src</em> which indicate a standard debian (source) archive with a
 123 dists directory. More about these types and the URI specification can be found
 124 in the sources.list manpage.
 125
 126 <sect1>Hashing the URI
 127 <p>
 128 All permanent information acquired from any of the sources is stored in the
 129 lists directory. Thus, there must be a way to relate the filename in the
 130 lists directory to a line in the sourcelist. To simplify things this is
 131 done by quoting the URI and treating _'s as quoteable characters and
 132 converting / to _. The URI spec says this is done by converting a
 133 sensitive character into %xx where xx is the hexadecimal representation
 134 from the ASCII character set. Examples:
 135
 136 <example>
 137 http://www.debian.org/archive/dists/stable/binary-i386/Packages
 138 /var/lib/apt/lists/www.debian.org_archive_dists_stable_binary-i386_Packages
 139
 140 cdrom:Debian 1.3/debian/Packages
 141 /var/lib/apt/info/Debian%201.3_debian_Packages
 142 </example>
 143
 144 <p>
 145 The other alternative that was considered was to use a deep directory
 146 structure but this poses two problems, it makes it very difficult to prune
 147 directories back when sources are no longer used and complicates the handling
 148 of the partial directory. This gives a very simple way to deal with all
 149 of the situations that can arise. Also note that the same rules described in
 150 the <em>Archive Directory</> section regarding the partial sub dir apply
 151 here as well.
 152 </sect1>
 153
 154 </sect>
 155                                                                   <!-- }}} -->
 156 <!-- Extended Status                                                   {{{ -->
 157 <!-- ===================================================================== -->
 158 <sect>Extended States File (extended_states)
 159
 160 <p>
 161 The extended_states file serves the same purpose as the normal dpkg status file
 162 (/var/lib/dpkg/status) except that it stores information unique to apt.
 163 This includes currently only the autoflag but is open to store more
 164 unique data that come up over time. It duplicates nothing from the normal
 165 dpkg status file.  Please see other APT documentation for a discussion
 166 of the exact internal behavior of these fields. The Package and the
 167 Architecture field are placed directly before the new fields to indicate
 168 which package they apply to. The new fields are as follows:
 169
 170 <taglist>
 171 <tag>Auto-Installed<item>
 172    The Auto flag can be 1 (Yes) or 0 (No) and controls whether the package
 173    was automatical installed to satisfy a dependency or if the user requested
 174    the installation
 175 </taglist>
 176 </sect>
 177                                                                   <!-- }}} -->
 178 <!-- Binary Package Cache                                              {{{ -->
 179 <!-- ===================================================================== -->
 180 <sect>Binary Package Cache (srcpkgcache.bin and pkgcache.bin)
 181
 182 <p>
 183 Please see cache.sgml for a complete description of what this file is. The
 184 cache file is updated whenever the contents of the lists directory changes.
 185 If the cache is erased, corrupted or of a non-matching version it will
 186 be automatically rebuilt by all of the tools that need it.
 187 <em>srcpkgcache.bin</> contains a cache of all of the package files in the
 188 source list. This allows regeneration of the cache when the status files
 189 change to use a prebuilt version for greater speed.
 190 </sect>
 191                                                                   <!-- }}} -->
 192 <!-- Downloads Directory                                               {{{ -->
 193 <!-- ===================================================================== -->
 194 <sect>Downloads Directory (archives)
 195
 196 <p>
 197 The archives directory is where all downloaded .deb archives go. When the
 198 file transfer is initiated the deb is placed in partial. Once the file
 199 is fully downloaded and its MD5 hash and size are verified it is moved
 200 from partial into archives/. Any files found in archives/ can be assumed
 201 to be verified.
 202
 203 <p>
 204 No directory structure is transferred from the receiving site and all .deb
 205 file names conform to debian conventions. No short (msdos) filename should
 206 be placed in archives. If the need arises .debs should be unpacked, scanned
 207 and renamed to their correct internal names. This is mostly to prevent
 208 file name conflicts but other programs may depend on this if convenient.
 209 A conforming .deb is one of the form, name_version_arch.deb. Our archive
 210 scripts do not handle epochs, but they are necessary and should be re-inserted.
 211 If necessary _'s and :'s in the fields should be quoted using the % convention.
 212 It must be possible to extract all 3 fields by examining the file name.
 213 Downloaded .debs must be found in one of the package lists with an exact
 214 name + version match..
 215 </sect>
 216                                                                   <!-- }}} -->
 217 <!-- The Methods Directory                                             {{{ -->
 218 <!-- ===================================================================== -->
 219 <sect> The Methods Directory (/usr/lib/apt/methods)
 220
 221 <p>
 222 The Methods directory is more fully described in the APT Methods interface
 223 document.
 224 </sect>
 225                                                                   <!-- }}} -->
 226 <!-- The Configuration File                                            {{{ -->
 227 <!-- ===================================================================== -->
 228 <sect> The Configuration File (/etc/apt/apt.conf)
 229
 230 <p>
 231 The configuration file (and the associated fragments directory
 232 /etc/apt/apt.conf.d/) is described in the apt.conf manpage.
 233 </sect>
 234                                                                   <!-- }}} -->
 235 <!-- The trusted.gpg File                                              {{{ -->
 236 <!-- ===================================================================== -->
 237 <sect> The trusted.gpg File (/etc/apt/trusted.gpg)
 238
 239 <p>
 240 The trusted.gpg file (and the files in the associated fragments directory
 241 /etc/apt/trusted.gpg.d/) is a binary file including the keyring used
 242 by apt to validate that the information (e.g. the Release file) it
 243 downloads are really from the distributor it clams to be and is
 244 unmodified and is therefore the last step in the chain of trust between
 245 the archive and the end user. This security system is described in the
 246 apt-secure manpage.
 247 </sect>
 248                                                                   <!-- }}} -->
 249 <!-- The Release File                                                  {{{ -->
 250 <!-- ===================================================================== -->
 251 <sect> The Release File
 252
 253 <p>
 254 This file plays an important role in how APT presents the archive to the
 255 user. Its main purpose is to present a descriptive name for the source
 256 of each version of each package. It also is used to detect when new versions
 257 of debian are released. It augments the package file it is associated with
 258 by providing meta information about the entire archive which the Packages
 259 file describes.
 260
 261 <p>
 262 The full name of the distribution for presentation to the user is formed
 263 as 'label version archive', with a possible extended name being
 264 'label version archive component'.
 265
 266 <p>
 267 The file is formed as the package file (RFC-822) with the following tags
 268 defined:
 269
 270 <taglist>
 271 <tag>Archive<item>
 272 This is the common name we give our archives, such as <em>stable</> or
 273 <em>unstable</>.
 274
 275 <tag>Component<item>
 276 Refers to the sub-component of the archive, <em>main</>, <em>contrib</>
 277 etc. Component may be omitted if there are no components for this archive.
 278
 279 <tag>Version<item>
 280 This is a version string with the same properties as in the Packages file.
 281 It represents the release level of the archive.
 282
 283 <tag>Origin<item>
 284 This specifies who is providing this archive. In the case of Debian the
 285 string will read 'Debian'. Other providers may use their own string
 286
 287 <tag>Label<item>
 288 This carries the encompassing name of the distribution. For Debian proper
 289 this field reads 'Debian'. For derived distributions it should contain their
 290 proper name.
 291
 292 <tag>Architecture<item>
 293 When the archive has packages for a single architecture then the Architecture
 294 is listed here. If a mixed set of systems are represented then this should
 295 contain the keyword <em>mixed</em>.
 296
 297 <tag>NotAutomatic<item>
 298 A Yes/No flag indicating that the archive is extremely unstable and its
 299 version's should never be automatically selected. This is to be used by
 300 experimental.
 301
 302 <tag>Description<item>
 303 Description is used to describe the release. For instance experimental would
 304 contain a warning that the packages have problems.
 305 </taglist>
 306
 307 <p>
 308 The location of the Release file in the archive is very important, it must
 309 be located in the same location as the packages file so that it can be
 310 located in all situations. The following is an example for the current stable
 311 release, 1.3.1r6
 312
 313 <example>
 314 Archive: stable
 315 Component: main
 316 Version: 1.3.1r6
 317 Origin: Debian
 318 Label: Debian
 319 Architecture: i386
 320 </example>
 321
 322 This is an example of experimental,
 323 <example>
 324 Archive: experimental
 325 Version: 0
 326 Origin: Debian
 327 Label: Debian
 328 Architecture: mixed
 329 NotAutomatic: Yes
 330 </example>
 331
 332 And unstable,
 333 <example>
 334 Archive: unstable
 335 Component: main
 336 Version: 2.1
 337 Origin: Debian
 338 Label: Debian
 339 Architecture: i386
 340 </example>
 341
 342 </sect>
 343                                                                   <!-- }}} -->
 344
 345 </book>