From 271733ee8eb9a673747bdef320af5ca8e8f18273 Mon Sep 17 00:00:00 2001 From: Guillem Jover Date: Wed, 2 Jul 2014 02:22:32 +0200 Subject: doc: Convert from DebianDoc SGML to DocBook XML --- doc/design.dbk | 438 ++++++++++++++++++++++++++ doc/design.sgml | 411 ------------------------ doc/dpkg-tech.dbk | 895 +++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/dpkg-tech.sgml | 511 ------------------------------ doc/files.dbk | 392 +++++++++++++++++++++++ doc/files.sgml | 345 --------------------- doc/guide.dbk | 560 +++++++++++++++++++++++++++++++++ doc/guide.sgml | 547 -------------------------------- doc/method.dbk | 712 ++++++++++++++++++++++++++++++++++++++++++ doc/method.sgml | 354 --------------------- doc/offline.dbk | 247 +++++++++++++++ doc/offline.sgml | 236 -------------- 12 files changed, 3244 insertions(+), 2404 deletions(-) create mode 100644 doc/design.dbk delete mode 100644 doc/design.sgml create mode 100644 doc/dpkg-tech.dbk delete mode 100644 doc/dpkg-tech.sgml create mode 100644 doc/files.dbk delete mode 100644 doc/files.sgml create mode 100644 doc/guide.dbk delete mode 100644 doc/guide.sgml create mode 100644 doc/method.dbk delete mode 100644 doc/method.sgml create mode 100644 doc/offline.dbk delete mode 100644 doc/offline.sgml (limited to 'doc') 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 @@ + + + %aptverbatiment; +]> + + + +The APT project design document + + + + + + Manoj Srivastavasrivasta@debian.org + + + +Version &apt-product-version; + + + +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. + + + +1997Manoj Srivastava + + +License Notice + +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. + + +This is distributed in the hope that it will be useful, but without +any warranty; without even the implied warranty of merchantability +or fitness for a particular purpose. See the GNU General Public License for +more details. + + +You should have received a copy of the GNU General Public License with your +Debian system, in /usr/share/common-licenses/GPL, or with +the debiandoc-sgml source package as the file +COPYING. If not, write to the Free Software Foundation, +Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + + + + + +Introduction + +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. + + +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) + + + +Requirements + + + +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. + + + + +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. + + + + +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. + + + + +This would allow APT to handle standard installations, +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. + + + + +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) + + + + +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, +configure immediately requests mentioned below should be +handled. + + + + +Handle replacement of a package providing a virtual package with another (for +example, it has been very difficult replacing sendmail with +smail, or vice versa), making sure that the dependencies are +still satisfied. + + + + +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. + + + + +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. + + + + +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. + + + + +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). + + + + +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) + + + + + +Procedural description + + +Set Options + + +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. + + + + +Updates + + +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. + + + + +Local status + + +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. + + + + +Relationship determination + + +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. + + + + +Selection + + +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) + + + + +Ordering of package installations and configuration + + +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). + + + + +Action + + +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. + + + + + + +Modules and interfaces + + +The user interface module + + +Look at Behan Webster's documentation. + + + + +Widget set + + +Related closely to above Could some one present design decisions of the widget +set here? + + + + +pdate Module + + +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) + + +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. + + + + +FTP methods + + + + +mount and file traversal module(s)? + + + + +Other methods ??? + + + + + + +Status file parser/generator + + +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 +dpkg -BORGiE on a file system. + + + + +Package file parser/generator + + +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. + + + + +Dependency module + + + + +dependency/conflict determination and linking + + + + +reverse dependency generator. Maybe merged with above + + + + + + +Package ordering Module + + +Create an ordering of the actions to be taken. + + + + +Event generator + + +module to interact with dpkg + + + + + + +Data flow and conversions analysis. + + ____________ + __\|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 | + |___________| + + +dpkg also interacts with status and available files. + + +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. + + +The other focal point for APT is the user interface. + + + + 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 @@ - - - - - The APT project design document - - Manoj Srivastava - srivasta@debian.org - - $Id: design.sgml,v 1.4 2003/02/12 15:05:45 doogie Exp $ - - 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. - - - Copyright ©1997 Manoj Srivastava - -

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

-

- This is distributed in the hope that it will be useful, but - without any warranty; without even the implied - warranty of merchantability or fitness for a particular - purpose. See the GNU General Public License for more - details.

- -

- You should have received a copy of the GNU General Public - License with your Debian system, in - /usr/share/common-licenses/GPL, or with the - COPYING. If not, write to the Free Software - Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, - USA.

- - - - Introduction -

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.

- -

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)

- - - Requirements -

- - -

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

- - -

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

- - -

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

- - -

- This would allow APT to handle standard - installations, 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.

- - -

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

- - -

- 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, - configure immediately requests mentioned below - should be handled.

- - -

- Handle replacement of a package providing a virtual - package with another (for example, it has been very - difficult replacing sendmail with - smail, or vice versa), making sure that the - dependencies are still satisfied.

- - -

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

- - -

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

- - -

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

- - -

- 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).

- - -

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

- - -

- - - Procedural description -

- Set Options - -

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

- - Updates - -

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

- - Local status - -

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

- - Relationship determination - -

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

- - Selection - -

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

- - Ordering of package installations and configuration - -

- 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).

- - Action - -

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

- - - -

- - - Modules and interfaces -

- The user interface module - -

Look at Behan Webster's documentation.

- - Widget set - -

- Related closely to above Could some one present design - decisions of the widget set here?

- - pdate Module - -

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

-

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

-

- -

FTP methods

- - -

mount and file traversal module(s)?

- - -

Other methods ???

- - -

- - Status file parser/generator - -

- 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 dpkg - -BORGiE on a file system.

- - Package file parser/generator - -

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

- - Dependency module - -

- -

dependency/conflict determination and linking

- - -

reverse dependency generator. Maybe merged with above

- - -

- - Package ordering Module - -

Create an ordering of the actions to be taken.

- - Event generator - -

module to interact with dpkg

- - - - - Data flow and conversions analysis. -

- - ____________ - __\|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 | - |___________| - - -

dpkg also interacts with status and available files.

- - -

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

- -

The other focal point for APT is the user interface.

