<!ENTITY % dynamicdata SYSTEM "dynamic.ent" > %dynamicdata;
<!-- CVS revision of this document -->
- <!ENTITY cvs-rev "$Revision: 1.261 $">
+ <!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 -->
<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">
<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.
<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
-— 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>
<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.
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 “test cycle”,
-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
stable distribution is incremented (e.g., ‘3.0’ becomes
‘3.0r1’, ‘2.2r4’ becomes ‘2.2r5’, 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
<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>.
<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
</example>
<p>
Think twice before adding a news item to the PTS because you won't be able
-to remove it later and you wan't be able to edit it either. The only thing
+to remove it later and you won't be able to edit it either. The only thing
that you can do is send a second news item that will deprecate the
information contained in the previous one.
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>
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
<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
<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
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
the bug to the right package. If you don't know which package it should
be reassigned to, you should ask for help on
<qref id="irc-channels">IRC</qref> or on &email-debian-devel;.
+Please make sure that the maintainer(s) of the package
+the bug is reassigned to
+know why you reassigned it.
<p>
Sometimes you also have to adjust the severity of the bug so that it
matches our definition of the severity. That's because people tend to
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&cvsroot=dak&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)
have to close the bugs that have been tagged fixed by the NMU. The easiest
way is to use the <tt>-v</tt> option of <prgn>dpkg-buildpackage</prgn>,
as this allows you to include just all changes since your last maintainer
-upload. Alternativly, you
+upload. Alternatively, you
can close them manually by sending the required mails to the
BTS or by adding the required <tt>closes: #nnnn</tt> in the changelog
entry of your next upload.
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>
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
<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>
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
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.
<sect2>Do not use first person
<p>
You should avoid the use of first person ("I will do this..." or "We
-recommend..."). The computer is not a person and the Debconf tempaltes
+recommend..."). The computer is not a person and the Debconf templates
do not speak for the Debian developers. You should use neutral
construction and often the passive form. Those of you who already
wrote scientific publications, just write your templates like you
~ianmdlvl / developers-reference.git / blobdiff