[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ 10 ] [ 11 ] [ 12 ] [ A ] [ B ] [ C ] [ D ] [ E ] [ F ] [ G ] [ next ]


Ubuntu Policy Manual
Chapter 10 - Files


10.1 Binaries

Two different packages must not install programs with different functionality but with the same filenames. (The case of two programs having the same functionality but different implementations is handled via "alternatives" or the "Conflicts" mechanism. See Maintainer Scripts, Section 3.9 and Conflicting binary packages - Conflicts, Section 7.4 respectively.) If this case happens, one of the programs must be renamed. The maintainers should report this to the ubuntu-devel mailing list and try to find a consensus about which program will have to be renamed. If a consensus cannot be reached, both programs must be renamed.

By default, when a package is being built, any binaries created should include debugging information, as well as being compiled with optimization. You should also turn on as many reasonable compilation warnings as possible; this makes life easier for porters, who can then look at build logs for possible problems. For the C programming language, this means the following compilation parameters should be used:

     CC = gcc
     CFLAGS = -O2 -g -Wall # sane warning options vary between programs
     LDFLAGS = # none
     INSTALL = install -s # (or use strip on the files in debian/tmp)

Note that by default all installed binaries should be stripped, either by using the -s flag to install, or by calling strip on the binaries after they have been copied into debian/tmp but before the tree is made into a package.

Although binaries in the build tree should be compiled with debugging information by default, it can often be difficult to debug programs if they are also subjected to compiler optimization. For this reason, it is recommended to support the standardized environment variable DEB_BUILD_OPTIONS (see debian/rules and DEB_BUILD_OPTIONS, Section 4.9.1). This variable can contain several flags to change how a package is compiled and built.

It is up to the package maintainer to decide what compilation options are best for the package. Certain binaries (such as computationally-intensive programs) will function better with certain flags (-O3, for example); feel free to use them. Please use good judgment here. Don't use flags for the sake of it; only use them if there is good reason to do so. Feel free to override the upstream author's ideas about which compilation options are best: they are often inappropriate for our environment.


10.2 Libraries

If the package is architecture: any, then the shared library compilation and linking flags must have -fPIC, or the package shall not build on some of the supported architectures[64]. Any exception to this rule must be discussed on the mailing list ubuntu-devel@lists.ubuntu.com, and a rough consensus obtained. The reasons for not compiling with -fPIC flag must be recorded in the file README.Debian, and care must be taken to either restrict the architecture or arrange for -fPIC to be used on architectures where it is required.[65]

As to the static libraries, the common case is not to have relocatable code, since there is no benefit, unless in specific cases; therefore the static version must not be compiled with the -fPIC flag. Any exception to this rule should be discussed on the mailing list ubuntu-devel@lists.ubuntu.com, and the reasons for compiling with the -fPIC flag must be recorded in the file README.Debian. [66]

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 be compiled twice, for the normal case.

You must specify the gcc option -D_REENTRANT when building a library (either static or shared) to make the library compatible with LinuxThreads.

Although not enforced by the build tools, shared libraries must be linked against all libraries that they use symbols from in the same way that binaries are. This ensures the correct functioning of the shlibs system and guarantees that all libraries can be safely opened with dlopen(). Packagers may wish to use the gcc option -Wl,-z,defs when building a shared library. Since this option enforces symbol resolution at build time, a missing library reference will be caught early as a fatal build error.

All installed shared libraries should be stripped with

     strip --strip-unneeded your-lib

