Ubuntu Policy Manual


Informally, the criteria used for inclusion is that the material meet one of the following requirements:

Standard interfaces

The material presented represents an interface to the packaging system that is mandated for use, and is used by, a significant number of packages, and therefore should not be changed without peer review. Package maintainers can then rely on this interfaces not changing, and the package management software authors need to ensure compatibility with these interface definitions. (Control file and changelog file formats are examples.)

Chosen Convention

If there are a number of technically viable choices that can be made, but one needs to select one of these options for inter-operability. The version number format is one example.

Please note that these are not mutually exclusive; selected conventions often become parts of standard interfaces.


Compare RFC 2119. Note, however, that these words are used in a different way in this document.


The Ubuntu archive software uses the term "component" internally and in the Release file format to refer to the division of an archive. The Debian Social Contract simply refers to "areas." This document uses terminology similar to the Social Contract.


It is possible that there are policy requirements which the package is unable to meet, for example, if the source is unavailable. These situations will need to be handled on a case-by-case basis.


It is possible that there are policy requirements which the package is unable to meet, for example, if the source is unavailable. These situations will need to be handled on a case-by-case basis.


Packages that originally came from the Debian archive will often not have Section fields matching the archive area selected for them in Ubuntu. There is no need to change the package just for this; the maintainers of the Ubuntu archive can and will override its placement.


This is an important criterion because we are trying to produce, amongst other things, a free Unix.


The detailed procedure for doing this gracefully can be found in the Debian Developer's Reference, see Related documents, Section 1.4.


This is in response to a poll of Debian maintainers, documented in the DebianMaintainerField specification.


The blurb that comes with a program in its announcements and/or README files is rarely suitable for use in a description. It is usually aimed at people who are already in the community where the package is used.


Essential is needed in part to avoid unresolvable dependency loops on upgrade. If packages add unnecessary dependencies on packages in this set, the chances that there will be an unresolvable dependency loop caused by forcing these Essential packages to be configured first before they need to be is greatly increased. It also increases the chances that frontends will be unable to calculate an upgrade path, even if one exists.

Also, functionality is rarely ever removed from the Essential set, but packages have been removed from the Essential set when the functionality moved to a different package. So depending on these packages just in case they stop being essential does way more harm than good.


The control.tar.gz inside the .deb. See deb(5).


Debconf or another tool that implements the Debian Configuration Management Specification will also be installed, and any versioned dependencies on it will be satisfied before preconfiguration begins.


See the file upgrading-checklist for information about policy which has changed between different versions of this document.




The reason for this is that dependencies change, and you should list all those packages, and only those packages that you need directly. What others need is their business. For example, if you only link against libimlib, you will need to build-depend on libimlib2-dev but not against any libjpeg* packages, even though libimlib2-dev currently depends on them: installation of libimlib2-dev will automatically ensure that all of its run-time dependencies are satisfied.


Mistakes in changelogs are usually best rectified by making a new changelog entry rather than "rewriting history" by editing old changelog entries.


Although there is nothing stopping an author who is also the Ubuntu maintainer from using this changelog for all their changes, it will have to be renamed if the Ubuntu and upstream maintainers become different people. In such a case, however, it might be better to maintain the package as a non-native package.


To be precise, the string should match the following Perl regular expression:


Then all of the bug numbers listed will be closed by the archive maintenance script (katie) using the version of the changelog entry.


To be precise, the string should match the following Perl regular expression:


Then all of the bug numbers listed will be closed by the archive maintenance software using the version of the changelog entry.


This is generated by date -R.


The rationale is that there is some information conveyed by knowing the age of the file, for example, you could recognize that some documentation is very old by looking at the modification time, so it would be nice if the modification time of the upstream source would be preserved.


This is not currently detected when building source packages, but only when extracting them.

Hard links may be permitted at some point in the future, but would require a fair amount of work.


Setgid directories are allowed.


Another common way to do this is for build to depend on build-stamp and to do nothing else, and for the build-stamp target to do the building and to touch build-stamp on completion. This is especially useful if the build routine creates a file or directory called build; in such a case, build will need to be listed as a phony target (i.e., as a dependency of the .PHONY target). See the documentation of make for more information on phony targets.


