Download the ebook

- Prev
- The Debian Administrator's Handbook
- Next

## 5.4. Manipulating Packages with `dpkg`

`dpkg` is the base command for handling Debian packages on the system. If you have `.deb` packages, it is `dpkg` that allows installation or analysis of their contents. But this program only has a partial view of the Debian universe: it knows what is installed on the system, and whatever it is given on the command line, but knows nothing of the other available packages. As such, it will fail if a dependency is not met. Tools such as `apt` and `aptitude`, on the contrary, will create a list of dependencies to install everything as automatically as possible.

### 5.4.1. Installing Packages

`dpkg` is, above all, the tool for installing an already available Debian package (because it does not download anything). To do this, we use its `-i` or `--install` option.

Example 5.2. Installation of a package with `dpkg`

    # dpkg -i man-db_2.8.5-2_amd64.deb
    (Reading database ... 14913 files and directories currently installed.)
    Preparing to unpack .../man-db_2.8.5-2_amd64.deb ...
    Unpacking man-db (2.8.5-2) over (2.8.5-2) ...
    Setting up man-db (2.8.5-2) ...
    Updating database of manual pages ...
    Processing triggers for mime-support (3.62) ...

We can see the different steps performed by `dpkg`; we know, thus, at what point any error may have occurred. The installation can also be effected in two stages: first unpacking, then configuration. `apt` takes advantage of this, limiting the number of calls to `dpkg` (since each call is costly, due to loading of the database in memory, especially the list of already installed files).

Example 5.3. Separate unpacking and configuration

    # dpkg --unpack man-db_2.8.5-2_amd64.deb
    (Reading database ... 14937 files and directories currently installed.)
    Preparing to unpack man-db_2.8.5-2_amd64.deb ...
    Unpacking man-db (2.8.5-2) over (2.8.5-2) ...
    Processing triggers for mime-support (3.62) ...
    # dpkg --configure man-db
    Setting up man-db (2.8.5-2) ...
    Updating database of manual pages ...

Sometimes `dpkg` will fail to install a package and return an error; if the user orders it to ignore this, it will only issue a warning; it is for this reason that we have the different `--force-*` options. The `dpkg --force-help` command, or documentation of this command, will give a complete list of these options. The most frequent error, which you are bound to encounter sooner or later, is a file collision. When a package contains a file that is already installed by another package, `dpkg` will refuse to install it. The following messages will then appear:

    Unpacking libgdm (from .../libgdm_3.8.3-2_amd64.deb) ...
    dpkg: error processing /var/cache/apt/archives/libgdm_3.8.3-2_amd64.deb (--unpack):
     trying to overwrite '/usr/bin/gdmflexiserver', which is also in package gdm3 3.4.1-9

In this case, if you think that replacing this file is not a significant risk to the stability of your system (which is usually the case), you can use the option `--force-overwrite`, which tells `dpkg` to ignore this error and overwrite the file.
While there are many available `--force-*` options, only `--force-overwrite` is likely to be used regularly. These options only exist for exceptional situations, and it is better to leave them alone as much as possible in order to respect the rules imposed by the packaging mechanism. Do not forget, these rules ensure the consistency and stability of your system.

### 5.4.2. Package Removal

Invoking `dpkg` with the `-r` or `--remove` option, followed by the name of a package, removes that package. This removal is, however, not complete: all of the configuration files, maintainer scripts, log files (system logs) and other user data handled by the package remain. That way disabling the program is easily done by uninstalling it, and it is still possible to quickly reinstall it with the same configuration. To completely remove everything associated with a package, use the `-P` or `--purge` option, followed by the package name.

Example 5.4. Removal and purge of the debian-cd package

    # dpkg -r debian-cd
    (Reading database ... 15915 files and directories currently installed.)
    Removing debian-cd (3.1.25) ...
    # dpkg -P debian-cd
    (Reading database ... 15394 files and directories currently installed.)
    Purging configuration files for debian-cd (3.1.25) ...

### 5.4.3. Querying `dpkg`'s Database and Inspecting `.deb` Files

Before concluding this section, we will study `dpkg` options that query the internal database in order to obtain information. Giving first the long options and then corresponding short options (that will evidently take the same possible arguments) we cite `--listfiles package` (or `-L`), which lists the files installed by this package; `--search file` (or `-S`), which finds the package(s) containing the file; `--status package` (or `-s`), which displays the headers of an installed package; `--list` (or `-l`), which displays the list of packages known to the system and their installation status; `--contents file.deb` (or `-c`), which lists the files in the Debian package specified; `--info file.deb` (or `-I`), which displays the headers of this Debian package.

