Allow /run and /run/lock, document purpose of /run

[debian/debian-policy.git] / policy.sgml

diff --git a/policy.sgml b/policy.sgml
index 16ffc0f98a2e9e20dd86ea6b6e0d89bc2c650fc3..f512315708535d5dc0691533da2f1ef7a48b8280 100644 (file)
--- a/policy.sgml
+++ b/policy.sgml
@@ -258,7 +258,6 @@
            <item><ref id="fhs"></item>
            <item><ref id="virtual_pkg"></item>
            <item><ref id="menus"></item>
            <item><ref id="fhs"></item>
            <item><ref id="virtual_pkg"></item>
            <item><ref id="menus"></item>

-           <item><ref id="mime"></item>

            <item><ref id="perl"></item>
            <item><ref id="maintscriptprompt"></item>
            <item><ref id="emacs"></item>
            <item><ref id="perl"></item>
            <item><ref id="maintscriptprompt"></item>
            <item><ref id="emacs"></item>


@@ -6250,11 +6249,30 @@ install -m644 debian/shlibs.<var>package</var> debian/<var>package</var>/DEBIAN/
               <item>
                 <p>
                   The following directories in the root filesystem are
               <item>
                 <p>
                   The following directories in the root filesystem are

-                  additionally allowed: <file>/sys</file> and
-                  <file>/selinux</file>. <footnote>These directories
-                  are used as mount points to mount virtual filesystems
-                  to get access to kernel information.</footnote>
-                </p>
+                  additionally allowed: <file>/run</file>,
+                  <footnote>
+                    The purpose of the /run hierarchy is storage of ephemeral
+                    system state, that is, state information that should
+                    not be preserved across a reboot.
+                    Files and directories residing in <file>/run</file>
+                    should be stored on a temporary filesystem.
+                    The <file>/run</file> directory is a
+                    replacement for <file>/var/run</file>; its
+                    subdirectory <file>/run/lock</file> is a replacement for
+                    <file>/var/lock</file>.
+                    /run/ and /run/lock/ have been introduced
+                    by most distributions and are on track to be 
+                    endorsed by the FHS.
+                    Additionally, the subdirectory <file>/run/shm</file>
+                    is a replacement for <file>/dev/shm</file>.
+                  </footnote>
+                  <file>/sys</file> and <file>/selinux</file>.
+                  <footnote>
+                    The <file>/sys</file> and <file>/selinux</file>
+                    directories are mount points where
+                    virtual filesystems are mounted which provide access
+                    to kernel information.
+                  </footnote>

               </item>
              <item>
                <p>
               </item>
              <item>
                <p>


@@ -6763,15 +6781,17 @@ test -f <var>program-executed-later-in-script</var> || exit 0
          </p>
 
          <p>
          </p>
 
          <p>

-           <file>/var/run</file> and <file>/var/lock</file> may be mounted
-           as temporary filesystems<footnote>
-               For example, using the <tt>RAMRUN</tt> and <tt>RAMLOCK</tt>
-               options in <file>/etc/default/rcS</file>.
-           </footnote>, so the <file>init.d</file> scripts must handle this
-           correctly. This will typically amount to creating any required
-           subdirectories dynamically when the <file>init.d</file> script
-           is run, rather than including them in the package and relying on
-           <prgn>dpkg</prgn> to create them.
+            Files and directories under <file>/run</file>, including those
+            in directories <file>/var/run</file> and <file>/var/lock</file>
+            which are symlinks or bind mounts to subdirectories of
+            <file>/run</file>, are normally stored on a temporary
+            filesystem and are normally not persistent across a reboot.
+            Consequently, packages cannot assume that these files or
+            directories are present at system boot time.
+            Files and directories under <file>/run</file> must not be
+            included in packages; such files or directories
+            must be created dynamically, for example, in the
+            <file>init.d</file> script.

          </p>
        </sect1>
 
          </p>
        </sect1>
 


@@ -7140,18 +7160,20 @@ Reloading <var>description</var> configuration...done.
        </p>
       </sect>
 
        </p>
       </sect>
 

-      <sect>
+      <sect id="cron-jobs">

        <heading>Cron jobs</heading>
 
        <p>
          Packages must not modify the configuration file
          <file>/etc/crontab</file>, and they must not modify the files in
        <heading>Cron jobs</heading>
 
        <p>
          Packages must not modify the configuration file
          <file>/etc/crontab</file>, and they must not modify the files in

