From: Russ Allbery Date: Mon, 26 Dec 2011 17:39:17 +0000 (-0800) Subject: Document cron job file naming restrictions X-Git-Url: https://git.donarmstrong.com/?p=debian%2Fdebian-policy.git;a=commitdiff_plain;h=2336a1cf44bf5c0cf4b1c2d1847098a79a548a74 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 Wording: Russ Allbery Seconded: Russ Allbery Seconded: Dominic Hargreaves Seconded: Javier Fernández-Sanguino Peña Closes: #609162 --- diff --git a/debian/changelog b/debian/changelog index 55c61ab..7161430 100644 --- a/debian/changelog +++ b/debian/changelog @@ -13,6 +13,13 @@ debian-policy (3.9.3.0) UNRELEASED; urgency=low Seconded: Raphaël Hertzog Seconded: Andrew McMillan Closes: #593533 + * Policy: Document cron job file naming restrictions + Wording: Karl E. Jorgensen + Wording: Russ Allbery + Seconded: Russ Allbery + Seconded: Dominic Hargreaves + Seconded: Javier Fernández-Sanguino Peña + 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 854fde6..55a33ba 100644 --- a/policy.sgml +++ b/policy.sgml @@ -7140,18 +7140,20 @@ Reloading description configuration...done.

- + Cron jobs

Packages must not modify the configuration file /etc/crontab, and they must not modify the files in - /var/spool/cron/crontabs.

+ /var/spool/cron/crontabs. +

- 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 into one or more of the following + directories: /etc/cron.hourly /etc/cron.daily @@ -7161,7 +7163,8 @@ Reloading description 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 - /etc/crontab.

+ /etc/crontab. +

All files installed in any of these directories must be @@ -7172,15 +7175,18 @@ Reloading description configuration...done.

If a certain job has to be executed at some other frequency or - at a specific time, the package should install a file - /etc/cron.d/package. This file uses the - same syntax as /etc/crontab and is processed by - cron automatically. The file must also be + at a specific time, the package should install a file in + /etc/cron.d with a name as specified + in . This file uses the same syntax + as /etc/crontab and is processed + by cron automatically. The file must also be treated as a configuration file. (Note that entries in the /etc/cron.d directory are not handled by anacron. Thus, you should only use this directory for jobs which may be skipped if the system is not - running.)

+ running.) +

+

Unlike crontab files described in the IEEE Std 1003.1-2008 (POSIX.1) available from @@ -7223,6 +7229,28 @@ Reloading description configuration...done. execute scripts in /etc/cron.{hourly,daily,weekly,monthly}.

+ + +

+ The file name of a cron job file should normally match the + name of the package from which it comes. +

+ +

+ 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 (-) and a suitable suffix. +

+ +

+ A cron job file name must not include any period or plus + characters (. or +) characters as this will + cause cron to ignore the file. Underscores (_) + should be used instead of . and + + characters. +

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