Example 5.5. Various queries with `dpkg`

    $ dpkg -L base-passwd
    /.
    /usr
    /usr/sbin
    /usr/sbin/update-passwd
    /usr/share
    /usr/share/base-passwd
    /usr/share/base-passwd/group.master
    /usr/share/base-passwd/passwd.master
    /usr/share/doc
    /usr/share/doc/base-passwd
    /usr/share/doc/base-passwd/README
    /usr/share/doc/base-passwd/changelog.gz
    /usr/share/doc/base-passwd/copyright
    /usr/share/doc/base-passwd/users-and-groups.html
    /usr/share/doc/base-passwd/users-and-groups.txt.gz
    /usr/share/doc-base
    /usr/share/doc-base/users-and-groups
    /usr/share/lintian
    /usr/share/lintian/overrides
    /usr/share/lintian/overrides/base-passwd
    /usr/share/man
    /usr/share/man/de
    /usr/share/man/de/man8
    /usr/share/man/de/man8/update-passwd.8.gz
    /usr/share/man/es
    /usr/share/man/es/man8
    /usr/share/man/es/man8/update-passwd.8.gz
    /usr/share/man/fr
    /usr/share/man/fr/man8
    /usr/share/man/fr/man8/update-passwd.8.gz
    /usr/share/man/ja
    /usr/share/man/ja/man8
    /usr/share/man/ja/man8/update-passwd.8.gz
    /usr/share/man/man8
    /usr/share/man/man8/update-passwd.8.gz
    /usr/share/man/pl
    /usr/share/man/pl/man8
    /usr/share/man/pl/man8/update-passwd.8.gz
    /usr/share/man/ru
    /usr/share/man/ru/man8
    /usr/share/man/ru/man8/update-passwd.8.gz
    $ dpkg -S /bin/date
    coreutils: /bin/date
    $ dpkg -s coreutils
    Package: coreutils
    Essential: yes
    Status: install ok installed
    Priority: required
    Section: utils
    Installed-Size: 15719
    Maintainer: Michael Stone <mstone@debian.org>
    Architecture: amd64
    Multi-Arch: foreign
    Version: 8.30-3
    Pre-Depends: libacl1 (>= 2.2.23), libattr1 (>= 1:2.4.44), libc6 (>= 2.28), libselinux1 (>= 2.1.13)
    Description: GNU core utilities
     This package contains the basic file, shell and text manipulation
     utilities which are expected to exist on every operating system.
     .
     Specifically, this package includes:
     arch base64 basename cat chcon chgrp chmod chown chroot cksum comm cp
     csplit cut date dd df dir dircolors dirname du echo env expand expr
     factor false flock fmt fold groups head hostid id install join link ln
     logname ls md5sum mkdir mkfifo mknod mktemp mv nice nl nohup nproc numfmt
     od paste pathchk pinky pr printenv printf ptx pwd readlink realpath rm
     rmdir runcon sha*sum seq shred sleep sort split stat stty sum sync tac
     tail tee test timeout touch tr true truncate tsort tty uname unexpand
     uniq unlink users vdir wc who whoami yes
    Homepage: http://gnu.org/software/coreutils
    $ dpkg -l 'b*'
    Desired=Unknown/Install/Remove/Purge/Hold
    | Status=Not/Inst/Conf-files/Unpacked/halF-conf/Half-inst/trig-aWait/Trig-pend
    |/ Err?=(none)/Reinst-required (Status,Err: uppercase=bad)
    ||/ Name                       Version              Architecture Description
    +++-====================-===============-===============-==================================================
    un  backupninja          <none>          <none>          (no description available)
    un  backuppc             <none>          <none>          (no description available)
    un  baobab               <none>          <node>          (no description available)
    un  base                 <none>          <none>          (no description available)
    un  base-config          <none>          <none>          (no description available)
    ii  base-files           11              amd64           Debian base system miscellaneous files
    ii  base-passwd          3.5.46          amd64           Debian base system master password and group files
    ii  bash                 5.0-4           amd64           GNU Bourne Again SHell
    [..]
    $ dpkg -c /var/cache/apt/archives/gnupg-utils_2.2.12-1_amd64.deb
    drwxr-xr-x root/root         0 2018-12-15 02:17 ./
    drwxr-xr-x root/root         0 2018-12-15 02:17 ./usr/
    drwxr-xr-x root/root         0 2018-12-15 02:17 ./usr/bin/
    -rwxr-xr-x root/root      3516 2018-12-15 02:17 ./usr/bin/gpg-zip
    -rwxr-xr-x root/root    866256 2018-12-15 02:17 ./usr/bin/gpgcompose
    -rwxr-xr-x root/root     30792 2018-12-15 02:17 ./usr/bin/gpgparsemail
    -rwxr-xr-x root/root     84432 2018-12-15 02:17 ./usr/bin/gpgsplit
    -rwxr-xr-x root/root    154952 2018-12-15 02:17 ./usr/bin/gpgtar
    -rwxr-xr-x root/root    166568 2018-12-15 02:17 ./usr/bin/kbxutil
    -rwxr-xr-x root/root      1081 2017-08-28 12:22 ./usr/bin/lspgpot
    -rwxr-xr-x root/root      2194 2018-11-18 23:37 ./usr/bin/migrate-pubring-from-classic-gpg
    -rwxr-xr-x root/root    121576 2018-12-15 02:17 ./usr/bin/symcryptrun
    -rwxr-xr-x root/root     18424 2018-12-15 02:17 ./usr/bin/watchgnupg
    drwxr-xr-x root/root         0 2018-12-15 02:17 ./usr/sbin/
    -rwxr-xr-x root/root      3075 2018-12-15 02:17 ./usr/sbin/addgnupghome
    -rwxr-xr-x root/root      2217 2018-12-15 02:17 ./usr/sbin/applygnupgdefaults
    drwxr-xr-x root/root         0 2018-12-15 02:17 ./usr/share/
    drwxr-xr-x root/root         0 2018-12-15 02:17 ./usr/share/doc/
    [...]
    $ dpkg -I /var/cache/apt/archives/gnupg-utils_2.2.12-1_amd64.deb
     new Debian package, version 2.0.
     size 857408 bytes: control archive=1844 bytes.
        1564 bytes,    32 lines      control
        1804 bytes,    28 lines      md5sums
     Package: gnupg-utils
     Source: gnupg2
     Version: 2.2.12-1
     Architecture: amd64
     Maintainer: Debian GnuPG Maintainers <pkg-gnupg-maint@lists.alioth.debian.org>
     Installed-Size: 1845
     Depends: libassuan0 (>= 2.0.1), libbz2-1.0, libc6 (>= 2.25), libgcrypt20 (>= 1.8.0), libgpg-error0 (>= 1.26-2~), libksba8 (>= 1.3.4), libreadline7 (>= 6.0), zlib1g (>= 1:1.1.4)
     Recommends: gpg, gpg-agent, gpgconf, gpgsm
     Breaks: gnupg (<< 2.1.21-4), gnupg-agent (<< 2.1.21-4)
     Replaces: gnupg (<< 2.1.21-4), gnupg-agent (<< 2.1.21-4)
     Section: utils
     Priority: optional
     Multi-Arch: foreign
     Homepage: https://www.gnupg.org/
     Description: GNU privacy guard - utility programs
      GnuPG is GNU's tool for secure communication and data storage.
      .
      This package contains several useful utilities for manipulating
      OpenPGP data and other related cryptographic elements.  It includes:
      .
       * addgnupghome -- create .gnupg home directories
       * applygnupgdefaults -- run gpgconf --apply-defaults for all users
       * gpgcompose -- an experimental tool for constructing arbitrary
                       sequences of OpenPGP packets (e.g. for testing)
       * gpgparsemail -- parse an e-mail message into annotated format
       * gpgsplit -- split a sequence of OpenPGP packets into files
       * gpgtar -- encrypt or sign files in an archive
       * kbxutil -- list, export, import Keybox data
       * lspgpot -- convert PGP ownertrust values to GnuPG
       * migrate-pubring-from-classic-gpg -- use only "modern" formats
       * symcryptrun -- use simple symmetric encryption tool in GnuPG framework
       * watchgnupg -- watch socket-based logs
    [..]

