\input texinfo  @c -*- texinfo -*-
@setfilename micron.info
@c %**start of header
@settitle GNU Micron Manual
@setchapternewpage odd

@defcodeindex pr
@defcodeindex op
@defcodeindex kw
@defcodeindex fl

@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex op cp
@syncodeindex pr cp
@syncodeindex kw cp

@include version.texi

@ifinfo
@dircategory System Administration
@direntry
* micron: (micron).     Flexible cron scheduler.
* micrond: (micron).    The cron daemon.
* crontab: (micron).    The crontab command.
* Crontab format: (micron).  Format of the crontab file.
@end direntry
@end ifinfo
@c %**end of header

@iftex
@finalout
@end iftex
@copying
Copyright @copyright{} 2021--2024 Sergey Poznyakoff

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover, and no Back-Cover texts.
A copy of the license is included in the section entitled ``GNU Free
Documentation License.''
@end copying

@titlepage
@title Micron
@subtitle version @value{VERSION}, @value{UPDATED}
@author Sergey Poznyakoff.
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top Micron

This edition of the @cite{Micron Manual}, last updated
@value{UPDATED},
documents @command{micron} Version @value{VERSION}.
@end ifnottex

@node Overview
@chapter Overview

@samp{Micron} is an implementation of the UNIX @command{cron} daemon,
a program that executes periodically various tasks.  It provides a
flexible job scheduler that offers complete control over execution
of the scheduled commands as well as additional organizational
features.

