chiark / gitweb /
Fixed removal code based on suggestions made by Jonas Meurer
[developers-reference.git] / developers-reference.sgml
index 11e387d3e976105d3f682b8b7f93c46a1f0b4a31..ffd88a593d2847320cbcf7f2a7540db718c4affb 100644 (file)
@@ -7,7 +7,7 @@
   <!ENTITY % dynamicdata  SYSTEM "dynamic.ent" > %dynamicdata;
 
   <!-- CVS revision of this document -->
-  <!ENTITY cvs-rev "$Revision: 1.263 $">
+  <!ENTITY cvs-rev "$Revision: 1.280 $">
 
   <!-- if you are translating this document, please notate the CVS
        revision of the original developer's reference in cvs-en-rev -->
@@ -58,6 +58,7 @@ writing to the &fsf-addr;.
        <p>
 If you want to print this reference, you should use the <url
 id="developers-reference.pdf" name="pdf version">.
+This page is also available in <url id="index.fr.html" name="French">.
 ]]>
 
     <toc detail="sect1">
@@ -309,13 +310,12 @@ can update the Debian key ring by sending your key to the key server at
 <tt>&keyserver-host;</tt>.
        <p>
 If you need to add a completely new key or remove an old key, you need
-to get the new key signed by another developer. After this, a mail
-signed by another developer listing your account name, the keyids
-of the old and of the new key and the reason should be send to
-&email-debian-keyring;. If the old key is compromised or invalid, you
+to get the new key signed by another developer. 
+If the old key is compromised or invalid, you
 also have to add the revocation certificate. If there is no real
-reason for a new key, the Keyring Maintainers will only accept it if
-it's more secure and connected to the old key.
+reason for a new key, the Keyring Maintainers might reject the new key.
+Details can be found at 
+<url id="http://keyring.debian.org/replacing_keys.html">.
        <p>
 The same key extraction routines discussed in <ref id="registering">
 apply. 
@@ -669,17 +669,10 @@ an email to &email-ftpmaster;, but also see the procedures in
 
       <sect1 id="servers-non-us">The non-US server
        <p>