### 5.4.4. `dpkg`'s Log File

`dpkg` keeps a log of all of its actions in `/var/log/dpkg.log`. This log is extremely verbose, since it details every one of the stages through which packages handled by `dpkg` go. In addition to offering a way to track dpkg's behavior, it helps, above all, to keep a history of the development of the system: one can find the exact moment when each package has been installed or updated, and this information can be extremely useful in understanding a recent change in behavior. Additionally, all versions being recorded, it is easy to cross-check the information with the `changelog.Debian.gz` for packages in question, or even with online bug reports.

### 5.4.5. Multi-Arch Support

All Debian packages have an `Architecture` field in their control information. This field can contain either “`all`” (for packages that are architecture independent) or the name of the architecture that it targets (like “amd64”, “armhf”, …). In the latter case, by default, `dpkg` will only accept to install the package if its architecture matches the host's architecture as returned by `dpkg --print-architecture`.
This restriction ensures that users do not end up with binaries compiled for an incorrect architecture. Everything would be perfect except that (some) computers can run binaries for multiple architectures, either natively (an “amd64“ system can run “i386” binaries) or through emulators.

#### 5.4.5.1. Enabling Multi-Arch

`dpkg`'s multi-arch support allows users to define “foreign architectures” that can be installed on the current system. This is simply done with `dpkg --add-architecture` like in the example below. There is a corresponding `dpkg --remove-architecture` to drop support of a foreign architecture, but it can only be used when no packages of this architecture remain.

    # dpkg --print-architecture
    amd64
    # dpkg --print-foreign-architectures
    # dpkg -i gcc-8-base_8.3.0-6_armhf.deb
    dpkg: error processing archive gcc-8-base_8.3.0-6_armhf.deb (--install):
     package architecture (armhf) does not match system (amd64)
    Errors were encountered while processing:
     gcc-8-base_8.3.0-6_armhf.deb
    # dpkg --add-architecture armhf
    # dpkg --add-architecture armel
    # dpkg --print-foreign-architectures
    armhf
    armel
    # dpkg -i gcc-8-base_8.3.0-6_armhf.deb
    (Reading database ... 14319 files and directories currently installed.)
    Preparing to unpack gcc-8-base_8.3.0-6_armhf.deb ...
    Unpacking gcc-8-base:armhf (8.3.0-6) ...
    Setting up gcc-8-base:armhf (8.3.0-6) ...
    # dpkg --remove-architecture armhf
    dpkg: error: cannot remove architecture 'armhf' currently in use by the database
    # dpkg --remove-architecture armel
    # dpkg --print-foreign-architectures
    armhf

