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.

562 lines
23 KiB

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  3. "" [
  4. <!ENTITY % aptent SYSTEM "apt.ent"> %aptent;
  5. <!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment;
  6. <!ENTITY % aptvendor SYSTEM "apt-vendor.ent"> %aptvendor;
  7. ]>
  8. <book lang="en">
  9. <title>APT User's Guide</title>
  10. <bookinfo>
  11. <authorgroup>
  12. <author>
  13. <personname>Jason Gunthorpe</personname><email></email>
  14. </author>
  15. </authorgroup>
  16. <releaseinfo>Version &apt-product-version;</releaseinfo>
  17. <abstract>
  18. <para>
  19. This document provides an overview of how to use the APT package manager.
  20. </para>
  21. </abstract>
  22. <copyright><year>1998</year><holder>Jason Gunthorpe</holder></copyright>
  23. <legalnotice>
  24. <title>License Notice</title>
  25. <para>
  26. "APT" and this document are free software; you can redistribute them and/or
  27. modify them under the terms of the GNU General Public License as published by
  28. the Free Software Foundation; either version 2 of the License, or (at your
  29. option) any later version.
  30. </para>
  31. </legalnotice>
  32. <legalnotice>
  33. <para>
  34. For more details, on Debian systems, see the file
  35. /usr/share/common-licenses/GPL for the full license.
  36. </para>
  37. </legalnotice>
  38. </bookinfo>
  39. <chapter id="ch1"><title>General</title>
  40. <para>
  41. The APT package currently contains two sections, the APT
  42. <command>dselect</command> method and the <command>apt-get</command> command
  43. line user interface. Both provide a way to install and remove packages as well
  44. as download new packages from the Internet.
  45. </para>
  46. <section id="s1.1"><title>Anatomy of the Package System</title>
  47. <para>
  48. The Debian packaging system has a large amount of information associated with
  49. each package to help assure that it integrates cleanly and easily into the
  50. system. The most prominent of its features is the dependency system.
  51. </para>
  52. <para>
  53. The dependency system allows individual programs to make use of shared elements
  54. in the system such as libraries. It simplifies placing infrequently used
  55. portions of a program in separate packages to reduce the number of things the
  56. average user is required to install. Also, it allows for choices in mail
  57. transport agents, X servers and so on.
  58. </para>
  59. <para>
  60. The first step to understanding the dependency system is to grasp the concept
  61. of a simple dependency. The meaning of a simple dependency is that a package
  62. requires another package to be installed at the same time to work properly.
  63. </para>
  64. <para>
  65. For instance, mailcrypt is an emacs extension that aids in encrypting email
  66. with GPG. Without GPGP installed mailcrypt is useless, so mailcrypt has a
  67. simple dependency on GPG. Also, because it is an emacs extension it has a
  68. simple dependency on emacs, without emacs it is completely useless.
  69. </para>
  70. <para>
  71. The other important dependency to understand is a conflicting dependency. It
  72. means that a package, when installed with another package, will not work and
  73. may possibly be extremely harmful to the system. As an example consider a mail
  74. transport agent such as sendmail, exim or qmail. It is not possible to have
  75. two mail transport agents installed because both need to listen to the network
  76. to receive mail. Attempting to install two will seriously damage the system so
  77. all mail transport agents have a conflicting dependency with all other mail
  78. transport agents.
  79. </para>
  80. <para>
  81. As an added complication there is the possibility for a package to pretend to
  82. be another package. Consider that exim and sendmail for many intents are
  83. identical, they both deliver mail and understand a common interface. Hence,
  84. the package system has a way for them to declare that they are both
  85. mail-transport-agents. So, exim and sendmail both declare that they provide a
  86. mail-transport-agent and other packages that need a mail transport agent depend
  87. on mail-transport-agent. This can add a great deal of confusion when trying to
  88. manually fix packages.
  89. </para>
  90. <para>
  91. At any given time a single dependency may be met by packages that are already
  92. installed or it may not be. APT attempts to help resolve dependency issues by
  93. providing a number of automatic algorithms that help in selecting packages for
  94. installation.
  95. </para>
  96. </section>
  97. </chapter>
  98. <chapter id="ch2"><title>apt-get</title>
  99. <para>
  100. <command>apt-get</command> provides a simple way to install packages from the
  101. command line. Unlike <command>dpkg</command>, <command>apt-get</command> does
  102. not understand .deb files, it works with the package's proper name and can only
  103. install .deb archives from a <emphasis>Source</emphasis>.
  104. </para>
  105. <para>
  106. The first <footnote><para> If you are using an http proxy server you must set
  107. the http_proxy environment variable first, see sources.list(5) </para>
  108. </footnote> thing that should be done before using <command>apt-get</command>
  109. is to fetch the package lists from the <emphasis>Sources</emphasis> so that it
  110. knows what packages are available. This is done with <literal>apt-get
  111. update</literal>. For instance,
  112. </para>
  113. <screen>
  114. # apt-get update
  115. Get stable/binary-i386/ Packages
  116. Get testing/contrib Packages
  117. Reading Package Lists... Done
  118. Building Dependency Tree... Done
  119. </screen>
  120. <para>
  121. Once updated there are several commands that can be used:
  122. </para>
  123. <variablelist>
  124. <varlistentry>
  125. <term>upgrade</term>
  126. <listitem>
  127. <para>
  128. Upgrade will attempt to gently upgrade the whole system. Upgrade will never
  129. install a new package or remove an existing package, nor will it ever upgrade a
  130. package that might cause some other package to break. This can be used daily
  131. to relatively safely upgrade the system. Upgrade will list all of the packages
  132. that it could not upgrade, this usually means that they depend on new packages
  133. or conflict with some other package. <command>dselect</command> or
  134. <literal>apt-get install</literal> can be used to force these packages to
  135. install.
  136. </para>
  137. </listitem>
  138. </varlistentry>
  139. <varlistentry>
  140. <term>install</term>
  141. <listitem>
  142. <para>
  143. Install is used to install packages by name. The package is automatically
  144. fetched and installed. This can be useful if you already know the name of the
  145. package to install and do not want to go into a GUI to select it. Any number
  146. of packages may be passed to install, they will all be fetched. Install
  147. automatically attempts to resolve dependency problems with the listed packages
  148. and will print a summary and ask for confirmation if anything other than its
  149. arguments are changed.
  150. </para>
  151. </listitem>
  152. </varlistentry>
  153. <varlistentry>
  154. <term>dist-upgrade</term>
  155. <listitem>
  156. <para>
  157. Dist-upgrade is a complete upgrader designed to simplify upgrading between
  158. releases of Debian. It uses a sophisticated algorithm to determine the best
  159. set of packages to install, upgrade and remove to get as much of the system to
  160. the newest release. In some situations it may be desired to use dist-upgrade
  161. rather than spend the time manually resolving dependencies in
  162. <command>dselect</command>. Once dist-upgrade has completed then
  163. <command>dselect</command> can be used to install any packages that may have
  164. been left out.
  165. </para>
  166. <para>
  167. It is important to closely look at what dist-upgrade is going to do, its
  168. decisions may sometimes be quite surprising.
  169. </para>
  170. </listitem>
  171. </varlistentry>
  172. </variablelist>
  173. <para>
  174. <command>apt-get</command> has several command line options that are detailed
  175. in its man page,
  176. <citerefentry><refentrytitle>apt-get</refentrytitle><manvolnum>8</manvolnum></citerefentry>. The
  177. most useful option is <literal>-d</literal> which does not install the
  178. fetched files. If the system has to download a large number of package it
  179. would be undesired to start installing them in case something goes wrong. When
  180. <literal>-d</literal> is used the downloaded archives can be installed by
  181. simply running the command that caused them to be downloaded again without
  182. <literal>-d</literal>.
  183. </para>
  184. </chapter>
  185. <chapter id="ch3"><title>DSelect</title>
  186. <para>
  187. The APT <command>dselect</command> method provides the complete
  188. APT system with the <command>dselect</command> package selection
  189. GUI. <command>dselect</command> is used to select the packages to be
  190. installed or removed and APT actually installs them.
  191. </para>
  192. <para>
  193. To enable the APT method you need to select [A]ccess in
  194. <command>dselect</command> and then choose the APT method. You will be
  195. prompted for a set of <emphasis>Sources</emphasis> which are places to fetch
  196. archives from. These can be remote Internet sites, local Debian mirrors or
  197. CD-ROMs. Each source can provide a fragment of the total Debian archive, APT
  198. will automatically combine them to form a complete set of packages. If you
  199. have a CD-ROM then it is a good idea to specify it first and then specify a
  200. mirror so that you have access to the latest bug fixes. APT will automatically
  201. use packages on your CD-ROM before downloading from the Internet.
  202. </para>
  203. <screen>
  204. Set up a list of distribution source locations
  205. Please give the base URL of the debian distribution.
  206. The access schemes I know about are: http file
  207. For example:
  208. file:/mnt/debian,
  211. URL []:
  212. </screen>
  213. <para>
  214. The <emphasis>Sources</emphasis> setup starts by asking for the base of the
  215. Debian archive, defaulting to an HTTP mirror. Next it asks for the distribution
  216. to get.
  217. </para>
  218. <screen>
  219. Please give the distribution tag to get or a path to the
  220. package file ending in a /. The distribution
  221. tags are typically something like: stable unstable testing non-US
  222. Distribution [stable]:
  223. </screen>
  224. <para>
  225. The distribution refers to the Debian version in the archive,
  226. <emphasis>stable</emphasis> refers to the latest released version
  227. and <emphasis>unstable</emphasis> refers to the developmental
  228. version. <emphasis>non-US</emphasis> is only available on some mirrors
  229. and refers to packages that contain encryption technology or other
  230. things that cannot be exported from the United States. Importing these
  231. packages into the US is legal however.
  232. </para>
  233. <screen>
  234. Please give the components to get
  235. The components are typically something like: main contrib non-free
  236. Components [main contrib non-free]:
  237. </screen>
  238. <para>
  239. The components list refers to the list of sub distributions to fetch. The
  240. distribution is split up based on software licenses, main being DFSG free
  241. packages while contrib and non-free contain things that have various
  242. restrictions placed on their use and distribution.
  243. </para>
  244. <para>
  245. Any number of sources can be added, the setup script will continue to prompt
  246. until you have specified all that you want.
  247. </para>
  248. <para>
  249. Before starting to use <command>dselect</command> it is necessary to update
  250. the available list by selecting [U]pdate from the menu. This is a superset of
  251. <literal>apt-get update</literal> that makes the fetched information available
  252. to <command>dselect</command>. [U]pdate must be performed even if
  253. <literal>apt-get update</literal> has been run before.
  254. </para>
  255. <para>
  256. You can then go on and make your selections using [S]elect and then perform
  257. the installation using [I]nstall. When using the APT method the [C]onfig and
  258. [R]emove commands have no meaning, the [I]nstall command performs both of
  259. them together.
  260. </para>
  261. <para>
  262. By default APT will automatically remove the package (.deb) files once they
  263. have been successfully installed. To change this behavior place
  264. <literal>Dselect::clean "prompt";</literal> in /etc/apt/apt.conf.
  265. </para>
  266. </chapter>
  267. <chapter id="ch4"><title>The Interface</title>
  268. <para>
  269. Both that APT <command>dselect</command> method and <command>apt-get</command>
  270. share the same interface. It is a simple system that generally tells you what
  271. it will do and then goes and does it. <footnote><para> The
  272. <command>dselect</command> method actually is a set of wrapper scripts to
  273. <command>apt-get</command>. The method actually provides more functionality
  274. than is present in <command>apt-get</command> alone. </para> </footnote> After
  275. printing out a summary of what will happen APT then will print out some
  276. informative status messages so that you can estimate how far along it is and
  277. how much is left to do.
  278. </para>
  279. <section id="s4.1"><title>Startup</title>
  280. <para>
  281. Before all operations except update, APT performs a number of actions
  282. to prepare its internal state. It also does some checks of the system's
  283. state. At any time these operations can be performed by running
  284. <literal>apt-get check</literal>.
  285. </para>
  286. <screen>
  287. # apt-get check
  288. Reading Package Lists... Done
  289. Building Dependency Tree... Done
  290. </screen>
  291. <para>
  292. The first thing it does is read all the package files into memory. APT uses a
  293. caching scheme so this operation will be faster the second time it is run. If
  294. some of the package files are not found then they will be ignored and a
  295. warning will be printed when apt-get exits.
  296. </para>
  297. <para>
  298. The final operation performs a detailed analysis of the system's
  299. dependencies. It checks every dependency of every installed or unpacked
  300. package and considers if it is OK. Should this find a problem then a report
  301. will be printed out and <command>apt-get</command> will refuse to run.
  302. </para>
  303. <screen>
  304. # apt-get check
  305. Reading Package Lists... Done
  306. Building Dependency Tree... Done
  307. You might want to run 'apt --fix-broken install' to correct these.
  308. Sorry, but the following packages have unmet dependencies:
  309. 9fonts: Depends: xlib6g but it is not installed
  310. uucp: Depends: mailx but it is not installed
  311. blast: Depends: xlib6g (&gt;= 3.3-5) but it is not installed
  312. adduser: Depends: perl-base but it is not installed
  313. aumix: Depends: libgpmg1 but it is not installed
  314. debiandoc-sgml: Depends: sgml-base but it is not installed
  315. bash-builtins: Depends: bash (&gt;= 2.01) but 2.0-3 is installed
  316. cthugha: Depends: svgalibg1 but it is not installed
  317. Depends: xlib6g (&gt;= 3.3-5) but it is not installed
  318. libreadlineg2: Conflicts:libreadline2 (&lt;&lt; 2.1-2.1)
  319. </screen>
  320. <para>
  321. In this example the system has many problems, including a serious problem with
  322. libreadlineg2. For each package that has unmet dependencies a line is printed
  323. out indicating the package with the problem and the dependencies that are
  324. unmet. A short explanation of why the package has a dependency problem is also
  325. included.
  326. </para>
  327. <para>
  328. There are two ways a system can get into a broken state like this. The
  329. first is caused by <command>dpkg</command> missing some subtle relationships
  330. between packages when performing upgrades. <footnote><para> APT however
  331. considers all known dependencies and attempts to prevent broken
  332. packages </para> </footnote>. The second is if a package installation
  333. fails during an operation. In this situation a package may have been
  334. unpacked without its dependents being installed.
  335. </para>
  336. <para>
  337. The second situation is much less serious than the first because APT places
  338. certain constraints on the order that packages are installed. In both cases
  339. supplying the <literal>-f</literal> option to <command>apt-get</command>
  340. will cause APT to deduce a possible solution to the problem and then
  341. continue on. The APT <command>dselect</command> method always supplies
  342. the <literal>-f</literal> option to allow for easy continuation of failed
  343. maintainer scripts.
  344. </para>
  345. <para>
  346. However, if the <literal>-f</literal> option is used to correct a seriously
  347. broken system caused by the first case then it is possible that it will either
  348. fail immediately or the installation sequence will fail. In either case it is
  349. necessary to manually use dpkg (possibly with forcing options) to correct the
  350. situation enough to allow APT to proceed.
  351. </para>
  352. </section>
  353. <section id="s4.2"><title>The Status Report</title>
  354. <para>
  355. Before proceeding <command>apt-get</command> will present a report on what will
  356. happen. Generally the report reflects the type of operation being performed
  357. but there are several common elements. In all cases the lists reflect the
  358. final state of things, taking into account the <literal>-f</literal> option
  359. and any other relevant activities to the command being executed.
  360. </para>
  361. <section id="s4.2.1"><title>The Extra Package list</title>
  362. <screen>
  363. The following extra packages will be installed:
  364. libdbd-mysql-perl xlib6 zlib1 xzx libreadline2 libdbd-msql-perl
  365. mailpgp xdpkg fileutils pinepgp zlib1g xlib6g perl-base
  366. bin86 libgdbm1 libgdbmg1 quake-lib gmp2 bcc xbuffy
  367. squake pgp-i python-base debmake ldso perl libreadlineg2
  368. ssh
  369. </screen>
  370. <para>
  371. The Extra Package list shows all of the packages that will be installed or
  372. upgraded in excess of the ones mentioned on the command line. It is only
  373. generated for an <literal>install</literal> command. The listed packages are
  374. often the result of an Auto Install.
  375. </para>
  376. </section>
  377. <section id="s4.2.2"><title>The Packages to Remove</title>
  378. <screen>
  379. The following packages will be REMOVED:
  380. xlib6-dev xpat2 tk40-dev xkeycaps xbattle xonix
  381. xdaliclock tk40 tk41 xforms0.86 ghostview xloadimage xcolorsel
  382. xadmin xboard perl-debug tkined xtetris libreadline2-dev perl-suid
  383. nas xpilot xfig
  384. </screen>
  385. <para>
  386. The Packages to Remove list shows all of the packages that will be removed
  387. from the system. It can be shown for any of the operations and should be given
  388. a careful inspection to ensure nothing important is to be taken off. The
  389. <literal>-f</literal> option is especially good at generating packages to
  390. remove so extreme care should be used in that case. The list may contain
  391. packages that are going to be removed because they are only partially
  392. installed, possibly due to an aborted installation.
  393. </para>
  394. </section>
  395. <section id="s4.2.3"><title>The New Packages list</title>
  396. <screen>
  397. The following NEW packages will installed:
  398. zlib1g xlib6g perl-base libgdbmg1 quake-lib gmp2 pgp-i python-base
  399. </screen>
  400. <para>
  401. The New Packages list is simply a reminder of what will happen. The packages
  402. listed are not presently installed in the system but will be when APT is done.
  403. </para>
  404. </section>
  405. <section id="s4.2.4"><title>The Kept Back list</title>
  406. <screen>
  407. The following packages have been kept back
  408. compface man-db tetex-base msql libpaper svgalib1
  409. gs snmp arena lynx xpat2 groff xscreensaver
  410. </screen>
  411. <para>
  412. Whenever the whole system is being upgraded there is the possibility that new
  413. versions of packages cannot be installed because they require new things or
  414. conflict with already installed things. In this case the package will appear
  415. in the Kept Back list. The best way to convince packages listed there to
  416. install is with <literal>apt-get install</literal> or by using
  417. <command>dselect</command> to resolve their problems.
  418. </para>
  419. </section>
  420. <section id="s4.2.5"><title>Held Packages warning</title>
  421. <screen>
  422. The following held packages will be changed:
  423. cvs
  424. </screen>
  425. <para>
  426. Sometimes you can ask APT to install a package that is on hold, in such a case
  427. it prints out a warning that the held package is going to be changed. This
  428. should only happen during dist-upgrade or install.
  429. </para>
  430. </section>
  431. <section id="s4.2.6"><title>Final summary</title>
  432. <para>
  433. Finally, APT will print out a summary of all the changes that will occur.
  434. </para>
  435. <screen>
  436. 206 packages upgraded, 8 newly installed, 23 to remove and 51 not upgraded.
  437. 12 packages not fully installed or removed.
  438. Need to get 65.7M/66.7M of archives. After unpacking 26.5M will be used.
  439. </screen>
  440. <para>
  441. The first line of the summary simply is a reduced version of all of the lists
  442. and includes the number of upgrades - that is packages already installed that
  443. have new versions available. The second line indicates the number of poorly
  444. configured packages, possibly the result of an aborted installation. The final
  445. line shows the space requirements that the installation needs. The first pair
  446. of numbers refer to the size of the archive files. The first number indicates
  447. the number of bytes that must be fetched from remote locations and the second
  448. indicates the total size of all the archives required. The next number
  449. indicates the size difference between the presently installed packages and the
  450. newly installed packages. It is roughly equivalent to the space required in
  451. /usr after everything is done. If a large number of packages are being removed
  452. then the value may indicate the amount of space that will be freed.
  453. </para>
  454. <para>
  455. Some other reports can be generated by using the -u option to show packages to
  456. upgrade, they are similar to the previous examples.
  457. </para>
  458. </section>
  459. </section>
  460. <section id="s4.3"><title>The Status Display</title>
  461. <para>
  462. During the download of archives and package files APT prints out a series of
  463. status messages.
  464. </para>
  465. <screen>
  466. # apt-get update
  467. Get:1 stable/non-US/ Packages
  468. Get:2 testing/contrib Packages
  469. Hit testing/main Packages
  470. Get:4 unstable/binary-i386/ Packages
  471. Get:5 testing/non-free Packages
  472. 11% [5 testing/non-free `Waiting for file' 0/32.1k 0%] 2203b/s 1m52s
  473. </screen>
  474. <para>
  475. The lines starting with <emphasis>Get</emphasis> are printed out when APT
  476. begins to fetch a file while the last line indicates the progress of the
  477. download. The first percent value on the progress line indicates the total
  478. percent done of all files. Unfortunately since the size of the Package files
  479. is unknown <literal>apt-get update</literal> estimates the percent done which
  480. causes some inaccuracies.
  481. </para>
  482. <para>
  483. The next section of the status line is repeated once for each download
  484. thread and indicates the operation being performed and some useful
  485. information about what is happening. Sometimes this section will simply
  486. read <emphasis>Forking</emphasis> which means the OS is loading the download
  487. module. The first word after the [ is the fetch number as shown on the
  488. history lines. The next word is the short form name of the object being
  489. downloaded. For archives it will contain the name of the package that is
  490. being fetched.
  491. </para>
  492. <para>
  493. Inside of the single quote is an informative string indicating the progress of
  494. the negotiation phase of the download. Typically it progresses from
  495. <emphasis>Connecting</emphasis> to <emphasis>Waiting for file</emphasis> to
  496. <emphasis>Downloading</emphasis> or <emphasis>Resuming</emphasis>. The final
  497. value is the number of bytes downloaded from the remote site. Once the
  498. download begins this is represented as <literal>102/10.2k</literal> indicating
  499. that 102 bytes have been fetched and 10.2 kilobytes is expected. The total
  500. size is always shown in 4 figure notation to preserve space. After the size
  501. display is a percent meter for the file itself. The second last element is the
  502. instantaneous average speed. This values is updated every 5 seconds and
  503. reflects the rate of data transfer for that period. Finally is shown the
  504. estimated transfer time. This is updated regularly and reflects the time to
  505. complete everything at the shown transfer rate.
  506. </para>
  507. <para>
  508. The status display updates every half second to provide a constant feedback on
  509. the download progress while the Get lines scroll back whenever a new file is
  510. started. Since the status display is constantly updated it is unsuitable for
  511. logging to a file, use the <literal>-q</literal> option to remove the status
  512. display.
  513. </para>
  514. </section>
  515. <section id="s4.4"><title>Dpkg</title>
  516. <para>
  517. APT uses <command>dpkg</command> for installing the archives and will
  518. switch over to the <command>dpkg</command> interface once downloading is
  519. completed. <command>dpkg</command> will also ask a number of questions as
  520. it processes the packages and the packages themselves may also ask several
  521. questions. Before each question there is usually a description of what it
  522. is asking and the questions are too varied to discuss completely here.
  523. </para>
  524. </section>
  525. </chapter>
  526. </book>