From d2b3a983e16f15d636619ebd61a3fa08c889b080 Mon Sep 17 00:00:00 2001 From: David Oberhollenzer Date: Sun, 18 Nov 2018 21:24:39 +0100 Subject: Initial commit Signed-off-by: David Oberhollenzer --- README.md | 122 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md new file mode 100644 index 0000000..94f1b7c --- /dev/null +++ b/README.md @@ -0,0 +1,122 @@ +# About + +This package contains a small cron implementation called `gcrond`. + +It was written due to a perceived lack of a proper, simple cron +implementation. All other cron implementation I came across were either decade +old, abandoned pieces of horror ("Cool, I didn't even know that C syntax +allows this!") or hopelessly integrated into other, much larger projects (e.g. +absorbed by SystemD or in the case of OpenBSD cron, married to special OpenBSD +syscalls). + +It was a fun little exercise and it seems to work so far. No idea about +standards compliance tough, the implementation was mostly written against +the Wikipedia article about Cron. + +## License + +The source code in this package is provided under the OpenBSD flavored ISC +license. So you can practically do as you wish, as long as you retain the +original copyright notice. The software is provided "as is" (as usual) with +no warranty whatsoever (e.g. it might actually do what it was designed for, +but it could just as well set your carpet on fire). + +The sub directory `m4` contains third party macro files used by the build +system which may be subject to their own, respective licenses. + + +## Portability + +The program in this package has been written for and tested on a GNU/Linux +system, so there may be some GNU-isms in there in addition to Linux specific +code. Depending on your target platform, some minor porting effort may be +required. + + +# Building and installing + +This package uses autotools. If you downloaded a distribution tar ball, simply +run the `configure` script and then `make` after the Makefile has been +generated. A list of possible `configure` options can be viewed by running +`configure --help`. + +If you really wish to do so, run `make install` to install the program on your +system. + +When working with the git tree, run the `autogen.sh` script to generate the +configure script and friends. + + +# Crontab File Format + +The cron daemon reads its configuration from all files it can find +in `/etc/crontab.d/` (exact path can be configured). + +The files are read line by line. Empty lines or lines starting with '#' are +skipped. + +Each non-empty line consists of the typical cron fields: + +1. The `minute` field. Legal values are from 0 to 59. +2. The `hour` field. Legal values are from 0 to 23. +3. The `day of month` field. Legal values are from 1 to 31 (or fewer, depending + on the month. +4. The `month` field. Legal values are from 1 to 12 (January to December) + or the mnemonics `JAN`, `FEB`, `MAR`, `APR`, ... +5. The `day of week` field. Legal values are from 0 to 6 (Sunday to Saturday) + or the mnemonics `SUN`, `MON`, `TUE`, `WED`, ... +6. The command to execute. + + +The fields are separated by spaces. For the time matching fields, multiple +comma separated values can be specified (e.g. `MON,WED,FRI` for a job that +should run on Mondays, Wednesdays and Fridays). + +The wild-card character `*` matches any legal value. An stepping can be +specified by appending `/` and then a stepping (e.g. for the minute field, +`*/5` would let a job run every five minutes). + +A range of values can also be specified as `-`, for instance +`MON-FRI` would match every day from Monday to Friday (equivalent to `1-5`). + +Intervals and specific values can be combined, for instance a day of month +field `*/7,13,25` would trigger once a week, starting from the first of the +month (1,7,14,21,28), but additionally include the 13th and the 25th. The +same could be expressed as `1-31/7,13,25`. + + +Instead of specifying a terse cron matching expression, the first five fields +can be replaced with one of the following mnemonics: + +- `@yearly` or `@anually` is equivalent to `0 0 1 1 *`, i.e. 1st of January + at midnight +- `@monthly` is equivalent to `0 0 1 * *`, i.e. 1st of every month at midnight +- `@weekly` is equivalent to `0 0 * * 0`, i.e. every Sunday at midnight +- `@daily` is equivalent to `0 0 * * *`, i.e. every day at midnight +- `@hourly` is equivalent to `0 * * * *`, i.e. every first minute of the hour + +Lastly, the command field is not broken down but passed to `/bin/sh -c` +*as is*. + + +# Security Considerations + +The cron daemon currently has no means of specifying a user to run the jobs as, +so if cron runs as root, the jobs it starts do as well. Since by default it +reads its configuration from `/etc` which by default is only writable by root, +this shouldn't be too much of a problem when using cron for typical system +administration tasks. + +If a job should run as another user, tools such as `su`, `runuser`, `setpriv` +et cetera need to be used. + +# Possible Future Directions + +The following things would be nice to have: + +- decent logging for cron and the output of the jobs. +- cron jobs per user, e.g. scan `~/.crontab.d` or similar and run the collected + jobs as the respective user. +- timezone handling +- some usable strategy for handling time jumps, e.g. caused by a job that + syncs time with an NTP server on a system without RTC. -- cgit v1.2.3