#### 5.4.5.2. Multi-Arch Related Changes

To make multi-arch actually useful and usable, libraries had to be repackaged and moved to an architecture-specific directory so that multiple copies (targeting different architectures) can be installed alongside. Such updated packages contain the “`Multi-Arch: same`” header field to tell the packaging system that the various architectures of the package can be safely co-installed (and that those packages can only satisfy dependencies of packages of the same architecture). The most important libraries have been converted since the introduction of multi-arch in Debian 7 Wheezy, but there are many libraries that will likely never be converted unless someone specifically requests it (through a bug report for example).

    $ dpkg -s gcc-8-base
    dpkg-query: error: --status needs a valid package name but 'gcc-8-base' is not: ambiguous package name 'gcc-8-base' with more than one installed instance

    Use --help for help about querying packages.
    $ dpkg -s gcc-8-base:amd64 gcc-8-base:armhf | grep ^Multi
    Multi-Arch: same
    Multi-Arch: same
    $ dpkg -L libgcc1:amd64 |grep .so
    /lib/x86_64-linux-gnu/libgcc_s.so.1
    $ dpkg -S /usr/share/doc/gcc-8-base/copyright
    gcc-8-base:amd64, gcc-8-base:armhf: /usr/share/doc/gcc-8-base/copyright

It is worth noting that `Multi-Arch: same` packages must have their names qualified with their architecture to be unambiguously identifiable. They also have the possibility to share files with other instances of the same package; `dpkg` ensures that all packages have bit-for-bit identical files when they are shared. Last but not least, all instances of a package must have the same version. They must thus be upgraded together.
Multi-Arch support also brings some interesting challenges in the way dependencies are handled. Satisfying a dependency requires either a package marked “`Multi-Arch: foreign`” or a package whose architecture matches the one of the package declaring the dependency (in this dependency resolution process, architecture-independent packages are assumed to be of the same architecture than the host). A dependency can also be weakened to allow any architecture to fulfill it, with the `package:any` syntax, but foreign packages can only satisfy such a dependency if they are marked “`Multi-Arch: allowed`”.

- Prev5.3. Structure of a Source Package
- Up
- Home
- Next5.5. Coexistence with Other Packaging Systems