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
     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)
   * 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>
 
        </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 +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
          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 +7175,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 +7229,28 @@ 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">
+         <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">

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>
   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>
 <tag>9.10</tag>
   <item>Packages using doc-base do not need to call install-docs anymore.
   </item>