10.1.Binaries

Two different packages must not install programs with differentfunctionality but with the same filenames. This also applies when theyare installed into different directories on the default (user or root)PATH. (The case of two programshaving the same functionality but different implementations is handledvia “alternatives” or the “Conflicts” mechanism. SeeMaintainer Scripts andConflicting binary packages - Conflicts respectively.) If this case happens,one of the programs must be renamed. The maintainers should report thisto thedebian-devel mailing list and try to find a consensus aboutwhich program will have to be renamed. If a consensus cannot be reached,both programs must be renamed.

There is an exception to the above rules for/usr/games: packages thatalready install programs to/usr/games, where another package installs aprogram of the same with different functionality to a different directory onthe defaultPATH, may continue to do so. However, packages must notinstall any newly conflicting programs to/usr/games, and packages alreadydoing so are encouraged to move these programs to non-conflicting names.

Packages must not install files to paths whose first component is a namedirectly under the file system root and which is a symbolic link to adirectory of the same name under/usr. That is, packages must not installfiles to paths matching the glob patterns/bin/*,/lib/*,/lib*/*and/sbin/*. The base-files package is an exception, for it installsaliasing symbolic links from/bin to/usr/bin,/lib to/usr/lib, et cetera. This restriction is necessary to avoid triggeringundefined behaviour indpkg.

Packages may assume that/bin,/lib and/sbin are always symboliclinks such that files under/usr/bin,/usr/lib and/usr/sbin arealways accessible via these aliases.

Binary executables must not be statically linked with the GNU C library,since this prevents the binary from benefiting from fixes andimprovements to the C library without being rebuilt and complicatessecurity updates. This requirement may be relaxed for binary executableswhose intended purpose is to diagnose and fix the system in situationswhere the GNU C library may not be usable (such as system recoveryshells or utilities like ldconfig) or for binary executables where thesecurity benefits of static linking outweigh the drawbacks.

By default, when a package is being built, any binaries created shouldinclude debugging information, as well as being compiled withoptimization. You should also turn on as many reasonable compilationwarnings as possible (seeMain building script: debian/rules). For the C programminglanguage, this means the following compilation parameters should beused:

CC=gccCFLAGS=-O2-g-Wall# sane warning options vary between programsLDFLAGS=# none

By default all installed binaries should be stripped by calling

strip--strip-unneeded--remove-section=.comment--remove-section=.notebinaries

on the binaries after they have been copied intodebian/tmp butbefore the tree is made into a package.

It is not recommended to strip binaries by passing the-s flag toinstall, because this fails to remove .comment and .note sections,and also prevents the automatic creation of dbgsym binary packages bytools likedh_strip.

Although binaries in the build tree should be compiled with debugginginformation by default, it can often be difficult to debug programs ifthey are also subjected to compiler optimization. For this reason, it isrecommended to support the standardized environment variableDEB_BUILD_OPTIONS (seedebian/rules and DEB_BUILD_OPTIONS).This variable can contain several flags to change how a package iscompiled and built.

It is up to the package maintainer to decide what compilation optionsare best for the package. Certain binaries (such ascomputationally-intensive programs) will function better with certainflags (-O3, for example); feel free to use them. Please use goodjudgment here. Don’t use flags for the sake of it; only use them ifthere is good reason to do so. Feel free to override the upstreamauthor’s ideas about which compilation options are best: they are ofteninappropriate for our environment.

10.2.Libraries

If the package isarchitecture: any, then the shared librarycompilation and linking flags must have-fPIC, or the package shallnot build on some of the supported architectures.[1] Any exceptionto this rule must be discussed on the mailing listdebian-devel@lists.debian.org, and a rough consensus obtained. Thereasons for not compiling with-fPIC flag must be recorded in thefileREADME.Debian, and care must be taken to either restrict thearchitecture or arrange for-fPIC to be used on architectures whereit is required.[2]

As to the static libraries, the common case is not to have relocatablecode, since there is no benefit, unless in specific cases; therefore thestatic version must not be compiled with the-fPIC flag. Anyexception to this rule should be discussed on the mailing listdebian-devel@lists.debian.org, and the reasons for compiling with the-fPIC flag must be recorded in the fileREADME.Debian.[3]

In other words, if both a shared and a static library is being built,each source unit (*.c, for example, for C files) will need to becompiled twice, for the normal case.

Libraries should be built with threading support and to be thread-safeif the library supports this.

Although not enforced by the build tools, shared libraries must belinked against all libraries that they use symbols from in the same waythat binaries are. This ensures the correct functioning of thesymbols andshlibs systems and guarantees that alllibraries can be safely opened withdlopen(). Packagers may wish touse the gcc option-Wl,-z,defs when building a shared library. Sincethis option enforces symbol resolution at build time, a missing libraryreference will be caught early as a fatal build error.

All installed shared libraries should be stripped with

strip--strip-unneeded--remove-section=.comment--remove-section=.noteyour-lib

(The option--strip-unneeded makesstrip remove only the symbolswhich aren’t needed for relocation processing.) Shared libraries canfunction perfectly well when stripped, since the symbols for dynamiclinking are in a separate part of the ELF object file.[4]

Note that under some circumstances it may be useful to install a sharedlibrary unstripped, for example when building a separate package tosupport debugging. The debhelperdh_strip tool can create suchpackages automatically.

Shared object files (often.so files) that are not publiclibraries, that is, they are not meant to be linked to by third partyexecutables (binaries of other packages), should be installed insubdirectories of the/usr/lib or/usr/lib/triplet directories(see the FHS for a definition). Such files are exempt from the rulesthat govern ordinary shared libraries, except that they must not beinstalled executable and should be stripped.[5]

Packages that uselibtool to create and install their sharedlibraries install a file containing additional metadata (ending in.la) alongside the library. For public libraries intended for use byother packages, these files normally should not be included in theDebian package, since the information they include is not necessary tolink with the shared library on Debian and can add unnecessaryadditional dependencies to other programs or libraries.[6] If the.la file is required for that library (if, for instance, it’s loadedvialibltdl in a way that requires that meta-information), thedependency_libs setting in the.la file should normally be setto the empty string. If the shared library development package hashistorically included the.la, it must be retained in thedevelopment package (withdependency_libs emptied) until alllibraries that depend on it have removed or emptieddependency_libsin their.la files to prevent linking with those other librariesusinglibtool from failing.

If the.la must be included, it should be included in thedevelopment (-dev) package, unless the library will be loaded bylibtool’slibltdl library. If it is intended for use withlibltdl, the.la files must go in the run-time library package.

These requirements for handling of.la files do not apply toloadable modules or libraries not installed in directories searched bydefault by the dynamic linker. Packages installing loadable modules willfrequently need to install the.la files alongside the modules sothat they can be loaded bylibltdl.dependency_libs does notneed to be modified for libraries or modules that are not installed indirectories searched by the dynamic linker by default and not intendedfor use by other packages.

You must make sure that you use only released versions of sharedlibraries to build your packages; otherwise other users will not be ableto run your binaries properly. Producing source packages that depend onunreleased compilers is also usually a bad idea.

10.3.Shared libraries

This section has moved toShared libraries.

10.4.Scripts

All command scripts, including the package maintainer scripts inside thepackage and used bydpkg, should have a#! line naming the shellto be used to interpret them.

In the case of Perl scripts this should be#!/usr/bin/perl.

When scripts are installed into a directory in the system PATH, thescript name should not include an extension such as.sh or.plthat denotes the scripting language currently used to implement it.

Shell scripts (sh andbash) other thaninit.d scripts shouldalmost certainly start withset-e so that errors are detected.init.d scripts are something of a special case, due to howfrequently they need to call commands that are allowed to fail, and itmay instead be easier to check the exit status of commands directly. SeeWriting the scripts for more information about writinginit.d scripts.

Every script should useset-e or check the exit status ofeverycommand.

Scripts may assume that/bin/sh implements the POSIX.1-2017 Shell CommandLanguage[7] plus the following additional features not mandated byPOSIX.1-2017..[8]

• echo-n, if implemented as a shell built-in, must not generate anewline.

• test, if implemented as a shell built-in, must support-a and-o as binary logical operators.

• local to create a scoped variable must be supported, includinglisting multiple variables in a single local command and assigning avalue to a variable at the same time as localizing it.local mayor may not preserve the variable value from an outer scope if noassignment is present. Uses such as:

  fname(){localabc=deltad# ... use a, b, c, d ...}

  must be supported and must set the value ofc todelta.

• The XSI extension tokill allowingkill-signal, where signalis either the name of a signal or one of the numeric signals listedin the XSI extension (0, 1, 2, 3, 6, 9, 14, and 15), must besupported ifkill is implemented as a shell built-in.

• The XSI extension totrap allowing numeric signals must besupported. In addition to the signal numbers listed in the extension,which are the same as forkill above, 13 (SIGPIPE) must beallowed.

If a shell script requires non-POSIX.1-2017 features from the shell interpreterother than those listed above, the appropriate shell must be specifiedin the first line of the script (e.g.,#!/bin/bash) and the packagemust depend on the package providing the shell (unless the shell packageis marked “Essential”, as in the case ofbash).

You may wish to restrict your script to POSIX.1-2017 features plus the aboveset when possible so that it may use/bin/sh as its interpreter.Checking your script withcheckbashisms from the devscripts packageor running your script with an alternate shell such asposh may helpuncover violations of the above requirements. If in doubt whether ascript complies with these requirements, use/bin/bash.

Perl scripts should check for errors when making any system calls,includingopen,print,close,rename andsystem.

csh andtcsh should be avoided as scripting languages. SeeCshProgramming Considered Harmful, one of thecomp.unix.* FAQs, whichcan be found athttp://www.faqs.org/faqs/unix-faq/shell/csh-whynot/. Ifan upstream package comes withcsh scripts then you must make surethat they start with#!/bin/csh and make your package depend on thec-shell virtual package.

Any scripts which create files in world-writeable directories (e.g., in/tmp) must use a mechanism which will fail atomically if a file withthe same name already exists.

The Debian base system provides thetempfile andmktemputilities for use by scripts for this purpose.

10.5.Symbolic links

In general, symbolic links within a top-level directory should berelative, and symbolic links pointing from one top-level directory to orinto another should be absolute. (A top-level directory is asub-directory of the root directory/.) For example, a symbolic linkfrom/usr/lib/foo to/usr/share/bar should be relative(../share/bar), but a symbolic link from/var/run to/runshould be absolute.[9] Symbolic links must not traverse above theroot directory.

In addition, symbolic links should be specified as short as possible,i.e., link targets likefoo/../bar are deprecated.

Note that when creating a relative link usingln it is not necessaryfor the target of the link to exist relative to the working directoryyou’re runningln from, nor is it necessary to change directory tothe directory where the link is to be made. Simply include the stringthat should appear as the target of the link (this will be a pathnamerelative to the directory in which the link resides) as the firstargument toln.

For example, in yourMakefile ordebian/rules, you can do thingslike:

ln -fs gcc $(prefix)/bin/ccln -fs gcc debian/tmp/usr/bin/ccln -fs ../sbin/sendmail $(prefix)/bin/runqln -fs ../sbin/sendmail debian/tmp/usr/bin/runq

A symbolic link pointing to a compressed file (in the sense that it ismeant to be uncompressed withunzip orzless etc.) should alwayshave the same file extension as the referenced file. (For example, if afilefoo.gz is referenced by a symbolic link, the filename of thelink has to end with “.gz” too, as inbar.gz.)

10.6.Device files

Packages must not include device files or named pipes in the packagefile tree.

Debian packages should assume that device files in/dev aredynamically managed by the kernel or some other system facility and donot have to be explicitly created or managed by the package. Debianpackages other than those whose purpose is to manage the/dev devicefile tree must not attempt to create or remove device files in/devwhen a dynamic device management facility is in use.

If named pipes or device files outside of/dev are required by apackage, they should normally be created when necessary by the programsin the package, by init scripts or systemd unit files, or by similaron-demand mechanisms. If such files need to be created during packageinstallation, they must be created in thepostinst maintainer script[10] and removed in either theprerm or thepostrm maintainerscript.

10.7.Configuration files

10.8.Log files

Log files should usually be named/var/log/package.log. If you havemany log files, or need a separate directory for permission reasons(/var/log is writable only byroot), you should usually create adirectory named/var/log/package and place your log files there.

Log files must be rotated occasionally so that they don’t growindefinitely. The best way to do this is to install a log rotationconfiguration file in the directory/etc/logrotate.d, normally named/etc/logrotate.d/package, and use the facilities provided bylogrotate.[13] Here is a good example for a logrotate config file(for more information seelogrotate(8)):

/var/log/foo/*.log{rotate12weeklycompressmissingokpostrotatestart-stop-daemon-K-p/var/run/foo.pid-sHUP-x/usr/sbin/foo-qendscript}

This rotates all files under/var/log/foo, saves 12 compressedgenerations, and tells the daemon to reopen its log files after the logrotation. It skips this log rotation (viamissingok) if no such logfile is present, which avoids errors if the package is removed but notpurged.

Log files should be removed when the package is purged (but not when itis only removed). This should be done by thepostrm script when itis called with the argumentpurge (seeDetails of removal and/or configuration purging).

10.9.Locale files

The directory/usr/share/locale/ contains localization files fordifferent locales.

Packages should not require the existence of any files in/usr/share/locale/ in order to function in aC orC.UTF-8locale.

10.10.Permissions and owners

The rules in this section are guidelines for general use. If necessaryyou may deviate from the details below. However, if you do so you mustmake sure that what is done is secure and you should try to be asconsistent as possible with the rest of the system. You are alsoencouraged to discuss it ondebian-devel first.

Files should be owned byroot:root, and made writable only by theowner and universally readable (and executable, if appropriate), that ismode 644 or 755.

Directories should be mode 755 or (for group-writability) mode 2775. Theownership of the directory should be consistent with its mode: if adirectory is mode 2775, it should be owned by the group that needs writeaccess to it.[14]

Control information files should be owned byroot:root and eithermode 644 (for most files) or mode 755 (for executables such asmaintainer scripts).

Setuid and setgid executables should be mode 4755 or 2755 respectively,and owned by the appropriate user or group. They should not be madeunreadable (modes like 4711 or 2711 or even 4111); doing so achieves noextra security, because anyone can find the binary in the freelyavailable Debian package; it is merely inconvenient. For the same reasonyou should not restrict read or execute permissions on non-set-idexecutables.

Some setuid programs need to be restricted to particular sets of users,using file permissions. In this case they should be owned by the uid towhich they are set-id, and by the group which should be allowed toexecute them. They should have mode 4754; again there is no point inmaking them unreadable to those users who must not be allowed to executethem.

It is possible to arrange that the system administrator can reconfigurethe package to correspond to their local security policy by changing thepermissions on a binary: they can do this by usingdpkg-statoverride, as described below.[15] Another method youshould consider is to create a group for people allowed to use theprogram(s) and make any setuid executables executable only by thatgroup.

If you need to create a new user or group for your package there are twopossibilities. Firstly, you may need to make some files in the binarypackage be owned by this user or group, or you may need to compile theuser or group id (rather than just the name) into the binary (thoughthis latter should be avoided if possible, as in this case you need astatically allocated id).

If you need a statically allocated id, you must ask for a user or groupid from thebase-passwd maintainer, and must not release the packageuntil you have been allocated one. Once you have been allocated one youmust either make the package depend on a version of thebase-passwdpackage with the id present in/etc/passwd or/etc/group, orarrange for your package to create the user or group itself with thecorrect id (usingadduser) in itspreinst orpostinst.(Doing it in thepostinst is to be preferred if it is possible,otherwise a pre-dependency will be needed on theadduser package.)

On the other hand, the program might be able to determine the uid or gidfrom the user or group name at runtime, so that a dynamically allocatedid can be used. In this case you should choose an appropriate user orgroup name, discussing this ondebian-devel and checking that it isunique. When this has been checked you must arrange for your package tocreate the user or group if necessary usingadduser in thepreinst orpostinst script (again, the latter is to be preferredif it is possible).

Note that changing the numeric value of an id associated with a name isvery difficult, and involves searching the file system for allappropriate files. You need to think carefully whether a static ordynamic id is required, since changing your mind later will causeproblems.

for i in /usr/bin/foo /usr/sbin/bar; do    # only do something when no setting exists    if ! dpkg-statoverride --list $i >/dev/null 2>&1; then        #include: debconf processing, question about foo and bar        if [ "$RET" = "true" ] ; then            dpkg-statoverride --update --add sysuser root 4755 $i        fi    fidone

for i in /usr/bin/foo /usr/sbin/bar; do    if dpkg-statoverride --list $i >/dev/null 2>&1; then        dpkg-statoverride --remove $i    fidone

10.11.File names

The name of the files installed by binary packages in the system PATH(namely/bin,/sbin,/usr/bin,/usr/sbin and/usr/games) must be encoded in ASCII.

The name of the files and directories installed by binary packagesoutside the system PATH must be encoded in UTF-8 and should berestricted to ASCII when it is possible to do so.

If you are using GCC,-fPIC produces code with relocatableposition independent code, which is required for most architecturesto create a shared library, with i386 and perhaps some others wherenon position independent code is permitted in a shared library.

Position independent code may have a performance penalty, especiallyoni386. However, in most cases the speed penalty must bemeasured against the memory wasted on the few architectures where nonposition independent code is even possible.

Some of the reasons why this might be required is if the librarycontains hand crafted assembly code that is not relocatable, thespeed penalty is excessive for compute intensive libs, and similarreasons.

Some of the reasons for linking static libraries with the-fPICflag are if, for example, one needs a Perl API for a library that isunder rapid development, and has an unstable API, so shared librariesare pointless at this phase of the library’s development. In thatcase, since Perl needs a library with relocatable code, it may makesense to create a static library with relocatable code. Anotherreason cited is if you are distilling various libraries into a commonshared library, likemklibs does in the Debian installer project.

You might want to replace--strip-unneeded with--strip-debug for static libraries, as dh_strip does. Whenstripping static libraries, you should also pass--enable-deterministic-archives to ensure that your packagebuild is reproducible.

A common example are the so-called “plug-ins”, internal shared objectsthat are dynamically loaded by programs usingdlopen(3).

These files store, among other things, all libraries on which thatshared library depends. Unfortunately, if the.la file is presentand contains that dependency information, usinglibtool whenlinking against that library will cause the resulting program orlibrary to be linked against those dependencies as well, even if thisis unnecessary. This can create unneeded dependencies on sharedlibrary packages that would otherwise be hidden behind the libraryABI, and can make library transitions to new SONAMEs unnecessarilycomplicated and difficult to manage.

The Open Group Base Specifications Issue 7, 2018 Edition, which isalso known as POSIX.1-2017 and as IEEE Std 1003.1-2017 and isavailable on the World Wide Web fromThe Open Group.

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

This is necessary to allow top-level directories to be symlinks. Iflinking/var/run to/run were done with the relative symboliclink../run, but/var were a symbolic link to/srv/disk1,the symbolic link would point to/srv/run rather than theintended target.

It’s better to usemkfifo rather thanmknod to create namedpipes to avoid false positives from automated checks for packagesincorrectly creating device files.

Thedpkg-maintscript-helper tool, available from the dpkgpackage, can help for this task.

Rationale: There are two problems with hard links. The first is thatsome editors break the link while editing one of the files, so thatthe two files may unwittingly become unlinked and different. Thesecond is thatdpkg might break the hard link while upgradingconffiles.

The traditional approach to log files has been to set upad hoc logrotation schemes using simple shell scripts and cron. While thisapproach is highly customizable, it requires quite a lot of sysadminwork. Even though the original Debian system helped a little byautomatically installing a system which can be used as a template,this was deemed not enough.

The use oflogrotate, 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 droptheir individual log rotation configurations (/etc/logrotate.d).

When a package is upgraded, and the owner or permissions of a fileincluded in the package has changed, dpkg arranges for the ownershipand permissions to be correctly set upon installation. However, thisdoes not extend to directories; the permissions and ownership ofdirectories already on the system does not change on install orupgrade of packages. This makes sense, since otherwise commondirectories like/usr would always be in flux. To correctlychange permissions of a directory the package owns, explicit actionis required, usually in thepostinst script. Care must be takento handle downgrades as well, in that case.

Ordinary files installed bydpkg (as opposed toconffilesand other similar objects) normally have their permissions reset tothe distributed permissions when the package is reinstalled. However,the use ofdpkg-statoverride overrides this default behavior.