The fakeroot package often allows one to build a package correctly even without being root.


Some packages support any delimiter, but whitespace is the easiest to parse inside a makefile and avoids ambiguity with flag values that contain commas.


Packages built with make can often implement this by passing the -jn option to make.


files.new is used as a temporary file by dpkg-gencontrol and dpkg-distaddfile - they write a new version of files here before renaming it, to avoid leaving a corrupted copy if an error occurs.


For example, parts of the GNU build system work like this.


Having multiple copies of the same code in Ubuntu is inefficient, often creates either static linking or shared library conflicts, and, most importantly, increases the difficulty of handling security vulnerabilities in the duplicated code.


dpkg's internal databases are in a similar format.


The paragraphs are also sometimes referred to as stanzas.


It is customary to leave a space after the package name if a version number is specified.


This is the most often used setting, and is recommended for new packages that aren't Architecture: all.


This is a setting used for a minority of cases where the program is not portable. Generally, it should not be used for new packages.


In the past, people specified the full version number in the Standards-Version field, for example "". Since minor patch-level changes don't introduce new policy, it was thought it would be better to relax policy and only require the first 3 components to be specified, in this example "2.3.0". All four components may still be used if someone wishes to do so.


Alphanumerics are A-Za-z0-9 only.


One common use of ~ is for upstream pre-releases. For example, 1.0~beta1~svn1245 sorts earlier than 1.0~beta1, which sorts earlier than 1.0.


Completely empty lines will not be rendered as blank lines. Instead, they will cause the parser to think you're starting a whole new record in the control file, and will therefore likely abort with an error.


Current distribution names are:


This is the current "released" version of Debian GNU/Linux. Once the distribution is stable only security fixes and other major bug fixes are allowed. When changes are made to this distribution, the release number is increased (for example: 2.2r1 becomes 2.2r2 then 2.2r3, etc).


This distribution value refers to the developmental part of the Debian distribution tree. New packages, new upstream versions of packages and bug fixes go into the unstable directory tree. Download from this distribution at your own risk.


This distribution value refers to the testing part of the Debian distribution tree. It receives its packages from the unstable distribution after a short time lag to ensure that there are no major issues with the unstable packages. It is less prone to breakage than unstable, but still risky. It is not possible to upload packages directly to testing.


From time to time, the testing distribution enters a state of "code-freeze" in anticipation of release as a stable version. During this period of testing only fixes for existing or newly-discovered bugs will be allowed. The exact details of this stage are determined by the Release Manager.


The packages with this distribution value are deemed by their maintainers to be high risk. Oftentimes they represent early beta or developmental packages from various sources that the maintainers want people to try, but are not ready to be a part of the other parts of the Debian distribution tree. Download at your own risk.

You should list all distributions that the package should be installed into.

More information is available in the Debian Developer's Reference, section "The Debian archive".


Other urgency values are supported with configuration changes in the archive software but are not used in Ubuntu. The urgency affects how quickly a package will be considered for inclusion into the testing distribution and gives an indication of the importance of any fixes included in the upload. Emergency and critical are treated as synonymous.


A space after each comma is conventional.


That is, the parts which are not the .dsc.


This is so that if an error occurs, the user interrupts dpkg or some other unforeseen circumstance happens you don't leave the user with a badly-broken package when dpkg attempts to repeat the action.


Part of the problem is due to what is arguably a bug in dpkg.


Historical note: Truly ancient (pre-1997) versions of dpkg passed <unknown> (including the angle brackets) in this case. Even older ones did not pass a second argument at all, under any circumstance. Note that upgrades using such an old dpkg version are unlikely to work for other reasons, even if this old argument behavior is handled by your postinst script.


Replaces is a one way relationship -- you have to install the replacing package after the replaced package.


If you make "build-arch" or "binary-arch", you need Build-Depends. If you make "build-indep" or "binary-indep", you need Build-Depends and Build-Depends-Indep. If you make "build" or "binary", you need both.

There is no Build-Depends-Arch; this role is essentially met with Build-Depends. Anyone building the build-indep and binary-indep targets is basically assumed to be building the whole package anyway and so installs all build dependencies. The autobuilders use dpkg-buildpackage -B, which calls build (not build-arch, since it does not yet know how to check for its existence) and binary-arch.