@cindex Vixie, Paul
@cindex Paul Vixie
@cindex Dillon, Matt
@cindex Matt Dillon
Cron daemons have a long history, dating back to Seventh Edition Unix.
The most widespread cron implementations today are @dfn{Vixie cron}
and its derivatives, originally written by Paul Vixie, and
@dfn{Dillon's cron}, written by Matt Dillon.

@samp{Micron} is a clean, multi-threaded implementation, written from
scratch, which does not share any code with its predecessors.  Some of
the new features provided by @samp{micron} are: flexible control over
cronjob's standard output and error streams, which can be redirected
to syslog, mailed to arbitrary list of emails, appended to a file, or
simply ignored, control over the number of cronjob instances that are
allowed to run simultaneously, and user-group crontabs.  For a
complete list, see @ref{Features}.

While providing new features, @samp{micron} tries to preserve backward
compatibility with the two above-mentioned implementations.  In
particular, existing crontabs from @dfn{Vixie} cron can be used with
@samp{micron} without changes.  The same holds true for per-user
crontabs from @dfn{Dillon's} cron.  System-wide crontabs from @dfn{Dillon's}
cron will require a minor editing: the user name must be added between
the schedule and command.

The implementation consists of two binaries: the main daemon @command{micrond}
and the @command{crontab} utility.

@node Crontabs
@chapter Crontabs

A set of @dfn{crontab} files contains instructions specifying what
commands to run and defining schedules for them.  @command{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 such are detected.

@node Crongroups
@section Crontab Groups
Crontabs are stored in several locations, collectively known as
@dfn{crontab groups} or @dfn{crongroups}, for short.  These are:

@table @dfn
@item master crontab
@cindex master crontab
@flindex /etc/crontab
The file @file{/etc/crontab}.  It is used for site-wide cronjobs, i.e.
tasks necessary for the normal functioning of the system.

@item system crontabs
@cindex system crontab
@flindex /etc/cron.d
A collection of crontab files in the @file{/etc/cron.d} directory.
These are used for per-package cronjobs.

@item user crontabs
@cindex user crontab
@flindex /var/spool/cron/crontabs
Crontab files located in @file{/var/spool/cron/crontabs} contain
per-user cronjobs and are editable by users.

@item user group crontabs
@cindex group crontab
@flindex /var/spool/cron/crongroups
A special crontab group intended for use with pseudo-accounts, such
as @samp{apache} or @samp{bind}.  Crontabs of this group are located in
subdirectories of @file{/var/spool/cron/crongroups} named by the
corresponding account.  This crontab group is described in detail
in @ref{User Group Crontabs}.
@end table

Each @emph{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
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 @command{crontab}
command is provided (@pxref{crontab}).

@node Crontab Format
@section Crontab Format

Crontabs used by @command{micrond} are mostly compatible with @dfn{Vixie}
crontabs.  They are plain text, line-oriented files.  When parsing a
crontab, the leading and trailing whitespace on each line is ignored.
Comments are introduced by a hash sign (#) appearing as the first
non-whitespace character in a line.  Comments and empty lines are
ignored.  Very long lines can be split across several physical lines
using backslash as continuation character.  Total length of a valid
crontab line after removing continuation characters cannot exceed 1024
characters.

Each crontab line is either a cronjob definition or a variable setting.

@node Cronjob Definition
@subsection Cronjob Definition
A @dfn{cronjob definition} is a line in crontab that defines a
running schedule, a user on whose behalf the job will be run (in
system crontabs), and a command to be run.

The fields are delimited by arbitrary amount of whitespace.

Cronjob definition begins with a @dfn{cron expression}, which
defines schedule for running the command.  It consists of five
fields in this order:

@multitable @columnfractions 0.4 0.6
@headitem field @tab allowed values
@item minute       @tab 0-59
@item hour         @tab 0-23
@item day of month @tab 1-31
@item month        @tab 1-12, or abbreviated month names
@item day of week  @tab	0-7 (0 or 7 is Sunday), or abbreviated day names
@end multitable

A field may contain a single asterisk @samp{*}, which stands for
``each time unit''.  For example, it means ``each minute'' when used
in the first field, ``each hour'' in second one, and so on.  Asterisk
can be followed by a slash and a decimal number, which defines a step
within the interval.  E.g. @samp{*/2} in second field stands for ``each
second hour''.

The field may also be a comma-delimited list of the following
constructs:

@table @asis
@item @var{n}
A single number.  E.g. @samp{2} in first field means ``second minute of an
hour''.

@item @var{i}-@var{j}
Two numbers delimited by a dash define a range.  E.g @samp{2-5} in first
field is ``minutes 2,3,4, and 5 (inclusive)''.  The order is
important.  For example, the following schedule:

@example
55-5 * * * *
@end example

@noindent
means ``minutes 55 through 59 and 0 through 5 of the next hour''.

@item @var{i}-@var{j}/@var{n}
Same as above, but with step of N units, e.g.:

@example
10-25/5 * * * *
@end example

@noindent
which stands for ``minutes 10,15,20,25''.
@end table

Names can be used in ``month'' and ``day of week'' fields.  Day and
week names are abbreviated to their first three characters
(case-insensitive).  Ranges or lists of names are allowed as well.

@cindex day field semantics
The day of command's execution is determined by two fields:
day of month, and day of week.  If both are supplied (i.e. are not
@samp{*}), the result depends on the selected @dfn{day field
semantics}.  There are three cases:

@table @dfn
@item Strict semantics
@cindex strict day semantics
The command will be run only when both fields match the current time.
For example,

@example
30 4 1,15 * 5
@end example

@noindent
means ``run the command at 4:30 am each Friday between the 1st and
15th of each month''.

This semantics is the default for @command{micrond}.

@item Vixie semantics
@cindex vixie day semantics
The command will be run when either field matches the current time.
Thus, the previous example would cause a command to be run at 4:30 am
on the 1st and 15th of each month, plus every Friday.

@item Dillon semantics
@cindex dillon day semantics
If both day of the month and day of week are supplied, the former
must be an integer number in range 1-5.  Its meaning is Nth such weekday
in the month.  For example, to run the date command at 11 am on the
second and third Monday, Tuesday and Wednesday of each month:

@example
0 11 2,3 * mon-wed date
@end example

To request the last Monday, etc. in a month, use @samp{5}.
This will always match the last Monday, etc., even if there are only
four Mondays in the month:

@example
0 11 1,5 * mon-wed date
@end example

When the fourth Monday in a month is the last, it will match against
both 4 and 5, but will only run once if both are specified.
@end table

The semantics to use is selected by setting the
@env{_MICRON_DAY_SEMANTICS} (@pxref{_MICRON_DAY_SEMANTICS}) variable
to one of the following values: @code{strict}, @code{vixie}, @code{dillon}
(case-insensitive).

Instead of the first five fields, the following macro-definitions can
be used:

@table @code
@kwindex @@reboot
@item @@reboot
Run once, at @command{micrond} startup.

@kwindex @@yearly
@kwindex @@annually
@item @@yearly
@itemx @@annually
Run once a year, i.e. @samp{0 0 1 1 *}.

@kwindex @@monthly
@item @@monthly
Run once a month, @samp{0 0 1 * *}.

@kwindex @@weekly
@item @@weekly
Run once a week, @samp{0 0 * * 0}.

@kwindex @@daily
@kwindex @@midnight
@item @@daily
@itemx @@midnight
Run once a day, @samp{0 0 * * *}.

@kwindex @@hourly
@item @@hourly
Run once an hour, @samp{0 * * * *}.
@end table

In master crontab (@file{/etc/crontab}) and system crontabs (located in
@file{/etc/cron.d}), the cron expression is followed by @dfn{user name} field,
which holds a login name of the user on whose behalf the command will
be run.

This field is absent in user personal crontabs, since these are always
run on behalf of the user that owns them,

@cindex input, cronjob
@cindex standard input for a cronjob
The remainder of line is taken as a shell command to be run when
the time matches the schedule.  The percent sign in the command line is
special: the first occurrence of unescaped and unquoted @samp{%}
delimits the command line proper and the text that will be piped to
its standard input.  Any unescaped occurrences of @samp{%} to the
right of it will be replaced with newlines.  To use a literal percent
sign in the job command line, either precede it with a backslash or
quote it using single or double quotes.

For example, the following command line:

@example
mail hostmaster%Hello,%%This is a daily notification.%--%Regards from cron.%
@end example

@noindent
will cause @command{mirond} to start the @command{mail} command and
to supply the following text to its standard input:

@example
@group
Hello,

This is a daily notification.
--
Regards from cron.
@end group
@end example

Before running the command, @command{micrond}
changes the directory to the home directory of the user on whose
behalf the command is run (as defined by the @env{HOME} environment
variable, @pxref{HOME}), modifies the environment as requested by variable
settings (@pxref{Variable Settings}) and runs the command as

@example
$SHELL -c "@var{command}"
@end example

Default @env{SHELL} is @samp{/bin/sh} (@pxref{SHELL}).

@node Variable Settings
@subsection Variable Settings
@cindex variables in crontab
@cindex variable, define
@cindex define a variable
Variable settings modify execution environment for subsequent cron
commands.  Some variables are internal to @command{micrond} and modify
its behavior.  A variable setting has the form

@example
@var{name} = @var{value}
@end example

@noindent
where @var{name} is the variable name and @var{value} is the value to
be assigned to it.  Notice several important differences from the
similar construct in shell.  First of all, optional whitespace is
allowed on either side of the equals sign.  Secondly, the value is
assigned verbatim, after removing any trailing and leading whitespace.
No expansions or substitutions take place.  If you need this kind of
functionality, move environment manipulations to a shell script and
invoke it from the cron command.

@cindex empty variable
@cindex variable, empty value
You don't need to quote @var{value} even if it contains embedded
whitespace.  There are only two cases when quoting becomes necessary: to
define an empty variable or to preserve leading or trailing
whitespace.  Both single and double quotes can be used, the only
requirement being that both quotes match.  Inside a quoted string, a
backslash character can be used to escape a quote character or another
backslash.  To define an empty variable, use a pair of quotes.

@cindex variable, undefine
@cindex variable, unset
@cindex unset a variable
The special construct

@example
@var{name} =
@end example

@noindent
unsets the variable @var{name}.

Each variable setting applies to all cron commands that follow it, until
another setting overwrites it or the end of file is encountered.

@cindex built-in variables
@cindex variable, built-in
@anchor{built-in variables}
The following are @dfn{built-in variables}.  They modify
the handling of cron commands that follow them, but are not copied to
the command environment.  Variables prefixed with @samp{_JOB_}
affect only the first cron command that appears after them, whereas
variables prefixed with @samp{_MICRON_} affect all commands that
follow them, until another assignment of the same variable is
encountered or the end of the file is reached.  A built-in variable
can be assigned a default value in the command line using the
@option{-v} option (@pxref{initial value}).

@defvr {Built-in variable} _MICRON_OUTFILE_FACILITY
@defvrx {Built-in variable} _JOB_OUTFILE_FACILITY
The value of this variable is the name of a file.  If the variable
is set, any output the cronjob produces will be appended to that file.

@xref{Sending output to file}.
@end defvr

@anchor{_MICRON_SYSLOG_FACILITY}
@defvr {Built-in variable} _MICRON_SYSLOG_FACILITY
@defvrx {Built-in variable} _JOB_SYSLOG_FACILITY
If this variable is set to a meaningful syslog facility, the cronjob
output will be logged to that facility (priority @samp{INFO}), instead
of mailing it the usual way.  @xref{Logging output to syslog}.

Allowed values for this variable are @code{auth}, @code{authpriv},
@code{cron}, @code{daemon}, @code{ftp}, @code{lpr}, @code{mail},
@code{news}, @code{syslog}, @code{user}, @code{uucp}, and @code{local0}
through @code{local7}.

The value @code{default} means to use the default syslog facility
(@code{cron}), and @code{off} or @code{none} disables syslog and
reverts to mailing the program output as directed by the @env{MAILTO}
variable (@pxref{MAILTO}).
@end defvr

@anchor{_JOB_SYSLOG_TAG}
@defvr {Built-in variable} _JOB_SYSLOG_TAG
Sets the syslog tag for the next cron command.  The tag is used when
logging cronjob output to syslog (@pxref{Logging output to syslog}),
or appending it to a file (@pxref{Sending output to file}).  If not
specified, the tag will be constructed as

@example
@var{file}:@var{line}(@var{prog})
@end example

@noindent
where @var{file} and @var{line} are the file name and line number of the
line where the cron command appeared and @var{prog} is the first word
of the command.

@anchor{_MICRON_SYSLOG_TAG}
@kwindex _MICRON_SYSLOG_TAG
The global counterpart of this variable, @env{_MICRON_SYSLOG_TAG},
is provided for completeness.  It is probably of little use, since it
sets the same tag for all crontab entries.
@end defvr

@anchor{_MICRON_MAXINSTANCES}
@defvr {Built-in variable} _MICRON_MAXINSTANCES
@defvrx {Built-in variable} _JOB_MAXINSTANCES
An integer value defining how many instances of the same cron job can
be running simultaneously.  Default is 1, i.e. @command{micrond} will
refuse to start a job if its previous run has not yet terminated.
@end defvr

@anchor{_JOB_MAILTO}
@defvr {Built-in variable} _JOB_MAILTO
This variable temporarily masks the @env{MAILTO} environment variable
and disables the variables @env{_MICRON_SYSLOG_FACILITY} and
@env{_MICRON_OUTFILE} for the next crontab entry.  After that, the
previous values are restored.  Use it to redirect output of a
single crontab entry to a particular email address.

@kwindex _MICRON_MAILTO
The global version of this variable, @env{_MICRON_MAILTO}, is mostly
equivalent to the traditional @env{MAILTO} variable, except that any
existing value of @env{MAILTO} is retained in the environment.

@xref{Mailing the cronjob output}, for the detailed discussion of how the
output is mailed.

@xref{Cronjob Output}
@end defvr

@anchor{_MICRON_DAY_SEMANTICS}
@defvr {Built-in variable} _MICRON_DAY_SEMANTICS
@defvrx {Built-in variable} _JOB_DAY_SEMANTICS
Defines the day semantics.  Allowed values are: @code{strict},
@code{vixie}, and @code{dillon} (case-insensitive).  @xref{Day
Field Semantics}.
@end defvr

The following are environment variables that modify the behavior of
@command{micrond} itself.

@anchor{MAILTO}
@defvr {Environment} MAILTO
Defines an email address or a comma-delimited list of email addresses.
If any of the cron commands that follow this setting produces anything on
its standard output or standard error, the output will be collected
and mailed to the emails listed in the @env{MAILTO} variable.  If the
variable is undefined, the output will be sent to the owner of the
crontab.  If @env{MAILTO} is set to an empty string, no mail will be
sent.

@xref{Mailing the cronjob output}, for the detailed discussion of how the
output is mailed.
@end defvr

@anchor{HOME}
@defvr {Environment} HOME
Defines the working directory from which the subsequent commands will
be run.  Defaults to home directory of the user on whose behalf
the command is run.
@end defvr

@anchor{SHELL}
@defvr {Environment} SHELL
Defines the shell used to start commands.  Defaults to @samp{/bin/sh}.
@end defvr

@node Cronjob Output
@section Cronjob Output
When run, a cronjob can print something on its standard output or
error streams.  The output it produces can be sent via email to
a given list of addresses, appended to a file, or reported via
syslog.  This @dfn{output redirection} can be configured either
globally, or individually for each job.  It is controlled by the
following variables:

@table @env
@item MAILTO
@itemx _MICRON_MAILTO
@itemx _JOB_MAILTO
Send the output via email.

@item _MICRON_SYSLOG_FACILITY
@itemx _JOB_SYSLOG_FACILITY
Report each output line via syslog.

@item _MICRON_OUTFILE
@itemx _JOB_OUTFILE
Append the output to a file.
@end table

These settings are discussed in detail in the following subsections.

@node Mailing the cronjob output
@subsection Mailing the cronjob output
@cindex email, job output
@cindex @code{From:} header, job output mail
The default behavior is to mail the cronjob output to the user on
whose behalf the cronjob is run.  The message @code{From:} header is
constructed as follows:

@example
From: (Cron daemon) <@var{owner}@@@var{host}>
@end example

@noindent
where @var{owner} is the login name of the job owner, and @var{host}
is the name of the host where it was run.

@cindex @code{Subject:} header, job output mail
The @code{Subject:} header contains the owner login name, hostname of the
server where the command was run and the command itself, in the
following format:

@example
Cron <@var{user}@@@var{host}> @var{command}
@end example

@cindex @code{X-Cron-Env:}, job output mail
A copy of execution environment is included in the message in the form of
additional @code{X-Cron-Env:} headers, each containing a single
environment variable.

The recipient of the message can be altered by setting the
@env{MAILTO}, @env{_JOB_MAILTO}, and @env{_MICRON_MAILTO}
variables in the crontab.

The @env{MAILTO} variable is the traditional way of defining the
recipients for the job output.  It affects all cronjobs in crontab
that appear after it, until next definition of any of the three
variables discussed, or end of the crontab file, whichever occurs
first.  It is also reflected in the environment of the job itself.
@xref{MAILTO}.

If @env{MAILTO} is unset, the default behavior (mailing to the owner)
is restored.  If it is set to an empty string, cronjob output is
discarded.

@emph{Notice} the difference:

@table @code
@item MAILTO =
Restores default behavior.

@item MAILTO = ""
Discards the output.
@end table

The two built-in variables @env{_JOB_MAILTO} and @env{_MICRON_MAILTO}
behave as @env{MAILTO}, with the following differences:

The @env{_JOB_MAILTO} variable, if set, affects only the cronjob that
immediately follows it.  It is not reflected in the environment.
@xref{_JOB_MAILTO}.

The @env{_MICRON_MAILTO} variable is rarely used.  It works exactly as
@env{MAILTO}, except that the actual value of the latter remains
unchanged.  It is not reflected in the environment, either.

@node Logging output to syslog
@subsection Logging output to syslog
@kwindex _MICRON_SYSLOG_FACILITY
To send the output of all the cronjobs to the syslog, assign the name
of the syslog facility to the built-in variable
@env{_MICRON_SYSLOG_FACILITY}, e.g.:

@example
_MICRON_SYSLOG_FACILITY = local0
@end example

Valid facility names are @code{auth}, @code{authpriv},
@code{cron}, @code{daemon}, @code{ftp}, @code{lpr}, @code{mail},
@code{news}, @code{syslog}, @code{user}, @code{uucp}, and @code{local0}
through @code{local7}.

Similarly, to log only a single cronjob output, define the
variable @env{_JOB_SYSLOG_FACILITY} immediately before that cronjob.

@anchor{cronjob tag}
In the produced log, each line of a cronjob output will be tagged with
a fully-qualified name of the cronjob, constructed as:

@example
@var{file}:@var{line}(@var{prog})
@end example

You can alter this using the @env{_JOB_SYSLOG_TAG} variable.  The
following example illustrates the use of the two per-job syslog
variables:

@example
_JOB_SYSLOG_FACILITY = daemon
_JOB_SYSLOG_TAG = daily_cleanup
0 1 * * *  root  /usr/local/bin/cleanup
@end example

@node Sending output to file
@subsection Sending output to file
@kwindex _MICRON_OUTFILE
To redirect cronjob output to a file, use the @env{_MICRON_OUTFILE}
or @env{_JOB_OUTFILE} built-in variables.  The value of these variables
is the name of file to append the output to.  For example, to redirect
output of all cronjobs in a crontab to file
@file{/var/log/cronout}, place the following at the beginning of the
crontab:

@example
_MICRON_OUTFILE = /var/log/cronout
@end example

For example, when running @command{micrond} in a docker container, you
can redirect the output of all cronjobs to the container log as
follows:

@example
_MICRON_OUTFILE = /proc/1/fd/1
@end example

@kwindex _JOB_OUTFILE
The @env{_JOB_OUTFILE} variable affects only the cronjob that follows it.

Output from each job is appended to the output file in a single
chunk, which appears between the following two delimiter lines:

@example
@var{ts_start}: @var{tag} output begins
@end example

@noindent
and

@example
@var{ts_end}: @var{tag} output ends
@end example

@noindent
where @var{ts_start} and @var{ts_end} are job start and
termination timestamps in ISO 8601 format, and @var{tag} is the
cronjob tag, formatted as described in @ref{cronjob tag}.  If the
@env{_SYSLOG_TAG} variable is defined, its value will be used instead.

For example:

@example
@group
2021-10-23T03:00:00: /etc/cron.d/backup:16(daily_backup) output begins
.
.
.
2021-10-23T03:07:15: /etc/cron.d/backup:16(daily_backup) output ends
@end group
@end example

@node micrond
@chapter micrond

@command{micrond} executes commands periodically as directed by one or
more @dfn{crontabs}.  @xref{Crontabs}, for a discussion of crontab
locations and format.

Normally, a cron job is not run if its previous instance is still
running.  For instance, if a cron job scheduled to run each minute
takes three minutes to finish, it will be actually run once in three
minutes.  This behavior can be altered by setting the
@env{_MICRON_MAXINSTANCES} variable to the desired number of cron job
instances that can be run simultaneously (use @env{_JOB_MAXINSTANCES}
to change the setting for one job only, @pxref{_MICRON_MAXINSTANCES}).

Depending on cronjob settings, any data the running job produces
on its standard output and standard error can be either logged via syslog in
real time, or captured and, upon termination of the job, mailed to the
job owner, or appended to a file (@pxref{Cronjob Output}).

On GNU/Linux systems, @command{micrond} monitors each opened crontab
for modifications and re-reads it as soon as it is written to disk.
On other systems, it checks crontab modification times each minute and
re-reads those crontabs for which this value has changed.

@node micrond invocation
@section micrond Invocation

The @command{micrond} daemon takes no command line arguments.  Its
behavior is controlled by command line options.

Unless instructed otherwise, upon startup @command{micrond}
disconnects from the controlling terminal and remains in the
background.  During normal execution it logs its diagnostic messages
(if any) via @code{syslog} facility @samp{cron}.  Eventual output and
error diagnostics from the invoked cron jobs are mailed to the job
owner, as described in @ref{Mailing the cronjob output}.

The following options modify the @command{micrond} behavior:

@table @option
@opindex -f
@item -f
Remain in foreground.

@opindex -h
@item -h
Display a short help summary and exit.

@opindex -g
@item -g @var{group}=@var{dir}
Define the directory or file name for crontab group @var{group}.
Valid group names are: @code{master}, @code{system}, @code{user},
and @code{group}.  @xref{Crongroups}.

@opindex -g
@item -g @var{group}
@itemx -g no@var{group}
Enable or disable crontab group @var{group}.  Note, that the
@code{group} crontab group is disabled by default.

@opindex -l
@item -l @var{pri}
Log only messages with syslog priority @var{pri} or higher.  Valid
arguments are, in order of increasing priority: @code{debug}, @code{info},
@code{notice}, @code{warning}, @code{err}, @code{crit}, @code{alert},
and @code{emerg}.

@opindex -m
@item -m @var{mailer}
Set the mailer command.  Default is @command{/usr/sbin/sendmail -oi -t}.

@opindex -P
@cindex PID file
@item -P @var{file}
Write PID of the program to @var{file}.

@opindex -p
@item -p @var{socket}
Send messages to syslog via this socket.  The argument is either an
absolute file name of a UNIX socket, or a host name or IPv4 address
optionally followed by a colon and port number or service name.

@opindex -S
@item -S
When running in foreground (see the @option{-f} option), log messages
from @command{micrond} to the syslog facility @samp{cron}, instead of
printing them to the standard error.  Not to be confused with the
@option{-s} option, described below.

@anchor{syslog option}
@opindex -s
@item -s
Log output from cronjobs to syslog.  By default, the @samp{cron}
facility is used.  Use the @option{-v syslog_facility=@var{f}} option
to change it to facility @var{f}.  See below, for the discussion of
the @option{-v} option.

@opindex -T
@item -T @var{N}
In foreground mode, when logs go to stderr, precede each line with a
timestamp in ISO 8601 format (@option{-T0}).  @var{N} can be 1 to skip
seconds and 2 to skip both minutes and seconds from the timestamp.

@opindex -t
@item -t @var{n}
Before exiting, @command{micrond} checks if any of the cronjobs are
still running.  If so, it sends them the @code{SIGTERM} signal and
waits @var{n} seconds for them to terminate.  The cronjobs that fail
to exit within that amount of time are terminated forcibly by sending
them the @code{SIGKILL} signal.

The default timeout is 60 seconds.

@opindex -V
@item -V
Print program version, licensing information and exit.

@anchor{initial value}
@cindex initial value of a built-in variable
@cindex built-in variable, initial value
@opindex -v
@item -v @var{name}=@var{value}
Assigns initial value for the @command{micrond} internal variable
@var{name} (@pxref{built-in variables}).  The variable name must be
used without prefix.  Comparison is case-insensitive.  For example:

@example
-v syslog_facility=daemon
@end example

@noindent
is equivalent to

@example
_MICRON_SYSLOG_FACILITY = daemon
@end example

@opindex -W
@item -W @var{opt}
@kwindex paranoid_memfree
Set internal @command{micrond} option.  As of version @value{VERSION},
only one such option is implemented: @code{paranoid_memfree}.  When
@option{-Wparanoid_memfree} is given, @command{micrond} will
meticulously free all allocated memory before terminating.  Normally
this isn't needed, as the operating system will reclaim that memory
anyway.  Use this option if you run @command{micrond} under
@command{valgrind} or another memory leak detector, in order to avoid
spurious warnings.
@end table

@node crontab
@chapter The @command{crontab} Utility
The @command{crontab} utility allows the user to list, edit or remove
personal or group crontabs.

The @command{micrond} cron daemon reads crontabs from several crontab
groups, two of which contain crontabs for particular system users.
The @dfn{user crongroup} contains per-user crontabs, and the @dfn{group
crongroup} contains user crontabs editable by a group of users
(@pxref{Crongroups}).

By default, @command{crontab} operates on per-user crontabs.  To edit
group crontabs, the @option{-g} option must be specified.

When run without arguments, @command{crontab} enters @dfn{copy mode},
in which it copies the content of the supplied file to the user
personal crontab, overwriting its prior content.  For example

@example
crontab newfile
@end example

@noindent
overwrites the current crontab schedule of the user with the content
of the file @file{newfile}.

To list the content of the crontab, use the @option{-l} option.  It will
be displayed on standard output.

@cindex @env{VISUAL}, environment variable
@cindex @env{EDITOR}, environment variable
@cindex @command{vi}
@cindex editor, default
@cindex default editor
To edit it, run @command{crontab -e}.  A temporary copy of the crontab
will be created and loaded to the editor specified by the @env{VISUAL}
environment variable.  If it is unset, the @env{EDITOR} variable is
consulted.  If this variable is unset as well, the built-in default
@samp{vi} will be used.

Once you quit the editor, the edited crontab will be atomically moved to
your personal crontab and re-read by @command{micrond}.

The @option{-r} option removes the crontab.  Use it with caution.
No backup copies are preserved.

When using destructive operations (such as copying or removal), it is
safer to use the @option{-i} option which instructs the program to ask
for the user consent before undertaking the modification.

The super-user can address the crontab of a particular user by
supplying the user login name with the @option{-u} option.  The use
of this option is restricted for super-user, except if used together
with the @option{-g} option.

User crontab groups contain multiple files for each system user.  They
are useful for certain pseudo-accounts.  For example, a site running
multiple web services may need to install separate crontabs for each
of them and to allow users who run these services to edit their
crontabs.  This is done using the @option{-g} option.  The name of the
account for which the crontab is edited is supplied with the
@option{-u} option.  For example, to edit a crontab @samp{portal} in
account @samp{www-data}, one would use:

@example
crontab -g -u www-data -e portal
@end example

The use of group crontabs for account @var{x} is allowed only for
users who are members of the primary group of @var{x}.

@node crontab Invocation
@section crontab Invocation

The crontab usage is:

@table @option
@item crontab [-u @var{name}] @var{file}
Copy mode.  Replace the crontab of the user who invoked the command
with the content of @var{file}.

The @option{-u} is allowed only for super-user.  With this option, the
crontab of the user @var{name} is replaced.

@item crontab [-eilr] [-u @var{name}]
List (@option{-l}), edit (@option{-e}) or remove (@option{-r}) the
user's crontab.

The @option{-u} is allowed only for super-user.  With this option, the
command operates on the crontab of the user @var{name}.

@item crontab -g [-u @var{name}] [-eilr] @var{file}
List (@option{-l}), edit (@option{-e}) or remove (@option{-r}) the
crontab @var{file} in the crongroup of the current user (or user
@var{name}). (@pxref{User Group Crontabs})

The @option{-u} option is allowed for super-user and any user whose
primary group matches that of the user @var{name}.
@end table

The following table summarizes command line options of the
@command{crontab} utility:

@table @option
@opindex -e
@item -e
Edit crontab.

@opindex -g
@item -g
Operate on user cron group files.

@opindex -h
@item -h
Print a short command line usage summary and exit.

@opindex -i
@item -i
Interactively ask before removing or replacing.

@opindex -l
@item -l
List crontab content.  When used with the @option{-g} option, this
option lists the content of the crontab @var{file} in the group.  If
@var{file} is not supplied, displays the list of available crontabs in
the group, along with their owners.

@opindex -r
@item -r
Remove the crontab.

@opindex -u
@item -u @var{name}
Operate on crontab of user @var{name}.

@opindex -V
@item -V
Print program version, licensing information and exit.
@end table

@node Features
@chapter Key Features

The following sections describe features specific to @command{micrond}.

@node User Group Crontabs
@section User 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 @command{httpd}
server runs as.  User group crontabs make it possible without
intervention of the system administrator.  Let's assume
@command{httpd} runs as the user @samp{apache}.  The system
administrator creates a directory
@file{/var/spool/cron/crongroups/apache}, and sets @samp{apache} as
its owner:

@example
@group
mkdir /var/spool/cron/crongroups/apache
chown apache: /var/spool/cron/crongroups/apache
@end group
@end example

Then, he adds login names of the users who are allowed to edit apache
cronjobs to the primary group of the @samp{apache} user.  Once done, these
users become able to create and edit crontabs in this directory using
the @command{crontab} command with the @option{-g} option (short for
@samp{group}).  For example, the command

@example
crontab -u apache -g -e myproject
@end example

edits the file @file{myproject} in this directory.

User group crontabs are disabled by default.  To enable them, run
@command{micrond} with the @option{-g group} option.

@node Long Crontab Lines
@section 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
total line length does not exceed 1024 characters.

@node Built-in Variables
@section 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: setting the name prefixed with @samp{_JOB_} affects only the
cron job definition that immediately follows (with optional
variable assignments in between), whereas setting the name prefixed with
@samp{_MICRON_} affects all commands that follow, until another
assignment of the same variable (or its @samp{_JOB_} counterpart) is
encountered or the end of  file is reached.  For example, the
following fragment instructs @command{micrond} to log all output
produced by the command @command{run-periodic} to syslog facility
@samp{daemon} using the tag @samp{hourly}.  These two settings affect
only this particular command:

@example
@group
_JOB_SYSLOG_FACILITY = daemon
_JOB_SYSLOG_TAG = hourly

15 * * * *  root  run-periodic
@end group
@end example

Built-in variables are described in detail in @ref{built-in variables}.

@node Day Field Semantics
@section Day Field Semantics
@cindex 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 @samp{*}),
their interpretation differs between various @command{cron}
implementations.  @dfn{Vixie} cron will run the command when either field
matches the current time (the fields are thus joined by a logical OR).
@dfn{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:

@example
0 11 1,4 * 1-3
@end example

@noindent
For @dfn{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 @dfn{Dillon's} cron is: ``run the command on
each first and fourth Monday, Tuesday and Wednesday in the month''.

The semantics used by @command{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 @emph{if}
the day of week is Monday, Tuesday or Wednesday''.  The use of @dfn{Vixie}
or @dfn{Dillon} semantics can be requested by setting the
@env{_MICRON_DAY_SEMANTICS} variable in the crontab.  For example,
the line:

@example
_MICRON_DAY_SEMANTICS = Vixie
@end example

requests the semantics used by @dfn{Vixie} cron.

@xref{_MICRON_DAY_SEMANTICS}, for a detailed description of this variable.

@node Variable Assignments in Crontabs
@section Variable Assignments 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, the output of the following two example
entries is mailed to two different users:

@example
@group
MAILTO=one
* * * * * command one
MAILTO=two
* * * * * command two
@end group
@end example

@node Job Output Report
@section Job Output Report

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

The default behavior is to send the output to the user on whose
behalf the cronjob was run.  This in discussed in @ref{Mailing the
cronjob output}.

When syslog is requested, each line of the cronjob output is sent to
the syslog in real time.  This setting can be enabled either globally
by the use @option{-s} command line option, individually in a crontab
(using the @env{_MICRON_SYSLOG_FACILITY} variable), or individually
for a cronjob using the @env{_JOB_SYSLOG_FACILITY} variable.

Syslog tag can be supplied using the @env{_JOB_SYSLOG_TAG} variable
(@pxref{_JOB_SYSLOG_TAG}).  In its absence, syslog tag is
constructed from the location of the job in the crontab file and the
first word of the command.

For a detailed discussion of syslog redirection, @xref{Logging output
to syslog}.

Finally, the output can be captured and appended to a given disk file
upon termination of the cronjob.  This can be useful, e.g. when
running @command{micrond} in a Docker container.  @xref{Logging output
to syslog}.

@node Simultaneous Job Execution
@section Simultaneous Job Execution

@command{Micrond} controls the number of simultaneously running
instances of a cron job.  It is set by the @env{_MICRON_MAXINSTANCES}
variable.  The default value is 1, which means that the job won't be
started until its previous instance terminates.

@xref{_MICRON_MAXINSTANCES}.

@node Detection of Crontab Modifications
@section Detection of Crontab Modifications

On GNU/Linux systems, @command{micrond} uses
@uref{http://man.gnu.org.ua/manpage/?7+inotify,inotify} to track
crontab modifications, which means that any change to a crontab is
noticed as soon as the crontab file is saved.

On other systems, @command{micrond} relies on checking the crontab
modification times each minute, which is less effective.

The use of the @samp{kqueue} interface on *BSD systems is planned in
future versions.

@node Downloads and Installation
@chapter Downloads and Installation

The program can be downloaded from
@uref{https://download.gnu.org.ua/release/micron}.  Before installation,
create a group which will be used as owner for the user and user group
crontab directories.  The @command{crontab} binary will be installed as
set-GID to that group.  By default, the group is named @samp{crontab}.
Assuming this, the usual build sequence is

@example
@group
./configure
make
make install
@end group
@end example

If you chose another group name, supply it to @command{configure}
using the @option{--with-crontab-gid} option.

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

@example
./configure --prefix=/usr
@end example

Please refer to the @file{INSTALL} document in the source directory
for a discussion of available options to configure and their effect.

@node Bug reports
@chapter Bug Reports

If you think you found a bug in @command{micron} or in its
documentation, please send a mail to @email{gray@@gnu.org} (Sergey
Poznyakoff) or use the bug tracker at
@uref{https://puszcza.gnu.org.ua/bugs/?group=micron} (requires
authorization).

@node GNU Free Documentation License
@appendix GNU Free Documentation License

@include fdl.texi

@node Index
@unnumbered Index
@printindex cp

@ifset WEBDOC
@ifhtml
@node This Manual in Other Formats
@unnumbered This Manual in Other Formats
@include otherdoc.texi
@end ifhtml
@end ifset

@bye