- - - 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 @@ + + + %aptverbatiment; +]> + + + +dpkg technical manual + + + + + + Tom Leestom@lpsg.demon.co.uk + + + +Version &apt-product-version; + + + +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. + + + +1997Tom Lees + + +License Notice + +APT and this document are free software; you can redistribute them and/or +modify them under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or (at your +option) any later version. + + +For more details, on Debian systems, see the file +/usr/share/common-licenses/GPL for the full license. + + + + + +Quick summary of dpkg's external interface + +
Control files + +The basic dpkg package control file supports the following major features:- + + + + +5 types of dependencies:- + + + + +Pre-Depends, which must be satisfied before a package may be unpacked + + + + +Depends, which must be satisfied before a package may be configured + + + + +Recommends, to specify a package which if not installed may severely limit the +usefulness of the package + + + + +Suggests, to specify a package which may increase the productivity of the +package + + + + +Conflicts, to specify a package which must NOT be installed in order for the +package to be configured + + + + +Breaks, to specify a package which is broken by the package and which should +therefore not be configured while broken + + + + +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:- + + + + +"<<" - less than + + + + +"<=" - less than or equal to + + + + +">>" - greater than + + + + +">=" - greater than or equal to + + + + +"==" - equal to + + + + + + +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. + + + + +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. + + + +
+ +
The dpkg status area + +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). + + +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:- + + + + +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". + + + + +status - this file contains information on the following things for every +package:- + + + + +Whether it is installed, not installed, unpacked, removed, failed +configuration, or half-installed (deconfigured in favour of another package). + + + + +Whether it is selected as install, hold, remove, or purge. + + + + +If it is "ok" (no installation problems), or "not-ok". + + + + +It usually also contains the section and priority (so that dselect may classify +packages not in available) + + + + +For packages which did not initially appear in the "available" file when they +were installed, the other control information for them. + + + + +The exact format for the "Status:" field is: + + + Status: Want Flag Status + + +Where Want may be one of +unknown, install, +hold, deinstall, +purge. Flag may +be one of ok, reinstreq, +hold, +hold-reinstreq. Status may +be one of not-installed, unpacked, +half-configured, installed, +half-installed config-files, +post-inst-failed, removal-failed. +The states are as follows:- + + + +not-installed + + +No files are installed from the package, it has no config files left, it +uninstalled cleanly if it ever was installed. + + + + +unpacked + + +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. + + + + +half-configured + + +The package was installed and unpacked, but the postinst script failed in some +way. + + + + +installed + + +All files for the package are installed, and the configuration was also +successful. + + + + +half-installed + + +An attempt was made to remove the packagem but there was a failure in the +prerm script. + + + + +config-files + + +The package was "removed", not "purged". The config files are left, but +nothing else. + + + + +post-inst-failed + + +Old name for half-configured. Do not use. + + + + +removal-failed + + +Old name for half-installed. Do not use. + + + + + +The two last items are only left in dpkg for compatibility - they are +understood by it, but never written out in this form. + + +Please see the dpkg source code, lib/parshelp.c, +statusinfos, eflaginfos and +wantinfos for more details. + + + + +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. + + + + +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. + + + + +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. + + + + +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. + + + + +updates - directory used internally by dpkg. This is discussed later, in the +section . + + + + +parts - temporary directory used by dpkg-split + + + +
+ +
The dpkg library files + +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). + + +The following files may be found in each of these subdirectories:- + + + + +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. + + + + +desc.<name> - Contains the long description displayed by dselect +when the cursor is put over the <name> method. + + + + +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). + + + + +install - Script/program called when the "install" option of dselect is run +with this method. Same arguments as for setup. + + + + +update - Script/program called when the "update" option of dselect is +run. Same arguments as for setup/install. + + + +
+ +
The "dpkg" command-line utility + +
"Documented" command-line interfaces + +As yet unwritten. You can refer to the other manuals for now. See +dpkg8. + +
+ +
Environment variables which dpkg responds to + + + +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. + + + + +SHELL - used to determine which shell to run in the case when DPKG_NO_TSTP +is set. + + + + +CC - used as the C compiler to call to determine the target architecture. The +default is "gcc". + + + + +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:- + + + + +ldconfig + + + + +start-stop-daemon + + + + +install-info + + + + +update-rc.d + + + + + +
+ +
Assertions + +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. + + +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):- + + + + +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. + + + + +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. + + + + +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. + +
+ +
--predep-package + +This strange option is described as follows in the source code: + + +/* 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 + */ + + +On further inspection of the source code, it appears that what is does is +this:- + + + + +Looks at the packages in the database which are selected as "install", +and are installed. + + + + +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. + + + + +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. + + + + +It then continues this for every dependency of the initial package. + + + + +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). + +
+ +
+ + + +dpkg-deb and .deb file internals + +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. + + +
The .deb archive format + +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:- + + + + +debian-binary + + + + +control.tar.gz + + + + +data.tar.gz + + + + +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. + +
+ +
The dpkg-deb command-line + +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:- + + + + +--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. + + + + +--contents (-c) <debfile> - Lists the contents of the "data.tar.gz" +member. + + + + +--control (-e) <debfile> - Extracts the control archive into a directory +called DEBIAN. Alternatively, with another argument, it will extract it into a +different directory. + + + + +--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. + + + + +--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. + + + + +--extract (-x) <debfile> <dir> - Extracts the data archive of a +debian package under the directory <dir>. + + + + +--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. + + + + +--fsys-tarfile <debfile> - This option outputs a gunzip'd version of +data.tar.gz to stdout. + + + + +--new - sets the archive format to be used to the new Debian format + + + + +--old - sets the archive format to be used to the old Debian format + + + + +--debug - Tells dpkg-deb to produce debugging output + + + + +--nocheck - Tells dpkg-deb not to check the sanity of the control file + + + + +--help (-h) - Gives a help message + + + + +--version - Shows the version number + + + + +--licence/--license (UK/US spellings) - Shows a brief outline of the GPL + + + + +
Internal checks used by dpkg-deb when building packages + +Here is a list of the internal checks used by dpkg-deb when building +packages. It is in the order they are done. + + + + +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. + + + + +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:- + + + + +The package name is checked to see if it contains any invalid characters (see + for this). + + + + +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. + + + + +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. + + + + +dpkg-deb then checks that the control file contains a valid version number. + + + + + + +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. + + + + +Next, dpkg-deb checks for the <dir>/DEBIAN directory. It complains if it +doesn't exist, or if it has permissions < 0755, or > 0775. + + + + +It then checks that all the files in this subdir are either symlinks or plain +files, and have permissions between 0555 and 0775. + + + + +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. + + + +
+ +
+ + + +dpkg internals + +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. + + +
Updates + +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 +scandir3, +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. + + +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. + + +These files are created internally by dpkg's "checkpoint" function, and are +cleaned up when dpkg exits cleanly. + + +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. + + +The other option would be to sync-rewrite the status file after each operation, +which would kill performance. + + +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. + +
+ +
What happens when dpkg reads the database + +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. + + +More information on updates is given above. + +
+ +
How dpkg compares version numbers + +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. + + +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. + + +Here are a few examples of how these rules apply:- + + +15 > 10 +0010 == 10 + +d.r > dsr +32.d.r == 0032.d.r +d.rnr < d.rnrn + +
+ + + + 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 @@ - - -dpkg technical manual - -Tom Lees tom@lpsg.demon.co.uk -$Id: dpkg-tech.sgml,v 1.3 2003/02/12 15:05:45 doogie Exp $ - - -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. - - - -Copyright © Tom Lees, 1997. -

-APT and this document are free software; you can redistribute them and/or -modify them under the terms of the GNU General Public License as published -by the Free Software Foundation; either version 2 of the License, or (at your -option) any later version. - -

-For more details, on Debian systems, see the file -/usr/share/common-licenses/GPL for the full license. - - - - -Quick summary of dpkg's external interface -Control files - -

-The basic dpkg package control file supports the following major features:- - - -5 types of dependencies:- - - Pre-Depends, which must be satisfied before a package may be - unpacked - Depends, which must be satisfied before a package may be - configured - Recommends, to specify a package which if not installed may - severely limit the usefulness of the package - Suggests, to specify a package which may increase the - productivity of the package - Conflicts, to specify a package which must NOT be installed - in order for the package to be configured - Breaks, to specify a package which is broken by the - package and which should therefore not be configured while broken - -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:- - - "<<" - less than - "<=" - less than or equal to - ">>" - greater than - ">=" - greater than or equal to - "==" - equal to - -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. -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. - - -The dpkg status area - -

-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). - -

-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:- - - -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". -status - this file contains information on the following things for -every package:- - - Whether it is installed, not installed, unpacked, removed, - failed configuration, or half-installed (deconfigured in - favour of another package). - Whether it is selected as install, hold, remove, or purge. - If it is "ok" (no installation problems), or "not-ok". - It usually also contains the section and priority (so that - dselect may classify packages not in available) - For packages which did not initially appear in the "available" - file when they were installed, the other control information - for them. - -

- The exact format for the "Status:" field is: - - Status: Want Flag Status - - Where Want may be one of unknown, install, - hold, deinstall, purge. Flag - may be one of ok, reinstreq, hold, - hold-reinstreq. - Status may be one of not-installed, unpacked, - half-configured, installed, half-installed - config-files, post-inst-failed, removal-failed. - The states are as follows:- - - not-installed - No files are installed from the package, it has no config files - left, it uninstalled cleanly if it ever was installed. - unpacked - 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. - half-configured - The package was installed and unpacked, but the postinst script - failed in some way. - installed - All files for the package are installed, and the configuration - was also successful. - half-installed - An attempt was made to remove the packagem but there was a failure - in the prerm script. - config-files - The package was "removed", not "purged". The config files are left, - but nothing else. - post-inst-failed - Old name for half-configured. Do not use. - removal-failed - Old name for half-installed. Do not use. - - The two last items are only left in dpkg for compatibility - they are - understood by it, but never written out in this form. - -