-The non-US server, <tt>non-us.debian.org</tt>,
-holds the canonical copy of the non-US part of the Debian archive.
-If you need to upload a package into one of the non-US sections, upload it
-to this server; see <ref id="upload-non-us">.
-       <p>
-Problems with the non-US package archive should generally be submitted as
-bugs against the <package>nonus.debian.org</package> pseudo-package (notice
-the lack of hyphen between "non" and "us" in the pseudo-package name
-&mdash; that's for backwards compatibility). Remember to check whether or
-not someone else has already reported the problem to the
-<url id="http://&bugs-host;/nonus.debian.org" name="Bug Tracking System">.
+The non-US server <tt>non-us.debian.org</tt>
+was discontinued with the release of sarge. The pseudo-package
+<package>nonus.debian.org</package>
+stil exists for now.
 
       <sect1 id="servers-www">The www-master server
        <p>
@@ -710,8 +703,7 @@ whereas on other hosts it won't.
        <p>
 Usually the only reason to use a different host is when you need to publish
 materials subject to the U.S. export restrictions, in which case you can use
-one of the other servers located outside the United States, such as the
-aforementioned <tt>non-us.debian.org</tt>.
+one of the other servers located outside the United States.
        <p>
 Send mail to &email-debian-devel; if you have any questions.
 
@@ -969,14 +961,17 @@ which control how packages move from <em>unstable</em> to <em>testing</em> are
 tightened.  Packages which are too buggy are removed.  No changes are
 allowed into <em>testing</em> except for bug fixes.  After some time
 has elapsed, depending on progress, the <em>testing</em> distribution
-goes into a `deep freeze', when no changes are made to it except those
-needed for the installation system.  This is called a &ldquo;test cycle&rdquo;,
-and it can last up to two weeks. There can be several test cycles,
-until the distribution is prepared for release, as decided by the
-release manager.  At the end of the last test cycle, the
-<em>testing</em> distribution is renamed to <em>stable</em>,
-overriding the old <em>stable</em> distribution, which is removed at
-that time (although it can be found at <tt>&archive-host;</tt>).
+is frozen even further.
+Details of the handling of the testing distribution are published
+by the Release Team on debian-devel-announce.
+After the open issues are solved to the satisfaction of the Release Team,
+the distribution is released.
+Releasing means
+that <em>testing</em> is renamed to <em>stable</em>,
+and a new copy is created for the new <em>testing</em>,
+and the previous <em>stable</em> is renamed to <em>oldstable</em>
+and stays there until it is finally archived.
+On archiving, the contents are moved to <tt>&archive-host;</tt>).
        <p>
 This development cycle is based on the assumption that the
 <em>unstable</em> distribution becomes <em>stable</em> after passing a
@@ -992,6 +987,9 @@ batch into the stable distribution and the revision level of the
 stable distribution is incremented (e.g., &lsquo;3.0&rsquo; becomes
 &lsquo;3.0r1&rsquo;, &lsquo;2.2r4&rsquo; becomes &lsquo;2.2r5&rsquo;, and
 so forth).
+Please refer to
+<qref id="upload-stable">uploads to the <em>stable</em> distribution</qref>
+for details.
        <p>
 Note that development under <em>unstable</em> continues during the
 freeze period, since the <em>unstable</em> distribution remains in
@@ -1125,8 +1123,7 @@ have accounts on these machines.
        <p>
 The Incoming system is responsible for collecting updated packages and
 installing them in the Debian archive. It consists of a set of
-directories and scripts that are installed both on <tt>&ftp-master-host;</tt>
-and <tt>&non-us-host;</tt>.
+directories and scripts that are installed on <tt>&ftp-master-host;</tt>.
        <p>
 Packages are uploaded by all the maintainers into a directory called
 <file>UploadQueue</file>. 
@@ -1245,7 +1242,7 @@ You can view the bugs of a given package at the URL
       <sect1 id="madison">The <prgn>madison</prgn> utility
         <p>
 <prgn>madison</prgn> is a command-line utility that is available
-on both <tt>&ftp-master-host;</tt> and <tt>&non-us-host;</tt>, and on
+on <tt>&ftp-master-host;</tt>, and on
 the mirror on <tt>&ftp-master-mirror;</tt>. It
 uses a single argument corresponding to a package name. In result
 it displays which version of the package is available for each
@@ -1537,8 +1534,23 @@ by Debian, facilitate contributions from external developers to projects
 started by Debian, and help projects whose goals are the promotion of Debian
 or its derivatives.
        <p>
+All Debian developers automatically have an account on Alioth.
+They can activate it by using the recover password facility.
+External developers can request guest accounts on Alioth.
+        <p>
 For more information please visit <url id="&url-alioth;">.
 
+    <sect id="developer-misc">Goodies for Developers
+        <p>
+     <sect1 id="lwn">LWN Subscriptions
+        <p>
+Since October of 2002, HP has sponsored a subscription to LWN for all 
+interested Debian developers.
+
+Details on how to get access to this benefit are in
+<url id="http://lists.debian.org/debian-devel-announce/2002/10/msg00018.html">.
+
+
 
    <chapt id="pkgs">Managing Packages
        <p>
@@ -1791,20 +1803,6 @@ the changes file last.  Otherwise, your upload may be rejected because the
 archive maintenance software will parse the changes file and see that not
 all files have been uploaded.
          <p>
-<!-- FIXME: is this still topical? Explain the rationale? -->
-<em>Note:</em> Do not upload to <tt>ftp-master</tt> cryptographic
-packages which belong to <em>contrib</em> or <em>non-free</em>. Uploads of
-such software should go to <tt>non-us</tt> (see <ref
-id="upload-non-us">). Furthermore packages containing code that is
-patent-restricted by the United States government cannot be uploaded to
-<tt>ftp-master</tt>; depending on the case they may still be uploaded to
-<file>non-US/non-free</file> (it's in non-free because of distribution issues
-and not because of the license of the software). If you can't upload it to
-<tt>ftp-master</tt>, then neither can you upload it to backup
-queues that finally also end up on <tt>ftp-master</tt>. If you are not sure
-whether U.S. patent controls or cryptographic controls apply to your
-package, post a message to &email-debian-devel; and ask.
-         <p>
 You may also find the Debian packages <ref id="dupload"> or
 <ref id="dput"> useful
 when uploading packages. These handy programs help automate the
@@ -1815,41 +1813,7 @@ and the Debian package <ref id="dcut">.
 
        <sect1 id="upload-non-us">Uploading to <tt>non-US</tt>
          <p>
-<em>Note:</em> non-us is currently not processed any more.
-         <p>
-As discussed above, export controlled software should not be uploaded
-to <tt>ftp-master</tt>.  Instead, upload the package with anonymous FTP
-to <ftpsite>non-us.debian.org</ftpsite>, placing the files in
-&upload-queue; (again, both <ref id="dupload"> and <ref
-id="dput"> can do this for you if invoked properly).
-         <p>
-Note that U.S. residents or citizens are subject to restrictions on
-export of cryptographic software. As of this writing, U.S. citizens
-are allowed to export some cryptographic software, subject to
-notification rules by the U.S. Department of Commerce.  However, this
-restriction has been waived for software which is already available
-outside the U.S.  Therefore, any cryptographic software which belongs
-in the <em>main</em> section of the Debian archive and does not depend
-on any package outside of <em>main</em> (e.g., does not depend on
-anything in <em>non-US/main</em>) can be uploaded to <tt>ftp-master</tt>
-or its queues, described above.
-         <p>
-Debian policy does not prevent upload to non-US by U.S. residents or
-citizens, but care should be taken in doing so. It is recommended that
-developers take all necessary steps to ensure that they are not
-breaking current US law by doing an upload to non-US, <em>including
-consulting a lawyer</em>.
-         <p>
-For packages in <em>non-US/main</em>, <em>non-US/contrib</em>,
-developers should at least follow the <url id="&url-u.s.-export;"
-name="procedure outlined by the US Government">.  Maintainers of
-<em>non-US/non-free</em> packages should further consult the <url
-id="&url-notification-of-export;" name="rules on notification of
-export"> of non-free software.
-         <p>
-This section is for information only and does not constitute legal
-advice. Again, it is strongly recommended that U.S. citizens and
-residents consult a lawyer before doing uploads to non-US.
+<em>Note:</em> non-us was discontinued with release of sarge.
 
 
        <sect1 id="delayed-incoming">Delayed uploads
@@ -1882,7 +1846,7 @@ For details, please see section <ref id="bug-security">.
 
        <sect1>Other upload queues
          <p>
-The scp queues on ftp-master, non-us, and security are mostly unusable
+The scp queues on ftp-master, and security are mostly unusable
 due to the login restrictions on those hosts.
          <p>
 The anonymous queues on ftp.uni-erlangen.de and ftp.uk.debian.org are
@@ -1948,7 +1912,7 @@ or priority for your package be changed from the old section or
 priority to the new one.  Be sure to explain your reasoning.
        <p>
 For more information about <em>override files</em>, see <manref
-name="dpkg-scanpackages" section="8"> and
+name="dpkg-scanpackages" section="1"> and
 <url id="&url-bts-devel;#maintincorrect">.
        <p>
 Note that the <tt>Section</tt> field describes both the section as
@@ -2877,7 +2841,56 @@ different sub-flavors of Debian, which may or may not really be of
 general interest (for instance, a flavor of Debian built with <prgn>gcc</prgn>
 bounds checking).  It will also enable Debian to recompile entire
 distributions quickly.
-          </sect2>
+          <p>
+The buildds admins of each arch can be contacted by the mail address
+$arch@buildd.debian.org.
+
+       <sect1 id="packages-arch-specific">When your package is <em>not</em> portable
+       <p>
+Some packages still have issues with building and/or working on some
+of the architectures supported by Debian, and cannot be ported at all,
+or not with a reasonable amount of time. An example is a package that
+is SVGA-specific (only i386), or uses other hardware-specific features
+not supported on all architectures.
+       <p>
+In order to prevent broken packages from being uploaded to the archive, and
+wasting buildd time, you need to do a few things:
+       <p>
+      <list>
+      <item>
+       <p>
+First, make sure your package <em>does</em> fail to build on
+architectures that it cannot support.
+There are a few ways to achieve this.
+The preferred way is to have a small testsuite during build time
+that will test the functionality, and fail if it doesn't work.
+This is a good idea anyway,
+as this will prevent (some) broken uploads on all architectures,
+and also will allow the package to build
+as soon as the required functionality is available.
+       <p>
+Additionally, if you believe the list of supported architectures is
+pretty constant, you should change 'any' to a list of supported
+architectures in debian/control.  This way, the build will fail also,
+and indicate this to a human reader without actually trying.
+      <item>
+       <p>
+In order to prevent autobuilders from needlessly trying to build your
+package, it must be included in <file>packages-arch-specific</file>, a
+list used by the <prgn>wanna-build</prgn> script.
+The current version is available as
+<url id="http://cvs.debian.org/srcdep/Packages-arch-specific?rev=HEAD&amp;cvsroot=dak&amp;content-type=text/vnd.viewcvs-markup">;
+please see the top of the file for whom to contact for changes.
+      </list>
+       <p>
+Please note that it is insufficient to only add your package to
+Packages-arch-specific
+without making it fail to build on unsupported architectures:
+A porter or any other person trying to build your package might
+accidently upload it without noticing it doesn't work.
+If in the past some binary packages were uploaded on unsupported architectures,
+request there removal by filing a bug against
+<package>ftp.debian.org</package>
 
 
     <sect id="nmu">Non-Maintainer Uploads (NMUs)
@@ -4047,6 +4060,409 @@ before the <file>/usr</file> partition is mounted. Most scripts won't have
 this problem, though.
       </sect>
 
+      <sect id="bpp-debian-security-audit">
+        <heading>Best practices for security review and design</heading>
+
+<p>When you are packaging software for other users you should make a
+best effort to ensure that the installation of the software, or its
+use, does not introduce security risks to either the system it is
+installed on or its users.</p>
+
+<p>You should make your best to review the source code of the package and
+detect issues that might introduce security bugs. The programming bugs
+which lead to security bugs typically include: <url
+id="http://en.wikipedia.org/wiki/Buffer_overflow" name="buffer
+overflows">, <url
+id="http://en.wikipedia.org/wiki/Cross_site_scripting" name="format
+string overflows">, <url
+id="http://en.wikipedia.org/wiki/Cross_site_scripting" name="heap
+overflows"> and <url
+id="http://en.wikipedia.org/wiki/Cross_site_scripting" name="integer
+overflows"> (in C/C++ programs), temporary <url
+id="http://en.wikipedia.org/wiki/Symlink_race" name="symlink race
+conditions"> (in scripts), <url
+id="http://en.wikipedia.org/wiki/Directory_traversal" name="directory
+traversal"> and command injection (in servers) and <url
+id="http://en.wikipedia.org/wiki/Cross_site_scripting"
+name="cross-site scripting">, and <url
+id="http://en.wikipedia.org/wiki/Cross_site_scripting" name="SQL
+injection bugs"> (in the case of web-oriented applications).</p>
+
+<p>Some of these issues might not be easy to spot unless you are an
+expert in the programming language the program uses, but some security
+problems are easy to detect and fix. For example, finding temporary
+race conditions in the source code can easily be done by running
+<tt>grep -r "/tmp/" .</tt> in the source code replace
+hardcoded filenames using temporary directories to calls to either
+<prgn>mktemp</prgn> or <prgn>tempfile</prgn> in shell
+scripts, <manref name="File::Temp" section="3perl"> in Perl scripts,
+and <manref name="tmpfile" section="3"> in C/C++.  You can also use
+<url id="http://www.debian.org/security/audit/tools" name="specific
+tools"> to assist to the security code review phase.</p>
+
+<p>When packaging software make sure that:
+
+<list>
+
+<item>The software runs with the minimum privileges it needs:
+
+<list>
+<item>The package does install binaries setuid or setgid.
+<prgn>Lintian</prgn> will warn of <url id="
+http://lintian.debian.org/reports/Tsetuid-binary.html" name="setuid">,
+<url id="http://lintian.debian.org/reports/Tsetgid-binary.html"
+name="setgid"> and <url
+id="http://lintian.debian.org/reports/Tsetuid-gid-binary.html"
+name="setuid and setgid"> binaries.
+
+<item>The daemons the package provide run with a 
+low privilege user (see <ref id="bpp-lower-privs">)
+
+</list>
+
+<item>Programmed (i.e., <prgn>cron</prgn>) tasks running in the
+system do NOT run as root or, if they do, do not implement complex
+tasks.
+
+</list>
+
+<p>If you have to do any of the above make sure the programs that
+might run with higher privileges have been audited for security
+bugs. If you are unsure, or need help, contact the <url
+id="http://www.debian.org/security/audit/" name="Debian Security Audit
+team">. In the case of setuid/setgid binaries, follow the Debian
+policy section regarding 
+<url id="http://www.debian.org/doc/debian-policy/ch-files.html#s10.9"
+name="permissions and owners">
+</p>
+
+<p>For more information, specific to secure programming, make sure you
+read (or point your upstream to) <url
+id="http://www.dwheeler.com/secure-programs/" name="Secure Programming
+for Linux and Unix HOWTO"> and the <url
+id="https://buildsecurityin.us-cert.gov/portal/" name="Build Security
+In"> portal. For more information specific to Debian security you can
+read the <url
+id="http://www.debian.org/doc/manuals/securing-debian-howto/"
+name="Debian Security Manual">
+</p>
+
+<!-- This should be explained here until #291177 gets fixed and this is
+       added to poliy -->
+
+       <sect1 id="bpp-lower-privs">
+         <heading>System users and groups for software daemons
+
+<p>If your software runs a daemon that does not need root privileges,
+you need to create a user for it. There are two kind of Debian users
+that can be used by packages: static uids (assigned by
+<package>base-passwd</package>) and dynamic uids in the range assigned
+to system users.
+
+<p>In the first case, you need to ask for a user or group id to the
+<package>base-passwd</package>, and a proper versioned depends to the
+<package>base-passwd</package> package that provides the user.
+
+<p>In the second case, you need to create the system user through maintainer
+scripts. <url id="http://www.debian.org/doc/debian-policy/ch-files.html#s10.9"
+name="policy"> requires you discuss an appropiate user and group name on
+<em>debian-devel</em> and make sure it is unique and does not overlap
+with other packages.
+
+<p>Running programs with a user with limited privileges makes sure
+that any security issue with the program makes limited damaged to the
+system and follows the principle of <em>least privilege</em> you can
+limit privileges in programs through other mechanisms besides running
+as non-root. Fore more information, read the <url
+id="http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/minimize-privileges.html"
+name="Minimize Privileges"> chapter of the <em>Secure Programming for
+Linux and Unix HOWTO</em> book.
+
+       <sect2 id="bpp-create-sysuser">
+         <heading>Creating system users and groups
+
+<p>If you want to create system groups on package installation you
+need to create it in either the <em>preinst</em> or in the <em>postinst</em>
+and have the package depend on <tt>adduser (>= 3.11)</tt>.
+
+<p>The following example code creates the user and group the daemon
+will run as when the package is installed or upgraded:
+
+<example>
+[...]
+case "$1" in
+    install|upgrade)
+
+       # If the package has default file it could be sourced, so that
+       # the local admin can overwrite the defaults
+       # Notice that the package could handle this defaults through
+       # debconf so that the local admin could select a different 
+       # user name for the system user than the one hardcoded in the
+       # package
+
+       [ -f "/etc/default/<var>packagename</var>" ] && . /etc/default/<var>packagename</var>
+
+
+       # Sane defaults:
+
+       [ -z "$SERVER_HOME" ] && SERVER_HOME=<var>server_dir</var>
+       [ -z "$SERVER_USER" ] && SERVER_USER=<var>server_user</var>
+       [ -z "$SERVER_NAME" ] && SERVER_NAME="<var>Server description</var>"
+       [ -z "$SERVER_GROUP" ] && SERVER_GROUP=<var>server_group</var>
+       # Groups that the user will be added to, if undefined, then none.
+       # Some daemons might need additional privileges and those can be
+       # granted by adding it to additional groups.
+       ADDGROUP=""
+
+
+       # create user to avoid running server as root
+       # 1. create group if not existing
+       if ! getent group | grep -q "^$SERVER_GROUP:" ; then
+             echo -n "Adding system group $SERVER_GROUP.."
+             addgroup --quiet --system $SERVER_GROUP 
+             if ! getent group | grep -q "^$SERVER_GROUP:"; then
+               echo "..ERROR creating system group. Aborting installation."
+              exit 1
+            fi
+           echo "..done"
+       fi
+       # 2. create homedir if it does not exist
+       test -d $SERVER_HOME || mkdir $SERVER_HOME
+       # 3. create user if it does not exist
+       if ! getent passwd | grep -q "^$SERVER_USER:"; then
+           echo -n "Adding system user $SERVER_USER.."
+           adduser --quiet \
+               --system \
+               --ingroup $SERVER_GROUP \
+               --no-create-home \
+               --disabled-password \
+               $SERVER_USER 
+           if ! getent passwd | grep -q "^$SERVER_USER:"; then
+             echo "..ERROR creating system user. Aborting installation."
+             exit 1
+          fi
+           echo "..done"
+           # 4. adjust passwd entry, only do this if the package
+           # creates the user
+           usermod -c "$SERVER_NAME" \
+               -d $SERVER_HOME \
+               -g $SERVER_GROUP \
+               $SERVER_USER
+       else
+       # The package might want to check if the user already exists
+       # and it is *not* a system user, in this case it could abort
+       # the installation (like in this example) or ask the administrator.
+       # Using a non-system user as the one in our package could 
+       # have unexpected consequences.
+       # Some packages try to prevent this kind of collision by using
+       # a prefix such as 'Debian-'
+         for LINE in `grep SYSTEM_UID /etc/adduser.conf | grep -v "^#"`; do
+            case $LINE in
+               FIRST_SYSTEM_UID*)
+                  FIRST_SYSTEM_UID=`echo $LINE | cut -f2 -d '='`
+               ;;
+               LAST_SYSTEM_UID*)
+                  LAST_SYSTEM_UID=`echo $LINE | cut -f2 -d '='`
+               ;;
+               *)
+               ;;
+            esac
+         done
+         # Abort package installation if the user has not been created by
+         # us.
+         if [ -n "$FIRST_SYSTEM_UID" ] && [ -n "$LAST_SYSTEM_UID" ]; then
+            if USERID=`getent passwd $SERVER_USER | cut -f 3 -d ':'`; then
+               if [ -n "$USERID" ]; then
+                  if [ "$FIRST_SYSTEM_UID" -le "$USERID" ] && \
+                     [ "$USERID" -le "$LAST_SYSTEM_UID" ]; then
+                       echo "The user $SERVER_USER already exists as a non system user!" >&2
+                       echo "Aborting package installation" >&2
+                       exit 1
+                  fi
+               fi
+            fi
+          fi
+        fi
+
+       # 5. adjust file and directory permissions
+       # The example below sets the server home as 750 as it
+       # contains (hypothetically) sensible information.
+       if ! dpkg-statoverride --list $SERVER_HOME >/dev/null
+       then
+               chown -R $SERVER_USER:adm $SERVER_HOME
+               chmod u=rwx,g=rxs,o= $SERVER_HOME
+       fi
+       # 6. Add the user to the ADDGROUP group
+       if test -n $ADDGROUP
+       then
+               if ! groups $SERVER_USER | grep -q $ADDGROUP; then
+                       adduser $SERVER_USER $ADDGROUP
+               fi
+       fi
+    ;;
+    configure)
+
+[...]
+</example>
+
+       <sect2 id="bpp-using-sysuser">
+         <heading>Using system users
+
+<p>In order to make use of the system user you have to make sure that the
+init.d script file:
+
+<list>
+<item>Starts the daemon dropping privileges, if the software does not
+do the <manref name="setuid" section="2"> or <manref name="seteuid"
+section="2"> call itself, you can use the <tt>--chuid</tt>
+call of <prgn>start-stop-daemon</prgn>.
+
+<item>Stops the daemon only if the user id matches, you can use the 
+<prgn>start-stop-daemon</prgn> <tt>--user</tt> option
+for this.
+
+<item>Does not run if either the user or the group do not exist:
+<example>
+  if getent passwd | grep -q "^<var>server_user</var>:"; then
+     echo "Server user does not exist. Aborting" >&2
+     exit 1
+  fi
+  if getent group | grep -q "^<var>server_group</var>:" ; then
+     echo "Server group does not exist. Aborting" >&2
+     exit 1
+  fi
+</example>
+
+</list>
+
+<p>File ownerships of files shipped by the package will need to be adjusted:
+
+<list>
+<item>Configuration files should be readable by the system user, if they
+contain sensitive information the system user should not own them unless there
+is a need for it to write to its own configuration files. Typically this means
+that the configuration files are owned by root and by the system group created
+by the package and are mode 0640.
+
+<item>If the The system user generates state files (such as pidfiles) it will
+need to have a directory under <tt>/var/run</tt> owned by itself.  It can be
+created by the package maintainers script but, since it can be wiped after a
+system reboot, it should be be recreated by the init.d script since the state
+directory.
+
+<item>If the daemon logs directly to <tt>/var/log</tt> logfiles should be
+writable by the system user but, once rotated, they should not be either owned
+or writable by it to prevent it from overwritting old log entries if a security
+vulnerability in the software were to be used. If the daemon logs to a
+directory under <tt>/var/log/</tt> then the directory should be owned by the
+system user and rotated log files need not be changed ownership.
+
+</list>
+
+       <sect2 id="bpp-removing-sysuser">
+         <heading>Removing system users
+
+<p>If the package creates the system user it can remove it when it is
+purged in its <em>postrm</em> script. This currently <em>not</em> recommended
+for all situations since it has a few known 
+<footnote>
+Some relevant threads discussing these issues include:
+<url
+id="http://lists.debian.org/debian-mentors/2004/10/msg00338.html">,
+<url id="http://lists.debian.org/debian-devel/2004/05/msg01156.html">
+and
+<url id="http://lists.debian.org/debian-devel/2005/10/msg00988.html">.
+</footnote>
+drawbacks. For example, files created by the daemon (or by an admin
+impersonating it) either on the local filesystem or in backup files will be
+orphaned and might be taken over by a new system user in the future if it is
+assigned the same uid. On the other hand, an unused local system user can be
+used to access even if the account has been locked (as some authentication
+systems might not use PAM or shadow authentication).
+
+<p>If you want to remove a system user and there is a possibility of it
+leaving orphaned files, the administrator should be asked for the preferred
+action either when the package is installed or when it is removed (see <ref
+id="debconf">). 
+
+<p>The following example code removes the user and groups created
+before only, and only if, the uid is in the range of dynamic assigned system
+uids and the gid is belongs to a system group:
+
+<example>
+case "$1" in
+    purge)
+[...]
+         # find first and last SYSTEM_UID numbers
+        if [ -r /etc/adduser.conf ] ; then
+          for LINE in `grep SYSTEM_UID /etc/adduser.conf | grep -v "^#"`; do
+            case $LINE in
+               FIRST_SYSTEM_UID*)
+                  FIRST_SYSTEM_UID=`echo $LINE | cut -f2 -d '='`
+               ;;
+               LAST_SYSTEM_UID*)
+                  LAST_SYSTEM_UID=`echo $LINE | cut -f2 -d '='`
+               ;;
+               FIRST_SYSTEM_GID*)
+                  FIRST_SYSTEM_GID=`echo $LINE | cut -f2 -d '='`
+               ;;
+               LAST_SYSTEM_GID*)
+                  LAST_SYSTEM_GID=`echo $LINE | cut -f2 -d '='`
+               ;;
+               *)
+               ;;
+            esac
+          done
+         fi
+         # Sane defaults
+        [ -z "$FIRST_SYSTEM_UID" ] && FIRST_SYSTEM_UID=100
+        [ -z "$LAST_SYSTEM_UID" ] && LAST_SYSTEM_UID=999
+        [ -z "$FIRST_SYSTEM_GID" ] && FIRST_SYSTEM_GID=100
+        [ -z "$LAST_SYSTEM_GID" ] && LAST_SYSTEM_GID=999
+
+         # Remove system account if it is a system user
+         CREATEDUSER="<var>server_user</var>"
+         if [ -n "$FIRST_SYSTEM_UID" ] && [ -n "$LAST_SYSTEM_UID" ]; then
+            if USERID=`getent passwd $CREATEDUSER | cut -f 3 -d ':'`; then
+               if [ -n "$USERID" ]; then
+                  if [ "$FIRST_SYSTEM_UID" -le "$USERID" ] && \
+                     [ "$USERID" -le "$LAST_SYSTEM_UID" ]; then
+                       echo -n "Removing $CREATEDUSER system user.."
+                        deluser --quiet $CREATEDUSER || true
+                       echo "..done"
+                  fi
+               fi
+            fi
+         fi
+         # Remove system group if it is a system group
+         CREATEDGROUP=<var>server_group</var>
+         if [ -n "$FIRST_SYSTEM_GID" ] && [ -n "$LAST_SYSTEM_GID" ]; then
+            if GROUPGID=`getent group $CREATEDGROUP | cut -f 3 -d ':'`; then
+               if [ -n "$GROUPGID" ]; then
+                  if [ "$FIRST_SYSTEM_GID" -le "$GROUPID" ] && \
+                     [ "$GROUPID" -le "$LAST_SYSTEM_GID" ]; then
+                       echo -n "Removing $CREATEDGROUP group.."
+                       delgroup --only-if-empty $CREATEDGROUP || true
+                       echo "..done"
+                  fi
+               fi
+            fi
+         fi
+[...]
+</example>
+
+<p>Other possibilities, are making sure the account is locked (has an invalid
+password and <em>/bin/false</em> as a shell) and/or changing the GECOS field
+pointing out that the account is no longer used.
+
+<!-- There is currently no consensus as to how any of the above should be
+     done in a way that would make it easy for administrators to locate
+     unused (but not removed) accounts -->
+
+</sect1>
+
+</sect>
 
       <sect id="bpp-config-mgmt">
        <heading>Configuration management with <package>debconf</package></heading>
@@ -4092,7 +4508,7 @@ Most questions should use medium and low priorities.
 Most Debian package maintainers are not native English speakers. So,
 writing properly phrased templates may not be easy for them.
        <p>
-Please use (and abuse) debian-l10n-english@lists.debian.org mailing
+Please use (and abuse) &email-debian-l10n-english; mailing
 list. Have your templates proofread.
        <p>
 Badly written templates give a poor image of your package, of your
@@ -4106,10 +4522,10 @@ doing so, try to balance between verbosity and simplicity.
        <sect2>Be kind to translators
        <p>
 Debconf templates may be translated. Debconf, along with its sister
-package po-debconf offers a simple framework for getting
+package <prgn>po-debconf</prgn> offers a simple framework for getting
 templates translated by translation teams or even individuals.
        <p>
-Please use gettext-based templates. Install po-debconf on your
+Please use gettext-based templates. Install <package>po-debconf</package> on your
 development system and read its documentation ("man po-debconf" is a
 good start).
        <p>
@@ -4122,10 +4538,57 @@ additional uploads. If you use gettext-based templates, the
 translator's name and e-mail addresses are mentioned in the po files
 headers.
        <p>
+The use of the <prgn>podebconf-report-po</prgn> from the
+po-debconf package is highly recommended to warn translators which
+have incomplete translations and request them for updates.
+       <p>
 If in doubt, you may also contact the translation team for a given
 language (debian-l10n-xxxxx@lists.debian.org), or the
-debian-i18n@lists.debian.org mailing list.
+&email-debian-i18n; mailing list.
+       <p>
+Calls for translations posted to
+&email-debian-i18n; with the <file>debian/po/templates.pot</file> file
+attached or referenced in a URL are encouraged. Be sure to mentions in
+these calls for new translations which languages you have existing
+translations for, in order to avoid duplicate work.
+       <sect2>Unfuzzy complete translations when correcting typos and spelling
+       <p>
 
+When the text of a debconf template is corrected and you are
+<strong>sure</strong> that the change does <strong>not</strong> affect
+translations, please be kind to translators and unfuzzy their
+translations.
+       <p>
+If you don't do so, the whole template will not be translated as long
+as a translator will send you an update.
+       <p>
+To <strong>unfuzzy</strong> translations, you can proceed the following way:
+       <enumlist>
+       <item>
+Put all incomplete PO files out of the way. You can check the
+completeness by using (needs the <package>gettext</package> package installed):
+<example>for i in debian/po/*po; do echo -n $i: ; msgfmt -o /dev/null
+--statistics $i; done</example>
+       <item>
+move all files which report either fuzzy strings to a temporary
+place. Files which report no fuzzy strings (only translated and
+untranslated) will be kept in place.
+       <item>
+now <strong>and now only</strong>, modify the template for the typos
+and check again that translation are not impacted (typos, spelling
+errors, sometimes typographical corrections are usually OK)
+       <item>
+run <prgn>debconf-updatepo</prgn>. This will fuzzy all strings
+you modified in translations. You can see this by running the above
+again
+       <item>
+use the following command:
+<example>for i in debian/po/*po; do msgattrib --output-file=$i --clear-fuzzy $i; done</example>
+       <item>
+move back to debian/po the files which showed fuzzy strings in the first step
+       <item>
+run <prgn>debconf-updatepo</prgn> again
+       </enumlist>
        <sect2>Do not make assumptions about interfaces
        <p>
 Templates text should not make reference to widgets belonging to some
@@ -4133,6 +4596,12 @@ debconf interfaces. Sentences like "If you answer Yes..." have no
 meaning for users of graphical interfaces which use checkboxes for
 boolean questions.
        <p>
+String templates should also avoid mentioning the default values in
+their description. First, because this is redundant with the values
+seen by the users. Also, because these default values may be different
+from the maintainer choices (for instance, when the debconf database
+was preseeded).
+       <p>
 More generally speaking, try to avoid referring to user actions.
 Just give facts.