Document cron job file naming restrictions

Cron job file names need to avoid . and + and should use _ for those
characters instead.  Also document a convention for packages that need
to include multiple cron job files.

Wording: Karl E. Jorgensen <karl@jorgensen.org.uk>
Wording: Russ Allbery <rra@debian.org>
Seconded: Russ Allbery <rra@debian.org>
Seconded: Dominic Hargreaves <dom@earth.li>
Seconded: Javier Fernández-Sanguino Peña <jfs@computer.org>
Closes: #609162

diff --git a/debian/changelog b/debian/changelog
index 55c61abc7657f0bc10b238d1aae3fe0621742c48..7161430590a5ab3689db486fc22e7bfe19882a86 100644 (file)
--- a/debian/changelog
+++ b/debian/changelog
@@ -13,6 +13,13 @@ debian-policy (3.9.3.0) UNRELEASED; urgency=low
     Seconded: Raphaël Hertzog <hertzog@debian.org>
     Seconded: Andrew McMillan <andrew@morphoss.com>
     Closes: #593533
+  * Policy: Document cron job file naming restrictions
+    Wording: Karl E. Jorgensen <karl@jorgensen.org.uk>
+    Wording: Russ Allbery <rra@debian.org>
+    Seconded: Russ Allbery <rra@debian.org>
+    Seconded: Dominic Hargreaves <dom@earth.li>
+    Seconded: Javier Fernández-Sanguino Peña <jfs@computer.org>
+    Closes: #609162
   * Consistently use "Debian source control file" for *.dsc files and
     "Source package control file" for debian/control files.  Patch from
     Charles Plessy.  (Closes: #626796)

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">

diff --git a/upgrading-checklist.sgml b/upgrading-checklist.sgml
index 41220a0424ca91663c61ab7a105901d08bb900c1..982f017032658f00034a5bdb33a9106bfabb7a8f 100644 (file)
--- a/upgrading-checklist.sgml
+++ b/upgrading-checklist.sgml
@@ -49,6 +49,13 @@ Unreleased.
   now contain the value <tt>any all</tt> for source packages building both
   architecture-independent and architecture-dependent packages.
   </item>
+<tag>9.5</tag>
+  <item>Cron job file names must not contain <tt>.</tt> or <tt>+</tt> or
+  they will be ignored by cron.  They should replace those characters
+  with <tt>_</tt>.  If a package provides multiple cron job files in the
+  same directory, they should each start with the package name (possibly
+  modified as above), <tt>-</tt>, and then some suitable prefix.
+  </item>
 <tag>9.10</tag>
   <item>Packages using doc-base do not need to call install-docs anymore.
   </item>