(The option --strip-unneeded makes strip remove only the symbols which aren't needed for relocation processing.) Shared libraries can function perfectly well when stripped, since the symbols for dynamic linking are in a separate part of the ELF object file.[67]

Note that under some circumstances it may be useful to install a shared library unstripped, for example when building a separate package to support debugging.

Shared object files (often .so files) that are not public libraries, that is, they are not meant to be linked to by third party executables (binaries of other packages), should be installed in subdirectories of the /usr/lib directory. Such files are exempt from the rules that govern ordinary shared libraries, except that they must not be installed executable and should be stripped.[68]

Packages containing shared libraries that may be linked to by other packages' binaries, but which for some compelling reason can not be installed in /usr/lib directory, may install the shared library files in subdirectories of the /usr/lib directory, in which case they should arrange to add that directory in /etc/ld.so.conf in the package's post-installation script, and remove it in the package's post-removal script.

An ever increasing number of packages are using libtool to do their linking. The latest GNU libtools (>= 1.3a) can take advantage of the metadata in the installed libtool archive files (*.la files). The main advantage of libtool's .la files is that it allows libtool to store and subsequently access metadata with respect to the libraries it builds. libtool will search for those files, which contain a lot of useful information about a library (such as library dependency information for static linking). Also, they're essential for programs using libltdl.[69]

Packages that use libtool to create shared libraries should include the .la files in the -dev package, unless the package relies on libtool's libltdl library, in which case the .la files must go in the run-time library package.

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


10.3 Shared libraries

This section has moved to Shared libraries, Chapter 8.


10.4 Scripts

All command scripts, including the package maintainer scripts inside the package and used by dpkg, should have a #! line naming the shell to 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, the script name should not include an extension such as .sh or .pl that denotes the scripting language currently used to implement it.

Shell scripts (sh and bash) should almost certainly start with set -e so that errors are detected. Every script should use set -e or check the exit status of every command.

Scripts may assume that /bin/sh implements the SUSv3 Shell Command Language[70] plus the following additional features not mandated by SUSv3:[71]

If a shell script requires non-SUSv3 features from the shell interpreter other than those listed above, the appropriate shell must be specified in the first line of the script (e.g., #!/bin/bash) and the package must depend on the package providing the shell (unless the shell package is marked "Essential", as in the case of bash).

You may wish to restrict your script to SUSv3 features plus the above set when possible so that it may use /bin/sh as its interpreter. If your script works with dash (originally called ash), it probably complies with the above requirements, but if you are in doubt, use /bin/bash.

Perl scripts should check for errors when making any system calls, including open, print, close, rename and system.

csh and tcsh should be avoided as scripting languages. See Csh Programming Considered Harmful, one of the comp.unix.* FAQs, which can be found at http://www.faqs.org/faqs/unix-faq/shell/csh-whynot/. If an upstream package comes with csh scripts then you must make sure that they start with #!/bin/csh and make your package depend on the c-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 with the same name already exists.

The Ubuntu base system provides the tempfile and mktemp utilities for use by scripts for this purpose.


10.5 Symbolic links

In general, symbolic links within a top-level directory should be relative, and symbolic links pointing from one top-level directory into another should be absolute. (A top-level directory is a sub-directory of the root directory /.)

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

Note that when creating a relative link using ln it is not necessary for the target of the link to exist relative to the working directory you're running ln from, nor is it necessary to change directory to the directory where the link is to be made. Simply include the string that should appear as the target of the link (this will be a pathname relative to the directory in which the link resides) as the first argument to ln.

For example, in your Makefile or debian/rules, you can do things like:

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

A symbolic link pointing to a compressed file should always have the same file extension as the referenced file. (For example, if a file foo.gz is referenced by a symbolic link, the filename of the link has to end with ".gz" too, as in bar.gz.)


10.6 Device files

Packages must not include device files in the package file tree.

If a package needs any special device files that are not included in the base system, it must call MAKEDEV in the postinst script, after notifying the user[72].

Packages must not remove any device files in the postrm or any other script. This is left to the system administrator.

Ubuntu uses the serial devices /dev/ttyS*. Programs using the old /dev/cu* devices should be changed to use /dev/ttyS*.


10.7 Configuration files


10.7.1 Definitions

configuration file

A file that affects the operation of a program, or provides site- or host-specific information, or otherwise customizes the behavior of a program. Typically, configuration files are intended to be modified by the system administrator (if needed or desired) to conform to local policy or to provide more useful site-specific behavior.

conffile

A file listed in a package's conffiles file, and is treated specially by dpkg (see Details of configuration, Section 6.7).

The distinction between these two is important; they are not interchangeable concepts. Almost all conffiles are configuration files, but many configuration files are not conffiles.

As noted elsewhere, /etc/init.d scripts, /etc/default files, scripts installed in /etc/cron.{hourly,daily,weekly,monthly}, and cron configuration installed in /etc/cron.d must be treated as configuration files. In general, any script that embeds configuration information is de-facto a configuration file and should be treated as such.


10.7.2 Location

Any configuration files created or used by your package must reside in /etc. If there are several, consider creating a subdirectory of /etc named after your package.

If your package creates or uses configuration files outside of /etc, and it is not feasible to modify the package to use /etc directly, put the files in /etc and create symbolic links to those files from the location that the package requires.


10.7.3 Behavior

Configuration file handling must conform to the following behavior:

The easy way to achieve this behavior is to make the configuration file a conffile. This is appropriate only if it is possible to distribute a default version that will work for most installations, although some system administrators may choose to modify it. This implies that the default version will be part of the package distribution, and must not be modified by the maintainer scripts during installation (or at any other time).

In order to ensure that local changes are preserved correctly, no package may contain or make hard links to conffiles.[73]

The other way to do it is via the maintainer scripts. In this case, the configuration file must not be listed as a conffile and must not be part of the package distribution. If the existence of a file is required for the package to be sensibly configured it is the responsibility of the package maintainer to provide maintainer scripts which correctly create, update and maintain the file and remove it on purge. (See Package maintainer scripts and installation procedure, Chapter 6 for more information.) These scripts must be idempotent (i.e., must work correctly if dpkg needs to re-run them due to errors during installation or removal), must cope with all the variety of ways dpkg can call maintainer scripts, must not overwrite or otherwise mangle the user's configuration without asking, must not ask unnecessary questions (particularly during upgrades), and must otherwise be good citizens.

The scripts are not required to configure every possible option for the package, but only those necessary to get the package running on a given system. Ideally the sysadmin should not have to do any configuration other than that done (semi-)automatically by the postinst script.

A common practice is to create a script called package-configure and have the package's postinst call it if and only if the configuration file does not already exist. In certain cases it is useful for there to be an example or template file which the maintainer scripts use. Such files should be in /usr/share/package or /usr/lib/package (depending on whether they are architecture-independent or not). There should be symbolic links to them from /usr/share/doc/package/examples if they are examples, and should be perfectly ordinary dpkg-handled files (not configuration files).

These two styles of configuration file handling must not be mixed, for that way lies madness: dpkg will ask about overwriting the file every time the package is upgraded.


10.7.4 Sharing configuration files

Packages which specify the same file as a conffile must be tagged as conflicting with each other. (This is an instance of the general rule about not sharing files. Note that neither alternatives nor diversions are likely to be appropriate in this case; in particular, dpkg does not handle diverted conffiles well.)

The maintainer scripts must not alter a conffile of any package, including the one the scripts belong to.

If two or more packages use the same configuration file and it is reasonable for both to be installed at the same time, one of these packages must be defined as owner of the configuration file, i.e., it will be the package which handles that file as a configuration file. Other packages that use the configuration file must depend on the owning package if they require the configuration file to operate. If the other package will use the configuration file if present, but is capable of operating without it, no dependency need be declared.

If it is desirable for two or more related packages to share a configuration file and for all of the related packages to be able to modify that configuration file, then the following should be done:

  • One of the related packages (the "owning" package) will manage the configuration file with maintainer scripts as described in the previous section.

  • The owning package should also provide a program that the other packages may use to modify the configuration file.

  • The related packages must use the provided program to make any desired modifications to the configuration file. They should either depend on the core package to guarantee that the configuration modifier program is available or accept gracefully that they cannot modify the configuration file if it is not. (This is in addition to the fact that the configuration file may not even be present in the latter scenario.)

  • Sometimes it's appropriate to create a new package which provides the basic infrastructure for the other packages and which manages the shared configuration files. (The sgml-base package is a good example.)


    10.7.5 User configuration files ("dotfiles")

    The files in /etc/skel will automatically be copied into new user accounts by adduser. No other program should reference the files in /etc/skel.

    Therefore, if a program needs a dotfile to exist in advance in $HOME to work sensibly, that dotfile should be installed in /etc/skel and treated as a configuration file.

    However, programs that require dotfiles in order to operate sensibly are a bad thing, unless they do create the dotfiles themselves automatically.

    Furthermore, programs should be configured by the Ubuntu default installation to behave as closely to the upstream default behavior as possible.

    Therefore, if a program in a Ubuntu package needs to be configured in some way in order to operate sensibly, that should be done using a site-wide configuration file placed in /etc. Only if the program doesn't support a site-wide default configuration and the package maintainer doesn't have time to add it may a default per-user file be placed in /etc/skel.

    /etc/skel should be as empty as we can make it. This is particularly true because there is no easy (or necessarily desirable) mechanism for ensuring that the appropriate dotfiles are copied into the accounts of existing users when a package is installed.


    10.8 Log files

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

    Log files must be rotated occasionally so that they don't grow indefinitely; the best way to do this is to drop a log rotation configuration file into the directory /etc/logrotate.d and use the facilities provided by logrotate.[74] Here is a good example for a logrotate config file (for more information see logrotate(8)):

         /var/log/foo/*.log {
         rotate 12
         weekly
         compress
         postrotate
         /etc/init.d/foo force-reload
         endscript
         }
    

    This rotates all files under /var/log/foo, saves 12 compressed generations, and forces the daemon to reload its configuration information after the log rotation.

    Log files should be removed when the package is purged (but not when it is only removed). This should be done by the postrm script when it is called with the argument purge (see Details of removal and/or configuration purging, Section 6.8).


    10.9 Permissions and owners

    The rules in this section are guidelines for general use. If necessary you may deviate from the details below. However, if you do so you must make sure that what is done is secure and you should try to be as consistent as possible with the rest of the system. You should probably also discuss it on ubuntu-devel first.

    Files should be owned by root:root, and made writable only by the owner and universally readable (and executable, if appropriate), that is mode 644 or 755.

    Directories should be mode 755 or (for group-writability) mode 2775. The ownership of the directory should be consistent with its mode: if a directory is mode 2775, it should be owned by the group that needs write access to it.[75]

    Setuid and setgid executables should be mode 4755 or 2755 respectively, and owned by the appropriate user or group. They should not be made unreadable (modes like 4711 or 2711 or even 4111); doing so achieves no extra security, because anyone can find the binary in the freely available Ubuntu package; it is merely inconvenient. For the same reason you should not restrict read or execute permissions on non-set-id executables.

    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 to which they are set-id, and by the group which should be allowed to execute them. They should have mode 4754; again there is no point in making them unreadable to those users who must not be allowed to execute them.

    It is possible to arrange that the system administrator can reconfigure the package to correspond to their local security policy by changing the permissions on a binary: they can do this by using dpkg-statoverride, as described below.[76] Another method you should consider is to create a group for people allowed to use the program(s) and make any setuid executables executable only by that group.

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

    If you need a statically allocated id, you must ask for a user or group id from the base-passwd maintainer, and must not release the package until you have been allocated one. Once you have been allocated one you must either make the package depend on a version of the base-passwd package with the id present in /etc/passwd or /etc/group, or arrange for your package to create the user or group itself with the correct id (using adduser) in its preinst or postinst. (Doing it in the postinst is to be preferred if it is possible, otherwise a pre-dependency will be needed on the adduser package.)

    On the other hand, the program might be able to determine the uid or gid from the user or group name at runtime, so that a dynamically allocated id can be used. In this case you should choose an appropriate user or group name, discussing this on ubuntu-devel and checking with the base-passwd maintainer that it is unique and that they do not wish you to use a statically allocated id instead. When this has been checked you must arrange for your package to create the user or group if necessary using adduser in the preinst or postinst script (again, the latter is to be preferred if it is possible).

    Note that changing the numeric value of an id associated with a name is very difficult, and involves searching the file system for all appropriate files. You need to think carefully whether a static or dynamic id is required, since changing your mind later will cause problems.


    10.9.1 The use of dpkg-statoverride

    This section is not intended as policy, but as a description of the use of dpkg-statoverride.

    If a system administrator wishes to have a file (or directory or other such thing) installed with owner and permissions different from those in the distributed Ubuntu package, they can use the dpkg-statoverride program to instruct dpkg to use the different settings every time the file is installed. Thus the package maintainer should distribute the files with their normal permissions, and leave it for the system administrator to make any desired changes. For example, a daemon which is normally required to be setuid root, but in certain situations could be used without being setuid, should be installed setuid in the .deb. Then the local system administrator can change this if they wish. If there are two standard ways of doing it, the package maintainer can use debconf to find out the preference, and call dpkg-statoverride in the maintainer script if necessary to accommodate the system administrator's choice. Care must be taken during upgrades to not override an existing setting.

    Given the above, dpkg-statoverride is essentially a tool for system administrators and would not normally be needed in the maintainer scripts. There is one type of situation, though, where calls to dpkg-statoverride would be needed in the maintainer scripts, and that involves packages which use dynamically allocated user or group ids. In such a situation, something like the following idiom can be very helpful in the package's postinst, where sysuser is a dynamically allocated id:

         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
           fi
         done
    

    The corresponding dpkg-statoverride --remove calls can then be made unconditionally when the package is purged.


    [ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ 10 ] [ 11 ] [ 12 ] [ A ] [ B ] [ C ] [ D ] [ E ] [ F ] [ G ] [ next ]


    Ubuntu Policy Manual

    version 3.8.2.0ubuntu1, 2009-06-19

    The Debian Policy Mailing List
    The Ubuntu Developers Mailing List