The purpose of the original split, I recall, was so that the autobuilders wouldn't need to install extra packages needed only for the binary-indep targets. But without a build-arch/build-indep split, this didn't work, since most of the work is done in the build target, not in the binary target.


Since it is common place to install several versions of a package that just provides shared libraries, it is a good idea that the library package should not contain any extraneous non-versioned files, unless they happen to be in versioned directories.


The soname is the shared object name: it's the thing that has to match exactly between building an executable and running it for the dynamic linker to be able run the program. For example, if the soname of the library is libfoo.so.6, the library package would be called libfoo6.


The package management system requires the library to be placed before the symbolic link pointing to it in the .deb file. This is so that when dpkg comes to install the symlink (overwriting the previous symlink pointing at an older version of the library), the new shared library is already in place. In the past, this was achieved by creating the library in the temporary packaging directory before creating the symlink. Unfortunately, this was not always effective, since the building of the tar file in the .deb depended on the behavior of the underlying file system. Some file systems (such as reiserfs) reorder the files so that the order of creation is forgotten. Since version 1.7.0, dpkg reorders the files itself as necessary when building a package. Thus it is no longer important to concern oneself with the order of file creation.


These are currently


During install or upgrade, the preinst is called before the new files are installed, so calling "ldconfig" is pointless. The preinst of an existing package can also be called if an upgrade fails. However, this happens during the critical time when a shared libs may exist on-disk under a temporary name. Thus, it is dangerous and forbidden by current policy to call "ldconfig" at this time.

When a package is installed or upgraded, "postinst configure" runs after the new files are safely on-disk. Since it is perfectly safe to invoke ldconfig unconditionally in a postinst, it is OK for a package to simply put ldconfig in its postinst without checking the argument. The postinst can also be called to recover from a failed upgrade. This happens before any new files are unpacked, so there is no reason to call "ldconfig" at this point.

For a package that is being removed, prerm is called with all the files intact, so calling ldconfig is useless. The other calls to "prerm" happen in the case of upgrade at a time when all the files of the old package are on-disk, so again calling "ldconfig" is pointless.

postrm, on the other hand, is called with the "remove" argument just after the files are removed, so this is the proper time to call "ldconfig" to notify the system of the fact that the shared libraries from the package are removed. The postrm can be called at several other times. At the time of "postrm purge", "postrm abort-install", or "postrm abort-upgrade", calling "ldconfig" is useless because the shared lib files are not on-disk. However, when "postrm" is invoked with arguments "upgrade", "failed-upgrade", or "disappear", a shared lib may exist on-disk under a temporary filename.


For example, a package-name-config script or pkg-config configuration files.


Previously, ${Source-Version} was used, but its name was confusing and it has been deprecated since dpkg 1.13.19.


In the past, the shared libraries linked to were determined by calling ldd, but now objdump is used to do this. The only change this makes to package building is that dpkg-shlibdeps must also be run on shared libraries, whereas in the past this was unnecessary. The rest of this footnote explains the advantage that this method gives.

We say that a binary foo directly uses a library libbar if it is explicitly linked with that library (that is, it uses the flag -lbar during the linking stage). Other libraries that are needed by libbar are linked indirectly to foo, and the dynamic linker will load them automatically when it loads libbar. A package should depend on the libraries it directly uses, and the dependencies for those libraries should automatically pull in the other libraries.

Unfortunately, the ldd program shows both the directly and indirectly used libraries, meaning that the dependencies determined included both direct and indirect dependencies. The use of objdump avoids this problem by determining only the directly used libraries.

A good example of where this helps is the following. We could update libimlib with a new version that supports a new graphics format called dgf (but retaining the same major version number). If we used the old ldd method, every package that uses libimlib would need to be recompiled so it would also depend on libdgf or it wouldn't run due to missing symbols. However with the new system, packages using libimlib can rely on libimlib itself having the dependency on libdgf and so they would not need rebuilding.


