dpkg reference Manual

dpkg reference Manual draft Wichert Akkerman

wichert@deephackmode.org

2001 2002 Wichert Akkerman Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation. There are no invariant sections. A copy of the license is included in the section entitled "GNU Free Documentation License". Preface This manual is a reference to the &debian; package management system. This manual is currently being written based on the previous packaging manual and as such is a work in progress. Introduction The Debian package management system is build up from various seperate tools that work together form a comprehensive system to manage your system. This document describes all the tools that used to handle and produce them as well as the file formats used. Version numbers It is essential for a packaging system to have a documented method to compare version numbers. Unfortunately there are different ways of dealing with them, each with their own good and bad sides. This chapter describes how &dpkg; compares version numbers. Version numbers are ASCII strings made up from alphanumeric characters (letters and digits) and the hyphen (-), dot (.), plus (+), minus (-) and colon (:) characters. A version number consists of two parts: the upstream version, and optionally the package revision, which are seperated by a hyphen. If there is no seperate package revision then the upstream version is not allowed to contain a hyphen. Comparing version numbers is done by breaking them into pieces and comparing those from left to right. Pieces are seperated by a transition from numbers to letters and by non-alphanumeric characters. Starting from &dpkg; 1.10 numbers of unlimited length may be used. Olders versions converted numbers to integers before comparing them and as a result can not handle numbers that do not fit into the C type int (2^31-1 on 32bit architectures and 2^63-1 on 64bit architectures). Managing diversions Diversions are a method to instruct &dpkg; to use a different filename when installing a file. This can be useful to prevent conflicts between related packages or when a system administator wants to replace a file with another version. Diversions are specific to either a package or the local system. A package specific diversion will only divert a file if it does not belongs to a specific package that was given when the diversion was created. This allow a package to divert a file from other packages and replacing them with its own copy. Local diversions are applied to all packages and can be used by the system administrator.

Managing diversions with dpkg-divert The official documentation for dpkg-divert can always be found online in the dpkg-divert 8 manual page.

Adding new diversions New options can be added using the --add option for dpkg-divert. Its syntax is:

Managing file permissions / ownership When you install a package &dpkg; will use the ownership and permissions that are used inside the package. In some situations you might not agree with those defaults and would like to use other settings. To support this a feature called statoverrides was introduced in &dpkg; 1.8.0, and an accompanying tool called dpkg-statoverride. Even though we use the word file here, this applies to all filesystem objects that &dpkg; handles, including directories, devices, etc. If you look at the &dpkg; changelog you will see that statoverrides were actually added in version 1.7.0. However that version had some problems both in dpkg-statoverrides which broke adding and removing of overrides and in &dpkg; itself which made it only apply overrides to normal files. Both problems were fixed in version 1.8.0.

How permissions and ownership are applied &dpkg; uses the following logic to determine the ownership and permissions to use when installing a file: Check if there is a statoverride registered for this file If an override is present use the ownership and permission specified in the override. If no override is present: Check if there is a system account with the same name as the owner used inside the archive. If so use that as owner, otherwise use the uid as used in the package. Check if there is a system group with the same name as the group used inside the archive. If so use that as group, otherwise use the gid as used in the package. Use the permissions as used in the package. The exact method that &dpkg; uses to set the ownership and permissions depends on the type of file that is being created: regular files Created with owner and group set to root and with mode 0. After the data has been written to the file the ownership and mode are set to their final values. FIFOs character and block devices directories Created with owner and group set to root and with mode 0, and then updated to set the ownership and mode to their final values. Hardlinks After the link has been made its ownership and permissions are setup. This means the original file will also be changed!

Managing overrides with dpkg-statoverride The official documentation for dpkg-statoverride can always be found online in the dpkg-statoverride 8 manual page.

Listing overrides You can get a list of all overrides present in the database by using the option:

dpkg-statoverride <glob>

There is an optional glob option that restricts the output from to overrides for files that match the glob expression. Please see the sh 1 or glob7 for a description of glob syntax. Listing overrides [fog;~]-1# dpkg-statoverride --list root root 0755 /bin/mount root root 0755 /bin/ping [fog;~]-2# dpkg-statoverride --list '*mount*' root root 0755 /bin/mount

Adding new overrides New options can be added using the option for dpkg-statoverride. Its syntax is:

dpkg-statoverride <user> <group> <mode> <file>