-         <file>/var/spool/cron/crontabs</file>.</p>
+         <file>/var/spool/cron/crontabs</file>.
+       </p>

 
        <p>
 
        <p>

-         If a package wants to install a job that has to be executed
-         via cron, it should place a file with the name of the
-         package in one or more of the following directories:
+         If a package wants to install a job that has to be executed via
+         cron, it should place a file named as specified
+         in <ref id="cron-files"> into one or more of the following
+         directories:

          <example compact="compact">
 /etc/cron.hourly
 /etc/cron.daily
          <example compact="compact">
 /etc/cron.hourly
 /etc/cron.daily


@@ -7161,7 +7183,8 @@ Reloading <var>description</var> configuration...done.
          As these directory names imply, the files within them are
          executed on an hourly, daily, weekly, or monthly basis,
          respectively. The exact times are listed in
          As these directory names imply, the files within them are
          executed on an hourly, daily, weekly, or monthly basis,
          respectively. The exact times are listed in

-         <file>/etc/crontab</file>.</p>
+         <file>/etc/crontab</file>.
+       </p>

 
        <p>
          All files installed in any of these directories must be
 
        <p>
          All files installed in any of these directories must be


@@ -7172,15 +7195,18 @@ Reloading <var>description</var> configuration...done.
 
        <p>
          If a certain job has to be executed at some other frequency or
 
        <p>
          If a certain job has to be executed at some other frequency or

-         at a specific time, the package should install a file
-         <file>/etc/cron.d/<var>package</var></file>. This file uses the
-         same syntax as <file>/etc/crontab</file> and is processed by
-         <prgn>cron</prgn> automatically. The file must also be
+         at a specific time, the package should install a file in
+         <file>/etc/cron.d</file> with a name as specified
+         in <ref id="cron-files">.  This file uses the same syntax
+         as <file>/etc/crontab</file> and is processed
+         by <prgn>cron</prgn> automatically. The file must also be

          treated as a configuration file. (Note that entries in the
          <file>/etc/cron.d</file> directory are not handled by
          <prgn>anacron</prgn>. Thus, you should only use this
          directory for jobs which may be skipped if the system is not
          treated as a configuration file. (Note that entries in the
          <file>/etc/cron.d</file> directory are not handled by
          <prgn>anacron</prgn>. Thus, you should only use this
          directory for jobs which may be skipped if the system is not

-         running.)</p>
+         running.)
+       </p>
+

        <p>
           Unlike <file>crontab</file> files described in the IEEE Std
           1003.1-2008 (POSIX.1) available from
        <p>
           Unlike <file>crontab</file> files described in the IEEE Std
           1003.1-2008 (POSIX.1) available from


@@ -7223,6 +7249,30 @@ Reloading <var>description</var> configuration...done.
           execute scripts in
           <file>/etc/cron.{hourly,daily,weekly,monthly}</file>.
         </p>
           execute scripts in
           <file>/etc/cron.{hourly,daily,weekly,monthly}</file>.
         </p>

+
+       <sect1 id="cron-files">
+         <heading>Cron job file names</heading>
+
+         <p>
+           The file name of a cron job file should normally match the
+           name of the package from which it comes.
+         </p>
+
+         <p>
+           If a package supplies multiple cron job files files in the
+           same directory, the file names should all start with the name
+           of the package (possibly modified as described below) followed
+           by a hyphen (<tt>-</tt>) and a suitable suffix.
+         </p>
+
+         <p>
+           A cron job file name must not include any period or plus
+           characters (<tt>.</tt> or <tt>+</tt>) characters as this will
+           cause cron to ignore the file.  Underscores (<tt>_</tt>)
+           should be used instead of <tt>.</tt> and <tt>+</tt>
+           characters.
+         </p>
+       </sect1>

       </sect>
 
       <sect id="menus">
       </sect>
 
       <sect id="menus">


@@ -7271,7 +7321,7 @@ Reloading <var>description</var> configuration...done.
          MIME (Multipurpose Internet Mail Extensions, RFCs 2045-2049)
          is a mechanism for encoding files and data streams and
          providing meta-information about them, in particular their
          MIME (Multipurpose Internet Mail Extensions, RFCs 2045-2049)
          is a mechanism for encoding files and data streams and
          providing meta-information about them, in particular their

