| 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 © 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> |