GNU micron README
See the end of file for copying conditions.

* Overview

This file contains brief information about configuring, setting up
and running micrond and associated programs.  It is *not* intended as
a replacement for the documentation, and is provided as a brief
reference only.

The complete documentation is shipped in the doc/ subdirectory, in
texifo format, as well as in a form of traditional UNIX manpages.  To
read the docs without installing micron, run `info -f
doc/micron.info'.  After the package is installed, it should suffice
to run `info micron'.

The documentation in various formats is available online at:

  https://www.gnu.org.ua/software/micron
 
* Introduction

GNU micron is an implementation of the UNIX cron daemon, a program that
executes periodically various tasks.  It aims to provide several
enhancements while being mostly backward-compatible with the two most
widely used cron implementations: Vixie and Dillon crons.

The implementation consists of two binaries: the main daemon micrond
and the crontab utility.

* Crontabs

Instructions specifying what commands to run and when are kept in
a set of crontab files.  Micrond reads its crontabs at startup and
loads them to memory.  When running, it keeps track of crontab
modifications and updates its in-memory tables as soon as a
modification is detected.

The crontabs are stored in several locations, collectively known as
"crontab groups":

**  master crontab

Master crontab is read from the file /etc/crontab.

** system crontabs

A collection of crontab files in the /etc/cron.d directory.

** user crontabs

Individual user crontabs are located in /var/spool/cron/crontabs.

** user group crontabs

A special crontab group intended for use with pseudo-accounts, such
as "apache", "www-data", or or "bind".  Crontabs of this group are
located in subdirectories of /var/spool/cron/crongroups named by the
corresponding account.  This crontab group will be described in detail
later.

Each active (i.e. non-empty and non-comment) line in a crontab
specifies a schedule and a command line to be run according to that
schedule.  Active lines in master and system crontabs specify also the
login name of the user on behalf of whom the command must be run.

Both master and system crontabs are writable only by the super-user.

User and user group crontabs belong to particular users and
instructions they contain are executed on behalf of their owners.
To enable users to manipulate their crontabs, the crontab command is
provided.

* Special Features

This section describes features which distinguish micrond from other
cron implementations.

** Group crontabs

User group crontabs are an experimental feature designed to facilitate
maintenance of per-service crontabs.  Consider, for example, a web
server that runs multiple web sites maintained by various users who
need to run periodic backend jobs on behalf of the account the httpd
server runs as.  User group crontabs make it possible without
intervention of the system administrator.  Let's assume httpd runs as
the user "apache".  The system administrator creates a directory
/var/spool/cron/crongroups/apache, and sets "apache" as its owner:

  mkdir /var/spool/cron/crongroups/apache
  chown apache: /var/spool/cron/crongroups/apache

Then, he adds login names of those users who should be able to edit
apache cronjobs to the primary group of the "apache" user.  Once done,
these users become able to create and edit crontabs in this directory
using the "crontab -g" command (short for "group").  For example, the
command

  crontab -u apache -g -e myproject

edits the file "myproject" in this directory.

Being an experimental feature, user group crontabs are disabled by
default.  To enable them, run "micrond" with the "-g group" option.

** Long crontab lines

Very long crontab lines can be split across several physical lines
using the familiar backslash continuation technique: a backslash
appearing immediately before the ending newline character is removed
along with the newline and the content of the next line is appended in
its place.  Multiple line continuations are allowed, as long as the
total line length does not exceed 1024 characters.

** Built-in variables

A number of built-in variables control the interpretation of crontab
entries and execution of commands.  Each built-in variable has two
name variants: the name prefixed with `_JOB_' affects only the cronjob
definition that immediately follows it (with optional variable
assignments in between), whereas the name prefixed with `_MICRON_'
affects all commands that follow, until another assignment of the
same variable is encountered or the end of file is reached.  For
example, the following fragment instructs micrond to log all output
produced by the command `run-periodic' to syslog facility `daemon'
using the tag "hourly".  These two settings affect only this
particular command:

  _JOB_SYSLOG_FACILITY = daemon
  _JOB_SYSLOG_TAG = hourly
  15 * * * *  root  run-periodic

The built-in variables are described in detail in

  https://www.gnu.org.ua/software/micron/manual/Variable-Settings.html

When referencing built-in variables in this document, we refer to them
using the `_MICRON_' prefix.  This means that in the sections that
follow, any reference to the variable `_MICRON_x' (global scope),
means that there is also the `_JOB_x' variable, whose semantics is
the same, but which affects only the cronjon that is defined
immediately after it.

** The day field semantics

In a crontab schedule, the day of a command's execution can be
specified by two fields: day of month (field 3), and day of week
(field 5).  If both fields are restricted (i.e. are not '*'), their
interpretation differs among various implementations.  Vixie cron will
run the command when either field matches the current time (the fields
are joined by a logical OR).  Dillon's cron interprets the 3rd field
as an ordinal number of weekday in month (so that allowed numeric
values of the 3rd field in this case are 1-5).  Consider for example
the following schedule

  0 11 1,4 * 1-3

For Vixie cron, this means "run the command on each 1st and 4th day of
the month as well as on each Monday, Tuesday and Wednesday".  The
meaning of this schedule for Dillon's cron is: "run the command on
each first and fourth Monday, Tuesday and Wednesday in the month".
The semantics used by micron is configurable.  By default it assumes
the two fields to be joined by a logical AND, i.e. the example above
would mean "each first and fourth day of the month *iff* the day of
week is Monday, Tuesday or Wednesday".  The use of Vixie or Dillon
semantics can be requested by setting the `_MICRON_DAY_SEMANTICS'
variable in the crontab.  For example, the line

  _MICRON_DAY_SEMANTICS = Vixie