-         type (e.g.  audio or video) and format (e.g. PNG, HTML,
+         type (e.g. audio or video) and format (e.g. PNG, HTML,

          MP3).
        </p>
 
          MP3).
        </p>
 


@@ -7288,11 +7338,25 @@ Reloading <var>description</var> configuration...done.
        </p>
 
        <p>
        </p>
 
        <p>

-         The MIME support policy can be found in the <tt>mime-policy</tt>
-         files in the <tt>debian-policy</tt> package.
-         It is also available from the Debian web mirrors at
-          <tt><url name="/doc/packaging-manuals/mime-policy/"
-               id="http://www.debian.org/doc/packaging-manuals/mime-policy/"></tt>.
+         The <package>mime-support</package> package provides the
+         <prgn>update-mime</prgn> program which allows packages to
+         register programs that can show, compose, edit or print
+         MIME types.
+       </p>
+
+       <p>
+         Packages containing such programs must register them
+         with <prgn>update-mime</prgn> as documented in <manref
+         name="update-mime" section="8">. They should <em>not</em> depend
+         on, recommend, or suggest <prgn>mime-support</prgn>. Instead,
+         they should just put something like the following in the
+         <tt>postinst</tt> and <tt>postrm</tt> scripts:
+
+         <example>
+  if [ -x /usr/sbin/update-mime ]; then
+      update-mime
+  fi
+         </example>

        </p>
 
       </sect>
        </p>
 
       </sect>


@@ -8187,22 +8251,6 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
        <sect1>
          <heading>Sharing configuration files</heading>
 
        <sect1>
          <heading>Sharing configuration files</heading>
 

-         <p>
-           Packages which specify the same file as a
-           <tt>conffile</tt> must be tagged as <em>conflicting</em>
-           with each other.  (This is an instance of the general rule
-           about not sharing files.  Note that neither alternatives
-           nor diversions are likely to be appropriate in this case;
-           in particular, <prgn>dpkg</prgn> does not handle diverted
-           <tt>conffile</tt>s well.)
-         </p>
-
-         <p>
-           The maintainer scripts must not alter a <tt>conffile</tt>
-           of <em>any</em> package, including the one the scripts
-           belong to.
-         </p>
-

          <p>
            If two or more packages use the same configuration file
            and it is reasonable for both to be installed at the same
          <p>
            If two or more packages use the same configuration file
            and it is reasonable for both to be installed at the same


@@ -8252,6 +8300,34 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
            and which manages the shared configuration files.  (The
            <tt>sgml-base</tt> package is a good example.)
          </p>
            and which manages the shared configuration files.  (The
            <tt>sgml-base</tt> package is a good example.)
          </p>

+
+         <p>
+           If the configuration file cannot be shared as described above,
+           the packages must be marked as conflicting with each other.
+           Two packages that specify the same file as
+           a <tt>conffile</tt> must conflict.  This is an instance of the
+           general rule about not sharing files.  Neither alternatives
+           nor diversions are likely to be appropriate in this case; in
+           particular, <prgn>dpkg</prgn> does not handle diverted
+           <tt>conffile</tt>s well.
+         </p>
+
+         <p>
+           When two packages both declare the same <tt>conffile</tt>, they
+           may see left-over configuration files from each other even
+           though they conflict with each other.  If a user removes
+           (without purging) one of the packages and installs the other,
+           the new package will take over the <tt>conffile</tt> from the
+           old package.  If the file was modified by the user, it will be
+           treated the same as any other locally
+           modified <tt>conffile</tt> during an upgrade.
+         </p>
+
+         <p>
+           The maintainer scripts must not alter a <tt>conffile</tt>
+           of <em>any</em> package, including the one the scripts
+           belong to.
+         </p>

        </sect1>
 
        <sect1>
        </sect1>
 
        <sect1>


@@ -9757,9 +9833,8 @@ END-INFO-DIR-ENTRY
 
        <p>
          In addition, the copyright file must say where the upstream
 
        <p>
          In addition, the copyright file must say where the upstream

-         sources (if any) were obtained.  It should name the original
-         authors of the package and the Debian maintainer(s) who were
-         involved with its creation.
+         sources (if any) were obtained, and should name the original
+         authors.

        </p>
 
        <p>
        </p>
 
        <p>