An example may help here. Let us say that the source package foo generates two binary packages, libfoo2 and foo-runtime. When building the binary packages, the two packages are created in the directories debian/libfoo2 and debian/foo-runtime respectively. (debian/tmp could be used instead of one of these.) Since libfoo2 provides the libfoo shared library, it will require a shlibs file, which will be installed in debian/libfoo2/DEBIAN/shlibs, eventually to become /var/lib/dpkg/info/libfoo2.shlibs. Then when dpkg-shlibdeps is run on the executable debian/foo-runtime/usr/bin/foo-prog, it will examine the debian/libfoo2/DEBIAN/shlibs file to determine whether foo-prog's library dependencies are satisfied by any of the libraries provided by libfoo2. For this reason, dpkg-shlibdeps must only be run once all of the individual binary packages' shlibs files have been installed into the build directory.


If you are using debhelper, the dh_shlibdeps program will do this work for you. It will also correctly handle multi-binary packages.


dh_shlibdeps from the debhelper suite will automatically add this option if it knows it is processing a udeb.


This can be determined using the command

     objdump -p /usr/lib/libz.so.1.1.3 | grep SONAME


This is what dh_makeshlibs in the debhelper suite does. If your package also has a udeb that provides a shared library, dh_makeshlibs can automatically generate the udeb: lines if you specify the name of the udeb with the --add-udeb option.


For example, using the RAMRUN and RAMLOCK options in /etc/default/rcS.


If you are using GCC, -fPIC produces code with relocatable position independent code, which is required for most architectures to create a shared library, with i386 and perhaps some others where non position independent code is permitted in a shared library.

Position independent code may have a performance penalty, especially on i386. However, in most cases the speed penalty must be measured against the memory wasted on the few architectures where non position independent code is even possible.


Some of the reasons why this might be required is if the library contains hand crafted assembly code that is not relocatable, the speed penalty is excessive for compute intensive libs, and similar reasons.


Some of the reasons for linking static libraries with the -fPIC flag are if, for example, one needs a Perl API for a library that is under rapid development, and has an unstable API, so shared libraries are pointless at this phase of the library's development. In that case, since Perl needs a library with relocatable code, it may make sense to create a static library with relocatable code. Another reason cited is if you are distilling various libraries into a common shared library, like mklibs does in the Debian installer project.


You might also want to use the options --remove-section=.comment and --remove-section=.note on both shared libraries and executables, and --strip-debug on static libraries.


A common example are the so-called "plug-ins", internal shared objects that are dynamically loaded by programs using dlopen(3).


Although libtool is fully capable of linking against shared libraries which don't have .la files, as it is a mere shell script it can add considerably to the build time of a libtool-using package if that shell script has to derive all this information from first principles for each library every time it is linked. With the advent of libtool version 1.4 (and to a lesser extent libtool version 1.3), the .la files also store information about inter-library dependencies which cannot necessarily be derived after the .la file is deleted.


Single UNIX Specification, version 3, which is also IEEE 1003.1-2004 (POSIX), and is available on the World Wide Web from The Open Group after free registration.


These features are in widespread use in the Linux community and are implemented in all of bash, dash, and ksh, the most common shells users may wish to use as /bin/sh.


This notification could be done via a (low-priority) debconf message, or an echo (printf) statement.


Rationale: There are two problems with hard links. The first is that some editors break the link while editing one of the files, so that the two files may unwittingly become unlinked and different. The second is that dpkg might break the hard link while upgrading conffiles.


The traditional approach to log files has been to set up ad hoc log rotation schemes using simple shell scripts and cron. While this approach is highly customizable, it requires quite a lot of sysadmin work. Even though the original Ubuntu system helped a little by automatically installing a system which can be used as a template, this was deemed not enough.

The use of logrotate, a program developed by Red Hat, is better, as it centralizes log management. It has both a configuration file (/etc/logrotate.conf) and a directory where packages can drop their individual log rotation configurations (/etc/logrotate.d).


When a package is upgraded, and the owner or permissions of a file included in the package has changed, dpkg arranges for the ownership and permissions to be correctly set upon installation. However, this does not extend to directories; the permissions and ownership of directories already on the system does not change on install or upgrade of packages. This makes sense, since otherwise common directories like /usr would always be in flux. To correctly change permissions of a directory the package owns, explicit action is required, usually in the postinst script. Care must be taken to handle downgrades as well, in that case.


