--- /dev/null
+all: debconf_specification.txt debconf_specification.html
+
+%.html: %.xml html.dsl
+ jade -V nochunks -t sgml -d html.dsl \
+ /usr/lib/sgml/declaration/xml.dcl $< > $@
+ -tidy -i -m -f /dev/null $@
+
+%.txt: %.html
+ links -dump $< | perl -pe 's/[\r\0]//g' > $@
+
+clean:
+ rm -f *.css *.html *.txt
--- /dev/null
+<?xml version="1.0"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+ "dtd/docbook-xml/4.1.2/docbookx.dtd" [
+<!ENTITY statuscodes_table SYSTEM "include/statuscodes.xml">
+<!ENTITY command_list SYSTEM "include/commands.xml">
+<!ENTITY priority_table SYSTEM "include/priorities.xml">
+<!ENTITY type_table SYSTEM "include/types.xml">
+]>
+<article>
+
+ <articleinfo>
+ <!-- one of (indexterm contrib authorblurb affiliation othername lineage surname firstname honorific citetitle volumenum titleabbrev title subtitle seriesvolnums revhistory releaseinfo pubsnumber publishername publisher pubdate productnumber productname printhistory pagenums othercredit orgname issuenum issn isbn invpartnumber editor edition date corpname corpauthor copyright contractsponsor contractnum confgroup collab biblioset bibliomisc authorinitials authorgroup author artpagenums address abstract abbrev itermset keywordset subjectset modespec legalnotice mediaobject graphic) -->
+ <title>Configuration management</title>
+ <subtitle>revision 7.0</subtitle>
+ <author>
+ <firstname>
+ Wichert
+ </firstname>
+ <surname>
+ Akkerman
+ </surname>
+ <affiliation>
+ <orgname>
+ The Debian Project
+ </orgname>
+ <address><email>wakkerma@debian.org</email></address>
+ </affiliation>
+ </author>
+ <author>
+ <firstname>
+ Joey
+ </firstname>
+ <surname>
+ Hess
+ </surname>
+ <affiliation>
+ <orgname>
+ The Debian Project
+ </orgname>
+ <address><email>joeyh@debian.org</email></address>
+ </affiliation>
+ </author>
+ <copyright>
+ <year>
+ 1998
+ </year>
+ <year>
+ 1999
+ </year>
+ <year>
+ 2000
+ </year>
+ <holder>
+ Wichert Akkerman and Joey Hess
+ </holder>
+ </copyright>
+ <legalnotice>
+ <para>
+ This text is copyright by the authors under the terms of the
+ BSD license, sans advertising clause.
+ </para>
+ </legalnotice>
+ </articleinfo>
+
+ <sect1>
+ <title>
+ Introduction
+ </title>
+ <para>
+ Configuration management is quickly becoming a very important issue.
+ Having programs which do cool stuff is great, but we need to store
+ their configuration as well. We see more and more different
+ configuration systems being introduced all the time, which is not very
+ practical. This text introduces a general configuration management
+ system which flexible enough to be used for all kinds of applications.
+ </para>
+ </sect1>
+
+ <sect1>
+ <title>
+ Configuration Data
+ </title>
+ <sect2>
+ <title>
+ The configuration space
+ </title>
+ <para>
+ All configuration information is stored in what I call the
+ configuration space. This is a database with a special design
+ which resembles the method we look at configuration information.
+ This is done by defining a hierarchy of information. Each package
+ receives its own space in the hierarchy. Each package is free to
+ use a flat space, or divide its space further into
+ sub-hierarchies. If multiple packages share a common purpose they
+ may use a shared toplevel hierarchy, preferably with the same name
+ as a shared (virtual) package name (for example, both
+ <application>mutt</application> and <application>elm</application>
+ can use <literal>mail-reader</literal>,
+ <application>strn</application> and <application>nn</application>
+ could use <literal>news-reader</literal>). This
+ shared tree can also be used as a default, ie a variable
+ <literal>news-reader/nntpserver</literal> can be used by
+ <application>strn</application> if <literal>strn/nntpserver</literal>
+ does not exist.
+ </para>
+ <para>
+ Each variable in the configuration space has some information
+ associated with it. Most importantly, it has a value. It also may
+ have a set of flags and a set of substitution data.
+ </para>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>
+ Templates
+ </title>
+ <para>
+ Each variable in the configuration space is associated with some
+ meta-data. The minimum meta-data associated with a variable is:
+ long and short description, type, and default value. The meta-data
+ is essentially static; the protocol described below does not allow it
+ to be changed.
+ </para>
+ <para>
+ The meta-data exists in a space with similar naming
+ properties to the configuration space described above, and typically
+ one variable in the configuration space will have associated with it
+ metadata with the same name in the meta-data space. However, this need
+ not be the case; many different variables can all be associated with
+ the same meta-data. In effect the meta-data serves as a template
+ for the configuration variable.
+ </para>
+ <sect2>
+ <title>
+ Template information
+ </title>
+ <para>
+ So, what do we need to store in a variable template? Of course we
+ need a name to identify the template. Template names are made up of
+ components separated by the character `/' (slash).
+ Each component is limited to alphanumerics and `+' `-' `.'
+ (plus, minus, full stop).
+ </para>
+ <para>
+ A type is also needed so data can be verified. Here is a table
+ of common types; implementations are free to make up more.
+ &type_table;
+ </para>
+ <para>
+ Of course a default value is useful as well, and
+ finally we need a description of the variable. We actually use two
+ descriptions: a short one (limited to 50 characters or so) and an
+ extended one.
+ </para>
+ <para>
+ The extended description may be word-wrapped by the
+ FrontEnd. To make separate paragraphs in it, use <literal>.</literal>
+ on a line by itself to separate them. Text in the extended
+ description that is prefaced by additional whitespace will not be
+ wordwrapped. Both the description and extended
+ description may have substitutions embedded in them. Ie,
+ <literal>${foo}</literal>. These will be expanded when the
+ descriptions are displayed.
+ </para>
+ <para>
+ This information is stored in a template file that consists of
+ stanzas in a rfc-822 compliant format, separated by blank lines.
+ Here is an example:
+ <programlisting>
+Template: hostname
+Type: string
+Default: debian
+Description: unqualified hostname for this computer
+ This is the name by which this computer will be known on the network. It
+ has to be a unique name in your domain.
+
+Template: domain
+Type: string
+Description: domain for this computer
+ This is the domain your computer is a member of. Typically it is
+ something like "mycompany.com" or "myuniversity.edu".
+ </programlisting>
+ </para>
+ </sect2>
+ </sect1>
+ <sect1>
+ <title>
+ Configuration frontends
+ </title>
+ <para>
+ Of course applications can use the database and meta-database directly.
+ But there should be a simple system to interact with the user that is
+ simple and modular enough to be used with systems ranging from
+ shell-scripts to Fortran programs. To do this we define a general
+ frontend that can be driven using the simplest and most common form of
+ communication: stdin and stdout.
+ </para>
+ <para>
+ Using this simple form of communication gives us a great advantage: it
+ becomes easy to change the frontend. That means the user can switch
+ between a console, a graphical or even a web-interface at will.
+ </para>
+ <para>
+ Besides being able to switch between types of frontends there is
+ another important aspect of a good user interface: user friendliness.
+ We have to account for the fact that some users know more then others
+ and change the information we show or ask from the user. We do this by
+ giving everything a priority and giving the user control over what
+ kind of questions he wants to see. Experts can request to see
+ everything, while novices get the option of only seeing only important
+ questions. Finally there is an option to simply skip all questions, so
+ it becomes possible to do automatic configuration using default values
+ or values that are downloaded into the database from a remote
+ location. This makes it simple for example to install and manage
+ clusters or lab rooms or do installs for dummies.
+ </para>
+ </sect1>
+ <sect1>
+ <title>
+ Communication with the frontend
+ </title>
+ <para>
+ This communication between the frontend and the application should be
+ as simple as possible. Since most IO implementations default to
+ line-buffered IO, so we use a simple language where each command is
+ exactly one line.
+ </para>
+ <para>
+ After sending each command to stdout, the client
+ should read one line from stdin. This is the response to the command,
+ and it will be in the form of a number followed by whitespace and an
+ optional string of text. The number is the status code, while the
+ text provides additional information.
+ &statuscodes_table;
+ </para>
+ <para>
+ Here are the currently supported commands.
+ </para>
+ <itemizedlist>
+ &command_list;
+ </itemizedlist>
+ </sect1>
+ <sect1>
+ <title>
+ Debian install-time configuration
+ </title>
+ <para>
+ Debian has had an excellent packaging system for a long time now. There is
+ one thing missing though: a system to handle the configuration of
+ packages so we don't have to stop the installation every time a package
+ needs some data from the user or wants to show some information.
+ </para>
+ <para>
+ We want to make a package which does not break older dpkg's, and we
+ want to be able to get the configuration information before the package
+ is unpacked. To do this we add two new files, config and templates, to
+ the control.tar.gz of a .deb package. Since all installation-software
+ (apt, dselect, dpkg) download the package before installing it, we can
+ extract this before the package is unpacked.
+ </para>
+ <para>
+ The templates file lists the templates for variables that this package
+ uses. This is done using the format as used in the example in the
+ section on templates.
+ </para>
+ <para>
+ The config-file contains a new element, which I call the configmodule.
+ This is a program that will determine the configuration before the
+ package is unpacked. This means it is run <emphasis>before</emphasis>
+ the preinst, and before the package is unpacked! This is done to make
+ sure that we can use the desired configuration in the preinst if
+ necessary.
+ </para>
+ <para>
+ How does the configmodule get its information? The configmodule
+ needs a way to retrieve information from the configuration space, ask
+ the user for information if necessary, etc. But we don't want to
+ implement a user interface for each package. To solve this we use a
+ separate frontend as specified in the section on frontends.
+ </para>
+ </sect1>
+</article>
--- /dev/null
+<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
+<!ENTITY docbook.dsl PUBLIC "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN" CDATA dsssl>
+]>
+<style-sheet>
+
+<style-specification id="html" use="docbook">
+<style-specification-body>
+
+(define %generate-article-toc% #t)
+(define %generate-article-titlepage% #t)
+(define %generate-legalnotice-link% #t)
+(define (article-titlepage-recto-elements)
+ (list (normalize "title")
+ (normalize "subtitle")
+ (normalize "authorgroup")
+ (normalize "author")
+ (normalize "releaseinfo")
+ (normalize "copyright")
+ (normalize "pubdate")
+ (normalize "revhistory")
+ (normalize "legalnotice")
+ (normalize "abstract")))
+
+</style-specification-body>
+</style-specification>
+
+<external-specification id="docbook" document="docbook.dsl">
+
+</style-sheet>
--- /dev/null
+<listitem id="command_version">
+ <para>
+ VERSION
+ <parameter>number</parameter>
+ </para>
+ <para>
+ This exchanges with the frontend the protocol version
+ number that is being used. The current version is
+ 2.0. Versions in the 2.x series will be
+ backwards-compatible. You may specify the protocol version
+ number you are speaking. The frontend will return the version
+ of the protocol it speaks. If the version you specify is too
+ low, this command will return the numeric return code
+ <literal>30</literal>.
+ </para>
+</listitem>
+<listitem id="command_capb">
+ <para>
+ CAPB
+ <parameter>capabilities</parameter>
+ </para>
+ <para>
+ This exchanges with the frontend a list of supported capabilities
+ Capabilities both the frontend and your confmodule support may be
+ used; the capabilities supported by the frontend are returned by
+ this command.
+ <table frame="all">
+ <title>Currently used capabilities</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>capability</entry>
+ <entry>description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>backup</entry>
+ <entry>
+ Backing up to a previous step is supported.
+ </entry>
+ </row>
+ <row>
+ <entry>multiselect</entry>
+ <entry>
+ The multiselect data type is supported. For compatability
+ reasons, you should not ask questions of this type unless
+ this capability is returned.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+</listitem>
+<listitem id="command_title">
+ <para>
+ TITLE
+ <parameter>string</parameter>
+ </para>
+ <para>
+ You can use this command to set a title in the
+ frontend. This may appear in different ways, depending on the
+ frontend being used, for example it might change the title
+ of the frontend's window. If you don't specify anything, a
+ title will automatically be generated.
+ </para>
+</listitem>
+<listitem id="command_stop">
+ <para>
+ STOP
+ </para>
+ <para>
+ This command tells the frontend you're done talking to it. Typically
+ the frontend can detect the termination of your program and this
+ command is not necessary.
+ </para>
+</listitem>
+<listitem id="command_input">
+ <para>
+ INPUT
+ <parameter>priority</parameter>
+ <parameter>question</parameter>
+ </para>
+ <para>
+ This tells the frontend to display a question (or other type of
+ item) to the user. <parameter>question</parameter> is the name of the
+ item to display, all other information about the item is retrieved
+ from the templates described previously.
+ <parameter>priority</parameter> is how important it is that the
+ user be prompted. The frontend need only ask this question if the
+ priority is high enough. The question is not displayed until a go
+ command is given. This allows us to ask multiple questions in a single
+ screen. Once a question has been displayed to the user and the user has
+ provided input, the frontend will set the
+ <literal>seen</literal> flag.
+ &priority_table;
+ </para>
+ <para>
+ Note that the frontend decides if the user is actually
+ prompted or not. If the user has already answered a
+ question, they are normally not asked it again even if
+ input is called again. And if the user is ignoring low
+ priority items, they will not see them. In either of
+ these cases, this command returns the numeric return code
+ <literal>30</literal>.
+ </para>
+</listitem>
+<listitem id="command_beginblock">
+ <para>
+ BEGINBLOCK
+ </para>
+</listitem>
+<listitem id="command_endblock">
+ <para>
+ ENDBLOCK
+ </para>
+ <para>
+ Some frontends are able to display a number of items to
+ the user at once. To do this, they need to be given blocks
+ of input commands, enclosed in the BEGINBLOCK and ENDBLOCK
+ commands. Blocks can be nested and very advanced frontends
+ may use this as a user interface hint.
+ </para>
+ <note>
+ <para>
+ There is an implicit block around any set of INPUT commands
+ that are not enclosed in an explicit block.
+ </para>
+ </note>
+</listitem>
+<listitem id="command_go">
+ <para>
+ GO
+ </para>
+ <para>
+ Shows the current set of accumulated items to the user and lets
+ them fill in values, etc. If the backup capability is supported
+ and the user indicates they want to back up a step, this command
+ returns the numeric return code <literal>30</literal>.
+ </para>
+</listitem>
+<listitem id="command_clear">
+ <para>
+ CLEAR
+ </para>
+ <para>
+ Clears the accumulated set of INPUT commands without displaying
+ them to the user.
+ </para>
+</listitem>
+<listitem id="command_get">
+ <para>
+ GET <parameter>question</parameter>
+ </para>
+ <para>
+ Ask the frontend to tell you how the user answered a question. The
+ value is returned to you.
+ </para>
+</listitem>
+<listitem id="command_set">
+ <para>
+ SET
+ <parameter>question</parameter>
+ <parameter>value</parameter>
+ </para>
+ <para>
+ Set the answer of a question to a value.
+ </para>
+</listitem>
+<listitem id="command_reset">
+ <para>
+ RESET <parameter>question</parameter>
+ </para>
+ <para>
+ Reset the question to its default value. This includes
+ resetting flags to their defaults.
+ </para>
+</listitem>
+<listitem id="command_subst">
+ <para>
+ SUBST
+ <parameter>question</parameter>
+ <parameter>key</parameter>
+ <parameter>value</parameter>
+ </para>
+ <para>
+ Questions (and other items) can have substitutions embedded in their
+ descriptions. These substitutions look like
+ "<literal>${key}</literal>". When the question is displayed,
+ the substitutions are replaced with their values. This
+ command can be used to set the value of a substitution.
+ </para>
+</listitem>
+<listitem id="command_fget">
+ <para>
+ FGET
+ <parameter>question</parameter>
+ <parameter>flag</parameter>
+ </para>
+ <para>
+ Questions (and other items) can have flags associated with them. The
+ flags have a value of "<literal>true</literal>" or
+ "<literal>false</literal>". This command returns
+ the value of a flag.
+ </para>
+</listitem>
+<listitem id="command_fset">
+ <para>
+ FSET
+ <parameter>question</parameter>
+ <parameter>flag</parameter>
+ <parameter>value</parameter>
+ </para>
+ <para>
+ This sets the state of a flag on a question. Valid
+ states for the flag are "<literal>true</literal>" and
+ "<literal>false</literal>".
+ </para>
+ <para>
+ One common flag is the
+ "<literal>seen</literal>" flag. It is normally only set if
+ a user already seen a question.
+ Typically, frontends only display questions to users if they have the
+ seen flag set to "false". Sometimes you want the user to see a
+ question again -- in these cases you can set the seen flag to
+ false to force the frontend to redisplay it.
+ </para>
+</listitem>
+<listitem id="command_metaget">
+ <para>
+ METAGET
+ <parameter>question</parameter>
+ <parameter>field</parameter>
+ </para>
+ <para>
+ This returns the value of any field of a question (the description, for
+ example).
+ </para>
+</listitem>
+<listitem id="command_register">
+ <para>
+ REGISTER
+ <parameter>template</parameter>
+ <parameter>question</parameter>
+ </para>
+ <para>
+ This creates a new question that is bound to a
+ template. By default each template has an associated
+ question with the same name. However, any number of
+ questions can really be associated with a template, and
+ this lets you create more such questions.
+ </para>
+</listitem>
+<listitem id="command_unregister">
+ <para>
+ UNREGISTER
+ <parameter>question</parameter>
+ </para>
+ <para>
+ This removes a question from the database.
+ </para>
+</listitem>
+<listitem id="command_purge">
+ <para>
+ PURGE
+ </para>
+ <para>
+ Call this in your postinst when your package is
+ purged. It removes all templates and questions your
+ package has generated.
+ </para>
+</listitem>
--- /dev/null
+<table frame="all">
+ <title>Supported priorities</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Priority</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>low</entry>
+ <entry>
+ Very trivial items that have defaults that
+ will work in the vast majority of cases.
+ </entry>
+ </row>
+ <row>
+ <entry>medium</entry>
+ <entry>
+ Normal items that have reasonable defaults.
+ </entry>
+ </row>
+ <row>
+ <entry>high</entry>
+ <entry>
+ Items that don't have a reasonable
+ default.
+ </entry>
+ </row>
+ <row>
+ <entry>critical</entry>
+ <entry>
+ Items that will probably break
+ the system without user intervention.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
--- /dev/null
+<table frame="all">
+<title>Numeric status codes</title>
+<tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Range</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>0</entry>
+ <entry>success</entry>
+ </row>
+ <row>
+ <entry>1-9</entry>
+ <entry>reserved</entry>
+ </row>
+ <row>
+ <entry>10-19</entry>
+ <entry>invalid parameters</entry>
+ </row>
+ <row>
+ <entry>20-29</entry>
+ <entry>syntax errors</entry>
+ </row>
+ <row>
+ <entry>30-99</entry>
+ <entry>command-specific return codes</entry>
+ </row>
+ <row>
+ <entry>100-109</entry>
+ <entry>internal errors</entry>
+ </row>
+ <row>
+ <entry>110-255</entry>
+ <entry>reserved</entry>
+ </row>
+ </tbody>
+</tgroup>
+</table>
--- /dev/null
+<table frame="all">
+ <title>Available data types</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>string</entry>
+ <entry>Holds any arbitrary string of data.</entry>
+ </row>
+ <row>
+ <entry>boolean</entry>
+ <entry>
+ Holds "<literal>true</literal>" or "<literal>false</literal>".
+ </entry>
+ </row>
+ <row>
+ <entry>select</entry>
+ <entry>
+ Holds one of a finite number of possible values. These
+ values must be specified in a field named
+ <literal>Choices:</literal>. Separate the possible values
+ with commas and spaces, like this:
+ <literal>
+ Choices: yes, no, maybe
+ </literal>
+ </entry>
+ </row>
+ <row>
+ <entry>multiselect</entry>
+ <entry>
+ Just like the select data type, except the user can choose any
+ number of items from the list. This means that the
+ <literal>Default:</literal> field and the actual value of the
+ question may be a comma and space delimited list of values,
+ just like the <literal>Choices:</literal> field.
+ </entry>
+ </row>
+ <row>
+ <entry>note</entry>
+ <entry>
+ This template is a note that can be displayed to the user. As
+ opposed to text, it is something important, that the user really
+ should see. If it is not possible to display it, it might be
+ saved to a log file or mailbox for them to see later.
+ </entry>
+ </row>
+ <row>
+ <entry>text</entry>
+ <entry>
+ This template is a scrap of text that can be displayed to
+ the user. It's intended to be used for mostly cosmetic
+ reasons, touching up around other questions that are asked
+ at the same time. Unlike a note, it isn't treated as
+ something the user should definitely see. Less complex frontends
+ may refuse to ever display this type of element.
+ </entry>
+ </row>
+ <row>
+ <entry>password</entry>
+ <entry>
+ Holds a password. Use with caution. Be aware that the password
+ the user enters will be written to a database. You
+ should consider clearing that value out of the database as soon
+ as is possible.
+ </entry>
+ </row>
+ </tbody>
+</tgroup>
+</table>
+
+debian-policy (3.5.0.0) unstable; urgency=low
+
+ * There have been numerous changes since the last major change, and
+ peole have had tiome now to review the recent changes, so I am
+ updating the policy minor version to reflect the quantity and
+ magnitude of changes since 3.2.1
+ * More spelling corrections, thanks to "Christian T. Steigies"
+ <cts@nikocity.de>
+ * Added mention of DEB_BUILD_OPTIONS in upgrading checklist.
+ closes: Bug#83924
+ * Fixed some typos. closes: Bug#83960
+ * Policy now mentions preinst scripts. closes: Bug#80342
+ * [AMENDMENT 2000/12/26] allow/document use of Debian Configuration
+ management system (debconf) closes: Bug#80347
+ * Yet more typo fixes closes: Bug#82743
+ * document the fact that x font utilities have moved to the package
+ xutils, closes: Bug#82966
+ * Fixed the date in the virtual package list closes: Bug#83438
+ * Cleaned up some ephemeral informative foornotes of the polic. Thanks
+ to Branden Robinson <branden@debian.org> closes: Bug#83065
+ * Corrected reference to the mime policy. closes: Bug#79891
+ * Corrected reference to the menu policy. closes: Bug#75925
+ * Added a note to the effect that the example make snippet used to
+ illustrate the DEB_BUILD_OPTIONS environment variable is merely
+ informative, and expanded the example to dismiss any confusion about
+ potential failure due to accidentally trying to strip scripts.
+ closes: Bug#80506
+
+ -- Manoj Srivastava <srivasta@debian.org> Sun, 28 Jan 2001 21:59:16 -0600
+
debian-policy (3.2.1.2) unstable; urgency=low
* The minimal change in version number is so that people can test and
menu-policy.text.gz \
policy-process.text.gz policy-process.pdf.gz \
proposal.text.gz menu-policy.pdf.gz proposal.pdf.gz \
- mime-policy.text.gz mime-policy.pdf.gz
+ mime-policy.text.gz mime-policy.pdf.gz \
+ debconf_spec/debconf_specification.html \
+ debconf_spec/debconf_specification.txt.gz \
+
STAMPS_TO_CLEAN = stamp-policy stamp-build stamp-configure
DIRS_TO_CLEAN = debian/tmp policy.html fhs \
menu-policy.html mime-policy.html \
version.ent proposal.sgml proposal.text.gz \
menu-policy.sgml menu-policy.text.gz \
mime-policy.sgml mime-policy.text.gz \
- policy-process.text.gz policy-process.sgml
+ policy-process.text.gz policy-process.sgml \
+ debconf_spec/debconf_specification.html \
+ debconf_spec/debconf_specification.txt.gz
BYHAND_FILES =policy.text.gz libc6-migration.text \
virtual-package-names-list.text menu-policy.text.gz \
- mime-policy.text.gz
+ mime-policy.text.gz policy.ps.gz policy.pdf.gz \
+ policy.html.tar.gz \
+ debconf_spec/debconf_specification.txt.gz
install_file = /usr/bin/install -p -o root -g root -m 644
GROFF_TMAC_PATH=. cd fhs && $(MAKE) fhs.ps fhs.pdf fhs.txt
lynx -dump fhs-changes-2.1.html > fhs/fhs-changes-2.1.text
lynx -dump upgrading-checklist.html > upgrading-checklist.text
+ $(MAKE) -c debconf_spec all
+ gzip -9f debconf_spec/debconf_specification.txt
touch stamp-build
configure: stamp-configure
chmod -R go=rX debian/tmp
dpkg --build debian/tmp ..
debiandoc2latexps policy.sgml
- mv policy.ps ../
- gzip -9qvf ../policy.ps
- debiandoc2latexpdf policy.sgml
- mv policy.pdf ../
- gzip -9qfv ../policy.pdf
- GZIP=-9v tar zcf ../policy.html.tar.gz policy.html
+ gzip -9qvf policy.ps
+ debiandoc2latexpdf policy.sgml
+ gzip -9qfv policy.pdf
+ GZIP=-9v tar zcf policy.html.tar.gz policy.html
$(install_file) version.ent $(DOCDIR)/
- dpkg-distaddfile -fdebian/files policy.ps.gz byhand -
- dpkg-distaddfile -fdebian/files policy.pdf.gz byhand -
- dpkg-distaddfile -fdebian/files policy.html.tar.gz byhand -
- for i in $(BYHAND_FILES); do \
- $(install_file) $$i .. ; \
- dpkg-distaddfile -fdebian/files $$i byhand - ; \
+ for i in $(BYHAND_FILES); do \
+ $(install_file) $$i .. ; \
+ dpkg-distaddfile -fdebian/files `filename $$i` byhand - ; \
done
touch stamp-policy
the part of a user installing many packages. This means,
amongst other things, using the <tt>--quiet</tt> option on
<prgn>install-info</prgn>.</p>
-
+
<p>
- Packages should try to minimize the amount of prompting
- they need to do, and they should ensure that the user will
- only ever be asked each question once. This means that
- packages should try to use appropriate shared
- configuration files (such as <tt>/etc/papersize</tt> and
- <tt>/etc/news/server</tt>), rather than each prompting for
- their own list of required pieces of information.</p>
-
+ Errors which occur during the execution of an installation
+ script must be checked and the installation must not
+ continue after an error.
+ </p>
+
<p>
+ Note, that <ref id="scripts">, in general applies to package
+ maintainer scripts, too.
+ </p>
+
+ <p>
+ You should not use <tt>dpkg-divert</tt>' on a file
+ belonging to another package without consulting the
+ maintainer of that package first.
+ </p>
+ <p>
+ All packages which supply an instance of a common command
+ name (or, in general, filename) should generally use
+ <prgn>update-alternatives</prgn>, so that they may be
+ installed together. If <prgn>update-alternatives</prgn>
+ is not used, then each package must use
+ <var>Conflicts</var> to ensure that other packages are
+ de-installed. (In this case, it may be appropriate to
+ specify a conflict against earlier versions of something
+ that previously did not use
+ <prgn>update-alternatives</prgn> - this is an exception to
+ the usual rule that this not allowed).
+ </p>
+
+
+ <sect2>
+ <heading>Prompting in maintainer scripts</heading>
+ <p>
+ Package maintainer scripts may prompt the user if
+ necessary. Prompting may be accomplished by hand, or by
+ communicating with a program, such as
+ <prgn>debconf</prgn>, which conforms to the Debian
+ Configuration management specification, version 2 or
+ higher. (Included in the
+ <file>debconf_specification</file> files in the
+ <package>debian-policy</package> package.)
+ You may also find this file on the FTP site
+ <ftpsite>ftp.debian.org</ftpsite> in
+ <ftppath>/debian/doc/package-developer/debconf_specification.txt.gz</ftppath>
+ or your local mirror.
+ <footnote>
+ <p>
+ 2.5% of Debian packages
+ [<url id="http://kitenet.net/programs/debconf/stats/">]
+ use debconf to prompt the user at install time, and
+ this number is growing daily. The benefits of using
+ debconf are briefly explained at
+ <url id="http://kitenet.net/doc/debconf-doc/introduction.html">;
+ they include preconfiguration, (mostly)
+ noninteractive installation, elimination of
+ redundant prompting, consistency of user interface,
+ etc.
+ </p>
+ <p>
+ With this increasing number of packages using
+ debconf, plus the existance of a nascent second
+ implementation of the Debian configuration
+ management system (<package>cdebconf</package>), and
+ the stabalization of the protocol these things use,
+ the time has finally come to reflect the use of
+ these things in policy.
+
+ </p>
+ </footnote>
+ </p>
+ <p>
+ Packages which use the Debian Configuration management
+ specification may contain an additional
+ <file>config</file> script and a <file>templates</file>
+ file in their control archive. The <prgn>config</prgn>
+ script can be run before the preinst, and before the
+ package is unpacked or any of its dependancies or
+ pre-dependancies are satisfied, so it must work using
+ only the tools present in the <em>Essential</em>
+ packages.
+ <footnote>
+ <p>
+ Debconf or another tool that implements the Debian
+ Configuration management specification will also be
+ installed, and any versioned dependancies on it will
+ be satisfied before preconfiguration begins.
+ </p>
+ </footnote>
+ </p>
+
+ <p>
+ Packages should try to minimize the amount of prompting
+ they need to do, and they should ensure that the user
+ will only ever be asked each question once. This means
+ that packages should try to use appropriate shared
+ configuration files (such as <tt>/etc/papersize</tt> and
+ <tt>/etc/news/server</tt>), and shared debconf variables
+ rather than each prompting for their own list of
+ required pieces of information.
+ </p>
+
+ <p>
It also means that an upgrade should not ask the same
questions again, unless the user has used <tt>dpkg
--purge</tt> to remove the package's configuration. The
documented.</p>
<p>
- If a package has a vitally important piece of information
- to pass to the user (such as "don't run me as I am, you
- must edit the following configuration files first or you
- risk your system emitting badly-formatted messages"), it
- should display this in the <prgn>postinst</prgn> script
- and prompt the user to hit return to acknowledge the
- message. Copyright messages do not count as vitally
- important (they belong in
- <tt>/usr/share/doc/<var>package</var>/copyright</tt>); neither
- do instructions on how to use a program (these should be
- in on line documentation, where all the users can see
- them).</p>
+ If a package has a vitally important piece of
+ information to pass to the user (such as "don't run me
+ as I am, you must edit the following configuration files
+ first or you risk your system emitting badly-formatted
+ messages"), it should display this in the
+ <prgn>config</prgn> or <prgn>postinst</prgn> script and
+ prompt the user to hit return to acknowledge the
+ message. Copyright messages do not count as vitally
+ important (they belong in
+ <tt>/usr/share/doc/<var>package</var>/copyright</tt>);
+ neither do instructions on how to use a program (these
+ should be in on line documentation, where all the users
+ can see them).</p>
<p>
Any necessary prompting should almost always be confined
- to the post-installation script, and should be protected
- with a conditional so that unnecessary prompting doesn't
- happen if a package's installation fails and the
- <prgn>postinst</prgn> is called with
+ to the <prgn>config</prgn> or <prgn>postinst</prgn>
+ script. If it is done in the <prgn>postinst</prgn>, it
+ should be protected with a conditional so that unnecessary
+ prompting doesn't happen if a package's installation fails
+ and the <prgn>postinst</prgn> is called with
<tt>abort-upgrade</tt>, <tt>abort-remove</tt> or
<tt>abort-deconfigure</tt>.</p>
- <p>
- Errors which occur during the execution of an installation
- script should be checked and the installation should not
- continue after an error.</p>
-
- <p>
- Note, that <ref id="scripts">, in general applies to
- package maintainer scripts, too.</p>
-
- <p>
- You should not use <prgn>dpkg-divert</prgn> on a file
- belonging to another package without consulting the maintainer
- of that package first.</p>
-
- <p>
- All packages which supply an instance of a common command
- name (or, in general, filename) should generally use
- <prgn>update-alternatives</prgn>, so that they may be
- installed together. If <prgn>update-alternatives</prgn>
- is not used, then each package must use <tt>Conflicts</tt>
- to ensure that other packages are de-installed. (In this
- case, it may be appropriate to specify a conflict against
- earlier versions of something that previously did not use
- <prgn>update-alternatives</prgn> -- this is an exception to
- the usual rule that this not allowed).
- </p>
</sect1>
</sect>
<sect>
</p>
<p>
- Broadly speaking the <prgn></prgn> is called before
+ Broadly speaking the <prgn>preinst</prgn> is called before
(a particular version of) a package is installed, and the
<prgn>postinst</prgn> afterwards; the <prgn>prerm</prgn>
before (a version of) a package is removed and the
The <prgn>foo</prgn> binary depends on the
<prgn>libbar</prgn> shared library, but no package seems
to provide a <tt>*.shlibs</tt> file in
- <tt></tt>var/lib/dpkg/info/. Let's determine the package
+ <tt>var/lib/dpkg/info/</tt>. Let's determine the package
responsible:
</p>
<p>
Menu entries should follow the current menu policy as
defined in the file <ftpsite>ftp.debian.org</ftpsite> in
- <ftppath>/debian/doc/package-developer/menu-policy.txt</ftppath>
+ <ftppath>/debian/doc/package-developer/menu-policy.text.gz</ftppath>
or your local mirror. In addition, it is included in the
<tt>debian-policy</tt> package.
</p>
compose, edit or print MIME types should register themselves
as such following the current MIME support policy as defined
in the file found on <ftpsite>ftp.debian.org</ftpsite> in
- <ftppath>/debian/doc/package-developer/mime_policy.txt</ftppath>
+ <ftppath>/debian/doc/package-developer/mime-policy.text.gz</ftppath>
or your local mirror. In addition, it is included in the
<tt>debian-policy</tt> package.
</p>
</p>
</footnote>
+
<example>
CFLAGS = -O2 -Wall
INSTALL = install
+ INSTALL_FILE = $(INSTALL) -p -o root -g root -m 644
+ INSTALL_PROGRAM = $(INSTALL) -p -o root -g root -m 755
+ INSTALL_SCRIPT = $(INSTALL) -p -o root -g root -m 755
+ INSTALL_DIR = $(INSTALL) -p -d -o root -g root -m 755
ifneq (,$(findstring debug,$(DEB_BUILD_OPTIONS)))
CFLAGS += -g
endif
ifeq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS)))
- INSTALL += -s
+ INSTALL_PROGRAM += -s
endif
- </example></p>
+ </example>
+
+ Please note that the above example is merely informative,
+ and is not a policy mandate. You may have to massage this
+ example in order to make it work for your package.
+
+ </p>
<p>
It is up to the package maintainer to decide what
<sect>
- <heading>Mail transport agents</heading>
+ <heading>Mail transport, delivery and user agents</heading>
<p>
Debian packages which process electronic mail, whether
All Debian MUAs, MTAs, MDAs and other mailbox accessing
programs (like IMAP daemons) must lock the mailbox in an
NFS-safe way. This means that <tt>fcntl()</tt> locking must
- to be combined with dot locking. To avoid dead locks, a
+ be combined with dot locking. To avoid deadlocks, a
program should use <tt>fcntl()</tt> first and dot locking
after this or alternatively implement the two locking
methods in a non blocking way<footnote>
in question is of standard or higher priority, in which case
X-specific binaries may be split into a separate package, or
alternative versions of the package with X support may be
- provided.<footnote>
- <p>
- <strong>NOTE</strong> The forthcoming major X Window
- System release shall probably change this
- drastically.
- </p>
- <p>
- This seems to be more what people want. It will enable
- packages like vim-tty to become legal if they are
- promoted to standard priority. Also, that X client in
- mtools can be split into its own package and made
- optional.
- </p>
- <p>
- This paves the way for xlib6g and xfree86-common to be
- moved from standard to optional, <strong>if</strong> all
- Xlib dependent packages are moved from standard to
- optional priority (or if non-Xlib-linked versions are
- retained in standard). That, however is up to the
- affected package maintainers and the archive
- maintainers, and is not mandated by this policy.
- </p>
- </footnote>
+ provided.
</p>
virtual package <tt>xserver</tt>.
<footnote>
<p>
- Rationale: implement current practice, and provide an
- actual policy for usage of the "xserver" virtual package
- which appears in the virtual packages list.
- In a nutshell, X servers that interface directly with
- the display and input hardware or via another subsystem
- (e.g., GGI) should provide xserver. Things like Xvfb,
- Xnest, and Xprt should not. <strong>NOTE</strong> The
- forthcoming major X Window System release shall probably
- change this drastically.
+ This implements current practice, and provides an actual
+ policy for usage of the "xserver" virtual package which
+ appears in the virtual packages list. In a nutshell, X
+ servers that interface directly with the display and input
+ hardware or via another subsystem (e.g., GGI) should provide
+ xserver. Things like Xvfb, Xnest, and Xprt should not.
</p>
</footnote>
</p>
<item>
BDF fonts should be converted to PCF fonts with the
<tt>bdftopcf</tt> utility (available in the
- <tt>xbase-clients</tt> package, <tt>gzip</tt>ped, and
+ <tt>xutils</tt> package, <tt>gzip</tt>ped, and
placed in a directory that corresponds to their
resolution:
<list>
</item>
<item>
Font packages must declare a dependency on
- <tt>xbase-clients</tt> and, in the package
+ <tt>xutils</tt> and, in the package
post-installation and post-removal scripts, invoke the
<tt>mkfontdir</tt> command on each directory into
which they installed fonts.
<item>
Font packages that provide one or more
<tt>fonts.scale</tt> files as described above must declare a
- versioned dependency on <tt>xbase-clients (>=
- 3.3.3.1-5)</tt> and invoke <tt>update-fonts-scale</tt> on each
+ versioned dependency on <tt>xutils (>=
+ 4.0.2)</tt> and invoke <tt>update-fonts-scale</tt> on each
directory into which they installed fonts
<em>before</em> invoking <tt>mkfontdir</tt> on that
directory. This invocation must occur in both the
<item>
Font packages that provide one or more
<tt>fonts.alias</tt> files as described above must
- declare a versioned dependency on <tt>xbase-clients
- (>= 3.3.3.1-5)</tt> and, in the package
+ declare a versioned dependency on <tt>xutils
+ (>= 4.0.2)</tt> and, in the package
post-installation and post-removal scripts, invoke
<tt>update-fonts-alias</tt> on each directory into
which they installed fonts.
Created On : Thu Oct 29 20:54:48 1998
Created On Node : tiamat.datasync.com
Last Modified By : Manoj Srivastava
- Last Modified On : Thu Jan 18 01:32:14 2001
+ Last Modified On : Fri Jan 19 14:01:36 2001
Last Machine Used: glaurung.green-gryphon.com
- Update Count : 14
+ Update Count : 15
Status : Unknown, Use with caution!
HISTORY :
Description :
Policy Manual:
- By default executables should not be built with the debugging
option -g. Instead, it is recommended to support building the
- package with debugging information optionally.
+ package with debugging information optionally. Please look at the
+ examples using DEB_BUILD_OPTIONS in the policy manual.
- Policy for packages where the upstream uses html changelog
files has been expanded. In short, a plain text changelog file
should always be generated for the upstream changes.
- Policy for packages providing an X terminal emulator has been
codified (use virtual package x-terminal-emulator)
- Policy for packages providing an X window manager has been
- codified (use virtual package x-window-anager, and also as an
+ codified (use virtual package x-window-manager, and also as an
alternative for /usr/bin/x-window-manager. The policy has
guidelines on how to calculate priority)
- Policy for packages providing an X fonts has been
- The location of the GPL has changed to
/usr/share/common-licenses. This may require changing the
copyright files to point to the correct location of the GPL and
- other major licences
+ other major licenses
- Packages that use libtool to create shared libraries must
include the .la files in the -dev packages.
- Use logrotate to rotate log files
and owners") to Section 4.9. All subsections of the old
Section 5 after 5.5 were moved down to fill in the number
gap.
- - Modified the section about changelog files to accomodate
+ - Modified the section about changelog files to accommodate
upstream changelogs which were formatted as HTML/ These
- upstream chagelog files should now be accessible as
+ upstream changelog files should now be accessible as
/usr/doc/package/changelog.html.gz
+ Symlinks are permissible to link the real, or upstream,
changelog name to the Debian mandated name.
Added rsh-client
Added telnet-client
Manoj Srivastava
- 16 January 1001 Added rsh server
+ 16 January 2001 Added rsh server
Added telnet-server
projects / debian / debian-policy.git / commitdiff