Add start of reference manual

1 files changed, 741 insertions, 0 deletions

diff --git a/doc/reference.sgml b/doc/reference.sgml
new file mode 100644
index 000000000..e1f1bde67
--- /dev/null
+++ b/doc/reference.sgml
@@ -0,0 +1,741 @@
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
+  <!ENTITY debian "<productname>Debian</productname>">
+  <!ENTITY dpkg "<command>dpkg</command>">
+  <!ENTITY dselect "<command>dselect</command>">
+  <!ENTITY deb "<filename>.deb</filename>">
+]>
+<book id="packaging-manual">
+<bookinfo>
+  <title>dpkg reference Manual</title>
+  <edition>draft</edition>
+  <authorgroup>
+    <author>
+      <firstname>Wichert</firstname>
+      <surname>Akkerman</surname>
+      <affiliation>
+	<address>
+	  <email>wichert@deephackmode.org</email>
+	</address>
+      </affiliation>
+    </author>
+  </authorgroup>
+  <copyright>
+    <year>2001</year>
+    <year>2002</year>
+    <holder>Wichert Akkerman</holder>
+  </copyright>
+
+  <legalnotice>
+    <para>
+      Permission is granted to copy, distribute and/or modify this document
+      under the terms of the GNU Free Documentation License, Version 1.1 or any
+      later version published by the Free Software Foundation. There are
+      no invariant sections. A copy of the license is included in the section
+      entitled "GNU Free Documentation License".
+    </para>
+  </legalnotice>
+</bookinfo>
+
+<preface>
+  <title>Preface</title>
+
+  <para>
+    This manual is a reference to the &debian; package management system.
+  </para>
+
+  <para>
+    This manual is currently being written based on the previous packaging
+    manual and as such is a work in progress.
+  </para>
+</preface>
+
+<chapter id="intro">
+  <title>Introduction</title>
+
+  <para>
+    The Debian package management system is build up from various seperate
+    tools that work together form a comprehensive system to manage your
+    system.
+  </para>
+
+  <para>
+    This document describes all the tools that used to handle and produce
+    them as well as the file formats used.
+  </para>
+</chapter>
+
+
+<chapter id="diversions">
+  <title>Managing diversions</title>
+
+  <para>
+    Diversions are a method to instruct &dpkg; to use a different filename
+    when installing a file. This can be useful to prevent conflicts between
+    related packages or when a system administator wants to replace a file
+    with another version.
+  </para>
+
+  <para>
+    Diversions are specific to either a package or the local system.  A
+    package specific diversion will only divert a file if it does not
+    belongs to a specific package that was given when the diversion was
+    created. This allow a package to divert a file from other packages and
+    replacing them with its own copy. Local diversions are applied to all
+    packages and can be used by the system administrator.
+  </para>
+
+  <section>
+    <title>Managing diversions with dpkg-divert</title>
+
+    <tip>
+      <para>
+	The official documentation for <command>dpkg-divert</command> can always
+	be found online in the
+	<citerefentry><refentrytitle>dpkg-divert</refentrytitle>
+	<manvolnum>8</manvolnum></citerefentry> manual page.
+      </para>
+    </tip>
+
+    <section>
+    <title>Adding new diversions</title>
+
+    <para>New options can be added using the <emphasis>--add</emphasis>
+    option for <command>dpkg-divert</command>. Its syntax is:
+    </para>
+
+    </section>
+
+  </section>
+</chapter>
+
+<chapter id="permissions">
+  <title>Managing file permissions / ownership</title>
+
+  <para>
+    When you install a package &dpkg; will use the ownership and permissions
+    that are used inside the package. In some situations you might not agree
+    with those defaults and would like to use other settings. To support this
+    a feature called statoverrides was introduced in &dpkg; 1.8.0, and an
+    accompanying tool called <command>dpkg-statoverride</command>.
+  </para>
+
+  <note>
+    <para>
+      Even though we use the word file here, this applies to all filesystem
+      objects that &dpkg; handles, including directories,
+      devices, etc.
+    </para>
+  </note>
+
+  <caution>
+    <para>
+      If you look at the &dpkg; changelog you will see that statoverrides
+      were actually added in version 1.7.0. However that version had
+      some problems both in <command>dpkg-statoverrides</command> which
+      broke adding and removing of overrides and in &dpkg; itself which
+      made it only apply overrides to normal files. Both problems
+      were fixed in version 1.8.0.
+    </para>
+  </caution>
+
+  <section>
+    <title>How permissions and ownership are applied</title>
+
+    <para>
+      &dpkg; uses the following logic to determine the ownership and
+      permissions to use when installing a file:
+    </para>
+
+    <orderedlist>
+      <listitem><para>Check if there is a statoverride registered for this file
+      </para></listitem>
+
+      <listitem><para>If an override is present use the ownership and permission
+	specified in the override.</para></listitem>
+
+      <listitem><para>If no override is present:</para>
+
+	<orderedlist>
+	  <listitem><para>Check if there is a system account with the same name
+	    as the owner used inside the archive. If so use that as owner,
+	    otherwise use the uid as used in the package.
+	  </para></listitem>
+
+	  <listitem><para>Check if there is a system group with the same name
+	    as the group used inside the archive. If so use that as group,
+	    otherwise use the gid as used in the package.
+	  </para></listitem>
+
+	  <listitem><para>Use the permissions as used in the package.
+	  </para></listitem>
+	</orderedlist>
+      </listitem>
+    </orderedlist>
+
+    <para>
+      The exact method that &dpkg; uses to set the ownership and permissions
+      depends on the type of file that is being created:
+    </para>
+
+    <variablelist>
+      <varlistentry>
+	<term>regular files</term>
+	<listitem><para>Created with owner and group set to
+	  <filename>root</filename> and with mode 0. After the data has
+	  been written to the file the ownership and mode are set to their
+	  final values.
+	</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>FIFOs</term>
+	<term>character and block devices</term>
+	<term>directories</term>
+	<listitem><para>Created with owner and group set to
+	  <filename>root</filename> and with mode 0, and then updated
+	  to set the ownership and mode to their final values.
+	</para></listitem>
+      </varlistentry>
+	  
+      <varlistentry>
+	<term>Hardlinks</term>
+	<listitem><para>After the link has been made its ownership and
+	  permissions are setup. <emphasis>This means the original file
+	  will also be changed!</emphasis>
+	</para></listitem>
+      </varlistentry>
+    </variablelist>
+  </section>
+
+  <section>
+    <title>Managing overrides with dpkg-statoverride</title>
+
+    <tip>
+      <para>
+	The official documentation for <command>dpkg-statoverride</command> can
+	always be found online in the
+	<citerefentry><refentrytitle>dpkg-statoverride</refentrytitle>
+	<manvolnum>8</manvolnum></citerefentry> manual page.
+      </para>
+    </tip>
+
+    <section>
+      <title>Listing overrides</title>
+
+      <para>
+	You can get a list of all overrides present in the database by using the
+	<option>--list</option> option:
+      </para>
+
+      <blockquote><para>
+	<synopsis><command>dpkg-statoverride</command> <option>--list</option> <parameter>&lt;glob&gt;</parameter></synopsis>
+</para></blockquote>
+
+      <para>
+	There is an optional glob option that restricts the output from
+	<option>--list</option> to overrides for files that match the glob
+	expression. 
+      <para>
+
+      <footnote>
+	<para>
+	  Please see the <citerefentry><refentrytitle>sh</refentrytitle>
+	  <manvolnum>1</manvolnum></citerefentry> or
+	  <citerefentry><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum>
+	  </citerefentry> for a description of glob syntax.
+	</para>
+      </footnote>
+
+      <example>
+	<title>Listing overrides</title>
+	<programlisting>
+[fog;~]-1# dpkg-statoverride --list
+root root 0755 /bin/mount
+root root 0755 /bin/ping
+[fog;~]-2# dpkg-statoverride --list '*mount*'
+root root 0755 /bin/mount
+</programlisting>
+      </example>
+    </section>
+
+    <section>
+      <title>Adding new overrides</title>
+
+      <para>
+	New options can be added using the <option>--add</option> option
+	for <command>dpkg-statoverride</command>. Its syntax is:
+      </para>
+
+      <blockquote><para>
+	<synopsis><command>dpkg-statoverride</command> <option>--add</option> <parameter>&lt;user&gt;</parameter> <parameter>&lt;group&gt;</parameter> <parameter>&lt;mode&gt;</parameter> <parameter>&lt;file&gt;</parameter>
+</synopsis></para></blockquote>
+      
+      <para>
+	This will add an override for <filename>&lt;file&gt;</filename> by
+	telling &dpkg; to use the user, group and mode given to
+	<command>dpkg-statoverride</command>. The user and group can be
+	specified in two ways: either by using the name as found in the
+	system account database (ie <filename>/etc/passwd</filename>, NIS or
+	another source configured in
+	<filename>/etc/nsswitch.conf</filename>), or by using a number
+	prefixed with <computeroutput>#</computeroutput>.
+      </para>
+
+      <example>
+	<title>Adding an override</title>
+
+      <programlisting>
+
+[fog;~]-1# ls -l /bin/mount
+-rwsr-xr-x    1 root     root        56284 Nov 23 06:14 /bin/mount
+[fog;~]-2# dpkg-statoverride --add root root 0755 /bin/mount
+[fog;~]-3# ls -l /bin/mount
+-rwsr-xr-x    1 root     root        56284 Nov 23 06:14 /bin/mount
+</programlisting>
+      </example>
+
+      <para>
+	Adding an override does not update the file on the filesystem, unless
+	you also specify the <option>--update</option> option.
+      </para>
+
+      <example>
+	<title>Adding an override using --update</title>
+
+	<programlisting>
+[fog;~]-1# ls -l /bin/mount
+-rwsr-xr-x    1 root     root        56284 Nov 23 06:14 /bin/mount
+[fog;~]-2# dpkg-statoverride --update --add root root 0755 /bin/mount
+[fog;~]-3# ls -l /bin/mount
+-rwxr-xr-x    1 root     root        56284 Nov 23 06:14 /bin/mount
+</programlisting>
+    </example>
+
+    <para>
+      If an override already exists and you want to replace it you can
+      use the <option>--force</option> to force <command>dpkg-statoverride
+      </command> to replace the existing override.
+    </para>
+
+    <example>
+      <title>Replacing an existing override</title>
+      <programlisting>
+[fog;~/sources/play/pkg-manual]-1# dpkg-statoverride --add root root 0755 /bin/mount
+An override for "/bin/mount" already exists, aborting
+[fog;~/sources/play/pkg-manual]-2# dpkg-statoverride --force --add root root 0755 /bin/mount
+An override for "/bin/mount" already exists, but --force specified so lets ignore it.
+[fog;~/sources/play/pkg-manual]-3# dpkg-statoverride --list /bin/mount
+root root 0755 /bin/mount
+</programlisting>
+    </example>
+  </section>
+
+  <section>
+    <title>Removing overrides</title>
+    <para>
+    Overrides can be removed using the <option>--remove</option> option,
+    which takes a single filename as argument:
+    </para>
+
+    <blockquote><para>
+      <synopsis><command>dpkg-statoverride</command> <option>--remove</option> <parameter>&lt;file&gt;</parameter></synopsis>
+</para></blockquote>
+
+    <para>
+    This will remove the override for <filename>&lt;file&gt;</filename>
+    from the database.
+    </para>
+
+    <note>
+      <para>When an override for a file is removed its ownership and permission
+      are <emphasis>not</emphasis> restored to the original value.
+      </para>
+    </note>
+
+    <example>
+      <title>Removing an override</title>
+      <programlisting>
+[fog;~]-1# dpkg-statoverride --list
+root root 0755 /bin/mount
+[fog;~]-2# dpkg-statoverride --remove /bin/mount
+[fog;~]-3# dpkg-statoverride --list
+[fog;~]-4#
+</programlisting>
+    </example>
+  </section>
+
+  </section>
+</chapter>
+
+
+<chapter id="formats">
+  <title>File formats</title>
+  <para>
+    This chapter describes all the file formats used by the package tools.
+    All files are text files which you can view and modify using any normal
+    text editor if needed.
+  </para>
+
+  <para>
+    Most file formats are based on the RFC822 format, which is best known
+    as the format used in e-mail headers.
+  </para>
+
+  <section>
+    <title>RFC822</title>
+    <para>
+      A RFC822 style messages consists of one or more blocks, seperated by
+      null lines (an empty line). Each block is made up of fields. Fields
+      can be folded over multiple lines by inserting a 'newline whitespace'
+      pair. This combination is interpreted as a single whitespace.
+    </para>
+
+    <para>
+      Each fiels s a single line consisting of a field-name and a
+      field-body, seperated by a colon (:). The field-name is made up
+      from printable ASCII characters minus the colon. The field-body
+      may be composed of all ASCII characters except CR or LF (they
+      are automatically removed when unfolding lines).
+    </para>
+
+    <example>
+      <title>RFC822 style file</title>
+
+      <programlisting>
+Header: value
+Description: this is an example of an RFC822 style message
+
+Section: new
+Name: body
+Description: this is block 2 of the example
+X-Fortune:
+ To be excellent when engaged in administration is to be like the North
+ Star.  As it remains in its one position, all the other stars surround it.
+ -- Confucius
+</programlisting>
+    </example>
+  </section>
+
+  <section>
+    <title>changes file</title>
+
+    <para>
+      Bla
+    </para>
+  </section>
+
+  <section>
+    <title>dsc file</title>
+
+    <para>
+      The <filename>.dsc</filename> file describes the source for a Debian
+      package: it contains general information over the source such as the
+      name of the package and which binary package it produces as well as
+      the files that contain the sourcecode.
+    </para>
+    
+    <para>
+      Just like other dpkg datafiles this file is formated using RFC822
+      syntax. In addition the file can signed as an OpenPGP ASCII armored
+      message (see RFC2440). The table below lists the allowed fields
+      in a <filename>.dsc</filename> file. The order used is not important,
+      although <command>dpkg-source</command> will output the fields using
+      the ordering used in the table.
+    </para>
+
+    <table>
+      <title>Fields in a <filename>.dsc</filename> file</title>
+      <tgroup cols="2">
+	<thead>
+	  <row><entry>Field</entry><entry>Description</entry></row>
+	</thead>
+	<tbody>
+	  <row><entry>Format</entry>
+	       <entry>Version of the <filename>.dsc</filename> file format used
+		      </entry></row>
+	  <row><entry>Source</entry>
+	       <entry>Name of the source package</entry></row>
+	  <row><entry>Version</entry>
+	       <entry>Version number of the source</entry></row>
+	  <row><entry>Binary</entry>
+	       <entry>comma seperated list of binary packages build from this
+		  source</entry></row>
+	  <row><entry>Origin</entry>
+	       <entry>Name of the organization that procudes this package
+		      </entry></row>
+	  <row><entry>Maintainer</entry>
+	       <entry>Maintainer of this package</entry></row>
+	  <row><entry>Uploaders</entry>
+	       <entry>Multi-line field with list of people authorized to make
+		      uploads of a package (optional)</entry>
+	  <row><entry>Architecture</entry>
+	       <entry>Space seperated list of architectures for which package
+		      are build from this source</entry></row>
+	  <row><entry>Standards-Version</entry>
+	       <entry>Version of &debian; policy this package is complient
+		      with</entry></row>
+	  <row><entry>Files</entry>
+	       <entry>Multi-line field with list of files with the actual source
+		      code</entry></row>
+	</tbody>
+      </tgroup>
+    </table>
+
+    <para>
+      The current version of the <filename>.dsc</filename> is 1.0 . The first
+      digit in the version number is the major version. Within a major version
+      the only allowed changes in format are additiong of new fields. This
+      guarantees that tools like <command>dpkg-source</command> will be
+      fully backwards and upwards compatible within  a major version.
+    </para>
+
+    <para>
+      The Files field contains one line for each file that is
+      contains source for this package (only 2 files are supported: a
+      <filename>.tar.gz</filename> file with the (original) source, and
+      an optional <filename>.diff.gz</filename> with Debian changes to the
+      source). Each file description consists of 3 items, seperated by
+      a single space:
+
+      <orderedlist>
+	<listitem><para>A MD5 checksum of the file</para></listitem>
+	<listitem><para>The filesize in bytes</para></listitem>
+	<listitem><para>The filename</para></listitem>
+      </orderedlist>
+    </para>
+
+    <example>
+      <title>modutils .dsc file</title>
+
+      <programlisting>
+-----BEGIN PGP SIGNED MESSAGE-----
+Hash: SHA1
+
+Format: 1.0
+Source: modutils
+Version: 2.4.1-1
+Binary: modutils
+Origin: debian
+Maintainer: Wichert Akkerman &lt;wakkerma@debian.org&gt;
+Architecture: any
+Standards-Version: 3.2.0
+Files: 
+ 6d69ff476c964e703659d950999e411c 246022 modutils_2.4.1.orig.tar.gz
+ 3de7100460662472404f8a83cccde6da 17219 modutils_2.4.1-1.diff.gz
+
+-----BEGIN PGP SIGNATURE-----
+Version: GnuPG v1.0.4 (GNU/Linux)
+Comment: For info see http://www.gnupg.org
+
+iEYEARECAAYFAjpbNIAACgkQPLiSUC+jvC1CFQCePvKBH6qT7/BKXVHCamKXZvZq
+Be8An1QDPcyDFtMddYJw/BwTVphbwzU6
+=Zl3g
+-----END PGP SIGNATURE-----
+</programlisting>
+    </example>
+  </section>
+
+  <section>
+    <title>control</title>
+
+    <table>
+      <title>Fields in the source section of the <filename>control</filename>
+	     file</title>
+      <tgroup cols="2">
+	<thead>
+	  <row><entry>Field</entry>
+	       <entry>required</entry>
+	       <entry>Description</entry>
+	  </row>
+	</thead>
+	<tbody>
+	  <row><entry>Source</entry><entry>yes</entry>
+	       <entry>Name of the source package</entry></row>
+	  <row><entry>Section</entry><entry>no</entry>
+	       <entry>Package category for this package, used by frontends.
+		      </entry></row>
+	  <row><entry>Priority</entry><entry>no</entry>
+	       <entry>Indication of package importance. Legal values are
+		      extra, important, optional, required and standard.
+		      </entry></row>
+	  <row><entry>Maintainer</entry><entry>yes</entry>
+	       <entry>Name of the source package</entry></row>
+	  <row><entry>Standards-Version</entry><entry>no</entry>
+	       <entry>Version of &debian; policy this package is complient
+		      with</entry></row>
+	  <row><entry>Build-Depends, Build-Conflicts,
+		      Build-Depends-Indep, Build-Conflicts-Indep</entry><entry>no</entry>
+	       <entry>Specify demands on the build environment</entry></row>
+	  <row><entry>Bugs</entry><entry>no</entry>
+	       <entry>Name of the source package</entry></row>
+	  <row><entry>Origin</entry><entry>no</entry>
+	       <entry>Name of the source package</entry></row>
+	</tbody>
+      </tgroup>
+    </table>
+
+
+    <table>
+      <title>Fields in the package section of the <filename>control</filename>
+	     file</title>
+      <tgroup cols="2">
+	<thead>
+	  <row><entry>Field</entry>
+	       <entry>required</entry>
+	       <entry>Description</entry>
+	  </row>
+	</thead>
+	<tbody>
+	  <row><entry>Package</entry><entry>yes</entry>
+	       <entry>Name of the package</entry></row>
+	  <row><entry>Architecture</entry><entry>yes</entry>
+	       <entry>Space seperated list of architectures for which package
+		      are build from this source</entry></row>
+	  <row><entry>Essential</entry><entry>no</entry>
+	       <entry>Indicates if a package is essential to the system
+		      </entry></row>
+	  <row><entry>Pre-Depends, Depends, Recommends, Suggests, Replaces,
+		      Conflicts</entry><entry>no</entry>
+	       <entry>Specify relations to other packages</entry></row>
+	  <row><entry>Description</entry><entry>yes</entry>
+	       <entry>Description of the package</entry></row>
+	</tbody>
+      </tgroup>
+    </table>
+  </section>
+
+  <section>
+    <title>diversions</title>
+
+    <para>
+      The <filename>diversions</filename> file contains all the alternatives
+      defined on this system. It is located in the &dpkg; admin directory.
+    </para>
+
+    <note>
+      <para>
+	This is an internal &dpkg; file: do not edit it by hand unless really
+	needed, but use the <command>dpkg-divert</command> tool instead.
+      </para>
+    </note>
+
+    <para>
+      For each diversion there are 3 lines in the diversions file:
+      <orderedlist>
+	<listitem><para>
+	  The name of the file that will be diverted.
+	</para></listitem>
+
+       <listitem><para>
+	 The filename that the diverted file will be diverted to.
+       </para></listitem>
+
+       <listitem><para>
+	 The name of the package that made this diversion. If it is a
+	 local (ie user) diversion the magic packagename `:' is used
+	 instead.
+       </para></listitem>
+      </orderedlist>
+    </para>
+
+    <example>
+      <title>Example <filename>diversions</filename> file</title>
+
+      <programlisting>
+/sbin/modprobe
+/sbin/modprobe.orig
+:
+/usr/bin/locate
+/usr/bin/locate.notslocate
+slocate
+</programlisting>
+    </example>
+  </section>
+
+  <section>
+    <title>statoverrides</title>
+    <para>
+      This file contains the list of all statoverrides that &dpkg; uses
+      when unpacking packages. It is located in the &dpkg; admin
+      directory. Each line in the file represents one override, and
+      comments are not allowed.
+    </para>
+
+    <note>
+      <para>
+	This is an internal &dpkg; file: do not edit it by hand unless really
+	needed, but use the <command>dpkg-statoverride</command> tool instead.
+      </para>
+    </note>
+
+    <para>
+      Each line contains 4 items, seperated by whitespace:
+      <orderedlist>
+	<listitem><para>
+	  The owner to use. This can be either an accountname that must
+	  be present on the system, or a numerical uid. Uids are prefixed
+	  with a <computeroutput>#</computeroutput>.
+	</para></listitem>
+
+	<listitem><para>
+	  The group to use. This can be either a group that must be present on
+	  the system, or a numerical gid. Gids are prefixed
+	  with a <computeroutput>#</computeroutput>.
+	</para></listitem>
+
+	<listitem><para>
+	  Mode to use for this file. This is an octal number.
+	</para></listitem>
+
+	<listitem><para>
+	  The filesystem object (file, directory, device, FIFO or link)
+	  to which this override should be applied. Since this is the
+	  last item on a line it may contain whitespace.
+	</para></listitem>
+      </orderedlist>
+    </para>
+
+    <example>
+      <title>Example <filename>statoverride</filename> file</title>
+      <programlisting>
+root wheel 04750 /bin/su
+root adm 0750 /var/log/apache
+</programlisting>
+
+      <para>
+        This will tell &dpkg; to do the following:
+      </para>
+
+      <itemizedlist>
+	<listitem><para><filename>/bin/su</filename> is installed owned by
+	  user <computeroutput>root</computeroutput> and group
+	  <computeroutput>wheel</computeroutput> with mode 04750. This means
+	  that only people in the <computeroutput>wheel</computeroutput>
+	  group are allowed to run <command>su</command>.
+        </para></listitem>
+  
+	<listitem><para><filename>/var/log/apache</filename> is installed
+	  owned by user <computeroutput>root</computeroutput> and group
+	  <computeroutput>adm</computeroutput> with mode 0750. This
+	  restricts the ability to view the
+	  <productname>apache</productname> to people in the
+	  <computeroutput>adm</computeroutput> group by disallowing others
+	  to access the <filename>/var/log/apache</filename> directory.
+        </para></listitem>
+      </itemizedlist>
+    </example>
+  </section>
+
+  <section>
+    <title>alternatives</title>
+
+    <para>
+      Bla
+    </para>
+  </section>
+</chapter>
+
+</book>
+
+<!-- vim: sw=2
+-->