README

   1 DCRON - DILLON'S LIGHTWEIGHT CRON DAEMON
   2 ========================================
   3
   4 This lightweight cron daemon aims to be simple and secure, with just enough
   5 features to stay useful. It was written from scratch by Matt Dillon in 1994.
   6 It's now developed and maintained by Jim Pryor.
   7
   8 In the author's opinion, having to combine a cron daemon with another daemon
   9 like anacron makes for too much complexity. So the goal is a simple cron daemon
  10 that can also take over the central functions of anacron.
  11
  12 Unlike other fatter cron daemons, though, this cron doesn't even try to manage
  13 environment variables or act as a shell. All jobs are run with `/bin/sh` for
  14 conformity and portability. We don't try to use the user's preferred shell:
  15 that breaks down for special users and even makes some of us normal users
  16 unhappy (for example, /bin/csh does not use a true O_APPEND mode and has
  17 difficulty redirecting stdout and stderr both to different places!). You can,
  18 of course, run shell scripts in whatever language you like by making them
  19 executable with #!/bin/csh or whatever as the first line. If you don't like
  20 the extra processes, just `exec` them.
  21
  22 If you need to set special environment variables, pass them as arguments to a
  23 script.
  24
  25 The programs were written with an eye towards security, hopefully we haven't
  26 forgotton anything. The programs were also written with an eye towards nice,
  27 clean, algorithmically sound code. It's small, and the only fancy code is that
  28 which deals with child processes. We do not try to optimize with vfork() since
  29 it causes headaches and is rather pointless considering we're execing a shell
  30 most of the time, and we pay close attention to leaving descriptors open in the
  31 crond and close attention to preventing crond from running away.
  32
  33
  34 DOWNLOADING
  35 -----------
  36
  37 The project is hosted at: <http://www.jimpryor.net/linux/dcron.html>.
  38
  39 The latest version is 4.5, which can be downloaded here:
  40 <http://www.jimpryor.net/linux/releases/dcron-4.5.tar.gz>.
  41
  42 A public git repo is available at: <http://repo.or.cz/w/dcron.git>.
  43
  44
  45 COMPILING
  46 ---------
  47
  48 You must use a compiler that understands prototypes, such as GCC.
  49
  50 (1) The following compile-time defaults are configurable via
  51 command-line assignments on the `make` line (they're shown here with
  52 their default values):
  53
  54         PREFIX=/usr/local         # where files will ultimately be installed
  55         SBINDIR = $(PREFIX)/sbin  # where crond will be installed
  56         BINDIR = $(PREFIX)/bin    # where crontab will be installed
  57         MANDIR = $(PREFIX)/share/man  # where manpages will be installed
  58         CRONTABS = /var/spool/cron/crontabs     # default dir for per-user crontabs
  59         CRONSTAMPS = /var/spool/cron/cronstamps # default dir
  60         SCRONTABS = /etc/cron.d   # default dir for system crontabs
  61
  62         CRONTAB_GROUP = wheel     # who's allowed to edit their own crontabs?
  63         LOG_IDENT = crond         # syslog uses facility LOG_CRON and this identity
  64         TIMESTAMP_FMT = %b %e %H:%M:%S  # used if LC_TIME unset and logging to file
  65
  66 A few additional compile-time settings are defined in defs.h. If you find yourself
  67 wanting to edit defs.h directly, try editing the DEFS line in the Makefile instead.
  68
  69 (2) Run make with your desired settings. For example:
  70
  71         make PREFIX=/usr CRONTAB_GROUP=users
  72
  73 (3) If you're using the git version, you might also want to `make man`,
  74 to be sure the manpages are updated. This requires
  75 [pandoc](http://johnmacfarlane.net/pandoc/).
  76
  77
  78 INSTALLING
  79 ----------
  80
  81 (4) `make install` installs the files underneath PREFIX (by default, /usr/local).
  82 If you're packaging, you can supply a DESTDIR argument here:
  83
  84         make DESTDIR=/path/to/your/package/root install
  85
  86 Permissions will be as follows:
  87
  88         -rwx------  0 root   root    32232 Jan  6 18:58 /usr/local/sbin/crond
  89         -rwsr-x---  0 root   wheel   15288 Jan  6 18:58 /usr/local/bin/crontab
  90
  91 Only users belonging to crontab's group (here "wheel") will be able to use it.
  92 You may want to create a special "cron" group and assign crontab to it:
  93
  94         groupadd cron
  95         chgrp cron /usr/local/bin/crontab
  96         chmod 4750 /usr/local/bin/crontab
  97
  98 (If the group already exists, you can specify it by supplying CRONTAB_GROUP
  99 to the `make` or `make install` commands.)
 100
 101 Then add users to group "cron" when you want them to be able to install
 102 or edit their own crontabs. The superuser is able to install crontabs for users
 103 who don't have the privileges to edit their own.
 104
 105 You should schedule crond to run automatically from system startup, using
 106 /etc/rc.local or a similar mechanism. crond automatically detaches. By default
 107 it logs all events <= loglevel NOTICE to syslog.
 108
 109 The crontab files are normally located in /var/spool/cron/crontabs, and timestamps
 110 are normally in /var/spool/cron/cronstamps. These directories normally have permissions:
 111
 112         drwxr-xr-x  2 root   root     4096 Jan  6 18:50 /var/spool/cron
 113         drwxr-xr-x  1 root   root        0 Jan  6 18:58 /var/spool/cron/crontabs
 114         drwxr-xr-x  1 root   root        0 Jan  6 18:58 /var/spool/cron/cronstamps/
 115
 116 Here is the superuser's crontab, created using `sudo crontab -e`:
 117
 118         -rw-------  0 root   root      513 Jan  6 18:58 /var/spool/cron/crontabs/root
 119
 120 TESTING
 121 -------
 122
 123 Use the crontab program to create a personal crontab with the following
 124 two lines:
 125
 126         * * * * *  date >> /tmp/test
 127         * * * * *  date
 128
 129 Check the log output of crond to ensure the cron entries are being
 130 run once a minute, check /tmp/test to ensure the date is being
 131 appended to it once a minute, and check your mail to ensure that crond
 132 is mailing you the date from the other entry once a minute.
 133
 134 After you are through testing cron, delete the entries with `crontab -e`
 135 or `crontab -d`.
 136
 137 EXTRAS
 138 ------
 139
 140 The following are included in the "extra" folder. None of them are installed
 141 by `make install`:
 142
 143 crond.rc
 144 :       This is an example rc script to start and stop crond. It could be placed in
 145 /etc/rc.d or /etc/init.d in suitable systems.
 146
 147 crond.conf
 148 :       This contains user-modifiable settings for crond.rc. The sample crond.rc
 149 expects to source this file from /etc/conf.d/crond.
 150
 151 run-cron
 152 :       This simple shell script is a bare-bones alternative to Debian's run-parts.
 153
 154 crond.service
 155 :      This is an example sysvinit service to start and stop crond. It
 156 could be placed in /lib/systemd/system in suitable systems.
 157
 158 root.crontab
 159 :       This is an example crontab to install for the root user, or to install
 160 in /etc/cron.d. It runs any executable scripts located in the directories /etc/cron.hourly,
 161 /etc/cron.daily, /etc/cron.weekly, and /etc/cron.monthly at the appropriate times.
 162 This example uses the run-cron script mentioned above, and relies on you to
 163 create the /etc/cron.* directories.
 164
 165 prune-cronstamps
 166 :       crond never removes any files from your cronstamps directory. If usernames
 167 are abandoned, or cron job names are abandoned, unused files will accumulate
 168 there. This simple cronjob will prune any cronstamp files older than three months.
 169 It will run weekly if placed in /etc/cron.d.
 170
 171 crond.logrotate
 172 :       This is an example to place in /etc/logrotate.d. This config file assumes you
 173 run crond using -L /var/log/crond.log. If you run crond using syslog instead (the default),
 174 you may prefer to configure the rotation of all your syslog-generated logs in a
 175 single config file.
 176
 177 crontab.vim
 178 :       This makes vim handle backup files in way that doesn't interfere with crontab's security
 179 model.
 180
 181
 182 BUG REPORTS, SUBMISSIONS
 183 ------------------------
 184
 185 Send any bug reports and source code changes to Jim Pryor:
 186 <profjim@jimpryor.net>.
 187
 188 We aim to keep this program simple, secure, and bug-free, in preference to
 189 adding features. Those advanced features we have added recently (such as
 190 @noauto, FREQ= and AFTER= tags, advanced cron.update parsing) fit naturally
 191 into the existing codebase.
 192
 193 Our goal is also to make this program compilable in as near to a C89-strict a
 194 manner as possible. Less-portable features we're aware of are described in the
 195 comments to defs.h. We'll reduce these dependencies as feasible. Do let us know
 196 if any of them are an obstacle to using crond on your platform.
 197
 198 Changes to defs.h, whether to override defaults or to accommodate your platform,
 199 should be made by a combination of a -D option in the Makefile
 200 and an #ifdef for that option in defs.h. Don't rely on pre-definitions made
 201 by the C compiler.
 202
 203 Prototypes for system functions should come from external include
 204 files and NOT from defs.h or any source file. If no prototype exists for a
 205 particular function, contact your vendor to get an update for your includes.
 206
 207 Note that the source code, especially in regard to changing the
 208 effective user, is Linux specific (SysVish). We welcome any changes
 209 in regard to making the mechanism work with other platforms.
 210
 211
 212 CREDITS
 213 -------
 214
 215 We use `concat`, a lightweight replacement for `asprintf`, in order to be more
 216 portable. This was written by Solar Designer and is in the public domain. See
 217 <http://www.openwall.com/popa3d/>.
 218