Ordinary files installed by dpkg (as opposed to conffiles and other similar objects) normally have their permissions reset to the distributed permissions when the package is reinstalled. However, the use of dpkg-statoverride overrides this default behavior. If you use this method, you should remember to describe dpkg-statoverride in the package documentation; being a relatively new addition to Debian, it is probably not yet well-known.


Currently, the strings are: i386 ia64 alpha amd64 armeb arm hppa m32r m68k mips mipsel powerpc ppc64 s390 s390x sh3 sh3eb sh4 sh4eb sparc darwin-i386 darwin-ia64 darwin-alpha darwin-amd64 darwin-armeb darwin-arm darwin-hppa darwin-m32r darwin-m68k darwin-mips darwin-mipsel darwin-powerpc darwin-ppc64 darwin-s390 darwin-s390x darwin-sh3 darwin-sh3eb darwin-sh4 darwin-sh4eb darwin-sparc freebsd-i386 freebsd-ia64 freebsd-alpha freebsd-amd64 freebsd-armeb freebsd-arm freebsd-hppa freebsd-m32r freebsd-m68k freebsd-mips freebsd-mipsel freebsd-powerpc freebsd-ppc64 freebsd-s390 freebsd-s390x freebsd-sh3 freebsd-sh3eb freebsd-sh4 freebsd-sh4eb freebsd-sparc kfreebsd-i386 kfreebsd-ia64 kfreebsd-alpha kfreebsd-amd64 kfreebsd-armeb kfreebsd-arm kfreebsd-hppa kfreebsd-m32r kfreebsd-m68k kfreebsd-mips kfreebsd-mipsel kfreebsd-powerpc kfreebsd-ppc64 kfreebsd-s390 kfreebsd-s390x kfreebsd-sh3 kfreebsd-sh3eb kfreebsd-sh4 kfreebsd-sh4eb kfreebsd-sparc knetbsd-i386 knetbsd-ia64 knetbsd-alpha knetbsd-amd64 knetbsd-armeb knetbsd-arm knetbsd-hppa knetbsd-m32r knetbsd-m68k knetbsd-mips knetbsd-mipsel knetbsd-powerpc knetbsd-ppc64 knetbsd-s390 knetbsd-s390x knetbsd-sh3 knetbsd-sh3eb knetbsd-sh4 knetbsd-sh4eb knetbsd-sparc netbsd-i386 netbsd-ia64 netbsd-alpha netbsd-amd64 netbsd-armeb netbsd-arm netbsd-hppa netbsd-m32r netbsd-m68k netbsd-mips netbsd-mipsel netbsd-powerpc netbsd-ppc64 netbsd-s390 netbsd-s390x netbsd-sh3 netbsd-sh3eb netbsd-sh4 netbsd-sh4eb netbsd-sparc openbsd-i386 openbsd-ia64 openbsd-alpha openbsd-amd64 openbsd-armeb openbsd-arm openbsd-hppa openbsd-m32r openbsd-m68k openbsd-mips openbsd-mipsel openbsd-powerpc openbsd-ppc64 openbsd-s390 openbsd-s390x openbsd-sh3 openbsd-sh3eb openbsd-sh4 openbsd-sh4eb openbsd-sparc hurd-i386 hurd-ia64 hurd-alpha hurd-amd64 hurd-armeb hurd-arm hurd-hppa hurd-m32r hurd-m68k hurd-mips hurd-mipsel hurd-powerpc hurd-ppc64 hurd-s390 hurd-s390x hurd-sh3 hurd-sh3eb hurd-sh4 hurd-sh4eb hurd-sparc


The Ubuntu base system already provides an editor and a pager program.


If it is not possible to establish both locks, the system shouldn't wait for the second lock to be established, but remove the first lock, wait a (random) time, and start over locking again.


You will need to depend on liblockfile1 (>>1.01) to use these functions.


There are two traditional permission schemes for mail spools: mode 600 with all mail delivery done by processes running as the destination user, or mode 660 and owned by group mail with mail delivery done by a process running as a system user in group mail. Historically, Debian required mode 660 mail spools to enable the latter model, but that model has become increasingly uncommon and the principle of least privilege indicates that mail systems that use the first model should use permissions of 600. If delivery to programs is permitted, it's easier to keep the mail system secure if the delivery agent runs as the destination user. Debian Policy therefore permits either scheme.