- Please see the dpkg source code, lib/parshelp.c, - statusinfos, eflaginfos and wantinfos for more - details. - -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. -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. -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. -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. -updates - directory used internally by dpkg. This is discussed later, -in the section . -parts - temporary directory used by dpkg-split - - -The dpkg library files - -

-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). - -

-The following files may be found in each of these subdirectories:- - - -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. -desc.<name> - Contains the long description displayed by dselect -when the cursor is put over the <name> method. -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). -install - Script/program called when the "install" option of dselect is -run with this method. Same arguments as for setup. -update - Script/program called when the "update" option of dselect is -run. Same arguments as for setup/install. - - -The "dpkg" command-line utility - -"Documented" command-line interfaces - -

-As yet unwritten. You can refer to the other manuals for now. See -. - -Environment variables which dpkg responds to - -

- -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. -SHELL - used to determine which shell to run in the case when -DPKG_NO_TSTP is set. -CC - used as the C compiler to call to determine the target architecture. -The default is "gcc". -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:- - - ldconfig - start-stop-daemon - install-info - update-rc.d - - - -Assertions - -

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

-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):- - - -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. -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. - - -

-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. - ---predep-package - -

-This strange option is described as follows in the source code: - - -/* 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 - */ - - -

-On further inspection of the source code, it appears that what is does is -this:- - - -Looks at the packages in the database which are selected as "install", -and are installed. -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. -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. -It then continues this for every dependency of the initial package. - - -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). - -dpkg-deb and .deb file internals - -

-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. - -The .deb archive format - -

-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:- - - -debian-binary -control.tar.gz -data.tar.gz - - -

-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. - -The dpkg-deb command-line - -

-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:- - - ---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. ---contents (-c) <debfile> - Lists the contents of the "data.tar.gz" -member. ---control (-e) <debfile> - Extracts the control archive into a -directory called DEBIAN. Alternatively, with another argument, it will extract -it into a different directory. ---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. ---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. ---extract (-x) <debfile> <dir> - Extracts the data archive -of a debian package under the directory <dir>. ---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. ---fsys-tarfile <debfile> - This option outputs a gunzip'd version -of data.tar.gz to stdout. ---new - sets the archive format to be used to the new Debian format ---old - sets the archive format to be used to the old Debian format ---debug - Tells dpkg-deb to produce debugging output ---nocheck - Tells dpkg-deb not to check the sanity of the control file ---help (-h) - Gives a help message ---version - Shows the version number ---licence/--license (UK/US spellings) - Shows a brief outline of the GPL - - -Internal checks used by dpkg-deb when building packages - -

-Here is a list of the internal checks used by dpkg-deb when building packages. -It is in the order they are done. - - -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. -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:- - - The package name is checked to see if it contains any invalid - characters (see for this). - 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. - 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. - dpkg-deb then checks that the control file contains a valid - version number. - -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. -Next, dpkg-deb checks for the <dir>/DEBIAN directory. It complains -if it doesn't exist, or if it has permissions < 0755, or > 0775. -It then checks that all the files in this subdir are either symlinks -or plain files, and have permissions between 0555 and 0775. -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. - - -dpkg internals - -

-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. - -Updates - -

-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 , 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. - -

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

-These files are created internally by dpkg's "checkpoint" function, and are -cleaned up when dpkg exits cleanly. - -

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

-The other option would be to sync-rewrite the status file after each -operation, which would kill performance. - -

-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. - -What happens when dpkg reads the database - -

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

-More information on updates is given above. - -How dpkg compares version numbers - -

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

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

-Here are a few examples of how these rules apply:- - - -15 > 10 -0010 == 10 - -d.r > dsr -32.d.r == 0032.d.r -d.rnr < d.rnrn - - - diff --git a/doc/files.dbk b/doc/files.dbk new file mode 100644 index 000000000..675c92664 --- /dev/null +++ b/doc/files.dbk @@ -0,0 +1,392 @@ + + + %aptverbatiment; +]> + + + +APT Files + + + + + + Jason Gunthorpejgg@debian.org + + + +Version &apt-product-version; + + + +This document describes the complete implementation and format of the installed +APT directory structure. It also serves as guide to how APT views the Debian +archive. + + + +1998-1999Jason Gunthorpe + + +License Notice + +"APT" and this document are free software; you can redistribute them and/or +modify them under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or (at your +option) any later version. + + +For more details, on Debian systems, see the file +/usr/share/common-licenses/GPL for the full license. + + + + + +Introduction + +

