Document cron job file naming restrictions

[debian/debian-policy.git] / policy.sgml

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