On Sun, 18 Sep 2022 20:52:23 -0700 Russ Allbery <r...@debian.org> wrote: > Ansgar <ans...@43-1.org> writes: > > > I would like to recommend packages to use tmpfiles.d(5) to manage > > creating directories in locations such as /var or /etc instead of > > maintainer scripts. > > > It could also be used to create trivial files below /var that should be > > recreated if deleted by accident (such as atd's sequence number which is > > currently created by the maintainer script). > > Hi all, > > Here's where I think we currently are with this proposal: > > * There should no longer be any blocker to adding a dependency on > systemd-tmpfiles since systemd-standalone-tmpfiles exists. > > * So far as I can tell, dh_installtmpfiles adds the correct stanza to the > postinst script for a service to run systemd-tmpfiles after the package > has installed its tmpfiles.d fragment. I believe that addresses > creating these files on installation on systems without any init system? > (Obviously if tmpfs file systems are subsequently reset on such a > system, there is nothing in place to recreate these tmp files, but I > think that's expected and not something we can address?) > > * Guillem plans to add support to dpkg to register these files properly as > package-associated files and also handle creation of the files. This is > great, and I am 100% in favor of it. I don't think that blocks this > change; to the contrary, I think this change is a good incremental step > towards that world, since it moves temporary file creation out of > maintainer scripts into a declarative syntax. dpkg can then either > consume the same syntax or packages can later convert that syntax to > whatever dpkg uses, depending on how the dpkg implementation works, > which will be a simple and easy-to-detect migration that Lintian can > diagnose. > > Therefore, I don't see anything blocking adopting this as a policy now, > and it seems like an obviously good idea to me. > > Am I missing something? If not, I think the next step is for someone to > propose wording.
I've done an initial attempt to define the wording, although I'm sure it will need quite a few changes. Attached as a patch, and also available on Salsa: https://salsa.debian.org/bluca/policy/-/commits/tmpfiles Happy to move/reword/change/enhance as required. > In order to handle installations that have no init system, I think we may > have to require that the dependency be listed as: > > systemd-standalone-tmpfiles | systemd-tmpfiles > > to avoid trying to install systemd into an init-free chroot. Maybe I have > that wrong? Currently, dh_installtmpfiles doesn't add a dependency at > all, probably because it assumes that the package will use a fallback to > create the files in cases without an init system? Either way, we should > address this in the Policy wording, and then encode that in > dh_installtmpfiles if needed. For now I've kept only a mention of the 'systemd-tmpfiles' virtual package. As maintainers we would really prefer if the 'main' implementation is pulled in whenever possible. When a minimal installation is desired (ie, a minbase), it is possible to manually specify the -standalone variant. This was a controversial point last year, see: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1017441 We could even decide that no dependency is added at all by dh, and instead the build tool needs to decide if it's building an image where tmpfiles snippets need to be ran, and if so pull in the preferred alternative. -- Kind regards, Luca Boccassi
From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001 From: Luca Boccassi <bl...@debian.org> Date: Tue, 9 May 2023 01:38:13 +0100 Subject: [PATCH] Define tmpfiles.d interface and usage --- locales/ja/LC_MESSAGES/ch-files.po | 97 ++++-- .../ja/LC_MESSAGES/ch-maintainerscripts.po | 293 ++++++++++-------- policy/ch-files.rst | 39 +++ policy/ch-maintainerscripts.rst | 6 + 4 files changed, 288 insertions(+), 147 deletions(-) diff --git a/locales/ja/LC_MESSAGES/ch-files.po b/locales/ja/LC_MESSAGES/ch-files.po index c241418..ec9d329 100644 --- a/locales/ja/LC_MESSAGES/ch-files.po +++ b/locales/ja/LC_MESSAGES/ch-files.po @@ -10,7 +10,7 @@ msgid "" msgstr "" "Project-Id-Version: Debian Policy Manual 4.1.6.0\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2021-08-17 20:06-0700\n" +"POT-Creation-Date: 2023-05-09 01:31+0100\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" "Language-Team: LANGUAGE <l...@li.org>\n" @@ -963,7 +963,60 @@ msgid "" " to ASCII when it is possible to do so." msgstr "" -#: ../../ch-files.rst:726 +#: ../../ch-files.rst:728 +msgid "tmpfiles.d" +msgstr "" + +#: ../../ch-files.rst:730 +msgid "" +"Packages might need additional files or directories to implement their " +"functionality. Directories that are located under ``/var/`` or ``/etc/``," +" and files that are located under ``/var/``, should not be created " +"manually via maintainer scripts, but instead be declaratively defined via" +" the `tmpfiles.d " +"<https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html>`_ " +"interface. The ``tmpfiles.d`` file format is defined by the ``systemd`` " +"project, and is guaranteed to be stable. Ideally, such definitions should" +" be defined upstream where applicable, and shipped as they are by Debian " +"packages." +msgstr "" + +#: ../../ch-files.rst:739 +msgid "" +"Details about the syntax and installation paths for ``tmpfiles.d`` are " +"defined by its `reference implementation's documentation, " +"<https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html>`_ and " +"will not be redefined here." +msgstr "" + +#: ../../ch-files.rst:744 +msgid "" +"``tmpfiles.d`` snippets should be usable on systems that do not boot " +"(such as a very minimal chroot image), and also systems booting with init" +" systems other than ``systemd``." +msgstr "" + +#: ../../ch-files.rst:748 +msgid "" +"``tmpfiles.d`` snippets should be detected at package build time by tools" +" such as ``debhelper``, packaged, and the appropriate snippet to call " +"them on install should be automatically added by helpers such as " +"``dh_installtmpfiles``, including the required dependency on the " +"appropriate ``tmpfiles.d`` implementation, so that such dependency can be" +" also satisfied on systems that are not bootable." +msgstr "" + +#: ../../ch-files.rst:755 +msgid "" +"Init systems are required to integrate with ``tmpfiles.d`` and run the " +"service that applies them on boot, and regularly for cleanup purposes. " +"The documentation for the reference implementation, `systemd-tmpfiles, " +"<https://www.freedesktop.org/software/systemd/man/systemd-"; +"tmpfiles.html>`_ explains how to call the program so that the appropriate" +" ``tmpfiles.d`` snippets are applied at the appropriate time." +msgstr "" + +#: ../../ch-files.rst:763 msgid "" "If you are using GCC, ``-fPIC`` produces code with relocatable position " "independent code, which is required for most architectures to create a " @@ -971,7 +1024,7 @@ msgid "" "independent code is permitted in a shared library." msgstr "" -#: ../../ch-files.rst:731 +#: ../../ch-files.rst:768 msgid "" "Position independent code may have a performance penalty, especially on " "``i386``. However, in most cases the speed penalty must be measured " @@ -979,14 +1032,14 @@ msgid "" "independent code is even possible." msgstr "" -#: ../../ch-files.rst:737 +#: ../../ch-files.rst:774 msgid "" "Some of the reasons why this might be required is if the library contains" " hand crafted assembly code that is not relocatable, the speed penalty is" " excessive for compute intensive libs, and similar reasons." msgstr "" -#: ../../ch-files.rst:743 +#: ../../ch-files.rst:780 msgid "" "Some of the reasons for linking static libraries with the ``-fPIC`` flag " "are if, for example, one needs a Perl API for a library that is under " @@ -998,7 +1051,7 @@ msgid "" "``mklibs`` does in the Debian installer project." msgstr "" -#: ../../ch-files.rst:753 +#: ../../ch-files.rst:790 msgid "" "You might want to replace ``--strip-unneeded`` with ``--strip-debug`` for" " static libraries, as dh_strip does. When stripping static libraries, " @@ -1006,13 +1059,13 @@ msgid "" "your package build is reproducible." msgstr "" -#: ../../ch-files.rst:760 +#: ../../ch-files.rst:797 msgid "" "A common example are the so-called \"plug-ins\", internal shared objects " "that are dynamically loaded by programs using :manpage:`dlopen(3)`." msgstr "" -#: ../../ch-files.rst:764 +#: ../../ch-files.rst:801 msgid "" "These files store, among other things, all libraries on which that shared" " library depends. Unfortunately, if the ``.la`` file is present and " @@ -1025,7 +1078,7 @@ msgid "" "manage." msgstr "" -#: ../../ch-files.rst:775 +#: ../../ch-files.rst:812 msgid "" "The Open Group Base Specifications Issue 7, 2018 Edition, which is also " "known as POSIX.1-2017 and as IEEE Std 1003.1-2017 and is available on the" @@ -1033,14 +1086,14 @@ msgid "" "<http://pubs.opengroup.org/onlinepubs/9699919799/download/>`_." msgstr "" -#: ../../ch-files.rst:781 +#: ../../ch-files.rst:818 msgid "" "These features are in widespread use in the Linux community and are " "implemented in all of bash, dash, and ksh, the most common shells users " "may wish to use as ``/bin/sh``." msgstr "" -#: ../../ch-files.rst:786 +#: ../../ch-files.rst:823 msgid "" "This is necessary to allow top-level directories to be symlinks. If " "linking ``/var/run`` to ``/run`` were done with the relative symbolic " @@ -1049,20 +1102,20 @@ msgid "" "target." msgstr "" -#: ../../ch-files.rst:793 +#: ../../ch-files.rst:830 msgid "" "It's better to use ``mkfifo`` rather than ``mknod`` to create named pipes" " to avoid false positives from automated checks for packages incorrectly " "creating device files." msgstr "" -#: ../../ch-files.rst:798 +#: ../../ch-files.rst:835 msgid "" "The ``dpkg-maintscript-helper`` tool, available from the dpkg package, " "can help for this task." msgstr "" -#: ../../ch-files.rst:802 +#: ../../ch-files.rst:839 msgid "" "Rationale: There are two problems with hard links. The first is that some" " editors break the link while editing one of the files, so that the two " @@ -1070,7 +1123,7 @@ msgid "" "``dpkg`` might break the hard link while upgrading ``conffile``\\ s." msgstr "" -#: ../../ch-files.rst:809 +#: ../../ch-files.rst:846 msgid "" "The traditional approach to log files has been to set up *ad hoc* log " "rotation schemes using simple shell scripts and cron. While this approach" @@ -1080,7 +1133,7 @@ msgid "" "enough." msgstr "" -#: ../../ch-files.rst:816 +#: ../../ch-files.rst:853 msgid "" "The use of ``logrotate``, a program developed by Red Hat, is better, as " "it centralizes log management. It has both a configuration file " @@ -1088,7 +1141,7 @@ msgid "" "individual log rotation configurations (``/etc/logrotate.d``)." msgstr "" -#: ../../ch-files.rst:822 +#: ../../ch-files.rst:859 msgid "" "When a package is upgraded, and the owner or permissions of a file " "included in the package has changed, dpkg arranges for the ownership and " @@ -1101,7 +1154,7 @@ msgid "" "script. Care must be taken to handle downgrades as well, in that case." msgstr "" -#: ../../ch-files.rst:834 +#: ../../ch-files.rst:871 msgid "" "Ordinary files installed by ``dpkg`` (as opposed to ``conffile``\\ s and " "other similar objects) normally have their permissions reset to the " @@ -1202,3 +1255,11 @@ msgstr "" #~ " ``debian-devel`` first." #~ msgstr "" +#~ msgid "" +#~ "Details about the syntax and " +#~ "installation paths for ``tmpfiles.d`` are " +#~ "defined by its reference implementation's " +#~ "documentation, and will not be redefined" +#~ " here." +#~ msgstr "" + diff --git a/locales/ja/LC_MESSAGES/ch-maintainerscripts.po b/locales/ja/LC_MESSAGES/ch-maintainerscripts.po index 547b8d7..c111c5c 100644 --- a/locales/ja/LC_MESSAGES/ch-maintainerscripts.po +++ b/locales/ja/LC_MESSAGES/ch-maintainerscripts.po @@ -10,7 +10,7 @@ msgid "" msgstr "" "Project-Id-Version: Debian Policy Manual 4.1.6.0\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2022-12-15 15:54-0700\n" +"POT-Creation-Date: 2023-05-09 01:30+0100\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" "Language-Team: LANGUAGE <l...@li.org>\n" @@ -90,11 +90,20 @@ msgid "" "directories. These considerations really apply to all shell scripts." msgstr "" -#: ../../ch-maintainerscripts.rst:56 +#: ../../ch-maintainerscripts.rst:53 +msgid "" +"Maintainer scripts should not be used to create or remove auxiliary files" +" and/or directories that packages may need, such as those in ``/var/`` or" +" ``/etc/``. Instead, :ref:`s-tmpfiles.d` snippets should be shipped, " +"being ideally provided by the upstream sources, if any. For more details " +"about the ``tmpfiles.d`` interface, see :ref:`s-tmpfiles.d`." +msgstr "" + +#: ../../ch-maintainerscripts.rst:62 msgid "Maintainer scripts idempotency" msgstr "" -#: ../../ch-maintainerscripts.rst:58 +#: ../../ch-maintainerscripts.rst:64 msgid "" "It is necessary for the error recovery procedures that the scripts be " "idempotent. This means that if it is run successfully, and then it is " @@ -105,11 +114,11 @@ msgid "" " a success status if everything is OK. [#]_" msgstr "" -#: ../../ch-maintainerscripts.rst:69 +#: ../../ch-maintainerscripts.rst:75 msgid "Controlling terminal for maintainer scripts" msgstr "" -#: ../../ch-maintainerscripts.rst:71 +#: ../../ch-maintainerscripts.rst:77 msgid "" "Maintainer scripts are not guaranteed to run with a controlling terminal " "and may not be able to interact with the user. They must be able to fall " @@ -120,7 +129,7 @@ msgid "" "behavior." msgstr "" -#: ../../ch-maintainerscripts.rst:79 +#: ../../ch-maintainerscripts.rst:85 msgid "" "For high-priority prompts without a reasonable default answer, maintainer" " scripts may abort if there is no controlling terminal. However, this " @@ -129,11 +138,11 @@ msgid "" " to be a bug in the package." msgstr "" -#: ../../ch-maintainerscripts.rst:88 +#: ../../ch-maintainerscripts.rst:94 msgid "Exit status" msgstr "" -#: ../../ch-maintainerscripts.rst:90 +#: ../../ch-maintainerscripts.rst:96 msgid "" "Each script must return a zero exit status for success, or a nonzero one " "for failure, since the package management system looks for the exit " @@ -141,11 +150,11 @@ msgid "" "that datum." msgstr "" -#: ../../ch-maintainerscripts.rst:98 +#: ../../ch-maintainerscripts.rst:104 msgid "Summary of ways maintainer scripts are called" msgstr "" -#: ../../ch-maintainerscripts.rst:100 +#: ../../ch-maintainerscripts.rst:106 msgid "" "What follows is a summary of all the ways in which maintainer scripts may" " be called along with what facilities those scripts may rely on being " @@ -155,23 +164,23 @@ msgid "" " version of a package that is being upgraded from or downgraded from." msgstr "" -#: ../../ch-maintainerscripts.rst:107 +#: ../../ch-maintainerscripts.rst:113 msgid "The ``preinst`` script may be called in the following ways:" msgstr "" -#: ../../ch-maintainerscripts.rst:109 +#: ../../ch-maintainerscripts.rst:115 msgid "``new-preinst`` install" msgstr "" -#: ../../ch-maintainerscripts.rst:110 +#: ../../ch-maintainerscripts.rst:116 msgid "``new-preinst`` install *old-version* *new-version*" msgstr "" -#: ../../ch-maintainerscripts.rst:111 +#: ../../ch-maintainerscripts.rst:117 msgid "``new-preinst`` upgrade *old-version* *new-version*" msgstr "" -#: ../../ch-maintainerscripts.rst:113 +#: ../../ch-maintainerscripts.rst:119 msgid "" "The package will not yet be unpacked, so the ``preinst`` script cannot " "rely on any files included in its package. Only essential packages and " @@ -182,11 +191,11 @@ msgid "" "completely configured and has not been removed since then." msgstr "" -#: ../../ch-maintainerscripts.rst:129 +#: ../../ch-maintainerscripts.rst:135 msgid "``old-preinst`` abort-upgrade *new-version*" msgstr "" -#: ../../ch-maintainerscripts.rst:123 +#: ../../ch-maintainerscripts.rst:129 msgid "" "Called during error handling of an upgrade that failed after unpacking " "the new package because the ``postrm upgrade`` action failed. The " @@ -197,15 +206,15 @@ msgid "" "\"Half-Installed\" if an upgrade of the pre-dependency failed. [#]_" msgstr "" -#: ../../ch-maintainerscripts.rst:131 +#: ../../ch-maintainerscripts.rst:137 msgid "The ``postinst`` script may be called in the following ways:" msgstr "" -#: ../../ch-maintainerscripts.rst:138 +#: ../../ch-maintainerscripts.rst:144 msgid "``postinst`` configure *most-recently-configured-version*" msgstr "" -#: ../../ch-maintainerscripts.rst:134 +#: ../../ch-maintainerscripts.rst:140 msgid "" "The files contained in the package will be unpacked. All package " "dependencies will at least be \"Unpacked\". If there are no circular " @@ -214,25 +223,25 @@ msgid "" ":ref:`s-binarydeps`." msgstr "" -#: ../../ch-maintainerscripts.rst:140 +#: ../../ch-maintainerscripts.rst:146 msgid "``old-postinst`` abort-upgrade *new-version*" msgstr "" -#: ../../ch-maintainerscripts.rst:141 +#: ../../ch-maintainerscripts.rst:147 msgid "``conflictor's-postinst`` abort-remove in-favour *package* *new-version*" msgstr "" -#: ../../ch-maintainerscripts.rst:142 +#: ../../ch-maintainerscripts.rst:148 msgid "``postinst`` abort-remove" msgstr "" -#: ../../ch-maintainerscripts.rst:143 +#: ../../ch-maintainerscripts.rst:149 msgid "" "``deconfigured's-postinst`` abort-deconfigure in-favour *failed-install-" "package* *version* [ removing conflicting-package version ]" msgstr "" -#: ../../ch-maintainerscripts.rst:145 +#: ../../ch-maintainerscripts.rst:151 msgid "" "The files contained in the package will be unpacked. All package " "dependencies will at least be \"Half-Installed\" and will have previously" @@ -245,29 +254,29 @@ msgid "" "dependencies are not available is often the best approach." msgstr "" -#: ../../ch-maintainerscripts.rst:156 +#: ../../ch-maintainerscripts.rst:162 msgid "The ``prerm`` script may be called in the following ways:" msgstr "" -#: ../../ch-maintainerscripts.rst:158 +#: ../../ch-maintainerscripts.rst:164 msgid "``prerm`` remove" msgstr "" -#: ../../ch-maintainerscripts.rst:159 +#: ../../ch-maintainerscripts.rst:165 msgid "``old-prerm`` upgrade *new-version*" msgstr "" -#: ../../ch-maintainerscripts.rst:160 +#: ../../ch-maintainerscripts.rst:166 msgid "``conflictor's-prerm`` remove in-favour package *new-version*" msgstr "" -#: ../../ch-maintainerscripts.rst:161 +#: ../../ch-maintainerscripts.rst:167 msgid "" "``deconfigured's-prerm`` deconfigure in-favour *package-being-installed* " "*version* [removing conflicting-package version]" msgstr "" -#: ../../ch-maintainerscripts.rst:163 +#: ../../ch-maintainerscripts.rst:169 msgid "" "The package whose ``prerm`` is being called will be at least \"Half-" "Installed\". All package dependencies will at least be \"Half-Installed\"" @@ -277,38 +286,38 @@ msgid "" " \"Half-Installed\" due to a partial upgrade." msgstr "" -#: ../../ch-maintainerscripts.rst:174 +#: ../../ch-maintainerscripts.rst:180 msgid "``new-prerm`` failed-upgrade *old-version* *new-version*" msgstr "" -#: ../../ch-maintainerscripts.rst:172 +#: ../../ch-maintainerscripts.rst:178 msgid "" "Called during error handling when ``prerm upgrade`` fails. The new " "package will not yet be unpacked, and all the same constraints as for " "``preinst upgrade`` apply." msgstr "" -#: ../../ch-maintainerscripts.rst:176 +#: ../../ch-maintainerscripts.rst:182 msgid "The ``postrm`` script may be called in the following ways:" msgstr "" -#: ../../ch-maintainerscripts.rst:178 +#: ../../ch-maintainerscripts.rst:184 msgid "``postrm`` remove" msgstr "" -#: ../../ch-maintainerscripts.rst:179 +#: ../../ch-maintainerscripts.rst:185 msgid "``postrm`` purge" msgstr "" -#: ../../ch-maintainerscripts.rst:180 +#: ../../ch-maintainerscripts.rst:186 msgid "``old-postrm`` upgrade *new-version*" msgstr "" -#: ../../ch-maintainerscripts.rst:181 +#: ../../ch-maintainerscripts.rst:187 msgid "``disappearer's-postrm`` disappear overwriter *overwriter-version*" msgstr "" -#: ../../ch-maintainerscripts.rst:183 +#: ../../ch-maintainerscripts.rst:189 msgid "" "The ``postrm`` script is called after the package's files have been " "removed or replaced. The package whose ``postrm`` is being called may " @@ -319,11 +328,11 @@ msgid "" "dependencies if those dependencies are unavailable. [#]_" msgstr "" -#: ../../ch-maintainerscripts.rst:197 +#: ../../ch-maintainerscripts.rst:203 msgid "``new-postrm`` failed-upgrade *old-version* *new-version*" msgstr "" -#: ../../ch-maintainerscripts.rst:193 +#: ../../ch-maintainerscripts.rst:199 msgid "" "Called when the old ``postrm upgrade`` action fails. The new package will" " be unpacked, but only essential packages and pre-dependencies can be " @@ -332,30 +341,30 @@ msgid "" "and was never removed." msgstr "" -#: ../../ch-maintainerscripts.rst:199 +#: ../../ch-maintainerscripts.rst:205 msgid "``new-postrm`` abort-install" msgstr "" -#: ../../ch-maintainerscripts.rst:200 +#: ../../ch-maintainerscripts.rst:206 msgid "``new-postrm`` abort-install *old-version* *new-version*" msgstr "" -#: ../../ch-maintainerscripts.rst:201 +#: ../../ch-maintainerscripts.rst:207 msgid "``new-postrm`` abort-upgrade *old-version* *new-version*" msgstr "" -#: ../../ch-maintainerscripts.rst:203 +#: ../../ch-maintainerscripts.rst:209 msgid "" "Called before unpacking the new package as part of the error handling of " "``preinst`` failures. May assume the same state as ``preinst`` can " "assume." msgstr "" -#: ../../ch-maintainerscripts.rst:210 +#: ../../ch-maintainerscripts.rst:216 msgid "Details of unpack phase of installation or upgrade" msgstr "" -#: ../../ch-maintainerscripts.rst:212 +#: ../../ch-maintainerscripts.rst:218 msgid "" "The procedure on installation/upgrade/overwrite/disappear (i.e., when " "running ``dpkg --unpack``, or the unpack stage of ``dpkg --install``) is " @@ -365,117 +374,117 @@ msgid "" "These are the \"error unwind\" calls listed below." msgstr "" -#: ../../ch-maintainerscripts.rst:219 +#: ../../ch-maintainerscripts.rst:225 msgid "Notify the currently installed package:" msgstr "" -#: ../../ch-maintainerscripts.rst:221 -msgid "If a version of the package is already \"Installed\", call" -msgstr "" - #: ../../ch-maintainerscripts.rst:227 +msgid "If a version of the package is already \"Installed\", call" +msgstr "" + +#: ../../ch-maintainerscripts.rst:233 msgid "" "If the script runs but exits with a non-zero exit status, ``dpkg`` will " "attempt:" msgstr "" -#: ../../ch-maintainerscripts.rst:234 +#: ../../ch-maintainerscripts.rst:240 msgid "" "If this works, the upgrade continues. If this does not work, the error " "unwind:" msgstr "" -#: ../../ch-maintainerscripts.rst:241 +#: ../../ch-maintainerscripts.rst:247 msgid "" "If this works, then the *old-version* is \"Installed\", if not, the old " "version is in a \"Half-Configured\" state." msgstr "" -#: ../../ch-maintainerscripts.rst:244 +#: ../../ch-maintainerscripts.rst:250 msgid "" "If a \"conflicting\" package is being removed at the same time, or if any" " package will be broken (due to ``Breaks``):" msgstr "" -#: ../../ch-maintainerscripts.rst:247 +#: ../../ch-maintainerscripts.rst:253 msgid "" "If ``--auto-deconfigure`` is specified, call, for each package to be " "deconfigured due to ``Breaks``:" msgstr "" -#: ../../ch-maintainerscripts.rst:255 ../../ch-maintainerscripts.rst:276 -#: ../../ch-maintainerscripts.rst:295 ../../ch-maintainerscripts.rst:336 -#: ../../ch-maintainerscripts.rst:352 +#: ../../ch-maintainerscripts.rst:261 ../../ch-maintainerscripts.rst:282 +#: ../../ch-maintainerscripts.rst:301 ../../ch-maintainerscripts.rst:342 +#: ../../ch-maintainerscripts.rst:358 msgid "Error unwind:" msgstr "" -#: ../../ch-maintainerscripts.rst:262 ../../ch-maintainerscripts.rst:284 +#: ../../ch-maintainerscripts.rst:268 ../../ch-maintainerscripts.rst:290 msgid "" "The deconfigured packages are marked as requiring configuration, so that " "if ``--install`` is used they will be configured again if possible." msgstr "" -#: ../../ch-maintainerscripts.rst:266 +#: ../../ch-maintainerscripts.rst:272 msgid "" "If any packages depended on a conflicting package being removed and " "``--auto-deconfigure`` is specified, call, for each such package:" msgstr "" -#: ../../ch-maintainerscripts.rst:288 +#: ../../ch-maintainerscripts.rst:294 msgid "To prepare for removal of each conflicting package, call:" msgstr "" -#: ../../ch-maintainerscripts.rst:302 +#: ../../ch-maintainerscripts.rst:308 msgid "Run the ``preinst`` of the new package:" msgstr "" -#: ../../ch-maintainerscripts.rst:304 -msgid "If the package is being upgraded, call:" -msgstr "" - #: ../../ch-maintainerscripts.rst:310 -msgid "If this fails, we call:" +msgid "If the package is being upgraded, call:" msgstr "" #: ../../ch-maintainerscripts.rst:316 -msgid "If that works, then" +msgid "If this fails, we call:" msgstr "" #: ../../ch-maintainerscripts.rst:322 +msgid "If that works, then" +msgstr "" + +#: ../../ch-maintainerscripts.rst:328 msgid "" "is called. If this works, then the old version is in an \"Installed\" " "state, or else it is left in an \"Unpacked\" state." msgstr "" -#: ../../ch-maintainerscripts.rst:325 +#: ../../ch-maintainerscripts.rst:331 msgid "If it fails, then the old version is left in an \"Half-Installed\" state." msgstr "" -#: ../../ch-maintainerscripts.rst:328 +#: ../../ch-maintainerscripts.rst:334 msgid "" "Otherwise, if the package had some configuration files from a previous " "version installed (i.e., it is in the \"Config-Files\" state):" msgstr "" -#: ../../ch-maintainerscripts.rst:342 +#: ../../ch-maintainerscripts.rst:348 msgid "" "If this fails, the package is left in a \"Half-Installed\" state, which " "requires a reinstall. If it works, the packages is left in a \"Config-" "Files\" state." msgstr "" -#: ../../ch-maintainerscripts.rst:346 +#: ../../ch-maintainerscripts.rst:352 msgid "Otherwise (i.e., the package was completely purged):" msgstr "" -#: ../../ch-maintainerscripts.rst:358 +#: ../../ch-maintainerscripts.rst:364 msgid "" "If the error-unwind fails, the package is in a \"Half-Installed\" phase, " "and requires a reinstall. If the error unwind works, the package is in " "the \"Not-Installed\" state." msgstr "" -#: ../../ch-maintainerscripts.rst:362 +#: ../../ch-maintainerscripts.rst:368 msgid "" "The new package's files are unpacked, overwriting any that may be on the " "system already, for example any from the old version of the same package " @@ -484,13 +493,13 @@ msgid "" "put them back as part of the error unwind." msgstr "" -#: ../../ch-maintainerscripts.rst:368 +#: ../../ch-maintainerscripts.rst:374 msgid "" "It is an error for a package to contain files which are on the system in " "another package, unless ``Replaces`` is used (see :ref:`s-replaces`)." msgstr "" -#: ../../ch-maintainerscripts.rst:372 +#: ../../ch-maintainerscripts.rst:378 msgid "" "It is a more serious error for a package to contain a plain file or other" " kind of non-directory where another package has a directory (again, " @@ -498,7 +507,7 @@ msgid "" "using ``--force-overwrite-dir``, but this is not advisable." msgstr "" -#: ../../ch-maintainerscripts.rst:378 +#: ../../ch-maintainerscripts.rst:384 msgid "" "Packages which overwrite each other's files produce behavior which, " "though deterministic, is hard for the system administrator to understand." @@ -507,40 +516,40 @@ msgid "" "removed again. [#]_" msgstr "" -#: ../../ch-maintainerscripts.rst:384 +#: ../../ch-maintainerscripts.rst:390 msgid "" "A directory will never be replaced by a symbolic link to a directory or " "vice versa; instead, the existing state (symlink or not) will be left " "alone and ``dpkg`` will follow the symlink if there is one." msgstr "" -#: ../../ch-maintainerscripts.rst:388 +#: ../../ch-maintainerscripts.rst:394 msgid "If the package is being upgraded:" msgstr "" -#: ../../ch-maintainerscripts.rst:390 -msgid "Call:" -msgstr "" - #: ../../ch-maintainerscripts.rst:396 -msgid "If this fails, ``dpkg`` will attempt:" +msgid "Call:" msgstr "" #: ../../ch-maintainerscripts.rst:402 +msgid "If this fails, ``dpkg`` will attempt:" +msgstr "" + +#: ../../ch-maintainerscripts.rst:408 msgid "If this works, installation continues. If not, Error unwind:" msgstr "" -#: ../../ch-maintainerscripts.rst:408 ../../ch-maintainerscripts.rst:415 +#: ../../ch-maintainerscripts.rst:414 ../../ch-maintainerscripts.rst:421 msgid "" "If this fails, the old version is left in a \"Half-Installed\" state. If " "it works, dpkg now calls:" msgstr "" -#: ../../ch-maintainerscripts.rst:422 +#: ../../ch-maintainerscripts.rst:428 msgid "If this fails, the old version is in an \"Unpacked\" state." msgstr "" -#: ../../ch-maintainerscripts.rst:424 +#: ../../ch-maintainerscripts.rst:430 msgid "" "This is the point of no return. If ``dpkg`` gets this far, it won't back " "off past this point if an error occurs. This will leave the package in a " @@ -549,36 +558,36 @@ msgid "" "irreversible." msgstr "" -#: ../../ch-maintainerscripts.rst:430 +#: ../../ch-maintainerscripts.rst:436 msgid "" "Any files which were in the old version of the package but not in the new" " are removed." msgstr "" -#: ../../ch-maintainerscripts.rst:433 +#: ../../ch-maintainerscripts.rst:439 msgid "The new file list replaces the old." msgstr "" -#: ../../ch-maintainerscripts.rst:435 +#: ../../ch-maintainerscripts.rst:441 msgid "The new maintainer scripts replace the old." msgstr "" -#: ../../ch-maintainerscripts.rst:437 +#: ../../ch-maintainerscripts.rst:443 msgid "" "Any packages all of whose files have been overwritten during the " "installation, and which aren't required for dependencies, are considered " "to have been removed. For each such package" msgstr "" -#: ../../ch-maintainerscripts.rst:441 +#: ../../ch-maintainerscripts.rst:447 msgid "``dpkg`` calls:" msgstr "" -#: ../../ch-maintainerscripts.rst:448 +#: ../../ch-maintainerscripts.rst:454 msgid "The package's maintainer scripts are removed." msgstr "" -#: ../../ch-maintainerscripts.rst:450 +#: ../../ch-maintainerscripts.rst:456 msgid "" "It is noted in the status database as being in a sane state, namely " "\"Not-Installed\" (any conffiles it may have are ignored, rather than " @@ -587,29 +596,29 @@ msgid "" "package is going to vanish." msgstr "" -#: ../../ch-maintainerscripts.rst:456 +#: ../../ch-maintainerscripts.rst:462 msgid "" "Any files in the package we're unpacking that are also listed in the file" " lists of other packages are removed from those lists. (This will " "lobotomize the file list of the \"conflicting\" package if there is one.)" msgstr "" -#: ../../ch-maintainerscripts.rst:461 +#: ../../ch-maintainerscripts.rst:467 msgid "The backup files made during installation, above, are deleted." msgstr "" -#: ../../ch-maintainerscripts.rst:463 +#: ../../ch-maintainerscripts.rst:469 msgid "The new package's status is now sane, and recorded as \"Unpacked\"." msgstr "" -#: ../../ch-maintainerscripts.rst:465 +#: ../../ch-maintainerscripts.rst:471 msgid "" "Here is another point of no return: if the conflicting package's removal " "fails we do not unwind the rest of the installation. The conflicting " "package is left in a half-removed limbo." msgstr "" -#: ../../ch-maintainerscripts.rst:469 +#: ../../ch-maintainerscripts.rst:475 msgid "" "If there was a conflicting package we go and do the removal actions " "(described below), starting with the removal of the conflicting package's" @@ -618,97 +627,97 @@ msgid "" "removed now)." msgstr "" -#: ../../ch-maintainerscripts.rst:478 +#: ../../ch-maintainerscripts.rst:484 msgid "Details of configuration" msgstr "" -#: ../../ch-maintainerscripts.rst:480 +#: ../../ch-maintainerscripts.rst:486 msgid "" "When we configure a package (this happens with ``dpkg --install`` and " "``dpkg --configure``), we first update any ``conffile``\\ s and then " "call:" msgstr "" -#: ../../ch-maintainerscripts.rst:487 +#: ../../ch-maintainerscripts.rst:493 msgid "" "No attempt is made to unwind after errors during configuration. If the " "configuration fails, the package is in a \"Half-Configured\" state, and " "an error message is generated." msgstr "" -#: ../../ch-maintainerscripts.rst:491 +#: ../../ch-maintainerscripts.rst:497 msgid "" "If there is no most recently configured version ``dpkg`` will pass a null" " argument. [#]_" msgstr "" -#: ../../ch-maintainerscripts.rst:497 -msgid "Details of removal and/or configuration purging" -msgstr "" - #: ../../ch-maintainerscripts.rst:503 +msgid "Details of removal and/or configuration purging" +msgstr "" + +#: ../../ch-maintainerscripts.rst:509 msgid "If prerm fails during replacement due to conflict" msgstr "" -#: ../../ch-maintainerscripts.rst:510 -msgid "Or else we call:" -msgstr "" - #: ../../ch-maintainerscripts.rst:516 +msgid "Or else we call:" +msgstr "" + +#: ../../ch-maintainerscripts.rst:522 msgid "" "If this fails, the package is in a \"Half-Configured\" state, or else it " "remains \"Installed\"." msgstr "" -#: ../../ch-maintainerscripts.rst:519 -msgid "The package's files are removed (except ``conffile``\\ s)." -msgstr "" - #: ../../ch-maintainerscripts.rst:525 +msgid "The package's files are removed (except ``conffile``\\ s)." +msgstr "" + +#: ../../ch-maintainerscripts.rst:531 msgid "" "If it fails, there's no error unwind, and the package is in an \"Half-" "Installed\" state." msgstr "" -#: ../../ch-maintainerscripts.rst:528 +#: ../../ch-maintainerscripts.rst:534 msgid "All the maintainer scripts except the ``postrm`` are removed." msgstr "" -#: ../../ch-maintainerscripts.rst:530 +#: ../../ch-maintainerscripts.rst:536 msgid "" "If we aren't purging the package we stop here. Note that packages which " "have no ``postrm`` and no ``conffile``\\ s are automatically purged when " "removed, as there is no difference except for the ``dpkg`` status." msgstr "" -#: ../../ch-maintainerscripts.rst:535 +#: ../../ch-maintainerscripts.rst:541 msgid "" "The ``conffile``\\ s and any backup files (``~``-files, ``#*#`` files, " "``%``-files, ``.dpkg-{old,new,tmp}``, etc.) are removed." msgstr "" -#: ../../ch-maintainerscripts.rst:542 +#: ../../ch-maintainerscripts.rst:548 msgid "If this fails, the package remains in a \"Config-Files\" state." msgstr "" -#: ../../ch-maintainerscripts.rst:544 +#: ../../ch-maintainerscripts.rst:550 msgid "The package's file list is removed." msgstr "" -#: ../../ch-maintainerscripts.rst:547 +#: ../../ch-maintainerscripts.rst:553 msgid "" "This is so that if an error occurs, the user interrupts ``dpkg`` or some " "other unforeseen circumstance happens you don't leave the user with a " "badly-broken package when ``dpkg`` attempts to repeat the action." msgstr "" -#: ../../ch-maintainerscripts.rst:553 +#: ../../ch-maintainerscripts.rst:559 msgid "" "This can happen if the new version of the package no longer pre-depends " "on a package that had been partially upgraded." msgstr "" -#: ../../ch-maintainerscripts.rst:557 +#: ../../ch-maintainerscripts.rst:563 msgid "" "For example, suppose packages foo and bar are \"Installed\" with foo " "depending on bar. If an upgrade of bar were started and then aborted, and" @@ -717,29 +726,29 @@ msgid "" "\"Half-Installed\"." msgstr "" -#: ../../ch-maintainerscripts.rst:564 +#: ../../ch-maintainerscripts.rst:570 msgid "" "This is often done by checking whether the command or facility the " "``postrm`` intends to call is available before calling it. For example:" msgstr "" -#: ../../ch-maintainerscripts.rst:574 +#: ../../ch-maintainerscripts.rst:580 msgid "" "in ``postrm`` purges the ``debconf`` configuration for the package if " "debconf is installed." msgstr "" -#: ../../ch-maintainerscripts.rst:578 +#: ../../ch-maintainerscripts.rst:584 msgid "" "See :doc:`ap-flowcharts` for flowcharts illustrating the processes " "described here." msgstr "" -#: ../../ch-maintainerscripts.rst:582 +#: ../../ch-maintainerscripts.rst:588 msgid "Part of the problem is due to what is arguably a bug in ``dpkg``." msgstr "" -#: ../../ch-maintainerscripts.rst:585 +#: ../../ch-maintainerscripts.rst:591 msgid "" "Historical note: Truly ancient (pre-1997) versions of ``dpkg`` passed " "``<unknown>`` (including the angle brackets) in this case. Even older " @@ -783,3 +792,29 @@ msgstr "" #~ msgid "``new-postrm`` abort-upgrade *old-version*" #~ msgstr "" +#~ msgid "" +#~ "Maintainer scripts should not be used" +#~ " to create or remove auxiliary files" +#~ " and/or directories that packages may " +#~ "need, such as those in ``/var/`` " +#~ "or ``/etc/``. Instead, `tmpfiles.d <>`_ " +#~ "snippets should be shipped, being " +#~ "ideally provided by the upstream " +#~ "sources, if any. For more details " +#~ "about the `tmpfiles.d interface, see " +#~ ":ref:`s-tmpfiles.d`." +#~ msgstr "" + +#~ msgid "" +#~ "Maintainer scripts should not be used" +#~ " to create or remove auxiliary files" +#~ " and/or directories that packages may " +#~ "need, such as those in ``/var/`` " +#~ "or ``/etc/``. Instead, :ref:`s-tmpfiles.d` " +#~ "snippets should be shipped, being " +#~ "ideally provided by the upstream " +#~ "sources, if any. For more details " +#~ "about the `tmpfiles.d interface, see " +#~ ":ref:`s-tmpfiles.d`." +#~ msgstr "" + diff --git a/policy/ch-files.rst b/policy/ch-files.rst index b34c183..a64d3e9 100644 --- a/policy/ch-files.rst +++ b/policy/ch-files.rst @@ -722,6 +722,45 @@ The name of the files and directories installed by binary packages outside the system PATH must be encoded in UTF-8 and should be restricted to ASCII when it is possible to do so. +.. _s-tmpfiles.d: + +tmpfiles.d +---------- + +Packages might need additional files or directories to implement their +functionality. Directories that are located under ``/var/`` or ``/etc/``, and +files that are located under ``/var/``, should not be created manually via +maintainer scripts, but instead be declaratively defined via the `tmpfiles.d +<https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html>`_ interface. +The ``tmpfiles.d`` file format is defined by the ``systemd`` project, and is +guaranteed to be stable. Ideally, such definitions should be defined upstream +where applicable, and shipped as they are by Debian packages. + +Details about the syntax and installation paths for ``tmpfiles.d`` are defined +by its `reference implementation's documentation, +<https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html>`_ and will +not be redefined here. + +``tmpfiles.d`` snippets should be usable on systems that do not boot (such as a +very minimal chroot image), and also systems booting with init systems other +than ``systemd``. + +``tmpfiles.d`` snippets should be detected at package build time by tools such +as ``debhelper``, packaged, and the appropriate snippet to call them on +installation, upgrade, removal, purge and other steps as required, should be +automatically added by helpers such as ``dh_installtmpfiles``, including the +required dependency on the appropriate ``tmpfiles.d`` implementation, while also +ensuring that such dependency can be satisfied on minimal systems that are not +bootable. The ``systemd-tmpfiles`` virtual package will ensure a binary package +providing tools that conform to the reference implementation will be installed. + +Init systems are required to integrate with ``tmpfiles.d`` and run the service +that applies them on boot, and regularly for cleanup purposes. The documentation +for the reference implementation, `systemd-tmpfiles, +<https://www.freedesktop.org/software/systemd/man/systemd-tmpfiles.html>`_ +explains how to call the program so that the appropriate ``tmpfiles.d`` snippets +are applied at the appropriate time. + .. [#] If you are using GCC, ``-fPIC`` produces code with relocatable position independent code, which is required for most architectures diff --git a/policy/ch-maintainerscripts.rst b/policy/ch-maintainerscripts.rst index 724074c..320949d 100644 --- a/policy/ch-maintainerscripts.rst +++ b/policy/ch-maintainerscripts.rst @@ -50,6 +50,12 @@ absolute pathname. Maintainer scripts should also not reset the appending package-specific directories. These considerations really apply to all shell scripts. +Maintainer scripts should not be used to create or remove auxiliary files and/or +directories that packages may need, such as those in ``/var/`` or ``/etc/``. +Instead, :ref:`s-tmpfiles.d` snippets should be shipped, being ideally provided by +the upstream sources, if any. For more details about the ``tmpfiles.d`` +interface, see :ref:`s-tmpfiles.d`. + .. _s-idempotency: Maintainer scripts idempotency
signature.asc
Description: This is a digitally signed message part