General + +This document serves two purposes. The first is to document the installed +directory structure and the format and purpose of each file. The second +purpose is to document how APT views the Debian archive and deals with multiple +package files. + + +The var directory structure is as follows: + + + /var/lib/apt/ + lists/ + partial/ + periodic/ + extended_states + cdroms.list + /var/cache/apt/ + archives/ + partial/ + pkgcache.bin + srcpkgcache.bin + /etc/apt/ + sources.list.d/ + apt.conf.d/ + preferences.d/ + trusted.gpg.d/ + sources.list + apt.conf + apt_preferences + trusted.gpg + /usr/lib/apt/ + methods/ + bzip2 + cdrom + copy + file + ftp + gpgv + gzip + http + https + lzma + rred + rsh + ssh + + +As is specified in the FHS 2.1 /var/lib/apt is used for application data that +is not expected to be user modified. /var/cache/apt is used for regeneratable +data and is where the package cache and downloaded .debs go. /etc/apt is the +place where configuration should happen and /usr/lib/apt is the place where the +apt and other packages can place binaries which can be used by the acquire +system of APT. + +
+ + + +Files + +
Files and fragment directories in /etc/apt + +All files in /etc/apt are used to modify specific aspects of APT. To enable +other packages to ship needed configuration herself all these files have a +fragment directory packages can place their files in instead of mangling with +the main files. The main files are therefore considered to be only used by the +user and not by a package. The documentation omits this directories most of +the time to be easier readable, so every time the documentation includes a +reference to a main file it really means the file or the fragment directories. + +
+ +
Distribution Source list (sources.list) + +The distribution source list is used to locate archives of the debian +distribution. It is designed to support any number of active sources and to +support a mix of source media. The file lists one source per line, with the +fastest source listed first. The format of each line is: + + +type uri args + + +The first item, type, indicates the format for the +remainder of the line. It is designed to indicate the structure of the +distribution the line is talking about. Currently the only defined values are +deb and deb-src which indicate a +standard debian (source) archive with a dists directory. More about these +types and the URI specification can be found in the sources.list manpage. + + +
Hashing the URI + +All permanent information acquired from any of the sources is stored in the +lists directory. Thus, there must be a way to relate the filename in the lists +directory to a line in the sourcelist. To simplify things this is done by +quoting the URI and treating _'s as quoteable characters and converting / +to _. The URI spec says this is done by converting a sensitive character +into %xx where xx is the hexadecimal representation from the ASCII character +set. Examples: + + +http://www.debian.org/archive/dists/stable/binary-i386/Packages +/var/lib/apt/lists/www.debian.org_archive_dists_stable_binary-i386_Packages + +cdrom:Debian 1.3/debian/Packages +/var/lib/apt/info/Debian%201.3_debian_Packages + + +The other alternative that was considered was to use a deep directory structure +but this poses two problems, it makes it very difficult to prune directories +back when sources are no longer used and complicates the handling of the +partial directory. This gives a very simple way to deal with all of the +situations that can arise. Also note that the same rules described in the +Archive Directory section regarding the partial sub dir +apply here as well. + +
+ +
+ +
Extended States File (extended_states) + +The extended_states file serves the same purpose as the normal dpkg status +file (/var/lib/dpkg/status) except that it stores information unique to +apt. This includes currently only the autoflag but is open to store more +unique data that come up over time. It duplicates nothing from the normal +dpkg status file. Please see other APT documentation for a discussion of +the exact internal behavior of these fields. The Package and the Architecture +field are placed directly before the new fields to indicate which package +they apply to. The new fields are as follows: + + + +Auto-Installed + + +The Auto flag can be 1 (Yes) or 0 (No) and controls whether the package was +automatical installed to satisfy a dependency or if the user requested the +installation + + + + +
+ +
Binary Package Cache (srcpkgcache.bin and pkgcache.bin) + +Please see cache.sgml for a complete description of what this file +is. The cache file is updated whenever the contents of the lists +directory changes. If the cache is erased, corrupted or of a non-matching +version it will be automatically rebuilt by all of the tools that need +it. srcpkgcache.bin contains a cache of all of the +package files in the source list. This allows regeneration of the cache +when the status files change to use a prebuilt version for greater speed. + +
+ +
Downloads Directory (archives) + +The archives directory is where all downloaded .deb archives go. When the file +transfer is initiated the deb is placed in partial. Once the file is fully +downloaded and its MD5 hash and size are verified it is moved from partial +into archives/. Any files found in archives/ can be assumed to be verified. + + +No directory structure is transferred from the receiving site and all .deb file +names conform to debian conventions. No short (msdos) filename should be +placed in archives. If the need arises .debs should be unpacked, scanned and +renamed to their correct internal names. This is mostly to prevent file name +conflicts but other programs may depend on this if convenient. A conforming +.deb is one of the form, name_version_arch.deb. Our archive scripts do not +handle epochs, but they are necessary and should be re-inserted. If necessary +_'s and :'s in the fields should be quoted using the % convention. It must be +possible to extract all 3 fields by examining the file name. Downloaded .debs +must be found in one of the package lists with an exact name + version match.. + +
+ +
The Methods Directory (/usr/lib/apt/methods) + +The Methods directory is more fully described in the APT Methods interface +document. + +
+ +
The Configuration File (/etc/apt/apt.conf) + +The configuration file (and the associated fragments directory +/etc/apt/apt.conf.d/) is described in the apt.conf manpage. + +
+ +
The trusted.gpg File (/etc/apt/trusted.gpg) + +The trusted.gpg file (and the files in the associated fragments directory +/etc/apt/trusted.gpg.d/) is a binary file including the keyring used by apt to +validate that the information (e.g. the Release file) it downloads are really +from the distributor it clams to be and is unmodified and is therefore the last +step in the chain of trust between the archive and the end user. This security +system is described in the apt-secure manpage. + +
+ +
The Release File + +This file plays an important role in how APT presents the archive to the +user. Its main purpose is to present a descriptive name for the source of +each version of each package. It also is used to detect when new versions +of debian are released. It augments the package file it is associated with +by providing meta information about the entire archive which the Packages +file describes. + + +The full name of the distribution for presentation to the user is formed as +'label version archive', with a possible extended name being 'label version +archive component'. + + +The file is formed as the package file (RFC-822) with the following tags +defined: + + + +Archive + + +This is the common name we give our archives, such as +stable or unstable. + + + + +Component + + +Refers to the sub-component of the archive, main, +contrib etc. Component may be omitted if there are no +components for this archive. + + + + +Version + + +This is a version string with the same properties as in the Packages file. It +represents the release level of the archive. + + + + +Origin + + +This specifies who is providing this archive. In the case of Debian the string +will read 'Debian'. Other providers may use their own string + + + + +Label + + +This carries the encompassing name of the distribution. For Debian proper this +field reads 'Debian'. For derived distributions it should contain their proper +name. + + + + +Architecture + + +When the archive has packages for a single architecture then the Architecture +is listed here. If a mixed set of systems are represented then this should +contain the keyword mixed. + + + + +NotAutomatic + + +A Yes/No flag indicating that the archive is extremely unstable and its +version's should never be automatically selected. This is to be used by +experimental. + + + + +Description + + +Description is used to describe the release. For instance experimental would +contain a warning that the packages have problems. + + + + + +The location of the Release file in the archive is very important, it must be +located in the same location as the packages file so that it can be located in +all situations. The following is an example for the current stable release, +1.3.1r6 + + +Archive: stable +Component: main +Version: 1.3.1r6 +Origin: Debian +Label: Debian +Architecture: i386 + + +This is an example of experimental, + + +Archive: experimental +Version: 0 +Origin: Debian +Label: Debian +Architecture: mixed +NotAutomatic: Yes + + +And unstable, + + +Archive: unstable +Component: main +Version: 2.1 +Origin: Debian +Label: Debian +Architecture: i386 + +
+ + + + + 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 @@ - - - -APT Files - -Jason Gunthorpe jgg@debian.org -$Id: files.sgml,v 1.12 2003/04/26 23:26:13 doogie Exp $ - - -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. - - - -Copyright © Jason Gunthorpe, 1998-1999. -

-"APT" and this document are free software; you can redistribute them and/or -modify them under the terms of the GNU General Public License as published -by the Free Software Foundation; either version 2 of the License, or (at your -option) any later version. - -

-For more details, on Debian systems, see the file -/usr/share/common-licenses/GPL for the full license. - - - - -Introduction - - -General - -

-This document serves two purposes. The first is to document the installed -directory structure and the format and purpose of each file. The second -purpose is to document how APT views the Debian archive and deals with -multiple package files. - -

-The var directory structure is as follows: - - /var/lib/apt/ - lists/ - partial/ - periodic/ - extended_states - cdroms.list - /var/cache/apt/ - archives/ - partial/ - pkgcache.bin - srcpkgcache.bin - /etc/apt/ - sources.list.d/ - apt.conf.d/ - preferences.d/ - trusted.gpg.d/ - sources.list - apt.conf - apt_preferences - trusted.gpg - /usr/lib/apt/ - methods/ - bzip2 - cdrom - copy - file - ftp - gpgv - gzip - http - https - lzma - rred - rsh - ssh - - -

-As is specified in the FHS 2.1 /var/lib/apt is used for application -data that is not expected to be user modified. /var/cache/apt is used -for regeneratable data and is where the package cache and downloaded .debs -go. /etc/apt is the place where configuration should happen and -/usr/lib/apt is the place where the apt and other packages can place -binaries which can be used by the acquire system of APT. - - - -Files - - -Files and fragment directories in /etc/apt - -

-All files in /etc/apt are used to modify specific aspects of APT. To enable -other packages to ship needed configuration herself all these files have -a fragment directory packages can place their files in instead of mangling -with the main files. The main files are therefore considered to be only -used by the user and not by a package. The documentation omits this directories -most of the time to be easier readable, so every time the documentation includes -a reference to a main file it really means the file or the fragment directories. - - - -Distribution Source list (sources.list) - -

-The distribution source list is used to locate archives of the debian -distribution. It is designed to support any number of active sources and to -support a mix of source media. The file lists one source per line, with the -fastest source listed first. The format of each line is: - -

-type uri args - -

-The first item, type, indicates the format for the remainder -of the line. It is designed to indicate the structure of the distribution -the line is talking about. Currently the only defined values are deb -and deb-src which indicate a standard debian (source) archive with a -dists directory. More about these types and the URI specification can be found -in the sources.list manpage. - -Hashing the URI -

-All permanent information acquired from any of the sources is stored in the -lists directory. Thus, there must be a way to relate the filename in the -lists directory to a line in the sourcelist. To simplify things this is -done by quoting the URI and treating _'s as quoteable characters and -converting / to _. The URI spec says this is done by converting a -sensitive character into %xx where xx is the hexadecimal representation -from the ASCII character set. Examples: - - -http://www.debian.org/archive/dists/stable/binary-i386/Packages -/var/lib/apt/lists/www.debian.org_archive_dists_stable_binary-i386_Packages - -cdrom:Debian 1.3/debian/Packages -/var/lib/apt/info/Debian%201.3_debian_Packages - - -

-The other alternative that was considered was to use a deep directory -structure but this poses two problems, it makes it very difficult to prune -directories back when sources are no longer used and complicates the handling -of the partial directory. This gives a very simple way to deal with all -of the situations that can arise. Also note that the same rules described in -the Archive Directory section regarding the partial sub dir apply -here as well. - - - - - - -Extended States File (extended_states) - -

