From 33aa4cedff0f8d0a09f80460568c296da8d16d26 Mon Sep 17 00:00:00 2001 From: David Oberhollenzer Date: Mon, 17 Sep 2018 13:39:30 +0200 Subject: [PATCH] Update documentation Signed-off-by: David Oberhollenzer --- README.md | 6 +++-- cmd/service/service.8 | 6 ++--- docs/cmdline.md | 4 +++ docs/defconfig.md | 8 ++++-- docs/gcron.md | 62 +++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 79 insertions(+), 7 deletions(-) create mode 100644 docs/gcron.md diff --git a/README.md b/README.md index c36ea8b..06ba004 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,8 @@ This directory contains the source code for a tiny service supervision framework devised for the Pygos system, consisting of an init daemon, -a small syslog daemon and various command line utilities. +a small syslog daemon, a _definitely_ non standards compliant cron +implementation and various command line utilities. The individual parts of the framework are designed to be independent of each other (for instance, the tiny syslogd is intended to work with *any* @@ -62,6 +63,8 @@ services and configuration provided with this package. See [docs/usyslogd.md](docs/usyslogd.md) for details on the tiny syslog implementation. +See [docs/gcron.md](docs/gcron.md) for details on the cron implementation. + ## Why @@ -110,4 +113,3 @@ that have been considered include: Nice and simple. Probably the best fit if the rest of your user space is busybox as well. - diff --git a/cmd/service/service.8 b/cmd/service/service.8 index a897817..3ca7cb2 100644 --- a/cmd/service/service.8 +++ b/cmd/service/service.8 @@ -22,7 +22,7 @@ Displays a list of currently enabled services. If an optional target is specified, lists services only for this target, otherwise, list services for all targets. .TP -.BR enable " " \fI\fP " " \fI[arguments]\fP +.BR enable " " \fI\fP " " \fI[arguments]\fP Enable (but do not start) a system service by creating a symlink in the configuration directory, pointing to the service template file. @@ -34,7 +34,7 @@ in the gcrond configuration directory, pointing to the service file. The extension \fB.gcron\fP is automatically appended to the service name. .TP -.BR disable " " \fI\fP " " \fI[arguments]\fP +.BR disable " " \fI\fP " " \fI[arguments]\fP Disable (but do not stop) a system service by removing the corresponding symlink in the configuration directory. @@ -45,7 +45,7 @@ the desired service instance. If built with support for gcrond, disable a gcron service by removing the corresponding symlink in the gcron configuration directory. .TP -.BR dumpscript " " \fI\fP " " \fI[arguments]\fP +.BR dumpscript " " \fI\fP " " \fI[arguments]\fP Parse a service file from and produce a pseudo shell script containing the exact commands executed when starting the service. .SH AVAILABILITY diff --git a/docs/cmdline.md b/docs/cmdline.md index c3945ec..e1500aa 100644 --- a/docs/cmdline.md +++ b/docs/cmdline.md @@ -13,6 +13,10 @@ Currently available service commands are: * disable - disable a service. If the service is parameterized, requires the same arguments used for enabling, to disable the specific instance of the service. + * schedule - enable a gcrond service. Only available if this package is built + with gcrond. + * unschedule - disnable a gcrond service. Only available if this package is + built with gcrond. * dumpscript - generate an equivalent shell script from the `exec` lines of a service after applying all parameter substitutions. * list - list all enabled service. A target can be specified to only list diff --git a/docs/defconfig.md b/docs/defconfig.md index cdfe333..3ab6563 100644 --- a/docs/defconfig.md +++ b/docs/defconfig.md @@ -71,6 +71,12 @@ the `sysinit` target and *before* the `network` target: * ifcfg - static network configuration Does the static network configuration outlined in [network.md](network.md) +The following services are enabled by default and configured to run *after* +the `network` target: + + * gcrond - if the `gcrond` daemon is compiled with this package, this service + is enabled by default. + ## Default Shutdown and Reboot Services @@ -98,8 +104,6 @@ For the shutdown and reboot targets, the following services are executed: type service can be enabled to manage an instace of the `hostapd` program. * unbound - A respawn type service that manages an instance of the `unbound` name resolver. - * usyslogd - A respawn type service that manages an instance of the `usyslogd` - syslogd implementation that is part of this package. * hwclock - If the system has a hardware clock, this service can restore the kernels clock from the hardware at bootup, between the `vfs` and `sysinit` targets. diff --git a/docs/gcron.md b/docs/gcron.md new file mode 100644 index 0000000..4327083 --- /dev/null +++ b/docs/gcron.md @@ -0,0 +1,62 @@ +# Gcron + +Gcron is a small daemon that executes batch commands once a certain +condition is met. + +In a typical installation, it reads configuration files from `/etc/gcron.d`. +If used together with the init system in this package, the `service` command +can be used to administer symlinks in that directory, pointing +to `/usr/share/init/.gcron`. + +Each file in the configuration directory represents a single scheduled batch +job. The syntax and most of the keywords are similar to `initd` service files +(See [services.md](services.md)). + +## Cron Style Patterns + +The following keywords can be used to specify classic cron style patterns for +when a job should be run: + + * `hour` + * `minute` + * `dayofmonth` + * `dayofweek` + * `month` + +For each of those keywords, a comma separated sequence of times can be +specified. Time ranges can be specified using the syntax `-`, +or using `*` for every possible value. A sequence (either range or star) +can be suffixed with `/` to specify an increment. +For instance, `minute */5` means every five minutes and `minute 15-30/2` +means every two minutes between quarter past and half past. + +In addition to numeric values, the keywords `dayofweek` and `month` allow +specifying 3 letter, uppercase week day and moth names such as `MON`, `TUE`, +etc and `JAN`, `FEB`, ... + +The job is only run when all specified conditions are met. Omitting a field +is the same as specifying `*`. + +## Named Intervals + +Alternatively to the above, the keyword `interval` can be used. The following +intervals can be specified: + + * `yearly` or `annually` means on every January the first at midnight. + * `monthly` means on every first of the month at midnight. + * `weekly` means every Sunday at midnight. + * `daily` means every day at midnight. + * `hourly` means every first minute of the hour. + +## Command Specification + +To specify *what* should be done once the condition is met, the following +keywords can be used: + + * `exec` - the command to run. Multiple commands can be grouped + using curly braces. + * `user` - a user name or ID to set before running the commands. + * `group` - a group name or ID to set before running the commands. + * `tty` - similar to init service files, the controlling tty or output file + for the batch commands. Like init service files, the `truncate` keyword + can be used.