File: //usr/share/doc/debian-policy/policy.html/ap-pkg-conffiles.html
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>5. Configuration file handling (from old Packaging Manual) — Debian Policy Manual v4.6.0.1</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/nature.css" />
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="6. Alternative versions of an interface - update-alternatives (from old Packaging Manual)" href="ap-pkg-alternatives.html" />
<link rel="prev" title="4. Control files and their fields (from old Packaging Manual)" href="ap-pkg-controlfields.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="ap-pkg-alternatives.html" title="6. Alternative versions of an interface - update-alternatives (from old Packaging Manual)"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="ap-pkg-controlfields.html" title="4. Control files and their fields (from old Packaging Manual)"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Debian Policy Manual v4.6.0.1</a> »</li>
<li class="nav-item nav-item-this"><a href=""><span class="section-number">5. </span>Configuration file handling (from old Packaging Manual)</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="configuration-file-handling-from-old-packaging-manual">
<h1><span class="section-number">5. </span>Configuration file handling (from old Packaging Manual)<a class="headerlink" href="#configuration-file-handling-from-old-packaging-manual" title="Permalink to this headline">¶</a></h1>
<p><code class="docutils literal notranslate"><span class="pre">dpkg</span></code> can do a certain amount of automatic handling of package
configuration files.</p>
<p>Whether this mechanism is appropriate depends on a number of factors,
but basically there are two approaches to any particular configuration
file.</p>
<p>The easy method is to ship a best-effort configuration in the package,
and use <code class="docutils literal notranslate"><span class="pre">dpkg</span></code>’s conffile mechanism to handle updates. If the user is
unlikely to want to edit the file, but you need them to be able to
without losing their changes, and a new package with a changed version
of the file is only released infrequently, this is a good approach.</p>
<p>The hard method is to build the configuration file from scratch in the
<code class="docutils literal notranslate"><span class="pre">postinst</span></code> script, and to take the responsibility for fixing any
mistakes made in earlier versions of the package automatically. This
will be appropriate if the file is likely to need to be different on
each system.</p>
<section id="automatic-handling-of-configuration-files-by-dpkg">
<span id="s-se-1"></span><h2><span class="section-number">5.1. </span>Automatic handling of configuration files by <code class="docutils literal notranslate"><span class="pre">dpkg</span></code><a class="headerlink" href="#automatic-handling-of-configuration-files-by-dpkg" title="Permalink to this headline">¶</a></h2>
<p>A package may contain a control information file called <code class="docutils literal notranslate"><span class="pre">conffiles</span></code>.
This file should be a list of filenames of configuration files needing
automatic handling, separated by newlines. The filenames should be
absolute pathnames, and the files referred to should actually exist in
the package.</p>
<p>When a package is upgraded <code class="docutils literal notranslate"><span class="pre">dpkg</span></code> will process the configuration files
during the configuration stage, shortly before it runs the package’s
<code class="docutils literal notranslate"><span class="pre">postinst</span></code> script,</p>
<p>For each file it checks to see whether the version of the file included
in the package is the same as the one that was included in the last
version of the package (the one that is being upgraded from); it also
compares the version currently installed on the system with the one
shipped with the last version.</p>
<p>If neither the user nor the package maintainer has changed the file, it
is left alone. If one or the other has changed their version, then the
changed version is preferred - i.e., if the user edits their file, but
the package maintainer doesn’t ship a different version, the user’s
changes will stay, silently, but if the maintainer ships a new version
and the user hasn’t edited it the new version will be installed (with an
informative message). If both have changed their version the user is
prompted about the problem and must resolve the differences themselves.</p>
<p>The comparisons are done by calculating the MD5 message digests of the
files, and storing the MD5 of the file as it was included in the most
recent version of the package.</p>
<p>When a package is installed for the first time <code class="docutils literal notranslate"><span class="pre">dpkg</span></code> will install the
file that comes with it, unless that would mean overwriting a file
already on the file system.</p>
<p>However, note that <code class="docutils literal notranslate"><span class="pre">dpkg</span></code> will <em>not</em> replace a conffile that was
removed by the user (or by a script). This is necessary because with
some programs a missing file produces an effect hard or impossible to
achieve in another way, so that a missing file needs to be kept that way
if the user did it.</p>
<p>Note that a package should <em>not</em> modify a <code class="docutils literal notranslate"><span class="pre">dpkg</span></code>-handled conffile in
its maintainer scripts. Doing this will lead to <code class="docutils literal notranslate"><span class="pre">dpkg</span></code> giving the user
confusing and possibly dangerous options for conffile update when the
package is upgraded.</p>
</section>
<section id="fully-featured-maintainer-script-configuration-handling">
<span id="s-se-2"></span><h2><span class="section-number">5.2. </span>Fully-featured maintainer script configuration handling<a class="headerlink" href="#fully-featured-maintainer-script-configuration-handling" title="Permalink to this headline">¶</a></h2>
<p>For files which contain site-specific information such as the hostname
and networking details and so forth, it is better to create the file in
the package’s <code class="docutils literal notranslate"><span class="pre">postinst</span></code> script.</p>
<p>This will typically involve examining the state of the rest of the
system to determine values and other information, and may involve
prompting the user for some information which can’t be obtained some
other way.</p>
<p>When using this method there are a couple of important issues which
should be considered:</p>
<p>If you discover a bug in the program which generates the configuration
file, or if the format of the file changes from one version to the next,
you will have to arrange for the postinst script to do something
sensible - usually this will mean editing the installed configuration
file to remove the problem or change the syntax. You will have to do
this very carefully, since the user may have changed the file, perhaps
to fix the very problem that your script is trying to deal with - you
will have to detect these situations and deal with them correctly.</p>
<p>If you do go down this route it’s probably a good idea to make the
program that generates the configuration file(s) a separate program in
<code class="docutils literal notranslate"><span class="pre">/usr/sbin</span></code>, by convention called <code class="docutils literal notranslate"><span class="pre">packageconfig</span></code> and then run that
if appropriate from the post-installation script. The <code class="docutils literal notranslate"><span class="pre">packageconfig</span></code>
program should not unquestioningly overwrite an existing configuration -
if its mode of operation is geared towards setting up a package for the
first time (rather than any arbitrary reconfiguration later) you should
have it check whether the configuration already exists, and require a
<code class="docutils literal notranslate"><span class="pre">--force</span></code> flag to overwrite it.</p>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">5. Configuration file handling (from old Packaging Manual)</a><ul>
<li><a class="reference internal" href="#automatic-handling-of-configuration-files-by-dpkg">5.1. Automatic handling of configuration files by <code class="docutils literal notranslate"><span class="pre">dpkg</span></code></a></li>
<li><a class="reference internal" href="#fully-featured-maintainer-script-configuration-handling">5.2. Fully-featured maintainer script configuration handling</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="ap-pkg-controlfields.html"
title="previous chapter"><span class="section-number">4. </span>Control files and their fields (from old Packaging Manual)</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="ap-pkg-alternatives.html"
title="next chapter"><span class="section-number">6. </span>Alternative versions of an interface - <code class="docutils literal notranslate"><span class="pre">update-alternatives</span></code> (from old Packaging Manual)</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/ap-pkg-conffiles.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="ap-pkg-alternatives.html" title="6. Alternative versions of an interface - update-alternatives (from old Packaging Manual)"
>next</a> |</li>
<li class="right" >
<a href="ap-pkg-controlfields.html" title="4. Control files and their fields (from old Packaging Manual)"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Debian Policy Manual v4.6.0.1</a> »</li>
<li class="nav-item nav-item-this"><a href=""><span class="section-number">5. </span>Configuration file handling (from old Packaging Manual)</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.2.0.
</div>
</body>
</html>