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