You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

394 lines
12 KiB

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