From 271733ee8eb9a673747bdef320af5ca8e8f18273 Mon Sep 17 00:00:00 2001 From: Guillem Jover Date: Wed, 2 Jul 2014 02:22:32 +0200 Subject: doc: Convert from DebianDoc SGML to DocBook XML --- doc/files.dbk | 392 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 392 insertions(+) create mode 100644 doc/files.dbk (limited to 'doc/files.dbk') diff --git a/doc/files.dbk b/doc/files.dbk new file mode 100644 index 000000000..675c92664 --- /dev/null +++ b/doc/files.dbk @@ -0,0 +1,392 @@ + + + %aptverbatiment; +]> + + + +APT Files + + + + + + Jason Gunthorpejgg@debian.org + + + +Version &apt-product-version; + + + +This document describes the complete implementation and format of the installed +APT directory structure. It also serves as guide to how APT views the Debian +archive. + + + +1998-1999Jason Gunthorpe + + +License Notice + +"APT" and this document are free software; you can redistribute them and/or +modify them under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or (at your +option) any later version. + + +For more details, on Debian systems, see the file +/usr/share/common-licenses/GPL for the full license. + + + + + +Introduction + +
General + +This document serves two purposes. The first is to document the installed +directory structure and the format and purpose of each file. The second +purpose is to document how APT views the Debian archive and deals with multiple +package files. + + +The var directory structure is as follows: + + + /var/lib/apt/ + lists/ + partial/ + periodic/ + extended_states + cdroms.list + /var/cache/apt/ + archives/ + partial/ + pkgcache.bin + srcpkgcache.bin + /etc/apt/ + sources.list.d/ + apt.conf.d/ + preferences.d/ + trusted.gpg.d/ + sources.list + apt.conf + apt_preferences + trusted.gpg + /usr/lib/apt/ + methods/ + bzip2 + cdrom + copy + file + ftp + gpgv + gzip + http + https + lzma + rred + rsh + ssh + + +As is specified in the FHS 2.1 /var/lib/apt is used for application data that +is not expected to be user modified. /var/cache/apt is used for regeneratable +data and is where the package cache and downloaded .debs go. /etc/apt is the +place where configuration should happen and /usr/lib/apt is the place where the +apt and other packages can place binaries which can be used by the acquire +system of APT. + +
+ + + +Files + +
Files and fragment directories in /etc/apt + +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. + +
+ +
Distribution Source list (sources.list) + +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: + + +type uri args + + +The first item, type, 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 +deb and deb-src 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. + + +
Hashing the URI + +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: + + +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 + + +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 +Archive Directory section regarding the partial sub dir +apply here as well. + +
+ +
+ +
Extended States File (extended_states) + +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: + + + +Auto-Installed + + +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 + + + + +
+ +
Binary Package Cache (srcpkgcache.bin and pkgcache.bin) + +Please see cache.sgml for a complete description of what this file +is. The cache file is updated whenever the contents of the lists +directory 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. srcpkgcache.bin contains a cache of all of the +package files in the source list. This allows regeneration of the cache +when the status files change to use a prebuilt version for greater speed. + +
+ +
Downloads Directory (archives) + +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. + + +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.. + +
+ +
The Methods Directory (/usr/lib/apt/methods) + +The Methods directory is more fully described in the APT Methods interface +document. + +
+ +
The Configuration File (/etc/apt/apt.conf) + +The configuration file (and the associated fragments directory +/etc/apt/apt.conf.d/) is described in the apt.conf manpage. + +
+ +
The trusted.gpg File (/etc/apt/trusted.gpg) + +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. + +
+ +
The Release File + +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. + + +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'. + + +The file is formed as the package file (RFC-822) with the following tags +defined: + + + +Archive + + +This is the common name we give our archives, such as +stable or unstable. + + + + +Component + + +Refers to the sub-component of the archive, main, +contrib etc. Component may be omitted if there are no +components for this archive. + + + + +Version + + +This is a version string with the same properties as in the Packages file. It +represents the release level of the archive. + + + + +Origin + + +This specifies who is providing this archive. In the case of Debian the string +will read 'Debian'. Other providers may use their own string + + + + +Label + + +This carries the encompassing name of the distribution. For Debian proper this +field reads 'Debian'. For derived distributions it should contain their proper +name. + + + + +Architecture + + +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 mixed. + + + + +NotAutomatic + + +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. + + + + +Description + + +Description is used to describe the release. For instance experimental would +contain a warning that the packages have problems. + + + + + +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 + + +Archive: stable +Component: main +Version: 1.3.1r6 +Origin: Debian +Label: Debian +Architecture: i386 + + +This is an example of experimental, + + +Archive: experimental +Version: 0 +Origin: Debian +Label: Debian +Architecture: mixed +NotAutomatic: Yes + + +And unstable, + + +Archive: unstable +Component: main +Version: 2.1 +Origin: Debian +Label: Debian +Architecture: i386 + +
+ + + + + -- cgit v1.2.3 From 5abbf5bbb5ee8717f89cac6ef409c4cec79259f6 Mon Sep 17 00:00:00 2001 From: David Kalnischkies Date: Fri, 18 Jul 2014 16:42:40 +0200 Subject: ensure that all docs use all entities files Not all are needed for all files at the moment, but the new docbook building hadn't available some of the entities it used as the files weren't correctly copied around in all cases and having the same across the bord makes working with all of them a little easier. Git-Dch: Ignore --- doc/files.dbk | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'doc/files.dbk') diff --git a/doc/files.dbk b/doc/files.dbk index 675c92664..f513e0008 100644 --- a/doc/files.dbk +++ b/doc/files.dbk @@ -1,8 +1,9 @@ - %aptent; %aptverbatiment; + %aptvendor; ]> -- cgit v1.2.3