This will add an override for <file> by telling &dpkg; to use the user, group and mode given to dpkg-statoverride. The user and group can be specified in two ways: either by using the name as found in the system account database (ie /etc/passwd, NIS or another source configured in /etc/nsswitch.conf), or by using a number prefixed with #. Adding an override [fog;~]-1# ls -l /bin/mount -rwsr-xr-x 1 root root 56284 Nov 23 06:14 /bin/mount [fog;~]-2# dpkg-statoverride --add root root 0755 /bin/mount [fog;~]-3# ls -l /bin/mount -rwsr-xr-x 1 root root 56284 Nov 23 06:14 /bin/mount Adding an override does not update the file on the filesystem, unless you also specify the option. Adding an override using --update [fog;~]-1# ls -l /bin/mount -rwsr-xr-x 1 root root 56284 Nov 23 06:14 /bin/mount [fog;~]-2# dpkg-statoverride --update --add root root 0755 /bin/mount [fog;~]-3# ls -l /bin/mount -rwxr-xr-x 1 root root 56284 Nov 23 06:14 /bin/mount If an override already exists and you want to replace it you can use the to force dpkg-statoverride to replace the existing override. Replacing an existing override [fog;~/sources/play/pkg-manual]-1# dpkg-statoverride --add root root 0755 /bin/mount An override for "/bin/mount" already exists, aborting [fog;~]-2# dpkg-statoverride --force --add root root 0755 /bin/mount An override for "/bin/mount" already exists, but --force specified so lets ignore it. [fog;~]-3# dpkg-statoverride --list /bin/mount root root 0755 /bin/mount

Removing overrides Overrides can be removed using the option, which takes a single filename as argument:

dpkg-statoverride <file>

This will remove the override for <file> from the database. When an override for a file is removed its ownership and permission are not restored to the original value. Removing an override [fog;~]-1# dpkg-statoverride --list root root 0755 /bin/mount [fog;~]-2# dpkg-statoverride --remove /bin/mount [fog;~]-3# dpkg-statoverride --list [fog;~]-4#

File formats This chapter describes all the file formats used by the package tools. All files are text files which you can view and modify using any normal text editor if needed. Most file formats are based on the RFC822 format, which is best known as the format used in e-mail headers. Each format has a version number which indicates the revision of the format being used. This version is always of the form "X.Y". The first number (X) is the major version. Within a major version the only allowed changes in format are the addition of new fields. This guarantees that tools will always be fully backwards and upwards compatible within a major version.

RFC822 A RFC822 style messages consists of one or more blocks, seperated by null lines (an empty line). Each block is made up of fields. Fields can be folded over multiple lines by inserting a 'newline whitespace' pair. This combination is interpreted as a single whitespace. Each fiels is a single line consisting of a field-name and a field-body, seperated by a colon (:). The field-name is made up from printable ASCII characters minus the colon. The field-body may be composed of all ASCII characters except CR or LF (they are automatically removed when unfolding lines). RFC822 style file Header: value Description: this is an example of an RFC822 style message Section: new Name: body Description: this is block 2 of the example X-Fortune: To be excellent when engaged in administration is to be like the North Star. As it remains in its one position, all the other stars surround it. -- Confucius

changes file The .changse file is used to describe a set of files that is going to be installed in an archive. All files have to belong to the same source package. The data in a changes include the changes made since the previous revision, version and architecture information and the list of files that form the change set along with a checksum Just like other dpkg datafiles this file is formated using RFC822 syntax. In addition the file can signed as an OpenPGP ASCII armored message (see RFC2440). The table below lists the allowed fields in a .dsc file. The order used is not important, although dpkg-genchanges will output the fields using the ordering used in the table. Fields in a <filename>.changes</filename> file Field Description Format Version of the file format used. Currently 1.7. Date The date (in RFC822 format) when the change set was build. Source The name of the source package from which the changes were build. Binary The binary packages (ie &deb; files) that are part of the change set. Architecture A space seperate list of architectures for which files are included in the set. Version Version number of the source from which the files were built. Distribution Distribution in which the changes should be installed, as taken from debian/changelog. Urgency Urgency of the changes, as taken from debian/changelog. Maintainer The maintainer of the package, as listed in debian/control. Changed-By The person who made the last changes to the sources, as listed in debian/changelog. Description Multi-line field describing the &deb; files in the package. Each line describes a single package in the format "packagename - short description". Closes Space seperate list of bugreports which are closed by this change set. (Optional) Changes Multi-line field with the changes made since the previous version, as taken from debian/changelog. Can possibly mention changes for multiple versions. Files Multi-line field with the list of files in the change set. Each line describes a single file in the format "MD5 filesize filename".

dsc file The .dsc file describes the source for a Debian package: it contains general information over the source such as the name of the package and which binary package it produces as well as the files that contain the sourcecode. Just like other dpkg datafiles this file is formated using RFC822 syntax. In addition the file can signed as an OpenPGP ASCII armored message (see RFC2440). The table below lists the allowed fields in a .dsc file. The order used is not important, although dpkg-source will output the fields using the ordering used in the table. Fields in a <filename>.dsc</filename> file FieldDescriptionFormat Version of the file format used. Currently 1.0. Source Name of the source packageVersion Version number of the sourceBinary comma seperated list of binary packages build from this sourceOrigin Name of the organization that procuded this package Maintainer Maintainer of this packageUploaders Multi-line field with list of people authorized to make uploads of a package (optional) Architecture Space seperated list of architectures for which package are build from this source Standards-Version Version of &debian; policy this package is complient with Files Multi-line field with list of files with the actual source code

