diff options
| -rw-r--r-- | doc/design.dbk | 438 | ||||
| -rw-r--r-- | doc/design.sgml | 411 | ||||
| -rw-r--r-- | doc/dpkg-tech.dbk | 895 | ||||
| -rw-r--r-- | doc/dpkg-tech.sgml | 511 | ||||
| -rw-r--r-- | doc/files.dbk | 392 | ||||
| -rw-r--r-- | doc/files.sgml | 345 | ||||
| -rw-r--r-- | doc/guide.dbk | 560 | ||||
| -rw-r--r-- | doc/guide.sgml | 547 | ||||
| -rw-r--r-- | doc/method.dbk | 712 | ||||
| -rw-r--r-- | doc/method.sgml | 354 | ||||
| -rw-r--r-- | doc/offline.dbk (renamed from doc/offline.sgml) | 309 |
11 files changed, 3157 insertions, 2317 deletions
diff --git a/doc/design.dbk b/doc/design.dbk new file mode 100644 index 000000000..06743c8af --- /dev/null +++ b/doc/design.dbk @@ -0,0 +1,438 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- -*- DocBook -*- --> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment; +]> + +<book lang="en"> + +<title>The APT project design document</title> + +<bookinfo> + +<authorgroup> + <author> + <personname>Manoj Srivastava</personname><email>srivasta@debian.org</email> + </author> +</authorgroup> + +<releaseinfo>Version &apt-product-version;</releaseinfo> + +<abstract> +<para> +This document is an overview of the specifications and design goals of the APT +project. It also attempts to give a broad description of the implementation +as well. +</para> +</abstract> + +<copyright><year>1997</year><holder>Manoj Srivastava</holder></copyright> + +<legalnotice> +<title>License Notice</title> +<para> +APT, including this document, is free software; you may redistribute it and/or +modify it under the terms of the GNU General Public License as published by the +Free Software Foundation; either version 2, or (at your option) any later +version. +</para> +<para> +This is distributed in the hope that it will be useful, but <emphasis>without +any warranty</emphasis>; without even the implied warranty of merchantability +or fitness for a particular purpose. See the GNU General Public License for +more details. +</para> +<para> +You should have received a copy of the GNU General Public License with your +Debian system, in <literal>/usr/share/common-licenses/GPL</literal>, or with +the <command>debiandoc-sgml</command> source package as the file +<literal>COPYING</literal>. If not, write to the Free Software Foundation, +Inc., 675 Mass Ave, Cambridge, MA 02139, USA. +</para> +</legalnotice> + +</bookinfo> + +<chapter id="introduction"><title>Introduction</title> +<para> +APT is supposed to be a replacement for dselect, and not a replacement for +dpkg. However, since addition functionality has been required for APT, and +given the fact that this is very closely related to dpkg, it is not +unreasonable to expect that additional functionality in the underlying dpkg +would also be requested. +</para> +<para> +Deity/dselect are the first introduction that people have to Debian, and +unfortunately this first impression contributes greatly to the public +perception of the distribution. It is imperative that this be a showcase for +Debian, rather than frighten novices away (which has been an accusation often +levelled at the current system) +</para> +</chapter> + +<chapter id="ch2"><title>Requirements</title> +<orderedlist numeration="arabic"> +<listitem> +<para> +APT should be a replacement for dselect. Therefore it should have all the +functionality that dselect has currently. This is the primary means of +interaction between the user and the package management system, and it should +be able to handle all tasks involved in installing, upgrading, and routine +management without having the users take recourse to the underlying management +system. +</para> +</listitem> +<listitem> +<para> +It should be easier to use and less confusing for novice users. The primary +stimulus for the creation of APT was the perceived intractability, complexity, +and non-intuitive behavior of the existing user interface, and as such, human +factors must be a primary mandate of APT. +</para> +</listitem> +<listitem> +<para> +It should be able to group packages more flexibly, and possibly allow +operations based on a group. One should be able to select, or deselect, +a coherent group of related packages simultaneously, allowing one to add, +remove, or upgrade functionality to a machine as one step. +</para> +</listitem> +<listitem> +<para> +This would allow APT to handle <emphasis>standard installations</emphasis>, +namely, one could then install a set of packages to enable a machine to +fulfill specific tasks. Define a few standard installations, and which +packages are included therein. The packages should be internally consistent. +</para> +</listitem> +<listitem> +<para> +Make use of a keywords field in package headers; provide a standard list of +keywords for people to use. This could be the underpinning to allow the +previous two requirements to work (though the developers are not constrained +to implement the previous requirements using keywords) +</para> +</listitem> +<listitem> +<para> +Use dependencies, conflicts, and reverse dependencies to properly order +packages for installation and removal. This has been a complaint in the past +that the installation methods do not really understand dependencies, causing +the upgrade process to break, or allowing the removal of packages that left the +system in an untenable state by breaking the dependencies on packages that were +dependent on the package being removed. A special emphasis is placed on +handling pre-dependencies correctly; the target of a predependency has to be +fully configured before attempting to install the pre-dependent package. Also, +<emphasis>configure immediately</emphasis> requests mentioned below should be +handled. +</para> +</listitem> +<listitem> +<para> +Handle replacement of a package providing a virtual package with another (for +example, it has been very difficult replacing <command>sendmail</command> with +<command>smail</command>, or vice versa), making sure that the dependencies are +still satisfied. +</para> +</listitem> +<listitem> +<para> +Handle source lists for updates from multiple sources. APT should also be able +to handle diverse methods of acquiring new packages; local filesystem, +mountable CD-ROM drives, FTP accessible repositories are some of the methods +that come to mind. Also, the source lists can be separated into categories, +such as main, contrib, non-us, non-local, non-free, my-very-own, etc. APT +should be set up to retrieve the Packages files from these multiple source +lists, as well as retrieving the packages themselves. +</para> +</listitem> +<listitem> +<para> +Handle base of source and acquire all Packages files underneath. (possibly +select based on architecture), this should be a simple extension of the +previous requirement. +</para> +</listitem> +<listitem> +<para> +Handle remote installation (to be implemented maybe in a future version, it +still needs to be designed). This would ease the burden of maintaining +multiple Debian machines on a site. In the authors opinion this is a killer +difference for the distribution, though it may be too hard a problem to be +implemented with the initial version of APT. However, some thought must be +given to this to enable APT to retain hooks for future functionality, or at +least to refrain from methods that may preclude remote activity. It is +desirable that adding remote installation not require a redesign of APT from +the ground up. +</para> +</listitem> +<listitem> +<para> +Be scalable. Dselect worked a lot better with 400 packages, but at last count +the number of packages was around twelve hundred and climbing. This also +requires APT to pay attention to the needs of small machines which are low on +memory (though this requirement shall diminish as we move towards bigger +machines, it would still be nice if Debian worked on all old machines where +Linux itself would work). +</para> +</listitem> +<listitem> +<para> +Handle install immediately requests. Some packages, like watchdog, are +required to be working for the stability of the machine itself. There are +others which may be required for the correct functioning of a production +machine, or which are mission critical applications. APT should, in these +cases, upgrade the packages with minimal downtime; allowing these packages to +be one of potentially hundreds of packages being upgraded concurrently may +not satisfy the requirements of the package or the site. (Watchdog, for +example, if not restarted quickly, may cause the machine to reboot in the +midst of installation, which may cause havoc on the machine) +</para> +</listitem> +</orderedlist> +</chapter> + +<chapter id="ch3"><title>Procedural description</title> +<variablelist> +<varlistentry> +<term>Set Options</term> +<listitem> +<para> +This process handles setting of user or site options, and configuration of all +aspects of APT. It allows the user to set the location and order of package +sources, allowing them to set up source list details, like ftp site locations, +passwords, etc. Display options may also be set. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Updates</term> +<listitem> +<para> +Build a list of available packages, using source lists or a base location and +trawling for Packages files (needs to be aware of architecture). This may +involve finding and retrieving Packages files, storing them locally for +efficiency, and parsing the data for later use. This would entail contacting +various underlying access modules (ftp, cdrom mounts, etc) Use a backing store +for speed. This may also require downloading the actual package files locally +for speed. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Local status</term> +<listitem> +<para> +Build up a list of packages already installed. This requires reading and +writing the local?? status file. For remote installation, this should +probably use similar mechanisms as the Packages file retrieval does. Use +the backing store for speed. One should consider multiple backing stores, +one for each machine. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Relationship determination</term> +<listitem> +<para> +Determine forward and reverse dependencies. All known dependency fields should +be acted upon, since it is fairly cheap to do so. Update the backing store +with this information. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Selection</term> +<listitem> +<para> +Present the data to the user. Look at Behan Webster's documentation for the +user interface procedures. (Note: In the authors opinion deletions and reverse +dependencies should also be presented to the user, in a strictly symmetric +fashion; this may make it easier to prevent a package being removed that breaks +dependencies) +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Ordering of package installations and configuration</term> +<listitem> +<para> +Build a list of events. Simple topological sorting gives order of packages +in dependency order. At certain points in this ordering, +predependencies/immediate configure directives cause an break in normal +ordering. We need to insert the uninstall/purge directive in the stream +(default: as early as possible). +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Action</term> +<listitem> +<para> +Take the order of installations and removals and build up a stream of events +to send to the packaging system (dpkg). Execute the list of events if +successful. Do not partially install packages and leave system in broken +state. Go to The Selection step as needed. +</para> +</listitem> +</varlistentry> +</variablelist> +</chapter> + +<chapter id="ch4"><title>Modules and interfaces</title> +<variablelist> +<varlistentry> +<term>The user interface module</term> +<listitem> +<para> +Look at Behan Webster's documentation. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Widget set</term> +<listitem> +<para> +Related closely to above Could some one present design decisions of the widget +set here? +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>pdate Module</term> +<listitem> +<para> +Distinct versions of the same package are recorded separately, but if multiple +Packages files contain the same version of a package, then only the first one +is recorded. For this reason, the least expensive update source should be +listed first (local file system is better than a remote ftp site) +</para> +<para> +This module should interact with the user interface module to set and change +configuration parameters for the modules listed below. It needs to record that +information in an on disk data file, to be read on future invocations. +</para> +<orderedlist numeration="arabic"> +<listitem> +<para> +FTP methods +</para> +</listitem> +<listitem> +<para> +mount and file traversal module(s)? +</para> +</listitem> +<listitem> +<para> +Other methods ??? +</para> +</listitem> +</orderedlist> +</listitem> +</varlistentry> +<varlistentry> +<term>Status file parser/generator</term> +<listitem> +<para> +The status file records the current state of the system, listing the packages +installed, etc. The status file is also one method of communicating with dpkg, +since it is perfectly permissible for the user to use APT to request packages +be updated, put others on hold, mark other for removal, etc, and then run +<literal>dpkg -BORGiE</literal> on a file system. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Package file parser/generator</term> +<listitem> +<para> +Related to above. Handle multiple Packages files, from different +sources. Each package contains a link back to the packages file structure +that contains details about the origin of the data. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Dependency module</term> +<listitem> +<itemizedlist> +<listitem> +<para> +dependency/conflict determination and linking +</para> +</listitem> +<listitem> +<para> +reverse dependency generator. Maybe merged with above +</para> +</listitem> +</itemizedlist> +</listitem> +</varlistentry> +<varlistentry> +<term>Package ordering Module</term> +<listitem> +<para> +Create an ordering of the actions to be taken. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Event generator</term> +<listitem> +<para> +module to interact with dpkg +</para> +</listitem> +</varlistentry> +</variablelist> +</chapter> + +<chapter id="ch5"><title>Data flow and conversions analysis.</title> +<screen> + ____________ + __\|ftp modules| + / /|___________| + _ ____________ / ________________ + | update | / |mount/local file| + |==========================>| module |/_____\| traversals | + | |_____________| /|________________| + | ^ ^ + | | | ______________ + ______|_______ _ _____ ______ | _____v________ \| | + |Configuration | |configuration| | |Packages Files| ===|Status file | + | module |<=>| data | | |______________| / /|____________| + |______________| |_____________| | ^ / + ^ | | / + | | _______v_______|/_ + | | | | ________________ + | | | |/_\| Dependency | + | | |backing store |\ /| Module | + | | |______________| _|_______________| + | \ ^ /| ^ + | \ | / | + | _\|____v_______|/__ ____v_______ + |_____________________________\| User interaction| | dpkg | + /|_________________|<==> Invoker | + |___________| +</screen> +<para> +dpkg also interacts with status and available files. +</para> +<para> +The backing store and the associated data structures are the core of APT. All +modules essentially revolve around the backing store, feeding it data, adding +and manipulating links and relationships between data in the backing store, +allowing the user to interact with and modify the data in the backing store, +and finally writing it out as the status file and possibly issuing directives +to dpkg. +</para> +<para> +The other focal point for APT is the user interface. +</para> +</chapter> + +</book> diff --git a/doc/design.sgml b/doc/design.sgml deleted file mode 100644 index 67406aa01..000000000 --- a/doc/design.sgml +++ /dev/null @@ -1,411 +0,0 @@ -<!doctype debiandoc PUBLIC "-//DebianDoc//DTD DebianDoc//EN"> -<debiandoc> - <book> - <titlepag> - <title> The APT project design document</title> - <author> - <name>Manoj Srivastava</name> - <email>srivasta@debian.org</email> - </author> - <version>$Id: design.sgml,v 1.4 2003/02/12 15:05:45 doogie Exp $</version> - <abstract> - This document is an overview of the specifications and design - goals of the APT project. It also attempts to give a broad - description of the implementation as well. - </abstract> - <copyright> - <copyrightsummary>Copyright ©1997 Manoj Srivastava - </copyrightsummary> - <p> - APT, including this document, is free software; you may - redistribute it and/or modify it under the terms of the GNU - General Public License as published by the Free Software - Foundation; either version 2, or (at your option) any later - version.</p> - <p> - This is distributed in the hope that it will be useful, but - <em>without any warranty</em>; without even the implied - warranty of merchantability or fitness for a particular - purpose. See the GNU General Public License for more - details.</p> - - <p> - You should have received a copy of the GNU General Public - License with your Debian system, in - <tt>/usr/share/common-licenses/GPL</tt>, or with the - <prgn/debiandoc-sgml/ source package as the file - <tt>COPYING</tt>. If not, write to the Free Software - Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, - USA.</p> - </copyright> - </titlepag> - <chapt id="introduction"> - <heading>Introduction</heading> - <p>APT is supposed to be a replacement for dselect, and not a - replacement for dpkg. However, since addition functionality - has been required for APT, and given the fact that this is - very closely related to dpkg, it is not unreasonable to expect - that additional functionality in the underlying dpkg would - also be requested.</p> - - <p> Deity/dselect are the first introduction that people have to - Debian, and unfortunately this first impression contributes - greatly to the public perception of the distribution. It is - imperative that this be a showcase for Debian, rather than - frighten novices away (which has been an accusation often - levelled at the current system)</p> - </chapt> - <chapt> - <heading>Requirements</heading> - <p> - <enumlist compact="compact"> - <item> - <p> - APT should be a replacement for dselect. Therefore it - should have all the functionality that dselect has - currently. This is the primary means of interaction - between the user and the package management system, and - it should be able to handle all tasks involved in - installing, upgrading, and routine management without - having the users take recourse to the underlying - management system.</p> - </item> - <item> - <p> - It should be easier to use and less confusing for novice - users. The primary stimulus for the creation of APT - was the perceived intractability, complexity, and - non-intuitive behavior of the existing user interface, - and as such, human factors must be a primary mandate of - APT.</p> - </item> - <item> - <p> - It should be able to group packages more flexibly, and - possibly allow operations based on a group. One should - be able to select, or deselect, a coherent group of - related packages simultaneously, allowing one to add, - remove, or upgrade functionality to a machine as one - step. - </p> - </item> - <item> - <p> - This would allow APT to handle <em>standard - installations</em>, namely, one could then install a - set of packages to enable a machine to fulfill specific - tasks. Define a few standard installations, and which - packages are included therein. The packages should be - internally consistent.</p> - </item> - <item> - <p> - Make use of a keywords field in package headers; provide - a standard list of keywords for people to use. This - could be the underpinning to allow the previous two - requirements to work (though the developers are not - constrained to implement the previous requirements using - keywords) - </p> - </item> - <item> - <p> - Use dependencies, conflicts, and reverse dependencies to - properly order packages for installation and - removal. This has been a complaint in the past that the - installation methods do not really understand - dependencies, causing the upgrade process to break, or - allowing the removal of packages that left the system in - an untenable state by breaking the dependencies on - packages that were dependent on the package being - removed. A special emphasis is placed on handling - pre-dependencies correctly; the target of a - predependency has to be fully configured before - attempting to install the pre-dependent package. Also, - <em>configure immediately</em> requests mentioned below - should be handled.</p> - </item> - <item> - <p> - Handle replacement of a package providing a virtual - package with another (for example, it has been very - difficult replacing <prgn>sendmail</prgn> with - <prgn>smail</prgn>, or vice versa), making sure that the - dependencies are still satisfied. </p> - </item> - <item> - <p> - Handle source lists for updates from multiple - sources. APT should also be able to handle diverse - methods of acquiring new packages; local filesystem, - mountable CD-ROM drives, FTP accessible repositories are - some of the methods that come to mind. Also, the source - lists can be separated into categories, such as main, - contrib, non-us, non-local, non-free, my-very-own, - etc. APT should be set up to retrieve the Packages - files from these multiple source lists, as well as - retrieving the packages themselves. </p> - </item> - <item> - <p> - Handle base of source and acquire all Packages files - underneath. (possibly select based on architecture), - this should be a simple extension of the previous - requirement.</p> - </item> - <item> - <p> - Handle remote installation (to be implemented maybe in a - future version, it still needs to be designed). This - would ease the burden of maintaining multiple Debian - machines on a site. In the authors opinion this is a - killer difference for the distribution, though it may be - too hard a problem to be implemented with the initial - version of APT. However, some thought must be given to - this to enable APT to retain hooks for future - functionality, or at least to refrain from methods that - may preclude remote activity. It is desirable that - adding remote installation not require a redesign of - APT from the ground up.</p> - </item> - <item> - <p> - Be scalable. Dselect worked a lot better with 400 - packages, but at last count the number of packages was - around twelve hundred and climbing. This also requires - APT to pay attention to the needs of small machines - which are low on memory (though this requirement shall - diminish as we move towards bigger machines, it would - still be nice if Debian worked on all old machines where - Linux itself would work).</p> - </item> - <item> - <p> - Handle install immediately requests. Some packages, like - watchdog, are required to be working for the stability - of the machine itself. There are others which may be - required for the correct functioning of a production - machine, or which are mission critical - applications. APT should, in these cases, upgrade the - packages with minimal downtime; allowing these packages - to be one of potentially hundreds of packages being - upgraded concurrently may not satisfy the requirements - of the package or the site. (Watchdog, for example, if - not restarted quickly, may cause the machine to reboot - in the midst of installation, which may cause havoc on - the machine)</p> - </item> - </enumlist> - </p> - </chapt> - <chapt> - <heading>Procedural description</heading> - <p><taglist> - <tag>Set Options</tag> - <item> - <p> - This process handles setting of user or - site options, and configuration of all aspects of - APT. It allows the user to set the location and order - of package sources, allowing them to set up source list - details, like ftp site locations, passwords, - etc. Display options may also be set.</p> - </item> - <tag>Updates</tag> - <item> - <p> - Build a list of available packages, using - source lists or a base location and trawling for - Packages files (needs to be aware of architecture). This - may involve finding and retrieving Packages files, - storing them locally for efficiency, and parsing the - data for later use. This would entail contacting various - underlying access modules (ftp, cdrom mounts, etc) Use a - backing store for speed. This may also require - downloading the actual package files locally for - speed.</p> - </item> - <tag>Local status</tag> - <item> - <p> - Build up a list of packages already - installed. This requires reading and writing the local?? - status file. For remote installation, this should - probably use similar mechanisms as the Packages file - retrieval does. Use the backing store for speed. One - should consider multiple backing stores, one for each - machine. - </p> - </item> - <tag>Relationship determination</tag> - <item> - <p> - Determine forward and reverse dependencies. All known - dependency fields should be acted upon, since it is - fairly cheap to do so. Update the backing store with - this information.</p> - </item> - <tag>Selection</tag> - <item> - <p> - Present the data to the user. Look at Behan Webster's - documentation for the user interface procedures. (Note: - In the authors opinion deletions and reverse - dependencies should also be presented to the user, in a - strictly symmetric fashion; this may make it easier to - prevent a package being removed that breaks - dependencies) - </p> - </item> - <tag>Ordering of package installations and configuration </tag> - <item> - <p> - Build a list of events. Simple topological sorting gives - order of packages in dependency order. At certain points - in this ordering, predependencies/immediate configure - directives cause an break in normal ordering. We need to - insert the uninstall/purge directive in the stream - (default: as early as possible).</p> - </item> - <tag>Action</tag> - <item> - <p> - Take the order of installations and removals and build - up a stream of events to send to the packaging system - (dpkg). Execute the list of events if successful. Do not - partially install packages and leave system in broken - state. Go to The Selection step as needed.</p> - </item> - - </taglist> - </p> - </chapt> - <chapt> - <heading>Modules and interfaces</heading> - <p><taglist> - <tag>The user interface module</tag> - <item> - <p> Look at Behan Webster's documentation.</p> - </item> - <tag>Widget set</tag> - <item> - <p> - Related closely to above Could some one present design - decisions of the widget set here?</p> - </item> - <tag>pdate Module</tag> - <item> - <p> - Distinct versions of the same package are recorded - separately, but if multiple Packages files contain the - same version of a package, then only the first one is - recorded. For this reason, the least expensive update - source should be listed first (local file system is - better than a remote ftp site)</p> - <p> - This module should interact with the user interface - module to set and change configuration parameters for - the modules listed below. It needs to record that - information in an on disk data file, to be read on - future invocations. </p> - <p><enumlist> - <item> - <p>FTP methods</p> - </item> - <item> - <p>mount and file traversal module(s)?</p> - </item> - <item> - <p>Other methods ???</p> - </item> - </enumlist> - </p> - </item> - <tag>Status file parser/generator</tag> - <item> - <p> - The status file records the current state of the system, - listing the packages installed, etc. The status file is - also one method of communicating with dpkg, since it is - perfectly permissible for the user to use APT to - request packages be updated, put others on hold, mark - other for removal, etc, and then run <tt>dpkg - -BORGiE</tt> on a file system.</p> - </item> - <tag>Package file parser/generator</tag> - <item> - <p> - Related to above. Handle multiple Packages files, from - different sources. Each package contains a link back to - the packages file structure that contains details about - the origin of the data. </p> - </item> - <tag>Dependency module</tag> - <item> - <p><list> - <item> - <p>dependency/conflict determination and linking</p> - </item> - <item> - <p>reverse dependency generator. Maybe merged with above</p> - </item> - </list> - </p> - </item> - <tag>Package ordering Module</tag> - <item> - <p>Create an ordering of the actions to be taken.</p> - </item> - <tag>Event generator</tag> - <item> - <p>module to interact with dpkg</p> - </item> - </taglist> - </chapt> - <chapt> - <heading>Data flow and conversions analysis.</heading> - <p> - <example> - ____________ - __\|ftp modules| - / /|___________| - _ ____________ / ________________ - | update | / |mount/local file| - |==========================>| module |/_____\| traversals | - | |_____________| /|________________| - | ^ ^ - | | | ______________ - ______|_______ _ _____ ______ | _____v________ \| | - |Configuration | |configuration| | |Packages Files| ===|Status file | - | module |<=>| data | | |______________| / /|____________| - |______________| |_____________| | ^ / - ^ | | / - | | _______v_______|/_ - | | | | ________________ - | | | |/_\| Dependency | - | | |backing store |\ /| Module | - | | |______________| _|_______________| - | \ ^ /| ^ - | \ | / | - | _\|____v_______|/__ ____v_______ - |_____________________________\| User interaction| | dpkg | - /|_________________|<==>| Invoker | - |___________| - - </example> - <p> dpkg also interacts with status and available files.</p> - - - <p> - The backing store and the associated data structures are the - core of APT. All modules essentially revolve around the - backing store, feeding it data, adding and manipulating links - and relationships between data in the backing store, allowing - the user to interact with and modify the data in the backing - store, and finally writing it out as the status file and - possibly issuing directives to dpkg.</p> - - <p>The other focal point for APT is the user interface.</p> - </chapt> - </book> -</debiandoc> diff --git a/doc/dpkg-tech.dbk b/doc/dpkg-tech.dbk new file mode 100644 index 000000000..e7d150cee --- /dev/null +++ b/doc/dpkg-tech.dbk @@ -0,0 +1,895 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- -*- DocBook -*- --> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment; +]> + +<book lang="en"> + +<title>dpkg technical manual</title> + +<bookinfo> + +<authorgroup> + <author> + <personname>Tom Lees</personname><email>tom@lpsg.demon.co.uk</email> + </author> +</authorgroup> + +<releaseinfo>Version &apt-product-version;</releaseinfo> + +<abstract> +<para> +This document describes the minimum necessary workings for the APT dselect +replacement. It gives an overall specification of what its external interface +must look like for compatibility, and also gives details of some internal +quirks. +</para> +</abstract> + +<copyright><year>1997</year><holder>Tom Lees</holder></copyright> + +<legalnotice> +<title>License Notice</title> +<para> +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. +</para> +<para> +For more details, on Debian systems, see the file +/usr/share/common-licenses/GPL for the full license. +</para> +</legalnotice> + +</bookinfo> + +<chapter id="ch1"><title>Quick summary of dpkg's external interface</title> + +<section id="control"><title>Control files</title> +<para> +The basic dpkg package control file supports the following major features:- +</para> +<itemizedlist> +<listitem> +<para> +5 types of dependencies:- +</para> +<itemizedlist> +<listitem> +<para> +Pre-Depends, which must be satisfied before a package may be unpacked +</para> +</listitem> +<listitem> +<para> +Depends, which must be satisfied before a package may be configured +</para> +</listitem> +<listitem> +<para> +Recommends, to specify a package which if not installed may severely limit the +usefulness of the package +</para> +</listitem> +<listitem> +<para> +Suggests, to specify a package which may increase the productivity of the +package +</para> +</listitem> +<listitem> +<para> +Conflicts, to specify a package which must NOT be installed in order for the +package to be configured +</para> +</listitem> +<listitem> +<para> +Breaks, to specify a package which is broken by the package and which should +therefore not be configured while broken +</para> +</listitem> +</itemizedlist> +<para> +Each of these dependencies can specify a version and a depedency on that +version, for example "<= 0.5-1", "== 2.7.2-1", etc. The comparators +available are:- +</para> +<itemizedlist> +<listitem> +<para> +"<<" - less than +</para> +</listitem> +<listitem> +<para> +"<=" - less than or equal to +</para> +</listitem> +<listitem> +<para> +">>" - greater than +</para> +</listitem> +<listitem> +<para> +">=" - greater than or equal to +</para> +</listitem> +<listitem> +<para> +"==" - equal to +</para> +</listitem> +</itemizedlist> +</listitem> +<listitem> +<para> +The concept of "virtual packages", which many other packages may provide, +using the Provides mechanism. An example of this is the "httpd" virtual +package, which all web servers should provide. Virtual package names may be +used in dependency headers. However, current policy is that virtual packages +do not support version numbers, so dependencies on virtual packages with +versions will always fail. +</para> +</listitem> +<listitem> +<para> +Several other control fields, such as Package, Version, Description, Section, +Priority, etc., which are mainly for classification purposes. The package +name must consist entirely of lowercase characters, plus the characters '+', +'-', and '.'. Fields can extend across multiple lines - on the second and +subsequent lines, there is a space at the beginning instead of a field name +and a ':'. Empty lines must consist of the text " .", which will be ignored, +as will the initial space for other continuation lines. This feature is +usually only used in the Description field. +</para> +</listitem> +</itemizedlist> +</section> + +<section id="s1.2"><title>The dpkg status area</title> +<para> +The "dpkg status area" is the term used to refer to the directory where dpkg +keeps its various status files (GNU would have you call it the dpkg shared +state directory). This is always, on Debian systems, /var/lib/dpkg. However, +the default directory name should not be hard-coded, but #define'd, so that +alteration is possible (it is available via configure in dpkg 1.4.0.9 and +above). Of course, in a library, code should be allowed to override the +default directory, but the default should be part of the library (so that +the user may change the dpkg admin dir simply by replacing the library). +</para> +<para> +Dpkg keeps a variety of files in its status area. These are discussed later +on in this document, but a quick summary of the files is here:- +</para> +<itemizedlist> +<listitem> +<para> +available - this file contains a concatenation of control information from all +the packages which dpkg knows about. This is updated using the dpkg commands +"--update-avail <file>", "--merge-avail <file>", and +"--clear-avail". +</para> +</listitem> +<listitem> +<para> +status - this file contains information on the following things for every +package:- +</para> +<itemizedlist> +<listitem> +<para> +Whether it is installed, not installed, unpacked, removed, failed +configuration, or half-installed (deconfigured in favour of another package). +</para> +</listitem> +<listitem> +<para> +Whether it is selected as install, hold, remove, or purge. +</para> +</listitem> +<listitem> +<para> +If it is "ok" (no installation problems), or "not-ok". +</para> +</listitem> +<listitem> +<para> +It usually also contains the section and priority (so that dselect may classify +packages not in available) +</para> +</listitem> +<listitem> +<para> +For packages which did not initially appear in the "available" file when they +were installed, the other control information for them. +</para> +</listitem> +</itemizedlist> +<para> +The exact format for the "Status:" field is: +</para> +<screen> + Status: Want Flag Status +</screen> +<para> +Where <replaceable>Want</replaceable> may be one of +<emphasis>unknown</emphasis>, <emphasis>install</emphasis>, +<emphasis>hold</emphasis>, <emphasis>deinstall</emphasis>, +<emphasis>purge</emphasis>. <replaceable>Flag</replaceable> may +be one of <emphasis>ok</emphasis>, <emphasis>reinstreq</emphasis>, +<emphasis>hold</emphasis>, +<emphasis>hold-reinstreq</emphasis>. <replaceable>Status</replaceable> may +be one of <emphasis>not-installed</emphasis>, <emphasis>unpacked</emphasis>, +<emphasis>half-configured</emphasis>, <emphasis>installed</emphasis>, +<emphasis>half-installed</emphasis> <emphasis>config-files</emphasis>, +<emphasis>post-inst-failed</emphasis>, <emphasis>removal-failed</emphasis>. +The states are as follows:- +</para> +<variablelist> +<varlistentry> +<term>not-installed</term> +<listitem> +<para> +No files are installed from the package, it has no config files left, it +uninstalled cleanly if it ever was installed. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>unpacked</term> +<listitem> +<para> +The basic files have been unpacked (and are listed in +/var/lib/dpkg/info/[package].list. There are config files present, but the +postinst script has _NOT_ been run. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>half-configured</term> +<listitem> +<para> +The package was installed and unpacked, but the postinst script failed in some +way. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>installed</term> +<listitem> +<para> +All files for the package are installed, and the configuration was also +successful. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>half-installed</term> +<listitem> +<para> +An attempt was made to remove the packagem but there was a failure in the +prerm script. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>config-files</term> +<listitem> +<para> +The package was "removed", not "purged". The config files are left, but +nothing else. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>post-inst-failed</term> +<listitem> +<para> +Old name for half-configured. Do not use. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>removal-failed</term> +<listitem> +<para> +Old name for half-installed. Do not use. +</para> +</listitem> +</varlistentry> +</variablelist> +<para> +The two last items are only left in dpkg for compatibility - they are +understood by it, but never written out in this form. +</para> +<para> +Please see the dpkg source code, <literal>lib/parshelp.c</literal>, +<emphasis>statusinfos</emphasis>, <emphasis>eflaginfos</emphasis> and +<emphasis>wantinfos</emphasis> for more details. +</para> +</listitem> +<listitem> +<para> +info - this directory contains files from the control archive of every +package currently installed. They are installed with a prefix of +"<packagename>.". In addition to this, it also contains a file +called <package>.list for every package, which contains a list +of files. Note also that the control file is not copied into here; it +is instead found as part of status or available. +</para> +</listitem> +<listitem> +<para> +methods - this directory is reserved for "method"-specific files - each +"method" has a subdirectory underneath this directory (or at least, +it can have). In addition, there is another subdirectory "mnt", where +misc. filesystems (floppies, CD-ROMs, etc.) are mounted. +</para> +</listitem> +<listitem> +<para> +alternatives - directory used by the "update-alternatives" program. It +contains one file for each "alternatives" interface, which contains +information about all the needed symlinked files for each alternative. +</para> +</listitem> +<listitem> +<para> +diversions - file used by the "dpkg-divert" program. Each diversion takes +three lines. The first is the package name (or ":" for user diversion), the +second the original filename, and the third the diverted filename. +</para> +</listitem> +<listitem> +<para> +updates - directory used internally by dpkg. This is discussed later, in the +section <xref linkend="updates"/>. +</para> +</listitem> +<listitem> +<para> +parts - temporary directory used by dpkg-split +</para> +</listitem> +</itemizedlist> +</section> + +<section id="s1.3"><title>The dpkg library files</title> +<para> +These files are installed under /usr/lib/dpkg (usually), but +/usr/local/lib/dpkg is also a possibility (as Debian policy dictates). Under +this directory, there is a "methods" subdirectory. The methods subdirectory in +turn contains any number of subdirectories for each general method processor +(note that one set of method scripts can, and is, used for more than one of +the methods listed under dselect). +</para> +<para> +The following files may be found in each of these subdirectories:- +</para> +<itemizedlist> +<listitem> +<para> +names - One line per method, two-digit priority to appear on menu at +beginning, followed by a space, the name, and then another space and +the short description. +</para> +</listitem> +<listitem> +<para> +desc.<name> - Contains the long description displayed by dselect +when the cursor is put over the <name> method. +</para> +</listitem> +<listitem> +<para> +setup - Script or program which sets up the initial values to be used +by this method. Called with first argument as the status area directory +(/var/lib/dpkg), second argument as the name of the method (as in the +directory name), and the third argument as the option (as in the names file). +</para> +</listitem> +<listitem> +<para> +install - Script/program called when the "install" option of dselect is run +with this method. Same arguments as for setup. +</para> +</listitem> +<listitem> +<para> +update - Script/program called when the "update" option of dselect is +run. Same arguments as for setup/install. +</para> +</listitem> +</itemizedlist> +</section> + +<section id="s1.4"><title>The "dpkg" command-line utility</title> + +<section id="s1.4.1"><title>"Documented" command-line interfaces</title> +<para> +As yet unwritten. You can refer to the other manuals for now. See +<citerefentry><refentrytitle>dpkg</refentrytitle><manvolnum>8</manvolnum></citerefentry>. +</para> +</section> + +<section id="s1.4.2"><title>Environment variables which dpkg responds to</title> +<itemizedlist> +<listitem> +<para> +DPKG_NO_TSTP - if set to a non-null value, this variable causes dpkg to run a +child shell process instead of sending itself a SIGTSTP, when the user selects +to background the dpkg process when it asks about conffiles. +</para> +</listitem> +<listitem> +<para> +SHELL - used to determine which shell to run in the case when DPKG_NO_TSTP +is set. +</para> +</listitem> +<listitem> +<para> +CC - used as the C compiler to call to determine the target architecture. The +default is "gcc". +</para> +</listitem> +<listitem> +<para> +PATH - dpkg checks that it can find at least the following files in the path +when it wants to run package installation scripts, and gives an error if it +cannot find all of them:- +</para> +<itemizedlist> +<listitem> +<para> +ldconfig +</para> +</listitem> +<listitem> +<para> +start-stop-daemon +</para> +</listitem> +<listitem> +<para> +install-info +</para> +</listitem> +<listitem> +<para> +update-rc.d +</para> +</listitem> +</itemizedlist> +</listitem> +</itemizedlist> +</section> + +<section id="s1.4.3"><title>Assertions</title> +<para> +The dpkg utility itself is required for quite a number of packages, even if +they have been installed with a tool totally separate from dpkg. The reason +for this is that some packages, in their pre-installation scripts, check that +your version of dpkg supports certain features. This was broken from the +start, and it should have actually been a control file header "Dpkg-requires", +or similar. What happens is that the configuration scripts will abort or +continue according to the exit code of a call to dpkg, which will stop them +from being wrongly configured. +</para> +<para> +These special command-line options, which simply return as true or false are +all prefixed with "--assert-". Here is a list of them (without the prefix):- +</para> +<itemizedlist> +<listitem> +<para> +support-predepends - Returns success or failure according to whether a version +of dpkg which supports predepends properly (1.1.0 or above) is installed, +according to the database. +</para> +</listitem> +<listitem> +<para> +working-epoch - Return success or failure according to whether a version of +dpkg which supports epochs in version properly (1.4.0.7 or above) is installed, +according to the database. +</para> +</listitem> +</itemizedlist> +<para> +Both these options check the status database to see what version of the +"dpkg" package is installed, and check it against a known working version. +</para> +</section> + +<section id="s1.4.4"><title>--predep-package</title> +<para> +This strange option is described as follows in the source code: +</para> +<screen> +/* Print a single package which: + * (a) is the target of one or more relevant predependencies. + * (b) has itself no unsatisfied pre-dependencies. + * If such a package is present output is the Packages file entry, + * which can be massaged as appropriate. + * Exit status: + * 0 = a package printed, OK + * 1 = no suitable package available + * 2 = error + */ +</screen> +<para> +On further inspection of the source code, it appears that what is does is +this:- +</para> +<itemizedlist> +<listitem> +<para> +Looks at the packages in the database which are selected as "install", +and are installed. +</para> +</listitem> +<listitem> +<para> +It then looks at the Pre-Depends information for each of these packages +from the available file. When it find a package for which any of the +pre-dependencies are not satisfied, it breaks from the loop through the +packages. +</para> +</listitem> +<listitem> +<para> +It then looks through the unsatisfied pre-dependencies, and looks for +packages which would satisfy this pre-dependency, stopping on the first +it finds. If it finds none, it bombs out with an error. +</para> +</listitem> +<listitem> +<para> +It then continues this for every dependency of the initial package. +</para> +</listitem> +</itemizedlist> +<para> +Eventually, it writes out the record of all the packages to satisfy the +pre-dependencies. This is used by the disk method to make sure that its +dependency ordering is correct. What happens is that all pre-depending +packages are first installed, then it runs dpkg -iGROEB on the directory, +which installs in the order package files are found. Since pre-dependencies +mean that a package may not even be unpacked unless they are satisfied, it +is necessary to do this (usually, since all the package files are unpacked +in one phase, the configured in another, this is not needed). +</para> +</section> + +</section> + +</chapter> + +<chapter id="ch2"><title>dpkg-deb and .deb file internals</title> +<para> +This chapter describes the internals to the "dpkg-deb" tool, which is used by +"dpkg" as a back-end. dpkg-deb has its own tar extraction functions, which is +the source of many problems, as it does not support long filenames, using +extension blocks. +</para> + +<section id="s2.1"><title>The .deb archive format</title> +<para> +The main principal of the new-format Debian archive (I won't describe the old +format - for that have a look at deb-old.5), is that the archive really is an +archive - as used by "ar" and friends. However, dpkg-deb uses this format +internally, rather than calling "ar". Inside this archive, there are usually +the following members:- +</para> +<itemizedlist> +<listitem> +<para> +debian-binary +</para> +</listitem> +<listitem> +<para> +control.tar.gz +</para> +</listitem> +<listitem> +<para> +data.tar.gz +</para> +</listitem> +</itemizedlist> +<para> +The debian-binary member consists simply of the string "2.0", indicating +the format version. control.tar.gz contains the control files (and scripts), +and the data.tar.gz contains the actual files to populate the filesystem +with. Both tarfiles extract straight into the current directory. Information +on the tar formats can be found in the GNU tar info page. Since dpkg-deb +calls "tar -cf" to build packages, the Debian packages use the GNU extensions. +</para> +</section> + +<section id="s2.2"><title>The dpkg-deb command-line</title> +<para> +dpkg-deb documents itself thoroughly with its '--help' command-line +option. However, I am including a reference to these for +completeness. dpkg-deb supports the following options:- +</para> +<itemizedlist> +<listitem> +<para> +--build (-b) <dir> - builds a .deb archive, takes a directory which +contains all the files as an argument. Note that the directory +<dir>/DEBIAN will be packed separately into the control archive. +</para> +</listitem> +<listitem> +<para> +--contents (-c) <debfile> - Lists the contents of the "data.tar.gz" +member. +</para> +</listitem> +<listitem> +<para> +--control (-e) <debfile> - Extracts the control archive into a directory +called DEBIAN. Alternatively, with another argument, it will extract it into a +different directory. +</para> +</listitem> +<listitem> +<para> +--info (-I) <debfile> - Prints the contents of the "control" file in the +control archive to stdout. Alternatively, giving it other arguments will cause +it to print the contents of those files instead. +</para> +</listitem> +<listitem> +<para> +--field (-f) <debfile> <field> ... - Prints any number of fields +from the "control" file. Giving it extra arguments limits the fields it prints +to only those specified. With no command-line arguments other than a filename, +it is equivalent to -I and just the .deb filename. +</para> +</listitem> +<listitem> +<para> +--extract (-x) <debfile> <dir> - Extracts the data archive of a +debian package under the directory <dir>. +</para> +</listitem> +<listitem> +<para> +--vextract (-X) <debfile> <dir> - Same as --extract, except it +is equivalent of giving tar the '-v' option - it prints the filenames as it +extracts them. +</para> +</listitem> +<listitem> +<para> +--fsys-tarfile <debfile> - This option outputs a gunzip'd version of +data.tar.gz to stdout. +</para> +</listitem> +<listitem> +<para> +--new - sets the archive format to be used to the new Debian format +</para> +</listitem> +<listitem> +<para> +--old - sets the archive format to be used to the old Debian format +</para> +</listitem> +<listitem> +<para> +--debug - Tells dpkg-deb to produce debugging output +</para> +</listitem> +<listitem> +<para> +--nocheck - Tells dpkg-deb not to check the sanity of the control file +</para> +</listitem> +<listitem> +<para> +--help (-h) - Gives a help message +</para> +</listitem> +<listitem> +<para> +--version - Shows the version number +</para> +</listitem> +<listitem> +<para> +--licence/--license (UK/US spellings) - Shows a brief outline of the GPL +</para> +</listitem> +</itemizedlist> + +<section id="s2.2.1"><title>Internal checks used by dpkg-deb when building packages</title> +<para> +Here is a list of the internal checks used by dpkg-deb when building +packages. It is in the order they are done. +</para> +<itemizedlist> +<listitem> +<para> +First, the output Debian archive argument, if it is given, is checked using +stat. If it is a directory, an internal flag is set. This check is only made +if the archive name is specified explicitly on the command-line. If the +argument was not given, the default is the directory name, with ".deb" +appended. +</para> +</listitem> +<listitem> +<para> +Next, the control file is checked, unless the --nocheck flag was specified on +the command-line. dpkg-deb will bomb out if the second argument to --build was +a directory, and --nocheck was specified. Note that dpkg-deb will not be able +to determine the name of the package in this case. In the control file, the +following things are checked:- +</para> +<itemizedlist> +<listitem> +<para> +The package name is checked to see if it contains any invalid characters (see +<xref linkend="control"/> for this). +</para> +</listitem> +<listitem> +<para> +The priority field is checked to see if it uses standard values, and +user-defined values are warned against. However, note that this check is now +redundant, since the control file no longer contains the priority - the +changes file now does this. +</para> +</listitem> +<listitem> +<para> +The control file fields are then checked against the standard list of fields +which appear in control files, and any "user-defined" fields are reported as +warnings. +</para> +</listitem> +<listitem> +<para> +dpkg-deb then checks that the control file contains a valid version number. +</para> +</listitem> +</itemizedlist> +</listitem> +<listitem> +<para> +After this, in the case where a directory was specified to build the .deb file +in, the filename is created as "directory/pkg_ver.deb" or +"directory/pkg_ver_arch.deb", depending on whether the control file contains +an architecture field. +</para> +</listitem> +<listitem> +<para> +Next, dpkg-deb checks for the <dir>/DEBIAN directory. It complains if it +doesn't exist, or if it has permissions < 0755, or > 0775. +</para> +</listitem> +<listitem> +<para> +It then checks that all the files in this subdir are either symlinks or plain +files, and have permissions between 0555 and 0775. +</para> +</listitem> +<listitem> +<para> +The conffiles file is then checked to see if the filenames are too +long. Warnings are produced for each that is. After this, it checks +that the package provides initial copies of each of these conffiles, +and that they are all plain files. +</para> +</listitem> +</itemizedlist> +</section> + +</section> + +</chapter> + +<chapter id="ch3"><title>dpkg internals</title> +<para> +This chapter describes the internals of dpkg itself. Although the low-level +formats are quite simple, what dpkg does in certain cases often does not make +sense. +</para> + +<section id="updates"><title>Updates</title> +<para> +This describes the /var/lib/dpkg/updates directory. The function of this +directory is somewhat strange, and seems only to be used internally. A +function called cleanupdates is called whenever the database is scanned. This +function in turn uses +<citerefentry><refentrytitle>scandir</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +to sort the files in this directory. Files who names do not consist entirely +of digits are discarded. dpkg also causes a fatal error if any of the +filenames are different lengths. +</para> +<para> +After having scanned the directory, dpkg in turn parses each file the same way +it parses the status file (they are sorted by the scandir to be in numerical +order). After having done this, it then writes the status information back to +the "status" file, and removes all the "updates" files. +</para> +<para> +These files are created internally by dpkg's "checkpoint" function, and are +cleaned up when dpkg exits cleanly. +</para> +<para> +Juding by the use of the updates directory I would call it a Journal. Inorder +to efficiently ensure the complete integrity of the status file dpkg will +"checkpoint" or journal all of it's activities in the updates directory. By +merging the contents of the updates directory (in order!!) against the original +status file it can get the precise current state of the system, even in the +event of a system failure while dpkg is running. +</para> +<para> +The other option would be to sync-rewrite the status file after each operation, +which would kill performance. +</para> +<para> +It is very important that any program that uses the status file abort if the +updates directory is not empty! The user should be informed to run dpkg +manually (what options though??) to correct the situation. +</para> +</section> + +<section id="s3.2"><title>What happens when dpkg reads the database</title> +<para> +First, the status file is read. This gives dpkg an initial idea of the +packages that are there. Next, the updates files are read in, overriding the +status file, and if necessary, the status file is re-written, and updates files +are removed. Finally, the available file is read. The available file is read +with flags which preclude dpkg from updating any status information from it, +though - installed version, etc., and is also told to record that the packages +it reads this time are available, not installed. +</para> +<para> +More information on updates is given above. +</para> +</section> + +<section id="s3.3"><title>How dpkg compares version numbers</title> +<para> +Version numbers consist of three parts: the epoch, the upstream version, and +the Debian revision. Dpkg compares these parts in that order. If the epochs +are different, it returns immediately, and so on. +</para> +<para> +However, the important part is how it compares the versions which are +essentially stored as just strings. These are compared in two distinct +parts: those consisting of numerical characters (which are evaluated, and +then compared), and those consisting of other characters. When comparing +non-numerical parts, they are compared as the character values (ASCII), +but non-alphabetical characters are considered "greater than" alphabetical +ones. Also note that longer strings (after excluding differences where +numerical values are equal) are considered "greater than" shorter ones. +</para> +<para> +Here are a few examples of how these rules apply:- +</para> +<screen> +15 > 10 +0010 == 10 + +d.r > dsr +32.d.r == 0032.d.r +d.rnr < d.rnrn +</screen> +</section> + +</chapter> + +</book> diff --git a/doc/dpkg-tech.sgml b/doc/dpkg-tech.sgml deleted file mode 100644 index ce0c5fa83..000000000 --- a/doc/dpkg-tech.sgml +++ /dev/null @@ -1,511 +0,0 @@ -<!doctype debiandoc PUBLIC "-//DebianDoc//DTD DebianDoc//EN"> -<book> -<title>dpkg technical manual</title> - -<author>Tom Lees <email>tom@lpsg.demon.co.uk</email></author> -<version>$Id: dpkg-tech.sgml,v 1.3 2003/02/12 15:05:45 doogie Exp $</version> - -<abstract> -This document describes the minimum necessary workings for the APT dselect -replacement. It gives an overall specification of what its external interface -must look like for compatibility, and also gives details of some internal -quirks. -</abstract> - -<copyright> -Copyright © Tom Lees, 1997. -<p> -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. - -<p> -For more details, on Debian systems, see the file -/usr/share/common-licenses/GPL for the full license. -</copyright> - -<toc sect> - -<chapt>Quick summary of dpkg's external interface -<sect id="control">Control files - -<p> -The basic dpkg package control file supports the following major features:- - -<list> -<item>5 types of dependencies:- - <list> - <item>Pre-Depends, which must be satisfied before a package may be - unpacked - <item>Depends, which must be satisfied before a package may be - configured - <item>Recommends, to specify a package which if not installed may - severely limit the usefulness of the package - <item>Suggests, to specify a package which may increase the - productivity of the package - <item>Conflicts, to specify a package which must NOT be installed - in order for the package to be configured - <item>Breaks, to specify a package which is broken by the - package and which should therefore not be configured while broken - </list> -Each of these dependencies can specify a version and a depedency on that -version, for example "<= 0.5-1", "== 2.7.2-1", etc. The comparators available -are:- - <list> - <item>"<<" - less than - <item>"<=" - less than or equal to - <item>">>" - greater than - <item>">=" - greater than or equal to - <item>"==" - equal to - </list> -<item>The concept of "virtual packages", which many other packages may provide, -using the Provides mechanism. An example of this is the "httpd" virtual package, -which all web servers should provide. Virtual package names may be used in -dependency headers. However, current policy is that virtual packages do not -support version numbers, so dependencies on virtual packages with versions -will always fail. -<item>Several other control fields, such as Package, Version, Description, -Section, Priority, etc., which are mainly for classification purposes. The -package name must consist entirely of lowercase characters, plus the characters -'+', '-', and '.'. Fields can extend across multiple lines - on the second -and subsequent lines, there is a space at the beginning instead of a field -name and a ':'. Empty lines must consist of the text " .", which will be -ignored, as will the initial space for other continuation lines. This feature -is usually only used in the Description field. -</list> - -<sect>The dpkg status area - -<p> -The "dpkg status area" is the term used to refer to the directory where dpkg -keeps its various status files (GNU would have you call it the dpkg shared -state directory). This is always, on Debian systems, /var/lib/dpkg. However, -the default directory name should not be hard-coded, but #define'd, so that -alteration is possible (it is available via configure in dpkg 1.4.0.9 and -above). Of course, in a library, code should be allowed to override the -default directory, but the default should be part of the library (so that -the user may change the dpkg admin dir simply by replacing the library). - -<p> -Dpkg keeps a variety of files in its status area. These are discussed later -on in this document, but a quick summary of the files is here:- - -<list> -<item>available - this file contains a concatenation of control information -from all the packages which dpkg knows about. This is updated using the dpkg -commands "--update-avail <file>", "--merge-avail <file>", and -"--clear-avail". -<item>status - this file contains information on the following things for -every package:- - <list> - <item>Whether it is installed, not installed, unpacked, removed, - failed configuration, or half-installed (deconfigured in - favour of another package). - <item>Whether it is selected as install, hold, remove, or purge. - <item>If it is "ok" (no installation problems), or "not-ok". - <item>It usually also contains the section and priority (so that - dselect may classify packages not in available) - <item>For packages which did not initially appear in the "available" - file when they were installed, the other control information - for them. - </list> - <p> - The exact format for the "Status:" field is: - <example> - Status: Want Flag Status - </example> - Where <var>Want</> may be one of <em>unknown</>, <em>install</>, - <em>hold</>, <em>deinstall</>, <em>purge</>. <var>Flag</> - may be one of <em>ok</>, <em>reinstreq</>, <em>hold</>, - <em>hold-reinstreq</>. - <var>Status</> may be one of <em>not-installed</>, <em>unpacked</>, - <em>half-configured</>, <em>installed</>, <em>half-installed</> - <em>config-files</>, <em>post-inst-failed</>, <em>removal-failed</>. - The states are as follows:- - <taglist> - <tag>not-installed - <item>No files are installed from the package, it has no config files - left, it uninstalled cleanly if it ever was installed. - <tag>unpacked - <item>The basic files have been unpacked (and are listed in - /var/lib/dpkg/info/[package].list. There are config files present, - but the postinst script has _NOT_ been run. - <tag>half-configured - <item>The package was installed and unpacked, but the postinst script - failed in some way. - <tag>installed - <item>All files for the package are installed, and the configuration - was also successful. - <tag>half-installed - <item>An attempt was made to remove the packagem but there was a failure - in the prerm script. - <tag>config-files - <item>The package was "removed", not "purged". The config files are left, - but nothing else. - <tag>post-inst-failed - <item>Old name for half-configured. Do not use. - <tag>removal-failed - <item>Old name for half-installed. Do not use. - </taglist> - The two last items are only left in dpkg for compatibility - they are - understood by it, but never written out in this form. - - <p> - Please see the dpkg source code, <tt>lib/parshelp.c</tt>, - <em>statusinfos</>, <em>eflaginfos</> and <em>wantinfos</> for more - details. - -<item>info - this directory contains files from the control archive of every -package currently installed. They are installed with a prefix of "<packagename>.". -In addition to this, it also contains a file called <package>.list for every -package, which contains a list of files. Note also that the control file is -not copied into here; it is instead found as part of status or available. -<item>methods - this directory is reserved for "method"-specific files - each -"method" has a subdirectory underneath this directory (or at least, it can -have). In addition, there is another subdirectory "mnt", where misc. -filesystems (floppies, CD-ROMs, etc.) are mounted. -<item>alternatives - directory used by the "update-alternatives" program. It -contains one file for each "alternatives" interface, which contains information -about all the needed symlinked files for each alternative. -<item>diversions - file used by the "dpkg-divert" program. Each diversion takes -three lines. The first is the package name (or ":" for user diversion), the -second the original filename, and the third the diverted filename. -<item>updates - directory used internally by dpkg. This is discussed later, -in the section <ref id="updates">. -<item>parts - temporary directory used by dpkg-split -</list> - -<sect>The dpkg library files - -<p> -These files are installed under /usr/lib/dpkg (usually), but -/usr/local/lib/dpkg is also a possibility (as Debian policy dictates). Under -this directory, there is a "methods" subdirectory. The methods subdirectory -in turn contains any number of subdirectories for each general method -processor (note that one set of method scripts can, and is, used for more than -one of the methods listed under dselect). - -<p> -The following files may be found in each of these subdirectories:- - -<list> -<item>names - One line per method, two-digit priority to appear on menu -at beginning, followed by a space, the name, and then another space and the -short description. -<item>desc.<name> - Contains the long description displayed by dselect -when the cursor is put over the <name> method. -<item>setup - Script or program which sets up the initial values to be used -by this method. Called with first argument as the status area directory -(/var/lib/dpkg), second argument as the name of the method (as in the directory -name), and the third argument as the option (as in the names file). -<item>install - Script/program called when the "install" option of dselect is -run with this method. Same arguments as for setup. -<item>update - Script/program called when the "update" option of dselect is -run. Same arguments as for setup/install. -</list> - -<sect>The "dpkg" command-line utility - -<sect1>"Documented" command-line interfaces - -<p> -As yet unwritten. You can refer to the other manuals for now. See -<manref name="dpkg" section="8">. - -<sect1>Environment variables which dpkg responds to - -<p> -<list> -<item>DPKG_NO_TSTP - if set to a non-null value, this variable causes dpkg to -run a child shell process instead of sending itself a SIGTSTP, when the user -selects to background the dpkg process when it asks about conffiles. -<item>SHELL - used to determine which shell to run in the case when -DPKG_NO_TSTP is set. -<item>CC - used as the C compiler to call to determine the target architecture. -The default is "gcc". -<item>PATH - dpkg checks that it can find at least the following files in the -path when it wants to run package installation scripts, and gives an error if -it cannot find all of them:- - <list> - <item>ldconfig - <item>start-stop-daemon - <item>install-info - <item>update-rc.d - </list> -</list> - -<sect1>Assertions - -<p> -The dpkg utility itself is required for quite a number of packages, even if -they have been installed with a tool totally separate from dpkg. The reason for -this is that some packages, in their pre-installation scripts, check that your -version of dpkg supports certain features. This was broken from the start, and -it should have actually been a control file header "Dpkg-requires", or similar. -What happens is that the configuration scripts will abort or continue according -to the exit code of a call to dpkg, which will stop them from being wrongly -configured. - -<p> -These special command-line options, which simply return as true or false are -all prefixed with "--assert-". Here is a list of them (without the prefix):- - -<list> -<item>support-predepends - Returns success or failure according to whether -a version of dpkg which supports predepends properly (1.1.0 or above) is -installed, according to the database. -<item>working-epoch - Return success or failure according to whether a version -of dpkg which supports epochs in version properly (1.4.0.7 or above) is -installed, according to the database. -</list> - -<p> -Both these options check the status database to see what version of the "dpkg" -package is installed, and check it against a known working version. - -<sect1>--predep-package - -<p> -This strange option is described as follows in the source code: - -<example> -/* Print a single package which: - * (a) is the target of one or more relevant predependencies. - * (b) has itself no unsatisfied pre-dependencies. - * If such a package is present output is the Packages file entry, - * which can be massaged as appropriate. - * Exit status: - * 0 = a package printed, OK - * 1 = no suitable package available - * 2 = error - */ -</example> - -<p> -On further inspection of the source code, it appears that what is does is -this:- - -<list> -<item>Looks at the packages in the database which are selected as "install", -and are installed. -<item>It then looks at the Pre-Depends information for each of these packages -from the available file. When it find a package for which any of the -pre-dependencies are not satisfied, it breaks from the loop through the packages. -<item>It then looks through the unsatisfied pre-dependencies, and looks for -packages which would satisfy this pre-dependency, stopping on the first it -finds. If it finds none, it bombs out with an error. -<item>It then continues this for every dependency of the initial package. -</list> - -Eventually, it writes out the record of all the packages to satisfy the -pre-dependencies. This is used by the disk method to make sure that its -dependency ordering is correct. What happens is that all pre-depending -packages are first installed, then it runs dpkg -iGROEB on the directory, -which installs in the order package files are found. Since pre-dependencies -mean that a package may not even be unpacked unless they are satisfied, it is -necessary to do this (usually, since all the package files are unpacked in one -phase, the configured in another, this is not needed). - -<chapt>dpkg-deb and .deb file internals - -<p> -This chapter describes the internals to the "dpkg-deb" tool, which is used -by "dpkg" as a back-end. dpkg-deb has its own tar extraction functions, which -is the source of many problems, as it does not support long filenames, using -extension blocks. - -<sect>The .deb archive format - -<p> -The main principal of the new-format Debian archive (I won't describe the old -format - for that have a look at deb-old.5), is that the archive really is -an archive - as used by "ar" and friends. However, dpkg-deb uses this format -internally, rather than calling "ar". Inside this archive, there are usually -the following members:- - -<list> -<item>debian-binary -<item>control.tar.gz -<item>data.tar.gz -</list> - -<p> -The debian-binary member consists simply of the string "2.0", indicating the -format version. control.tar.gz contains the control files (and scripts), and -the data.tar.gz contains the actual files to populate the filesystem with. -Both tarfiles extract straight into the current directory. Information on the -tar formats can be found in the GNU tar info page. Since dpkg-deb calls -"tar -cf" to build packages, the Debian packages use the GNU extensions. - -<sect>The dpkg-deb command-line - -<p> -dpkg-deb documents itself thoroughly with its '--help' command-line option. -However, I am including a reference to these for completeness. dpkg-deb -supports the following options:- - -<list> -<item>--build (-b) <dir> - builds a .deb archive, takes a directory which -contains all the files as an argument. Note that the directory -<dir>/DEBIAN will be packed separately into the control archive. -<item>--contents (-c) <debfile> - Lists the contents of the "data.tar.gz" -member. -<item>--control (-e) <debfile> - Extracts the control archive into a -directory called DEBIAN. Alternatively, with another argument, it will extract -it into a different directory. -<item>--info (-I) <debfile> - Prints the contents of the "control" file -in the control archive to stdout. Alternatively, giving it other arguments will -cause it to print the contents of those files instead. -<item>--field (-f) <debfile> <field> ... - Prints any number of -fields from the "control" file. Giving it extra arguments limits the fields it -prints to only those specified. With no command-line arguments other than a -filename, it is equivalent to -I and just the .deb filename. -<item>--extract (-x) <debfile> <dir> - Extracts the data archive -of a debian package under the directory <dir>. -<item>--vextract (-X) <debfile> <dir> - Same as --extract, except -it is equivalent of giving tar the '-v' option - it prints the filenames as -it extracts them. -<item>--fsys-tarfile <debfile> - This option outputs a gunzip'd version -of data.tar.gz to stdout. -<item>--new - sets the archive format to be used to the new Debian format -<item>--old - sets the archive format to be used to the old Debian format -<item>--debug - Tells dpkg-deb to produce debugging output -<item>--nocheck - Tells dpkg-deb not to check the sanity of the control file -<item>--help (-h) - Gives a help message -<item>--version - Shows the version number -<item>--licence/--license (UK/US spellings) - Shows a brief outline of the GPL -</list> - -<sect1>Internal checks used by dpkg-deb when building packages - -<p> -Here is a list of the internal checks used by dpkg-deb when building packages. -It is in the order they are done. - -<list> -<item>First, the output Debian archive argument, if it is given, is checked -using stat. If it is a directory, an internal flag is set. This check is only -made if the archive name is specified explicitly on the command-line. If the -argument was not given, the default is the directory name, with ".deb" -appended. -<item>Next, the control file is checked, unless the --nocheck flag was -specified on the command-line. dpkg-deb will bomb out if the second argument -to --build was a directory, and --nocheck was specified. Note that dpkg-deb -will not be able to determine the name of the package in this case. In the -control file, the following things are checked:- - <list> - <item>The package name is checked to see if it contains any invalid - characters (see <ref id="control"> for this). - <item>The priority field is checked to see if it uses standard values, - and user-defined values are warned against. However, note that this - check is now redundant, since the control file no longer contains - the priority - the changes file now does this. - <item>The control file fields are then checked against the standard - list of fields which appear in control files, and any "user-defined" - fields are reported as warnings. - <item>dpkg-deb then checks that the control file contains a valid - version number. - </list> -<item>After this, in the case where a directory was specified to build the -.deb file in, the filename is created as "directory/pkg_ver.deb" or -"directory/pkg_ver_arch.deb", depending on whether the control file contains -an architecture field. -<item>Next, dpkg-deb checks for the <dir>/DEBIAN directory. It complains -if it doesn't exist, or if it has permissions < 0755, or > 0775. -<item>It then checks that all the files in this subdir are either symlinks -or plain files, and have permissions between 0555 and 0775. -<item>The conffiles file is then checked to see if the filenames are too -long. Warnings are produced for each that is. After this, it checks that -the package provides initial copies of each of these conffiles, and that -they are all plain files. -</list> - -<chapt>dpkg internals - -<p> -This chapter describes the internals of dpkg itself. Although the low-level -formats are quite simple, what dpkg does in certain cases often does not -make sense. - -<sect id="updates">Updates - -<p> -This describes the /var/lib/dpkg/updates directory. The function of this -directory is somewhat strange, and seems only to be used internally. A function -called cleanupdates is called whenever the database is scanned. This function -in turn uses <manref name="scandir" section="3">, to sort the files in this -directory. Files who names do not consist entirely of digits are discarded. -dpkg also causes a fatal error if any of the filenames are different lengths. - -<p> -After having scanned the directory, dpkg in turn parses each file the same way -it parses the status file (they are sorted by the scandir to be in numerical -order). After having done this, it then writes the status information back -to the "status" file, and removes all the "updates" files. - -<p> -These files are created internally by dpkg's "checkpoint" function, and are -cleaned up when dpkg exits cleanly. - -<p> -Juding by the use of the updates directory I would call it a Journal. Inorder -to efficiently ensure the complete integrity of the status file dpkg will -"checkpoint" or journal all of it's activities in the updates directory. By -merging the contents of the updates directory (in order!!) against the -original status file it can get the precise current state of the system, -even in the event of a system failure while dpkg is running. - -<p> -The other option would be to sync-rewrite the status file after each -operation, which would kill performance. - -<p> -It is very important that any program that uses the status file abort if -the updates directory is not empty! The user should be informed to run dpkg -manually (what options though??) to correct the situation. - -<sect>What happens when dpkg reads the database - -<p> -First, the status file is read. This gives dpkg an initial idea of the packages -that are there. Next, the updates files are read in, overriding the status -file, and if necessary, the status file is re-written, and updates files are -removed. Finally, the available file is read. The available file is read -with flags which preclude dpkg from updating any status information from it, -though - installed version, etc., and is also told to record that the packages -it reads this time are available, not installed. - -<p> -More information on updates is given above. - -<sect>How dpkg compares version numbers - -<p> -Version numbers consist of three parts: the epoch, the upstream version, and -the Debian revision. Dpkg compares these parts in that order. If the epochs -are different, it returns immediately, and so on. - -<p> -However, the important part is how it compares the versions which are -essentially stored as just strings. These are compared in two distinct parts: -those consisting of numerical characters (which are evaluated, and then -compared), and those consisting of other characters. When comparing -non-numerical parts, they are compared as the character values (ASCII), but -non-alphabetical characters are considered "greater than" alphabetical ones. -Also note that longer strings (after excluding differences where numerical -values are equal) are considered "greater than" shorter ones. - -<p> -Here are a few examples of how these rules apply:- - -<example> -15 > 10 -0010 == 10 - -d.r > dsr -32.d.r == 0032.d.r -d.rnr < d.rnrn -</example> - -</book> 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 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- -*- DocBook -*- --> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment; +]> + +<book lang="en"> + +<title>APT Files</title> + +<bookinfo> + +<authorgroup> + <author> + <personname>Jason Gunthorpe</personname><email>jgg@debian.org</email> + </author> +</authorgroup> + +<releaseinfo>Version &apt-product-version;</releaseinfo> + +<abstract> +<para> +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. +</para> +</abstract> + +<copyright><year>1998-1999</year><holder>Jason Gunthorpe</holder></copyright> + +<legalnotice> +<title>License Notice</title> +<para> +"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. +</para> +<para> +For more details, on Debian systems, see the file +/usr/share/common-licenses/GPL for the full license. +</para> +</legalnotice> + +</bookinfo> + +<chapter id="ch1"><title>Introduction</title> + +<section id="s1.1"><title>General</title> +<para> +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. +</para> +<para> +The var directory structure is as follows: +</para> +<screen> + /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 +</screen> +<para> +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. +</para> +</section> + +</chapter> + +<chapter id="ch2"><title>Files</title> + +<section id="s2.1"><title>Files and fragment directories in /etc/apt</title> +<para> +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. +</para> +</section> + +<section id="s2.2"><title>Distribution Source list (sources.list)</title> +<para> +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: +</para> +<para> +<replaceable>type uri args</replaceable> +</para> +<para> +The first item, <replaceable>type</replaceable>, 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 +<emphasis>deb</emphasis> and <emphasis>deb-src</emphasis> 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. +</para> + +<section id="s2.2.1"><title>Hashing the URI</title> +<para> +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: +</para> +<screen> +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 +</screen> +<para> +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 +<emphasis>Archive Directory</emphasis> section regarding the partial sub dir +apply here as well. +</para> +</section> + +</section> + +<section id="s2.3"><title>Extended States File (extended_states)</title> +<para> +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: +</para> +<variablelist> +<varlistentry> +<term>Auto-Installed</term> +<listitem> +<para> +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 +</para> +</listitem> +</varlistentry> +</variablelist> +</section> + +<section id="s2.4"><title>Binary Package Cache (srcpkgcache.bin and pkgcache.bin)</title> +<para> +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. <emphasis>srcpkgcache.bin</emphasis> 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. +</para> +</section> + +<section id="s2.5"><title>Downloads Directory (archives)</title> +<para> +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. +</para> +<para> +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.. +</para> +</section> + +<section id="s2.6"><title>The Methods Directory (/usr/lib/apt/methods)</title> +<para> +The Methods directory is more fully described in the APT Methods interface +document. +</para> +</section> + +<section id="s2.7"><title>The Configuration File (/etc/apt/apt.conf)</title> +<para> +The configuration file (and the associated fragments directory +/etc/apt/apt.conf.d/) is described in the apt.conf manpage. +</para> +</section> + +<section id="s2.8"><title>The trusted.gpg File (/etc/apt/trusted.gpg)</title> +<para> +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. +</para> +</section> + +<section id="s2.9"><title>The Release File</title> +<para> +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. +</para> +<para> +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'. +</para> +<para> +The file is formed as the package file (RFC-822) with the following tags +defined: +</para> +<variablelist> +<varlistentry> +<term>Archive</term> +<listitem> +<para> +This is the common name we give our archives, such as +<emphasis>stable</emphasis> or <emphasis>unstable</emphasis>. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Component</term> +<listitem> +<para> +Refers to the sub-component of the archive, <emphasis>main</emphasis>, +<emphasis>contrib</emphasis> etc. Component may be omitted if there are no +components for this archive. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Version</term> +<listitem> +<para> +This is a version string with the same properties as in the Packages file. It +represents the release level of the archive. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Origin</term> +<listitem> +<para> +This specifies who is providing this archive. In the case of Debian the string +will read 'Debian'. Other providers may use their own string +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Label</term> +<listitem> +<para> +This carries the encompassing name of the distribution. For Debian proper this +field reads 'Debian'. For derived distributions it should contain their proper +name. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Architecture</term> +<listitem> +<para> +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 <emphasis>mixed</emphasis>. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>NotAutomatic</term> +<listitem> +<para> +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. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Description</term> +<listitem> +<para> +Description is used to describe the release. For instance experimental would +contain a warning that the packages have problems. +</para> +</listitem> +</varlistentry> +</variablelist> +<para> +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 +</para> +<screen> +Archive: stable +Component: main +Version: 1.3.1r6 +Origin: Debian +Label: Debian +Architecture: i386 +</screen> +<para> +This is an example of experimental, +</para> +<screen> +Archive: experimental +Version: 0 +Origin: Debian +Label: Debian +Architecture: mixed +NotAutomatic: Yes +</screen> +<para> +And unstable, +</para> +<screen> +Archive: unstable +Component: main +Version: 2.1 +Origin: Debian +Label: Debian +Architecture: i386 +</screen> +</section> + +</chapter> + + +</book> diff --git a/doc/files.sgml b/doc/files.sgml deleted file mode 100644 index 56c7f574d..000000000 --- a/doc/files.sgml +++ /dev/null @@ -1,345 +0,0 @@ -<!-- -*- mode: sgml; mode: fold -*- --> -<!doctype debiandoc PUBLIC "-//DebianDoc//DTD DebianDoc//EN"> -<book> -<title>APT Files</title> - -<author>Jason Gunthorpe <email>jgg@debian.org</email></author> -<version>$Id: files.sgml,v 1.12 2003/04/26 23:26:13 doogie Exp $</version> - -<abstract> -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. -</abstract> - -<copyright> -Copyright © Jason Gunthorpe, 1998-1999. -<p> -"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. - -<p> -For more details, on Debian systems, see the file -/usr/share/common-licenses/GPL for the full license. -</copyright> - -<toc sect> - -<chapt>Introduction -<!-- General {{{ --> -<!-- ===================================================================== --> -<sect>General - -<p> -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. - -<p> -The var directory structure is as follows: -<example> - /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 -</example> - -<p> -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. -</sect> - <!-- }}} --> - -<chapt>Files -<!-- Distribution Source List {{{ --> -<!-- ===================================================================== --> -<sect>Files and fragment directories in /etc/apt - -<p> -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. - -</sect> - -<sect>Distribution Source list (sources.list) - -<p> -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: - -<p> -<var>type uri args</var> - -<p> -The first item, <var>type</var>, 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 <em>deb</em> -and <em>deb-src</em> 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. - -<sect1>Hashing the URI -<p> -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: - -<example> -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 -</example> - -<p> -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 <em>Archive Directory</> section regarding the partial sub dir apply -here as well. -</sect1> - -</sect> - <!-- }}} --> -<!-- Extended Status {{{ --> -<!-- ===================================================================== --> -<sect>Extended States File (extended_states) - -<p> -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: - -<taglist> -<tag>Auto-Installed<item> - 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 -</taglist> -</sect> - <!-- }}} --> -<!-- Binary Package Cache {{{ --> -<!-- ===================================================================== --> -<sect>Binary Package Cache (srcpkgcache.bin and pkgcache.bin) - -<p> -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. -<em>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. -</sect> - <!-- }}} --> -<!-- Downloads Directory {{{ --> -<!-- ===================================================================== --> -<sect>Downloads Directory (archives) - -<p> -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. - -<p> -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.. -</sect> - <!-- }}} --> -<!-- The Methods Directory {{{ --> -<!-- ===================================================================== --> -<sect> The Methods Directory (/usr/lib/apt/methods) - -<p> -The Methods directory is more fully described in the APT Methods interface -document. -</sect> - <!-- }}} --> -<!-- The Configuration File {{{ --> -<!-- ===================================================================== --> -<sect> The Configuration File (/etc/apt/apt.conf) - -<p> -The configuration file (and the associated fragments directory -/etc/apt/apt.conf.d/) is described in the apt.conf manpage. -</sect> - <!-- }}} --> -<!-- The trusted.gpg File {{{ --> -<!-- ===================================================================== --> -<sect> The trusted.gpg File (/etc/apt/trusted.gpg) - -<p> -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. -</sect> - <!-- }}} --> -<!-- The Release File {{{ --> -<!-- ===================================================================== --> -<sect> The Release File - -<p> -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. - -<p> -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'. - -<p> -The file is formed as the package file (RFC-822) with the following tags -defined: - -<taglist> -<tag>Archive<item> -This is the common name we give our archives, such as <em>stable</> or -<em>unstable</>. - -<tag>Component<item> -Refers to the sub-component of the archive, <em>main</>, <em>contrib</> -etc. Component may be omitted if there are no components for this archive. - -<tag>Version<item> -This is a version string with the same properties as in the Packages file. -It represents the release level of the archive. - -<tag>Origin<item> -This specifies who is providing this archive. In the case of Debian the -string will read 'Debian'. Other providers may use their own string - -<tag>Label<item> -This carries the encompassing name of the distribution. For Debian proper -this field reads 'Debian'. For derived distributions it should contain their -proper name. - -<tag>Architecture<item> -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 <em>mixed</em>. - -<tag>NotAutomatic<item> -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. - -<tag>Description<item> -Description is used to describe the release. For instance experimental would -contain a warning that the packages have problems. -</taglist> - -<p> -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 - -<example> -Archive: stable -Component: main -Version: 1.3.1r6 -Origin: Debian -Label: Debian -Architecture: i386 -</example> - -This is an example of experimental, -<example> -Archive: experimental -Version: 0 -Origin: Debian -Label: Debian -Architecture: mixed -NotAutomatic: Yes -</example> - -And unstable, -<example> -Archive: unstable -Component: main -Version: 2.1 -Origin: Debian -Label: Debian -Architecture: i386 -</example> - -</sect> - <!-- }}} --> - -</book> diff --git a/doc/guide.dbk b/doc/guide.dbk new file mode 100644 index 000000000..e8a8ae274 --- /dev/null +++ b/doc/guide.dbk @@ -0,0 +1,560 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- -*- DocBook -*- --> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment; +]> + +<book lang="en"> + +<title>APT User's Guide</title> + +<bookinfo> + +<authorgroup> + <author> + <personname>Jason Gunthorpe</personname><email>jgg@debian.org</email> + </author> +</authorgroup> + +<releaseinfo>Version &apt-product-version;</releaseinfo> + +<abstract> +<para> +This document provides an overview of how to use the the APT package manager. +</para> +</abstract> + +<copyright><year>1998</year><holder>Jason Gunthorpe</holder></copyright> + +<legalnotice> +<title>License Notice</title> +<para> +"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. +</para> +</legalnotice> + +<legalnotice> +<para> +For more details, on Debian systems, see the file +/usr/share/common-licenses/GPL for the full license. +</para> +</legalnotice> + +</bookinfo> + +<chapter id="ch1"><title>General</title> +<para> +The APT package currently contains two sections, the APT +<command>dselect</command> method and the <command>apt-get</command> command +line user interface. Both provide a way to install and remove packages as well +as download new packages from the Internet. +</para> + +<section id="s1.1"><title>Anatomy of the Package System</title> +<para> +The Debian packaging system has a large amount of information associated with +each package to help assure that it integrates cleanly and easily into the +system. The most prominent of its features is the dependency system. +</para> +<para> +The dependency system allows individual programs to make use of shared elements +in the system such as libraries. It simplifies placing infrequently used +portions of a program in separate packages to reduce the number of things the +average user is required to install. Also, it allows for choices in mail +transport agents, X servers and so on. +</para> +<para> +The first step to understanding the dependency system is to grasp the concept +of a simple dependency. The meaning of a simple dependency is that a package +requires another package to be installed at the same time to work properly. +</para> +<para> +For instance, mailcrypt is an emacs extension that aids in encrypting email +with GPG. Without GPGP installed mailcrypt is useless, so mailcrypt has a +simple dependency on GPG. Also, because it is an emacs extension it has a +simple dependency on emacs, without emacs it is completely useless. +</para> +<para> +The other important dependency to understand is a conflicting dependency. It +means that a package, when installed with another package, will not work and +may possibly be extremely harmful to the system. As an example consider a mail +transport agent such as sendmail, exim or qmail. It is not possible to have +two mail transport agents installed because both need to listen to the network +to receive mail. Attempting to install two will seriously damage the system so +all mail transport agents have a conflicting dependency with all other mail +transport agents. +</para> +<para> +As an added complication there is the possibility for a package to pretend to +be another package. Consider that exim and sendmail for many intents are +identical, they both deliver mail and understand a common interface. Hence, +the package system has a way for them to declare that they are both +mail-transport-agents. So, exim and sendmail both declare that they provide a +mail-transport-agent and other packages that need a mail transport agent depend +on mail-transport-agent. This can add a great deal of confusion when trying to +manually fix packages. +</para> +<para> +At any given time a single dependency may be met by packages that are already +installed or it may not be. APT attempts to help resolve dependency issues by +providing a number of automatic algorithms that help in selecting packages for +installation. +</para> +</section> + +</chapter> + +<chapter id="ch2"><title>apt-get</title> +<para> +<command>apt-get</command> provides a simple way to install packages from the +command line. Unlike <command>dpkg</command>, <command>apt-get</command> does +not understand .deb files, it works with the package's proper name and can only +install .deb archives from a <emphasis>Source</emphasis>. +</para> +<para> +The first <footnote><para> If you are using an http proxy server you must set +the http_proxy environment variable first, see sources.list(5) </para> +</footnote> thing that should be done before using <command>apt-get</command> +is to fetch the package lists from the <emphasis>Sources</emphasis> so that it +knows what packages are available. This is done with <literal>apt-get +update</literal>. For instance, +</para> +<screen> +# apt-get update +Get http://ftp.de.debian.org/debian-non-US/ stable/binary-i386/ Packages +Get http://llug.sep.bnl.gov/debian/ testing/contrib Packages +Reading Package Lists... Done +Building Dependency Tree... Done +</screen> +<para> +Once updated there are several commands that can be used: +</para> +<variablelist> +<varlistentry> +<term>upgrade</term> +<listitem> +<para> +Upgrade will attempt to gently upgrade the whole system. Upgrade will never +install a new package or remove an existing package, nor will it ever upgrade a +package that might cause some other package to break. This can be used daily +to relatively safely upgrade the system. Upgrade will list all of the packages +that it could not upgrade, this usually means that they depend on new packages +or conflict with some other package. <command>dselect</command> or +<literal>apt-get install</literal> can be used to force these packages to +install. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>install</term> +<listitem> +<para> +Install is used to install packages by name. The package is automatically +fetched and installed. This can be useful if you already know the name of the +package to install and do not want to go into a GUI to select it. Any number +of packages may be passed to install, they will all be fetched. Install +automatically attempts to resolve dependency problems with the listed packages +and will print a summary and ask for confirmation if anything other than its +arguments are changed. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>dist-upgrade</term> +<listitem> +<para> +Dist-upgrade is a complete upgrader designed to simplify upgrading between +releases of Debian. It uses a sophisticated algorithm to determine the best +set of packages to install, upgrade and remove to get as much of the system to +the newest release. In some situations it may be desired to use dist-upgrade +rather than spend the time manually resolving dependencies in +<command>dselect</command>. Once dist-upgrade has completed then +<command>dselect</command> can be used to install any packages that may have +been left out. +</para> +<para> +It is important to closely look at what dist-upgrade is going to do, its +decisions may sometimes be quite surprising. +</para> +</listitem> +</varlistentry> +</variablelist> +<para> +<command>apt-get</command> has several command line options that are detailed +in its man page, +<citerefentry><refentrytitle>apt-get</refentrytitle><manvolnum>8</manvolnum></citerefentry>. The +most useful option is <literal>-d</literal> which does not install the +fetched files. If the system has to download a large number of package it +would be undesired to start installing them in case something goes wrong. When +<literal>-d</literal> is used the downloaded archives can be installed by +simply running the command that caused them to be downloaded again without +<literal>-d</literal>. +</para> +</chapter> + +<chapter id="ch3"><title>DSelect</title> +<para> +The APT <command>dselect</command> method provides the complete +APT system with the <command>dselect</command> package selection +GUI. <command>dselect</command> is used to select the packages to be +installed or removed and APT actually installs them. +</para> +<para> +To enable the APT method you need to select [A]ccess in +<command>dselect</command> and then choose the APT method. You will be +prompted for a set of <emphasis>Sources</emphasis> which are places to fetch +archives from. These can be remote Internet sites, local Debian mirrors or +CD-ROMs. Each source can provide a fragment of the total Debian archive, APT +will automatically combine them to form a complete set of packages. If you +have a CD-ROM then it is a good idea to specify it first and then specify a +mirror so that you have access to the latest bug fixes. APT will automatically +use packages on your CD-ROM before downloading from the Internet. +</para> +<screen> + Set up a list of distribution source locations + + Please give the base URL of the debian distribution. + The access schemes I know about are: http file + + For example: + file:/mnt/debian, + ftp://ftp.debian.org/debian, + http://ftp.de.debian.org/debian, + + + URL [http://llug.sep.bnl.gov/debian]: +</screen> +<para> +The <emphasis>Sources</emphasis> setup starts by asking for the base of the +Debian archive, defaulting to a HTTP mirror. Next it asks for the distribution +to get. +</para> +<screen> + Please give the distribution tag to get or a path to the + package file ending in a /. The distribution + tags are typically something like: stable unstable testing non-US + + Distribution [stable]: +</screen> +<para> +The distribution refers to the Debian version in the archive, +<emphasis>stable</emphasis> refers to the latest released version +and <emphasis>unstable</emphasis> refers to the developmental +version. <emphasis>non-US</emphasis> is only available on some mirrors +and refers to packages that contain encryption technology or other +things that cannot be exported from the United States. Importing these +packages into the US is legal however. +</para> +<screen> + Please give the components to get + The components are typically something like: main contrib non-free + + Components [main contrib non-free]: +</screen> +<para> +The components list refers to the list of sub distributions to fetch. The +distribution is split up based on software licenses, main being DFSG free +packages while contrib and non-free contain things that have various +restrictions placed on their use and distribution. +</para> +<para> +Any number of sources can be added, the setup script will continue to prompt +until you have specified all that you want. +</para> +<para> +Before starting to use <command>dselect</command> it is necessary to update +the available list by selecting [U]pdate from the menu. This is a superset of +<literal>apt-get update</literal> that makes the fetched information available +to <command>dselect</command>. [U]pdate must be performed even if +<literal>apt-get update</literal> has been run before. +</para> +<para> +You can then go on and make your selections using [S]elect and then perform +the installation using [I]nstall. When using the APT method the [C]onfig and +[R]emove commands have no meaning, the [I]nstall command performs both of +them together. +</para> +<para> +By default APT will automatically remove the package (.deb) files once they +have been successfully installed. To change this behavior place +<literal>Dselect::clean "prompt";</literal> in /etc/apt/apt.conf. +</para> +</chapter> + +<chapter id="ch4"><title>The Interface</title> +<para> +Both that APT <command>dselect</command> method and <command>apt-get</command> +share the same interface. It is a simple system that generally tells you what +it will do and then goes and does it. <footnote><para> The +<command>dselect</command> method actually is a set of wrapper scripts to +<command>apt-get</command>. The method actually provides more functionality +than is present in <command>apt-get</command> alone. </para> </footnote> After +printing out a summary of what will happen APT then will print out some +informative status messages so that you can estimate how far along it is and +how much is left to do. +</para> + +<section id="s4.1"><title>Startup</title> +<para> +Before all operations except update, APT performs a number of actions +to prepare its internal state. It also does some checks of the system's +state. At any time these operations can be performed by running +<literal>apt-get check</literal>. +</para> +<screen> +# apt-get check +Reading Package Lists... Done +Building Dependency Tree... Done +</screen> +<para> +The first thing it does is read all the package files into memory. APT uses a +caching scheme so this operation will be faster the second time it is run. If +some of the package files are not found then they will be ignored and a +warning will be printed when apt-get exits. +</para> +<para> +The final operation performs a detailed analysis of the system's +dependencies. It checks every dependency of every installed or unpacked +package and considers if it is OK. Should this find a problem then a report +will be printed out and <command>apt-get</command> will refuse to run. +</para> +<screen> +# apt-get check +Reading Package Lists... Done +Building Dependency Tree... Done +You might want to run apt-get -f install' to correct these. +Sorry, but the following packages have unmet dependencies: + 9fonts: Depends: xlib6g but it is not installed + uucp: Depends: mailx but it is not installed + blast: Depends: xlib6g (>= 3.3-5) but it is not installed + adduser: Depends: perl-base but it is not installed + aumix: Depends: libgpmg1 but it is not installed + debiandoc-sgml: Depends: sgml-base but it is not installed + bash-builtins: Depends: bash (>= 2.01) but 2.0-3 is installed + cthugha: Depends: svgalibg1 but it is not installed + Depends: xlib6g (>= 3.3-5) but it is not installed + libreadlineg2: Conflicts:libreadline2 (<< 2.1-2.1) +</screen> +<para> +In this example the system has many problems, including a serious problem with +libreadlineg2. For each package that has unmet dependencies a line is printed +out indicating the package with the problem and the dependencies that are +unmet. A short explanation of why the package has a dependency problem is also +included. +</para> +<para> +There are two ways a system can get into a broken state like this. The +first is caused by <command>dpkg</command> missing some subtle relationships +between packages when performing upgrades. <footnote><para> APT however +considers all known dependencies and attempts to prevent broken +packages </para> </footnote>. The second is if a package installation +fails during an operation. In this situation a package may have been +unpacked without its dependents being installed. +</para> +<para> +The second situation is much less serious than the first because APT places +certain constraints on the order that packages are installed. In both cases +supplying the <literal>-f</literal> option to <command>apt-get</command> +will cause APT to deduce a possible solution to the problem and then +continue on. The APT <command>dselect</command> method always supplies +the <literal>-f</literal> option to allow for easy continuation of failed +maintainer scripts. +</para> +<para> +However, if the <literal>-f</literal> option is used to correct a seriously +broken system caused by the first case then it is possible that it will either +fail immediately or the installation sequence will fail. In either case it is +necessary to manually use dpkg (possibly with forcing options) to correct the +situation enough to allow APT to proceed. +</para> +</section> + +<section id="s4.2"><title>The Status Report</title> +<para> +Before proceeding <command>apt-get</command> will present a report on what will +happen. Generally the report reflects the type of operation being performed +but there are several common elements. In all cases the lists reflect the +final state of things, taking into account the <literal>-f</literal> option +and any other relevant activities to the command being executed. +</para> + +<section id="s4.2.1"><title>The Extra Package list</title> +<screen> +The following extra packages will be installed: + libdbd-mysql-perl xlib6 zlib1 xzx libreadline2 libdbd-msql-perl + mailpgp xdpkg fileutils pinepgp zlib1g xlib6g perl-base + bin86 libgdbm1 libgdbmg1 quake-lib gmp2 bcc xbuffy + squake pgp-i python-base debmake ldso perl libreadlineg2 + ssh +</screen> +<para> +The Extra Package list shows all of the packages that will be installed or +upgraded in excess of the ones mentioned on the command line. It is only +generated for an <literal>install</literal> command. The listed packages are +often the result of an Auto Install. +</para> +</section> + +<section id="s4.2.2"><title>The Packages to Remove</title> +<screen> +The following packages will be REMOVED: + xlib6-dev xpat2 tk40-dev xkeycaps xbattle xonix + xdaliclock tk40 tk41 xforms0.86 ghostview xloadimage xcolorsel + xadmin xboard perl-debug tkined xtetris libreadline2-dev perl-suid + nas xpilot xfig +</screen> +<para> +The Packages to Remove list shows all of the packages that will be removed +from the system. It can be shown for any of the operations and should be given +a careful inspection to ensure nothing important is to be taken off. The +<literal>-f</literal> option is especially good at generating packages to +remove so extreme care should be used in that case. The list may contain +packages that are going to be removed because they are only partially +installed, possibly due to an aborted installation. +</para> +</section> + +<section id="s4.2.3"><title>The New Packages list</title> +<screen> +The following NEW packages will installed: + zlib1g xlib6g perl-base libgdbmg1 quake-lib gmp2 pgp-i python-base +</screen> +<para> +The New Packages list is simply a reminder of what will happen. The packages +listed are not presently installed in the system but will be when APT is done. +</para> +</section> + +<section id="s4.2.4"><title>The Kept Back list</title> +<screen> +The following packages have been kept back + compface man-db tetex-base msql libpaper svgalib1 + gs snmp arena lynx xpat2 groff xscreensaver +</screen> +<para> +Whenever the whole system is being upgraded there is the possibility that new +versions of packages cannot be installed because they require new things or +conflict with already installed things. In this case the package will appear +in the Kept Back list. The best way to convince packages listed there to +install is with <literal>apt-get install</literal> or by using +<command>dselect</command> to resolve their problems. +</para> +</section> + +<section id="s4.2.5"><title>Held Packages warning</title> +<screen> +The following held packages will be changed: + cvs +</screen> +<para> +Sometimes you can ask APT to install a package that is on hold, in such a case +it prints out a warning that the held package is going to be changed. This +should only happen during dist-upgrade or install. +</para> +</section> + +<section id="s4.2.6"><title>Final summary</title> +<para> +Finally, APT will print out a summary of all the changes that will occur. +</para> +<screen> +206 packages upgraded, 8 newly installed, 23 to remove and 51 not upgraded. +12 packages not fully installed or removed. +Need to get 65.7M/66.7M of archives. After unpacking 26.5M will be used. +</screen> +<para> +The first line of the summary simply is a reduced version of all of the lists +and includes the number of upgrades - that is packages already installed that +have new versions available. The second line indicates the number of poorly +configured packages, possibly the result of an aborted installation. The final +line shows the space requirements that the installation needs. The first pair +of numbers refer to the size of the archive files. The first number indicates +the number of bytes that must be fetched from remote locations and the second +indicates the total size of all the archives required. The next number +indicates the size difference between the presently installed packages and the +newly installed packages. It is roughly equivalent to the space required in +/usr after everything is done. If a large number of packages are being removed +then the value may indicate the amount of space that will be freed. +</para> +<para> +Some other reports can be generated by using the -u option to show packages to +upgrade, they are similar to the previous examples. +</para> +</section> + +</section> + +<section id="s4.3"><title>The Status Display</title> +<para> +During the download of archives and package files APT prints out a series of +status messages. +</para> +<screen> +# apt-get update +Get:1 http://ftp.de.debian.org/debian-non-US/ stable/non-US/ Packages +Get:2 http://llug.sep.bnl.gov/debian/ testing/contrib Packages +Hit http://llug.sep.bnl.gov/debian/ testing/main Packages +Get:4 http://ftp.de.debian.org/debian-non-US/ unstable/binary-i386/ Packages +Get:5 http://llug.sep.bnl.gov/debian/ testing/non-free Packages +11% [5 testing/non-free `Waiting for file' 0/32.1k 0%] 2203b/s 1m52s +</screen> +<para> +The lines starting with <emphasis>Get</emphasis> are printed out when APT +begins to fetch a file while the last line indicates the progress of the +download. The first percent value on the progress line indicates the total +percent done of all files. Unfortunately since the size of the Package files +is unknown <literal>apt-get update</literal> estimates the percent done which +causes some inaccuracies. +</para> +<para> +The next section of the status line is repeated once for each download +thread and indicates the operation being performed and some useful +information about what is happening. Sometimes this section will simply +read <emphasis>Forking</emphasis> which means the OS is loading the download +module. The first word after the [ is the fetch number as shown on the +history lines. The next word is the short form name of the object being +downloaded. For archives it will contain the name of the package that is +being fetched. +</para> +<para> +Inside of the single quote is an informative string indicating the progress of +the negotiation phase of the download. Typically it progresses from +<emphasis>Connecting</emphasis> to <emphasis>Waiting for file</emphasis> to +<emphasis>Downloading</emphasis> or <emphasis>Resuming</emphasis>. The final +value is the number of bytes downloaded from the remote site. Once the +download begins this is represented as <literal>102/10.2k</literal> indicating +that 102 bytes have been fetched and 10.2 kilobytes is expected. The total +size is always shown in 4 figure notation to preserve space. After the size +display is a percent meter for the file itself. The second last element is the +instantaneous average speed. This values is updated every 5 seconds and +reflects the rate of data transfer for that period. Finally is shown the +estimated transfer time. This is updated regularly and reflects the time to +complete everything at the shown transfer rate. +</para> +<para> +The status display updates every half second to provide a constant feedback on +the download progress while the Get lines scroll back whenever a new file is +started. Since the status display is constantly updated it is unsuitable for +logging to a file, use the <literal>-q</literal> option to remove the status +display. +</para> +</section> + +<section id="s4.4"><title>Dpkg</title> +<para> +APT uses <command>dpkg</command> for installing the archives and will +switch over to the <command>dpkg</command> interface once downloading is +completed. <command>dpkg</command> will also ask a number of questions as +it processes the packages and the packages themselves may also ask several +questions. Before each question there is usually a description of what it +is asking and the questions are too varied to discuss completely here. +</para> +</section> + +</chapter> + +</book> diff --git a/doc/guide.sgml b/doc/guide.sgml deleted file mode 100644 index 747c5718c..000000000 --- a/doc/guide.sgml +++ /dev/null @@ -1,547 +0,0 @@ -<!-- -*- mode: sgml; mode: fold -*- --> -<!doctype debiandoc PUBLIC "-//DebianDoc//DTD DebianDoc//EN"> -<book> -<title>APT User's Guide</title> - -<author>Jason Gunthorpe <email>jgg@debian.org</email></author> -<version>$Id: guide.sgml,v 1.7 2003/04/26 23:26:13 doogie Exp $</version> - -<abstract> -This document provides an overview of how to use the the APT package manager. -</abstract> - -<copyright> -Copyright © Jason Gunthorpe, 1998. -<p> -"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. - -<p> -For more details, on Debian systems, see the file -/usr/share/common-licenses/GPL for the full license. -</copyright> - -<toc sect> - -<!-- General {{{ --> -<!-- ===================================================================== --> -<chapt>General - -<p> -The APT package currently contains two sections, the APT <prgn>dselect</> -method and the <prgn>apt-get</> command line user interface. Both provide -a way to install and remove packages as well as download new packages from -the Internet. - -<sect>Anatomy of the Package System -<p> -The Debian packaging system has a large amount of information associated with -each package to help assure that it integrates cleanly and easily into -the system. The most prominent of its features is the dependency system. - -<p> -The dependency system allows individual programs to make use of shared -elements in the system such as libraries. It simplifies placing infrequently -used portions of a program in separate packages to reduce the -number of things the average user is required to install. Also, it allows -for choices in mail transport agents, X servers and -so on. - -<p> -The first step to understanding the dependency system is to grasp the concept -of a simple dependency. The meaning of a simple dependency is that a package -requires another package to be installed at the same time to work properly. - -<p> -For instance, mailcrypt is an emacs extension that aids in encrypting email -with GPG. Without GPGP installed mailcrypt is useless, so mailcrypt has a -simple dependency on GPG. Also, because it is an emacs extension it has a -simple dependency on emacs, without emacs it is completely useless. - -<p> -The other important dependency to understand is a conflicting dependency. It -means that a package, when installed with another package, will not work and -may possibly be extremely harmful to the system. As an example consider a -mail transport agent such as sendmail, exim or qmail. It is not possible -to have two mail transport agents installed because both need to listen to -the network to receive mail. Attempting to install two will seriously -damage the system so all mail transport agents have a conflicting dependency -with all other mail transport agents. - -<p> -As an added complication there is the possibility for a package to pretend -to be another package. Consider that exim and sendmail for many intents are -identical, they both deliver mail and understand a common interface. Hence, -the package system has a way for them to declare that they are both -mail-transport-agents. So, exim and sendmail both declare that they provide a -mail-transport-agent and other packages that need a mail transport agent -depend on mail-transport-agent. This can add a great deal of confusion when -trying to manually fix packages. - -<p> -At any given time a single dependency may be met by packages that are already -installed or it may not be. APT attempts to help resolve dependency issues -by providing a number of automatic algorithms that help in selecting packages -for installation. -</sect> - -</chapt> - <!-- }}} --> -<!-- apt-get {{{ --> -<!-- ===================================================================== --> -<chapt>apt-get - -<p> -<prgn>apt-get</> provides a simple way to install packages from the command -line. Unlike <prgn>dpkg</>, <prgn>apt-get</> does not understand .deb files, -it works with the package's proper name and can only install .deb archives from -a <em>Source</>. - -<p> -The first <footnote>If you are using an http proxy server you must set the -http_proxy environment variable first, see sources.list(5)</footnote> thing that -should be done before using <prgn>apt-get</> is to fetch the package lists -from the <em>Sources</> so that it knows what packages are -available. This is done with <tt>apt-get update</>. For instance, - -<p> -<example> -# apt-get update -Get http://ftp.de.debian.org/debian-non-US/ stable/binary-i386/ Packages -Get http://llug.sep.bnl.gov/debian/ testing/contrib Packages -Reading Package Lists... Done -Building Dependency Tree... Done -</example> - -<p> -Once updated there are several commands that can be used: -<taglist> -<tag>upgrade<item> -Upgrade will attempt to gently upgrade the whole system. Upgrade will -never install a new package or remove an existing package, nor will it -ever upgrade a package that might cause some other package to break. -This can be used daily to relatively safely upgrade the system. Upgrade -will list all of the packages that it could not upgrade, this usually -means that they depend on new packages or conflict with some other package. -<prgn>dselect</> or <tt>apt-get install</> can be used to force these -packages to install. - -<tag>install<item> -Install is used to install packages by name. The package is -automatically fetched and installed. This can be useful if you already -know the name of the package to install and do not want to go into a GUI -to select it. Any number of packages may be passed to install, they will -all be fetched. Install automatically attempts to resolve dependency problems -with the listed packages and will print a summary and ask for confirmation -if anything other than its arguments are changed. - -<tag>dist-upgrade<item> -Dist-upgrade is a complete upgrader designed to simplify upgrading between -releases of Debian. It uses a sophisticated algorithm to determine the best -set of packages to install, upgrade and remove to get as much of the system -to the newest release. In some situations it may be desired to use dist-upgrade -rather than spend the time manually resolving dependencies in <prgn>dselect</>. -Once dist-upgrade has completed then <prgn>dselect</> can be used to install -any packages that may have been left out. - -<p> -It is important to closely look at what dist-upgrade is going to do, its -decisions may sometimes be quite surprising. -</taglist> - -<p> -<prgn>apt-get</> has several command line options that are detailed in its -man page, <manref name="apt-get" section="8">. The most useful option is -<tt>-d</> which does not install the fetched files. If the system has to -download a large number of package it would be undesired to start installing -them in case something goes wrong. When <tt>-d</> is used the downloaded -archives can be installed by simply running the command that caused them to -be downloaded again without <tt>-d</>. - -</chapt> - <!-- }}} --> -<!-- DSelect {{{ --> -<!-- ===================================================================== --> -<chapt>DSelect -<p> -The APT <prgn>dselect</> method provides the complete APT system with -the <prgn>dselect</> package selection GUI. <prgn>dselect</> is used to -select the packages to be installed or removed and APT actually installs them. - -<p> -To enable the APT method you need to select [A]ccess in <prgn>dselect</> -and then choose the APT method. You will be prompted for a set of -<em>Sources</> which are places to fetch archives from. These can be remote -Internet sites, local Debian mirrors or CD-ROMs. Each source can provide -a fragment of the total Debian archive, APT will automatically combine them -to form a complete set of packages. If you have a CD-ROM then it is a good idea -to specify it first and then specify a mirror so that you have access to -the latest bug fixes. APT will automatically use packages on your CD-ROM before -downloading from the Internet. - -<p> -<example> - Set up a list of distribution source locations - - Please give the base URL of the debian distribution. - The access schemes I know about are: http file - - For example: - file:/mnt/debian, - ftp://ftp.debian.org/debian, - http://ftp.de.debian.org/debian, - - - URL [http://llug.sep.bnl.gov/debian]: -</example> - -<p> -The <em>Sources</> setup starts by asking for the base of the Debian -archive, defaulting to a HTTP mirror. Next it asks for the distribution to -get. - -<p> -<example> - Please give the distribution tag to get or a path to the - package file ending in a /. The distribution - tags are typically something like: stable unstable testing non-US - - Distribution [stable]: -</example> - -<p> -The distribution refers to the Debian version in the archive, <em>stable</> -refers to the latest released version and <em>unstable</> refers to the -developmental version. <em>non-US</> is only available on some mirrors and -refers to packages that contain encryption technology or other things that -cannot be exported from the United States. Importing these packages into the -US is legal however. - -<p> -<example> - Please give the components to get - The components are typically something like: main contrib non-free - - Components [main contrib non-free]: -</example> - -<p> -The components list refers to the list of sub distributions to fetch. The -distribution is split up based on software licenses, main being DFSG free -packages while contrib and non-free contain things that have various -restrictions placed on their use and distribution. - -<p> -Any number of sources can be added, the setup script will continue to -prompt until you have specified all that you want. - -<p> -Before starting to use <prgn>dselect</> it is necessary to update the -available list by selecting [U]pdate from the menu. This is a superset of -<tt>apt-get update</> that makes the fetched information available to -<prgn>dselect</>. [U]pdate must be performed even if <tt>apt-get update</> -has been run before. - -<p> -You can then go on and make your selections using [S]elect and then -perform the installation using [I]nstall. When using the APT method -the [C]onfig and [R]emove commands have no meaning, the [I]nstall command -performs both of them together. - -<p> -By default APT will automatically remove the package (.deb) files once they have been -successfully installed. To change this behavior place <tt>Dselect::clean -"prompt";</> in /etc/apt/apt.conf. - -</chapt> - <!-- }}} --> -<!-- The Interfaces {{{ --> -<!-- ===================================================================== --> -<chapt>The Interface - -<p> -Both that APT <prgn>dselect</> method and <prgn>apt-get</> share the same -interface. It is a simple system that generally tells you what it will do -and then goes and does it. -<footnote> -The <prgn>dselect</> method actually is a set of wrapper scripts -to <prgn>apt-get</>. The method actually provides more functionality than -is present in <prgn>apt-get</> alone. -</footnote> -After printing out a summary of what will happen APT then will print out some -informative status messages so that you can estimate how far along it is and -how much is left to do. - -<!-- ===================================================================== --> -<sect>Startup - -<p> -Before all operations except update, APT performs a number of actions to -prepare its internal state. It also does some checks of the system's state. -At any time these operations can be performed by running <tt>apt-get check</>. -<p> -<example> -# apt-get check -Reading Package Lists... Done -Building Dependency Tree... Done -</example> - -<p> -The first thing it does is read all the package files into memory. APT -uses a caching scheme so this operation will be faster the second time it -is run. If some of the package files are not found then they will be ignored -and a warning will be printed when apt-get exits. - -<p> -The final operation performs a detailed analysis of the system's dependencies. -It checks every dependency of every installed or unpacked package and considers -if it is OK. Should this find a problem then a report will be printed out and -<prgn>apt-get</> will refuse to run. - -<p> -<example> -# apt-get check -Reading Package Lists... Done -Building Dependency Tree... Done -You might want to run apt-get -f install' to correct these. -Sorry, but the following packages have unmet dependencies: - 9fonts: Depends: xlib6g but it is not installed - uucp: Depends: mailx but it is not installed - blast: Depends: xlib6g (>= 3.3-5) but it is not installed - adduser: Depends: perl-base but it is not installed - aumix: Depends: libgpmg1 but it is not installed - debiandoc-sgml: Depends: sgml-base but it is not installed - bash-builtins: Depends: bash (>= 2.01) but 2.0-3 is installed - cthugha: Depends: svgalibg1 but it is not installed - Depends: xlib6g (>= 3.3-5) but it is not installed - libreadlineg2: Conflicts:libreadline2 (<< 2.1-2.1) -</example> - -<p> -In this example the system has many problems, including a serious problem -with libreadlineg2. For each package that has unmet dependencies a line -is printed out indicating the package with the problem and the dependencies -that are unmet. A short explanation of why the package has a dependency -problem is also included. - -<p> -There are two ways a system can get into a broken state like this. The -first is caused by <prgn>dpkg</> missing some subtle relationships between -packages when performing upgrades. <footnote>APT however considers all known -dependencies and attempts to prevent broken packages</footnote>. The second is -if a package installation fails during an operation. In this situation a -package may have been unpacked without its dependents being installed. - -<p> -The second situation is much less serious than the first because APT places -certain constraints on the order that packages are installed. In both cases -supplying the <tt>-f</> option to <prgn>apt-get</> will cause APT to deduce a -possible solution to the problem and then continue on. The APT <prgn>dselect</> -method always supplies the <tt>-f</> option to allow for easy continuation -of failed maintainer scripts. - -<p> -However, if the <tt>-f</> option is used to correct a seriously broken system -caused by the first case then it is possible that it will either fail -immediately or the installation sequence will fail. In either case it is -necessary to manually use dpkg (possibly with forcing options) to correct -the situation enough to allow APT to proceed. -</sect> - -<!-- ===================================================================== --> -<sect>The Status Report - -<p> -Before proceeding <prgn>apt-get</> will present a report on what will happen. -Generally the report reflects the type of operation being performed but there -are several common elements. In all cases the lists reflect the final state -of things, taking into account the <tt>-f</> option and any other relevant -activities to the command being executed. - -<sect1>The Extra Package list -<p> -<example> -The following extra packages will be installed: - libdbd-mysql-perl xlib6 zlib1 xzx libreadline2 libdbd-msql-perl - mailpgp xdpkg fileutils pinepgp zlib1g xlib6g perl-base - bin86 libgdbm1 libgdbmg1 quake-lib gmp2 bcc xbuffy - squake pgp-i python-base debmake ldso perl libreadlineg2 - ssh -</example> - -<p> -The Extra Package list shows all of the packages that will be installed -or upgraded in excess of the ones mentioned on the command line. It is -only generated for an <tt>install</> command. The listed packages are -often the result of an Auto Install. -</sect1> - -<sect1>The Packages to Remove -<p> -<example> -The following packages will be REMOVED: - xlib6-dev xpat2 tk40-dev xkeycaps xbattle xonix - xdaliclock tk40 tk41 xforms0.86 ghostview xloadimage xcolorsel - xadmin xboard perl-debug tkined xtetris libreadline2-dev perl-suid - nas xpilot xfig -</example> - -<p> -The Packages to Remove list shows all of the packages that will be -removed from the system. It can be shown for any of the operations and -should be given a careful inspection to ensure nothing important is to -be taken off. The <tt>-f</> option is especially good at generating packages -to remove so extreme care should be used in that case. The list may contain -packages that are going to be removed because they are only -partially installed, possibly due to an aborted installation. -</sect1> - -<sect1>The New Packages list -<p> -<example> -The following NEW packages will installed: - zlib1g xlib6g perl-base libgdbmg1 quake-lib gmp2 pgp-i python-base -</example> - -<p> -The New Packages list is simply a reminder of what will happen. The packages -listed are not presently installed in the system but will be when APT is done. -</sect1> - -<sect1>The Kept Back list -<p> -<example> -The following packages have been kept back - compface man-db tetex-base msql libpaper svgalib1 - gs snmp arena lynx xpat2 groff xscreensaver -</example> - -<p> -Whenever the whole system is being upgraded there is the possibility that -new versions of packages cannot be installed because they require new things -or conflict with already installed things. In this case the package will -appear in the Kept Back list. The best way to convince packages listed -there to install is with <tt>apt-get install</> or by using <prgn>dselect</> -to resolve their problems. -</sect1> - -<sect1>Held Packages warning -<p> -<example> -The following held packages will be changed: - cvs -</example> - -<p> -Sometimes you can ask APT to install a package that is on hold, in such a -case it prints out a warning that the held package is going to be -changed. This should only happen during dist-upgrade or install. -</sect1> - -<sect1>Final summary -<p> -Finally, APT will print out a summary of all the changes that will occur. - -<p> -<example> -206 packages upgraded, 8 newly installed, 23 to remove and 51 not upgraded. -12 packages not fully installed or removed. -Need to get 65.7M/66.7M of archives. After unpacking 26.5M will be used. -</example> - -<p> -The first line of the summary simply is a reduced version of all of the -lists and includes the number of upgrades - that is packages already -installed that have new versions available. The second line indicates the -number of poorly configured packages, possibly the result of an aborted -installation. The final line shows the space requirements that the -installation needs. The first pair of numbers refer to the size of -the archive files. The first number indicates the number of bytes that -must be fetched from remote locations and the second indicates the -total size of all the archives required. The next number indicates the -size difference between the presently installed packages and the newly -installed packages. It is roughly equivalent to the space required in -/usr after everything is done. If a large number of packages are being -removed then the value may indicate the amount of space that will be -freed. - -<p> -Some other reports can be generated by using the -u option to show packages -to upgrade, they are similar to the previous examples. -</sect> - -<!-- ===================================================================== --> -<sect>The Status Display -<p> -During the download of archives and package files APT prints out a series of -status messages. - -<p> -<example> -# apt-get update -Get:1 http://ftp.de.debian.org/debian-non-US/ stable/non-US/ Packages -Get:2 http://llug.sep.bnl.gov/debian/ testing/contrib Packages -Hit http://llug.sep.bnl.gov/debian/ testing/main Packages -Get:4 http://ftp.de.debian.org/debian-non-US/ unstable/binary-i386/ Packages -Get:5 http://llug.sep.bnl.gov/debian/ testing/non-free Packages -11% [5 testing/non-free `Waiting for file' 0/32.1k 0%] 2203b/s 1m52s -</example> - -<p> -The lines starting with <em>Get</> are printed out when APT begins to fetch -a file while the last line indicates the progress of the download. The first -percent value on the progress line indicates the total percent done of all -files. Unfortunately since the size of the Package files is unknown -<tt>apt-get update</> estimates the percent done which causes some -inaccuracies. - -<p> -The next section of the status line is repeated once for each download thread -and indicates the operation being performed and some useful information -about what is happening. Sometimes this section will simply read <em>Forking</> -which means the OS is loading the download module. The first word after the [ -is the fetch number as shown on the history lines. The next word -is the short form name of the object being downloaded. For archives it will -contain the name of the package that is being fetched. - -<p> -Inside of the single quote is an informative string indicating the progress -of the negotiation phase of the download. Typically it progresses from -<em>Connecting</> to <em>Waiting for file</> to <em>Downloading</> or -<em>Resuming</>. The final value is the number of bytes downloaded from the -remote site. Once the download begins this is represented as <tt>102/10.2k</> -indicating that 102 bytes have been fetched and 10.2 kilobytes is expected. -The total size is always shown in 4 figure notation to preserve space. After -the size display is a percent meter for the file itself. -The second last element is the instantaneous average speed. This values is -updated every 5 seconds and reflects the rate of data transfer for that -period. Finally is shown the estimated transfer time. This is updated -regularly and reflects the time to complete everything at the shown -transfer rate. - -<p> -The status display updates every half second to provide a constant feedback -on the download progress while the Get lines scroll back whenever a new -file is started. Since the status display is constantly updated it is -unsuitable for logging to a file, use the <tt>-q</> option to remove the -status display. -</sect> - -<!-- ===================================================================== --> -<sect>Dpkg - -<p> -APT uses <prgn>dpkg</> for installing the archives and will switch -over to the <prgn>dpkg</> interface once downloading is completed. -<prgn>dpkg</> will also ask a number of questions as it processes the packages -and the packages themselves may also ask several questions. Before each -question there is usually a description of what it is asking and the -questions are too varied to discuss completely here. -</sect> - -</chapt> - <!-- }}} --> - -</book> diff --git a/doc/method.dbk b/doc/method.dbk new file mode 100644 index 000000000..d2eb04df1 --- /dev/null +++ b/doc/method.dbk @@ -0,0 +1,712 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- -*- DocBook -*- --> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment; +]> + +<book lang="en"> + +<title>APT Method Interface</title> + +<bookinfo> + +<authorgroup> + <author> + <personname>Jason Gunthorpe</personname><email>jgg@debian.org</email> + </author> +</authorgroup> + +<releaseinfo>Version &apt-product-version;</releaseinfo> + +<abstract> +<para> +This document describes the interface that APT uses to the archive access +methods. +</para> +</abstract> + +<copyright><year>1998</year><holder>Jason Gunthorpe</holder></copyright> + +<legalnotice> +<title>License Notice</title> +<para> +"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. +</para> +<para> +For more details, on Debian systems, see the file +/usr/share/common-licenses/GPL for the full license. +</para> +</legalnotice> + +</bookinfo> + +<chapter id="ch1"><title>Introduction</title> + +<section id="s1.1"><title>General</title> +<para> +The APT method interface allows APT to acquire archive files (.deb), index +files (Packages, Release, Mirrors) and source files (.tar.gz, .diff). It is a +general, extensible system designed to satisfy all of these requirements: +</para> +<orderedlist numeration="arabic"> +<listitem> +<para> +Remote methods that download files from a distant site +</para> +</listitem> +<listitem> +<para> +Resume of aborted downloads +</para> +</listitem> +<listitem> +<para> +Progress reporting +</para> +</listitem> +<listitem> +<para> +If-Modified-Since (IMS) checking for index files +</para> +</listitem> +<listitem> +<para> +In-Line MD5 generation +</para> +</listitem> +<listitem> +<para> +No-copy in-filesystem methods +</para> +</listitem> +<listitem> +<para> +Multi-media methods (like CD's) +</para> +</listitem> +<listitem> +<para> +Dynamic source selection for failure recovery +</para> +</listitem> +<listitem> +<para> +User interaction for user/password requests and media swaps +</para> +</listitem> +<listitem> +<para> +Global configuration +</para> +</listitem> +</orderedlist> +<para> +Initial releases of APT (0.1.x) used a completely different method interface +that only supported the first 6 items. This new interface deals with the +remainder. +</para> +</section> + +<section id="s1.2"><title>Terms</title> +<para> +Several terms are used through out the document, they have specific meanings +which may not be immediately evident. To clarify they are summarized here. +</para> +<variablelist> +<varlistentry> +<term>source</term> +<listitem> +<para> +Refers to an item in source list. More specifically it is the broken down +item, that is each source maps to exactly one index file. Archive sources map +to Package files and Source Code sources map to Source files. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>archive file</term> +<listitem> +<para> +Refers to a binary package archive (.deb, .rpm, etc). +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>source file</term> +<listitem> +<para> +Refers to one of the files making up the source code of a package. In debian +it is one of .diff.gz, .dsc. or .tar.gz. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>URI</term> +<listitem> +<para> +Universal Resource Identifier (URI) is a super-set of the familiar URL +syntax used by web browsers. It consists of an access specification +followed by a specific location in that access space. The form is +<access>:<location>. Network addresses are given with the form +<access>://[<user>[:<pas>]@]hostname[:port]/<location>. +Some examples: +</para> +<screen> +file:/var/mirrors/debian/ +ftp://ftp.debian.org/debian +ftp://jgg:MooCow@localhost:21/debian +nfs://bigred/var/mirrors/debian +rsync://debian.midco.net/debian +cdrom:Debian 2.0r1 Disk 1/ +</screen> +</listitem> +</varlistentry> +<varlistentry> +<term>method</term> +<listitem> +<para> +There is a one to one mapping of URI access specifiers to methods. A method is +a program that knows how to handle a URI access type and operates according to +the specifications in this file. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>method instance</term> +<listitem> +<para> +A specific running method. There can be more than one instance of each method +as APT is capable of concurrent method handling. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>message</term> +<listitem> +<para> +A series of lines terminated by a blank line sent down one of the communication +lines. The first line should have the form xxx TAG where xxx are digits +forming the status code and TAG is an informational string +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>acquire</term> +<listitem> +<para> +The act of bring a URI into the local pathname space. This may simply be +verifying the existence of the URI or actually downloading it from a remote +site. +</para> +</listitem> +</varlistentry> +</variablelist> +</section> + +</chapter> + +<chapter id="ch2"><title>Specification</title> + +<section id="s2.1"><title>Overview</title> +<para> +All methods operate as a sub process of a main controlling parent. 3 FD's are +opened for use by the method allowing two way communication and emergency error +reporting. The FD's correspond to the well known unix FD's, stdin, stdout and +stderr. +</para> +<para> +Through operation of the method communication is done via http style plain +text. Specifically RFC-822 (like the Package file) fields are used to describe +items and a numeric-like header is used to indicate what is happening. Each of +these distinct communication messages should be sent quickly and without pause. +</para> +<para> +In some instances APT may pre-invoke a method to allow things like file URI's +to determine how many files are available locally. +</para> +</section> + +<section id="s2.2"><title>Message Overview</title> +<para> +The first line of each message is called the message header. The first 3 +digits (called the Status Code) have the usual meaning found in the http +protocol. 1xx is informational, 2xx is successful and 4xx is failure. The 6xx +series is used to specify things sent to the method. After the status code is +an informational string provided for visual debugging. +</para> +<itemizedlist> +<listitem> +<para> +100 Capabilities - Method capabilities +</para> +</listitem> +<listitem> +<para> +101 Log - General Logging +</para> +</listitem> +<listitem> +<para> +102 Status - Inter-URI status reporting (login progress) +</para> +</listitem> +<listitem> +<para> +200 URI Start - URI is starting acquire +</para> +</listitem> +<listitem> +<para> +201 URI Done - URI is finished acquire +</para> +</listitem> +<listitem> +<para> +400 URI Failure - URI has failed to acquire +</para> +</listitem> +<listitem> +<para> +401 General Failure - Method did not like something sent to it +</para> +</listitem> +<listitem> +<para> +402 Authorization Required - Method requires authorization to access the URI. +Authorization is User/Pass +</para> +</listitem> +<listitem> +<para> +403 Media Failure - Method requires a media change +</para> +</listitem> +<listitem> +<para> +600 URI Acquire - Request a URI be acquired +</para> +</listitem> +<listitem> +<para> +601 Configuration - Sends the configuration space +</para> +</listitem> +<listitem> +<para> +602 Authorization Credentials - Response to the 402 message +</para> +</listitem> +<listitem> +<para> +603 Media Changed - Response to the 403 message +</para> +</listitem> +</itemizedlist> +<para> +Only the 6xx series of status codes is sent TO the method. Furthermore the +method may not emit status codes in the 6xx range. The Codes 402 and 403 +require that the method continue reading all other 6xx codes until the proper +602/603 code is received. This means the method must be capable of handling an +unlimited number of 600 messages. +</para> +<para> +The flow of messages starts with the method sending out a <emphasis>100 +Capabilities</emphasis> and APT sending out a <emphasis>601 +Configuration</emphasis>. After that APT begins sending <emphasis>600 URI +Acquire</emphasis> and the method sends out <emphasis>200 URI Start</emphasis>, +<emphasis>201 URI Done</emphasis> or <emphasis>400 URI Failure</emphasis>. No +synchronization is performed, it is expected that APT will send <emphasis>600 +URI Acquire</emphasis> messages at -any- time and that the method should queue +the messages. This allows methods like http to pipeline requests to the remote +server. It should be noted however that APT will buffer messages so it is not +necessary for the method to be constantly ready to receive them. +</para> +</section> + +<section id="s2.3"><title>Header Fields</title> +<para> +The following is a short index of the header fields that are supported +</para> +<variablelist> +<varlistentry> +<term>URI</term> +<listitem> +<para> +URI being described by the message +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Filename</term> +<listitem> +<para> +Location in the filesystem +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Last-Modified</term> +<listitem> +<para> +A time stamp in RFC1123 notation for use by IMS checks +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>IMS-Hit</term> +<listitem> +<para> +The already existing item is valid +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Size</term> +<listitem> +<para> +Size of the file in bytes +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Resume-Point</term> +<listitem> +<para> +Location that transfer was started +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>MD5-Hash</term> +<listitem> +<para> +Computed MD5 hash for the file +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Message</term> +<listitem> +<para> +String indicating some displayable message +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Media</term> +<listitem> +<para> +String indicating the media name required +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Site</term> +<listitem> +<para> +String indicating the site authorization is required for +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>User</term> +<listitem> +<para> +Username for authorization +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Password</term> +<listitem> +<para> +Password for authorization +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Fail</term> +<listitem> +<para> +Operation failed +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Drive</term> +<listitem> +<para> +Drive the media should be placed in +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Config-Item</term> +<listitem> +<para> +A string of the form +<replaceable>item</replaceable>=<replaceable>value</replaceable> derived from +the APT configuration space. These may include method specific values and +general values not related to the method. It is up to the method to filter out +the ones it wants. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Single-Instance</term> +<listitem> +<para> +Requires that only one instance of the method be run This is a yes/no value. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Pipeline</term> +<listitem> +<para> +The method is capable of pipelining. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Local</term> +<listitem> +<para> +The method only returns Filename: fields. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Send-Config</term> +<listitem> +<para> +Send configuration to the method. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Needs-Cleanup</term> +<listitem> +<para> +The process is kept around while the files it returned are being used. This is +primarily intended for CD-ROM and File URIs that need to unmount filesystems. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Version</term> +<listitem> +<para> +Version string for the method +</para> +</listitem> +</varlistentry> +</variablelist> +<para> +This is a list of which headers each status code can use +</para> +<variablelist> +<varlistentry> +<term>100 Capabilities</term> +<listitem> +<para> +Displays the capabilities of the method. Methods should set the pipeline bit +if their underlying protocol supports pipelining. The only known method that +does support pipelining is http. Fields: Version, Single-Instance, Pre-Scan, +Pipeline, Send-Config, Needs-Cleanup +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>101 Log</term> +<listitem> +<para> +A log message may be printed to the screen if debugging is enabled. This is +only for debugging the method. Fields: Message +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>102 Status</term> +<listitem> +<para> +Message gives a progress indication for the method. It can be used to show +pre-transfer status for Internet type methods. Fields: Message +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>200 URI Start</term> +<listitem> +<para> +Indicates the URI is starting to be transferred. The URI is specified along +with stats about the file itself. Fields: URI, Size, Last-Modified, +Resume-Point +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>201 URI Done</term> +<listitem> +<para> +Indicates that a URI has completed being transferred. It is possible to +specify a <emphasis>201 URI Done</emphasis> without a <emphasis>URI +Start</emphasis> which would mean no data was transferred but the file is now +available. A Filename field is specified when the URI is directly available in +the local pathname space. APT will either directly use that file or copy it +into another location. It is possible to return Alt-* fields to indicate that +another possibility for the URI has been found in the local pathname space. +This is done if a decompressed version of a .gz file is found. Fields: URI, +Size, Last-Modified, Filename, MD5-Hash +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>400 URI Failure</term> +<listitem> +<para> +Indicates a fatal URI failure. The URI is not retrievable from this source. As +with <emphasis>201 URI Done</emphasis> <emphasis>200 URI Start</emphasis> is +not required to precede this message Fields: URI, Message +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>401 General Failure</term> +<listitem> +<para> +Indicates that some unspecific failure has occurred and the method is unable +to continue. The method should terminate after sending this message. It +is intended to check for invalid configuration options or other severe +conditions. Fields: Message +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>402 Authorization Required</term> +<listitem> +<para> +The method requires a Username and Password pair to continue. After sending +this message the method will expect APT to send a <emphasis>602 Authorization +Credentials</emphasis> message with the required information. It is possible +for a method to send this multiple times. Fields: Site +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>403 Media Failure</term> +<listitem> +<para> +A method that deals with multiple media requires that a new media be +inserted. The Media field contains the name of the media to be +inserted. Fields: Media, Drive +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>600 URI Acquire</term> +<listitem> +<para> +APT is requesting that a new URI be added to the acquire list. Last-Modified +has the time stamp of the currently cache file if applicable. Filename is the +name of the file that the acquired URI should be written to. Fields: URI, +Filename Last-Modified +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>601 Configuration</term> +<listitem> +<para> +APT is sending the configuration space to the method. A series of Config-Item +fields will be part of this message, each containing an entry from the +configuration space. Fields: Config-Item. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>602 Authorization Credentials</term> +<listitem> +<para> +This is sent in response to a <emphasis>402 Authorization Required</emphasis> +message. It contains the entered username and password. Fields: Site, User, +Password +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>603 Media Changed</term> +<listitem> +<para> +This is sent in response to a <emphasis>403 Media Failure</emphasis> +message. It indicates that the user has changed media and it is safe +to proceed. Fields: Media, Fail +</para> +</listitem> +</varlistentry> +</variablelist> +</section> + +<section id="s2.4"><title>Notes</title> +<para> +The methods supplied by the stock apt are: +</para> +<orderedlist numeration="arabic"> +<listitem> +<para> +cdrom - For Multi-Disc CD-ROMs +</para> +</listitem> +<listitem> +<para> +copy - (internal) For copying files around the filesystem +</para> +</listitem> +<listitem> +<para> +file - For local files +</para> +</listitem> +<listitem> +<para> +gzip - (internal) For decompression +</para> +</listitem> +<listitem> +<para> +http - For HTTP servers +</para> +</listitem> +</orderedlist> +<para> +The two internal methods, copy and gzip, are used by the acquire code to +parallize and simplify the automatic decompression of package files as well as +copying package files around the file system. Both methods can be seen to act +the same except that one decompresses on the fly. APT uses them by generating +a copy URI that is formed identically to a file URI. The destination file is +send as normal. The method then takes the file specified by the URI and writes +it to the destination file. A typical set of operations may be: +</para> +<screen> +http://foo.com/Packages.gz -> /bar/Packages.gz +gzip:/bar/Packages.gz -> /bar/Packages.decomp +rename Packages.decomp to /final/Packages +</screen> +<para> +The http method implements a fully featured HTTP/1.1 client that supports +deep pipelining and reget. It works best when coupled with an apache 1.3 +server. The file method simply generates failures or success responses +with the filename field set to the proper location. The cdrom method acts +the same except that it checks that the mount point has a valid cdrom in +it. It does this by (effectively) computing a md5 hash of 'ls -l' on the +mountpoint. +</para> +</section> + +</chapter> + +</book> diff --git a/doc/method.sgml b/doc/method.sgml deleted file mode 100644 index 5aa7b52e8..000000000 --- a/doc/method.sgml +++ /dev/null @@ -1,354 +0,0 @@ -<!-- -*- mode: sgml; mode: fold -*- --> -<!doctype debiandoc PUBLIC "-//DebianDoc//DTD DebianDoc//EN"> -<book> -<title>APT Method Interface </title> - -<author>Jason Gunthorpe <email>jgg@debian.org</email></author> -<version>$Id: method.sgml,v 1.10 2003/02/12 15:05:46 doogie Exp $</version> - -<abstract> -This document describes the interface that APT uses to the archive -access methods. -</abstract> - -<copyright> -Copyright © Jason Gunthorpe, 1998. -<p> -"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. - -<p> -For more details, on Debian systems, see the file -/usr/share/common-licenses/GPL for the full license. -</copyright> - -<toc sect> - -<chapt>Introduction -<!-- General {{{ --> -<!-- ===================================================================== --> -<sect>General - -<p> -The APT method interface allows APT to acquire archive files (.deb), index -files (Packages, Release, Mirrors) and source files (.tar.gz, .diff). It -is a general, extensible system designed to satisfy all of these -requirements: - -<enumlist> -<item>Remote methods that download files from a distant site -<item>Resume of aborted downloads -<item>Progress reporting -<item>If-Modified-Since (IMS) checking for index files -<item>In-Line MD5 generation -<item>No-copy in-filesystem methods -<item>Multi-media methods (like CD's) -<item>Dynamic source selection for failure recovery -<item>User interaction for user/password requests and media swaps -<item>Global configuration -</enumlist> - -Initial releases of APT (0.1.x) used a completely different method -interface that only supported the first 6 items. This new interface -deals with the remainder. -</sect> - <!-- }}} --> -<!-- Terms {{{ --> -<!-- ===================================================================== --> -<sect>Terms - -<p> -Several terms are used through out the document, they have specific -meanings which may not be immediately evident. To clarify they are summarized -here. - -<taglist> -<tag>source<item> -Refers to an item in source list. More specifically it is the broken down -item, that is each source maps to exactly one index file. Archive sources -map to Package files and Source Code sources map to Source files. - -<tag>archive file<item> -Refers to a binary package archive (.deb, .rpm, etc). - -<tag>source file<item> -Refers to one of the files making up the source code of a package. In -debian it is one of .diff.gz, .dsc. or .tar.gz. - -<tag>URI<item> -Universal Resource Identifier (URI) is a super-set of the familiar URL -syntax used by web browsers. It consists of an access specification -followed by a specific location in that access space. The form is -<access>:<location>. Network addresses are given with the form -<access>://[<user>[:<pas>]@]hostname[:port]/<location>. -Some examples: -<example> -file:/var/mirrors/debian/ -ftp://ftp.debian.org/debian -ftp://jgg:MooCow@localhost:21/debian -nfs://bigred/var/mirrors/debian -rsync://debian.midco.net/debian -cdrom:Debian 2.0r1 Disk 1/ -</example> - -<tag>method<item> -There is a one to one mapping of URI access specifiers to methods. A method -is a program that knows how to handle a URI access type and operates according -to the specifications in this file. - -<tag>method instance<item> -A specific running method. There can be more than one instance of each method -as APT is capable of concurrent method handling. - -<tag>message<item> -A series of lines terminated by a blank line sent down one of the -communication lines. The first line should have the form xxx TAG -where xxx are digits forming the status code and TAG is an informational -string - -<tag>acquire<item> -The act of bring a URI into the local pathname space. This may simply -be verifying the existence of the URI or actually downloading it from -a remote site. - -</taglist> - -</sect> - <!-- }}} --> -<chapt>Specification -<!-- Overview {{{ --> -<!-- ===================================================================== --> -<sect>Overview - -<p> -All methods operate as a sub process of a main controlling parent. 3 FD's -are opened for use by the method allowing two way communication and -emergency error reporting. The FD's correspond to the well known unix FD's, -stdin, stdout and stderr. - -<p> -Through operation of the method communication is done via http -style plain text. Specifically RFC-822 (like the Package file) fields -are used to describe items and a numeric-like header is used to indicate -what is happening. Each of these distinct communication messages should be -sent quickly and without pause. - -<p> -In some instances APT may pre-invoke a method to allow things like file -URI's to determine how many files are available locally. -</sect> - <!-- }}} --> -<!-- Message Overview {{{ --> -<!-- ===================================================================== --> -<sect>Message Overview - -<p> -The first line of each message is called the message header. The first -3 digits (called the Status Code) have the usual meaning found in the -http protocol. 1xx is informational, 2xx is successful and 4xx is failure. -The 6xx series is used to specify things sent to the method. After the -status code is an informational string provided for visual debugging. - -<list> -<item>100 Capabilities - Method capabilities -<item>101 Log - General Logging -<item>102 Status - Inter-URI status reporting (login progress) -<item>200 URI Start - URI is starting acquire -<item>201 URI Done - URI is finished acquire -<item>400 URI Failure - URI has failed to acquire -<item>401 General Failure - Method did not like something sent to it -<item>402 Authorization Required - Method requires authorization - to access the URI. Authorization is User/Pass -<item>403 Media Failure - Method requires a media change -<item>600 URI Acquire - Request a URI be acquired -<item>601 Configuration - Sends the configuration space -<item>602 Authorization Credentials - Response to the 402 message -<item>603 Media Changed - Response to the 403 message -</list> - -Only the 6xx series of status codes is sent TO the method. Furthermore -the method may not emit status codes in the 6xx range. The Codes 402 -and 403 require that the method continue reading all other 6xx codes -until the proper 602/603 code is received. This means the method must be -capable of handling an unlimited number of 600 messages. - -<p> -The flow of messages starts with the method sending out a -<em>100 Capabilities</> and APT sending out a <em>601 Configuration</>. -After that APT begins sending <em>600 URI Acquire</> and the method -sends out <em>200 URI Start</>, <em>201 URI Done</> or -<em>400 URI Failure</>. No synchronization is performed, it is expected -that APT will send <em>600 URI Acquire</> messages at -any- time and -that the method should queue the messages. This allows methods like http -to pipeline requests to the remote server. It should be noted however -that APT will buffer messages so it is not necessary for the method -to be constantly ready to receive them. -</sect> - <!-- }}} --> -<!-- Header Fields {{{ --> -<!-- ===================================================================== --> -<sect>Header Fields - -<p> -The following is a short index of the header fields that are supported - -<taglist> -<tag>URI<item>URI being described by the message -<tag>Filename<item>Location in the filesystem -<tag>Last-Modified<item>A time stamp in RFC1123 notation for use by IMS checks -<tag>IMS-Hit<item>The already existing item is valid -<tag>Size<item>Size of the file in bytes -<tag>Resume-Point<item>Location that transfer was started -<tag>MD5-Hash<item>Computed MD5 hash for the file -<tag>Message<item>String indicating some displayable message -<tag>Media<item>String indicating the media name required -<tag>Site<item>String indicating the site authorization is required for -<tag>User<item>Username for authorization -<tag>Password<item>Password for authorization -<tag>Fail<item>Operation failed -<tag>Drive<item>Drive the media should be placed in -<tag>Config-Item<item> -A string of the form <var>item</>=<var>value</> derived from the APT -configuration space. These may include method specific values and general -values not related to the method. It is up to the method to filter out -the ones it wants. -<tag>Single-Instance<item>Requires that only one instance of the method be run - This is a yes/no value. -<tag>Pipeline<item>The method is capable of pipelining. -<tag>Local<item>The method only returns Filename: fields. -<tag>Send-Config<item>Send configuration to the method. -<tag>Needs-Cleanup<item>The process is kept around while the files it returned -are being used. This is primarily intended for CD-ROM and File URIs that need -to unmount filesystems. -<tag>Version<item>Version string for the method -</taglist> - -This is a list of which headers each status code can use - -<taglist> -<tag>100 Capabilities<item> -Displays the capabilities of the method. Methods should set the -pipeline bit if their underlying protocol supports pipelining. The -only known method that does support pipelining is http. -Fields: Version, Single-Instance, Pre-Scan, Pipeline, Send-Config, -Needs-Cleanup - -<tag>101 Log<item> -A log message may be printed to the screen if debugging is enabled. This -is only for debugging the method. -Fields: Message - -<tag>102 Status<item> -Message gives a progress indication for the method. It can be used to show -pre-transfer status for Internet type methods. -Fields: Message - -<tag>200 URI Start<item> -Indicates the URI is starting to be transferred. The URI is specified -along with stats about the file itself. -Fields: URI, Size, Last-Modified, Resume-Point - -<tag>201 URI Done<item> -Indicates that a URI has completed being transferred. It is possible -to specify a <em>201 URI Done</> without a <em>URI Start</> which would -mean no data was transferred but the file is now available. A Filename -field is specified when the URI is directly available in the local -pathname space. APT will either directly use that file or copy it into -another location. It is possible to return Alt-* fields to indicate that -another possibility for the URI has been found in the local pathname space. -This is done if a decompressed version of a .gz file is found. -Fields: URI, Size, Last-Modified, Filename, MD5-Hash - -<tag>400 URI Failure<item> -Indicates a fatal URI failure. The URI is not retrievable from this source. -As with <em>201 URI Done</> <em>200 URI Start</> is not required to precede -this message -Fields: URI, Message - -<tag>401 General Failure<item> -Indicates that some unspecific failure has occurred and the method is unable -to continue. The method should terminate after sending this message. It -is intended to check for invalid configuration options or other severe -conditions. -Fields: Message - -<tag>402 Authorization Required<item> -The method requires a Username and Password pair to continue. After sending -this message the method will expect APT to send a <em>602 Authorization -Credentials</> message with the required information. It is possible for -a method to send this multiple times. -Fields: Site - -<tag>403 Media Failure<item> -A method that deals with multiple media requires that a new media be inserted. -The Media field contains the name of the media to be inserted. -Fields: Media, Drive - -<tag>600 URI Acquire<item> -APT is requesting that a new URI be added to the acquire list. Last-Modified -has the time stamp of the currently cache file if applicable. Filename -is the name of the file that the acquired URI should be written to. -Fields: URI, Filename Last-Modified - -<tag>601 Configuration<item> -APT is sending the configuration space to the method. A series of -Config-Item fields will be part of this message, each containing an entry -from the configuration space. -Fields: Config-Item. - -<tag>602 Authorization Credentials<item> -This is sent in response to a <em>402 Authorization Required</> message. -It contains the entered username and password. -Fields: Site, User, Password - -<tag>603 Media Changed<item> -This is sent in response to a <em>403 Media Failure</> message. It -indicates that the user has changed media and it is safe to proceed. -Fields: Media, Fail -</taglist> - -</sect> - <!-- }}} --> -<!-- Method Notes {{{ --> -<!-- ===================================================================== --> -<sect>Notes - -<p> -The methods supplied by the stock apt are: -<enumlist> -<item>cdrom - For Multi-Disc CD-ROMs -<item>copy - (internal) For copying files around the filesystem -<item>file - For local files -<item>gzip - (internal) For decompression -<item>http - For HTTP servers -</enumlist> - -<p> -The two internal methods, copy and gzip, are used by the acquire code to -parallize and simplify the automatic decompression of package files as well -as copying package files around the file system. Both methods can be seen to -act the same except that one decompresses on the fly. APT uses them by -generating a copy URI that is formed identically to a file URI. The destination -file is send as normal. The method then takes the file specified by the -URI and writes it to the destination file. A typical set of operations may -be: -<example> -http://foo.com/Packages.gz -> /bar/Packages.gz -gzip:/bar/Packages.gz -> /bar/Packages.decomp -rename Packages.decomp to /final/Packages -</example> - -<p> -The http method implements a fully featured HTTP/1.1 client that supports -deep pipelining and reget. It works best when coupled with an apache 1.3 -server. The file method simply generates failures or success responses with -the filename field set to the proper location. The cdrom method acts the same -except that it checks that the mount point has a valid cdrom in it. It does -this by (effectively) computing a md5 hash of 'ls -l' on the mountpoint. - -</sect> - <!-- }}} --> - -</book> diff --git a/doc/offline.sgml b/doc/offline.dbk index 659ca3147..7163f8bd5 100644 --- a/doc/offline.sgml +++ b/doc/offline.dbk @@ -1,74 +1,89 @@ -<!-- -*- mode: sgml; mode: fold -*- --> -<!doctype debiandoc PUBLIC "-//DebianDoc//DTD DebianDoc//EN"> -<book> +<?xml version="1.0" encoding="UTF-8"?> +<!-- -*- DocBook -*- --> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment; +]> + +<book lang="en"> + <title>Using APT Offline</title> -<author>Jason Gunthorpe <email>jgg@debian.org</email></author> -<version>$Id: offline.sgml,v 1.8 2003/02/12 15:06:41 doogie Exp $</version> +<bookinfo> + +<authorgroup> + <author> + <personname>Jason Gunthorpe</personname><email>jgg@debian.org</email> + </author> +</authorgroup> + +<releaseinfo>Version &apt-product-version;</releaseinfo> <abstract> -This document describes how to use APT in a non-networked environment, +<para> +This document describes how to use APT in a non-networked environment, specifically a 'sneaker-net' approach for performing upgrades. +</para> </abstract> -<copyright> -Copyright © Jason Gunthorpe, 1999. -<p> +<copyright><year>1999</year><holder>Jason Gunthorpe</holder></copyright> + +<legalnotice> +<title>License Notice</title> +<para> "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 +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. - -<p> +</para> +<para> For more details, on Debian systems, see the file /usr/share/common-licenses/GPL for the full license. -</copyright> +</para> +</legalnotice> -<toc sect> +</bookinfo> -<chapt>Introduction -<!-- Overview {{{ --> -<!-- ===================================================================== --> -<sect>Overview +<chapter id="ch1"><title>Introduction</title> -<p> +<section id="s1.1"><title>Overview</title> +<para> Normally APT requires direct access to a Debian archive, either from a local media or through a network. Another common complaint is that a Debian machine -is on a slow link, such as a modem and another machine has a very fast +is on a slow link, such as a modem and another machine has a very fast connection but they are physically distant. - -<p> -The solution to this is to use large removable media such as a Zip disc or a +</para> +<para> +The solution to this is to use large removable media such as a Zip disc or a SuperDisk disc. These discs are not large enough to store the entire Debian -archive but can easily fit a subset large enough for most users. The idea -is to use APT to generate a list of packages that are required and then fetch -them onto the disc using another machine with good connectivity. It is -even possible to use another Debian machine with APT or to use a completely -different OS and a download tool like wget. Let <em>remote host</em> mean the -machine downloading the packages, and <em>target host</em> the one with bad or -no connection. - -<p> +archive but can easily fit a subset large enough for most users. The idea is +to use APT to generate a list of packages that are required and then fetch them +onto the disc using another machine with good connectivity. It is even +possible to use another Debian machine with APT or to use a completely +different OS and a download tool like wget. Let <emphasis>remote +host</emphasis> mean the machine downloading the packages, and <emphasis>target +host</emphasis> the one with bad or no connection. +</para> +<para> This is achieved by creatively manipulating the APT configuration file. The essential premise to tell APT to look on a disc for it's archive files. Note that the disc should be formated with a filesystem that can handle long file names such as ext2, fat32 or vfat. +</para> +</section> -</sect> - <!-- }}} --> +</chapter> -<chapt>Using APT on both machines -<!-- Overview {{{ --> -<!-- ===================================================================== --> -<sect>Overview +<chapter id="ch2"><title>Using APT on both machines</title> -<p> -APT being available on both machines gives the simplest configuration. The -basic idea is to place a copy of the status file on the disc and use the -remote machine to fetch the latest package files and decide which packages to +<section id="s2.1"><title>Overview</title> +<para> +APT being available on both machines gives the simplest configuration. The +basic idea is to place a copy of the status file on the disc and use the remote +machine to fetch the latest package files and decide which packages to download. The disk directory structure should look like: - -<example> +</para> +<screen> /disc/ archives/ partial/ @@ -77,36 +92,32 @@ download. The disk directory structure should look like: status sources.list apt.conf -</example> - -</sect> - <!-- }}} --> -<!-- The configuartion file {{{ --> -<!-- ===================================================================== --> -<sect>The configuration file - -<p> -The configuration file should tell APT to store its files on the disc and -to use the configuration files on the disc as well. The sources.list should -contain the proper sites that you wish to use from the remote machine, and -the status file should be a copy of <em>/var/lib/dpkg/status</em> from the -<em>target host</em>. Please note, if you are using a local archive you must use -copy URIs, the syntax is identical to file URIs. - -<p> -<em>apt.conf</em> must contain the necessary information to make APT use the -disc: - -<example> +</screen> +</section> + +<section id="s2.2"><title>The configuration file</title> +<para> +The configuration file should tell APT to store its files on the disc and to +use the configuration files on the disc as well. The sources.list should +contain the proper sites that you wish to use from the remote machine, and the +status file should be a copy of <emphasis>/var/lib/dpkg/status</emphasis> from +the <emphasis>target host</emphasis>. Please note, if you are using a local +archive you must use copy URIs, the syntax is identical to file URIs. +</para> +<para> +<emphasis>apt.conf</emphasis> must contain the necessary information to make +APT use the disc: +</para> +<screen> APT { /* This is not necessary if the two machines are the same arch, it tells the remote APT what architecture the target machine is */ Architecture "i386"; - + Get::Download-Only "true"; }; - + Dir { /* Use the disc for state information and redirect the status file from @@ -117,120 +128,120 @@ disc: // Binary caches will be stored locally Cache::archives "/disc/archives/"; Cache "/tmp/"; - + // Location of the source list. Etc "/disc/"; - }; -</example> - + }; +</screen> +<para> More details can be seen by examining the apt.conf man page and the sample -configuration file in <em>/usr/share/doc/apt/examples/apt.conf</em>. - -<p> -On the target machine the first thing to do is mount the disc and copy -<em>/var/lib/dpkg/status</em> to it. You will also need to create the directories -outlined in the Overview, <em>archives/partial/</em> and <em>lists/partial/</em>. -Then take the disc to the remote machine and configure the sources.list. -On the remote machine execute the following: - -<example> +configuration file in +<emphasis>/usr/share/doc/apt/examples/apt.conf</emphasis>. +</para> +<para> +On the target machine the first thing to do is mount the disc and copy +<emphasis>/var/lib/dpkg/status</emphasis> to it. You will also need +to create the directories outlined in the Overview, +<emphasis>archives/partial/</emphasis> and +<emphasis>lists/partial/</emphasis>. Then take the disc to the +remote machine and configure the sources.list. On the remote +machine execute the following: +</para> +<screen> # export APT_CONFIG="/disc/apt.conf" # apt-get update [ APT fetches the package files ] # apt-get dist-upgrade [ APT fetches all the packages needed to upgrade the target machine ] -</example> - +</screen> +<para> The dist-upgrade command can be replaced with any other standard APT commands, -particularly dselect-upgrade. You can even use an APT front end such as -<em>dselect</em>. However this presents a problem in communicating your -selections back to the local computer. - -<p> -Now the disc contains all of the index files and archives needed to upgrade -the target machine. Take the disc back and run: - -<example> +particularly dselect-upgrade. You can even use an APT front end such as +<emphasis>dselect</emphasis>. However this presents a problem in communicating +your selections back to the local computer. +</para> +<para> +Now the disc contains all of the index files and archives needed to upgrade the +target machine. Take the disc back and run: +</para> +<screen> # export APT_CONFIG="/disc/apt.conf" # apt-get check [ APT generates a local copy of the cache files ] # apt-get --no-d -o dir::state::status=/var/lib/dpkg/status dist-upgrade [ Or any other APT command ] -</example> - -<p> -It is necessary for proper function to re-specify the status file to be the +</screen> +<para> +It is necessary for proper function to re-specify the status file to be the local one. This is very important! - -<p> -If you are using dselect you can do the very risky operation of copying +</para> +<para> +If you are using dselect you can do the very risky operation of copying disc/status to /var/lib/dpkg/status so that any selections you made on the -remote machine are updated. I highly recommend that people only make selections -on the local machine - but this may not always be possible. DO NOT copy -the status file if dpkg or APT have been run in the mean time!! - -</sect> - <!-- }}} --> - -<chapt>Using APT and wget -<!-- Overview {{{ --> -<!-- ===================================================================== --> -<sect>Overview - -<p> -<em>wget</em> is a popular and portable download tool that can run on nearly -any machine. Unlike the method above this requires that the Debian machine -already has a list of available packages. - -<p> +remote machine are updated. I highly recommend that people only make +selections on the local machine - but this may not always be possible. DO NOT +copy the status file if dpkg or APT have been run in the mean time!! +</para> +</section> + +</chapter> + +<chapter id="ch3"><title>Using APT and wget</title> + +<section id="s3.1"><title>Overview</title> +<para> +<emphasis>wget</emphasis> is a popular and portable download tool that can run +on nearly any machine. Unlike the method above this requires that the Debian +machine already has a list of available packages. +</para> +<para> The basic idea is to create a disc that has only the archive files downloaded from the remote site. This is done by using the --print-uris option to apt-get and then preparing a wget script to actually fetch the packages. +</para> +</section> -</sect> - <!-- }}} --> -<!-- Operation {{{ --> -<!-- ===================================================================== --> -<sect>Operation - -<p> +<section id="s3.2"><title>Operation</title> +<para> Unlike the previous technique no special configuration files are required. We merely use the standard APT commands to generate the file list. - -<example> - # apt-get dist-upgrade +</para> +<screen> + # apt-get dist-upgrade [ Press no when prompted, make sure you are happy with the actions ] - # apt-get -qq --print-uris dist-upgrade > uris - # awk '{print "wget -O " $2 " " $1}' < uris > /disc/wget-script -</example> - -Any command other than dist-upgrade could be used here, including + # apt-get -qq --print-uris dist-upgrade > uris + # awk '{print "wget -O " $2 " " $1}' < uris > /disc/wget-script +</screen> +<para> +Any command other than dist-upgrade could be used here, including dselect-upgrade. - -<p> -The /disc/wget-script file will now contain a list of wget commands to execute +</para> +<para> +The /disc/wget-script file will now contain a list of wget commands to execute in order to fetch the necessary archives. This script should be run with the -current directory as the disc's mount point so as to save the output on the +current directory as the disc's mount point so as to save the output on the disc. - -<p> +</para> +<para> The remote machine would do something like - -<example> +</para> +<screen> # cd /disc # sh -x ./wget-script [ wait.. ] -</example> - +</screen> +<para> Once the archives are downloaded and the disc returned to the Debian machine installation can proceed using, - -<example> +</para> +<screen> # apt-get -o dir::cache::archives="/disc/" dist-upgrade -</example> - +</screen> +<para> Which will use the already fetched archives on the disc. +</para> +</section> + +</chapter> -</sect> - <!-- }}} --> </book> |