Document cron job file naming restrictions

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

diff --git a/policy.sgml b/policy.sgml
index 854fde66d2e4e1d29bddb7f9dbb2201988ccdcc6..55a33babc918a6b717950f6ae4a10f3026c7ebfe 100644 (file)
--- a/policy.sgml
+++ b/policy.sgml
@@ -7140,18 +7140,20 @@ Reloading <var>description</var> configuration...done.
        </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
-         <file>/var/spool/cron/crontabs</file>.</p>
+         <file>/var/spool/cron/crontabs</file>.
+       </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
@@ -7161,7 +7163,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
-         <file>/etc/crontab</file>.</p>
+         <file>/etc/crontab</file>.
+       </p>
 
        <p>
          All files installed in any of these directories must be
@@ -7172,15 +7175,18 @@ Reloading <var>description</var> configuration...done.
 
        <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
-         running.)</p>
+         running.)
+       </p>
+
        <p>
           Unlike <file>crontab</file> files described in the IEEE Std
           1003.1-2008 (POSIX.1) available from
@@ -7223,6 +7229,28 @@ Reloading <var>description</var> configuration...done.
           execute scripts in
           <file>/etc/cron.{hourly,daily,weekly,monthly}</file>.
         </p>
+
+       <sect1 id="cron-files">
+         <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">