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/guide.dbk | 560 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 560 insertions(+) create mode 100644 doc/guide.dbk (limited to 'doc/guide.dbk') 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. + +
+ + + + -- cgit v1.2.3