9 Two different packages must not install programs with different
10 functionality but with the same filenames. (The case of two programs
11 having the same functionality but different implementations is handled
12 via "alternatives" or the "Conflicts" mechanism. See
13 :ref:`s-maintscripts` and
14 :ref:`s-conflicts` respectively.) If this case happens,
15 one of the programs must be renamed. The maintainers should report this
16 to the ``debian-devel`` mailing list and try to find a consensus about
17 which program will have to be renamed. If a consensus cannot be reached,
18 *both* programs must be renamed.
20 To support merged-\ ``/usr`` systems, packages must not install files in
21 both ``/path`` and ``/usr/path``. For example, a package may not install
22 both ``/bin/example`` and ``/usr/bin/example``.
24 If a file is moved between ``/path`` and ``/usr/path`` in revisions of a
25 Debian package, and a compatibility symlink at the old path is needed,
26 the symlink must be managed in a way that will not break when ``/path``
27 and ``/usr/path`` are the same underlying directory due to symlinks or
30 Binary executables must not be statically linked with the GNU C library,
31 since this prevents the binary from benefiting from fixes and
32 improvements to the C library without being rebuilt and complicates
33 security updates. This requirement may be relaxed for binary executables
34 whose intended purpose is to diagnose and fix the system in situations
35 where the GNU C library may not be usable (such as system recovery
36 shells or utilities like ldconfig) or for binary executables where the
37 security benefits of static linking outweigh the drawbacks.
39 By default, when a package is being built, any binaries created should
40 include debugging information, as well as being compiled with
41 optimization. You should also turn on as many reasonable compilation
42 warnings as possible; this makes life easier for porters, who can then
43 look at build logs for possible problems. For the C programming
44 language, this means the following compilation parameters should be
50 CFLAGS = -O2 -g -Wall # sane warning options vary between programs
52 INSTALL = install -s # (or use strip on the files in debian/tmp)
54 Note that by default all installed binaries should be stripped, either
55 by using the ``-s`` flag to ``install``, or by calling ``strip`` on the
56 binaries after they have been copied into ``debian/tmp`` but before the
57 tree is made into a package.
59 Although binaries in the build tree should be compiled with debugging
60 information by default, it can often be difficult to debug programs if
61 they are also subjected to compiler optimization. For this reason, it is
62 recommended to support the standardized environment variable
63 ``DEB_BUILD_OPTIONS`` (see :ref:`s-debianrules-options`).
64 This variable can contain several flags to change how a package is
67 It is up to the package maintainer to decide what compilation options
68 are best for the package. Certain binaries (such as
69 computationally-intensive programs) will function better with certain
70 flags (``-O3``, for example); feel free to use them. Please use good
71 judgment here. Don't use flags for the sake of it; only use them if
72 there is good reason to do so. Feel free to override the upstream
73 author's ideas about which compilation options are best: they are often
74 inappropriate for our environment.
81 If the package is **architecture: any**, then the shared library
82 compilation and linking flags must have ``-fPIC``, or the package shall
83 not build on some of the supported architectures. [#]_ Any exception
84 to this rule must be discussed on the mailing list
85 *debian-devel@lists.debian.org*, and a rough consensus obtained. The
86 reasons for not compiling with ``-fPIC`` flag must be recorded in the
87 file ``README.Debian``, and care must be taken to either restrict the
88 architecture or arrange for ``-fPIC`` to be used on architectures where
91 As to the static libraries, the common case is not to have relocatable
92 code, since there is no benefit, unless in specific cases; therefore the
93 static version must not be compiled with the ``-fPIC`` flag. Any
94 exception to this rule should be discussed on the mailing list
95 *debian-devel@lists.debian.org*, and the reasons for compiling with the
96 ``-fPIC`` flag must be recorded in the file ``README.Debian``. [#]_
98 In other words, if both a shared and a static library is being built,
99 each source unit (``*.c``, for example, for C files) will need to be
100 compiled twice, for the normal case.
102 Libraries should be built with threading support and to be thread-safe
103 if the library supports this.
105 Although not enforced by the build tools, shared libraries must be
106 linked against all libraries that they use symbols from in the same way
107 that binaries are. This ensures the correct functioning of the
108 :ref:`symbols <s-sharedlibs-symbols>` and :ref:`shlibs <s-sharedlibs-shlibdeps>` systems and guarantees that all
109 libraries can be safely opened with ``dlopen()``. Packagers may wish to
110 use the gcc option ``-Wl,-z,defs`` when building a shared library. Since
111 this option enforces symbol resolution at build time, a missing library
112 reference will be caught early as a fatal build error.
114 All installed shared libraries should be stripped with
118 strip --strip-unneeded your-lib
120 (The option ``--strip-unneeded`` makes ``strip`` remove only the symbols
121 which aren't needed for relocation processing.) Shared libraries can
122 function perfectly well when stripped, since the symbols for dynamic
123 linking are in a separate part of the ELF object file. [#]_
125 Note that under some circumstances it may be useful to install a shared
126 library unstripped, for example when building a separate package to
129 Shared object files (often ``.so`` files) that are not public
130 libraries, that is, they are not meant to be linked to by third party
131 executables (binaries of other packages), should be installed in
132 subdirectories of the ``/usr/lib`` or ``/usr/lib/triplet`` directories
133 (see the FHS for a definition). Such files are exempt from the rules
134 that govern ordinary shared libraries, except that they must not be
135 installed executable and should be stripped. [#]_
137 Packages that use ``libtool`` to create and install their shared
138 libraries install a file containing additional metadata (ending in
139 ``.la``) alongside the library. For public libraries intended for use by
140 other packages, these files normally should not be included in the
141 Debian package, since the information they include is not necessary to
142 link with the shared library on Debian and can add unnecessary
143 additional dependencies to other programs or libraries. [#]_ If the
144 ``.la`` file is required for that library (if, for instance, it's loaded
145 via ``libltdl`` in a way that requires that meta-information), the
146 ``dependency_libs`` setting in the ``.la`` file should normally be set
147 to the empty string. If the shared library development package has
148 historically included the ``.la``, it must be retained in the
149 development package (with ``dependency_libs`` emptied) until all
150 libraries that depend on it have removed or emptied ``dependency_libs``
151 in their ``.la`` files to prevent linking with those other libraries
152 using ``libtool`` from failing.
154 If the ``.la`` must be included, it should be included in the
155 development (``-dev``) package, unless the library will be loaded by
156 ``libtool``'s ``libltdl`` library. If it is intended for use with
157 ``libltdl``, the ``.la`` files must go in the run-time library package.
159 These requirements for handling of ``.la`` files do not apply to
160 loadable modules or libraries not installed in directories searched by
161 default by the dynamic linker. Packages installing loadable modules will
162 frequently need to install the ``.la`` files alongside the modules so
163 that they can be loaded by ``libltdl``. ``dependency_libs`` does not
164 need to be modified for libraries or modules that are not installed in
165 directories searched by the dynamic linker by default and not intended
166 for use by other packages.
168 You must make sure that you use only released versions of shared
169 libraries to build your packages; otherwise other users will not be able
170 to run your binaries properly. Producing source packages that depend on
171 unreleased compilers is also usually a bad idea.
178 This section has moved to :doc:`Shared libraries <ch-sharedlibs>`.
185 All command scripts, including the package maintainer scripts inside the
186 package and used by ``dpkg``, should have a ``#!`` line naming the shell
187 to be used to interpret them.
189 In the case of Perl scripts this must be ``#!/usr/bin/perl``.
191 When scripts are installed into a directory in the system PATH, the
192 script name should not include an extension such as ``.sh`` or ``.pl``
193 that denotes the scripting language currently used to implement it.
195 Shell scripts (``sh`` and ``bash``) other than ``init.d`` scripts should
196 almost certainly start with ``set -e`` so that errors are detected.
197 ``init.d`` scripts are something of a special case, due to how
198 frequently they need to call commands that are allowed to fail, and it
199 may instead be easier to check the exit status of commands directly. See
200 :ref:`s-writing-init` for more information about writing
203 Every script should use ``set -e`` or check the exit status of *every*
206 Scripts may assume that ``/bin/sh`` implements the SUSv3 Shell Command
207 Language [#]_ plus the following additional features not mandated by
210 - ``echo -n``, if implemented as a shell built-in, must not generate a
213 - ``test``, if implemented as a shell built-in, must support ``-a`` and
214 ``-o`` as binary logical operators.
216 - ``local`` to create a scoped variable must be supported, including
217 listing multiple variables in a single local command and assigning a
218 value to a variable at the same time as localizing it. ``local`` may
219 or may not preserve the variable value from an outer scope if no
220 assignment is present. Uses such as:
226 # ... use a, b, c, d ...
229 must be supported and must set the value of ``c`` to ``delta``.
231 - The XSI extension to ``kill`` allowing ``kill -signal``, where signal
232 is either the name of a signal or one of the numeric signals listed
233 in the XSI extension (0, 1, 2, 3, 6, 9, 14, and 15), must be
234 supported if ``kill`` is implemented as a shell built-in.
236 - The XSI extension to ``trap`` allowing numeric signals must be
237 supported. In addition to the signal numbers listed in the extension,
238 which are the same as for ``kill`` above, 13 (SIGPIPE) must be
241 If a shell script requires non-SUSv3 features from the shell interpreter
242 other than those listed above, the appropriate shell must be specified
243 in the first line of the script (e.g., ``#!/bin/bash``) and the package
244 must depend on the package providing the shell (unless the shell package
245 is marked "Essential", as in the case of ``bash``).
247 You may wish to restrict your script to SUSv3 features plus the above
248 set when possible so that it may use ``/bin/sh`` as its interpreter.
249 Checking your script with ``checkbashisms`` from the devscripts package
250 or running your script with an alternate shell such as ``posh`` may help
251 uncover violations of the above requirements. If in doubt whether a
252 script complies with these requirements, use ``/bin/bash``.
254 Perl scripts should check for errors when making any system calls,
255 including ``open``, ``print``, ``close``, ``rename`` and ``system``.
257 ``csh`` and ``tcsh`` should be avoided as scripting languages. See *Csh
258 Programming Considered Harmful*, one of the ``comp.unix.*`` FAQs, which
259 can be found at http://www.faqs.org/faqs/unix-faq/shell/csh-whynot/. If
260 an upstream package comes with ``csh`` scripts then you must make sure
261 that they start with ``#!/bin/csh`` and make your package depend on the
262 ``c-shell`` virtual package.
264 Any scripts which create files in world-writeable directories (e.g., in
265 ``/tmp``) must use a mechanism which will fail atomically if a file with
266 the same name already exists.
268 The Debian base system provides the ``tempfile`` and ``mktemp``
269 utilities for use by scripts for this purpose.
276 In general, symbolic links within a top-level directory should be
277 relative, and symbolic links pointing from one top-level directory to or
278 into another should be absolute. (A top-level directory is a
279 sub-directory of the root directory ``/``.) For example, a symbolic link
280 from ``/usr/lib/foo`` to ``/usr/share/bar`` should be relative
281 (``../share/bar``), but a symbolic link from ``/var/run`` to ``/run``
282 should be absolute. [#]_ Symbolic links must not traverse above the
285 In addition, symbolic links should be specified as short as possible,
286 i.e., link targets like ``foo/../bar`` are deprecated.
288 Note that when creating a relative link using ``ln`` it is not necessary
289 for the target of the link to exist relative to the working directory
290 you're running ``ln`` from, nor is it necessary to change directory to
291 the directory where the link is to be made. Simply include the string
292 that should appear as the target of the link (this will be a pathname
293 relative to the directory in which the link resides) as the first
296 For example, in your ``Makefile`` or ``debian/rules``, you can do things
301 ln -fs gcc $(prefix)/bin/cc
302 ln -fs gcc debian/tmp/usr/bin/cc
303 ln -fs ../sbin/sendmail $(prefix)/bin/runq
304 ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
306 A symbolic link pointing to a compressed file (in the sense that it is
307 meant to be uncompressed with ``unzip`` or ``zless`` etc.) should always
308 have the same file extension as the referenced file. (For example, if a
309 file ``foo.gz`` is referenced by a symbolic link, the filename of the
310 link has to end with "``.gz``" too, as in ``bar.gz``.)
317 Packages must not include device files or named pipes in the package
320 Debian packages should assume that device files in ``/dev`` are
321 dynamically managed by the kernel or some other system facility and do
322 not have to be explicitly created or managed by the package. Debian
323 packages other than those whose purpose is to manage the ``/dev`` device
324 file tree must not attempt to create or remove device files in ``/dev``
325 when a dynamic device management facility is in use.
327 If named pipes or device files outside of ``/dev`` are required by a
328 package, they should normally be created when necessary by the programs
329 in the package, by init scripts or systemd unit files, or by similar
330 on-demand mechanisms. If such files need to be created during package
331 installation, they must be created in the ``postinst`` maintainer script
332 [#]_ and removed in either the ``prerm`` or the ``postrm`` maintainer
346 A file that affects the operation of a program, or provides site- or
347 host-specific information, or otherwise customizes the behavior of a
348 program. Typically, configuration files are intended to be modified
349 by the system administrator (if needed or desired) to conform to
350 local policy or to provide more useful site-specific behavior.
353 A file listed in a package's ``conffiles`` file, and is treated
354 specially by ``dpkg`` (see :ref:`s-configdetails`).
356 The distinction between these two is important; they are not
357 interchangeable concepts. Almost all ``conffile``\ s are configuration
358 files, but many configuration files are not ``conffiles``.
360 As noted elsewhere, ``/etc/init.d`` scripts, ``/etc/default`` files,
361 scripts installed in ``/etc/cron.{hourly,daily,weekly,monthly}``, and
362 cron configuration installed in ``/etc/cron.d`` must be treated as
363 configuration files. In general, any script that embeds configuration
364 information is de-facto a configuration file and should be treated as
372 Any configuration files created or used by your package must reside in
373 ``/etc``. If there are several, consider creating a subdirectory of
374 ``/etc`` named after your package.
376 If your package creates or uses configuration files outside of ``/etc``,
377 and it is not feasible to modify the package to use ``/etc`` directly,
378 put the files in ``/etc`` and create symbolic links to those files from
379 the location that the package requires.
386 Configuration file handling must conform to the following behavior:
388 - local changes must be preserved during a package upgrade, and
390 - configuration files must be preserved when the package is removed,
391 and only deleted when the package is purged.
393 Obsolete configuration files without local changes should be removed by
394 the package during upgrade. [#]_
396 The easy way to achieve this behavior is to make the configuration file
397 a ``conffile``. This is appropriate only if it is possible to distribute
398 a default version that will work for most installations, although some
399 system administrators may choose to modify it. This implies that the
400 default version will be part of the package distribution, and must not
401 be modified by the maintainer scripts during installation (or at any
404 In order to ensure that local changes are preserved correctly, no
405 package may contain or make hard links to conffiles. [#]_
407 The other way to do it is via the maintainer scripts. In this case, the
408 configuration file must not be listed as a ``conffile`` and must not be
409 part of the package distribution. If the existence of a file is required
410 for the package to be sensibly configured it is the responsibility of
411 the package maintainer to provide maintainer scripts which correctly
412 create, update and maintain the file and remove it on purge. (See
413 :doc:`Package maintainer scripts and installation procedure <ch-maintainerscripts>`
414 for more information.) These scripts must be idempotent (i.e., must work
415 correctly if ``dpkg`` needs to re-run them due to errors during
416 installation or removal), must cope with all the variety of ways
417 ``dpkg`` can call maintainer scripts, must not overwrite or otherwise
418 mangle the user's configuration without asking, must not ask unnecessary
419 questions (particularly during upgrades), and must otherwise be good
422 The scripts are not required to configure every possible option for the
423 package, but only those necessary to get the package running on a given
424 system. Ideally the sysadmin should not have to do any configuration
425 other than that done (semi-)automatically by the ``postinst`` script.
427 A common practice is to create a script called ``package-configure`` and
428 have the package's ``postinst`` call it if and only if the configuration
429 file does not already exist. In certain cases it is useful for there to
430 be an example or template file which the maintainer scripts use. Such
431 files should be in ``/usr/share/package`` or ``/usr/lib/package``
432 (depending on whether they are architecture-independent or not). There
433 should be symbolic links to them from
434 ``/usr/share/doc/package/examples`` if they are examples, and should be
435 perfectly ordinary ``dpkg``-handled files (*not* configuration files).
437 These two styles of configuration file handling must not be mixed, for
438 that way lies madness: ``dpkg`` will ask about overwriting the file
439 every time the package is upgraded.
443 Sharing configuration files
444 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
446 If two or more packages use the same configuration file and it is
447 reasonable for both to be installed at the same time, one of these
448 packages must be defined as *owner* of the configuration file, i.e., it
449 will be the package which handles that file as a configuration file.
450 Other packages that use the configuration file must depend on the owning
451 package if they require the configuration file to operate. If the other
452 package will use the configuration file if present, but is capable of
453 operating without it, no dependency need be declared.
455 If it is desirable for two or more related packages to share a
456 configuration file *and* for all of the related packages to be able to
457 modify that configuration file, then the following should be done:
459 1. One of the related packages (the "owning" package) will manage the
460 configuration file with maintainer scripts as described in the
463 2. The owning package should also provide a program that the other
464 packages may use to modify the configuration file.
466 3. The related packages must use the provided program to make any
467 desired modifications to the configuration file. They should either
468 depend on the core package to guarantee that the configuration
469 modifier program is available or accept gracefully that they cannot
470 modify the configuration file if it is not. (This is in addition to
471 the fact that the configuration file may not even be present in the
474 Sometimes it's appropriate to create a new package which provides the
475 basic infrastructure for the other packages and which manages the shared
476 configuration files. (The ``sgml-base`` package is a good example.)
478 If the configuration file cannot be shared as described above, the
479 packages must be marked as conflicting with each other. Two packages
480 that specify the same file as a ``conffile`` must conflict. This is an
481 instance of the general rule about not sharing files. Neither
482 alternatives nor diversions are likely to be appropriate in this case;
483 in particular, ``dpkg`` does not handle diverted ``conffile``\ s well.
485 When two packages both declare the same ``conffile``, they may see
486 left-over configuration files from each other even though they conflict
487 with each other. If a user removes (without purging) one of the packages
488 and installs the other, the new package will take over the ``conffile``
489 from the old package. If the file was modified by the user, it will be
490 treated the same as any other locally modified ``conffile`` during an
493 The maintainer scripts must not alter a ``conffile`` of *any* package,
494 including the one the scripts belong to.
498 User configuration files ("dotfiles")
499 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
501 The files in ``/etc/skel`` will automatically be copied into new user
502 accounts by ``adduser``. No other program should reference the files in
505 Therefore, if a program needs a dotfile to exist in advance in ``$HOME``
506 to work sensibly, that dotfile should be installed in ``/etc/skel`` and
507 treated as a configuration file.
509 However, programs that require dotfiles in order to operate sensibly are
510 a bad thing, unless they do create the dotfiles themselves
513 Furthermore, programs should be configured by the Debian default
514 installation to behave as closely to the upstream default behavior as
517 Therefore, if a program in a Debian package needs to be configured in
518 some way in order to operate sensibly, that should be done using a
519 site-wide configuration file placed in ``/etc``. Only if the program
520 doesn't support a site-wide default configuration and the package
521 maintainer doesn't have time to add it may a default per-user file be
522 placed in ``/etc/skel``.
524 ``/etc/skel`` should be as empty as we can make it. This is particularly
525 true because there is no easy (or necessarily desirable) mechanism for
526 ensuring that the appropriate dotfiles are copied into the accounts of
527 existing users when a package is installed.
534 Log files should usually be named ``/var/log/package.log``. If you have
535 many log files, or need a separate directory for permission reasons
536 (``/var/log`` is writable only by ``root``), you should usually create a
537 directory named ``/var/log/package`` and place your log files there.
539 Log files must be rotated occasionally so that they don't grow
540 indefinitely. The best way to do this is to install a log rotation
541 configuration file in the directory ``/etc/logrotate.d``, normally named
542 ``/etc/logrotate.d/package``, and use the facilities provided by
543 ``logrotate``. [#]_ Here is a good example for a logrotate config file
544 (for more information see logrotate(8)):
554 start-stop-daemon -K -p /var/run/foo.pid -s HUP -x /usr/sbin/foo -q
558 This rotates all files under ``/var/log/foo``, saves 12 compressed
559 generations, and tells the daemon to reopen its log files after the log
560 rotation. It skips this log rotation (via ``missingok``) if no such log
561 file is present, which avoids errors if the package is removed but not
564 Log files should be removed when the package is purged (but not when it
565 is only removed). This should be done by the ``postrm`` script when it
566 is called with the argument ``purge`` (see
567 :ref:`s-removedetails`).
569 .. _s-permissions-owners:
571 Permissions and owners
572 ----------------------
574 The rules in this section are guidelines for general use. If necessary
575 you may deviate from the details below. However, if you do so you must
576 make sure that what is done is secure and you should try to be as
577 consistent as possible with the rest of the system. You should probably
578 also discuss it on ``debian-devel`` first.
580 Files should be owned by ``root:root``, and made writable only by the
581 owner and universally readable (and executable, if appropriate), that is
584 Directories should be mode 755 or (for group-writability) mode 2775. The
585 ownership of the directory should be consistent with its mode: if a
586 directory is mode 2775, it should be owned by the group that needs write
589 Control information files should be owned by ``root:root`` and either
590 mode 644 (for most files) or mode 755 (for executables such as
591 :ref:`maintainer scripts <s-maintscripts>`).
593 Setuid and setgid executables should be mode 4755 or 2755 respectively,
594 and owned by the appropriate user or group. They should not be made
595 unreadable (modes like 4711 or 2711 or even 4111); doing so achieves no
596 extra security, because anyone can find the binary in the freely
597 available Debian package; it is merely inconvenient. For the same reason
598 you should not restrict read or execute permissions on non-set-id
601 Some setuid programs need to be restricted to particular sets of users,
602 using file permissions. In this case they should be owned by the uid to
603 which they are set-id, and by the group which should be allowed to
604 execute them. They should have mode 4754; again there is no point in
605 making them unreadable to those users who must not be allowed to execute
608 It is possible to arrange that the system administrator can reconfigure
609 the package to correspond to their local security policy by changing the
610 permissions on a binary: they can do this by using
611 ``dpkg-statoverride``, as described below. [#]_ Another method you
612 should consider is to create a group for people allowed to use the
613 program(s) and make any setuid executables executable only by that
616 If you need to create a new user or group for your package there are two
617 possibilities. Firstly, you may need to make some files in the binary
618 package be owned by this user or group, or you may need to compile the
619 user or group id (rather than just the name) into the binary (though
620 this latter should be avoided if possible, as in this case you need a
621 statically allocated id).
623 If you need a statically allocated id, you must ask for a user or group
624 id from the ``base-passwd`` maintainer, and must not release the package
625 until you have been allocated one. Once you have been allocated one you
626 must either make the package depend on a version of the ``base-passwd``
627 package with the id present in ``/etc/passwd`` or ``/etc/group``, or
628 arrange for your package to create the user or group itself with the
629 correct id (using ``adduser``) in its ``preinst`` or ``postinst``.
630 (Doing it in the ``postinst`` is to be preferred if it is possible,
631 otherwise a pre-dependency will be needed on the ``adduser`` package.)
633 On the other hand, the program might be able to determine the uid or gid
634 from the user or group name at runtime, so that a dynamically allocated
635 id can be used. In this case you should choose an appropriate user or
636 group name, discussing this on ``debian-devel`` and checking that it is
637 unique. When this has been checked you must arrange for your package to
638 create the user or group if necessary using ``adduser`` in the
639 ``preinst`` or ``postinst`` script (again, the latter is to be preferred
642 Note that changing the numeric value of an id associated with a name is
643 very difficult, and involves searching the file system for all
644 appropriate files. You need to think carefully whether a static or
645 dynamic id is required, since changing your mind later will cause
650 The use of ``dpkg-statoverride``
651 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
653 This section is not intended as policy, but as a description of the use
654 of ``dpkg-statoverride``.
656 If a system administrator wishes to have a file (or directory or other
657 such thing) installed with owner and permissions different from those in
658 the distributed Debian package, they can use the ``dpkg-statoverride``
659 program to instruct ``dpkg`` to use the different settings every time
660 the file is installed. Thus the package maintainer should distribute the
661 files with their normal permissions, and leave it for the system
662 administrator to make any desired changes. For example, a daemon which
663 is normally required to be setuid root, but in certain situations could
664 be used without being setuid, should be installed setuid in the
665 ``.deb``. Then the local system administrator can change this if they
666 wish. If there are two standard ways of doing it, the package maintainer
667 can use ``debconf`` to find out the preference, and call
668 ``dpkg-statoverride`` in the maintainer script if necessary to
669 accommodate the system administrator's choice. Care must be taken during
670 upgrades to not override an existing setting.
672 Given the above, ``dpkg-statoverride`` is essentially a tool for system
673 administrators and would not normally be needed in the maintainer
674 scripts. There is one type of situation, though, where calls to
675 ``dpkg-statoverride`` would be needed in the maintainer scripts, and
676 that involves packages which use dynamically allocated user or group
677 ids. In such a situation, something like the following idiom can be very
678 helpful in the package's ``postinst``, where ``sysuser`` is a
679 dynamically allocated id:
683 for i in /usr/bin/foo /usr/sbin/bar; do
684 # only do something when no setting exists
685 if ! dpkg-statoverride --list $i >/dev/null 2>&1; then
686 #include: debconf processing, question about foo and bar
687 if [ "$RET" = "tru.. [#] ; then
688 dpkg-statoverride --update --add sysuser root 4755 $i
693 The corresponding code to remove the override when the package is purged
698 for i in /usr/bin/foo /usr/sbin/bar; do
699 if dpkg-statoverride --list $i >/dev/null 2>&1; then
700 dpkg-statoverride --remove $i
709 The name of the files installed by binary packages in the system PATH
710 (namely ``/bin``, ``/sbin``, ``/usr/bin``, ``/usr/sbin`` and
711 ``/usr/games``) must be encoded in ASCII.
713 The name of the files and directories installed by binary packages
714 outside the system PATH must be encoded in UTF-8 and should be
715 restricted to ASCII when it is possible to do so.
718 If you are using GCC, ``-fPIC`` produces code with relocatable
719 position independent code, which is required for most architectures
720 to create a shared library, with i386 and perhaps some others where
721 non position independent code is permitted in a shared library.
723 Position independent code may have a performance penalty, especially
724 on ``i386``. However, in most cases the speed penalty must be
725 measured against the memory wasted on the few architectures where non
726 position independent code is even possible.
729 Some of the reasons why this might be required is if the library
730 contains hand crafted assembly code that is not relocatable, the
731 speed penalty is excessive for compute intensive libs, and similar
735 Some of the reasons for linking static libraries with the ``-fPIC``
736 flag are if, for example, one needs a Perl API for a library that is
737 under rapid development, and has an unstable API, so shared libraries
738 are pointless at this phase of the library's development. In that
739 case, since Perl needs a library with relocatable code, it may make
740 sense to create a static library with relocatable code. Another
741 reason cited is if you are distilling various libraries into a common
742 shared library, like ``mklibs`` does in the Debian installer project.
745 You might also want to use the options ``--remove-section=.comment``
746 and ``--remove-section=.note`` on both shared libraries and
747 executables, and ``--strip-debug`` on static libraries.
750 A common example are the so-called "plug-ins", internal shared
751 objects that are dynamically loaded by programs using dlopen(3).
754 These files store, among other things, all libraries on which that
755 shared library depends. Unfortunately, if the ``.la`` file is present
756 and contains that dependency information, using ``libtool`` when
757 linking against that library will cause the resulting program or
758 library to be linked against those dependencies as well, even if this
759 is unnecessary. This can create unneeded dependencies on shared
760 library packages that would otherwise be hidden behind the library
761 ABI, and can make library transitions to new SONAMEs unnecessarily
762 complicated and difficult to manage.
765 Single UNIX Specification, version 3, which is also IEEE 1003.1-2004
766 (POSIX), and is available on the World Wide Web from `The Open
767 Group <http://www.unix.org/version3/online.html>`_ after free
771 These features are in widespread use in the Linux community and are
772 implemented in all of bash, dash, and ksh, the most common shells
773 users may wish to use as ``/bin/sh``.
776 This is necessary to allow top-level directories to be symlinks. If
777 linking ``/var/run`` to ``/run`` were done with the relative symbolic
778 link ``../run``, but ``/var`` were a symbolic link to ``/srv/disk1``,
779 the symbolic link would point to ``/srv/run`` rather than the
783 It's better to use ``mkfifo`` rather than ``mknod`` to create named
784 pipes to avoid false positives from automated checks for packages
785 incorrectly creating device files.
788 The ``dpkg-maintscript-helper`` tool, available from the dpkg
789 package, can help for this task.
792 Rationale: There are two problems with hard links. The first is that
793 some editors break the link while editing one of the files, so that
794 the two files may unwittingly become unlinked and different. The
795 second is that ``dpkg`` might break the hard link while upgrading
799 The traditional approach to log files has been to set up *ad hoc* log
800 rotation schemes using simple shell scripts and cron. While this
801 approach is highly customizable, it requires quite a lot of sysadmin
802 work. Even though the original Debian system helped a little by
803 automatically installing a system which can be used as a template,
804 this was deemed not enough.
806 The use of ``logrotate``, a program developed by Red Hat, is better,
807 as it centralizes log management. It has both a configuration file
808 (``/etc/logrotate.conf``) and a directory where packages can drop
809 their individual log rotation configurations (``/etc/logrotate.d``).
812 When a package is upgraded, and the owner or permissions of a file
813 included in the package has changed, dpkg arranges for the ownership
814 and permissions to be correctly set upon installation. However, this
815 does not extend to directories; the permissions and ownership of
816 directories already on the system does not change on install or
817 upgrade of packages. This makes sense, since otherwise common
818 directories like ``/usr`` would always be in flux. To correctly
819 change permissions of a directory the package owns, explicit action
820 is required, usually in the ``postinst`` script. Care must be taken
821 to handle downgrades as well, in that case.
824 Ordinary files installed by ``dpkg`` (as opposed to ``conffile``\ s
825 and other similar objects) normally have their permissions reset to
826 the distributed permissions when the package is reinstalled. However,
827 the use of ``dpkg-statoverride`` overrides this default behavior.