- <p>
- In our example, if the first version of the <tt>zlib1g</tt>
- package which contained a minor number of at least
- <tt>1.3</tt> was <var>1:1.1.3-1</var>, then the
- <tt>shlibs</tt> entry for this library could say:
- <example compact="compact">
-libz 1 zlib1g (>= 1:1.1.3)
- </example>
- The version-specific dependency is to avoid warnings from
- the dynamic linker about using older shared libraries with
- newer binaries.
- </p>
- </sect1>
-
- <sect1>
- <heading>Providing a <file>shlibs</file> file</heading>
-
- <p>
- If your package provides a shared library, you should create
- a <file>shlibs</file> file following the format described above.
- It is usual to call this file <file>debian/shlibs</file> (but if
- you have multiple binary packages, you might want to call it
- <file>debian/shlibs.<var>package</var></file> instead). Then
- let <file>debian/rules</file> install it in the control area:
- <example compact="compact">
-install -m644 debian/shlibs debian/tmp/DEBIAN
- </example>
- or, in the case of a multi-binary package:
- <example compact="compact">
-install -m644 debian/shlibs.<var>package</var> debian/<var>package</var>/DEBIAN/shlibs
- </example>
- An alternative way of doing this is to create the
- <file>shlibs</file> file in the control area directly from
- <file>debian/rules</file> without using a <file>debian/shlibs</file>
- file at all,<footnote>
- This is what <prgn>dh_makeshlibs</prgn> in the
- <tt>debhelper</tt> suite does.
- </footnote>
- since the <file>debian/shlibs</file> file itself is ignored by
- <prgn>dpkg-shlibdeps</prgn>.
- </p>
-
- <p>
- As <prgn>dpkg-shlibdeps</prgn> reads the
- <file>DEBIAN/shlibs</file> files in all of the binary packages
- being built from this source package, all of the
- <file>DEBIAN/shlibs</file> files should be installed before
- <prgn>dpkg-shlibdeps</prgn> is called on any of the binary
- packages.
- </p>
- </sect1>
-
- <sect1 id="shlibslocal">
- <heading>Writing the <file>debian/shlibs.local</file> file</heading>
-
- <p>
- This file is intended only as a <em>temporary</em> fix if
- your binaries or libraries depend on a library whose package
- does not yet provide a correct <file>shlibs</file> file.
- </p>
-
- <p>
- We will assume that you are trying to package a binary
- <tt>foo</tt>. When you try running
- <prgn>dpkg-shlibdeps</prgn> you get the following error
- message (<tt>-O</tt> displays the dependency information on
- <tt>stdout</tt> instead of writing it to
- <tt>debian/substvars</tt>, and the lines have been wrapped
- for ease of reading):
- <example compact="compact">
-$ dpkg-shlibdeps -O debian/tmp/usr/bin/foo
-dpkg-shlibdeps: warning: unable to find dependency
- information for shared library libbar (soname 1,
- path /usr/lib/libbar.so.1, dependency field Depends)
-shlibs:Depends=libc6 (>= 2.2.2-2)
- </example>
- You can then run <prgn>ldd</prgn> on the binary to find the
- full location of the library concerned:
- <example compact="compact">
-$ ldd foo
-libbar.so.1 => /usr/lib/libbar.so.1 (0x4001e000)
-libc.so.6 => /lib/libc.so.6 (0x40032000)
-/lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
- </example>
- So the <prgn>foo</prgn> binary depends on the
- <prgn>libbar</prgn> shared library, but no package seems to
- provide a <file>*.shlibs</file> file handling
- <file>libbar.so.1</file> in <file>/var/lib/dpkg/info/</file>. Let's
- determine the package responsible:
- <example compact="compact">
-$ dpkg -S /usr/lib/libbar.so.1
-bar1: /usr/lib/libbar.so.1
-$ dpkg -s bar1 | grep Version
-Version: 1.0-1
- </example>
- This tells us that the <tt>bar1</tt> package, version 1.0-1,
- is the one we are using. Now we can file a bug against the
- <tt>bar1</tt> package and create our own
- <file>debian/shlibs.local</file> to locally fix the problem.
- Including the following line into your
- <file>debian/shlibs.local</file> file:
- <example compact="compact">
-libbar 1 bar1 (>= 1.0-1)
- </example>
- should allow the package build to work.
- </p>
-
- <p>
- As soon as the maintainer of <tt>bar1</tt> provides a
- correct <file>shlibs</file> file, you should remove this line
- from your <file>debian/shlibs.local</file> file. (You should
- probably also then have a versioned <tt>Build-Depends</tt>
- on <tt>bar1</tt> to help ensure that others do not have the
- same problem building your package.)
- </p>
- </sect1>
-
- </sect>
-
- </chapt>
-
- <chapt id="opersys"><heading>The Operating System</heading>
-
- <sect>
- <heading>Filesystem hierarchy</heading>
-
-
- <sect1 id="fhs">
- <heading>Filesystem Structure</heading>
-
- <p>
- The location of all installed files and directories must
- comply with the Filesystem Hierarchy Standard (FHS),
- version 2.1, except where doing so would violate other
- terms of Debian Policy. The version of this document
- referred here can be found in the <tt>debian-policy</tt>
- package or on
- <url id="http://www.debian.org/doc/packaging-manuals/fhs/"
- name="FHS (Debian copy)"> alongside this manual (or, if
- you have the <package>debian-policy</package> installed,
- you can try <url
- id="file:///usr/share/doc/debian-policy/fhs/" name="FHS
- (local copy)">). The
- latest version, which may be a more recent version, may
- be found on
- <url id="http://www.pathname.com/fhs/" name="FHS (upstream)">.
- Specific questions about following the standard may be
- asked on the <tt>debian-devel</tt> mailing list, or
- referred to the FHS mailing list (see the
- <url id="http://www.pathname.com/fhs/" name="FHS web site"> for
- more information).
- </p>
- </sect1>
-
- <sect1>
- <heading>Site-specific programs</heading>
-
- <p>
- As mandated by the FHS, packages must not place any
- files in <file>/usr/local</file>, either by putting them in
- the file system archive to be unpacked by <prgn>dpkg</prgn>
- or by manipulating them in their maintainer scripts.
- </p>
-
- <p>
- However, the package may create empty directories below
- <file>/usr/local</file> so that the system administrator knows
- where to place site-specific files. These directories
- should be removed on package removal if they are
- empty.
- </p>
-
- <p>
- Note, that this applies only to directories <em>below</em>
- <file>/usr/local</file>, not <em>in</em> <file>/usr/local</file>.
- Packages must not create sub-directories in the directory
- <file>/usr/local</file> itself, except those listed in FHS,
- section 4.5. However, you may create directories below
- them as you wish. You must not remove any of the
- directories listed in 4.5, even if you created them.
- </p>
-
- <p>
- Since <file>/usr/local</file> can be mounted read-only from a
- remote server, these directories must be created and
- removed by the <prgn>postinst</prgn> and <prgn>prerm</prgn>
- maintainer scripts and not be included in the
- <file>.deb</file> archive. These scripts must not fail if
- either of these operations fail.
- </p>
-
- <p>
- For example, the <tt>emacsen-common</tt> package could
- contain something like
- <example compact="compact">
-if [ ! -e /usr/local/share/emacs ]
-then
- if mkdir /usr/local/share/emacs 2>/dev/null
- then
- chown root:staff /usr/local/share/emacs
- chmod 2775 /usr/local/share/emacs
- fi
-fi
- </example>
- in its <prgn>postinst</prgn> script, and
- <example compact="compact">
-rmdir /usr/local/share/emacs/site-lisp 2>/dev/null || true
-rmdir /usr/local/share/emacs 2>/dev/null || true
- </example>
- in the <prgn>prerm</prgn> script. (Note that this form is
- used to ensure that if the script is interrupted, the
- directory <file>/usr/local/share/emacs</file> will still be
- removed.)
- </p>
-
- <p>
- If you do create a directory in <file>/usr/local</file> for
- local additions to a package, you should ensure that
- settings in <file>/usr/local</file> take precedence over the
- equivalents in <file>/usr</file>.
- </p>
-
- <p>
- However, because <file>/usr/local</file> and its contents are
- for exclusive use of the local administrator, a package
- must not rely on the presence or absence of files or
- directories in <file>/usr/local</file> for normal operation.
- </p>
-
- <p>
- The <file>/usr/local</file> directory itself and all the
- subdirectories created by the package should (by default) have
- permissions 2775 (group-writable and set-group-id) and be
- owned by <tt>root.staff</tt>.
- </p>
- </sect1>
-
- <sect1>
- <heading>The system-wide mail directory</heading>
- <p>
- The system-wide mail directory is <file>/var/mail</file>. This
- directory is part of the base system and should not owned
- by any particular mail agents. The use of the old
- location <file>/var/spool/mail</file> is deprecated, even
- though the spool may still be physically located there.
- To maintain partial upgrade compatibility for systems
- which have <file>/var/spool/mail</file> as their physical mail
- spool, packages using <file>/var/mail</file> must depend on
- either <package>libc6</package> (>= 2.1.3-13), or on
- <package>base-files</package> (>= 2.2.0), or on later
- versions of either one of these packages.
- </p>
- </sect1>
- </sect>
-
- <sect>
- <heading>Users and groups</heading>
-
- <sect1>
- <heading>Introduction</heading>
- <p>
- The Debian system can be configured to use either plain or
- shadow passwords.
- </p>
-
- <p>
- Some user ids (UIDs) and group ids (GIDs) are reserved
- globally for use by certain packages. Because some
- packages need to include files which are owned by these
- users or groups, or need the ids compiled into binaries,
- these ids must be used on any Debian system only for the
- purpose for which they are allocated. This is a serious
- restriction, and we should avoid getting in the way of
- local administration policies. In particular, many sites
- allocate users and/or local system groups starting at 100.
- </p>
-
- <p>
- Apart from this we should have dynamically allocated ids,
- which should by default be arranged in some sensible
- order, but the behavior should be configurable.
- </p>
-
- <p>
- Packages other than <tt>base-passwd</tt> must not modify
- <file>/etc/passwd</file>, <file>/etc/shadow</file>,
- <file>/etc/group</file> or <file>/etc/gshadow</file>.
- </p>
- </sect1>
-
- <sect1>
- <heading>UID and GID classes</heading>
- <p>
- The UID and GID numbers are divided into classes as
- follows:
- <taglist>
- <tag>0-99:</tag>
- <item>
- <p>
- Globally allocated by the Debian project, the same
- on every Debian system. These ids will appear in
- the <file>passwd</file> and <file>group</file> files of all
- Debian systems, new ids in this range being added
- automatically as the <tt>base-passwd</tt> package is
- updated.
- </p>
-
- <p>
- Packages which need a single statically allocated
- uid or gid should use one of these; their
- maintainers should ask the <tt>base-passwd</tt>
- maintainer for ids.
- </p>
- </item>
-
- <tag>100-999:</tag>
- <item>
- <p>
- Dynamically allocated system users and groups.
- Packages which need a user or group, but can have
- this user or group allocated dynamically and
- differently on each system, should use <tt>adduser
- --system</tt> to create the group and/or user.
- <prgn>adduser</prgn> will check for the existence of
- the user or group, and if necessary choose an unused
- id based on the ranges specified in
- <file>adduser.conf</file>.
- </p>
- </item>
-
- <tag>1000-29999:</tag>
- <item>
- <p>
- Dynamically allocated user accounts. By default
- <prgn>adduser</prgn> will choose UIDs and GIDs for
- user accounts in this range, though
- <file>adduser.conf</file> may be used to modify this
- behavior.
- </p>
- </item>
-
- <tag>30000-59999:</tag>
- <item>
- <p>Reserved.</p>
- </item>
-
- <tag>60000-64999:</tag>
- <item>
- <p>
- Globally allocated by the Debian project, but only
- created on demand. The ids are allocated centrally
- and statically, but the actual accounts are only
- created on users' systems on demand.
- </p>
-
- <p>
- These ids are for packages which are obscure or
- which require many statically-allocated ids. These
- packages should check for and create the accounts in
- <file>/etc/passwd</file> or <file>/etc/group</file> (using
- <prgn>adduser</prgn> if it has this facility) if
- necessary. Packages which are likely to require
- further allocations should have a "hole" left after
- them in the allocation, to give them room to
- grow.
- </p>
- </item>
-
- <tag>65000-65533:</tag>
- <item>
- <p>Reserved.</p>
- </item>
-
- <tag>65534:</tag>
- <item>
- <p>
- User <tt>nobody</tt>. The corresponding gid refers
- to the group <tt>nogroup</tt>.
- </p>
- </item>
-
- <tag>65535:</tag>
- <item>
- <p>
- <tt>(uid_t)(-1) == (gid_t)(-1)</tt> <em>must
- not</em> be used, because it is the error return
- sentinel value.
- </p>
- </item>
- </taglist>
- </p>
- </sect1>
- </sect>
-
- <sect id="sysvinit">
- <heading>System run levels and <file>init.d</file> scripts</heading>
-
- <sect1 id="/etc/init.d">
- <heading>Introduction</heading>
-
- <p>
- The <file>/etc/init.d</file> directory contains the scripts
- executed by <prgn>init</prgn> at boot time and when the
- init state (or "runlevel") is changed (see <manref
- name="init" section="8">).
- </p>
-
- <p>
- There are at least two different, yet functionally
- equivalent, ways of handling these scripts. For the sake
- of simplicity, this document describes only the symbolic
- link method. However, it must not be assumed by maintainer
- scripts that this method is being used, and any automated
- manipulation of the various runlevel behaviours by
- maintainer scripts must be performed using
- <prgn>update-rc.d</prgn> as described below and not by
- manually installing or removing symlinks. For information
- on the implementation details of the other method,
- implemented in the <tt>file-rc</tt> package, please refer
- to the documentation of that package.
- </p>
-
- <p>
- These scripts are referenced by symbolic links in the
- <file>/etc/rc<var>n</var>.d</file> directories. When changing
- runlevels, <prgn>init</prgn> looks in the directory
- <file>/etc/rc<var>n</var>.d</file> for the scripts it should
- execute, where <tt><var>n</var></tt> is the runlevel that
- is being changed to, or <tt>S</tt> for the boot-up
- scripts.
- </p>
-
- <p>
- The names of the links all have the form
- <file>S<var>mm</var><var>script</var></file> or
- <file>K<var>mm</var><var>script</var></file> where
- <var>mm</var> is a two-digit number and <var>script</var>
- is the name of the script (this should be the same as the
- name of the actual script in <file>/etc/init.d</file>).
- </p>
-
- <p>
- When <prgn>init</prgn> changes runlevel first the targets
- of the links whose names start with a <tt>K</tt> are
- executed, each with the single argument <tt>stop</tt>,
- followed by the scripts prefixed with an <tt>S</tt>, each
- with the single argument <tt>start</tt>. (The links are
- those in the <file>/etc/rc<var>n</var>.d</file> directory
- corresponding to the new runlevel.) The <tt>K</tt> links
- are responsible for killing services and the <tt>S</tt>
- link for starting services upon entering the runlevel.
- </p>
-
- <p>
- For example, if we are changing from runlevel 2 to
- runlevel 3, init will first execute all of the <tt>K</tt>
- prefixed scripts it finds in <file>/etc/rc3.d</file>, and then
- all of the <tt>S</tt> prefixed scripts in that directory.
- The links starting with <tt>K</tt> will cause the
- referred-to file to be executed with an argument of
- <tt>stop</tt>, and the <tt>S</tt> links with an argument
- of <tt>start</tt>.
- </p>
-
- <p>
- The two-digit number <var>mm</var> is used to determine
- the order in which to run the scripts: low-numbered links
- have their scripts run first. For example, the
- <tt>K20</tt> scripts will be executed before the
- <tt>K30</tt> scripts. This is used when a certain service
- must be started before another. For example, the name
- server <prgn>bind</prgn> might need to be started before
- the news server <prgn>inn</prgn> so that <prgn>inn</prgn>
- can set up its access lists. In this case, the script
- that starts <prgn>bind</prgn> would have a lower number
- than the script that starts <prgn>inn</prgn> so that it
- runs first:
- <example compact="compact">
-/etc/rc2.d/S17bind
-/etc/rc2.d/S70inn
- </example>
- </p>
-
- <p>
- The two runlevels 0 (halt) and 6 (reboot) are slightly
- different. In these runlevels, the links with an
- <tt>S</tt> prefix are still called after those with a
- <tt>K</tt> prefix, but they too are called with the single
- argument <tt>stop</tt>.
- </p>
-
- <p>
- Also, if the script name ends <tt>.sh</tt>, the script
- will be sourced in runlevel <tt>S</tt> rather that being
- run in a forked subprocess, but will be explicitly run by
- <prgn>sh</prgn> in all other runlevels.
- </p>
- </sect1>
-
- <sect1>
- <heading>Writing the scripts</heading>
-
- <p>
- Packages that include daemons for system services should
- place scripts in <file>/etc/init.d</file> to start or stop
- services at boot time or during a change of runlevel.
- These scripts should be named
- <file>/etc/init.d/<var>package</var></file>, and they should
- accept one argument, saying what to do:
-
- <taglist>
- <tag><tt>start</tt></tag>
- <item>start the service,</item>
-
- <tag><tt>stop</tt></tag>
- <item>stop the service,</item>
-
- <tag><tt>restart</tt></tag>
- <item>stop and restart the service if it's already running,
- otherwise start the service</item>