From a694cff01eb1dfd7073ddf7a58051cbd4e3553fc Mon Sep 17 00:00:00 2001
From: Russ Allbery <rra@debian.org>
Date: Mon, 26 Dec 2011 09:39:17 -0800
Subject: [PATCH] Document cron job file naming restrictions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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
---
 policy.sgml |   50 +++++++++++++++++++++++++++++++++++++++-----------
 1 files changed, 39 insertions(+), 11 deletions(-)

diff --git a/policy.sgml b/policy.sgml
index 854fde6..55a33ba 100644
--- 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">
-- 
1.7.7.3

