<!-- vim: set sw=2 et sts=2 ft=xml: -->
<!-- Last content review: 2024-01-27T12:40:15 UTC -->
  <chapter id="_debian_package_management">
    <title>Debian package management</title>
    <note>
      <para>This chapter is written assuming the latest stable release is codename: <literal>@-@codename-stable@-@</literal>.</para>
      <para>The data source of the APT system is collectively refered as <emphasis role="strong">the source list</emphasis> in this document .  This can be defined anywhere in the "<literal>/etc/apt/sources.list</literal>" file, "<literal>/etc/apt/sources.list.d/*.list</literal>" files, or "<literal>/etc/apt/sources.list.d/*.sources</literal>" files.</para>
    </note>
    <section id="_debian_package_management_prerequisites">
      <title>Debian package management prerequisites</title>
      <section id="_debian_package_management_system">
        <title>Debian package management system</title>
        <para><ulink url="https://www.debian.org">Debian</ulink> is a volunteer organization which builds <emphasis role="strong">consistent</emphasis> distributions of pre-compiled binary packages of free software and distributes them from its archive.</para>
        <para><ulink url="http://deb.debian.org/debian/">The Debian archive</ulink> is offered by <ulink url="https://www.debian.org/mirror/">many remote mirror sites</ulink> for access through HTTP and FTP methods. It is also available as <ulink url="https://www.debian.org/CD/">CD-ROM/DVD</ulink>.</para>
        <para>The current Debian package management system which can utilize all these resources is <ulink url="https://en.wikipedia.org/wiki/APT_(software)">Advanced Packaging Tool (APT)</ulink>. </para>
        <para>The Debian package management system, <emphasis role="strong">when used properly</emphasis>, offers the user to install <emphasis role="strong">consistent sets of binary packages</emphasis> to the system from the archive.  Currently, there are @-@all-packages@-@ packages available for the @-@arch@-@ architecture.</para>
        <para>The Debian package management system has a rich history and many choices for the front end user program and back end archive access method to be used.  Currently, we recommend the following.</para>
        <itemizedlist>
          <listitem>
            <para><literal>apt</literal>(8) for all interactive command line operations, including package installation, removal and dist-upgrades.</para>
          </listitem>
          <listitem>
            <para><literal>apt-get</literal>(8) for calling Debian package management system from scripts. It is also a fallback option when <literal>apt</literal> is not available (often with older Debian systems).</para>
          </listitem>
          <listitem>
            <para><literal>aptitude</literal>(8) for an interactive text interface to manage the installed packages and to search the available packages.</para>
          </listitem>
        </itemizedlist>
        <table pgwide="0" frame="topbot" rowsep="1" colsep="1">
          <title>List of Debian package management tools</title>
          <tgroup cols="4">
            <colspec colwidth="124pt" align="left"/>
            <colspec colwidth="76pt" align="left"/>
            <colspec colwidth="70pt" align="left"/>
            <colspec colwidth="483pt" align="left"/>
            <thead>
              <row>
                <entry> package </entry>
                <entry> popcon </entry>
                <entry> size </entry>
                <entry> description </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry> <literal>dpkg</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry> low level package management system for Debian (file based) </entry>
              </row>
              <row>
                <entry> <literal>apt</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry> APT front-end to manage packages with CLI: <literal>apt</literal>/<literal>apt-get</literal>/<literal>apt-cache</literal> </entry>
              </row>
              <row>
                <entry> <literal>aptitude</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry> APT front-end to interactively manage packages with full screen console: <literal>aptitude</literal>(8) </entry>
              </row>
              <row>
                <entry> <literal>tasksel</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry> APT front-end to install selected tasks: <literal>tasksel</literal>(8) </entry>
              </row>
              <row>
                <entry> <literal>unattended-upgrades</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry> enhancement package for APT to enable automatic installation of security upgrades </entry>
              </row>
              <row>
                <entry> <literal>gnome-software</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry> Software Center for GNOME (GUI APT front-end) </entry>
              </row>
              <row>
                <entry> <literal>synaptic</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry> graphical package manager (GTK APT front-end) </entry>
              </row>
              <row>
                <entry> <literal>apt-utils</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry> APT utility programs: <literal>apt-extracttemplates</literal>(1), <literal>apt-ftparchive</literal>(1), and <literal>apt-sortpkgs</literal>(1) </entry>
              </row>
              <row>
                <entry> <literal>apt-listchanges</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry> package change history notification tool </entry>
              </row>
              <row>
                <entry> <literal>apt-listbugs</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry> lists critical bugs before each APT installation </entry>
              </row>
              <row>
                <entry> <literal>apt-file</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry> APT package searching utility — command-line interface </entry>
              </row>
              <row>
                <entry> <literal>apt-rdepends</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry> recursively lists package dependencies </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
      </section>
      <section id="_package_configuration">
        <title>Package configuration</title>
        <para>Here are some key points for package configuration on the Debian system.</para>
        <itemizedlist>
          <listitem> <para> The manual configuration by the system administrator is respected. In other words, the package configuration system makes no intrusive configuration for the sake of convenience.  </para> </listitem>
          <listitem> <para> Each package comes with its own configuration script with standardized user interface called <literal>debconf</literal>(7) to help initial installation process of the package.  </para> </listitem>
          <listitem> <para> Debian Developers try their best to make your upgrade experience flawless with package configuration scripts.  </para> </listitem>
          <listitem> <para> Full functionalities of packaged software are available to the system administrator.  But ones with security risks are disabled in the default installation.  </para> </listitem>
          <listitem> <para> If you manually activate a service with some security risks, you are responsible for the risk containment.  </para> </listitem>
          <listitem> <para> Esoteric configuration may be manually enabled by the system administrator.  This may create interference with popular generic helper programs for the system configuration.  </para> </listitem>
        </itemizedlist>
      </section>
      <section id="_basic_precautions">
        <title>Basic precautions</title>
        <warning> <para>Do not install packages from random mixture of suites.  It probably breaks the package consistency which requires deep system management knowledge, such as compiler <ulink url="https://en.wikipedia.org/wiki/Application_binary_interface">ABI</ulink>, <ulink url="https://en.wikipedia.org/wiki/Library_(computing)">library</ulink> version, interpreter features, etc.</para> </warning>
        <para>The <ulink url="https://en.wikipedia.org/wiki/Newbie">newbie</ulink> Debian system administrator should stay with the <emphasis role="strong"><literal>stable</literal></emphasis> release of Debian while applying only security updates.  Until you understand the Debian system very well, you should follow the following precautions.</para>
        <itemizedlist>
          <listitem> <para> Do not include <emphasis role="strong"><literal>testing</literal></emphasis> or <emphasis role="strong"><literal>unstable</literal></emphasis> in <emphasis role="strong">the source list</emphasis>.  </para> </listitem>
          <listitem> <para> Do not mix standard Debian with other non-Debian archives such as Ubuntu in <emphasis role="strong">the source list</emphasis> .  </para> </listitem>
          <listitem> <para> Do not create "<literal>/etc/apt/preferences</literal>".  </para> </listitem>
          <listitem> <para> Do not change default behavior of package management tools through configuration files without knowing their full impacts.  </para> </listitem>
          <listitem> <para> Do not install random packages by "<literal>dpkg -i <emphasis>random_package</emphasis></literal>".  </para> </listitem>
          <listitem> <para> Do not ever install random packages by  "<literal>dpkg --force-all -i <emphasis>random_package</emphasis></literal>".  </para> </listitem>
          <listitem> <para> Do not erase or alter files in "<literal>/var/lib/dpkg/</literal>".  </para> </listitem>
          <listitem>
            <para> Do not overwrite system files by installing software programs directly compiled from source.  </para>
            <itemizedlist>
              <listitem> <para> Install them into "<literal>/usr/local</literal>" or "<literal>/opt</literal>", if needed.  </para> </listitem>
            </itemizedlist>
          </listitem>
        </itemizedlist>
        <para>The non-compatible effects caused by violating above precautions to the Debian package management system may leave your system unusable.</para>
        <para>The serious Debian system administrator who runs mission critical servers, should use extra precautions.</para>
        <itemizedlist>
          <listitem>
            <para> Do not install any packages including security updates from Debian without thoroughly testing them with your particular configuration under safe conditions.  </para>
            <itemizedlist>
              <listitem> <para> You as the system administrator are responsible for your system in the end.  </para> </listitem>
              <listitem> <para> The long stability history of the Debian system is no guarantee by itself.  </para> </listitem>
            </itemizedlist>
          </listitem>
        </itemizedlist>
      </section>
      <section id="_life_with_eternal_upgrades">
        <title>Life with eternal upgrades</title>
        <caution> <para>For your <emphasis role="strong">production server</emphasis>, the <literal>stable</literal> suite with the security updates is recommended.  The same can be said for desktop PCs on which you can spend limited administration efforts.</para> </caution>
        <para>Despite my warnings above, I know many readers of this document may wish to run the newer <literal>testing</literal> or <literal>unstable</literal> suites.</para>
        <para><ulink url="https://en.wikipedia.org/wiki/Bodhi">Enlightenment</ulink> with the following saves a person from the eternal <ulink url="https://en.wikipedia.org/wiki/Karma">karmic</ulink> struggle of upgrade <ulink url="https://en.wikipedia.org/wiki/Naraka">hell</ulink> and let him reach Debian <ulink url="https://en.wikipedia.org/wiki/Nirvana">nirvana</ulink>.</para>
        <para> This list is targeted for the <emphasis role="strong">self-administered</emphasis> Desktop environment.</para>
        <itemizedlist>
          <listitem> <para> Use the <literal>testing</literal> suite since it is practically the rolling release automatically managed by the Debian archive QA infrastructure such as the <ulink url="https://ci.debian.net/">Debian continuous integration</ulink>, the <ulink url="https://wiki.debian.org/SourceOnlyUpload">source only upload practices</ulink>, and the <ulink url="https://wiki.debian.org/Teams/ReleaseTeam/TransitionTracker">library transition tracking</ulink>.  The packages in the <literal>testing</literal> suite are updated frequently enough to offer all the latest features.</para> </listitem>
          <listitem> <para> Set the codename corresponding to the <literal>testing</literal> suite ("<literal>@-@codename-testing@-@</literal>" during the <literal>@-@codename-stable@-@</literal>-as-<literal>stable</literal> release cycle) in <emphasis role="strong">the source list</emphasis>. </para> </listitem>
          <listitem> <para> Manually update this codename in <emphasis role="strong">the source list</emphasis> to the new one only after assessing situation by yourself for about a month after the major suite release.  The Debian user and developer mailing list are good sources of information for this, too.  </para> </listitem>
        </itemizedlist>
        <para>The use of the <literal>unstable</literal> suite isn't recommended.  The <literal>unstable</literal> suite is <emphasis role="strong">good for debugging packages</emphasis> as a developer but tends to expose you to unnecessary risks for the normal Desktop usage.  Even though the <literal>unstable</literal> suite of the Debian system looks very stable for most of the times, there have been some package problems and a few of them were not so trivial to resolve. </para>
        <para>Here are some basic precautionary measure ideas to ensure quick and easy recovery from bugs in Debian packages.</para>
        <itemizedlist>
          <listitem> <para> Make the system <emphasis role="strong">dual bootable</emphasis> by installing the <literal>stable</literal> suite of the Debian system to another partition </para> </listitem>
          <listitem> <para> Make the installation CD handy for the <emphasis role="strong">rescue boot</emphasis> </para> </listitem>
          <listitem> <para> Consider installing <literal>apt-listbugs</literal> to check the <ulink url="https://www.debian.org/Bugs/">Debian Bug Tracking System (BTS)</ulink> information before the upgrade </para> </listitem>
          <listitem> <para> Learn the package system infrastructure enough to work around the problem </para> </listitem>
        </itemizedlist>
        <caution> <para>If you can not do any one of these precautionary actions, you are probably not ready for the <literal>testing</literal> and <literal>unstable</literal> suites.</para> </caution>
      </section>
      <section id="_debian_archive_basics">
        <title>Debian archive basics</title>
        <tip> <para>Official policy of the Debian archive is defined at <ulink url="https://www.debian.org/doc/debian-policy/ch-archive">Debian Policy Manual, Chapter 2 - The Debian Archive</ulink>.</para> </tip>
        <para>Let's look into <ulink url="http://deb.debian.org/debian/">the Debian archive</ulink> from a system user's perspective.</para>
        <para>For a system user, <ulink url="http://deb.debian.org/debian/">the Debian archive</ulink> is accessed using the APT system.</para>
        <para>The APT system specifies its data source as <emphasis role="strong">the source list</emphasis> and it is described in <literal>sources.list</literal>(5).</para>
        <para>For the <literal>@-@codename-stable@-@</literal> system with the typical HTTP access, <emphasis role="strong">the source list</emphasis> in one-line-style as the following:</para>
        <screen>deb http://deb.debian.org/debian/ @-@codename-stable@-@ main non-free-firmware contrib non-free
deb-src http://deb.debian.org/debian/ @-@codename-stable@-@ main non-free-firmware contrib non-free

deb http://security.debian.org/debian-security @-@codename-stable@-@-security main non-free-firmware contrib non-free
deb-src http://security.debian.org/debian-security @-@codename-stable@-@-security main non-free-firmware contrib non-free</screen>
        <para>Alternatively, the equivalent source list in deb822-style is the following.</para>
        <screen>Types: deb deb-src
URIs: http://deb.debian.org/debian/
Suites: @-@codename-stable@-@
Components: main non-free-firmware contrib non-free