This implements current practice, and provides an actual policy for usage of the xserver virtual package which appears in the virtual packages list. In a nutshell, X servers that interface directly with the display and input hardware or via another subsystem (e.g., GGI) should provide xserver. Things like Xvfb, Xnest, and Xprt should not.


"New terminal window" does not necessarily mean a new top-level X window directly parented by the window manager; it could, if the terminal emulator application were so coded, be a new "view" in a multiple-document interface (MDI).


For the purposes of Ubuntu Policy, a "font for the X Window System" is one which is accessed via X protocol requests. Fonts for the Linux console, for PostScript renderer, or any other purpose, do not fit this definition. Any tool which makes such fonts available to the X Window System, however, must abide by this font policy.


This is because the X server may retrieve fonts from the local file system or over the network from an X font server; the Ubuntu package system is empowered to deal only with the local file system.


Note that this mechanism is not the same as using app-defaults; app-defaults are tied to the client binary on the local file system, whereas X resources are stored in the X server and affect all connecting clients.


These libraries used to be all symbolic links. However, with X11R7, /usr/include/X11 and /usr/lib/X11 are now real directories, and packages should ship their files here instead of in /usr/X11R6/{include,lib}/X11. x11-common (>= 1:7.0.0) is the package responsible for converting these symlinks into directories.


OSF/Motif and OpenMotif are collectively referred to as "Motif" in this policy document.


If you are using debhelper, the dh_icons program will do this work for you.


It is not very hard to write a man page. See the Man-Page-HOWTO, man(7), the examples created by debmake or dh_make, the helper programs help2man, or the directory /usr/share/doc/man-db/examples.


Supporting this in man often requires unreasonable processing time to find a manual page or to report that none exists, and moves knowledge into man's database that would be better left in the file system. This support is therefore deprecated and will cease to be present in the future.


man will automatically detect whether UTF-8 is in use. In future, all manual pages will be required to use UTF-8.


At the time of writing, Chinese and Portuguese are the main languages with such differences, so pt_BR, zh_CN, and zh_TW are all allowed.


The system administrator should be able to delete files in /usr/share/doc/ without causing any programs to break.


Please note that this does not override the section on changelog files below, so the file /usr/share/package/changelog.Debian.gz must refer to the changelog for the current version of package in question. In practice, this means that the sources of the target and the destination of the symlink must be the same (same source package and version).


At this phase of the transition, we no longer require a symbolic link in /usr/doc/. At a later point, policy shall change to make the symbolic links a bug.


The rationale: The important thing here is that HTML docs should be available in some package, not necessarily in the main binary package.


In particular, /usr/share/common-licenses/BSD, /usr/share/common-licenses/Apache-2.0, /usr/share/common-licenses/Artistic, /usr/share/common-licenses/GPL-2, /usr/share/common-licenses/GPL-3, /usr/share/common-licenses/LGPL-2, /usr/share/common-licenses/LGPL-2.1, /usr/share/common-licenses/LGPL-3, /usr/share/common-licenses/GFDL-1.2, and /usr/share/common-licenses/GFDL-1.3 respectively.


Rationale: People should not have to look in places for upstream changelogs merely because they are given different names or are distributed in HTML format.


dpkg is targeted primarily at Debian GNU/Linux and Ubuntu, but may work on or be ported to other systems.


This is so that the control file which is produced has the right permissions


They may be specified either in the locations in the source tree where they are created or in the locations in the temporary build tree where they are installed prior to binary package creation.


At the time of writing, an example for this was the xmms package, with Depends used for the xmms executable, Recommends for the plug-ins and Suggests for even more optional features provided by unzip.


This is not currently detected when building source packages, but only when extracting them.


Hard links may be permitted at some point in the future, but would require a fair amount of work.


Setgid directories are allowed.


Renaming a file is not treated specially - it is seen as the removal of the old file (which generates a warning, but is otherwise ignored), and the creation of the new one.

Ubuntu Policy Manual

version, 2009-06-19

The Debian Policy Mailing List
The Ubuntu Developers Mailing List