The Files field contains one line for each file that is contains source for this package (only 2 files are supported: a .tar.gz file with the (original) source, and an optional .diff.gz with Debian changes to the source). Each file description consists of 3 items, seperated by a single space: A MD5 checksum of the file The filesize in bytes The filename modutils .dsc file -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Format: 1.0 Source: modutils Version: 2.4.1-1 Binary: modutils Origin: debian Maintainer: Wichert Akkerman <wakkerma@debian.org> Architecture: any Standards-Version: 3.2.0 Files: 6d69ff476c964e703659d950999e411c 246022 modutils_2.4.1.orig.tar.gz 3de7100460662472404f8a83cccde6da 17219 modutils_2.4.1-1.diff.gz -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.0.4 (GNU/Linux) Comment: For info see http://www.gnupg.org iEYEARECAAYFAjpbNIAACgkQPLiSUC+jvC1CFQCePvKBH6qT7/BKXVHCamKXZvZq Be8An1QDPcyDFtMddYJw/BwTVphbwzU6 =Zl3g -----END PGP SIGNATURE-----

control Fields in the source section of the <filename>control</filename> file Field required Description Sourceyes Name of the source packageSectionno Package category for this package, used by frontends. Priorityno Indication of package importance. Legal values are extra, important, optional, required and standard. Maintaineryes Name of the source packageStandards-Versionno Version of &debian; policy this package is complient withBuild-Depends, Build-Conflicts, Build-Depends-Indep, Build-Conflicts-Indepno Specify demands on the build environmentBugsno Name of the source packageOriginno Name of the source package

Fields in the package section of the <filename>control</filename> file Field required Description Packageyes Name of the packageArchitectureyes Space seperated list of architectures for which package are build from this sourceEssentialno Indicates if a package is essential to the system Pre-Depends, Depends, Recommends, Suggests, Replaces, Conflictsno Specify relations to other packagesDescriptionyes Description of the package

diversions The diversions file contains all the alternatives defined on this system. It is located in the &dpkg; admin directory. This is an internal &dpkg; file: do not edit it by hand unless really needed, but use the dpkg-divert tool instead. For each diversion there are 3 lines in the diversions file: The name of the file that will be diverted. The filename that the diverted file will be diverted to. The name of the package that made this diversion. If it is a local (ie user) diversion the magic packagename `:' is used instead. Example <filename>diversions</filename> file /sbin/modprobe /sbin/modprobe.orig : /usr/bin/locate /usr/bin/locate.notslocate slocate

statoverrides This file contains the list of all statoverrides that &dpkg; uses when unpacking packages. It is located in the &dpkg; admin directory. Each line in the file represents one override, and comments are not allowed. This is an internal &dpkg; file: do not edit it by hand unless really needed, but use the dpkg-statoverride tool instead. Each line contains 4 items, seperated by whitespace: The owner to use. This can be either an accountname that must be present on the system, or a numerical uid. Uids are prefixed with a #. The group to use. This can be either a group that must be present on the system, or a numerical gid. Gids are prefixed with a #. Mode to use for this file. This is an octal number. The filesystem object (file, directory, device, FIFO or link) to which this override should be applied. Since this is the last item on a line it may contain whitespace. Example <filename>statoverride</filename> file root wheel 04750 /bin/su root adm 0750 /var/log/apache This will tell &dpkg; to do the following: /bin/su is installed owned by user root and group wheel with mode 04750. This means that only people in the wheel group are allowed to run su. /var/log/apache is installed owned by user root and group adm with mode 0750. This restricts the ability to view the apache to people in the adm group by disallowing others to access the /var/log/apache directory.

alternatives The configuration for alternatives is spread over two places: the symlink to the selected alternative is stored in /etc/alternatives and the list of available alternatives is kept in a series of files in /var/lib/dpkg/alternatives/. For each alternative there is a single file in /var/lib/dpkg/alternatives/ named after the the alternative it describes. The file is a normal text file: The first line lists the state of the alternative, either `manual' or `auto'. The second line is the filename that the alternative will provide. A list of zero or more slave links. For each slave there are two lines: the first contains the name of the slave and the second contains the filename. An empty line A list of one or more alternatives. Each alternative is made up as follows: The filename of the file providing the alternative. The priority For each slave link a single line with the file providing the link. An empty line can be used to indicate an alternative does not provide a slave.