cronie/man/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 "22 September 2010"
.SH NAME
crontab \- maintains crontab files for individual users
.SH SYNOPSIS
.B crontab
.RB [ -u
.IR user ] " file"
.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
.SH DESCRIPTION
.I Crontab
is the program used to install, remove or list the 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 (1)
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
Running cron jobs 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 cron
If the
.I cron.allow
file does not exist but the
.I cron.deny
file does exist, then a user must \fInot\fR be listed in the
.I cron.deny
file in order to use cron.  If neither of these files exists,
only the super user is allowed to use cron.
Another way to restrict access to cron is to use PAM authentication to set up users,
which are allowed or disallowed to use 
.I 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
.SH "OPTIONS"
.TP
.B "\-u"
Appends the name of the user whose crontab is to be modified.  If this option 
is not used,
.I crontab
examines "your" crontab, i.e., the crontab of the person executing the
command.  Note that
.BR su (8)
may confuse
.IR crontab ,
thus, when executing commands under
.BR su (8)
you should always use the
.B -u
option. If no crontab exists for a particular user, it is created for him the first time the 
.B crontab -u
command is used under his username.
.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 \s-1VISUAL\s+1 or \s-1EDITOR\s+1 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 \fB-c\fP 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 \fB-c\fP 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 \fB-n\fP option.
.SH "SEE ALSO"
.BR crontab (5), 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'').  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
.nf
Paul Vixie <vixie@isc.org>
Colin Dean <colin@colin-dean.org>