-The extended_states file serves the same purpose as the normal dpkg status file -(/var/lib/dpkg/status) except that it stores information unique to apt. -This includes currently only the autoflag but is open to store more -unique data that come up over time. It duplicates nothing from the normal -dpkg status file. Please see other APT documentation for a discussion -of the exact internal behavior of these fields. The Package and the -Architecture field are placed directly before the new fields to indicate -which package they apply to. The new fields are as follows: - - -Auto-Installed - The Auto flag can be 1 (Yes) or 0 (No) and controls whether the package - was automatical installed to satisfy a dependency or if the user requested - the installation - - - - - -Binary Package Cache (srcpkgcache.bin and pkgcache.bin) - -

-Please see cache.sgml for a complete description of what this file is. The -cache file is updated whenever the contents of the lists directory changes. -If the cache is erased, corrupted or of a non-matching version it will -be automatically rebuilt by all of the tools that need it. -srcpkgcache.bin contains a cache of all of the package files in the -source list. This allows regeneration of the cache when the status files -change to use a prebuilt version for greater speed. - - - - -Downloads Directory (archives) - -

-The archives directory is where all downloaded .deb archives go. When the -file transfer is initiated the deb is placed in partial. Once the file -is fully downloaded and its MD5 hash and size are verified it is moved -from partial into archives/. Any files found in archives/ can be assumed -to be verified. - -

-No directory structure is transferred from the receiving site and all .deb -file names conform to debian conventions. No short (msdos) filename should -be placed in archives. If the need arises .debs should be unpacked, scanned -and renamed to their correct internal names. This is mostly to prevent -file name conflicts but other programs may depend on this if convenient. -A conforming .deb is one of the form, name_version_arch.deb. Our archive -scripts do not handle epochs, but they are necessary and should be re-inserted. -If necessary _'s and :'s in the fields should be quoted using the % convention. -It must be possible to extract all 3 fields by examining the file name. -Downloaded .debs must be found in one of the package lists with an exact -name + version match.. - - - - - The Methods Directory (/usr/lib/apt/methods) - -

-The Methods directory is more fully described in the APT Methods interface -document. - - - - - The Configuration File (/etc/apt/apt.conf) - -

-The configuration file (and the associated fragments directory -/etc/apt/apt.conf.d/) is described in the apt.conf manpage. - - - - - The trusted.gpg File (/etc/apt/trusted.gpg) - -

-The trusted.gpg file (and the files in the associated fragments directory -/etc/apt/trusted.gpg.d/) is a binary file including the keyring used -by apt to validate that the information (e.g. the Release file) it -downloads are really from the distributor it clams to be and is -unmodified and is therefore the last step in the chain of trust between -the archive and the end user. This security system is described in the -apt-secure manpage. - - - - - The Release File - -

-This file plays an important role in how APT presents the archive to the -user. Its main purpose is to present a descriptive name for the source -of each version of each package. It also is used to detect when new versions -of debian are released. It augments the package file it is associated with -by providing meta information about the entire archive which the Packages -file describes. - -

-The full name of the distribution for presentation to the user is formed -as 'label version archive', with a possible extended name being -'label version archive component'. - -

-The file is formed as the package file (RFC-822) with the following tags -defined: - - -Archive -This is the common name we give our archives, such as stable or -unstable. - -Component -Refers to the sub-component of the archive, main, contrib -etc. Component may be omitted if there are no components for this archive. - -Version -This is a version string with the same properties as in the Packages file. -It represents the release level of the archive. - -Origin -This specifies who is providing this archive. In the case of Debian the -string will read 'Debian'. Other providers may use their own string - -Label -This carries the encompassing name of the distribution. For Debian proper -this field reads 'Debian'. For derived distributions it should contain their -proper name. - -Architecture -When the archive has packages for a single architecture then the Architecture -is listed here. If a mixed set of systems are represented then this should -contain the keyword mixed. - -NotAutomatic -A Yes/No flag indicating that the archive is extremely unstable and its -version's should never be automatically selected. This is to be used by -experimental. - -Description -Description is used to describe the release. For instance experimental would -contain a warning that the packages have problems. - - -

-The location of the Release file in the archive is very important, it must -be located in the same location as the packages file so that it can be -located in all situations. The following is an example for the current stable -release, 1.3.1r6 - - -Archive: stable -Component: main -Version: 1.3.1r6 -Origin: Debian -Label: Debian -Architecture: i386 - - -This is an example of experimental, - -Archive: experimental -Version: 0 -Origin: Debian -Label: Debian -Architecture: mixed -NotAutomatic: Yes - - -And unstable, - -Archive: unstable -Component: main -Version: 2.1 -Origin: Debian -Label: Debian -Architecture: i386 - - - - - - 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 @@ + + + %aptverbatiment; +]> + + + +APT User's Guide + + + + + + Jason Gunthorpejgg@debian.org + + + +Version &apt-product-version; + + + +This document provides an overview of how to use the the APT package manager. + + + +1998Jason Gunthorpe + + +License Notice + +"APT" and this document are free software; you can redistribute them and/or +modify them under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or (at your +option) any later version. + + + + + +For more details, on Debian systems, see the file +/usr/share/common-licenses/GPL for the full license. + + + + + +General + +The APT package currently contains two sections, the APT +dselect method and the apt-get command +line user interface. Both provide a way to install and remove packages as well +as download new packages from the Internet. + + +

Anatomy of the Package System + +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. + + +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. + + +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. + + +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. + + +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. + + +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. + + +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. + +
+ + + +apt-get + +apt-get provides a simple way to install packages from the +command line. Unlike dpkg, apt-get does +not understand .deb files, it works with the package's proper name and can only +install .deb archives from a Source. + + +The first If you are using an http proxy server you must set +the http_proxy environment variable first, see sources.list(5) + thing that should be done before using apt-get +is to fetch the package lists from the Sources so that it +knows what packages are available. This is done with apt-get +update. For instance, + + +# 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 + + +Once updated there are several commands that can be used: + + + +upgrade + + +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. dselect or +apt-get install can be used to force these packages to +install. + + + + +install + + +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. + + + + +dist-upgrade + + +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 +dselect. Once dist-upgrade has completed then +dselect can be used to install any packages that may have +been left out. + + +It is important to closely look at what dist-upgrade is going to do, its +decisions may sometimes be quite surprising. + + + + + +apt-get has several command line options that are detailed +in its man page, +apt-get8. The +most useful option is -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 +-d is used the downloaded archives can be installed by +simply running the command that caused them to be downloaded again without +-d. + + + +DSelect + +The APT dselect method provides the complete +APT system with the dselect package selection +GUI. dselect is used to select the packages to be +installed or removed and APT actually installs them. + + +To enable the APT method you need to select [A]ccess in +dselect and then choose the APT method. You will be +prompted for a set of 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. + + + 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]: + + +The 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. + + + 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]: + + +The distribution refers to the Debian version in the archive, +stable refers to the latest released version +and unstable refers to the developmental +version. 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. + + + Please give the components to get + The components are typically something like: main contrib non-free + + Components [main contrib non-free]: + + +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. + + +Any number of sources can be added, the setup script will continue to prompt +until you have specified all that you want. + + +Before starting to use dselect it is necessary to update +the available list by selecting [U]pdate from the menu. This is a superset of +apt-get update that makes the fetched information available +to dselect. [U]pdate must be performed even if +apt-get update has been run before. + + +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. + + +By default APT will automatically remove the package (.deb) files once they +have been successfully installed. To change this behavior place +Dselect::clean "prompt"; in /etc/apt/apt.conf. + + + +The Interface + +Both that APT dselect method and 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. The +dselect method actually is a set of wrapper scripts to +apt-get. The method actually provides more functionality +than is present in apt-get alone. 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. + + +
Startup + +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 +apt-get check. + + +# apt-get check +Reading Package Lists... Done +Building Dependency Tree... Done + + +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. + + +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 apt-get will refuse to run. + + +# 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) + + +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. + + +There are two ways a system can get into a broken state like this. The +first is caused by dpkg missing some subtle relationships +between packages when performing upgrades. APT however +considers all known dependencies and attempts to prevent broken +packages . 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. + + +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 -f option to apt-get +will cause APT to deduce a possible solution to the problem and then +continue on. The APT dselect method always supplies +the -f option to allow for easy continuation of failed +maintainer scripts. + + +However, if the -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. + +
+ +
The Status Report + +Before proceeding 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 -f option +and any other relevant activities to the command being executed. + + +
The Extra Package list + +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 + + +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 install command. The listed packages are +often the result of an Auto Install. + +
+ +
The Packages to Remove + +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 + + +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 +-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. + +
+ +
The New Packages list + +The following NEW packages will installed: + zlib1g xlib6g perl-base libgdbmg1 quake-lib gmp2 pgp-i python-base + + +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. + +
+ +
The Kept Back list + +The following packages have been kept back + compface man-db tetex-base msql libpaper svgalib1 + gs snmp arena lynx xpat2 groff xscreensaver + + +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 apt-get install or by using +dselect to resolve their problems. + +
+ +
Held Packages warning + +The following held packages will be changed: + cvs + + +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. + +
+ +
Final summary + +Finally, APT will print out a summary of all the changes that will occur. + + +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. + + +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. + + +Some other reports can be generated by using the -u option to show packages to +upgrade, they are similar to the previous examples. + +
+ +
+ +
The Status Display + +During the download of archives and package files APT prints out a series of +status messages. + + +# 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 + + +The lines starting with 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 apt-get update estimates the percent done which +causes some inaccuracies. + + +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 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. + + +Inside of the single quote is an informative string indicating the progress of +the negotiation phase of the download. Typically it progresses from +Connecting to Waiting for file to +Downloading or Resuming. The final +value is the number of bytes downloaded from the remote site. Once the +download begins this is represented as 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. + + +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 -q option to remove the status +display. + +
+ +
Dpkg + +APT uses dpkg for installing the archives and will +switch over to the dpkg interface once downloading is +completed. 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. + +
+ + + + 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 @@ - - - -APT User's Guide - -Jason Gunthorpe jgg@debian.org -$Id: guide.sgml,v 1.7 2003/04/26 23:26:13 doogie Exp $ - - -This document provides an overview of how to use the the APT package manager. - - - -Copyright © Jason Gunthorpe, 1998. -

