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 libraries,
130 that is, they are not meant to be linked to by third party executables
131 (binaries of other packages), should be installed in subdirectories of
132 the ``/usr/lib`` directory. Such files are exempt from the rules that
133 govern ordinary shared libraries, except that they must not be installed
134 executable and should be stripped. [#]_
136 Packages that use ``libtool`` to create and install their shared
137 libraries install a file containing additional metadata (ending in
138 ``.la``) alongside the library. For public libraries intended for use by
139 other packages, these files normally should not be included in the
140 Debian package, since the information they include is not necessary to
141 link with the shared library on Debian and can add unnecessary
142 additional dependencies to other programs or libraries. [#]_ If the
143 ``.la`` file is required for that library (if, for instance, it's loaded
144 via ``libltdl`` in a way that requires that meta-information), the
145 ``dependency_libs`` setting in the ``.la`` file should normally be set
146 to the empty string. If the shared library development package has
147 historically included the ``.la``, it must be retained in the
148 development package (with ``dependency_libs`` emptied) until all
149 libraries that depend on it have removed or emptied ``dependency_libs``
150 in their ``.la`` files to prevent linking with those other libraries
151 using ``libtool`` from failing.
153 If the ``.la`` must be included, it should be included in the
154 development (``-dev``) package, unless the library will be loaded by
155 ``libtool``'s ``libltdl`` library. If it is intended for use with
156 ``libltdl``, the ``.la`` files must go in the run-time library package.
158 These requirements for handling of ``.la`` files do not apply to
159 loadable modules or libraries not installed in directories searched by
160 default by the dynamic linker. Packages installing loadable modules will
161 frequently need to install the ``.la`` files alongside the modules so
162 that they can be loaded by ``libltdl``. ``dependency_libs`` does not
163 need to be modified for libraries or modules that are not installed in
164 directories searched by the dynamic linker by default and not intended
165 for use by other packages.
167 You must make sure that you use only released versions of shared
168 libraries to build your packages; otherwise other users will not be able
169 to run your binaries properly. Producing source packages that depend on
170 unreleased compilers is also usually a bad idea.
177 This section has moved to :doc:`Shared libraries <ch-sharedlibs>`.
184 All command scripts, including the package maintainer scripts inside the
185 package and used by ``dpkg``, should have a ``#!`` line naming the shell
186 to be used to interpret them.
188 In the case of Perl scripts this should be ``#!/usr/bin/perl``.
190 When scripts are installed into a directory in the system PATH, the
191 script name should not include an extension such as ``.sh`` or ``.pl``
192 that denotes the scripting language currently used to implement it.
194 Shell scripts (``sh`` and ``bash``) other than ``init.d`` scripts should
195 almost certainly start with ``set -e`` so that errors are detected.
196 ``init.d`` scripts are something of a special case, due to how
197 frequently they need to call commands that are allowed to fail, and it
198 may instead be easier to check the exit status of commands directly. See
199 :ref:`s-writing-init` for more information about writing
202 Every script should use ``set -e`` or check the exit status of *every*
205 Scripts may assume that ``/bin/sh`` implements the SUSv3 Shell Command
206 Language [#]_ plus the following additional features not mandated by
209 - ``echo -n``, if implemented as a shell built-in, must not generate a
212 - ``test``, if implemented as a shell built-in, must support ``-a`` and
213 ``-o`` as binary logical operators.
215 - ``local`` to create a scoped variable must be supported, including
216 listing multiple variables in a single local command and assigning a
217 value to a variable at the same time as localizing it. ``local`` may
218 or may not preserve the variable value from an outer scope if no
219 assignment is present. Uses such as:
225 # ... use a, b, c, d ...
228 must be supported and must set the value of ``c`` to ``delta``.
230 - The XSI extension to ``kill`` allowing ``kill -signal``, where signal
231 is either the name of a signal or one of the numeric signals listed
232 in the XSI extension (0, 1, 2, 3, 6, 9, 14, and 15), must be
233 supported if ``kill`` is implemented as a shell built-in.
235 - The XSI extension to ``trap`` allowing numeric signals must be
236 supported. In addition to the signal numbers listed in the extension,
237 which are the same as for ``kill`` above, 13 (SIGPIPE) must be
240 If a shell script requires non-SUSv3 features from the shell interpreter
241 other than those listed above, the appropriate shell must be specified
242 in the first line of the script (e.g., ``#!/bin/bash``) and the package
243 must depend on the package providing the shell (unless the shell package
244 is marked "Essential", as in the case of ``bash``).
246 You may wish to restrict your script to SUSv3 features plus the above
247 set when possible so that it may use ``/bin/sh`` as its interpreter.
248 Checking your script with ``checkbashisms`` from the devscripts package
249 or running your script with an alternate shell such as ``posh`` may help
250 uncover violations of the above requirements. If in doubt whether a
251 script complies with these requirements, use ``/bin/bash``.
253 Perl scripts should check for errors when making any system calls,
254 including ``open``, ``print``, ``close``, ``rename`` and ``system``.
256 ``csh`` and ``tcsh`` should be avoided as scripting languages. See *Csh
257 Programming Considered Harmful*, one of the ``comp.unix.*`` FAQs, which
258 can be found at http://www.faqs.org/faqs/unix-faq/shell/csh-whynot/. If
259 an upstream package comes with ``csh`` scripts then you must make sure
260 that they start with ``#!/bin/csh`` and make your package depend on the
261 ``c-shell`` virtual package.
263 Any scripts which create files in world-writeable directories (e.g., in
264 ``/tmp``) must use a mechanism which will fail atomically if a file with
265 the same name already exists.
267 The Debian base system provides the ``tempfile`` and ``mktemp``
268 utilities for use by scripts for this purpose.
275 In general, symbolic links within a top-level directory should be
276 relative, and symbolic links pointing from one top-level directory to or
277 into another should be absolute. (A top-level directory is a
278 sub-directory of the root directory ``/``.) For example, a symbolic link
279 from ``/usr/lib/foo`` to ``/usr/share/bar`` should be relative
280 (``../share/bar``), but a symbolic link from ``/var/run`` to ``/run``
281 should be absolute. [#]_ Symbolic links must not traverse above the
284 In addition, symbolic links should be specified as short as possible,
285 i.e., link targets like ``foo/../bar`` are deprecated.
287 Note that when creating a relative link using ``ln`` it is not necessary
288 for the target of the link to exist relative to the working directory
289 you're running ``ln`` from, nor is it necessary to change directory to
290 the directory where the link is to be made. Simply include the string
291 that should appear as the target of the link (this will be a pathname
292 relative to the directory in which the link resides) as the first
295 For example, in your ``Makefile`` or ``debian/rules``, you can do things
300 ln -fs gcc $(prefix)/bin/cc
301 ln -fs gcc debian/tmp/usr/bin/cc
302 ln -fs ../sbin/sendmail $(prefix)/bin/runq
303 ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
305 A symbolic link pointing to a compressed file (in the sense that it is
306 meant to be uncompressed with ``unzip`` or ``zless`` etc.) should always
307 have the same file extension as the referenced file. (For example, if a
308 file ``foo.gz`` is referenced by a symbolic link, the filename of the
309 link has to end with "``.gz``" too, as in ``bar.gz``.)
316 Packages must not include device files or named pipes in the package
319 Debian packages should assume that device files in ``/dev`` are
320 dynamically managed by the kernel or some other system facility and do
321 not have to be explicitly created or managed by the package. Debian
322 packages other than those whose purpose is to manage the ``/dev`` device
323 file tree must not attempt to create or remove device files in ``/dev``
324 when a dynamic device management facility is in use.
326 If named pipes or device files outside of ``/dev`` are required by a
327 package, they should normally be created when necessary by the programs
328 in the package, by init scripts or systemd unit files, or by similar
329 on-demand mechanisms. If such files need to be created during package
330 installation, they must be created in the ``postinst`` maintainer script
331 [#]_ and removed in either the ``prerm`` or the ``postrm`` maintainer
345 A file that affects the operation of a program, or provides site- or
346 host-specific information, or otherwise customizes the behavior of a
347 program. Typically, configuration files are intended to be modified
348 by the system administrator (if needed or desired) to conform to
349 local policy or to provide more useful site-specific behavior.
352 A file listed in a package's ``conffiles`` file, and is treated
353 specially by ``dpkg`` (see :ref:`s-configdetails`).
355 The distinction between these two is important; they are not
356 interchangeable concepts. Almost all ``conffile``\ s are configuration
357 files, but many configuration files are not ``conffiles``.
359 As noted elsewhere, ``/etc/init.d`` scripts, ``/etc/default`` files,
360 scripts installed in ``/etc/cron.{hourly,daily,weekly,monthly}``, and
361 cron configuration installed in ``/etc/cron.d`` must be treated as
362 configuration files. In general, any script that embeds configuration
363 information is de-facto a configuration file and should be treated as
371 Any configuration files created or used by your package must reside in
372 ``/etc``. If there are several, consider creating a subdirectory of
373 ``/etc`` named after your package.
375 If your package creates or uses configuration files outside of ``/etc``,
376 and it is not feasible to modify the package to use ``/etc`` directly,
377 put the files in ``/etc`` and create symbolic links to those files from
378 the location that the package requires.
385 Configuration file handling must conform to the following behavior:
387 - local changes must be preserved during a package upgrade, and
389 - configuration files must be preserved when the package is removed,
390 and only deleted when the package is purged.
392 Obsolete configuration files without local changes should be removed by
393 the package during upgrade. [#]_
395 The easy way to achieve this behavior is to make the configuration file
396 a ``conffile``. This is appropriate only if it is possible to distribute
397 a default version that will work for most installations, although some
398 system administrators may choose to modify it. This implies that the
399 default version will be part of the package distribution, and must not
400 be modified by the maintainer scripts during installation (or at any
403 In order to ensure that local changes are preserved correctly, no
404 package may contain or make hard links to conffiles. [#]_
406 The other way to do it is via the maintainer scripts. In this case, the
407 configuration file must not be listed as a ``conffile`` and must not be
408 part of the package distribution. If the existence of a file is required
409 for the package to be sensibly configured it is the responsibility of
410 the package maintainer to provide maintainer scripts which correctly
411 create, update and maintain the file and remove it on purge. (See
412 :doc:`Package maintainer scripts and installation procedure <ch-maintainerscripts>`
413 for more information.) These scripts must be idempotent (i.e., must work
414 correctly if ``dpkg`` needs to re-run them due to errors during
415 installation or removal), must cope with all the variety of ways
416 ``dpkg`` can call maintainer scripts, must not overwrite or otherwise
417 mangle the user's configuration without asking, must not ask unnecessary
418 questions (particularly during upgrades), and must otherwise be good
421 The scripts are not required to configure every possible option for the
422 package, but only those necessary to get the package running on a given
423 system. Ideally the sysadmin should not have to do any configuration
424 other than that done (semi-)automatically by the ``postinst`` script.
426 A common practice is to create a script called ``package-configure`` and
427 have the package's ``postinst`` call it if and only if the configuration
428 file does not already exist. In certain cases it is useful for there to
429 be an example or template file which the maintainer scripts use. Such
430 files should be in ``/usr/share/package`` or ``/usr/lib/package``
431 (depending on whether they are architecture-independent or not). There
432 should be symbolic links to them from
433 ``/usr/share/doc/package/examples`` if they are examples, and should be
434 perfectly ordinary ``dpkg``-handled files (*not* configuration files).
436 These two styles of configuration file handling must not be mixed, for
437 that way lies madness: ``dpkg`` will ask about overwriting the file
438 every time the package is upgraded.
442 Sharing configuration files
443 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
445 If two or more packages use the same configuration file and it is
446 reasonable for both to be installed at the same time, one of these
447 packages must be defined as *owner* of the configuration file, i.e., it
448 will be the package which handles that file as a configuration file.
449 Other packages that use the configuration file must depend on the owning
450 package if they require the configuration file to operate. If the other
451 package will use the configuration file if present, but is capable of
452 operating without it, no dependency need be declared.
454 If it is desirable for two or more related packages to share a
455 configuration file *and* for all of the related packages to be able to
456 modify that configuration file, then the following should be done:
458 1. One of the related packages (the "owning" package) will manage the
459 configuration file with maintainer scripts as described in the
462 2. The owning package should also provide a program that the other
463 packages may use to modify the configuration file.
465 3. The related packages must use the provided program to make any
466 desired modifications to the configuration file. They should either
467 depend on the core package to guarantee that the configuration
468 modifier program is available or accept gracefully that they cannot
469 modify the configuration file if it is not. (This is in addition to
470 the fact that the configuration file may not even be present in the
473 Sometimes it's appropriate to create a new package which provides the
474 basic infrastructure for the other packages and which manages the shared
475 configuration files. (The ``sgml-base`` package is a good example.)
477 If the configuration file cannot be shared as described above, the
478 packages must be marked as conflicting with each other. Two packages
479 that specify the same file as a ``conffile`` must conflict. This is an
480 instance of the general rule about not sharing files. Neither
481 alternatives nor diversions are likely to be appropriate in this case;
482 in particular, ``dpkg`` does not handle diverted ``conffile``\ s well.
484 When two packages both declare the same ``conffile``, they may see
485 left-over configuration files from each other even though they conflict
486 with each other. If a user removes (without purging) one of the packages
487 and installs the other, the new package will take over the ``conffile``
488 from the old package. If the file was modified by the user, it will be
489 treated the same as any other locally modified ``conffile`` during an
492 The maintainer scripts must not alter a ``conffile`` of *any* package,
493 including the one the scripts belong to.
497 User configuration files ("dotfiles")
498 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
500 The files in ``/etc/skel`` will automatically be copied into new user
501 accounts by ``adduser``. No other program should reference the files in
504 Therefore, if a program needs a dotfile to exist in advance in ``$HOME``
505 to work sensibly, that dotfile should be installed in ``/etc/skel`` and
506 treated as a configuration file.
508 However, programs that require dotfiles in order to operate sensibly are
509 a bad thing, unless they do create the dotfiles themselves
512 Furthermore, programs should be configured by the Debian default
513 installation to behave as closely to the upstream default behavior as
516 Therefore, if a program in a Debian package needs to be configured in
517 some way in order to operate sensibly, that should be done using a
518 site-wide configuration file placed in ``/etc``. Only if the program
519 doesn't support a site-wide default configuration and the package
520 maintainer doesn't have time to add it may a default per-user file be
521 placed in ``/etc/skel``.
523 ``/etc/skel`` should be as empty as we can make it. This is particularly
524 true because there is no easy (or necessarily desirable) mechanism for
525 ensuring that the appropriate dotfiles are copied into the accounts of
526 existing users when a package is installed.
533 Log files should usually be named ``/var/log/package.log``. If you have
534 many log files, or need a separate directory for permission reasons
535 (``/var/log`` is writable only by ``root``), you should usually create a
536 directory named ``/var/log/package`` and place your log files there.
538 Log files must be rotated occasionally so that they don't grow
539 indefinitely. The best way to do this is to install a log rotation
540 configuration file in the directory ``/etc/logrotate.d``, normally named
541 ``/etc/logrotate.d/package``, and use the facilities provided by
542 ``logrotate``. [#]_ Here is a good example for a logrotate config file
543 (for more information see logrotate8):
553 start-stop-daemon -K -p /var/run/foo.pid -s HUP -x /usr/sbin/foo -q
557 This rotates all files under ``/var/log/foo``, saves 12 compressed
558 generations, and tells the daemon to reopen its log files after the log
559 rotation. It skips this log rotation (via ``missingok``) if no such log
560 file is present, which avoids errors if the package is removed but not
563 Log files should be removed when the package is purged (but not when it
564 is only removed). This should be done by the ``postrm`` script when it
565 is called with the argument ``purge`` (see
566 :ref:`s-removedetails`).
568 .. _s-permissions-owners:
570 Permissions and owners
571 ----------------------
573 The rules in this section are guidelines for general use. If necessary
574 you may deviate from the details below. However, if you do so you must
575 make sure that what is done is secure and you should try to be as
576 consistent as possible with the rest of the system. You should probably
577 also discuss it on ``debian-devel`` first.
579 Files should be owned by ``root:root``, and made writable only by the
580 owner and universally readable (and executable, if appropriate), that is
583 Directories should be mode 755 or (for group-writability) mode 2775. The
584 ownership of the directory should be consistent with its mode: if a
585 directory is mode 2775, it should be owned by the group that needs write
588 Control information files should be owned by ``root:root`` and either
589 mode 644 (for most files) or mode 755 (for executables such as
590 :ref:`maintainer scripts <s-maintscripts>`).
592 Setuid and setgid executables should be mode 4755 or 2755 respectively,
593 and owned by the appropriate user or group. They should not be made
594 unreadable (modes like 4711 or 2711 or even 4111); doing so achieves no
595 extra security, because anyone can find the binary in the freely
596 available Debian package; it is merely inconvenient. For the same reason
597 you should not restrict read or execute permissions on non-set-id
600 Some setuid programs need to be restricted to particular sets of users,
601 using file permissions. In this case they should be owned by the uid to
602 which they are set-id, and by the group which should be allowed to
603 execute them. They should have mode 4754; again there is no point in
604 making them unreadable to those users who must not be allowed to execute
607 It is possible to arrange that the system administrator can reconfigure
608 the package to correspond to their local security policy by changing the
609 permissions on a binary: they can do this by using
610 ``dpkg-statoverride``, as described below. [#]_ Another method you
611 should consider is to create a group for people allowed to use the
612 program(s) and make any setuid executables executable only by that
615 If you need to create a new user or group for your package there are two
616 possibilities. Firstly, you may need to make some files in the binary
617 package be owned by this user or group, or you may need to compile the
618 user or group id (rather than just the name) into the binary (though
619 this latter should be avoided if possible, as in this case you need a
620 statically allocated id).
622 If you need a statically allocated id, you must ask for a user or group
623 id from the ``base-passwd`` maintainer, and must not release the package
624 until you have been allocated one. Once you have been allocated one you
625 must either make the package depend on a version of the ``base-passwd``
626 package with the id present in ``/etc/passwd`` or ``/etc/group``, or
627 arrange for your package to create the user or group itself with the
628 correct id (using ``adduser``) in its ``preinst`` or ``postinst``.
629 (Doing it in the ``postinst`` is to be preferred if it is possible,
630 otherwise a pre-dependency will be needed on the ``adduser`` package.)
632 On the other hand, the program might be able to determine the uid or gid
633 from the user or group name at runtime, so that a dynamically allocated
634 id can be used. In this case you should choose an appropriate user or
635 group name, discussing this on ``debian-devel`` and checking that it is
636 unique. When this has been checked you must arrange for your package to
637 create the user or group if necessary using ``adduser`` in the
638 ``preinst`` or ``postinst`` script (again, the latter is to be preferred
641 Note that changing the numeric value of an id associated with a name is
642 very difficult, and involves searching the file system for all
643 appropriate files. You need to think carefully whether a static or
644 dynamic id is required, since changing your mind later will cause
649 The use of ``dpkg-statoverride``
650 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
652 This section is not intended as policy, but as a description of the use
653 of ``dpkg-statoverride``.
655 If a system administrator wishes to have a file (or directory or other
656 such thing) installed with owner and permissions different from those in
657 the distributed Debian package, they can use the ``dpkg-statoverride``
658 program to instruct ``dpkg`` to use the different settings every time
659 the file is installed. Thus the package maintainer should distribute the
660 files with their normal permissions, and leave it for the system
661 administrator to make any desired changes. For example, a daemon which
662 is normally required to be setuid root, but in certain situations could
663 be used without being setuid, should be installed setuid in the
664 ``.deb``. Then the local system administrator can change this if they
665 wish. If there are two standard ways of doing it, the package maintainer
666 can use ``debconf`` to find out the preference, and call
667 ``dpkg-statoverride`` in the maintainer script if necessary to
668 accommodate the system administrator's choice. Care must be taken during
669 upgrades to not override an existing setting.
671 Given the above, ``dpkg-statoverride`` is essentially a tool for system
672 administrators and would not normally be needed in the maintainer
673 scripts. There is one type of situation, though, where calls to
674 ``dpkg-statoverride`` would be needed in the maintainer scripts, and
675 that involves packages which use dynamically allocated user or group
676 ids. In such a situation, something like the following idiom can be very
677 helpful in the package's ``postinst``, where ``sysuser`` is a
678 dynamically allocated id:
682 for i in /usr/bin/foo /usr/sbin/bar; do
683 # only do something when no setting exists
684 if ! dpkg-statoverride --list $i >/dev/null 2>&1; then
685 #include: debconf processing, question about foo and bar
686 if [ "$RET" = "tru.. [#] ; then
687 dpkg-statoverride --update --add sysuser root 4755 $i
692 The corresponding code to remove the override when the package is purged
697 for i in /usr/bin/foo /usr/sbin/bar; do
698 if dpkg-statoverride --list $i >/dev/null 2>&1; then
699 dpkg-statoverride --remove $i
708 The name of the files installed by binary packages in the system PATH
709 (namely ``/bin``, ``/sbin``, ``/usr/bin``, ``/usr/sbin`` and
710 ``/usr/games``) must be encoded in ASCII.
712 The name of the files and directories installed by binary packages
713 outside the system PATH must be encoded in UTF-8 and should be
714 restricted to ASCII when it is possible to do so.
717 If you are using GCC, ``-fPIC`` produces code with relocatable
718 position independent code, which is required for most architectures
719 to create a shared library, with i386 and perhaps some others where
720 non position independent code is permitted in a shared library.
722 Position independent code may have a performance penalty, especially
723 on ``i386``. However, in most cases the speed penalty must be
724 measured against the memory wasted on the few architectures where non
725 position independent code is even possible.
728 Some of the reasons why this might be required is if the library
729 contains hand crafted assembly code that is not relocatable, the
730 speed penalty is excessive for compute intensive libs, and similar
734 Some of the reasons for linking static libraries with the ``-fPIC``
735 flag are if, for example, one needs a Perl API for a library that is
736 under rapid development, and has an unstable API, so shared libraries
737 are pointless at this phase of the library's development. In that
738 case, since Perl needs a library with relocatable code, it may make
739 sense to create a static library with relocatable code. Another
740 reason cited is if you are distilling various libraries into a common
741 shared library, like ``mklibs`` does in the Debian installer project.
744 You might also want to use the options ``--remove-section=.comment``
745 and ``--remove-section=.note`` on both shared libraries and
746 executables, and ``--strip-debug`` on static libraries.
749 A common example are the so-called "plug-ins", internal shared
750 objects that are dynamically loaded by programs using dlopen3.
753 These files store, among other things, all libraries on which that
754 shared library depends. Unfortunately, if the ``.la`` file is present
755 and contains that dependency information, using ``libtool`` when
756 linking against that library will cause the resulting program or
757 library to be linked against those dependencies as well, even if this
758 is unnecessary. This can create unneeded dependencies on shared
759 library packages that would otherwise be hidden behind the library
760 ABI, and can make library transitions to new SONAMEs unnecessarily
761 complicated and difficult to manage.
764 Single UNIX Specification, version 3, which is also IEEE 1003.1-2004
765 (POSIX), and is available on the World Wide Web from `The Open
766 Group <http://www.unix.org/version3/online.html>`_ after free
770 These features are in widespread use in the Linux community and are
771 implemented in all of bash, dash, and ksh, the most common shells
772 users may wish to use as ``/bin/sh``.
775 This is necessary to allow top-level directories to be symlinks. If
776 linking ``/var/run`` to ``/run`` were done with the relative symbolic
777 link ``../run``, but ``/var`` were a symbolic link to ``/srv/disk1``,
778 the symbolic link would point to ``/srv/run`` rather than the
782 It's better to use ``mkfifo`` rather than ``mknod`` to create named
783 pipes to avoid false positives from automated checks for packages
784 incorrectly creating device files.
787 The ``dpkg-maintscript-helper`` tool, available from the dpkg
788 package, can help for this task.
791 Rationale: There are two problems with hard links. The first is that
792 some editors break the link while editing one of the files, so that
793 the two files may unwittingly become unlinked and different. The
794 second is that ``dpkg`` might break the hard link while upgrading
798 The traditional approach to log files has been to set up *ad hoc* log
799 rotation schemes using simple shell scripts and cron. While this
800 approach is highly customizable, it requires quite a lot of sysadmin
801 work. Even though the original Debian system helped a little by
802 automatically installing a system which can be used as a template,
803 this was deemed not enough.
805 The use of ``logrotate``, a program developed by Red Hat, is better,
806 as it centralizes log management. It has both a configuration file
807 (``/etc/logrotate.conf``) and a directory where packages can drop
808 their individual log rotation configurations (``/etc/logrotate.d``).
811 When a package is upgraded, and the owner or permissions of a file
812 included in the package has changed, dpkg arranges for the ownership
813 and permissions to be correctly set upon installation. However, this
814 does not extend to directories; the permissions and ownership of
815 directories already on the system does not change on install or
816 upgrade of packages. This makes sense, since otherwise common
817 directories like ``/usr`` would always be in flux. To correctly
818 change permissions of a directory the package owns, explicit action
819 is required, usually in the ``postinst`` script. Care must be taken
820 to handle downgrades as well, in that case.
823 Ordinary files installed by ``dpkg`` (as opposed to ``conffile``\ s
824 and other similar objects) normally have their permissions reset to
825 the distributed permissions when the package is reinstalled. However,
826 the use of ``dpkg-statoverride`` overrides this default behavior.