You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
547 lines
22 KiB
547 lines
22 KiB
<!-- -*- mode: sgml; mode: fold -*- -->
|
|
<!doctype debiandoc PUBLIC "-//DebianDoc//DTD DebianDoc//EN">
|
|
<book>
|
|
<title>APT User's Guide</title>
|
|
|
|
<author>Jason Gunthorpe <email>jgg@debian.org</email></author>
|
|
<version>$Id: guide.sgml,v 1.7 2003/04/26 23:26:13 doogie Exp $</version>
|
|
|
|
<abstract>
|
|
This document provides an overview of how to use the the APT package manager.
|
|
</abstract>
|
|
|
|
<copyright>
|
|
Copyright © Jason Gunthorpe, 1998.
|
|
<p>
|
|
"APT" and this document are free software; you can redistribute them and/or
|
|
modify them under the terms of the GNU General Public License as published
|
|
by the Free Software Foundation; either version 2 of the License, or (at your
|
|
option) any later version.
|
|
|
|
<p>
|
|
For more details, on Debian GNU/Linux systems, see the file
|
|
/usr/share/common-licenses/GPL for the full license.
|
|
</copyright>
|
|
|
|
<toc sect>
|
|
|
|
<!-- General {{{ -->
|
|
<!-- ===================================================================== -->
|
|
<chapt>General
|
|
|
|
<p>
|
|
The APT package currently contains two sections, the APT <prgn>dselect</>
|
|
method and the <prgn>apt-get</> command line user interface. Both provide
|
|
a way to install and remove packages as well as download new packages from
|
|
the Internet.
|
|
|
|
<sect>Anatomy of the Package System
|
|
<p>
|
|
The Debian packaging system has a large amount of information associated with
|
|
each package to help assure that it integrates cleanly and easily into
|
|
the system. The most prominent of its features is the dependency system.
|
|
|
|
<p>
|
|
The dependency system allows individual programs to make use of shared
|
|
elements in the system such as libraries. It simplifies placing infrequently
|
|
used portions of a program in separate packages to reduce the
|
|
number of things the average user is required to install. Also, it allows
|
|
for choices in mail transport agents, X servers and
|
|
so on.
|
|
|
|
<p>
|
|
The first step to understanding the dependency system is to grasp the concept
|
|
of a simple dependency. The meaning of a simple dependency is that a package
|
|
requires another package to be installed at the same time to work properly.
|
|
|
|
<p>
|
|
For instance, mailcrypt is an emacs extension that aids in encrypting email
|
|
with GPG. Without GPGP installed mail-crypt is useless, so mailcrypt has a
|
|
simple dependency on GPG. Also, because it is an emacs extension it has a
|
|
simple dependency on emacs, without emacs it is completely useless.
|
|
|
|
<p>
|
|
The other important dependency to understand is a conflicting dependency. It
|
|
means that a package, when installed with another package, will not work and
|
|
may possibly be extremely harmful to the system. As an example consider a
|
|
mail transport agent such as sendmail, exim or qmail. It is not possible
|
|
to have two mail transport agents installed because both need to listen to
|
|
the network to receive mail. Attempting to install two will seriously
|
|
damage the system so all mail transport agents have a conflicting dependency
|
|
with all other mail transport agents.
|
|
|
|
<p>
|
|
As an added complication there is the possibility for a package to pretend
|
|
to be another package. Consider that exim and sendmail for many intents are
|
|
identical, they both deliver mail and understand a common interface. Hence,
|
|
the package system has a way for them to declare that they are both
|
|
mail-transport-agents. So, exim and sendmail both declare that they provide a
|
|
mail-transport-agent and other packages that need a mail transport agent
|
|
depend on mail-transport-agent. This can add a great deal of confusion when
|
|
trying to manually fix packages.
|
|
|
|
<p>
|
|
At any given time a single dependency may be met by packages that are already
|
|
installed or it may not be. APT attempts to help resolve dependency issues
|
|
by providing a number of automatic algorithms that help in selecting packages
|
|
for installation.
|
|
</sect>
|
|
|
|
</chapt>
|
|
<!-- }}} -->
|
|
<!-- apt-get {{{ -->
|
|
<!-- ===================================================================== -->
|
|
<chapt>apt-get
|
|
|
|
<p>
|
|
<prgn>apt-get</> provides a simple way to install packages from the command
|
|
line. Unlike <prgn>dpkg</>, <prgn>apt-get</> does not understand .deb files,
|
|
it works with the package's proper name and can only install .deb archives from
|
|
a <em>Source</>.
|
|
|
|
<p>
|
|
The first <footnote>If you are using an http proxy server you must set the
|
|
http_proxy environment variable first, see sources.list(5)</footnote> thing that
|
|
should be done before using <prgn>apt-get</> is to fetch the package lists
|
|
from the <em>Sources</> so that it knows what packages are
|
|
available. This is done with <tt>apt-get update</>. For instance,
|
|
|
|
<p>
|
|
<example>
|
|
# apt-get update
|
|
Get http://ftp.de.debian.org/debian-non-US/ stable/binary-i386/ Packages
|
|
Get http://llug.sep.bnl.gov/debian/ testing/contrib Packages
|
|
Reading Package Lists... Done
|
|
Building Dependency Tree... Done
|
|
</example>
|
|
|
|
<p>
|
|
Once updated there are several commands that can be used:
|
|
<taglist>
|
|
<tag>upgrade<item>
|
|
Upgrade will attempt to gently upgrade the whole system. Upgrade will
|
|
never install a new package or remove an existing package, nor will it
|
|
ever upgrade a package that might cause some other package to break.
|
|
This can be used daily to relatively safely upgrade the system. Upgrade
|
|
will list all of the packages that it could not upgrade, this usually
|
|
means that they depend on new packages or conflict with some other package.
|
|
<prgn>dselect</> or <tt>apt-get install</> can be used to force these
|
|
packages to install.
|
|
|
|
<tag>install<item>
|
|
Install is used to install packages by name. The package is
|
|
automatically fetched and installed. This can be useful if you already
|
|
know the name of the package to install and do not want to go into a GUI
|
|
to select it. Any number of packages may be passed to install, they will
|
|
all be fetched. Install automatically attempts to resolve dependency problems
|
|
with the listed packages and will print a summary and ask for confirmation
|
|
if anything other than its arguments are changed.
|
|
|
|
<tag>dist-upgrade<item>
|
|
Dist-upgrade is a complete upgrader designed to simplify upgrading between
|
|
releases of Debian. It uses a sophisticated algorithm to determine the best
|
|
set of packages to install, upgrade and remove to get as much of the system
|
|
to the newest release. In some situations it may be desired to use dist-upgrade
|
|
rather than spend the time manually resolving dependencies in <prgn>dselect</>.
|
|
Once dist-upgrade has completed then <prgn>dselect</> can be used to install
|
|
any packages that may have been left out.
|
|
|
|
<p>
|
|
It is important to closely look at what dist-upgrade is going to do, its
|
|
decisions may sometimes be quite surprising.
|
|
</taglist>
|
|
|
|
<p>
|
|
<prgn>apt-get</> has several command line options that are detailed in its
|
|
man page, <manref name="apt-get" section="8">. The most useful option is
|
|
<tt>-d</> which does not install the fetched files. If the system has to
|
|
download a large number of package it would be undesired to start installing
|
|
them in case something goes wrong. When <tt>-d</> is used the downloaded
|
|
archives can be installed by simply running the command that caused them to
|
|
be downloaded again without <tt>-d</>.
|
|
|
|
</chapt>
|
|
<!-- }}} -->
|
|
<!-- DSelect {{{ -->
|
|
<!-- ===================================================================== -->
|
|
<chapt>DSelect
|
|
<p>
|
|
The APT <prgn>dselect</> method provides the complete APT system with
|
|
the <prgn>dselect</> package selection GUI. <prgn>dselect</> is used to
|
|
select the packages to be installed or removed and APT actually installs them.
|
|
|
|
<p>
|
|
To enable the APT method you need to to select [A]ccess in <prgn>dselect</>
|
|
and then choose the APT method. You will be prompted for a set of
|
|
<em>Sources</> which are places to fetch archives from. These can be remote
|
|
Internet sites, local Debian mirrors or CDROMs. 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 CDROM 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 CDROM before
|
|
downloading from the Internet.
|
|
|
|
<p>
|
|
<example>
|
|
Set up a list of distribution source locations
|
|
|
|
Please give the base URL of the debian distribution.
|
|
The access schemes I know about are: http file
|
|
|
|
For example:
|
|
file:/mnt/debian,
|
|
ftp://ftp.debian.org/debian,
|
|
http://ftp.de.debian.org/debian,
|
|
|
|
|
|
URL [http://llug.sep.bnl.gov/debian]:
|
|
</example>
|
|
|
|
<p>
|
|
The <em>Sources</> setup starts by asking for the base of the Debian
|
|
archive, defaulting to a HTTP mirror. Next it asks for the distribution to
|
|
get.
|
|
|
|
<p>
|
|
<example>
|
|
Please give the distribution tag to get or a path to the
|
|
package file ending in a /. The distribution
|
|
tags are typically something like: stable unstable testing non-US
|
|
|
|
Distribution [stable]:
|
|
</example>
|
|
|
|
<p>
|
|
The distribution refers to the Debian version in the archive, <em>stable</>
|
|
refers to the latest released version and <em>unstable</> refers to the
|
|
developmental version. <em>non-US</> is only available on some mirrors and
|
|
refers to packages that contain encryption technology or other things that
|
|
cannot be exported from the United States. Importing these packages into the
|
|
US is legal however.
|
|
|
|
<p>
|
|
<example>
|
|
Please give the components to get
|
|
The components are typically something like: main contrib non-free
|
|
|
|
Components [main contrib non-free]:
|
|
</example>
|
|
|
|
<p>
|
|
The components list refers to the list of sub distributions to fetch. The
|
|
distribution is split up based on software licenses, main being DFSG free
|
|
packages while contrib and non-free contain things that have various
|
|
restrictions placed on their use and distribution.
|
|
|
|
<p>
|
|
Any number of sources can be added, the setup script will continue to
|
|
prompt until you have specified all that you want.
|
|
|
|
<p>
|
|
Before starting to use <prgn>dselect</> it is necessary to update the
|
|
available list by selecting [U]pdate from the menu. This is a super-set of
|
|
<tt>apt-get update</> that makes the fetched information available to
|
|
<prgn>dselect</>. [U]pdate must be performed even if <tt>apt-get update</>
|
|
has been run before.
|
|
|
|
<p>
|
|
You can then go on and make your selections using [S]elect and then
|
|
perform the installation using [I]nstall. When using the APT method
|
|
the [C]onfig and [R]emove commands have no meaning, the [I]nstall command
|
|
performs both of them together.
|
|
|
|
<p>
|
|
By default APT will automatically remove the package (.deb) files once they have been
|
|
successfully installed. To change this behavior place <tt>Dselect::clean
|
|
"prompt";</> in /etc/apt/apt.conf.
|
|
|
|
</chapt>
|
|
<!-- }}} -->
|
|
<!-- The Interfaces {{{ -->
|
|
<!-- ===================================================================== -->
|
|
<chapt>The Interface
|
|
|
|
<p>
|
|
Both that APT <prgn>dselect</> method and <prgn>apt-get</> share the same
|
|
interface. It is a simple system that generally tells you what it will do
|
|
and then goes and does it.
|
|
<footnote>
|
|
The <prgn>dselect</> method actually is a set of wrapper scripts
|
|
to <prgn>apt-get</>. The method actually provides more functionality than
|
|
is present in <prgn>apt-get</> alone.
|
|
</footnote>
|
|
After printing out a summary of what will happen APT then will print out some
|
|
informative status messages so that you can estimate how far along it is and
|
|
how much is left to do.
|
|
|
|
<!-- ===================================================================== -->
|
|
<sect>Startup
|
|
|
|
<p>
|
|
Before all operations except update, APT performs a number of actions to
|
|
prepare its internal state. It also does some checks of the system's state.
|
|
At any time these operations can be performed by running <tt>apt-get check</>.
|
|
<p>
|
|
<example>
|
|
# apt-get check
|
|
Reading Package Lists... Done
|
|
Building Dependency Tree... Done
|
|
</example>
|
|
|
|
<p>
|
|
The first thing it does is read all the package files into memory. APT
|
|
uses a caching scheme so this operation will be faster the second time it
|
|
is run. If some of the package files are not found then they will be ignored
|
|
and a warning will be printed when apt-get exits.
|
|
|
|
<p>
|
|
The final operation performs a detailed analysis of the system's dependencies.
|
|
It checks every dependency of every installed or unpacked package and considers
|
|
if it is OK. Should this find a problem then a report will be printed out and
|
|
<prgn>apt-get</> will refuse to run.
|
|
|
|
<p>
|
|
<example>
|
|
# apt-get check
|
|
Reading Package Lists... Done
|
|
Building Dependency Tree... Done
|
|
You might want to run apt-get -f install' to correct these.
|
|
Sorry, but the following packages have unmet dependencies:
|
|
9fonts: Depends: xlib6g but it is not installed
|
|
uucp: Depends: mailx but it is not installed
|
|
blast: Depends: xlib6g (>= 3.3-5) but it is not installed
|
|
adduser: Depends: perl-base but it is not installed
|
|
aumix: Depends: libgpmg1 but it is not installed
|
|
debiandoc-sgml: Depends: sgml-base but it is not installed
|
|
bash-builtins: Depends: bash (>= 2.01) but 2.0-3 is installed
|
|
cthugha: Depends: svgalibg1 but it is not installed
|
|
Depends: xlib6g (>= 3.3-5) but it is not installed
|
|
libreadlineg2: Conflicts:libreadline2 (<< 2.1-2.1)
|
|
</example>
|
|
|
|
<p>
|
|
In this example the system has many problems, including a serious problem
|
|
with libreadlineg2. For each package that has unmet dependencies a line
|
|
is printed out indicating the package with the problem and the dependencies
|
|
that are unmet. A short explanation of why the package has a dependency
|
|
problem is also included.
|
|
|
|
<p>
|
|
There are two ways a system can get into a broken state like this. The
|
|
first is caused by <prgn>dpkg</> missing some subtle relationships between
|
|
packages when performing upgrades. <footnote>APT however considers all known
|
|
dependencies and attempts to prevent broken packages</footnote>. The second is
|
|
if a package installation fails during an operation. In this situation a
|
|
package may have been unpacked without its dependents being installed.
|
|
|
|
<p>
|
|
The second situation is much less serious than the first because APT places
|
|
certain constraints on the order that packages are installed. In both cases
|
|
supplying the <tt>-f</> option to <prgn>apt-get</> will cause APT to deduce a
|
|
possible solution to the problem and then continue on. The APT <prgn>dselect</>
|
|
method always supplies the <tt>-f</> option to allow for easy continuation
|
|
of failed maintainer scripts.
|
|
|
|
<p>
|
|
However, if the <tt>-f</> option is used to correct a seriously broken system
|
|
caused by the first case then it is possible that it will either fail
|
|
immediately or the installation sequence will fail. In either case it is
|
|
necessary to manually use dpkg (possibly with forcing options) to correct
|
|
the situation enough to allow APT to proceed.
|
|
</sect>
|
|
|
|
<!-- ===================================================================== -->
|
|
<sect>The Status Report
|
|
|
|
<p>
|
|
Before proceeding <prgn>apt-get</> will present a report on what will happen.
|
|
Generally the report reflects the type of operation being performed but there
|
|
are several common elements. In all cases the lists reflect the final state
|
|
of things, taking into account the <tt>-f</> option and any other relevant
|
|
activities to the command being executed.
|
|
|
|
<sect1>The Extra Package list
|
|
<p>
|
|
<example>
|
|
The following extra packages will be installed:
|
|
libdbd-mysql-perl xlib6 zlib1 xzx libreadline2 libdbd-msql-perl
|
|
mailpgp xdpkg fileutils pinepgp zlib1g xlib6g perl-base
|
|
bin86 libgdbm1 libgdbmg1 quake-lib gmp2 bcc xbuffy
|
|
squake pgp-i python-base debmake ldso perl libreadlineg2
|
|
ssh
|
|
</example>
|
|
|
|
<p>
|
|
The Extra Package list shows all of the packages that will be installed
|
|
or upgraded in excess of the ones mentioned on the command line. It is
|
|
only generated for an <tt>install</> command. The listed packages are
|
|
often the result of an Auto Install.
|
|
</sect1>
|
|
|
|
<sect1>The Packages to Remove
|
|
<p>
|
|
<example>
|
|
The following packages will be REMOVED:
|
|
xlib6-dev xpat2 tk40-dev xkeycaps xbattle xonix
|
|
xdaliclock tk40 tk41 xforms0.86 ghostview xloadimage xcolorsel
|
|
xadmin xboard perl-debug tkined xtetris libreadline2-dev perl-suid
|
|
nas xpilot xfig
|
|
</example>
|
|
|
|
<p>
|
|
The Packages to Remove list shows all of the packages that will be
|
|
removed from the system. It can be shown for any of the operations and
|
|
should be given a careful inspection to ensure nothing important is to
|
|
be taken off. The <tt>-f</> option is especially good at generating packages
|
|
to remove so extreme care should be used in that case. The list may contain
|
|
packages that are going to be removed because they are only
|
|
partially installed, possibly due to an aborted installation.
|
|
</sect1>
|
|
|
|
<sect1>The New Packages list
|
|
<p>
|
|
<example>
|
|
The following NEW packages will installed:
|
|
zlib1g xlib6g perl-base libgdbmg1 quake-lib gmp2 pgp-i python-base
|
|
</example>
|
|
|
|
<p>
|
|
The New Packages list is simply a reminder of what will happen. The packages
|
|
listed are not presently installed in the system but will be when APT is done.
|
|
</sect1>
|
|
|
|
<sect1>The Kept Back list
|
|
<p>
|
|
<example>
|
|
The following packages have been kept back
|
|
compface man-db tetex-base msql libpaper svgalib1
|
|
gs snmp arena lynx xpat2 groff xscreensaver
|
|
</example>
|
|
|
|
<p>
|
|
Whenever the whole system is being upgraded there is the possibility that
|
|
new versions of packages cannot be installed because they require new things
|
|
or conflict with already installed things. In this case the package will
|
|
appear in the Kept Back list. The best way to convince packages listed
|
|
there to install is with <tt>apt-get install</> or by using <prgn>dselect</>
|
|
to resolve their problems.
|
|
</sect1>
|
|
|
|
<sect1>Held Packages warning
|
|
<p>
|
|
<example>
|
|
The following held packages will be changed:
|
|
cvs
|
|
</example>
|
|
|
|
<p>
|
|
Sometimes you can ask APT to install a package that is on hold, in such a
|
|
case it prints out a warning that the held package is going to be
|
|
changed. This should only happen during dist-upgrade or install.
|
|
</sect1>
|
|
|
|
<sect1>Final summary
|
|
<p>
|
|
Finally, APT will print out a summary of all the changes that will occur.
|
|
|
|
<p>
|
|
<example>
|
|
206 packages upgraded, 8 newly installed, 23 to remove and 51 not upgraded.
|
|
12 packages not fully installed or removed.
|
|
Need to get 65.7M/66.7M of archives. After unpacking 26.5M will be used.
|
|
</example>
|
|
|
|
<p>
|
|
The first line of the summary simply is a reduced version of all of the
|
|
lists and includes the number of upgrades - that is packages already
|
|
installed that have new versions available. The second line indicates the
|
|
number of poorly configured packages, possibly the result of an aborted
|
|
installation. The final line shows the space requirements that the
|
|
installation needs. The first pair of numbers refer to the size of
|
|
the archive files. The first number indicates the number of bytes that
|
|
must be fetched from remote locations and the second indicates the
|
|
total size of all the archives required. The next number indicates the
|
|
size difference between the presently installed packages and the newly
|
|
installed packages. It is roughly equivalent to the space required in
|
|
/usr after everything is done. If a large number of packages are being
|
|
removed then the value may indicate the amount of space that will be
|
|
freed.
|
|
|
|
<p>
|
|
Some other reports can be generated by using the -u option to show packages
|
|
to upgrade, they are similar to the previous examples.
|
|
</sect>
|
|
|
|
<!-- ===================================================================== -->
|
|
<sect>The Status Display
|
|
<p>
|
|
During the download of archives and package files APT prints out a series of
|
|
status messages.
|
|
|
|
<p>
|
|
<example>
|
|
# apt-get update
|
|
Get:1 http://ftp.de.debian.org/debian-non-US/ stable/non-US/ Packages
|
|
Get:2 http://llug.sep.bnl.gov/debian/ testing/contrib Packages
|
|
Hit http://llug.sep.bnl.gov/debian/ testing/main Packages
|
|
Get:4 http://ftp.de.debian.org/debian-non-US/ unstable/binary-i386/ Packages
|
|
Get:5 http://llug.sep.bnl.gov/debian/ testing/non-free Packages
|
|
11% [5 testing/non-free `Waiting for file' 0/32.1k 0%] 2203b/s 1m52s
|
|
</example>
|
|
|
|
<p>
|
|
The lines starting with <em>Get</> are printed out when APT begins to fetch
|
|
a file while the last line indicates the progress of the download. The first
|
|
percent value on the progress line indicates the total percent done of all
|
|
files. Unfortunately since the size of the Package files is unknown
|
|
<tt>apt-get update</> estimates the percent done which causes some
|
|
inaccuracies.
|
|
|
|
<p>
|
|
The next section of the status line is repeated once for each download thread
|
|
and indicates the operation being performed and some useful information
|
|
about what is happening. Sometimes this section will simply read <em>Forking</>
|
|
which means the OS is loading the download module. The first word after the [
|
|
is the fetch number as shown on the history lines. The next word
|
|
is the short form name of the object being downloaded. For archives it will
|
|
contain the name of the package that is being fetched.
|
|
|
|
<p>
|
|
Inside of the single quote is an informative string indicating the progress
|
|
of the negotiation phase of the download. Typically it progresses from
|
|
<em>Connecting</> to <em>Waiting for file</> to <em>Downloading</> or
|
|
<em>Resuming</>. The final value is the number of bytes downloaded from the
|
|
remote site. Once the download begins this is represented as <tt>102/10.2k</>
|
|
indicating that 102 bytes have been fetched and 10.2 kilobytes is expected.
|
|
The total size is always shown in 4 figure notation to preserve space. After
|
|
the size display is a percent meter for the file itself.
|
|
The second last element is the instantaneous average speed. This values is
|
|
updated every 5 seconds and reflects the rate of data transfer for that
|
|
period. Finally is shown the estimated transfer time. This is updated
|
|
regularly and reflects the time to complete everything at the shown
|
|
transfer rate.
|
|
|
|
<p>
|
|
The status display updates every half second to provide a constant feedback
|
|
on the download progress while the Get lines scroll back whenever a new
|
|
file is started. Since the status display is constantly updated it is
|
|
unsuitable for logging to a file, use the <tt>-q</> option to remove the
|
|
status display.
|
|
</sect>
|
|
|
|
<!-- ===================================================================== -->
|
|
<sect>Dpkg
|
|
|
|
<p>
|
|
APT uses <prgn>dpkg</> for installing the archives and will switch
|
|
over to the <prgn>dpkg</> interface once downloading is completed.
|
|
<prgn>dpkg</> will also ask a number of questions as it processes the packages
|
|
and the packages themselves may also ask several questions. Before each
|
|
question there is usually a description of what it is asking and the
|
|
questions are too varied to discuss completely here.
|
|
</sect>
|
|
|
|
</chapt>
|
|
<!-- }}} -->
|
|
|
|
</book>
|
|
|