Types: deb deb-src
URIs: http://security.debian.org/debian-security/
Suites: @-@codename-stable@-@-security
Components: main non-free-firmware contrib non-free</screen>
        <para>Key points of <emphasis role="strong">the source list</emphasis> are followings.</para>
        <itemizedlist>
          <listitem> <para> One-line-style format </para>
            <itemizedlist>
              <listitem> <para> It's definition files are in the "<literal>/etc/apt/sources.list</literal>" file and "<literal>/etc/apt/sources.list.d/*.list</literal>" files.  </para> </listitem>
              <listitem> <para> Each line defines the data source for the APT system.  </para> </listitem>
              <listitem> <para> The "<literal>deb</literal>" line defines for the binary packages.  </para> </listitem>
              <listitem> <para> The "<literal>deb-src</literal>" line defines for the source packages.  </para> </listitem>
              <listitem> <para> The 1st argument is the root URL of the Debian archive.  </para> </listitem>
              <listitem> <para> The 2nd argument is the distribution name using either the suite name or the codename.  </para> </listitem>
              <listitem> <para> The 3rd and following arguments are the list of valid archive area names of the Debian archive.  </para> </listitem>
            </itemizedlist>
          </listitem>
          <listitem> <para> Deb822-style format </para>
            <itemizedlist>
              <listitem> <para> It's definition files are in "<literal>/etc/apt/sources.list.d/*.sources</literal>" files.  </para> </listitem>
              <listitem> <para> Each block of lines separated by a blank line defines the data source for the APT system.  </para> </listitem>
              <listitem> <para> The "<literal>Types:</literal>" stanza defines the list of types such as "<literal>deb</literal>" and "<literal>deb-src</literal>".  </para> </listitem>
              <listitem> <para> The "<literal>URIs:</literal>" stanza defines the list of root URIs of the Debian archive.  </para> </listitem>
              <listitem> <para> The "<literal>Suites:</literal>" stanza defines the list of distribution names using either the suite name or the codename.  </para> </listitem>
              <listitem> <para> The "<literal>Components:</literal>" stanza defines the list of valid archive area names of the Debian archive.  </para> </listitem>
            </itemizedlist>
          </listitem>
        </itemizedlist>
        <para>The definition for "<literal>deb-src</literal>" can safely be omitted if it is just for <literal>aptitude</literal> which does not access source related meta data. It speeds up the updates of the archive meta data. </para>
        <para>The URL can be  "<literal>https://</literal>", "<literal>http://</literal>", "<literal>ftp://</literal>", "<literal>file://</literal>", ….</para>
        <para>Lines starting with "<literal>#</literal>" are comments and ignored. </para>
        <para>Here, I tend to use codename "<literal>@-@codename-stable@-@</literal>" or "<literal>@-@codename-testing@-@</literal>" instead of suite name "<literal>stable</literal>" or "<literal>testing</literal>" to avoid surprises when the next <literal>stable</literal> is released.</para>
        <tip> <para>If "<literal>sid</literal>" is used in the above example instead of "<literal>@-@codename-stable@-@</literal>", the "<literal>deb: http://security.debian.org/ …</literal>" line or its deb822 equivalent content for security updates in <emphasis role="strong">the source list</emphasis> is not required.   This is because there is no security update archive for "<literal>sid</literal>" (<literal>unstable</literal>).</para> </tip>
        <para>Here is the list of URL of the Debian archive sites and suite name or codename used in the configuration file after the <literal>@-@codename-stable@-@</literal> release.</para>
        <table pgwide="0" frame="topbot" rowsep="1" colsep="1">
          <title>List of Debian archive sites</title>
          <tgroup cols="4">
            <colspec colwidth="100pt" align="left"/>
            <colspec colwidth="100pt" align="left"/>
            <colspec colwidth="100pt" align="left"/>
            <colspec colwidth="400pt" align="left"/>
            <thead>
              <row>
                <entry> archive URL </entry>
                <entry> suite name</entry>
                <entry> codename </entry>
                <entry> purpose of repository </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry> <ulink url="http://deb.debian.org/debian/">http://deb.debian.org/debian/</ulink> </entry>
                <entry> <literal>stable</literal> </entry>
                <entry> <literal>@-@codename-stable@-@</literal> </entry>
                <entry> Quasi-static <literal>stable</literal> release after extensive checks </entry>
              </row>
              <row>
                <entry> <ulink url="http://deb.debian.org/debian/">http://deb.debian.org/debian/</ulink> </entry>
                <entry> <literal>testing</literal> </entry>
                <entry> <literal>@-@codename-testing@-@</literal> </entry>
                <entry> Dynamic <literal>testing</literal> release after decent checks and short waits </entry>
              </row>
              <row>
                <entry> <ulink url="http://deb.debian.org/debian/">http://deb.debian.org/debian/</ulink> </entry>
                <entry> <literal>unstable</literal>  </entry>
                <entry> <literal>@-@codename-unstable@-@</literal> </entry>
                <entry> Dynamic <literal>unstable</literal> release after minimal checks and no waits </entry>
              </row>
              <row>
                <entry> <ulink url="http://deb.debian.org/debian/">http://deb.debian.org/debian/</ulink> </entry>
                <entry> <literal>experimental</literal> </entry>
                <entry> N/A </entry>
                <entry> Pre-release experiments by developers (optional, only for developer) </entry>
              </row>
              <row>
                <entry> <ulink url="http://deb.debian.org/debian/">http://deb.debian.org/debian/</ulink> </entry>
                <entry> <literal>stable-proposed-updates</literal> </entry>
                <entry> <literal>@-@codename-stable@-@-proposed-updates</literal> </entry>
                <entry> Updates for the next <literal>stable</literal> point release (optional) </entry>
              </row>
              <row>
                <entry> <ulink url="http://deb.debian.org/debian/">http://deb.debian.org/debian/</ulink> </entry>
                <entry> <literal>stable-updates</literal> </entry>
                <entry> <literal>@-@codename-stable@-@-updates</literal> </entry>
                <entry> Subset of <literal>stable-proposed-updates</literal> suite needing urgent updates such as timezone data (optional) </entry>
              </row>
              <row>
                <entry> <ulink url="http://deb.debian.org/debian/">http://deb.debian.org/debian/</ulink> </entry>
                <entry> <literal>stable-backports</literal>  </entry>
                <entry> <literal>@-@codename-stable@-@-backports</literal> </entry>
                <entry> Random collection of recompiled packages mostly from the <literal>testing</literal> release (optional) </entry>
              </row>
              <row>
                <entry> <ulink url="http://security.debian.org/debian-security/">http://security.debian.org/debian-security/</ulink> </entry>
                <entry> <literal>stable-security</literal> </entry>
                <entry> <literal>@-@codename-stable@-@-security</literal> </entry>
                <entry> Security updates for the <literal>stable</literal> release (important) </entry>
              </row>
              <row>
                <entry> <ulink url="http://security.debian.org/debian-security/">http://security.debian.org/debian-security/</ulink> </entry>
                <entry> <literal>testing-security</literal> </entry>
                <entry> <literal>@-@codename-testing@-@-security</literal> </entry>
                <entry> This isn't actively supported nor used by the security team </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <caution> <para>Only pure <emphasis role="strong"><literal>stable</literal></emphasis> release with security updates provides the best stability. Running mostly <emphasis role="strong"><literal>stable</literal></emphasis> release mixed with some packages from <emphasis role="strong"><literal>testing</literal></emphasis> or <emphasis role="strong"><literal>unstable</literal></emphasis> release is riskier than running pure <emphasis role="strong"><literal>unstable</literal></emphasis> release for library version mismatch etc.  If you really need the latest version of some programs under <emphasis role="strong"><literal>stable</literal></emphasis> release, please use packages from <ulink url="https://wiki.debian.org/StableUpdates">stable-updates</ulink> and <ulink url="https://backports.debian.org">backports</ulink> (see <xref linkend="_updates_and_backports"/>) services.  These services must be used with extra care.</para> </caution>
        <caution>
          <para>You should basically list only one of <literal>stable</literal>, <literal>testing</literal>, or <literal>unstable</literal> suites in the "<literal>deb</literal>" line.  If you list any combination of <literal>stable</literal>, <literal>testing</literal>, and <literal>unstable</literal> suites in the "<literal>deb</literal>" line, APT programs slow down while only the latest archive is effective.  Multiple listing makes sense for these when the "<literal>/etc/apt/preferences</literal>" file is used with clear objectives (see <xref linkend="_tweaking_candidate_version"/>).</para>
        </caution>
        <tip> <para>For the Debian system with the <literal>stable</literal> suite, it is a good idea to include the content with "<literal>http://security.debian.org/</literal>" in <emphasis role="strong">the source list</emphasis> to enable security updates as in the example above.</para> </tip>
        <note> <para>The security bugs for the <literal>stable</literal> archive are fixed by the Debian security team.  This activity has been quite rigorous and reliable.  Those for the <literal>testing</literal> archive may be fixed by the Debian testing security team.  For <ulink url="https://lists.debian.org/debian-testing-security-announce/2008/12/msg00019.html">several</ulink> <ulink url="https://lists.debian.org/debian-testing-security-announce/2010/01/msg00000.html">reasons</ulink>, this activity is not as rigorous as that for <literal>stable</literal> and you may need to wait for the migration of fixed <literal>unstable</literal> packages to the <literal>testing</literal> archive.  Those for the <literal>unstable</literal> archive are fixed by the individual maintainer.  Actively maintained <literal>unstable</literal> packages are usually in a fairly good shape by leveraging latest upstream security fixes.  See <ulink url="https://www.debian.org/security/faq">Debian security FAQ</ulink> for how Debian handles security bugs.</para> </note>
        <table pgwide="0" frame="topbot" rowsep="1" colsep="1">
          <title>List of Debian archive area</title>
          <tgroup cols="3">
            <colspec colwidth="59pt" align="left"/>
            <colspec colwidth="130pt" align="left"/>
            <colspec colwidth="271pt" align="left"/>
            <thead>
              <row>
                <entry> area </entry>
                <entry> number of packages </entry>
                <entry> criteria of package component </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry> <literal>main</literal> </entry>
                <entry> @-@main-packages@-@ </entry>
                <entry> DFSG compliant and no dependency to <literal>non-free</literal> </entry>
              </row>
              <row>
                <entry> <literal>non-free-firmware</literal> </entry>
                <entry> @-@non-free-firmware-packages@-@ </entry>
                <entry> <ulink url="https://www.debian.org/vote/2022/vote_003">not DFSG compliant, firmware required for reasonable system installation experience</ulink> </entry>
              </row>
              <row>
                <entry> <literal>contrib</literal> </entry>
                <entry> @-@contrib-packages@-@ </entry>
                <entry> DFSG compliant but having dependency to <literal>non-free</literal> </entry>
              </row>
              <row>
                <entry> <literal>non-free</literal> </entry>
                <entry> @-@non-free-packages@-@ </entry>
                <entry> not DFSG compliant and not in <literal>non-free-firmware</literal> </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <para>Here the number of packages in the above is for the @-@arch@-@ architecture.  The <literal>main</literal> area provides the Debian system (see <xref linkend="_debian_is_100_free_software"/>).</para>
        <para>The Debian archive organization can be studied best by pointing your browser to the each archive URL appended with <literal>dists</literal> or <literal>pool</literal>.</para>
        <para>The distribution is referred by two ways, the suite or <ulink url="https://www.debian.org/doc/manuals/developers-reference/resources.html#codenames">codename</ulink>. The word distribution is alternatively used as the synonym to the suite in many documentations. The relationship between the suite and the codename can be summarized as the following.</para>
        <table pgwide="0" frame="topbot" rowsep="1" colsep="1">
          <title>The relationship between suite and codename</title>
          <tgroup cols="4">
            <colspec colwidth="233pt" align="left"/>
            <colspec colwidth="195pt" align="left"/>
            <colspec colwidth="217pt" align="left"/>
            <colspec colwidth="103pt" align="left"/>
            <thead>
              <row>
                <entry> Timing </entry>
                <entry> suite = <literal>stable</literal> </entry>
                <entry> suite = <literal>testing</literal> </entry>
                <entry> suite = <literal>unstable</literal> </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry> after the <literal>@-@codename-stable@-@</literal> release </entry>
                <entry> codename = <literal>@-@codename-stable@-@</literal> </entry>
                <entry> codename = <literal>@-@codename-testing@-@</literal> </entry>
                <entry> codename = <literal>sid</literal> </entry>
              </row>
              <row>
                <entry> after the <literal>@-@codename-testing@-@</literal> release </entry>
                <entry> codename = <literal>@-@codename-testing@-@</literal> </entry>
                <entry> codename = <literal>@-@codename-nexttesting@-@</literal> </entry>
                <entry> codename = <literal>sid</literal> </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <para>The history of codenames are described in <ulink url="https://www.debian.org/doc/manuals/debian-faq/ftparchives#oldcodenames">Debian FAQ: 6.2.1 Which other codenames have been used in the past?</ulink></para>
        <para>In the stricter Debian archive terminology, the word "section" is specifically used for the categorization of packages by the application area.  (Although, the word "main section" may sometimes be used to describe the Debian archive area named as "main".)</para>
        <para>Every time a new upload is done by a Debian developer (DD) to the <literal>unstable</literal> archive (via <ulink url="https://incoming.debian.org/">incoming</ulink> processing), the DD is required to ensure uploaded packages to be compatible with the latest set of packages in the latest <literal>unstable</literal> archive.</para>
        <para>If DD breaks this compatibility intentionally for important library upgrade etc, there is usually announcement to <ulink url="https://lists.debian.org/debian-devel/">the debian-devel mailing list</ulink> etc.</para>
        <para>Before a set of packages are moved by the Debian archive maintenance script from the <literal>unstable</literal> archive to the <literal>testing</literal> archive, the archive maintenance script not only checks the maturity (about 2-10 days old) and the status of the RC bug reports for the packages but also tries to ensure them to be compatible with the latest set of packages in the <literal>testing</literal> archive. This process makes the <literal>testing</literal> archive very current and usable.</para>
        <para>Through the gradual archive freeze process led by the release team, the <literal>testing</literal> archive is matured to make it completely consistent and bug free with some manual interventions.  Then the new <literal>stable</literal> release is created by assigning the codename for the old <literal>testing</literal> archive to the new <literal>stable</literal> archive and creating the new codename for the new <literal>testing</literal> archive.  The initial contents of the new <literal>testing</literal> archive is exactly the same as that of the newly released <literal>stable</literal> archive.</para>
        <para>Both the <literal>unstable</literal> and the <literal>testing</literal> archives may suffer temporary glitches due to several factors.</para>
        <itemizedlist>
          <listitem> <para> Broken package upload to the archive (mostly for <literal>unstable</literal>) </para> </listitem>
          <listitem> <para> Delay of accepting the new packages to the archive (mostly for <literal>unstable</literal>) </para> </listitem>
          <listitem> <para> Archive synchronization timing issue (both for <literal>testing</literal> and <literal>unstable</literal>) </para> </listitem>
          <listitem> <para> Manual intervention to the archive such as package removal (more for <literal>testing</literal>) etc.  </para> </listitem>
        </itemizedlist>
        <para>So if you ever decide to use these archives, you should be able to fix or work around these kinds of glitches.</para>
        <caution> <para>For about few months after a new <literal>stable</literal> release, most desktop users should use the <literal>stable</literal> archive with its security updates even if they usually use <literal>unstable</literal> or <literal>testing</literal> archives.  For this transition period, both <literal>unstable</literal> and <literal>testing</literal> archives are not good for most people. Your system is difficult to keep in good working condition with the <literal>unstable</literal> archive since it suffers surges of major upgrades for core packages.  The <literal>testing</literal> archive is not useful either since it contains mostly the same content as the <literal>stable</literal> archive without its security support (<ulink url="https://lists.debian.org/debian-testing-security-announce/2008/12/msg00019.html">Debian testing-security-announce 2008-12</ulink>). After a month or so, <literal>unstable</literal> or <literal>testing</literal> archives may become useful if you are careful.</para> </caution>
        <tip> <para>When tracking the <literal>testing</literal> archive, a problem caused by a removed package is usually worked around by installing corresponding package from the <literal>unstable</literal> archive which is uploaded for bug fix.</para> </tip>
        <para>See <ulink url="https://www.debian.org/doc/debian-policy/">Debian Policy Manual</ulink> for archive definitions.</para>
        <itemizedlist>
          <listitem> <para> "<ulink url="https://www.debian.org/doc/debian-policy/ch-archive#s-subsections">Sections</ulink>" </para> </listitem>
          <listitem> <para> "<ulink url="https://www.debian.org/doc/debian-policy/ch-archive#s-priorities">Priorities</ulink>" </para> </listitem>
          <listitem> <para> "<ulink url="https://www.debian.org/doc/debian-policy/ch-binary#s3.7">Base system</ulink>" </para> </listitem>
          <listitem> <para> "<ulink url="https://www.debian.org/doc/debian-policy/ch-binary#s3.8">Essential packages</ulink>" </para> </listitem>
        </itemizedlist>
      </section>
      <section id="_debian_is_100_free_software">
        <title>Debian is 100% free software</title>
        <para>Debian is 100% free software because of the followings:</para>
        <itemizedlist>
          <listitem> <para> Debian installs only free software by default to respect user's freedoms.  </para> </listitem>
          <listitem> <para> Debian provides only free software in <literal>main</literal>.  </para> </listitem>
          <listitem> <para> Debian recommends running only free software from <literal>main</literal>.  </para> </listitem>
          <listitem> <para> No packages in <literal>main</literal> depend nor recommend packages in <literal>non-free</literal> nor <literal>non-free-firmware</literal> nor <literal>contrib</literal>.  </para> </listitem>
        </itemizedlist>
        <para>Some people wonder if the following 2 facts contradict or not.</para>
        <itemizedlist>
          <listitem> <para> "Debian will remain 100% free". (First term of <ulink url="https://www.debian.org/social_contract">Debian Social Contract</ulink>) </para> </listitem>
          <listitem> <para> Debian servers host some <literal>non-free-firmware</literal>, <literal>non-free</literal> and <literal>contrib</literal> packages.  </para> </listitem>
        </itemizedlist>
        <para>These do not contradict, because of the followings.</para>
        <itemizedlist>
          <listitem> <para> The Debian system is 100% free and its packages are hosted by Debian servers in the <literal>main</literal> area.  </para> </listitem>
          <listitem> <para> Packages outside of the Debian system are hosted by Debian servers in the <literal>non-free</literal>, <literal>non-free-firmware</literal> and <literal>contrib</literal> areas.  </para> </listitem>
        </itemizedlist>
        <para>These are precisely explained in the 4th and 5th terms of <ulink url="https://www.debian.org/social_contract">Debian Social Contract</ulink>:</para>
        <itemizedlist>
          <listitem>
            <para> Our priorities are our users and free software </para>
            <itemizedlist>
              <listitem> <para> We will be guided by the needs of our users and the free software community. We will place their interests first in our priorities. We will support the needs of our users for operation in many different kinds of computing environments. We will not object to non-free works that are intended to be used on Debian systems, or attempt to charge a fee to people who create or use such works. We will allow others to create distributions containing both the Debian system and other works, without any fee from us. In furtherance of these goals, we will provide an integrated system of high-quality materials with no legal restrictions that would prevent such uses of the system.  </para> </listitem>
            </itemizedlist>
          </listitem>
          <listitem>
            <para> Works that do not meet our free software standards </para>
            <itemizedlist>
              <listitem> <para> We acknowledge that some of our users require the use of works that do not conform to the Debian Free Software Guidelines. We have created "<literal>non-free</literal>", "<literal>non-free-firmware</literal>" and "<literal>contrib</literal>" areas in our archive for these works. The packages in these areas are not part of the Debian system, although they have been configured for use with Debian. We encourage CD manufacturers to read the licenses of the packages in these areas and determine if they can distribute the packages on their CDs. Thus, although non-free works are not a part of Debian, we support their use and provide infrastructure for non-free packages (such as our bug tracking system and mailing lists).  The Debian official media may include firmware that is otherwise not part of the Debian system to enable use of Debian with hardware that requires such firmware.</para> </listitem>
            </itemizedlist>
          </listitem>
        </itemizedlist>
        <note> <para>The actual text of the 5th term in the current <ulink url="https://www.debian.org/social_contract">Debian Social Contract</ulink> 1.2 is slightly different from the above text.  This editorial deviation is intentional one to make this user document consistent without changing the real content of the Social Contract.</para> </note>
        <para>Users should be aware of the risks of using packages in the <literal>non-free</literal>, <literal>non-free-firmware</literal> and <literal>contrib</literal> areas:</para>
        <itemizedlist>
          <listitem> <para> lack of freedom for such software packages </para> </listitem>
          <listitem> <para> lack of support from Debian on such software packages (Debian can't support software properly without having access to its source code.) </para> </listitem>
          <listitem> <para> contamination of your 100% free Debian system </para> </listitem>
        </itemizedlist>
        <para>The <ulink url="https://www.debian.org/social_contract#guidelines">Debian Free Software Guidelines</ulink> are the free software standards for <ulink url="https://www.debian.org">Debian</ulink>.  Debian interprets "software" in the widest scope including document, firmware, logo, and artwork data in the package.  This makes Debian's free software standards very strict ones.</para>
        <para>Typical <literal>non-free</literal>, <literal>non-free-firmware</literal> and <literal>contrib</literal> packages include freely distributable packages of following types:</para>
        <itemizedlist>
          <listitem> <para> Document packages under <ulink url="https://en.wikipedia.org/wiki/GNU_Free_Documentation_License">GNU Free Documentation License</ulink> with invariant sections such as ones for GCC and Make.  (mostly found in the <literal>non-free/doc</literal> section.) </para> </listitem>
          <listitem> <para> Firmware packages containing sourceless binary data such as ones listed in <xref linkend="_hardware_drivers_and_firmware"/> as <literal>non-free-firmware</literal>. (mostly found in the <literal>non-free-firmware/kernel</literal> section.) </para> </listitem>
          <listitem> <para> Game and font packages with restriction on commercial use and/or content modification.  </para> </listitem>
        </itemizedlist>
        <para>Please note that the number of <literal>non-free</literal>, <literal>non-free-firmware</literal> and <literal>contrib</literal> packages is less than 2% of that of <literal>main</literal> packages.  Enabling access to the <literal>non-free</literal>, <literal>non-free-firmware</literal> and <literal>contrib</literal> areas does not obscure the source of packages.  Interactive full screen use of <literal>aptitude</literal>(8) provides you with full visibility and control over what packages are installed from which area to keep your system as free as you wish.</para>
      </section>
      <section id="_package_dependencies">
        <title>Package dependencies</title>
        <para>The Debian system offers a consistent set of binary packages through its versioned binary dependency declaration mechanism in the control file fields.   Here is a bit over simplified definition for them.</para>
        <itemizedlist>
          <listitem>
            <para> "Depends" </para>
            <itemizedlist>
              <listitem> <para> This declares an absolute dependency and all of the packages listed in this field must be installed at the same time or in advance.  </para> </listitem>
            </itemizedlist>
          </listitem>
          <listitem>
            <para> "Pre-Depends" </para>
            <itemizedlist>
              <listitem> <para> This is like Depends, except that it requires completed installation of the listed packages in advance.  </para> </listitem>
            </itemizedlist>
          </listitem>
          <listitem>
            <para> "Recommends" </para>
            <itemizedlist>
              <listitem> <para> This declares a strong, but not absolute, dependency.  Most users would not want the package unless all of the packages listed in this field are installed.  </para> </listitem>
            </itemizedlist>
          </listitem>
          <listitem>
            <para> "Suggests" </para>
            <itemizedlist>
              <listitem> <para> This declares a weak dependency.  Many users of this package may benefit from installing packages listed in this field but can have reasonable functions without them.  </para> </listitem>
            </itemizedlist>
          </listitem>
          <listitem>
            <para> "Enhances" </para>
            <itemizedlist>
              <listitem> <para> This declares a weak dependency like Suggests but works in the opposite direction.  </para> </listitem>
            </itemizedlist>
          </listitem>
          <listitem>
            <para> "Breaks" </para>
            <itemizedlist>
              <listitem> <para> This declares a package incompatibility usually with some version specification.  Generally the resolution is to upgrade all of the packages listed in this field.  </para> </listitem>
            </itemizedlist>
          </listitem>
          <listitem>
            <para> "Conflicts" </para>
            <itemizedlist>
              <listitem> <para> This declares an absolute incompatibility.  All of the packages listed in this field must be removed to install this package.  </para> </listitem>
            </itemizedlist>
          </listitem>
          <listitem>
            <para> "Replaces" </para>
            <itemizedlist>
              <listitem> <para> This is declared when files installed by this package replace files in the listed packages.  </para> </listitem>
            </itemizedlist>
          </listitem>
          <listitem>
            <para> "Provides" </para>
            <itemizedlist>
              <listitem> <para> This is declared when this package provide all of the files and functionality in the listed packages.  </para> </listitem>
            </itemizedlist>
          </listitem>
        </itemizedlist>
        <note> <para>Please note that defining "Provides", "Conflicts" and "Replaces" simultaneously to an virtual package is the sane configuration.  This ensures that only one real package providing this virtual package can be installed at any one time.</para> </note>
        <para>The official definition including source dependency can be found in <ulink url="https://www.debian.org/doc/debian-policy/ch-relationships">the Policy Manual: Chapter 7 - Declaring relationships between packages</ulink>.</para>
      </section>
      <section id="_the_event_flow_of_the_package_management">
        <title>The event flow of the package management</title>
        <para>Here is a summary of the simplified event flow of the package management by APT.</para>
        <itemizedlist>
          <listitem>
            <para><emphasis role="strong">Update</emphasis> ("<literal>apt update</literal>", "<literal>aptitude update</literal>" or "<literal>apt-get update</literal>"): </para>
            <orderedlist>
              <listitem> <para> Fetch archive metadata from remote archive </para> </listitem>
              <listitem> <para> Reconstruct and update local metadata for use by APT </para> </listitem>
            </orderedlist>
          </listitem>
          <listitem>
            <para><emphasis role="strong">Upgrade</emphasis> ("<literal>apt upgrade</literal>" and "<literal>apt full-upgrade</literal>", or "<literal>aptitude safe-upgrade</literal>" and "<literal>aptitude full-upgrade</literal>", or "<literal>apt-get upgrade</literal>" and "<literal>apt-get dist-upgrade</literal>"): </para>
            <orderedlist>
              <listitem> <para> Choose candidate version which is usually the latest available version for all installed packages (see <xref linkend="_tweaking_candidate_version"/> for exception) </para> </listitem>
              <listitem> <para> Make package dependency resolution </para> </listitem>
              <listitem> <para> Fetch selected binary packages from remote archive if candidate version is different from installed version </para> </listitem>
              <listitem> <para> Unpack fetched binary packages </para> </listitem>
              <listitem> <para> Run <emphasis role="strong">preinst</emphasis> script </para> </listitem>
              <listitem> <para> Install binary files </para> </listitem>
              <listitem> <para> Run <emphasis role="strong">postinst</emphasis> script </para> </listitem>
            </orderedlist>
          </listitem>
          <listitem>
            <para><emphasis role="strong">Install</emphasis> ("<literal>apt install …</literal>", <literal>aptitude install …</literal>" or "<literal>apt-get install …</literal>"): </para>
            <orderedlist>
              <listitem> <para> Choose packages listed on the command line </para> </listitem>
              <listitem> <para> Make package dependency resolution </para> </listitem>
              <listitem> <para> Fetch selected binary packages from remote archive </para> </listitem>
              <listitem> <para> Unpack fetched binary packages </para> </listitem>
              <listitem> <para> Run <emphasis role="strong">preinst</emphasis> script </para> </listitem>
              <listitem> <para> Install binary files </para> </listitem>
              <listitem> <para> Run <emphasis role="strong">postinst</emphasis> script </para> </listitem>
            </orderedlist>
          </listitem>
          <listitem>
            <para><emphasis role="strong">Remove</emphasis> ("<literal>apt remove …</literal>", "<literal>aptitude remove …</literal>" or "<literal>apt-get remove …</literal>"): </para>
            <orderedlist>
              <listitem>
                <para> Choose packages listed on the command line </para>
              </listitem>
              <listitem>
                <para> Make package dependency resolution </para>
              </listitem>
              <listitem>
                <para> Run <emphasis role="strong">prerm</emphasis> script </para>
              </listitem>
              <listitem>
                <para> Remove installed files <emphasis role="strong">except</emphasis> configuration files </para>
              </listitem>
              <listitem>
                <para> Run <emphasis role="strong">postrm</emphasis> script </para>
              </listitem>
            </orderedlist>
          </listitem>
          <listitem>
            <para><emphasis role="strong">Purge</emphasis> ("<literal>apt purge</literal>", "<literal>aptitude purge …</literal>" or "<literal>apt-get purge …</literal>"): </para>
            <orderedlist>
              <listitem>
                <para> Choose packages listed on the command line </para>
              </listitem>
              <listitem>
                <para> Make package dependency resolution </para>
              </listitem>
              <listitem>
                <para> Run <emphasis role="strong">prerm</emphasis> script </para>
              </listitem>
              <listitem>
                <para> Remove installed files <emphasis role="strong">including</emphasis> configuration files </para>
              </listitem>
              <listitem>
                <para> Run <emphasis role="strong">postrm</emphasis> script </para>
              </listitem>
            </orderedlist>
          </listitem>
        </itemizedlist>
        <para>Here, I intentionally skipped technical details for the sake of big picture.</para>
      </section>
      <section id="_first_response_to_package_management_troubles">
        <title>First response to package management troubles</title>
        <para>You should read the fine official documentation.  The first document to read is the Debian specific "<literal>/usr/share/doc/<emphasis>package_name</emphasis>/README.Debian</literal>".  Other documentation in "<literal>/usr/share/doc/<emphasis>package_name</emphasis>/</literal>" should be consulted too.  If you set shell as <xref linkend="_customizing_bash"/>, type the following.</para>
        <screen>$ cd <emphasis>package_name</emphasis>
$ pager README.Debian
$ mc</screen>
        <para>You may need to install the corresponding documentation package named with "<literal>-doc</literal>" suffix for detailed information.</para>
        <para>If you are experiencing problems with a specific package, make sure to check out <ulink url="https://bugs.debian.org/">the Debian bug tracking system (BTS)</ulink> sites, first.</para>
        <table pgwide="0" frame="topbot" rowsep="1" colsep="1">
          <title>List of key web site to resolving problems with a specific package</title>
          <tgroup cols="2">
            <colspec colwidth="407pt" align="left"/>
            <colspec colwidth="320pt" align="left"/>
            <thead>
              <row>
                <entry> web site </entry>
                <entry> command </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry> Home page of <ulink url="https://bugs.debian.org/">the Debian bug tracking system (BTS)</ulink> </entry>
                <entry> <literal>sensible-browser "https://bugs.debian.org/"</literal> </entry>
              </row>
              <row>
                <entry> The bug report of a known package name </entry>
                <entry> <literal>sensible-browser "https://bugs.debian.org/<emphasis>package_name</emphasis>"</literal> </entry>
              </row>
              <row>
                <entry> The bug report of known bug number </entry>
                <entry> <literal>sensible-browser "https://bugs.debian.org/<emphasis>bug_number</emphasis>"</literal> </entry>
              </row>
            </tbody>
            </tgroup>
        </table>
        <para>Search <ulink url="https://www.google.com">Google</ulink> with search words including "<literal>site:debian.org</literal>", "<literal>site:wiki.debian.org</literal>", "<literal>site:lists.debian.org</literal>", etc.</para>
        <para>When you file a bug report, please use <literal>reportbug</literal>(1) command.</para>
      </section>
      <section id="_how_to_pick_debian_packages">
        <title>How to pick Debian packages</title>
        <para>When you encounter more than 2 similar packages and wonder which one to install without "trial and error" efforts, you should use some <emphasis role="strong">common sense</emphasis>.  I consider following points are good indications of preferred packages.</para>
        <itemizedlist>
          <listitem> <para> Essential: yes &gt; no </para> </listitem>
          <listitem> <para> Area: main &gt; contrib &gt; non-free </para> </listitem>
          <listitem> <para> Priority: required &gt; important &gt; standard &gt; optional &gt; extra </para> </listitem>
          <listitem> <para> Tasks: packages listed in tasks such as "Desktop environment" </para> </listitem>
          <listitem> <para> Packages selected by the dependency package (e.g., <literal>gcc-10</literal> by <literal>gcc</literal>) </para> </listitem>
          <listitem> <para> Popcon: higher in the vote and install number </para> </listitem>
          <listitem> <para> Changelog: regular updates by the maintainer </para> </listitem>
          <listitem> <para> BTS: No RC bugs (no critical, no grave, and no serious bugs) </para> </listitem>
          <listitem> <para> BTS: responsive maintainer to bug reports </para> </listitem>
          <listitem> <para> BTS: higher number of the recently fixed bugs </para> </listitem>
          <listitem> <para> BTS: lower number of remaining non-wishlist bugs </para> </listitem>
        </itemizedlist>
        <para>Debian being a volunteer project with distributed development model, its archive contains many packages with different focus and quality.  You must make your own decision what to do with them.</para>
      </section>
      <section id="_how_to_cope_with_conflicting_requirements">
        <title>How to cope with conflicting requirements</title>
        <para>Whatever suite of Debian system you may decide to use, you may still wish to run versions of programs which aren't available in that suite.  Even if you find binary packages of such programs in other Debian suites or in other non-Debian resources, their requirements may conflict with your current Debian system.</para>
        <para>Although you can tweak package management system with <emphasis role="strong">apt-pinning</emphasis> technique etc. as described in <xref linkend="_tweaking_candidate_version"/> to instal such out-of-sync binary packages, such tweaking approaches have only limited use cases since they may break those programs and your system.</para>
        <para>Before brutally installing such out-of-sync packages, you should seek all available alternative safer technical solutions which are compatible with your current Debian syetem.</para>
        <itemizedlist>
          <listitem>
            <para> Install such programs using corresponding sandboxed upstream binary packages (see <xref linkend="_sandbox"/>). </para>
            <itemizedlist>
              <listitem> <para> Many mostly GUI programs such as LibreOffice and GNOME applications are available as
              <ulink url="https://en.wikipedia.org/wiki/Flatpak">Flatpak</ulink>,
              <ulink url="https://en.wikipedia.org/wiki/Snap_(software)">Snap</ulink>, or
              <ulink url="https://en.wikipedia.org/wiki/AppImage">AppImage</ulink> packages. </para> </listitem>
            </itemizedlist>
          </listitem>
          <listitem>
            <para> Create a chroot or similar environment and run such programs in it (see <xref linkend="_virtualized_system"/>). </para>
            <itemizedlist>
              <listitem> <para> CLI commands can be executed easily under its compatible chroot (see <xref linkend="_chroot_system"/>). </para> </listitem>
              <listitem> <para> Multiple full desktop environments can be tried easily without reboot (see <xref linkend="_multiple_desktop_systems"/>). </para> </listitem>
            </itemizedlist>
          </listitem>
          <listitem>
            <para> Build desired versions of binary packages which are compatible with your current Debian syetem by yourself. </para>
            <itemizedlist>
              <listitem> <para> This is a <ulink url="https://www.debian.org/doc/manuals/debmake-doc/">non-trivial task</ulink> (see <xref linkend="_porting_a_package_to_the_stable_system"/>).</para> </listitem>
            </itemizedlist>
          </listitem>
        </itemizedlist>
      </section>
    </section>
    <section id="_basic_package_management_operations">
      <title>Basic package management operations</title>
      <para>Repository based package management operations on the Debian system can be performed by many APT-based package management tools available on the Debian system.  Here, we explain 3 basic package management tools: <literal>apt</literal>, <literal>apt-get</literal> / <literal>apt-cache</literal> and <literal>aptitude</literal>.</para>
      <para>For the package management operation which involves package installation or updates package metadata, you need to have root privilege.</para>
      <section id="_literal_apt_literal_vs_literal_apt_get_literal_literal_apt_cache_literal_vs_literal_aptitude_literal">
        <title><literal>apt</literal> vs. <literal>apt-get</literal> / <literal>apt-cache</literal> vs. <literal>aptitude</literal></title>
        <para>Although <literal>aptitude</literal> is a very nice interactive tool which the author mainly uses, you should know some cautionary facts:</para>
        <itemizedlist>
          <listitem>
            <para> The <literal>aptitude</literal> command is not recommended for the release-to-release system upgrade on the <literal>stable</literal> Debian system after the new release.  </para>
            <itemizedlist>
              <listitem> <para> The use of "<literal>apt full-upgrade</literal>" or "<literal>apt-get dist-upgrade</literal>" is recommended for it.  See <ulink url="https://bugs.debian.org/411280">Bug #411280</ulink>.  </para> </listitem>
            </itemizedlist>
          </listitem>
          <listitem>
            <para> The <literal>aptitude</literal> command sometimes suggests mass package removals for the system upgrade on the <literal>testing</literal> or <literal>unstable</literal> Debian system.  </para>
            <itemizedlist>
              <listitem> <para> This situation has frightened many system administrators.  Don't panic.  </para> </listitem>
              <listitem> <para> This seems to be caused mostly by the version skew among packages depended or recommended by a meta-package such as <literal>gnome-core</literal>.  </para> </listitem>
              <listitem> <para> This can be resolved by selecting "Cancel pending actions" in the <literal>aptitude</literal> command menu, exiting <literal>aptitude</literal>, and using "<literal>apt full-upgrade</literal>".  </para> </listitem>
            </itemizedlist>
          </listitem>
        </itemizedlist>
        <para>The <literal>apt-get</literal> and <literal>apt-cache</literal> commands are the most <emphasis role="strong">basic</emphasis> APT-based package management tools.</para>
        <itemizedlist>
          <listitem> <para><literal>apt-get</literal> and <literal>apt-cache</literal> offer only the commandline user interface.  </para> </listitem>
          <listitem> <para><literal>apt-get</literal> is most suitable for the <emphasis role="strong">major system upgrade</emphasis> between releases, etc.  </para> </listitem>
          <listitem> <para><literal>apt-get</literal> offers a <emphasis role="strong">robust</emphasis> package dependency resolver.  </para> </listitem>
          <listitem> <para><literal>apt-get</literal> is less demanding on hardware resources.  It consumes less memory and runs faster.  </para> </listitem>
          <listitem> <para><literal>apt-cache</literal> offers a <emphasis role="strong">standard</emphasis> regex based search on the package name and description.  </para> </listitem>
          <listitem> <para><literal>apt-get</literal> and <literal>apt-cache</literal> can manage multiple versions of packages using <literal>/etc/apt/preferences</literal> but it is quite cumbersome.  </para> </listitem>
        </itemizedlist>
        <para>The <literal>apt</literal> command is a high-level commandline interface for package management. It is basically a wrapper of <literal>apt-get</literal>, <literal>apt-cache</literal> and similar commands, originally intended as an end-user interface and enables some options better suited for interactive usage by default.</para>
        <itemizedlist>
          <listitem> <para><literal>apt</literal> provides a friendly progress bar when installing packages using <literal>apt install</literal>.  </para> </listitem>
          <listitem> <para><literal>apt</literal> will <emphasis role="strong">remove</emphasis> cached <literal>.deb</literal> packages by default after sucessful installation of downloaded packages.  </para> </listitem>
        </itemizedlist>
        <tip> <para>Users are recommended to use the new <literal>apt</literal>(8) command for <emphasis role="strong">interactive</emphasis> usage and use the <literal>apt-get</literal>(8) and <literal>apt-cache</literal>(8) commands in the shell script.</para> </tip>
        <para>The <literal>aptitude</literal> command is the most <emphasis role="strong">versatile</emphasis> APT-based package management tool.</para>
        <itemizedlist>
          <listitem> <para><literal>aptitude</literal> offers the fullscreen interactive text user interface.  </para> </listitem>
          <listitem> <para><literal>aptitude</literal> offers the commandline user interface, too.  </para> </listitem>
          <listitem> <para><literal>aptitude</literal> is most suitable for the <emphasis role="strong">daily interactive package management</emphasis> such as inspecting installed packages and searching available packages.  </para> </listitem>
          <listitem> <para><literal>aptitude</literal> is more demanding on hardware resources.  It consumes more memory and runs slower.  </para> </listitem>
          <listitem> <para><literal>aptitude</literal> offers an <emphasis role="strong">enhanced</emphasis> regex based search on all of the package metadata.  </para> </listitem>
          <listitem> <para><literal>aptitude</literal> can manage multiple versions of packages without using <literal>/etc/apt/preferences</literal> and it is quite intuitive.  </para> </listitem>
        </itemizedlist>
      </section>
      <section id="_basic_package_management_operations_with_the_commandline">
        <title>Basic package management operations with the commandline</title>
        <para>Here are basic package management operations with the commandline using <literal>apt</literal>(8), <literal>aptitude</literal>(8) and <literal>apt-get</literal>(8) /<literal>apt-cache</literal>(8).</para>
        <table pgwide="0" frame="topbot" rowsep="1" colsep="1">
          <title>Basic package management operations with the commandline using <literal>apt</literal>(8), <literal>aptitude</literal>(8) and <literal>apt-get</literal>(8) /<literal>apt-cache</literal>(8)</title>
          <tgroup cols="4">
            <colspec colwidth="114pt" align="left"/>
            <colspec colwidth="146pt" align="left"/>
            <colspec colwidth="179pt" align="left"/>
            <colspec colwidth="423pt" align="left"/>
            <thead>
              <row>
                <entry><literal>apt</literal> syntax </entry>
		<entry><literal>aptitude</literal> syntax </entry>
                <entry><literal>apt-get</literal>/<literal>apt-cache</literal> syntax </entry>
                <entry> description </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry> <literal>apt update</literal> </entry>
                <entry> <literal>aptitude update</literal> </entry>
                <entry> <literal>apt-get update</literal> </entry>
                <entry> update package archive metadata </entry>
              </row>
              <row>
                <entry> <literal>apt install foo</literal> </entry>
                <entry> <literal>aptitude install foo</literal> </entry>
                <entry> <literal>apt-get install foo</literal> </entry>
                <entry> install candidate version of "<literal>foo</literal>" package with its dependencies </entry>
              </row>
              <row>
                <entry> <literal>apt upgrade</literal> </entry>
                <entry> <literal>aptitude safe-upgrade</literal> </entry>
                <entry> <literal>apt-get upgrade</literal> </entry>
                <entry> install candidate version of installed packages without removing any other packages </entry>
              </row>
              <row>
                <entry> <literal>apt full-upgrade</literal> </entry>
                <entry> <literal>aptitude full-upgrade</literal> </entry>
                <entry> <literal>apt-get dist-upgrade</literal> </entry>
                <entry> install candidate version of installed packages while removing other packages if needed </entry>
              </row>
              <row>
                <entry> <literal>apt remove foo</literal> </entry>
                <entry> <literal>aptitude remove foo</literal> </entry>
                <entry> <literal>apt-get remove foo</literal> </entry>
                <entry> remove "<literal>foo</literal>" package while leaving its configuration files </entry>
              </row>
              <row>
                <entry> <literal>apt autoremove</literal> </entry>
                <entry> N/A </entry>
                <entry> <literal>apt-get autoremove</literal> </entry>
                <entry> remove auto-installed packages which are no longer required </entry>
              </row>
              <row>
                <entry> <literal>apt purge foo</literal> </entry>
                <entry> <literal>aptitude purge foo</literal> </entry>
                <entry> <literal>apt-get purge foo</literal> </entry>
                <entry> purge "<literal>foo</literal>" package with its configuration files </entry>
              </row>
              <row>
                <entry> <literal>apt clean</literal> </entry>
                <entry> <literal>aptitude clean</literal> </entry>
                <entry> <literal>apt-get clean</literal> </entry>
                <entry> clear out the local repository of retrieved package files completely </entry>
              </row>
              <row>
                <entry> <literal>apt autoclean</literal> </entry>
                <entry> <literal>aptitude autoclean</literal> </entry>
                <entry> <literal>apt-get autoclean</literal> </entry>
                <entry> clear out the local repository of retrieved package files for outdated packages </entry>
              </row>
              <row>
                <entry> <literal>apt show foo</literal> </entry>
                <entry> <literal>aptitude show foo</literal> </entry>
                <entry> <literal>apt-cache show foo</literal> </entry>
                <entry> display detailed information about "<literal>foo</literal>" package </entry>
              </row>
              <row>
                <entry> <literal>apt search <emphasis>regex</emphasis></literal> </entry>
                <entry> <literal>aptitude search <emphasis>regex</emphasis></literal> </entry>
                <entry> <literal>apt-cache search <emphasis>regex</emphasis></literal> </entry>
                <entry> search packages which match <emphasis>regex</emphasis> </entry>
              </row>
              <row>
                <entry> N/A </entry>
                <entry> <literal>aptitude why <emphasis>regex</emphasis></literal> </entry>
                <entry> N/A </entry>
                <entry> explain the reason why <emphasis>regex</emphasis> matching packages should be installed </entry>
              </row>
              <row>
                <entry> N/A </entry>
                <entry> <literal>aptitude why-not <emphasis>regex</emphasis></literal> </entry>
                <entry> N/A </entry>
                <entry> explain the reason why <emphasis>regex</emphasis> matching packages can not be installed </entry>
              </row>
              <row>
                <entry> <literal>apt list --manual-installed</literal> </entry>
                <entry> <literal>aptitude search '~i!~M'</literal> </entry>
                <entry> <literal>apt-mark showmanual</literal> </entry>
                <entry> list manually installed packages </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <para><literal>apt</literal> / <literal>apt-get</literal> and <literal>aptitude</literal> can be mixed without major troubles.</para>
        <para>The "<literal>aptitude why <emphasis>regex</emphasis></literal>" can list more information by "<literal>aptitude -v why <emphasis>regex</emphasis></literal>".  Similar information can be obtained by "<literal>apt rdepends <emphasis>package</emphasis></literal>" or "<literal>apt-cache rdepends <emphasis>package</emphasis></literal>".</para>
        <para>When <literal>aptitude</literal> command is started in the commandline mode and faces some issues such as package conflicts, you can switch to the full screen interactive mode by pressing "<literal>e</literal>"-key later at the prompt.</para>
        <note> <para>Although the <literal>aptitude</literal> command comes with rich features such as its enhanced package resolver, this complexity has caused (or may still causes) some regressions such as <ulink url="https://bugs.debian.org/411123">Bug #411123</ulink>, <ulink url="https://bugs.debian.org/514930">Bug #514930</ulink>, and <ulink url="https://bugs.debian.org/570377">Bug #570377</ulink>.  In case of doubt, please use the <literal>apt</literal>, <literal>apt-get</literal> and <literal>apt-cache</literal> commands over the <literal>aptitude</literal> command.</para> </note>
        <para>You may provide command options right after "<literal>aptitude</literal>".</para>
        <table pgwide="0" frame="topbot" rowsep="1" colsep="1">
          <title>Notable command options for <literal>aptitude</literal>(8)</title>
          <tgroup cols="2">
            <colspec colwidth="81pt" align="left"/>
            <colspec colwidth="396pt" align="left"/>
            <thead>
              <row>
                <entry> command option </entry>
                <entry> description </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry> <literal>-s</literal> </entry>
                <entry> simulate the result of the command </entry>
              </row>
              <row>
                <entry> <literal>-d</literal> </entry>
                <entry> download only but no install/upgrade </entry>
              </row>
              <row>
                <entry> <literal>-D</literal> </entry>
                <entry> show brief explanations before the automatic installations and removals </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <para>See <literal>aptitude</literal>(8) and "aptitude user's manual" at "<literal>/usr/share/doc/aptitude/README</literal>" for more.</para>
      </section>
      <section id="_interactive_use_of_aptitude">
        <title>Interactive use of aptitude</title>
        <para>For the interactive package management, you start <literal>aptitude</literal> in interactive mode from the console shell prompt as follows.</para>
        <screen>$ sudo aptitude -u
Password:</screen>
        <para>This updates the local copy of the archive information and display the package list in the full screen with menu.  Aptitude places its configuration at "<literal>~/.aptitude/config</literal>".</para>
        <tip> <para>If you want to use root's configuration instead of user's one, use "<literal>sudo -H aptitude …</literal>" instead of "<literal>sudo aptitude …</literal>" in the above expression.</para> </tip>
        <tip> <para><literal>Aptitude</literal> automatically sets <emphasis role="strong">pending actions</emphasis> as it is started interactively. If you do not like it, you can reset it from menu: "Action" → "Cancel pending actions".</para> </tip>
      </section>
      <section id="_key_bindings_of_aptitude">
        <title>Key bindings of aptitude</title>
        <para>Notable key strokes to browse status of packages and to set "planned action" on them in this full screen mode are the following.</para>
        <table pgwide="0" frame="topbot" rowsep="1" colsep="1">
          <title>List of key bindings for aptitude</title>
          <tgroup cols="2">
            <colspec colwidth="206pt" align="left"/>
            <colspec colwidth="347pt" align="left"/>
            <thead>
              <row>
                <entry> key </entry>
                <entry> key binding </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry><literal>F10</literal> or <literal>Ctrl-t</literal> </entry>
                <entry> menu </entry>
              </row>
              <row>
                <entry> <literal>?</literal> </entry>
                <entry> display <emphasis role="strong">help</emphasis> for keystroke (more complete listing) </entry>
              </row>
              <row>
                <entry><literal>F10</literal> → Help → User's Manual </entry>
                <entry> display User's Manual </entry>
              </row>
              <row>
                <entry> <literal>u</literal> </entry>
                <entry> update package archive information </entry>
              </row>
              <row>
                <entry> <literal>+</literal> </entry>
                <entry> mark the package for the <emphasis role="strong">upgrade</emphasis> or the <emphasis role="strong">install</emphasis> </entry>
              </row>
              <row>
                <entry> <literal>-</literal> </entry>
                <entry> mark the package for the <emphasis role="strong">remove</emphasis> (keep configuration files) </entry>
              </row>
              <row>
                <entry> <literal>_</literal> </entry>
                <entry> mark the package for the <emphasis role="strong">purge</emphasis> (remove configuration files) </entry>
              </row>
              <row>
                <entry> <literal>=</literal> </entry>
                <entry> place the package on <emphasis role="strong">hold</emphasis> </entry>
              </row>
              <row>
                <entry> <literal>U</literal> </entry>
                <entry> mark all upgradable packages (function as <emphasis role="strong">full-upgrade</emphasis>) </entry>
              </row>
              <row>
                <entry> <literal>g</literal> </entry>
                <entry> start <emphasis role="strong">downloading</emphasis> and <emphasis role="strong">installing</emphasis> selected packages </entry>
              </row>
              <row>
                <entry> <literal>q</literal> </entry>
                <entry> quit current screen and save changes </entry>
              </row>
              <row>
                <entry> <literal>x</literal> </entry>
                <entry> quit current screen and discard changes </entry>
              </row>
              <row>
                <entry> <literal>Enter</literal> </entry>
                <entry> view information about a package </entry>
              </row>
              <row>
                <entry> <literal>C</literal> </entry>
                <entry> view a package's changelog </entry>
              </row>
              <row>
                <entry> <literal>l</literal> </entry>
                <entry> change the limit for the displayed packages </entry>
              </row>
              <row>
                <entry> <literal>/</literal> </entry>
                <entry> search for the first match </entry>
              </row>
              <row>
                <entry> <literal>\</literal> </entry>
                <entry> repeat the last search </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <para>The file name specification of the command line and the menu prompt after pressing "<literal>l</literal>" and "<literal>//</literal>" take the aptitude regex as described below.  Aptitude regex can explicitly match a package name using a string started by "<literal>~n</literal>" and followed by the package name.</para>
        <tip> <para>You need to press "<literal>U</literal>" to get all the installed packages upgraded to the <emphasis role="strong">candidate version</emphasis> in the visual interface.  Otherwise only the selected packages and certain packages with versioned dependency to them are upgraded to the <emphasis role="strong">candidate version</emphasis>.</para> </tip>
      </section>
      <section id="_package_views_under_aptitude">
        <title>Package views under aptitude</title>
        <para>In the interactive full screen mode of <literal>aptitude</literal>(8), packages in the package list are displayed as the next example.</para>
        <screen>idA   libsmbclient                             -2220kB 3.0.25a-1  3.0.25a-2</screen>
        <para>Here, this line means from the left as the following.</para>
        <itemizedlist>
          <listitem> <para> The "current state" flag (the first letter) </para> </listitem>
          <listitem> <para> The "planned action" flag (the second letter) </para> </listitem>
          <listitem> <para> The "automatic" flag (the  third letter) </para> </listitem>
          <listitem> <para> The Package name </para> </listitem>
          <listitem> <para> The change in disk space usage attributed to "planned action" </para> </listitem>
          <listitem> <para> The current version of the package </para> </listitem>
          <listitem> <para> The candidate version of the package </para> </listitem>
        </itemizedlist>
        <tip> <para>The full list of flags are given at the bottom of <emphasis role="strong">Help</emphasis> screen shown by pressing "<literal>?</literal>".</para> </tip>
        <para>The <emphasis role="strong">candidate version</emphasis> is chosen according to the current local preferences (see <literal>apt_preferences</literal>(5) and <xref linkend="_tweaking_candidate_version"/>).</para>
        <para>Several types of package views are available under the menu "<literal>Views</literal>".</para>
        <table pgwide="0" frame="topbot" rowsep="1" colsep="1">
          <title>List of views for aptitude</title>
          <tgroup cols="2">
            <colspec colwidth="130pt" align="left"/>
            <colspec colwidth="521pt" align="left"/>
            <thead>
              <row>
                <entry> view </entry>
                <entry> description of view </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry> <literal>Package View</literal> </entry>
                <entry> see <xref linkend="standard-package-views"/> (default) </entry>
              </row>
              <row>
                <entry> <literal>Audit Recommendations</literal> </entry>
                <entry> list packages which are recommended by some installed packages but not yet installed </entry>
              </row>
              <row>
                <entry> <literal>Flat Package List</literal> </entry>
                <entry> list packages without categorization (for use with regex) </entry>
              </row>
              <row>
                <entry> <literal>Debtags Browser</literal> </entry>
                <entry> list packages categorized according to their <ulink url="https://debtags.debian.org/">debtags</ulink> entries </entry>
              </row>
              <row>
                <entry> <literal>Source Package View</literal> </entry>
                <entry> list packages grouped by source packages </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <note> <para>Please help us <ulink url="https://debtags.debian.org/getting-started/">improving tagging packages with debtags!</ulink></para> </note>
        <para>The standard "<literal>Package View</literal>" categorizes packages somewhat like <literal>dselect</literal> with few extra features.</para>
        <table id="standard-package-views" pgwide="0" frame="topbot" rowsep="1" colsep="1">
          <title>The categorization of standard package views</title>
          <tgroup cols="2">
            <colspec colwidth="217pt" align="left"/>
            <colspec colwidth="439pt" align="left"/>
            <thead>
              <row>
                <entry> category </entry>
                <entry> description of view </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry> <literal>Upgradable Packages</literal> </entry>
                <entry> list packages organized as <literal>section</literal> → <literal>area</literal> → <literal>package</literal> </entry>
              </row>
              <row>
                <entry> <literal>New Packages</literal> </entry>
                <entry> , , </entry>
              </row>
              <row>
                <entry> <literal>Installed Packages</literal> </entry>
                <entry> , , </entry>
              </row>
              <row>
                <entry> <literal>Not Installed Packages</literal> </entry>
                <entry> , , </entry>
              </row>
              <row>
                <entry> <literal>Obsolete and Locally Created Packages</literal> </entry>
                <entry> , , </entry>
              </row>
              <row>
                <entry> <literal>Virtual Packages</literal> </entry>
                <entry> list packages with the same function </entry>
              </row>
              <row>
                <entry> <literal>Tasks</literal> </entry>
                <entry> list packages with different functions generally needed for a task </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <tip> <para><literal>Tasks</literal> view can be used to cherry pick packages for your task.</para> </tip>
      </section>
      <section id="_search_method_options_with_aptitude">
        <title>Search method options with aptitude</title>
        <para>Aptitude offers several options for you to search packages using its regex formula.</para>
        <itemizedlist>
          <listitem>
            <para> Shell commandline: </para>
            <itemizedlist>
              <listitem>
                <para> "<literal>aptitude search '<emphasis>aptitude_regex</emphasis>'</literal>" to list installation status, package name and short description of matching packages </para>
              </listitem>
              <listitem>
                <para> "<literal>aptitude show '<emphasis>package_name</emphasis>'</literal>" to list detailed description of the package </para>
              </listitem>
            </itemizedlist>
          </listitem>
          <listitem>
            <para> Interactive full screen mode: </para>
            <itemizedlist>
              <listitem> <para> "<literal>l</literal>" to limit package view to matching packages </para> </listitem>
              <listitem> <para> "<literal>/</literal>" for search to a matching package </para> </listitem>
              <listitem> <para> "<literal>\</literal>" for backward search to a matching package </para> </listitem>
              <listitem> <para> "<literal>n</literal>" for find-next </para> </listitem>
              <listitem> <para> "<literal>N</literal>" for find-next (backward) </para> </listitem>
            </itemizedlist>
          </listitem>
        </itemizedlist>
        <tip> <para>The string for <emphasis>package_name</emphasis> is treated as the exact string match to the package name unless it is started explicitly with "<literal>~</literal>" to be the regex formula.</para> </tip>
      </section>
      <section id="_the_aptitude_regex_formula">
        <title>The aptitude regex formula</title>
        <para>The aptitude regex formula is mutt-like extended <emphasis role="strong">ERE</emphasis> (see <xref linkend="_regular_expressions"/>) and the meanings of the <literal>aptitude</literal> specific special match rule extensions are as follows.</para>
        <table pgwide="0" frame="topbot" rowsep="1" colsep="1">
          <title>List of the aptitude regex formula</title>
          <tgroup cols="2">
            <colspec colwidth="494pt" align="left"/>
            <colspec colwidth="304pt" align="left"/>
            <thead>
              <row>
                <entry> description of the extended match rule </entry>
                <entry> regex formula </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry> match on package name </entry>
                <entry> <literal>~n<emphasis>regex_name</emphasis></literal> </entry>
              </row>
              <row>
                <entry> match on description </entry>
                <entry> <literal>~d<emphasis>regex_description</emphasis></literal> </entry>
              </row>
              <row>
                <entry> match on task name </entry>
                <entry> <literal>~t<emphasis>regex_task</emphasis></literal> </entry>
              </row>
              <row>
                <entry> match on debtag </entry>
                <entry> <literal>~G<emphasis>regex_debtag</emphasis></literal> </entry>
              </row>
              <row>
                <entry> match on maintainer </entry>
                <entry> <literal>~m<emphasis>regex_maintainer</emphasis></literal> </entry>
              </row>
              <row>
                <entry> match on package section </entry>
                <entry> <literal>~s<emphasis>regex_section</emphasis></literal> </entry>
              </row>
              <row>
                <entry> match on package version </entry>
                <entry> <literal>~V<emphasis>regex_version</emphasis></literal> </entry>
              </row>
              <row>
                <entry> match archive </entry>
                <entry><literal>~A{@-@codename-stable@-@,@-@codename-testing@-@,sid</literal>} </entry>
	      </row>
              <row>
                <entry> match origin </entry>
                <entry><literal>~O{debian,…</literal>} </entry>
              </row>
              <row>
                <entry> match priority </entry>
                <entry><literal>~p{extra,important,optional,required,standard</literal>} </entry>
              </row>
              <row>
                <entry> match essential packages </entry>
                <entry> <literal>~E</literal> </entry>
              </row>
              <row>
                <entry> match virtual packages </entry>
                <entry> <literal>~v</literal> </entry>
              </row>
              <row>
                <entry> match new packages </entry>
                <entry> <literal>~N</literal> </entry>
              </row>
              <row>
                <entry> match with pending action </entry>
                <entry><literal>~a{install,upgrade,downgrade,remove,purge,hold,keep</literal>} </entry>
              </row>
              <row>
                <entry> match installed packages </entry>
                <entry> <literal>~i</literal> </entry>
              </row>
              <row>
                <entry> match installed packages with <emphasis role="strong">A</emphasis>-mark (auto installed packages) </entry>
                <entry> <literal>~M</literal> </entry>
              </row>
              <row>
                <entry> match installed packages without <emphasis role="strong">A</emphasis>-mark (administrator selected packages) </entry>
                <entry> <literal>~i!~M</literal> </entry>
              </row>
              <row>
                <entry> match installed and upgradable packages </entry>
                <entry> <literal>~U</literal> </entry>
              </row>
              <row>
                <entry> match removed but not purged packages </entry>
                <entry> <literal>~c</literal> </entry>
              </row>
              <row>
                <entry> match removed, purged or can-be-removed packages </entry>
                <entry> <literal>~g</literal> </entry>
              </row>
              <row>
                <entry> match packages declaring a broken dependency </entry>
                <entry> <literal>~b</literal> </entry>
              </row>
              <row>
                <entry> match packages declaring broken dependency of <emphasis>type</emphasis> </entry>
                <entry> <literal>~B<emphasis>type</emphasis></literal> </entry>
              </row>
              <row>
                <entry> match <emphasis>pattern</emphasis> packages declaring dependency of <emphasis>type</emphasis> </entry>
                <entry> <literal>~D[<emphasis>type</emphasis>:]<emphasis>pattern</emphasis></literal> </entry>
              </row>
              <row>
                <entry> match <emphasis>pattern</emphasis> packages declaring broken dependency of <emphasis>type</emphasis> </entry>
                <entry> <literal>~DB[<emphasis>type</emphasis>:]<emphasis>pattern</emphasis></literal> </entry>
              </row>
              <row>
                <entry> match packages to which the <emphasis>pattern</emphasis> matching package declares dependency <emphasis>type</emphasis> </entry>
                <entry> <literal>~R[<emphasis>type</emphasis>:]<emphasis>pattern</emphasis></literal> </entry>
              </row>
              <row>
                <entry> match packages to which the <emphasis>pattern</emphasis> matching package declares broken dependency <emphasis>type</emphasis> </entry>
                <entry> <literal>~RB[<emphasis>type</emphasis>:]<emphasis>pattern</emphasis></literal> </entry>
              </row>
              <row>
                <entry> match packages to which some other installed packages depend on </entry>
                <entry> <literal>~R~i</literal> </entry>
              </row>
              <row>
                <entry> match packages to which no other installed packages depend on </entry>
                <entry> <literal>!~R~i</literal> </entry>
              </row>
              <row>
                <entry> match packages to which some other installed packages depend or recommend on </entry>
                <entry> <literal>~R~i|~Rrecommends:~i</literal> </entry>
              </row>
              <row>
                <entry> match <emphasis>pattern</emphasis> package with filtered version </entry>
                <entry> <literal>~S filter <emphasis>pattern</emphasis></literal> </entry>
              </row>
              <row>
                <entry> match all packages (true) </entry>
                <entry> <literal>~T</literal> </entry>
              </row>
              <row>
                <entry> match no packages (false) </entry>
                <entry> <literal>~F</literal> </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <itemizedlist>
          <listitem> <para> The regex part is the same <emphasis role="strong">ERE</emphasis> as the one used in typical Unix-like text tools using "<literal>^</literal>", "<literal>.*</literal>", "<literal>$</literal>" etc. as in <literal>egrep</literal>(1), <literal>awk</literal>(1) and <literal>perl</literal>(1).  </para> </listitem>
          <listitem> <para> The dependency <emphasis>type</emphasis> is one of (depends, predepends, recommends, suggests, conflicts, replaces, provides) specifying the package interrelationship.  </para> </listitem>
          <listitem> <para> The default dependency <emphasis>type</emphasis> is "depends".  </para> </listitem>
        </itemizedlist>
        <tip> <para>When <emphasis>regex_pattern</emphasis> is a null string, place "<literal>~T</literal>" immediately after the command.</para> </tip>
        <para>Here are some short cuts.</para>
        <itemizedlist>
          <listitem> <para> "<literal>~P<emphasis>term</emphasis></literal>" == "<literal>~Dprovides:<emphasis>term</emphasis></literal>" </para> </listitem>
          <listitem> <para> "<literal>~C<emphasis>term</emphasis></literal>" == "<literal>~Dconflicts:<emphasis>term</emphasis></literal>" </para> </listitem>
          <listitem> <para> "<literal>…~W term</literal>" == "<literal>(…|term)</literal>" </para> </listitem>
        </itemizedlist>
        <para>Users familiar with <literal>mutt</literal> pick up quickly, as mutt was the inspiration for the expression syntax. See "SEARCHING, LIMITING, AND EXPRESSIONS" in the "User's Manual" "<literal>/usr/share/doc/aptitude/README</literal>".</para>
        <note> <para>With the <literal>lenny</literal> version of <literal>aptitude</literal>(8), the new <emphasis role="strong">long form</emphasis> syntax such as "<literal>?broken</literal>" may be used for regex matching in place for its old <emphasis role="strong">short form</emphasis> equivalent "<literal>~b</literal>". Now space character "<literal> </literal>" is considered as one of the regex terminating character in addition to tilde character "<literal>~</literal>".  See "User's Manual" for the new <emphasis role="strong">long form</emphasis> syntax.</para> </note>
      </section>
      <section id="_dependency_resolution_of_aptitude">
        <title>Dependency resolution of aptitude</title>
        <para>The selection of a package in <literal>aptitude</literal> not only pulls in packages which are defined in its "<literal>Depends:</literal>" list but also defined in the "<literal>Recommends:</literal>" list if the menu "<literal>F10</literal> → Options → Preferences → Dependency handling" is set accordingly.  These auto installed packages are removed automatically if they are no longer needed under <literal>aptitude</literal>.</para>
        <para>The flag controlling the "auto install" behavior of the <literal>aptitude</literal> command can also be manipulated using the <literal>apt-mark</literal>(8) command from the <literal>apt</literal> package.</para>
      </section>
      <section id="_package_activity_logs">
        <title>Package activity logs</title>
        <para>You can check package activity history in the log files.</para>
        <table pgwide="0" frame="topbot" rowsep="1" colsep="1">
          <title>The log files for package activities</title>
          <tgroup cols="2">
            <colspec colwidth="130pt" align="left"/>
            <colspec colwidth="309pt" align="left"/>
            <thead>
              <row>
                <entry> file </entry>
                <entry> content </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry> <literal>/var/log/dpkg.log</literal> </entry>
                <entry> Log of <literal>dpkg</literal> level activity for all package activities </entry>
              </row>
              <row>
                <entry> <literal>/var/log/apt/term.log</literal> </entry>
                <entry> Log of generic APT activity </entry>
              </row>
              <row>
                <entry> <literal>/var/log/aptitude</literal> </entry>
                <entry> Log of <literal>aptitude</literal> command activity </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <para>In reality, it is not so easy to get meaningful understanding quickly out from these logs.  See <xref linkend="_recording_changes_in_configuration_files"/> for easier way.</para>
      </section>
    </section>
    <section id="_examples_of_aptitude_operations">
      <title>Examples of aptitude operations</title>
      <para>Here are few examples of <literal>aptitude</literal>(8) operations.</para>
      <section id="_seeking_interesting_packages">
        <title>Seeking interesting packages</title>
        <para>You can seek packages which satisfy your needs with <literal>aptitude</literal> from the package description or from the list under "Tasks".</para>
      </section>
      <section id="_listing_packages_with_regex_matching_on_package_names">
        <title>Listing packages with regex matching on package names</title>
        <para>The following command lists packages with regex matching on package names.</para>
        <screen>$ aptitude search '~n(pam|nss).*ldap'
p libnss-ldap - NSS module for using LDAP as a naming service
p libpam-ldap - Pluggable Authentication Module allowing LDAP interfaces</screen>
        <para>This is quite handy for you to find the exact name of a package.</para>
      </section>
      <section id="_browsing_with_the_regex_matching">
        <title>Browsing with the regex matching</title>
        <para>The regex "<literal>~dipv6</literal>" in the "New Flat Package List" view with "<literal>l</literal>" prompt, limits view to packages with the matching description and let you browse their information interactively.</para>
      </section>
      <section id="_purging_removed_packages_for_good">
        <title>Purging removed packages for good</title>
        <para>You can purge all remaining configuration files of removed packages.</para>
        <para>Check results of the following command.</para>
        <screen># aptitude search '~c'</screen>
        <para>If you think listed packages are OK to be purged, execute the following command.</para>
        <screen># aptitude purge '~c'</screen>
        <para>You may want to do the similar in the interactive mode for fine grained control.</para>
        <para>You provide the regex "<literal>~c</literal>" in the "New Package View" view with "<literal>l</literal>" prompt.  This limits the package view only to regex matched packages, i.e., "removed but not purged".  All these regex matched packages can be shown by pressing "<literal>[</literal>" at top level headings.</para>
        <para>Then you press "<literal>_</literal>" at top level headings such as "Not Installed Packages".  Only regex matched packages under the heading are marked to be purged by this.  You can exclude some packages to be purged by pressing "<literal>=</literal>" interactively for each of them.</para>
        <para>This technique is quite handy and works for many other command keys.</para>
      </section>
      <section id="_tidying_auto_manual_install_status">
        <title>Tidying auto/manual install status</title>
        <para>Here is how I tidy auto/manual install status for packages (after using non-aptitude package installer etc.).</para>
        <orderedlist>
          <listitem> <para> Start <literal>aptitude</literal> in interactive mode as root.  </para> </listitem>
          <listitem> <para> Type "<literal>u</literal>", "<literal>U</literal>", "<literal>f</literal>" and "<literal>g</literal>" to update and upgrade package list and packages.  </para> </listitem>
          <listitem> <para> Type "<literal>l</literal>" to enter the package display limit as "<literal>~i(~R~i|~Rrecommends:~i)</literal>" and type "<literal>M</literal>" over "<literal>Installed Packages</literal>" as auto installed.  </para> </listitem>
          <listitem> <para> Type "<literal>l</literal>" to enter the package display limit as "<literal>~prequired|~pimportant|~pstandard|~E</literal>" and type "<literal>m</literal>" over "<literal>Installed Packages</literal>" as manual installed.  </para> </listitem>
          <listitem> <para> Type "<literal>l</literal>" to enter the package display limit as "<literal>~i!~M</literal>" and remove unused package by typing "<literal>-</literal>" over each of them after exposing them by typing "<literal>[</literal>" over "<literal>Installed Packages</literal>".  </para> </listitem>
          <listitem> <para> Type "<literal>l</literal>", to enter the package display limit as "<literal>~i</literal>"; then type "<literal>m</literal>" over "<literal>Tasks</literal>", to mark that packages as manual installed.  </para> </listitem>
          <listitem> <para> Exit <literal>aptitude</literal>.  </para> </listitem>
          <listitem> <para> Start "<literal>apt-get -s autoremove|less</literal>" as root to check what are not used.  </para> </listitem>
          <listitem> <para> Restart <literal>aptitude</literal> in interactive mode and mark needed packages as "<literal>m</literal>".  </para> </listitem>
          <listitem> <para> Restart "<literal>apt-get -s autoremove|less</literal>" as root to recheck REMOVED contain only expected packages.  </para> </listitem>
          <listitem> <para> Start "<literal>apt-get autoremove|less</literal>" as root to autoremove unused packages.  </para> </listitem>
        </orderedlist>
        <para>The "<literal>m</literal>" action over "<literal>Tasks</literal>" is an optional one to prevent mass package removal situation in future.</para>
      </section>
      <section id="_system_wide_upgrade">
        <title>System wide upgrade</title>
        <note> <para>When moving to a new release etc, you should consider to perform a clean installation of new system even though Debian is upgradable as described below.  This provides you a chance to remove garbages collected and exposes you to the best combination of latest packages.  Of course, you should make a full backup of system to a safe place (see <xref linkend="_backup_and_recovery"/>) before doing this. I recommend to make a dual boot configuration using different partition to have the smoothest transition.</para> </note>
        <para>You can perform system wide upgrade to a newer release by changing contents of <emphasis role="strong">the source list</emphasis> pointing to a new release and running the "<literal>apt update; apt dist-upgrade</literal>" command.</para>
        <para>To upgrade from <literal>stable</literal> to <literal>testing</literal> or <literal>unstable</literal> during the <literal>@-@codename-stable@-@</literal>-as-<literal>stable</literal> release cycle, you replace "<literal>@-@codename-stable@-@</literal>" in <emphasis role="strong">the source list</emphasis> example of <xref linkend="_debian_archive_basics"/> with "<literal>@-@codename-testing@-@</literal>" or "<literal>sid</literal>".</para>
        <para>In reality, you may face some complications due to some package transition issues, mostly due to package dependencies.  The larger the difference of the upgrade, the more likely you face larger troubles.  For the transition from the old <literal>stable</literal> to the new <literal>stable</literal> after its release, you can read its new <ulink url="https://www.debian.org/releases/stable/releasenotes">Release Notes</ulink> and follow the exact procedure described in it to minimize troubles.</para>
        <para>When you decide to move from <literal>stable</literal> to <literal>testing</literal> before its formal release, there are no <ulink url="https://www.debian.org/releases/stable/releasenotes">Release Notes</ulink> to help you. The difference between <literal>stable</literal> and <literal>testing</literal> could have grown quite large after the previous <literal>stable</literal> release and makes upgrade situation complicated.</para>
        <para>You should make precautionary moves for the full upgrade while gathering latest information from mailing list and using common senses.</para>
        <orderedlist>
          <listitem> <para> Read previous "Release Notes".  </para> </listitem>
          <listitem> <para> Backup entire system (especially data and configuration information).  </para> </listitem>
          <listitem> <para> Have bootable media handy for broken bootloader.  </para> </listitem>
          <listitem> <para> Inform users on the system well in advance.  </para> </listitem>
          <listitem> <para> Record upgrade activity with <literal>script</literal>(1).  </para> </listitem>
          <listitem> <para> Apply "unmarkauto" to required packages, e.g., "<literal>aptitude unmarkauto vim</literal>", to prevent removal.  </para> </listitem>
          <listitem> <para> Minimize installed packages to reduce chance of package conflicts, e.g., remove desktop task packages.  </para> </listitem>
          <listitem> <para> Remove the "<literal>/etc/apt/preferences</literal>" file (disable <emphasis role="strong">apt-pinning</emphasis>).  </para> </listitem>
          <listitem> <para> Try to upgrade step wise: <literal>oldstable</literal> → <literal>stable</literal> → <literal>testing</literal> → <literal>unstable</literal>.  </para> </listitem>
          <listitem> <para> Update <emphasis role="strong">the source list</emphasis> to point to new archive only and run "<literal>aptitude update</literal>".  </para> </listitem>
          <listitem> <para> Install, optionally, new <emphasis role="strong">core packages</emphasis> first, e.g., "<literal>aptitude install perl</literal>".  </para> </listitem>
          <listitem> <para> Run the "<literal>apt-get -s dist-upgrade</literal>" command to assess impact.  </para> </listitem>
          <listitem> <para> Run the "<literal>apt-get dist-upgrade</literal>" command at last.  </para> </listitem>
        </orderedlist>
        <caution> <para>It is not wise to skip major Debian release when upgrading between <literal>stable</literal> releases.</para> </caution>
        <caution> <para>In previous "Release Notes", GCC, Linux Kernel, initrd-tools, Glibc, Perl, APT tool chain, etc. have required some special attention for system wide upgrade.</para> </caution>
        <para>For daily upgrade in <literal>unstable</literal>, see <xref linkend="_safeguarding_for_package_problems"/>.</para>
      </section>
    </section>
    <section id="_advanced_package_management_operations">
      <title>Advanced package management operations</title>
      <section id="_advanced_package_management_operations_with_commandline">
        <title>Advanced package management operations with commandline</title>
        <para>Here are list of other package management operations for which <literal>aptitude</literal> is too high-level or lacks required functionalities.</para>
        <table pgwide="0" frame="topbot" rowsep="1" colsep="1">
          <title>List of advanced package management operations</title>
          <tgroup cols="2">
            <colspec colwidth="342pt" align="left"/>
            <colspec colwidth="407pt" align="left"/>
            <thead>
              <row>
                <entry> command </entry>
                <entry> action </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry> <literal>COLUMNS=120 dpkg -l <emphasis>package_name_pattern</emphasis></literal> </entry>
                <entry> list status of an installed package for the bug report </entry>
              </row>
              <row>
                <entry> <literal>dpkg -L <emphasis>package_name</emphasis></literal> </entry>
                <entry> list contents of an installed package </entry>
              </row>
              <row>
                <entry> <literal>dpkg -L <emphasis>package_name</emphasis> | egrep '/usr/share/man/man.*/.+'</literal> </entry>
                <entry> list manpages for an installed package </entry>
              </row>
              <row>
                <entry> <literal>dpkg -S <emphasis>file_name_pattern</emphasis></literal> </entry>
                <entry> list installed packages which have matching file name </entry>
              </row>
              <row>
                <entry> <literal>apt-file search <emphasis>file_name_pattern</emphasis></literal> </entry>
                <entry> list packages in archive which have matching file name </entry>
              </row>
              <row>
                <entry> <literal>apt-file list <emphasis>package_name_pattern</emphasis></literal> </entry>
                <entry> list contents of matching packages in archive </entry>
              </row>
              <row>
                <entry> <literal>dpkg-reconfigure <emphasis>package_name</emphasis></literal> </entry>
                <entry> reconfigure the exact package </entry>
              </row>
              <row>
                <entry> <literal>dpkg-reconfigure -plow <emphasis>package_name</emphasis></literal> </entry>
                <entry> reconfigure the exact package with the most detailed question </entry>
              </row>
              <row>
                <entry> <literal>configure-debian</literal> </entry>
                <entry> reconfigure packages from the full screen menu </entry>
              </row>
              <row>
                <entry> <literal>dpkg --audit</literal> </entry>
                <entry> audit system for partially installed packages </entry>
              </row>
              <row>
                <entry> <literal>dpkg --configure -a</literal> </entry>
                <entry> configure all partially installed packages </entry>
              </row>
              <row>
                <entry> <literal>apt-cache policy <emphasis>binary_package_name</emphasis></literal> </entry>
                <entry> show available version, priority, and archive information of a binary package </entry>
              </row>
              <row>
                <entry> <literal>apt-cache madison <emphasis>package_name</emphasis></literal> </entry>
                <entry> show available version, archive information of a package </entry>
              </row>
              <row>
                <entry> <literal>apt-cache showsrc <emphasis>binary_package_name</emphasis></literal> </entry>
                <entry> show source package information of a binary package </entry>
              </row>
              <row>
                <entry> <literal>apt-get build-dep <emphasis>package_name</emphasis></literal> </entry>
                <entry> install required packages to build package </entry>
              </row>
              <row>
                <entry> <literal>aptitude build-dep <emphasis>package_name</emphasis></literal> </entry>
                <entry> install required packages to build package </entry>
              </row>
              <row>
                <entry> <literal>apt-get source <emphasis>package_name</emphasis></literal> </entry>
                <entry> download a source (from standard archive) </entry>
              </row>
              <row>
                <entry> <literal>dget <emphasis>URL for dsc file</emphasis></literal> </entry>
                <entry> download a source packages (from other archive) </entry>
              </row>
              <row>
                <entry> <literal>dpkg-source -x <emphasis>package_name</emphasis>_<emphasis>version</emphasis>-<emphasis>debian.revision</emphasis>.dsc</literal> </entry>
                <entry> build a source tree from a set of source packages ("<literal>*.orig.tar.gz</literal>" and "<literal>*.debian.tar.gz</literal>"/"<literal>*.diff.gz</literal>") </entry>
              </row>
              <row>
                <entry> <literal>debuild binary</literal> </entry>
                <entry> build package(s) from a local source tree </entry>
              </row>
              <row>
                <entry> <literal>make-kpkg kernel_image</literal> </entry>
                <entry> build a kernel package from a kernel source tree </entry>
              </row>
              <row>
                <entry> <literal>make-kpkg --initrd kernel_image</literal> </entry>
                <entry> build a kernel package from a kernel source tree with initramfs enabled </entry>
              </row>
              <row>
                <entry> <literal>dpkg -i <emphasis>package_name</emphasis>_<emphasis>version</emphasis>-<emphasis>debian.revision</emphasis>_<emphasis>arch</emphasis>.deb</literal> </entry>
                <entry> install a local package to the system </entry>
              </row>
              <row>
                <entry> <literal>apt install /path/to/<emphasis>package_filename</emphasis>.deb</literal> </entry>
                <entry> install a local package to the system, meanwhile try to resolve dependency automatically </entry>
              </row>
              <row>
                <entry> <literal>debi <emphasis>package_name</emphasis>_<emphasis>version</emphasis>-<emphasis>debian.revision</emphasis>_<emphasis>arch</emphasis>.dsc</literal> </entry>
                <entry> install local package(s) to the system </entry>
              </row>
              <row>
                <entry> <literal>dpkg --get-selections '*' &gt;selection.txt</literal> </entry>
                <entry> save <literal>dpkg</literal> level package selection state information </entry>
              </row>
              <row>
                <entry> <literal>dpkg --set-selections &lt;selection.txt</literal> </entry>
                <entry> set <literal>dpkg</literal> level package selection state information </entry>
              </row>
              <row>
                <entry> <literal>echo <emphasis>package_name</emphasis> hold | dpkg --set-selections</literal> </entry>
                <entry> set <literal>dpkg</literal> level package selection state for a package to <emphasis role="strong">hold</emphasis>  (equivalent to "<literal>aptitude hold <emphasis>package_name</emphasis></literal>") </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <note> <para>For a package with the <ulink url="https://wiki.debian.org/Multiarch">multi-arch</ulink> feature, you may need to specify the architecture name for some commands.  For example, use "<literal>dpkg -L libglib2.0-0:amd64</literal>" to list contents of the <literal>libglib2.0-0</literal> package for the <literal>amd64</literal> architecture.</para> </note>
        <caution> <para>Lower level package tools such as "<literal>dpkg -i …</literal>" and "<literal>debi …</literal>" should be carefully used by the system administrator.  It does not automatically take care required package dependencies. Dpkg's commandline options "<literal>--force-all</literal>" and similar (see <literal>dpkg</literal>(1)) are intended to be used by experts only.  Using them without fully understanding their effects may break your whole system.</para> </caution>
        <para>Please note the following.</para>
        <itemizedlist>
          <listitem> <para> All system configuration and installation commands require to be run from root.  </para> </listitem>
          <listitem> <para> Unlike <literal>aptitude</literal> which uses regex (see <xref linkend="_regular_expressions"/>), other package management commands use pattern like shell glob (see <xref linkend="_shell_glob"/>).  </para> </listitem>
          <listitem> <para><literal>apt-file</literal>(1) provided by the <literal>apt-file</literal> package must run "<literal>apt-file update</literal>" in advance.  </para> </listitem>
          <listitem> <para><literal>configure-debian</literal>(8) provided by the <literal>configure-debian</literal> package runs <literal>dpkg-reconfigure</literal>(8) as its backend.  </para> </listitem>
          <listitem> <para><literal>dpkg-reconfigure</literal>(8) runs package scripts using <literal>debconf</literal>(1) as its backend.  </para> </listitem>
          <listitem> <para> "<literal>apt-get build-dep</literal>", "<literal>apt-get source</literal>" and "<literal>apt-cache showsrc</literal>" commands require "<literal>deb-src</literal>" entry in <emphasis role="strong">the source list</emphasis>.  </para> </listitem>
          <listitem> <para><literal>dget</literal>(1), <literal>debuild</literal>(1), and <literal>debi</literal>(1) require <literal>devscripts</literal> package.  </para> </listitem>
          <listitem> <para> See (re)packaging procedure using "<literal>apt-get source</literal>" in <xref linkend="_porting_a_package_to_the_stable_system"/>.  </para> </listitem>
          <listitem> <para><literal>make-kpkg</literal> command requires the <literal>kernel-package</literal> package (see <xref linkend="_the_kernel"/>).  </para> </listitem>
          <listitem> <para> See <xref linkend="_making_debian_package"/> for general packaging.  </para> </listitem>
        </itemizedlist>
      </section>
      <section id="_verification_of_installed_package_files">
        <title>Verification of installed package files</title>
        <para>The installation of <literal>debsums</literal> enables verification of installed package files against MD5sum values in the "<literal>/var/lib/dpkg/info/*.md5sums</literal>" file with <literal>debsums</literal>(1).  See <xref linkend="_the_md5_sum"/> for how MD5sum works.</para>
        <note> <para>Because MD5sum database may be tampered by the intruder, <literal>debsums</literal>(1) is of limited use as a security tool. It is only good for checking local modifications by the administrator or damage due to media errors.</para> </note>
      </section>
      <section id="_safeguarding_for_package_problems">
        <title>Safeguarding for package problems</title>
        <para>Many users prefer to follow the <emphasis role="strong">testing</emphasis> (or <emphasis role="strong">unstable</emphasis>) releases of the Debian system for its new features and packages.  This makes the system more prone to be hit by the critical package bugs.</para>
        <para>The installation of the <literal>apt-listbugs</literal> package safeguards your system against critical bugs by checking Debian BTS automatically for critical bugs when upgrading with APT system.</para>
        <para>The installation of the <literal>apt-listchanges</literal> package provides important news in "<literal>NEWS.Debian</literal>" when upgrading with APT system.</para>
      </section>
      <section id="_searching_on_the_package_meta_data">
        <title>Searching on the package meta data</title>
        <para>Although visiting Debian site <ulink url="https://packages.debian.org/">https://packages.debian.org/</ulink> facilitates easy ways to search on the package meta data these days, let's look into more traditional ways.</para>
        <para>The <literal>grep-dctrl</literal>(1), <literal>grep-status</literal>(1), and <literal>grep-available</literal>(1) commands can be used to search any file which has the general format of a Debian package control file.</para>
        <para>The "<literal>dpkg -S <emphasis>file_name_pattern</emphasis></literal>" can be used to search package names which contain files with the matching name installed by <literal>dpkg</literal>.  But this overlooks files created by the maintainer scripts.</para>
        <para>If you need to make more elaborate search on the dpkg meta data, you need to run "<literal>grep -e regex_pattern *</literal>" command in the "<literal>/var/lib/dpkg/info/</literal>" directory.  This makes you search words mentioned in package scripts and installation query texts.</para>
        <para>If you wish to look up package dependency recursively, you should use <literal>apt-rdepends</literal>(8).</para>
      </section>
    </section>
    <section id="_debian_package_management_internals">
      <title>Debian package management internals</title>
      <para>Let's learn how the Debian package management system works internally.  This should help you to create your own solution to some package problems.</para>
      <section id="_archive_meta_data">
        <title>Archive meta data</title>
        <para>Meta data files for each distribution are stored under "<literal>dist/<emphasis>codename</emphasis></literal>" on each Debian mirror sites, e.g., "<literal>http://deb.debian.org/debian/</literal>".  Its archive structure can be browsed by the web browser. There are 6 types of key meta data.</para>
        <table pgwide="0" frame="topbot" rowsep="1" colsep="1">
          <title>The content of the Debian archive meta data</title>
          <tgroup cols="3">
            <colspec colwidth="141pt" align="left"/>
            <colspec colwidth="336pt" align="left"/>
            <colspec colwidth="244pt" align="left"/>
            <thead>
              <row>
                <entry> file </entry>
                <entry> location </entry>
                <entry> content </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry> <literal>Release</literal> </entry>
                <entry> top of distribution </entry>
                <entry> archive description and integrity information </entry>
              </row>
              <row>
                <entry> <literal>Release.gpg</literal> </entry>
                <entry> top of distribution </entry>
                <entry> signature file for the "<literal>Release</literal>" file signed with the archive key </entry>
              </row>
              <row>
                <entry> <literal>Contents-<emphasis>architecture</emphasis></literal> </entry>
                <entry> top of distribution </entry>
                <entry> list of all files for all the packages in the pertinent archive </entry>
              </row>
              <row>
                <entry> <literal>Release</literal> </entry>
                <entry> top of each distribution/area/architecture combination </entry>
                <entry> archive description used for the rule of <literal>apt_preferences</literal>(5) </entry>
              </row>
              <row>
                <entry> <literal>Packages</literal> </entry>
                <entry> top of each distribution/area/binary-architecture combination </entry>
                <entry> concatenated <literal>debian/control</literal> for binary packages </entry>
              </row>
              <row>
                <entry> <literal>Sources</literal> </entry>
                <entry> top of each distribution/area/source combination </entry>
                <entry> concatenated <literal>debian/control</literal> for source packages </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <para>In the recent archive, these meta data are stored as the compressed and differential files to reduce network traffic.</para>
      </section>
      <section id="_top_level_release_file_and_authenticity">
        <title>Top level "Release" file and authenticity</title>
        <tip> <para>The top level "<literal>Release</literal>" file is used for signing the archive under the <emphasis role="strong">secure APT</emphasis> system.</para> </tip>
        <para>Each suite of the Debian archive has a top level "<literal>Release</literal>" file, e.g., "<literal>http://deb.debian.org/debian/dists/unstable/Release</literal>", as follows.</para>
        <screen>Origin: Debian
Label: Debian
Suite: unstable
Codename: sid
Date: Sat, 14 May 2011 08:20:50 UTC
Valid-Until: Sat, 21 May 2011 08:20:50 UTC
Architectures: alpha amd64 armel hppa hurd-i386 i386 ia64 kfreebsd-amd64 kfreebsd-i386 mips mipsel powerpc s390 sparc
Components: main contrib non-free
Description: Debian x.y Unstable - Not Released
MD5Sum:
 bdc8fa4b3f5e4a715dd0d56d176fc789 18876880 Contents-alpha.gz
 9469a03c94b85e010d116aeeab9614c0 19441880 Contents-amd64.gz
 3d68e206d7faa3aded660dc0996054fe 19203165 Contents-armel.gz
...</screen>
        <note> <para>Here, you can find my rationale to use the "suite", and "codename" in <xref linkend="_debian_archive_basics"/>.  The "distribution" is used when referring to both "suite" and "codename".  All archive "area" names offered by the archive are listed under "Components".</para> </note>
        <para>The integrity of the top level "<literal>Release</literal>" file is verified by cryptographic infrastructure called the <ulink url="https://wiki.debian.org/SecureApt">secure apt</ulink> as described in <literal>apt-secure</literal>(8).</para>
        <itemizedlist>
          <listitem> <para> The cryptographic signature file "<literal>Release.gpg</literal>" is created from the authentic top level "<literal>Release</literal>" file and the secret Debian archive key.  </para> </listitem>
          <listitem> <para> The public Debian archive keys are locally installed by the latest <literal>debian-archive-keyring</literal> package. </para> </listitem>
          <listitem> <para> The <emphasis role="strong">secure APT</emphasis> system automatically verifies the integrity of the downloaded top level "<literal>Release</literal>" file cryptographically by this "<literal>Release.gpg</literal>" file and the locally installed public Debian archive keys.</para> </listitem>
          <listitem> <para> The integrity of all the "<literal>Packages</literal>" and "<literal>Sources</literal>" files are verified by using MD5sum values in its top level "<literal>Release</literal>" file.  The integrity of all package files are verified by using MD5sum values in the "<literal>Packages</literal>" and "<literal>Sources</literal>" files.  See <literal>debsums</literal>(1) and <xref linkend="_verification_of_installed_package_files"/>.</para>  </listitem>
          <listitem> <para> Since the cryptographic signature verification is a much more CPU intensive process than the MD5sum value calculation, use of MD5sum value for each package while using cryptographic signature for the top level "<literal>Release</literal>" file provides <ulink url="https://www.infodrom.org/~joey/Writing/Linux-Journal/secure-apt/">the good security with the performance</ulink> (see <xref linkend="_data_security_infrastructure"/>).</para> </listitem>
        </itemizedlist>
        <para> If <emphasis role="strong">the source list</emphasis> entry specifies the "<literal>signed-by</literal>" option, the integrity of its downloaded top level "<literal>Release</literal>" file is verified using specified public key. This is useful when <emphasis role="strong">the source list</emphasis> contains non-Debian archives.</para>
        <tip> <para>The use of <literal>apt-key</literal>(8) command for APT key management is deprecated.</para> </tip>
        <para> Also, you can manually verify the integrity of the "<literal>Release</literal>" file with the "<literal>Release.gpg</literal>" file and the public Debian archive key posted on <ulink url="https://ftp-master.debian.org">ftp-master.debian.org</ulink> using <literal>gpg</literal>. </para>
      </section>
      <section id="_archive_level_release_files">
        <title>Archive level "Release" files</title>
        <tip> <para>The archive level "<literal>Release</literal>" files are used for the rule of <literal>apt_preferences</literal>(5).</para> </tip>
        <para>There are archive level "<literal>Release</literal>" files for all archive locations specified by <emphasis role="strong">the source list</emphasis>, such as "<literal>http://deb.debian.org/debian/dists/unstable/main/binary-amd64/Release</literal>" or "<literal>http://deb.debian.org/debian/dists/sid/main/binary-amd64/Release</literal>" as follows.</para>
        <screen>Archive: unstable
Origin: Debian
Label: Debian
Component: main
Architecture: amd64</screen>
        <caution>
          <para>For "<literal>Archive:</literal>" stanza, suite names ("<literal>stable</literal>", "<literal>testing</literal>", "<literal>unstable</literal>", …) are used in <ulink url="http://deb.debian.org/debian/">the Debian archive</ulink> while codenames ("<literal>trusty</literal>", "<literal>xenial</literal>", "<literal>artful</literal>", …) are used in <ulink url="http://archive.ubuntu.com/ubuntu/">the Ubuntu archive</ulink>.</para>
        </caution>
        <para>For some archives, such as <literal>experimental</literal>, and <literal>@-@codename-stable@-@-backports</literal>, which contain packages which should not be installed automatically, there is an extra line, e.g., "<literal>http://deb.debian.org/debian/dists/experimental/main/binary-amd64/Release</literal>" as follows.</para>
        <screen>Archive: experimental
Origin: Debian
Label: Debian
NotAutomatic: yes
Component: main
Architecture: amd64</screen>
        <para>Please note that for normal archives without "<literal>NotAutomatic: yes</literal>", the default Pin-Priority value is 500, while for special archives with "<literal>NotAutomatic: yes</literal>", the default Pin-Priority value is 1 (see <literal>apt_preferences</literal>(5) and <xref linkend="_tweaking_candidate_version"/>).</para>
      </section>
      <section id="_fetching_of_the_meta_data_for_the_package">
        <title>Fetching of the meta data for the package</title>
        <para>When APT tools, such as <literal>aptitude</literal>, <literal>apt-get</literal>, <literal>synaptic</literal>, <literal>apt-file</literal>, <literal>auto-apt</literal>, … are used, we need to update the local copies of the meta data containing the Debian archive information. These local copies have following file names corresponding to the specified <literal>distribution</literal>, <literal>area</literal>, and <literal>architecture</literal> names in <emphasis role="strong">the source list</emphasis> (see <xref linkend="_debian_archive_basics"/>).</para>
        <itemizedlist>
          <listitem> <para> "<literal>/var/lib/apt/lists/deb.debian.org_debian_dists_<emphasis>distribution</emphasis>_Release</literal>" </para> </listitem>
          <listitem> <para> "<literal>/var/lib/apt/lists/deb.debian.org_debian_dists_<emphasis>distribution</emphasis>_Release.gpg</literal>" </para> </listitem>
          <listitem> <para> "<literal>/var/lib/apt/lists/deb.debian.org_debian_dists_<emphasis>distribution</emphasis>_<emphasis>area</emphasis>_binary-<emphasis>architecture</emphasis>_Packages</literal>" </para> </listitem>
          <listitem> <para> "<literal>/var/lib/apt/lists/deb.debian.org_debian_dists_<emphasis>distribution</emphasis>_<emphasis>area</emphasis>_source_Sources</literal>" </para> </listitem>
          <listitem> <para> "<literal>/var/cache/apt/apt-file/deb.debian.org_debian_dists_<emphasis>distribution</emphasis>_Contents-<emphasis>architecture</emphasis>.gz</literal>" (for <literal>apt-file</literal>) </para> </listitem>
        </itemizedlist>
        <para>First 4 types of files are shared by all the pertinent APT commands and updated from command line by "<literal>apt-get update</literal>" or "<literal>aptitude update</literal>".  The "<literal>Packages</literal>" meta data are updated if the "<literal>deb</literal>" is specified in <emphasis role="strong">the source list</emphasis>. The "<literal>Sources</literal>" meta data are updated if the "<literal>deb-src</literal>" is specified in <emphasis role="strong">the source list</emphasis>.</para>
        <para>The "<literal>Packages</literal>" and "<literal>Sources</literal>" meta data contain "<literal>Filename:</literal>" stanza pointing to the file location of the binary and source packages.  Currently, these packages are located under the "<literal>pool/</literal>" directory tree for the improved transition over the releases.</para>
        <para>Local copies of "<literal>Packages</literal>" meta data can be interactively searched with the help of <literal>aptitude</literal>.  The specialized search command <literal>grep-dctrl</literal>(1) can search local copies of "<literal>Packages</literal>" and "<literal>Sources</literal>" meta data.</para>
        <para>Local copy of "<literal>Contents-<emphasis>architecture</emphasis></literal>" meta data can be updated by "<literal>apt-file update</literal>" and its location is different from other 4 ones. See <literal>apt-file</literal>(1). (The <literal>auto-apt</literal> uses different location for local copy of "<literal>Contents-<emphasis>architecture</emphasis>.gz</literal>" as default.)</para>
      </section>
      <section id="_the_package_state_for_apt">
        <title>The package state for APT</title>
        <para>In addition to the remotely fetched meta data, the APT tool after <literal>lenny</literal> stores its locally generated installation state information in the "<literal>/var/lib/apt/extended_states</literal>" which is used by all APT tools to track all auto installed packages.</para>
      </section>
      <section id="_the_package_state_for_aptitude">
        <title>The package state for aptitude</title>
        <para>In addition to the remotely fetched meta data, the <literal>aptitude</literal> command stores its locally generated installation state information in the "<literal>/var/lib/aptitude/pkgstates</literal>" which is used only by it.</para>
      </section>
      <section id="_local_copies_of_the_fetched_packages">
        <title>Local copies of the fetched packages</title>
        <para>All the remotely fetched packages via APT mechanism are stored in the "<literal>/var/cache/apt/archives</literal>" until they are cleaned.</para>
        <para>This cache file cleaning policy for <literal>aptitude</literal> can be set under "<literal>Options</literal>" → "<literal>Preferences</literal>" and it may be forced by its menu "<literal>Clean package cache</literal>" or "<literal>Clean obsolete files</literal>" under "<literal>Actions</literal>".</para>
      </section>
      <section id="_debian_package_file_names">
        <title>Debian package file names</title>
        <para>Debian package files have particular name structures.</para>
        <table pgwide="0" frame="topbot" rowsep="1" colsep="1">
          <title>The name structure of Debian packages</title>
          <tgroup cols="2">
            <colspec colwidth="304pt" align="left"/>
            <colspec colwidth="401pt" align="left"/>
            <thead>
              <row>
                <entry> package type </entry>
                <entry> name structure </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry> The binary package (a.k.a <literal>deb</literal>) </entry>
                <entry> <literal><emphasis>package-name</emphasis>_<emphasis>upstream-version</emphasis>-<emphasis>debian.revision</emphasis>_<emphasis>architecture</emphasis>.deb</literal> </entry>
              </row>
              <row>
                <entry> The binary package for debian-installer (a.k.a <literal>udeb</literal>) </entry>
                <entry> <literal><emphasis>package-name</emphasis>_<emphasis>upstream-version</emphasis>-<emphasis>debian.revision</emphasis>_<emphasis>architecture</emphasis>.udeb</literal> </entry>
              </row>
              <row>
                <entry> The source package (upstream source) </entry>
                <entry> <literal><emphasis>package-name</emphasis>_<emphasis>upstream-version</emphasis>-<emphasis>debian.revision</emphasis>.orig.tar.gz</literal> </entry>
              </row>
              <row>
                <entry> The <literal>1.0</literal> source package (Debian changes) </entry>
                <entry> <literal><emphasis>package-name</emphasis>_<emphasis>upstream-version</emphasis>-<emphasis>debian.revision</emphasis>.diff.gz</literal> </entry>
              </row>
              <row>
                <entry> The <literal>3.0 (quilt)</literal> source package (Debian changes) </entry>
                <entry> <literal><emphasis>package-name</emphasis>_<emphasis>upstream-version</emphasis>-<emphasis>debian.revision</emphasis>.debian.tar.gz</literal> </entry>
              </row>
              <row>
                <entry> The source package (description) </entry>
                <entry> <literal><emphasis>package-name</emphasis>_<emphasis>upstream-version</emphasis>-<emphasis>debian.revision</emphasis>.dsc</literal> </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <tip> <para>Here only the basic source package formats are described.  See more on <literal>dpkg-source</literal>(1).</para> </tip>
        <table pgwide="0" frame="topbot" rowsep="1" colsep="1">
          <title>The usable characters for each component in the Debian package names</title>
          <tgroup cols="3">
            <colspec colwidth="114pt" align="left"/>
            <colspec colwidth="141pt" align="left"/>
            <colspec colwidth="54pt" align="left"/>
            <thead>
              <row>
                <entry> name component </entry>
                <entry> usable characters (ERE regex) </entry>
                <entry> existence </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry> <literal><emphasis>package-name</emphasis></literal> </entry>
                <entry> <literal>[a-z0-9][-a-z0-9.+]+</literal> </entry>
                <entry> required </entry>
              </row>
              <row>
                <entry> <literal><emphasis>epoch</emphasis>:</literal> </entry>
                <entry> <literal>[0-9]+:</literal> </entry>
                <entry> optional </entry>
              </row>
              <row>
                <entry> <literal><emphasis>upstream-version</emphasis></literal> </entry>
                <entry> <literal>[-a-zA-Z0-9.+:]+</literal> </entry>
                <entry> required </entry>
              </row>
              <row>
                <entry> <literal><emphasis>debian.revision</emphasis></literal> </entry>
                <entry> <literal>[a-zA-Z0-9.+~]+</literal> </entry>
                <entry> optional </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <note> <para>You can check package version order by <literal>dpkg</literal>(1), e.g., "<literal>dpkg --compare-versions 7.0 gt 7.~pre1 ; echo $?</literal>" .</para> </note>
        <note> <para><ulink url="https://www.debian.org/devel/debian-installer/">The debian-installer (d-i)</ulink> uses <literal>udeb</literal> as the file extension for its binary package instead of normal <literal>deb</literal>.  An <literal>udeb</literal> package is a stripped down <literal>deb</literal> package which removes few non-essential contents such as documentation to save space while relaxing the package policy requirements.  Both <literal>deb</literal> and <literal>udeb</literal> packages share the same package structure.  The "<literal>u</literal>" stands for micro.</para> </note>
      </section>
      <section id="_the_dpkg_command">
        <title>The dpkg command</title>
        <para><literal>dpkg</literal>(1) is the lowest level tool for the Debian package management.  This is very powerful and needs to be used with care.</para>
        <para>While installing package called "<literal><emphasis>package_name</emphasis></literal>", <literal>dpkg</literal> process it in the following order.</para>
        <orderedlist>
          <listitem> <para> Unpack the deb file ("<literal>ar -x</literal>" equivalent) </para> </listitem>
          <listitem> <para> Execute "<literal><emphasis>package_name</emphasis>.preinst</literal>" using <literal>debconf</literal>(1) </para> </listitem>
          <listitem> <para> Install the package content to the system ("<literal>tar -x</literal>" equivalent) </para> </listitem>
          <listitem> <para> Execute "<literal><emphasis>package_name</emphasis>.postinst</literal>" using <literal>debconf</literal>(1) </para> </listitem>
        </orderedlist>
        <para>The <literal>debconf</literal> system provides standardized user interaction with I18N and L10N (<xref linkend="_i18n_and_l10n"/>) supports.</para>
        <table pgwide="0" frame="topbot" rowsep="1" colsep="1">
          <title>The notable files created by <literal>dpkg</literal></title>
          <tgroup cols="2">
            <colspec colwidth="249pt" align="left"/>
            <colspec colwidth="439pt" align="left"/>
            <thead>
              <row>
                <entry> file </entry>
                <entry> description of contents </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry> <literal>/var/lib/dpkg/info/<emphasis>package_name</emphasis>.conffiles</literal> </entry>
                <entry> list of configuration files. (user modifiable) </entry>
              </row>
              <row>
                <entry> <literal>/var/lib/dpkg/info/<emphasis>package_name</emphasis>.list</literal> </entry>
                <entry> list of files and directories installed by the package </entry>
              </row>
              <row>
                <entry> <literal>/var/lib/dpkg/info/<emphasis>package_name</emphasis>.md5sums</literal> </entry>
                <entry> list of MD5 hash values for files installed by the package </entry>
              </row>
              <row>
                <entry> <literal>/var/lib/dpkg/info/<emphasis>package_name</emphasis>.preinst</literal> </entry>
                <entry> package script to be run before the package installation </entry>
              </row>
              <row>
                <entry> <literal>/var/lib/dpkg/info/<emphasis>package_name</emphasis>.postinst</literal> </entry>
                <entry> package script to be run after the package installation </entry>
              </row>
              <row>
                <entry> <literal>/var/lib/dpkg/info/<emphasis>package_name</emphasis>.prerm</literal> </entry>
                <entry> package script to be run before the package removal </entry>
              </row>
              <row>
                <entry> <literal>/var/lib/dpkg/info/<emphasis>package_name</emphasis>.postrm</literal> </entry>
                <entry> package script to be run after the package removal </entry>
              </row>
              <row>
                <entry> <literal>/var/lib/dpkg/info/<emphasis>package_name</emphasis>.config</literal> </entry>
                <entry> package script for <literal>debconf</literal> system </entry>
              </row>
              <row>
                <entry> <literal>/var/lib/dpkg/alternatives/<emphasis>package_name</emphasis></literal> </entry>
                <entry> the alternative information used by the <literal>update-alternatives</literal> command </entry>
              </row>
              <row>
                <entry> <literal>/var/lib/dpkg/available</literal> </entry>
                <entry> the availability information for all the package </entry>
              </row>
              <row>
                <entry> <literal>/var/lib/dpkg/diversions</literal> </entry>
                <entry> the diversions information used by <literal>dpkg</literal>(1) and set by <literal>dpkg-divert</literal>(8) </entry>
              </row>
              <row>
                <entry> <literal>/var/lib/dpkg/statoverride</literal> </entry>
                <entry> the stat override information used by <literal>dpkg</literal>(1) and set by <literal>dpkg-statoverride</literal>(8) </entry>
              </row>
              <row>
                <entry> <literal>/var/lib/dpkg/status</literal> </entry>
                <entry> the status information for all the packages </entry>
              </row>
              <row>
                <entry> <literal>/var/lib/dpkg/status-old</literal> </entry>
                <entry> the first-generation backup of the "<literal>var/lib/dpkg/status</literal>" file </entry>
              </row>
              <row>
                <entry> <literal>/var/backups/dpkg.status*</literal> </entry>
                <entry> the second-generation backup and older ones of the "<literal>var/lib/dpkg/status</literal>" file </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <para>The "<literal>status</literal>" file is also used by the tools such as <literal>dpkg</literal>(1), "<literal>dselect update</literal>" and "<literal>apt-get -u dselect-upgrade</literal>".</para>
        <para>The specialized search command <literal>grep-dctrl</literal>(1) can search the local copies of "<literal>status</literal>" and "<literal>available</literal>" meta data.</para>
        <tip> <para>In <ulink url="https://www.debian.org/devel/debian-installer/">the debian-installer</ulink> environment, the <literal>udpkg</literal> command is used to open <literal>udeb</literal> packages.  The <literal>udpkg</literal> command is a stripped down version of the <literal>dpkg</literal> command.</para> </tip>
      </section>
      <section id="_the_update_alternatives_command">
        <title>The update-alternatives command</title>
        <para>The Debian system has mechanism to install somewhat overlapping programs peacefully using <literal>update-alternatives</literal>(1).  For example, you can make the <literal>vi</literal> command select to run <literal>vim</literal> while installing both <literal>vim</literal> and <literal>nvi</literal> packages.</para>
        <screen>$ ls -l $(type -p vi)
lrwxrwxrwx 1 root root 20 2007-03-24 19:05 /usr/bin/vi -&gt; /etc/alternatives/vi
$ sudo update-alternatives --display vi
...
$ sudo update-alternatives --config vi
  Selection    Command
 ----------------------------------------------
      1        /usr/bin/vim
*+    2        /usr/bin/nvi

Enter to keep the default[*], or type selection number: 1</screen>
        <para>The Debian alternatives system keeps its selection as symlinks in "<literal>/etc/alternatives/</literal>".  The selection process uses corresponding file in "<literal>/var/lib/dpkg/alternatives/</literal>".</para>
      </section>
      <section id="_the_dpkg_statoverride_command">
        <title>The dpkg-statoverride command</title>
        <para><emphasis role="strong">Stat overrides</emphasis> provided by the <literal>dpkg-statoverride</literal>(8) command are a way to tell <literal>dpkg</literal>(1) to use a different owner or mode for a <emphasis role="strong">file</emphasis> when a package is installed. If "<literal>--update</literal>" is specified and file exists, it is immediately set to the new owner and mode.</para>
        <caution> <para>The direct alteration of owner or mode for a <emphasis role="strong">file</emphasis> owned by the package using <literal>chmod</literal> or <literal>chown</literal> commands by the system administrator is reset by the next upgrade of the package.</para> </caution>
        <note> <para>I use the word <emphasis role="strong">file</emphasis> here, but in reality this can be any filesystem object that <literal>dpkg</literal> handles, including directories, devices, etc.</para> </note>
      </section>
      <section id="_the_dpkg_divert_command">
        <title>The dpkg-divert command</title>
        <para>File <emphasis role="strong">diversions</emphasis> provided by the <literal>dpkg-divert</literal>(8) command are a way of forcing <literal>dpkg</literal>(1) not to install a file into its default location, but to a <emphasis role="strong">diverted</emphasis> location.  The use of <literal>dpkg-divert</literal> is meant for the package maintenance scripts.  Its casual use by the system administrator is deprecated.</para>
      </section>
    </section>
    <section id="_recovery_from_a_broken_system">
      <title>Recovery from a broken system</title>
      <para>When running <literal>testing</literal> or <literal>unstable</literal> system, the administrator is expected to recover from broken package management situation.</para>
      <caution> <para>Some methods described here are high risk actions.  You have been warned!</para> </caution>
      <section id="_failed_installation_due_to_missing_dependencies">
        <title>Failed installation due to missing dependencies</title>
        <para>If you force to install a package by "<literal>sudo dpkg -i ...</literal>" to a system without all dependency packages installed, the package installation will fail as partially installed.</para>
        <para>You should install all dependency packages using APT-system or "<literal>sudo dpkg -i ...</literal>".</para>
        <para>Then, configure all partially installed packages with the following command.</para>
        <screen># dpkg --configure -a</screen>
      </section>
      <section id="_caching_errors_of_the_package_data">
        <title>Caching errors of the package data</title>
        <para>Caching errors of the package data cause intriguing errors, such as <ulink url="https://bugs.debian.org/1003865">"GPG error: ... invalid: BADSIG ..."</ulink> with APT.</para>
        <para>You should remove all cached data by "<literal>sudo rm -rf /var/lib/apt/* </literal>" and try again. (If <literal>apt-cacher-ng</literal> is used, you should also run "<literal>sudo rm -rf /var/cache/apt-cacher-ng/* </literal>".)</para>
      </section>
      <section id="_incompatibility_with_old_user_configuration">
        <title>Incompatibility with old user configuration</title>
        <para>If a desktop GUI program experienced instability after significant upstream version upgrade, you should suspect interference with old local configuration files created by it. If it is stable under a newly created user account, this hypothesis is confirmed.  (This is a bug of packaging and usually avoided by the packager.)</para>
        <para>To recover stability, you should move corresponding local configuration files and restart the GUI program.  You may need to read old configuration file contents to recover configuration information later.  (Do not erase them too quickly.)</para>
      </section>
      <section id="_different_packages_with_overlapped_files">
        <title>Different packages with overlapped files</title>
        <para>Archive level package management systems, such as <literal>aptitude</literal>(8) or <literal>apt-get</literal>(1), do not even try to install packages with overlapped files using package dependencies (see <xref linkend="_package_dependencies"/>).</para>
        <para>Errors by the package maintainer or deployment of inconsistently mixed source of archives (see <xref linkend="_packages_from_mixed_source_of_archives"/>) by the system administrator may create a situation with incorrectly defined package dependencies. When you install a package with overlapped files using <literal>aptitude</literal>(8) or <literal>apt-get</literal>(1) under such a situation, <literal>dpkg</literal>(1) which unpacks package ensures to return error to the calling program without overwriting existing files.</para>
        <caution> <para>The use of third party packages introduces significant system risks via maintainer scripts which are run with root privilege and can do anything to your system.  The <literal>dpkg</literal>(1) command only protects against overwriting by the unpacking.</para> </caution>
        <para>You can work around such broken installation by removing the old offending package, <literal><emphasis>old-package</emphasis></literal>, first.</para>
        <screen>$ sudo dpkg -P <emphasis>old-package</emphasis></screen>
      </section>
      <section id="_fixing_broken_package_script">
        <title>Fixing broken package script</title>
        <para>When a command in the package script returns error for some reason and the script exits with error, the package management system aborts their action and ends up with partially installed packages.  When a package contains bugs in its removal scripts, the package may become impossible to remove and quite nasty.</para>
        <para>For the package script problem of "<literal><emphasis>package_name</emphasis></literal>", you should look into following package scripts.</para>
        <itemizedlist>
          <listitem> <para> "<literal>/var/lib/dpkg/info/<emphasis>package_name</emphasis>.preinst</literal>" </para> </listitem>
          <listitem> <para> "<literal>/var/lib/dpkg/info/<emphasis>package_name</emphasis>.postinst</literal>" </para> </listitem>
          <listitem> <para> "<literal>/var/lib/dpkg/info/<emphasis>package_name</emphasis>.prerm</literal>" </para> </listitem>
          <listitem> <para> "<literal>/var/lib/dpkg/info/<emphasis>package_name</emphasis>.postrm</literal>" </para> </listitem>
        </itemizedlist>
        <para>Edit the offending package script from the root using following techniques.</para>
        <itemizedlist>
          <listitem> <para> disable the offending line by preceding "<literal>#</literal>" </para> </listitem>
          <listitem> <para> force to return success by appending the offending line with "<literal>|| true</literal>" </para> </listitem>
        </itemizedlist>
        <para>Then, follow <xref linkend="_recovery_from_a_broken_system" />.</para>
      </section>
      <section id="_rescue_with_the_dpkg_command">
        <title>Rescue with the dpkg command</title>
        <para>Since <literal>dpkg</literal> is very low level package tool, it can function under the very bad situation such as unbootable system without network connection.  Let's assume <literal>foo</literal> package was broken and needs to be replaced.</para>
        <para>You may still find cached copies of older bug free version of <literal>foo</literal> package in the package cache directory: "<literal>/var/cache/apt/archives/</literal>".  (If not, you can download it from archive of <ulink url="https://snapshot.debian.org/">https://snapshot.debian.org/</ulink> or copy it from package cache of a functioning machine.)</para>
        <para>If you can boot the system, you may install it by the following command.</para>
        <screen># dpkg -i /path/to/foo_<emphasis>old_version</emphasis>_<emphasis>arch</emphasis>.deb</screen>
        <tip> <para>If system breakage is minor, you may alternatively downgrade the whole system as in <xref linkend="_emergency_downgrading"/> using the higher level APT system.</para> </tip>
        <para>If your system is unbootable from hard disk, you should seek other ways to boot it.</para>
        <orderedlist>
          <listitem> <para> Boot the system using the debian-installer CD in rescue mode.  </para> </listitem>
          <listitem> <para> Mount the unbootable system on the hard disk to "<literal>/target</literal>".  </para> </listitem>
          <listitem> <para> Install older version of <literal>foo</literal> package by the following.  </para> </listitem>
        </orderedlist>
        <screen># dpkg --root /target -i /path/to/foo_<emphasis>old_version</emphasis>_<emphasis>arch</emphasis>.deb</screen>
        <para>This example works even if the <literal>dpkg</literal> command on the hard disk is broken.</para>
        <tip> <para>Any GNU/Linux system started by another system on hard disk, live GNU/Linux CD, bootable USB-key drive, or netboot can be used similarly to rescue broken system.</para> </tip>
        <para>If attempting to install a package this way fails due to some dependency violations and you really need to do this as the last resort, you can override dependency using <literal>dpkg</literal>'s "<literal>--ignore-depends</literal>", "<literal>--force-depends</literal>" and other options.    If you do this, you need to make serious effort to restore proper dependency later. See <literal>dpkg</literal>(8) for details.</para>
        <note> <para>If your system is seriously broken, you should make a full backup of system to a safe place (see <xref linkend="_backup_and_recovery"/>) and should perform a clean installation.  This is less time consuming and produces better results in the end.</para> </note>
      </section>
      <section id="_recovering_package_selection_data">
        <title>Recovering package selection data</title>
        <para>If "<literal>/var/lib/dpkg/status</literal>" becomes corrupt for any reason, the Debian system loses package selection data and suffers severely.  Look for the old "<literal>/var/lib/dpkg/status</literal>" file at "<literal>/var/lib/dpkg/status-old</literal>" or "<literal>/var/backups/dpkg.status.*</literal>".</para>
        <para>Keeping "<literal>/var/backups/</literal>" in a separate partition may be a good idea since this directory contains lots of important system data.</para>
        <para>For serious breakage, I recommend to make fresh re-install after making backup of the system. Even if everything in "<literal>/var/</literal>" is gone, you can still recover some information from directories in "<literal>/usr/share/doc/</literal>" to guide your new installation.</para>
        <para>Reinstall minimal (desktop) system.</para>
        <screen># mkdir -p /path/to/old/system</screen>
        <para>Mount old system at "<literal>/path/to/old/system/</literal>".</para>
        <screen># cd /path/to/old/system/usr/share/doc
# ls -1 &gt;~/ls1.txt
# cd /usr/share/doc
# ls -1 &gt;&gt;~/ls1.txt
# cd
# sort ls1.txt | uniq | less</screen>
        <para>Then you are presented with package names to install.  (There may be some non-package names such as "<literal>texmf</literal>".)</para>
      </section>
    </section>
    <section id="_tips_for_the_package_management">
      <title>Tips for the package management</title>
      <para>For simplicity, <emphasis role="strong">the source list</emphasis> examples in this section are presented as "<literal>/etc/apt/sources.list</literal>" in one-line-style after the <literal>@-@codename-stable@-@</literal> release.</para>
      <section id="_who_uploaded_the_package">
        <title>Who uploaded the package?</title>
        <para>Although the maintainer name listed in "<literal>/var/lib/dpkg/available</literal>" and "<literal>/usr/share/doc/package_name/changelog</literal>" provide some information on "who is behind the packaging activity", the actual uploader of the package is somewhat obscure.  <literal>who-uploads</literal>(1) in the <literal>devscripts</literal> package identifies the actual uploader of Debian source packages.</para>
      </section>
      <section id="_limiting_download_bandwidth_for_apt">
        <title>Limiting download bandwidth for APT</title>
        <para>If you want to limit the download bandwidth for APT to e.g. 800Kib/sec (=100kiB/sec), you should configure APT with its configuration parameter as the following.</para>
        <screen>APT::Acquire::http::Dl-Limit "800";</screen>
      </section>
      <section id="_automatic_download_and_upgrade_of_packages">
        <title>Automatic download and upgrade of packages</title>
        <para>The <literal>apt</literal> package comes with its own cron script "<literal>/etc/cron.daily/apt</literal>" to support the automatic download of packages.  This script can be enhanced to perform the automatic upgrade of packages by installing the <literal>unattended-upgrades</literal> package. These can be customized by parameters in "<literal>/etc/apt/apt.conf.d/02backup</literal>" and "<literal>/etc/apt/apt.conf.d/50unattended-upgrades</literal>" as described in "<literal>/usr/share/doc/unattended-upgrades/README</literal>".</para>
        <para>The <literal>unattended-upgrades</literal> package is mainly intended for the security upgrade for the <literal>stable</literal> system.  If the risk of breaking an existing <literal>stable</literal> system by the automatic upgrade is smaller than that of the system broken by the intruder using its security hole which has been closed by the security update, you should consider using this automatic upgrade with configuration parameters as the following.</para>
        <screen>APT::Periodic::Update-Package-Lists "1";
APT::Periodic::Download-Upgradeable-Packages "1";
APT::Periodic::Unattended-Upgrade "1";</screen>
        <para>If you are running an <literal>testing</literal> or <literal>unstable</literal> system, you do not want to use the automatic upgrade since it certainly breaks system some day.  Even for such <literal>testing</literal> or <literal>unstable</literal> case, you may still want to download packages in advance to save time for the interactive upgrade with configuration parameters as the following.</para>
        <screen>APT::Periodic::Update-Package-Lists "1";
APT::Periodic::Download-Upgradeable-Packages "1";
APT::Periodic::Unattended-Upgrade "0";</screen>
      </section>
      <section id="_updates_and_backports">
        <title>Updates and Backports</title>
        <para>There are <ulink url="https://wiki.debian.org/StableUpdates">stable-updates</ulink> ("<literal>@-@codename-stable@-@</literal>-updates" during the <literal>@-@codename-stable@-@</literal>-as-<literal>stable</literal> release cycle) and <ulink url="https://backports.debian.org">backports.debian.org</ulink> archives which provide upgrade packages for <literal>stable</literal>.</para>
        <para>In order to use these archives, you list all required archives in the "<literal>/etc/apt/sources.list</literal>" file as the following.</para>
        <screen>deb http://deb.debian.org/debian/ @-@codename-stable@-@ main non-free-firmware contrib non-free
deb http://security.debian.org/debian-security @-@codename-stable@-@-security main non-free-firmware contrib non-free
deb http://deb.debian.org/debian/ @-@codename-stable@-@-updates main non-free-firmware contrib non-free
deb http://deb.debian.org/debian/ @-@codename-stable@-@-backports main non-free-firmware contrib non-free</screen>
        <para>There is no need to set Pin-Priority value explicitly in the "<literal>/etc/apt/preferences</literal>" file.  When newer packages become available, the default configuration provides most reasonable upgrades (see <xref linkend="_archive_level_release_files"/>).</para>
        <itemizedlist>
          <listitem> <para> All installed older packages are upgraded to newer ones from <literal>@-@codename-stable@-@-updates</literal>.  </para> </listitem>
          <listitem> <para> Only manually installed older packages from <literal>@-@codename-stable@-@-backports</literal> are upgraded to newer ones from <literal>@-@codename-stable@-@-backports</literal>. </para> </listitem>
        </itemizedlist>
        <para>Whenever you wish to install a package named "<literal><emphasis>package-name</emphasis></literal>" with its dependency from <literal>@-@codename-stable@-@-backports</literal> archive manually, you use following command while switching target release with "<literal>-t</literal>" option.</para>
        <screen>$ sudo apt-get install -t @-@codename-stable@-@-backports <emphasis>package-name</emphasis></screen>
        <warning> <para>Do not install too many packages from <ulink url="https://backports.debian.org">backports.debian.org</ulink> archives.  It may cause package dependency complications. See <xref linkend="_how_to_cope_with_conflicting_requirements"/> for alternative solutions. </para> </warning>
      </section>
      <section id="_external_package_archives">
        <title>External package archives</title>
        <warning> <para>You should be aware that the external package gains the root priviledge to your system. You should only use the trusted external package archive. See <xref linkend="_how_to_cope_with_conflicting_requirements"/> for alternative solutions. </para> </warning>
        <para>You can use secure APT with Debian-compatible external package archive by adding it to <emphasis role="strong">the source list</emphasis> and its archive key file into the "<literal>/etc/apt/trusted.gpg.d/</literal>" directory.  See <literal>sources.list</literal>(5), <literal>apt-secure</literal>(8) and <literal>apt-key</literal>(8). </para>
      </section>
      <section id="_packages_from_mixed_source_of_archives">
        <title>Packages from mixed source of archives without <emphasis role="strong">apt-pinning</emphasis></title>
        <caution> <para>Installing packages from mixed source of archives is not supported by the official Debian distribution except for officially supported particular combinations of archives such as <literal>stable</literal> with <ulink url="https://www.debian.org/security/">security updates</ulink> and <ulink url="https://wiki.debian.org/StableUpdates">stable-updates</ulink>.</para> </caution>
        <para>Here is an example of operations to include specific newer upstream version packages found in <literal>unstable</literal> while tracking <literal>testing</literal> for single occasion.</para>
        <orderedlist>
          <listitem> <para> Change the "<literal>/etc/apt/sources.list</literal>" file temporarily to single "<literal>unstable</literal>" entry.  </para> </listitem>
          <listitem> <para> Run "<literal>aptitude update</literal>".  </para> </listitem>
          <listitem> <para> Run "<literal>aptitude install <emphasis>package-name</emphasis></literal>".  </para> </listitem>
          <listitem> <para> Recover the original "<literal>/etc/apt/sources.list</literal>" file for <literal>testing</literal>.  </para> </listitem>
          <listitem> <para> Run "<literal>aptitude update</literal>".  </para> </listitem>
        </orderedlist>
        <para>You do not create the "<literal>/etc/apt/preferences</literal>" file nor need to worry about <emphasis role="strong">apt-pinning</emphasis> with this manual approach.  But this is very cumbersome.</para>
        <caution> <para>When using mixed source of archives, you must ensure compatibility of packages by yourself since the Debian does not guarantee it. If package incompatibility exists, you may break system. You must be able to judge these technical requirements. The use of mixed source of random archives is completely optional operation and its use is not something I encourage you to use.</para> </caution>
        <para>General rules for installing packages from different archives are the following.</para>
        <itemizedlist>
          <listitem>
            <para> Non-binary packages ("<literal>Architecture: all</literal>") are <emphasis role="strong">safer</emphasis> to install.  </para>
            <itemizedlist>
              <listitem> <para> documentation packages: no special requirements </para> </listitem>
              <listitem> <para> interpreter program packages: compatible interpreter must be available </para> </listitem>
            </itemizedlist>
          </listitem>
          <listitem>
            <para> Binary packages (non "<literal>Architecture: all</literal>") usually face many road blocks and are <emphasis role="strong">unsafe</emphasis> to install.  </para>
            <itemizedlist>
              <listitem> <para> library version compatibility (including "<literal>libc</literal>") </para> </listitem>
              <listitem> <para> related utility program version compatibility </para> </listitem>
              <listitem> <para> Kernel <ulink url="https://en.wikipedia.org/wiki/Application_binary_interface">ABI</ulink> compatibility </para> </listitem>
              <listitem> <para> C++ <ulink url="https://en.wikipedia.org/wiki/Application_binary_interface">ABI</ulink> compatibility </para> </listitem>
              <listitem> <para> … </para> </listitem>
            </itemizedlist>
          </listitem>
        </itemizedlist>
        <note> <para>In order to make a package to be <emphasis role="strong">safer</emphasis> to install, some commercial non-free binary program packages may be provided with completely statically linked libraries.  You should still check <ulink url="https://en.wikipedia.org/wiki/Application_binary_interface">ABI</ulink> compatibility issues etc. for them.</para> </note>
        <note>
          <para>Except to avoid broken package for a short term, installing binary packages from non-Debian archives is generally bad idea.  You should seek all available alternative safer technical solutions which are compatible with your current Debian syetem (see <xref linkend="_how_to_cope_with_conflicting_requirements"/>).</para>
        </note>
      </section>
      <section id="_tweaking_candidate_version">
        <title>Tweaking candidate version with <emphasis role="strong">apt-pinning</emphasis></title>
        <warning> <para>Use of <emphasis role="strong">apt-pinning</emphasis> technique by a novice user is sure call for major troubles.  You must avoid using this technique except when you absolutely need it.</para> </warning>
        <para>Without the "<literal>/etc/apt/preferences</literal>" file, APT system choses the latest available version as the <emphasis role="strong">candidate version</emphasis> using the version string.  This is the normal state and most recommended usage of APT system.  All officially supported combinations of archives do not require the "<literal>/etc/apt/preferences</literal>" file since some archives which should not be used as the automatic source of upgrades are marked as <emphasis role="strong">NotAutomatic</emphasis> and dealt properly.</para>
        <tip> <para>The version string comparison rule can be verified with, e.g., "<literal>dpkg  --compare-versions ver1.1 gt ver1.1~1; echo $?</literal>" (see <literal>dpkg</literal>(1)).</para> </tip>
        <para>When you install packages from mixed source of archives (see <xref linkend="_packages_from_mixed_source_of_archives"/>) regularly, you can automate these complicated operations by creating the "<literal>/etc/apt/preferences</literal>" file with proper entries and tweaking the package selection rule for <emphasis role="strong">candidate version</emphasis> as described in <literal>apt_preferences</literal>(5).  This is called <emphasis role="strong">apt-pinning</emphasis>.</para>
        <para>When using <emphasis role="strong">apt-pinning</emphasis>, you must ensure compatibility of packages by yourself since the Debian does not guarantee it.  The <emphasis role="strong">apt-pinning</emphasis> is completely optional operation and its use is not something I encourage you to use.</para>
        <para>Archive level Release files (see <xref linkend="_archive_level_release_files"/>) are used for the rule of <literal>apt_preferences</literal>(5).  Thus <emphasis role="strong">apt-pinning</emphasis> works only with "suite" name for <ulink url="http://deb.debian.org/debian/dists/">normal Debian archives</ulink> and <ulink url="http://security.debian.org/debian-security/dists/">security Debian archives</ulink>. (This is different from <ulink url="https://www.ubuntu.com/">Ubuntu</ulink> archives.)  For example, you can do "<literal>Pin: release a=unstable</literal>" but can not do "<literal>Pin: release a=sid</literal>" in the "<literal>/etc/apt/preferences</literal>" file.</para>
        <para>When you use non-Debian archive as a part of <emphasis role="strong">apt-pinning</emphasis>, you should check what they are intended for and also check their credibility.  For example, Ubuntu and Debian are not meant to be mixed.</para>
        <note> <para>Even if you do not create the "<literal>/etc/apt/preferences</literal>" file, you can do fairly complex system operations (see <xref linkend="_rescue_with_the_dpkg_command"/> and <xref linkend="_packages_from_mixed_source_of_archives"/>) without <emphasis role="strong">apt-pinning</emphasis>.</para> </note>
        <para>Here is a simplified explanation of <emphasis role="strong">apt-pinning</emphasis> technique.</para>
        <para>The APT system choses the highest Pin-Priority <emphasis role="strong">upgrading</emphasis> package from available package sources defined in the "<literal>/etc/apt/sources.list</literal>" file as the <emphasis role="strong">candidate version</emphasis> package.  If the Pin-Priority of the package is larger than 1000, this version restriction for <emphasis role="strong">upgrading</emphasis> is dropped to enable downgrading (see <xref linkend="_emergency_downgrading"/>).</para>
        <para>Pin-Priority value of each package is defined by "Pin-Priority" entries in the "<literal>/etc/apt/preferences</literal>" file or uses its default value.</para>
        <table pgwide="0" frame="topbot" rowsep="1" colsep="1">
          <title>List of notable Pin-Priority values for <emphasis role="strong">apt-pinning</emphasis> technique.</title>
          <tgroup cols="2">
            <colspec colwidth="76pt" align="left"/>
            <colspec colwidth="190pt" align="left"/>
            <thead>
              <row>
                <entry> Pin-Priority </entry>
                <entry> <emphasis role="strong">apt-pinning</emphasis> effects to the package </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry> 1001 </entry>
                <entry> install the package even if this constitutes a downgrade of the package </entry>
              </row>
              <row>
                <entry> 990 </entry>
                <entry> used as the default for the <emphasis role="strong">target release</emphasis> archive </entry>
              </row>
              <row>
                <entry> 500 </entry>
                <entry> used as the default for the <emphasis role="strong">normal</emphasis> archive </entry>
              </row>
              <row>
                <entry> 100 </entry>
                <entry> used as the default for the <emphasis role="strong">NotAutomatic</emphasis> and <emphasis role="strong">ButAutomaticUpgrades</emphasis> archive </entry>
              </row>
              <row>
                <entry> 100 </entry>
                <entry> used for the <emphasis role="strong">installed</emphasis> package </entry>
              </row>
              <row>
                <entry> 1 </entry>
                <entry> used as the default for the <emphasis role="strong">NotAutomatic</emphasis> archive </entry>
              </row>
              <row>
                <entry> -1 </entry>
                <entry><emphasis role="strong">never install</emphasis> the package even if recommended </entry> </row>
            </tbody>
          </tgroup>
        </table>
        <para>The <emphasis role="strong">target release</emphasis> archive can be set by the command line option, e.g., "<literal>apt-get install -t testing some-package</literal>" </para>
        <para>The  <emphasis role="strong">NotAutomatic</emphasis> and <emphasis role="strong">ButAutomaticUpgrades</emphasis> archive is set by archive server having its archive level Release file (see <xref linkend="_archive_level_release_files"/>) containing both "<literal>NotAutomatic: yes</literal>" and "<literal>ButAutomaticUpgrades: yes</literal>". The  <emphasis role="strong">NotAutomatic</emphasis> archive is set by archive server having its archive level Release file containing only "<literal>NotAutomatic: yes</literal>".</para>
        <para>The <emphasis role="strong">apt-pinning situation</emphasis> of <emphasis>package</emphasis> from multiple archive sources is displayed by "<literal>apt-cache policy <emphasis>package</emphasis></literal>".</para>
        <itemizedlist>
          <listitem> <para> A line started with "<literal>Package pin:</literal>" lists the package version of <emphasis role="strong">pin</emphasis> if association just with <emphasis>package</emphasis> is defined, e.g., "<literal>Package pin: 0.190</literal>".  </para> </listitem>
          <listitem> <para> No line with "<literal>Package pin:</literal>" exists if no association just with <emphasis>package</emphasis> is defined.  </para> </listitem>
          <listitem> <para> The Pin-Priority value associated just with <emphasis>package</emphasis> is listed right side of all version strings, e.g., "<literal>0.181 700</literal>".  </para> </listitem>
          <listitem> <para> "<literal>0</literal>" is listed right side of all version strings if no association just with <emphasis>package</emphasis> is defined, e.g., "<literal>0.181 0</literal>".  </para> </listitem>
          <listitem> <para> The Pin-Priority values of archives (defined as "<literal>Package: *</literal>" in the "<literal>/etc/apt/preferences</literal>" file) are listed left side of all archive paths, e.g., "<literal>100 http://deb.debian.org/debian/ @-@codename-stable@-@-backports/main Packages</literal>".  </para> </listitem>
        </itemizedlist>
      </section>
      <section id="_blocking_packages_installed_by_recommends">
        <title>Blocking packages installed by "Recommends"</title>
        <warning> <para>Use of <emphasis role="strong">apt-pinning</emphasis> technique by a novice user is sure call for major troubles.  You must avoid using this technique except when you absolutely need it.</para> </warning>
        <para>If you wish not to pull in particular packages automatically by "Recommends", you must create the "<literal>/etc/apt/preferences</literal>" file and explicitly list all those packages at the top of it as the following.</para>
        <screen>Package: <emphasis>package-1</emphasis>
Pin: version *
Pin-Priority: -1

Package: <emphasis>package-2</emphasis>
Pin: version *
Pin-Priority: -1</screen>
      </section>
      <section id="_tracking_literal_testing_literal_with_some_packages_from_literal_unstable_literal">
        <title>Tracking <literal>testing</literal> with some packages from <literal>unstable</literal></title>
        <warning> <para>Use of <emphasis role="strong">apt-pinning</emphasis> technique by a novice user is sure call for major troubles.  You must avoid using this technique except when you absolutely need it.</para> </warning>
        <para>Here is an example of <emphasis role="strong">apt-pinning</emphasis> technique to include specific newer upstream version packages found in <literal>unstable</literal> regularly upgraded while tracking <literal>testing</literal>.  You list all required archives in the "<literal>/etc/apt/sources.list</literal>" file as the following.</para>
        <screen>deb http://deb.debian.org/debian/ testing main contrib non-free
deb http://deb.debian.org/debian/ unstable main contrib non-free
deb http://security.debian.org/debian-security testing-security main contrib</screen>
        <para>Set the "<literal>/etc/apt/preferences</literal>" file as the following.</para>
        <screen>Package: *
Pin: release a=unstable
Pin-Priority: 100</screen>
        <para>When you wish to install a package named "<literal><emphasis>package-name</emphasis></literal>" with its dependencies from <literal>unstable</literal> archive under this configuration, you issue the following command which switches target release with "<literal>-t</literal>" option (Pin-Priority of <literal>unstable</literal> becomes 990).</para>
        <screen>$ sudo apt-get install -t unstable <emphasis>package-name</emphasis></screen>
        <para>With this configuration, usual execution of "<literal>apt-get upgrade</literal>" and "<literal>apt-get dist-upgrade</literal>" (or "<literal>aptitude safe-upgrade</literal>" and "<literal>aptitude full-upgrade</literal>") upgrades packages which were installed from <literal>testing</literal> archive using current <literal>testing</literal> archive and packages which were installed from <literal>unstable</literal> archive using current <literal>unstable</literal> archive.</para>
        <caution> <para>Be careful not to remove "<literal>testing</literal>" entry from the "<literal>/etc/apt/sources.list</literal>" file.  Without "<literal>testing</literal>" entry in it, APT system upgrades packages using newer <literal>unstable</literal> archive.</para> </caution>
        <tip> <para>I usually edit the "<literal>/etc/apt/sources.list</literal>" file to comment out "<literal>unstable</literal>" archive entry right after above operation.  This avoids slow update process of having too many entries in the "<literal>/etc/apt/sources.list</literal>" file although this prevents upgrading packages which were installed from <literal>unstable</literal> archive using current <literal>unstable</literal> archive.</para> </tip>
        <tip> <para>If "<literal>Pin-Priority: 1</literal>" is used instead of "<literal>Pin-Priority: 100</literal>" in the "<literal>/etc/apt/preferences</literal>" file, already installed packages having Pin-Priority value of 100 are not upgraded by <literal>unstable</literal> archive even if "<literal>testing</literal>" entry in the "<literal>/etc/apt/sources.list</literal>" file is removed.</para> </tip>
        <para>If you wish to track particular packages in <literal>unstable</literal> automatically without initial "<literal>-t unstable</literal>" installation, you must create the "<literal>/etc/apt/preferences</literal>" file and explicitly list all those packages at the top of it as the following.</para>
        <screen>Package: <emphasis>package-1</emphasis>
Pin: release a=unstable
Pin-Priority: 700

Package: <emphasis>package-2</emphasis>
Pin: release a=unstable
Pin-Priority: 700</screen>
        <para>These set Pin-Priority value for each specific package.  For example, in order to track the latest <literal>unstable</literal> version of this "Debian Reference" in English, you should have following entries in the "<literal>/etc/apt/preferences</literal>" file.</para>
        <screen>Package: debian-reference-en
Pin: release a=unstable
Pin-Priority: 700

Package: debian-reference-common
Pin: release a=unstable
Pin-Priority: 700</screen>
        <tip> <para>This <emphasis role="strong">apt-pinning</emphasis> technique is valid even when you are tracking <literal>stable</literal> archive.  Documentation packages have been always safe to install from <literal>unstable</literal> archive in my experience, so far.</para> </tip>
      </section>
      <section id="_tracking_literal_unstable_literal_with_some_packages_from_literal_experimental_literal">
        <title>Tracking <literal>unstable</literal> with some packages from <literal>experimental</literal></title>
        <warning> <para>Use of <emphasis role="strong">apt-pinning</emphasis> technique by a novice user is sure call for major troubles.  You must avoid using this technique except when you absolutely need it.</para> </warning>
        <para>Here is another example of <emphasis role="strong">apt-pinning</emphasis> technique to include specific newer upstream version packages found in <literal>experimental</literal> while tracking <literal>unstable</literal>.  You list all required archives in the "<literal>/etc/apt/sources.list</literal>" file as the following.</para>
        <screen>deb http://deb.debian.org/debian/ unstable main contrib non-free
deb http://deb.debian.org/debian/ experimental main contrib non-free
deb http://security.debian.org/ testing-security main contrib</screen>
        <para>The default Pin-Priority value for <literal>experimental</literal> archive is always 1 (&lt;&lt;100) since it is <emphasis role="strong">NotAutomatic</emphasis> archive (see <xref linkend="_archive_level_release_files"/>).  There is no need to set Pin-Priority value explicitly in the "<literal>/etc/apt/preferences</literal>" file just to use <literal>experimental</literal> archive unless you wish to track particular packages in it automatically for next upgrading.</para>
      </section>
      <section id="_emergency_downgrading">
        <title>Emergency downgrading</title>
        <warning> <para>Use of <emphasis role="strong">apt-pinning</emphasis> technique by a novice user is sure call for major troubles.  You must avoid using this technique except when you absolutely need it.</para> </warning>
        <caution> <para>Downgrading is not officially supported by the Debian by design.  It should be done only as a part of emergency recovery process.  Despite of this situation, it is known to work well in many incidents.  For critical systems, you should backup all important data on the system after the recovery operation and re-install the new system from the scratch.</para> </caution>
        <para>You may be lucky to downgrade from newer archive to older archive to recover from broken system upgrade by manipulating <emphasis role="strong">candidate version</emphasis> (see <xref linkend="_tweaking_candidate_version"/>).  This is lazy alternative to tedious actions of many "<literal>dpkg -i <emphasis>broken-package</emphasis>_<emphasis>old-version</emphasis>.deb</literal>" commands (see <xref linkend="_rescue_with_the_dpkg_command"/>).</para>
        <para>Search lines in the "<literal>/etc/apt/sources.list</literal>" file tracking <literal>unstable</literal> as the following.</para>
        <screen>deb http://deb.debian.org/debian/ @-@codename-unstable@-@ main contrib non-free</screen>
        <para>Replace it with the following to track <literal>testing</literal>.</para>
        <screen>deb http://deb.debian.org/debian/ @-@codename-testing@-@ main contrib non-free</screen>
        <para>Set the "<literal>/etc/apt/preferences</literal>" file as the following.</para>
        <screen>Package: *
Pin: release a=testing
Pin-Priority: 1010</screen>
        <para>Run "<literal>apt-get update; apt-get dist-upgrade</literal>" to force downgrading of packages across the system.</para>
        <para>Remove this special "<literal>/etc/apt/preferences</literal>" file after this emergency downgrading.</para>
        <tip> <para>It is a good idea to remove (not purge!) as much packages to minimize dependency problems.  You may need to manually remove and install some packages to get system downgraded.  Linux kernel, bootloader, udev, PAM, APT, and networking related packages and their configuration files require special attention.</para> </tip>
      </section>
      <section id="_the_equivs_package">
        <title>The equivs package</title>
        <para>If you are to compile a program from source to replace the Debian package, it is best to make it into a real local debianized package (<literal>*.deb</literal>) and use private archive.</para>
        <para>If you chose to compile a program from source and to install them under "<literal>/usr/local</literal>" instead, you may need to use <literal>equivs</literal> as a last resort to satisfy the missing package dependency.</para>
        <screen>Package: equivs
Priority: optional
Section: admin
Description: Circumventing Debian package dependencies
 This package provides a tool to create trivial Debian packages.
 Typically these packages contain only dependency information, but they
 can also include normal installed files like other packages do.
 .
 One use for this is to create a metapackage: a package whose sole
 purpose is to declare dependencies and conflicts on other packages so
 that these will be automatically installed, upgraded, or removed.
 .
 Another use is to circumvent dependency checking: by letting dpkg
 think a particular package name and version is installed when it
 isn't, you can work around bugs in other packages' dependencies.
 (Please do still file such bugs, though.)</screen>
      </section>
      <section id="_porting_a_package_to_the_stable_system">
        <title>Porting a package to the stable system</title>
        <caution> <para>There is no gurantee for the procedure descried here to work without extra manual efforts for system differences.</para> </caution>
        <para>For partial upgrades of the <literal>stable</literal> system, rebuilding a package within its environment using the source package is desirable.  This avoids massive package upgrades due to their dependencies.</para>
        <para>Add the following entries to the "<literal>/etc/apt/sources.list</literal>" of a <literal>stable</literal> system.</para>
        <screen>deb-src http://deb.debian.org/debian unstable  main contrib non-free</screen>
        <para>Install required packages for the compilation and download the source package as the following.</para>
        <screen># apt-get update
# apt-get dist-upgrade
# apt-get install fakeroot devscripts build-essential
# apt-get build-dep foo
$ apt-get source foo
$ cd foo*</screen>
        <para>Update some tool chain packages such as <literal>dpkg</literal>, and <literal>debhelper</literal> from the
backport packages if they are required for the backporting.</para>
        <para>Execute the following.</para>
        <screen>$ dch -i</screen>
        <para>Bump package version, e.g. one appended with "<literal>+bp1</literal>" in "<literal>debian/changelog</literal>"</para>
        <para>Build packages and install them to the system as the following.</para>
        <screen>$ debuild
$ cd ..
# debi foo*.changes</screen>
      </section>
      <section id="_proxy_server_for_apt">
        <title>Proxy server for APT</title>
        <para>Since mirroring whole subsection of Debian archive wastes disk space and network bandwidth, deployment of a local proxy server for APT is desirable consideration when you administer many systems on <ulink url="https://en.wikipedia.org/wiki/Local_area_network">LAN</ulink>.  APT can be configure to use generic web (http) proxy servers such as <literal>squid</literal> (see <xref linkend="_other_network_application_servers"/>) as described in <literal>apt.conf</literal>(5) and in "<literal>/usr/share/doc/apt/examples/configure-index.gz</literal>".  The "<literal>$http_proxy</literal>" environment variable can be used to override proxy server setting in the "<literal>/etc/apt/apt.conf</literal>" file.</para>
        <para>There are proxy tools specially for Debian archive.  You should check BTS before using them.</para>
        <table pgwide="0" frame="topbot" rowsep="1" colsep="1">
          <title>List of the proxy tools specially for Debian archive</title>
          <tgroup cols="4">
            <colspec colwidth="86pt" align="left"/>
            <colspec colwidth="76pt" align="left"/>
            <colspec colwidth="70pt" align="left"/>
            <colspec colwidth="515pt" align="left"/>
            <thead>
              <row>
                <entry> package </entry>
                <entry> popcon </entry>
                <entry> size </entry>
                <entry> description </entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry> <literal>approx</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry> caching proxy server for Debian archive files (compiled <ulink url="https://en.wikipedia.org/wiki/Objective_Caml">OCaml</ulink> program) </entry>
              </row>
              <row>
                <entry> <literal>apt-cacher</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry> Caching proxy for Debian package and source files (Perl program) </entry>
              </row>
              <row>
                <entry> <literal>apt-cacher-ng</literal> </entry>
                <entry> @-@popcon1@-@ </entry>
                <entry> @-@psize1@-@ </entry>
                <entry> Caching proxy for distribution of software packages (compiled C++ program) </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <caution> <para>When Debian reorganizes its archive structure, these specialized proxy tools tend to require code rewrites by the package maintainer and may not be functional for a while.  On the other hand, generic web (http) proxy servers are more robust and easier to cope with such changes.</para> </caution>
      </section>
      <section id="_more_readings_for_the_package_management">
        <title>More readings for the package management</title>
        <para>You can learn more on the package management from following documentations.</para>
        <itemizedlist>
          <listitem>
            <para> Primary documentations on the package management: </para>
            <itemizedlist>
              <listitem> <para><literal>aptitude</literal>(8), <literal>dpkg</literal>(1), <literal>tasksel</literal>(8), <literal>apt</literal>(8), <literal>apt-get</literal>(8), <literal>apt-config</literal>(8), <literal>apt-secure</literal>(8), <literal>sources.list</literal>(5), <literal>apt.conf</literal>(5), and <literal>apt_preferences</literal>(5); </para> </listitem>
              <listitem> <para> "<literal>/usr/share/doc/apt-doc/guide.html/index.html</literal>" and "<literal>/usr/share/doc/apt-doc/offline.html/index.html</literal>" from the <literal>apt-doc</literal> package; and </para> </listitem>
              <listitem> <para> "<literal>/usr/share/doc/aptitude/html/en/index.html</literal>" from the <literal>aptitude-doc-en</literal> package.  </para> </listitem>
            </itemizedlist>
          </listitem>
          <listitem>
            <para> Official and detailed documentations on the Debian archive: </para>
            <itemizedlist>
              <listitem> <para><ulink url="https://www.debian.org/doc/debian-policy/ch-archive">"Debian Policy Manual Chapter 2 - The Debian Archive"</ulink>, </para> </listitem>
              <listitem> <para><ulink url="https://www.debian.org/doc/manuals/developers-reference/resources.html#archive">"Debian Developer's Reference, Chapter 4 - Resources for Debian Developers 4.6 The Debian archive"</ulink>, and </para> </listitem>
              <listitem> <para><ulink url="https://www.debian.org/doc/manuals/debian-faq/ftparchives">"The Debian GNU/Linux FAQ, Chapter 6 - The Debian FTP archives"</ulink>.  </para> </listitem>
            </itemizedlist>
          </listitem>
          <listitem>
            <para> Tutorial for building of a Debian package for Debian users: </para>
            <itemizedlist>
              <!--  <listitem> <para><ulink url="https://www.debian.org/doc/manuals/maint-guide/">"Debian New Maintainers' Guide"</ulink> (deprecated).  </para> </listitem> -->
              <listitem> <para><ulink url="https://www.debian.org/doc/manuals/debmake-doc/">"Guide for Debian Maintainers"</ulink>.  </para> </listitem>
            </itemizedlist>
          </listitem>
        </itemizedlist>
      </section>
    </section>
  </chapter>