requests the semantics used by Vixie cron.

** Variable assignment in crontabs

Variable assignments can appear anyplace in a crontab.  The modified
environment remains in effect for all subsequent commands until
changed by another assignment or the end of file is reached, whichever
happens first.  For example, output of the following two example
entries is mailed to two different users: 

  MAILTO=one
  * * * * * command one
  MAILTO=two
  * * * * * command two

** Cronjob output

Output of a crontab job can be either mailed to its owner (a
traditional behavior) or reported via syslog to arbitrary facility, or
appended to a disk file.

This is controlled by the following variables: `MAILTO', `_MICRON_MAILTO',
`_MICRON_SYSLOG_FACILITY', and `_MICRON_OUTFILE'.  For details, refer to

  https://www.gnu.org.ua/software/micron/manual/Cronjob-Output.html

** Simultaneous job execution

The number of simultaneously running instances of a cron job is
limited by the value of the `_MICRON_MAXINSTANCES' variable.  The
default value is 1, which means that the job won't be started until
its previous instance terminates.

** Detection of crontab modifications

On GNU/Linux systems, micrond uses `inotify' to track crontab
modifications.  This means that any change to a crontab is noticed as
soon as the crontab file is saved.

On other systems, micrond relies to checking the crontab modification
times each minute, which is less effective.

The use of `kqueue' interface on *BSD systems is planned in future
versions.

* Downloads and Installation

The program can be downloaded from

  https://download.gnu.org.ua/release/micron

Before installation, create a group which will be used as owner of the
user and user group crontab directories.  The `crontab' binary will be
installed as set-GID to that group.  By default, the group is named
"crontab".  Assuming this, the usual build sequence is

  ./configure
  make
  make install

If you chose another group name, supply it to `configure' with the
`--with-crontab-gid' option.

The above commands will install the package under "/usr/local".  That
is, the server will be installed as "/usr/local/sbin/micron", the
`crontab' utility as "/usr/local/bin/crontab", etc.  If that's not
what you want, use the `--prefix' option to specify the installation 
prefix, e.g.

  ./configure --prefix=/usr

Refer to the `INSTALL' document in the source directory for a
discussion of available options to configure and their effect.

* Testing

To execute tests, run `make check'.  Unit tests (parser and time
scheduler testsuites) don't require any special software and are
always enabled.  Tests that involve running the micrond library
are disabled by default.  These tests require two special loadable
libraries:

- libfaketime
    A library that reports modified dates and times.  It is
    available from

      https://github.com/wolfcw/libfaketime

    You will need version 0.9.8 or newer.  Notice, that although
    debian-based systems provide libfaketime as a package, the
    packaged version is (at the time of this writing) outdated and
    cannot be used for micron testsuite.

- libfakeroot
    A library that fakes root privileges.  It is not needed
    when `make check' is run as root, obviously.  The library
    is available from

      http://ftp.debian.org/debian/pool/main/f/fakeroot/.

    On debian-based systems it can be installed using

      apt-get install libfakeroot

    The library will be placed to

      /usr/lib/x86_64-linux-gnu/libfakeroot/libfakeroot-0.so    

If both libraries are installed, run ./configure with options
--with-faketime and --with-fakeroot.  Both options take as argument
the name of the directory, where the corresponding library can be
found, e.g.:

  ./configure --with-faketime=/usr/lib/x86_64-linux-gnu/faketime \
              --with-fakeroot=/usr/lib/x86_64-linux-gnu/libfakeroot

Once configured this way, `make check' will also run tests in which
micrond binary is involved.  Notice, that for obvious reasons these
take some time to execute.  Depending on the nature of test, this time
ranges between 5 and 28 seconds.  Running all 14 micrond tests takes
slighly more than 2 minutes.

* The name

It was thought to be a MInimal CRON implementation.  Turned out the
other way.

* Bug reporting.

Send bug reports to <gray@gnu.org.ua>.  Make sure to mention "micron"
in the subject.

You can also use bug-tracker at

  https://puszcza.gnu.org.ua/bugs/?group=micron

(requires authorization).

* References

Complete documentation for micron is available in various formats from

  https://www.gnu.org.ua/software/micron

Download directory:

  https://download.gnu.org.ua/release/micron

Development version:

  https://puszcza.gnu.org.ua/software/micron/

Git repository:

  https://git.gnu.org.ua/micron.git/

* Copyright information:

Copyright (C) 2021-2024 Sergey Poznyakoff

   Permission is granted to anyone to make or distribute verbatim copies
   of this document as received, in any medium, provided that the
   copyright notice and this permission notice are preserved,
   thus giving the recipient permission to redistribute in turn.

   Permission is granted to distribute modified versions
   of this document, or of portions of it,
   under the above conditions, provided also that they
   carry prominent notices stating who last changed them.

Local Variables:
mode: outline
paragraph-separate: "[	]*$"
version-control: never
End:
