Bug#609162: debian-policy: package names with dots/periods ('.') and crontab files: packagers beware

[Russ Allbery <rra@debian.org>]

Javier Fernández-Sanguino Peña <jfs@computer.org> writes:
> On Tue, Sep 13, 2011 at 05:02:27PM -0500, Jonathan Nieder wrote:

>> (bcc: cron maintainers, request-tracker3.8 maintainers, debianutils
>>  maintainers, jtmd)
>> Hi,
>> 
>> Karl E. Jorgensen noticed that the current advice for naming files in
>> cron.d breaks for packages with a dot in their name and proposed a
>> small policy change to fix that.  Seconds?  Objections?

> Yes, that issue has been recently documented more in detail in cron's
> manpage (in version 3.0pl1-119). In any case, this issue is still open
> as bug 618317 and bug 631884. We (the cron maintainers) are yet
> undecided on whether we are going to keep it as it is or if we are going
> to change the default behaviour in future releases.

Hi everyone,

Thank you for the review of the cron job file naming, and sorry about the
long delay in processing the results.  I've just now committed this change
to the Policy repository for the next release.  I reworked the wording a
little bit; the final version is attached.

> Ok with this change. But please notice that there are some restrictions
> to the file permissions of the files under /etc/cron.d (from cron's
> manpage:  "must be owned by root, and must not be group- or
> other-writable.").

> Maybe those restrictions should be included there too?

We should be okay to leave this out since it just duplicates the existing
general requirement in Policy concerning all file permissions in 10.9:

    Files should be owned by root:root, and made writable only by the
    owner and universally readable (and executable, if appropriate), that
    is mode 644 or 755.

> Agree with this change, as it is the current situation. But please note
> that we might change this in the future and lift this requirement for
> future Debian releases.

If you do end up doing this, could you try to remember to let us know so
that Policy can also be changed?

> In addition, strictly speacking, the filename restriction does not
> necessarily apply to the files under /etc/cron.d (there is a '-l' switch
> in our Vixie cron implementation for those sysadmins that want LSB-style
> filenames there).  But, for the sake of brevity, we might want to put
> the general case.

Yeah, I think it's better to document the default case since that's what
packages have to assume and rely on.  If the local sysadmin wants to
change the behavior for their own cron jobs, that's great, but packages
can't assume that's been done.

Here is the patch as applied.

-- 
Russ Allbery (rra@debian.org)               <http://www.eyrie.org/~eagle/>

>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