policy/ap-pkg-conffiles.rst

   1 Configuration file handling (from old Packaging Manual)
   2 =======================================================
   3
   4 ``dpkg`` can do a certain amount of automatic handling of package
   5 configuration files.
   6
   7 Whether this mechanism is appropriate depends on a number of factors,
   8 but basically there are two approaches to any particular configuration
   9 file.
  10
  11 The easy method is to ship a best-effort configuration in the package,
  12 and use ``dpkg``'s conffile mechanism to handle updates. If the user is
  13 unlikely to want to edit the file, but you need them to be able to
  14 without losing their changes, and a new package with a changed version
  15 of the file is only released infrequently, this is a good approach.
  16
  17 The hard method is to build the configuration file from scratch in the
  18 ``postinst`` script, and to take the responsibility for fixing any
  19 mistakes made in earlier versions of the package automatically. This
  20 will be appropriate if the file is likely to need to be different on
  21 each system.
  22
  23 .. _s-sE.1:
  24
  25 Automatic handling of configuration files by ``dpkg``
  26 -----------------------------------------------------
  27
  28 A package may contain a control information file called ``conffiles``.
  29 This file should be a list of filenames of configuration files needing
  30 automatic handling, separated by newlines. The filenames should be
  31 absolute pathnames, and the files referred to should actually exist in
  32 the package.
  33
  34 When a package is upgraded ``dpkg`` will process the configuration files
  35 during the configuration stage, shortly before it runs the package's
  36 ``postinst`` script,
  37
  38 For each file it checks to see whether the version of the file included
  39 in the package is the same as the one that was included in the last
  40 version of the package (the one that is being upgraded from); it also
  41 compares the version currently installed on the system with the one
  42 shipped with the last version.
  43
  44 If neither the user nor the package maintainer has changed the file, it
  45 is left alone. If one or the other has changed their version, then the
  46 changed version is preferred - i.e., if the user edits their file, but
  47 the package maintainer doesn't ship a different version, the user's
  48 changes will stay, silently, but if the maintainer ships a new version
  49 and the user hasn't edited it the new version will be installed (with an
  50 informative message). If both have changed their version the user is
  51 prompted about the problem and must resolve the differences themselves.
  52
  53 The comparisons are done by calculating the MD5 message digests of the
  54 files, and storing the MD5 of the file as it was included in the most
  55 recent version of the package.
  56
  57 When a package is installed for the first time ``dpkg`` will install the
  58 file that comes with it, unless that would mean overwriting a file
  59 already on the file system.
  60
  61 However, note that ``dpkg`` will *not* replace a conffile that was
  62 removed by the user (or by a script). This is necessary because with
  63 some programs a missing file produces an effect hard or impossible to
  64 achieve in another way, so that a missing file needs to be kept that way
  65 if the user did it.
  66
  67 Note that a package should *not* modify a ``dpkg``-handled conffile in
  68 its maintainer scripts. Doing this will lead to ``dpkg`` giving the user
  69 confusing and possibly dangerous options for conffile update when the
  70 package is upgraded.
  71
  72 .. _s-sE.2:
  73
  74 Fully-featured maintainer script configuration handling
  75 -------------------------------------------------------
  76
  77 For files which contain site-specific information such as the hostname
  78 and networking details and so forth, it is better to create the file in
  79 the package's ``postinst`` script.
  80
  81 This will typically involve examining the state of the rest of the
  82 system to determine values and other information, and may involve
  83 prompting the user for some information which can't be obtained some
  84 other way.
  85
  86 When using this method there are a couple of important issues which
  87 should be considered:
  88
  89 If you discover a bug in the program which generates the configuration
  90 file, or if the format of the file changes from one version to the next,
  91 you will have to arrange for the postinst script to do something
  92 sensible - usually this will mean editing the installed configuration
  93 file to remove the problem or change the syntax. You will have to do
  94 this very carefully, since the user may have changed the file, perhaps
  95 to fix the very problem that your script is trying to deal with - you
  96 will have to detect these situations and deal with them correctly.
  97
  98 If you do go down this route it's probably a good idea to make the
  99 program that generates the configuration file(s) a separate program in
 100 ``/usr/sbin``, by convention called ``packageconfig`` and then run that
 101 if appropriate from the post-installation script. The ``packageconfig``
 102 program should not unquestioningly overwrite an existing configuration -
 103 if its mode of operation is geared towards setting up a package for the
 104 first time (rather than any arbitrary reconfiguration later) you should
 105 have it check whether the configuration already exists, and require a
 106 ``--force`` flag to overwrite it.
 107