-"APT" and this document are free software; you can redistribute them and/or -modify them under the terms of the GNU General Public License as published -by the Free Software Foundation; either version 2 of the License, or (at your -option) any later version. - -

-For more details, on Debian systems, see the file -/usr/share/common-licenses/GPL for the full license. - - - - - - -General - -

-The APT package currently contains two sections, the APT dselect -method and the apt-get command line user interface. Both provide -a way to install and remove packages as well as download new packages from -the Internet. - -Anatomy of the Package System -

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

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

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

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

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

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

-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. - - - - - - -apt-get - -

-apt-get provides a simple way to install packages from the command -line. Unlike dpkg, apt-get does not understand .deb files, -it works with the package's proper name and can only install .deb archives from -a Source. - -

-The first If you are using an http proxy server you must set the -http_proxy environment variable first, see sources.list(5) thing that -should be done before using apt-get is to fetch the package lists -from the Sources so that it knows what packages are -available. This is done with apt-get update. For instance, - -

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

-Once updated there are several commands that can be used: - -upgrade -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. -dselect or apt-get install can be used to force these -packages to install. - -install -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. - -dist-upgrade -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 dselect. -Once dist-upgrade has completed then dselect can be used to install -any packages that may have been left out. - -

-It is important to closely look at what dist-upgrade is going to do, its -decisions may sometimes be quite surprising. - - -

-apt-get has several command line options that are detailed in its -man page, . The most useful option is --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 -d is used the downloaded -archives can be installed by simply running the command that caused them to -be downloaded again without -d. - - - - - -DSelect -

-The APT dselect method provides the complete APT system with -the dselect package selection GUI. dselect is used to -select the packages to be installed or removed and APT actually installs them. - -

-To enable the APT method you need to select [A]ccess in dselect -and then choose the APT method. You will be prompted for a set of -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. - -

- - 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]: - - -

-The 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. - -

- - 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]: - - -

-The distribution refers to the Debian version in the archive, stable -refers to the latest released version and unstable refers to the -developmental version. 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. - -

- - Please give the components to get - The components are typically something like: main contrib non-free - - Components [main contrib non-free]: - - -

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

-Any number of sources can be added, the setup script will continue to -prompt until you have specified all that you want. - -

-Before starting to use dselect it is necessary to update the -available list by selecting [U]pdate from the menu. This is a superset of -apt-get update that makes the fetched information available to -dselect. [U]pdate must be performed even if apt-get update -has been run before. - -

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

-By default APT will automatically remove the package (.deb) files once they have been -successfully installed. To change this behavior place Dselect::clean -"prompt"; in /etc/apt/apt.conf. - - - - - -The Interface - -

-Both that APT dselect method and 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. - -The dselect method actually is a set of wrapper scripts -to apt-get. The method actually provides more functionality than -is present in apt-get alone. - -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. - - -Startup - -

-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 apt-get check. -

- -# apt-get check -Reading Package Lists... Done -Building Dependency Tree... Done - - -

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

-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 -apt-get will refuse to run. - -

- -# 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) - - -

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

-There are two ways a system can get into a broken state like this. The -first is caused by dpkg missing some subtle relationships between -packages when performing upgrades. APT however considers all known -dependencies and attempts to prevent broken packages. 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. - -

-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 -f option to apt-get will cause APT to deduce a -possible solution to the problem and then continue on. The APT dselect -method always supplies the -f option to allow for easy continuation -of failed maintainer scripts. - -

-However, if the -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. - - - -The Status Report - -

-Before proceeding 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 -f option and any other relevant -activities to the command being executed. - -The Extra Package list -

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

-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 install command. The listed packages are -often the result of an Auto Install. - - -The Packages to Remove -

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

-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 -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. - - -The New Packages list -

- -The following NEW packages will installed: - zlib1g xlib6g perl-base libgdbmg1 quake-lib gmp2 pgp-i python-base - - -

-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. - - -The Kept Back list -

- -The following packages have been kept back - compface man-db tetex-base msql libpaper svgalib1 - gs snmp arena lynx xpat2 groff xscreensaver - - -

-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 apt-get install or by using dselect -to resolve their problems. - - -Held Packages warning -

- -The following held packages will be changed: - cvs - - -

-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. - - -Final summary -

-Finally, APT will print out a summary of all the changes that will occur. - -

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

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

-Some other reports can be generated by using the -u option to show packages -to upgrade, they are similar to the previous examples. - - - -The Status Display -

-During the download of archives and package files APT prints out a series of -status messages. - -

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

-The lines starting with 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 -apt-get update estimates the percent done which causes some -inaccuracies. - -

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

-Inside of the single quote is an informative string indicating the progress -of the negotiation phase of the download. Typically it progresses from -Connecting to Waiting for file to Downloading or -Resuming. The final value is the number of bytes downloaded from the -remote site. Once the download begins this is represented as 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. - -

-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 -q option to remove the -status display. - - - -Dpkg - -

-APT uses dpkg for installing the archives and will switch -over to the dpkg interface once downloading is completed. -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. - - - - - - 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 @@ + + + %aptverbatiment; +]> + + + +APT Method Interface + + + + + + Jason Gunthorpejgg@debian.org + + + +Version &apt-product-version; + + + +This document describes the interface that APT uses to the archive access +methods. + + + +1998Jason Gunthorpe + + +License Notice + +"APT" and this document are free software; you can redistribute them and/or +modify them under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or (at your +option) any later version. + + +For more details, on Debian systems, see the file +/usr/share/common-licenses/GPL for the full license. + + + + + +Introduction + +

