path: root/upstream/opensuse-tumbleweed/man1/crontab.1

.\"/* Copyright 1988,1990,1993 by Paul Vixie
.\" * All rights reserved
.\" */
.\"
.\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC")
.\" Copyright (c) 1997,2000 by Internet Software Consortium, Inc.
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.\" Modified 2010/09/12 by Colin Dean, Durham University IT Service,
.\" to add clustering support.
.\"
.\" $Id: crontab.1,v 1.7 2004/01/23 19:03:32 vixie Exp $
.\"
.TH CRONTAB 1 "2019-10-29" "cronie" "User Commands"
.SH NAME
crontab \- maintains crontab files for individual users
.SH SYNOPSIS
.B crontab
.RB [ -u
.IR user ]
.RI < "file"
.RB | \ - >
.br
.B crontab
.RB [ -T ]
.RI < "file"
.RB | \ - >
.br
.B crontab
.RB [ -u
.IR user ]
.RB < -l " | " -r " | " -e >\ [ -i ]
.RB [ -s ]
.br
.B crontab
.BR -n \ [
.IR "hostname " ]
.br
.B crontab
.BR -c
.br
.B crontab
.BR -V
.SH DESCRIPTION
.I Crontab
is the program used to install a crontab table
.IR file ,
remove or list the existing tables used to serve the
.BR cron (8)
daemon.  Each user can have their own crontab, and though these are files
in
.IR /var/spool/ ,
they are not intended to be edited directly.  For SELinux in MLS mode,
you can define more crontabs for each range.  For more information, see
.BR selinux (8).
.PP
In this version of
.IR Cron
it is possible to use a network-mounted shared
.I /var/spool/cron
across a cluster of hosts and specify that only one of the hosts should
run the crontab jobs in the particular directory at any one time.  You
may also use
.BR crontab
from any of these hosts to edit the same shared set of crontab files, and
to set and query which host should run the crontab jobs.
.PP
Scheduling cron jobs with
.BR crontab
can be allowed or disallowed for different users.  For this purpose, use the
.I cron.allow
and
.I cron.deny
files.  If the
.I cron.allow
file exists, a user must be listed in it to be allowed to use
.BR crontab .
If the
.I cron.allow
file does not exist but the
.I cron.deny
file does exist, then a user must
.I not
be listed in the
.I cron.deny
file in order to use
.BR crontab.
If neither of these files exist, then only the super user is allowed to use
.BR crontab .
.PP
Another way to restrict the scheduling of cron jobs beyond
.BR crontab
is to use PAM authentication in
.I /etc/security/access.conf
to set up users, which are allowed or disallowed to use
.BR crontab
or modify system cron jobs in the
.IR /etc/cron.d/
directory.
.PP
The temporary directory can be set in an environment variable.  If it is
not set by the user, the
.I /tmp
directory is used.
.PP
When listing a crontab on a terminal the output will be colorized unless
an environment variable
.I NO_COLOR
is set.
.PP
On edition or deletion of the crontab, a backup of the last crontab will be saved to
.I $XDG_CACHE_HOME/crontab/crontab.bak
or 
.I $XDG_CACHE_HOME/crontab/crontab.<user>.bak
if
.B -u
is used.
If the
.I XDG_CACHE_HOME
environment variable is not set,
.I $HOME/.cache
will be used instead.
.PP
.SH "OPTIONS"
.TP
.B "\-u"
Specifies the name of the user whose crontab is to be modified.  If this
option is not used,
.BR crontab
examines "your" crontab, i.e., the crontab of the person executing the
command. If no crontab exists for a particular user, it is created for
them the first time the
.B crontab -u
command is used under their username.
.TP
.B "\-T"
Test the crontab file syntax without installing it. 
Once an issue is found, the validation is interrupted, so this will not return all the existing issues at the same execution.
.TP
.B "\-l"
Displays the current crontab on standard output.
.TP
.B "\-r"
Removes the current crontab.
.TP
.B "\-e"
Edits the current crontab using the editor specified by the
.I VISUAL
or
.I EDITOR
environment variables.  After you exit from the editor, the modified
crontab will be installed automatically.
.TP
.B "\-i"
This option modifies the
.B "\-r"
option to prompt the user for a 'y/Y' response before actually removing
the crontab.
.TP
.B "\-s"
Appends the current SELinux security context string as an MLS_LEVEL
setting to the crontab file before editing / replacement occurs - see the
documentation of MLS_LEVEL in
.BR crontab (5).
.TP
.B "\-n"
This option is relevant only if
.BR cron (8)
was started with the
.B \-c
option, to enable clustering support.  It is used to set the host in the
cluster which should run the jobs specified in the crontab files in the
.I /var/spool/cron
directory.  If a hostname is supplied, the host whose hostname returned
by
.BR gethostname (2)
matches the supplied hostname, will be selected to run the selected cron jobs subsequently.  If there
is no host in the cluster matching the supplied hostname, or you explicitly specify
an empty hostname, then the selected jobs will not be run at all.  If the hostname
is omitted, the name of the local host returned by
.BR gethostname (2)
is used.  Using this option has no effect on the
.I /etc/crontab
file and the files in the
.I /etc/cron.d
directory, which are always run, and considered host-specific.  For more
information on clustering support, see
.BR cron (8).
.TP
.B "\-c"
This option is only relevant if
.BR cron (8)
was started with the
.B \-c
option, to enable clustering support.  It is used to query which host in
the cluster is currently set to run the jobs specified in the crontab
files in the directory
.I /var/spool/cron
, as set using the
.B \-n
option.
.TP
.B "\-V"
Print version and exit.
.SH CAVEATS
The files
.I cron.allow
and
.I cron.deny
cannot be used to restrict the execution of cron jobs; they only restrict the
use of
.BR crontab .
In particular, restricting access to
.BR crontab
has no effect on an existing
.I crontab
of a user. Its jobs will continue to be executed until the crontab is removed.
.PP
The files
.I cron.allow
and
.I cron.deny
must be readable by the user invoking
.BR crontab .
If this is not the case, then they are treated as non-existent.
.SH "SEE ALSO"
.BR crontab (5),
.BR cron (8)
.SH FILES
.nf
/etc/cron.allow
/etc/cron.deny
.fi
.SH STANDARDS
The
.I crontab
command conforms to IEEE Std1003.2-1992 (``POSIX'') with one exception:
For replacing the current crontab with data from standard input the
.B \-
has to be specified on the command line if the standard input is a TTY.
This new command syntax differs from previous versions of Vixie Cron,
as well as from the classic SVR3 syntax.
.SH DIAGNOSTICS
An informative usage message appears if you run a crontab with a faulty
command defined in it.
.SH AUTHOR
.MT vixie@isc.org
Paul Vixie
.ME
.br
.MT colin@colin-dean.org
Colin Dean
.ME