General + +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: + + + + +Remote methods that download files from a distant site + + + + +Resume of aborted downloads + + + + +Progress reporting + + + + +If-Modified-Since (IMS) checking for index files + + + + +In-Line MD5 generation + + + + +No-copy in-filesystem methods + + + + +Multi-media methods (like CD's) + + + + +Dynamic source selection for failure recovery + + + + +User interaction for user/password requests and media swaps + + + + +Global configuration + + + + +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. + +
+ +
Terms + +Several terms are used through out the document, they have specific meanings +which may not be immediately evident. To clarify they are summarized here. + + + +source + + +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. + + + + +archive file + + +Refers to a binary package archive (.deb, .rpm, etc). + + + + +source file + + +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. + + + + +URI + + +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: + + +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/ + + + + +method + + +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. + + + + +method instance + + +A specific running method. There can be more than one instance of each method +as APT is capable of concurrent method handling. + + + + +message + + +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 + + + + +acquire + + +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. + + + + +
+ + + +Specification + +
Overview + +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. + + +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. + + +In some instances APT may pre-invoke a method to allow things like file URI's +to determine how many files are available locally. + +
+ +
Message Overview + +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. + + + + +100 Capabilities - Method capabilities + + + + +101 Log - General Logging + + + + +102 Status - Inter-URI status reporting (login progress) + + + + +200 URI Start - URI is starting acquire + + + + +201 URI Done - URI is finished acquire + + + + +400 URI Failure - URI has failed to acquire + + + + +401 General Failure - Method did not like something sent to it + + + + +402 Authorization Required - Method requires authorization to access the URI. +Authorization is User/Pass + + + + +403 Media Failure - Method requires a media change + + + + +600 URI Acquire - Request a URI be acquired + + + + +601 Configuration - Sends the configuration space + + + + +602 Authorization Credentials - Response to the 402 message + + + + +603 Media Changed - Response to the 403 message + + + + +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. + + +The flow of messages starts with the method sending out a 100 +Capabilities and APT sending out a 601 +Configuration. After that APT begins sending 600 URI +Acquire and the method sends out 200 URI Start, +201 URI Done or 400 URI Failure. No +synchronization is performed, it is expected that APT will send 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. + +
+ +
Header Fields + +The following is a short index of the header fields that are supported + + + +URI + + +URI being described by the message + + + + +Filename + + +Location in the filesystem + + + + +Last-Modified + + +A time stamp in RFC1123 notation for use by IMS checks + + + + +IMS-Hit + + +The already existing item is valid + + + + +Size + + +Size of the file in bytes + + + + +Resume-Point + + +Location that transfer was started + + + + +MD5-Hash + + +Computed MD5 hash for the file + + + + +Message + + +String indicating some displayable message + + + + +Media + + +String indicating the media name required + + + + +Site + + +String indicating the site authorization is required for + + + + +User + + +Username for authorization + + + + +Password + + +Password for authorization + + + + +Fail + + +Operation failed + + + + +Drive + + +Drive the media should be placed in + + + + +Config-Item + + +A string of the form +item=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. + + + + +Single-Instance + + +Requires that only one instance of the method be run This is a yes/no value. + + + + +Pipeline + + +The method is capable of pipelining. + + + + +Local + + +The method only returns Filename: fields. + + + + +Send-Config + + +Send configuration to the method. + + + + +Needs-Cleanup + + +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. + + + + +Version + + +Version string for the method + + + + + +This is a list of which headers each status code can use + + + +100 Capabilities + + +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 + + + + +101 Log + + +A log message may be printed to the screen if debugging is enabled. This is +only for debugging the method. Fields: Message + + + + +102 Status + + +Message gives a progress indication for the method. It can be used to show +pre-transfer status for Internet type methods. Fields: Message + + + + +200 URI Start + + +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 + + + + +201 URI Done + + +Indicates that a URI has completed being transferred. It is possible to +specify a 201 URI Done without a 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 + + + + +400 URI Failure + + +Indicates a fatal URI failure. The URI is not retrievable from this source. As +with 201 URI Done 200 URI Start is +not required to precede this message Fields: URI, Message + + + + +401 General Failure + + +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 + + + + +402 Authorization Required + + +The method requires a Username and Password pair to continue. After sending +this message the method will expect APT to send a 602 Authorization +Credentials message with the required information. It is possible +for a method to send this multiple times. Fields: Site + + + + +403 Media Failure + + +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 + + + + +600 URI Acquire + + +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 + + + + +601 Configuration + + +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. + + + + +602 Authorization Credentials + + +This is sent in response to a 402 Authorization Required +message. It contains the entered username and password. Fields: Site, User, +Password + + + + +603 Media Changed + + +This is sent in response to a 403 Media Failure +message. It indicates that the user has changed media and it is safe +to proceed. Fields: Media, Fail + + + + +
+ +
Notes + +The methods supplied by the stock apt are: + + + + +cdrom - For Multi-Disc CD-ROMs + + + + +copy - (internal) For copying files around the filesystem + + + + +file - For local files + + + + +gzip - (internal) For decompression + + + + +http - For HTTP servers + + + + +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: + + +http://foo.com/Packages.gz -> /bar/Packages.gz +gzip:/bar/Packages.gz -> /bar/Packages.decomp +rename Packages.decomp to /final/Packages + + +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. + +
+ + + + 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 @@ - - - -APT Method Interface - -Jason Gunthorpe jgg@debian.org -$Id: method.sgml,v 1.10 2003/02/12 15:05:46 doogie Exp $ - - -This document describes the interface that APT uses to the archive -access methods. - - - -Copyright © Jason Gunthorpe, 1998. -

-"APT" and this document are free software; you can redistribute them and/or -modify them under the terms of the GNU General Public License as published -by the Free Software Foundation; either version 2 of the License, or (at your -option) any later version. - -

-For more details, on Debian systems, see the file -/usr/share/common-licenses/GPL for the full license. - - - - -Introduction - - -General - -

-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: - - -Remote methods that download files from a distant site -Resume of aborted downloads -Progress reporting -If-Modified-Since (IMS) checking for index files -In-Line MD5 generation -No-copy in-filesystem methods -Multi-media methods (like CD's) -Dynamic source selection for failure recovery -User interaction for user/password requests and media swaps -Global configuration - - -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. - - - - -Terms - -

-Several terms are used through out the document, they have specific -meanings which may not be immediately evident. To clarify they are summarized -here. - - -source -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. - -archive file -Refers to a binary package archive (.deb, .rpm, etc). - -source file -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. - -URI -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: - -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/ - - -method -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. - -method instance -A specific running method. There can be more than one instance of each method -as APT is capable of concurrent method handling. - -message -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 - -acquire -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. - - - - - -Specification - - -Overview - -

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

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

-In some instances APT may pre-invoke a method to allow things like file -URI's to determine how many files are available locally. - - - - -Message Overview - -

-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. - - -100 Capabilities - Method capabilities -101 Log - General Logging -102 Status - Inter-URI status reporting (login progress) -200 URI Start - URI is starting acquire -201 URI Done - URI is finished acquire -400 URI Failure - URI has failed to acquire -401 General Failure - Method did not like something sent to it -402 Authorization Required - Method requires authorization - to access the URI. Authorization is User/Pass -403 Media Failure - Method requires a media change -600 URI Acquire - Request a URI be acquired -601 Configuration - Sends the configuration space -602 Authorization Credentials - Response to the 402 message -603 Media Changed - Response to the 403 message - - -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. - -

-The flow of messages starts with the method sending out a -100 Capabilities and APT sending out a 601 Configuration. -After that APT begins sending 600 URI Acquire and the method -sends out 200 URI Start, 201 URI Done or -400 URI Failure. No synchronization is performed, it is expected -that APT will send 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. - - - - -Header Fields - -

-The following is a short index of the header fields that are supported - - -URIURI being described by the message -FilenameLocation in the filesystem -Last-ModifiedA time stamp in RFC1123 notation for use by IMS checks -IMS-HitThe already existing item is valid -SizeSize of the file in bytes -Resume-PointLocation that transfer was started -MD5-HashComputed MD5 hash for the file -MessageString indicating some displayable message -MediaString indicating the media name required -SiteString indicating the site authorization is required for -UserUsername for authorization -PasswordPassword for authorization -FailOperation failed -DriveDrive the media should be placed in -Config-Item -A string of the form item=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. -Single-InstanceRequires that only one instance of the method be run - This is a yes/no value. -PipelineThe method is capable of pipelining. -LocalThe method only returns Filename: fields. -Send-ConfigSend configuration to the method. -Needs-CleanupThe 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. -VersionVersion string for the method - - -This is a list of which headers each status code can use - - -100 Capabilities -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 - -101 Log -A log message may be printed to the screen if debugging is enabled. This -is only for debugging the method. -Fields: Message - -102 Status -Message gives a progress indication for the method. It can be used to show -pre-transfer status for Internet type methods. -Fields: Message - -200 URI Start -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 - -201 URI Done -Indicates that a URI has completed being transferred. It is possible -to specify a 201 URI Done without a 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 - -400 URI Failure -Indicates a fatal URI failure. The URI is not retrievable from this source. -As with 201 URI Done 200 URI Start is not required to precede -this message -Fields: URI, Message - -401 General Failure -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 - -402 Authorization Required -The method requires a Username and Password pair to continue. After sending -this message the method will expect APT to send a 602 Authorization -Credentials message with the required information. It is possible for -a method to send this multiple times. -Fields: Site - -403 Media Failure -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 - -600 URI Acquire -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 - -601 Configuration -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. - -602 Authorization Credentials -This is sent in response to a 402 Authorization Required message. -It contains the entered username and password. -Fields: Site, User, Password - -603 Media Changed -This is sent in response to a 403 Media Failure message. It -indicates that the user has changed media and it is safe to proceed. -Fields: Media, Fail - - - - - - -Notes - -

-The methods supplied by the stock apt are: - -cdrom - For Multi-Disc CD-ROMs -copy - (internal) For copying files around the filesystem -file - For local files -gzip - (internal) For decompression -http - For HTTP servers - - -

-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: - -http://foo.com/Packages.gz -> /bar/Packages.gz -gzip:/bar/Packages.gz -> /bar/Packages.decomp -rename Packages.decomp to /final/Packages - - -

-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. - - - - - diff --git a/doc/offline.dbk b/doc/offline.dbk new file mode 100644 index 000000000..7163f8bd5 --- /dev/null +++ b/doc/offline.dbk @@ -0,0 +1,247 @@ + + + %aptverbatiment; +]> + + + +Using APT Offline + + + + + + Jason Gunthorpejgg@debian.org + + + +Version &apt-product-version; + + + +This document describes how to use APT in a non-networked environment, +specifically a 'sneaker-net' approach for performing upgrades. + + + +1999Jason Gunthorpe + + +License Notice + +"APT" and this document are free software; you can redistribute them and/or +modify them under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or (at your +option) any later version. + + +For more details, on Debian systems, see the file +/usr/share/common-licenses/GPL for the full license. + + + + + +Introduction + +

Overview + +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 +connection but they are physically distant. + + +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 remote +host mean the machine downloading the packages, and target +host the one with bad or no connection. + + +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. + +
+ + + +Using APT on both machines + +
Overview + +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: + + + /disc/ + archives/ + partial/ + lists/ + partial/ + status + sources.list + apt.conf + +
+ +
The configuration file + +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 /var/lib/dpkg/status from +the target host. Please note, if you are using a local +archive you must use copy URIs, the syntax is identical to file URIs. + + +apt.conf must contain the necessary information to make +APT use the disc: + + + 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 + the /var/lib/dpkg default */ + State "/disc/"; + State::status "status"; + + // Binary caches will be stored locally + Cache::archives "/disc/archives/"; + Cache "/tmp/"; + + // Location of the source list. + Etc "/disc/"; + }; + + +More details can be seen by examining the apt.conf man page and the sample +configuration file in +/usr/share/doc/apt/examples/apt.conf. + + +On the target machine the first thing to do is mount the disc and copy +/var/lib/dpkg/status to it. You will also need +to create the directories outlined in the Overview, +archives/partial/ and +lists/partial/. Then take the disc to the +remote machine and configure the sources.list. On the remote +machine execute the following: + + + # 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 ] + + +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 +dselect. However this presents a problem in communicating +your selections back to the local computer. + + +Now the disc contains all of the index files and archives needed to upgrade the +target machine. Take the disc back and run: + + + # 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 ] + + +It is necessary for proper function to re-specify the status file to be the +local one. This is very important! + + +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!! + +
+ + + +Using APT and wget + +
Overview + +wget 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. + + +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. + +
+ +
Operation + +Unlike the previous technique no special configuration files are required. We +merely use the standard APT commands to generate the file list. + + + # 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 + + +Any command other than dist-upgrade could be used here, including +dselect-upgrade. + + +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 +disc. + + +The remote machine would do something like + + + # cd /disc + # sh -x ./wget-script + [ wait.. ] + + +Once the archives are downloaded and the disc returned to the Debian machine +installation can proceed using, + + + # apt-get -o dir::cache::archives="/disc/" dist-upgrade + + +Which will use the already fetched archives on the disc. + +
+ + + + diff --git a/doc/offline.sgml b/doc/offline.sgml deleted file mode 100644 index 659ca3147..000000000 --- a/doc/offline.sgml +++ /dev/null @@ -1,236 +0,0 @@ - - - -Using APT Offline - -Jason Gunthorpe jgg@debian.org -$Id: offline.sgml,v 1.8 2003/02/12 15:06:41 doogie Exp $ - - -This document describes how to use APT in a non-networked environment, -specifically a 'sneaker-net' approach for performing upgrades. - - - -Copyright © Jason Gunthorpe, 1999. -

-"APT" and this document are free software; you can redistribute them and/or -modify them under the terms of the GNU General Public License as published -by the Free Software Foundation; either version 2 of the License, or (at your -option) any later version. - -

-For more details, on Debian systems, see the file -/usr/share/common-licenses/GPL for the full license. - - - - -Introduction - - -Overview - -

-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 -connection but they are physically distant. - -

-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 remote host mean the -machine downloading the packages, and target host the one with bad or -no connection. - -

-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. - - - - -Using APT on both machines - - -Overview - -

-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: - - - /disc/ - archives/ - partial/ - lists/ - partial/ - status - sources.list - apt.conf - - - - - - -The configuration file - -

-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 /var/lib/dpkg/status from the -target host. Please note, if you are using a local archive you must use -copy URIs, the syntax is identical to file URIs. - -

-apt.conf must contain the necessary information to make APT use the -disc: - - - 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 - the /var/lib/dpkg default */ - State "/disc/"; - State::status "status"; - - // Binary caches will be stored locally - Cache::archives "/disc/archives/"; - Cache "/tmp/"; - - // Location of the source list. - Etc "/disc/"; - }; - - -More details can be seen by examining the apt.conf man page and the sample -configuration file in /usr/share/doc/apt/examples/apt.conf. - -

-On the target machine the first thing to do is mount the disc and copy -/var/lib/dpkg/status to it. You will also need to create the directories -outlined in the Overview, archives/partial/ and lists/partial/. -Then take the disc to the remote machine and configure the sources.list. -On the remote machine execute the following: - - - # 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 ] - - -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 -dselect. However this presents a problem in communicating your -selections back to the local computer. - -

-Now the disc contains all of the index files and archives needed to upgrade -the target machine. Take the disc back and run: - - - # 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 ] - - -

-It is necessary for proper function to re-specify the status file to be the -local one. This is very important! - -

-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!! - - - - -Using APT and wget - - -Overview - -

-wget 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. - -

-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. - - - - - -Operation - -

-Unlike the previous technique no special configuration files are required. We -merely use the standard APT commands to generate the file list. - - - # 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 - - -Any command other than dist-upgrade could be used here, including -dselect-upgrade. - -

-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 -disc. - -

-The remote machine would do something like - - - # cd /disc - # sh -x ./wget-script - [ wait.. ] - - -Once the archives are downloaded and the disc returned to the Debian machine -installation can proceed using, - - - # apt-get -o dir::cache::archives="/disc/" dist-upgrade - - -Which will use the already fetched archives on the disc. - - - - -- cgit v1.2.3