From owner-svn-doc-all@FreeBSD.ORG Mon May 5 15:48:08 2014 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 3D23D7B0; Mon, 5 May 2014 15:48:08 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 291F11B6F; Mon, 5 May 2014 15:48:08 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s45Fm80J061052; Mon, 5 May 2014 15:48:08 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s45Fm8P4061050; Mon, 5 May 2014 15:48:08 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201405051548.s45Fm8P4061050@svn.freebsd.org> From: Dru Lavigne Date: Mon, 5 May 2014 15:48:08 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44761 - head/en_US.ISO8859-1/books/handbook/config X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 05 May 2014 15:48:08 -0000 Author: dru Date: Mon May 5 15:48:07 2014 New Revision: 44761 URL: http://svnweb.freebsd.org/changeset/doc/44761 Log: Editorial review of cron section. This probably belongs in Basics chapter. Modified: head/en_US.ISO8859-1/books/handbook/config/chapter.xml Modified: head/en_US.ISO8859-1/books/handbook/config/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/handbook/config/chapter.xml Mon May 5 13:22:25 2014 (r44760) +++ head/en_US.ISO8859-1/books/handbook/config/chapter.xml Mon May 5 15:48:07 2014 (r44761) @@ -232,53 +232,41 @@ run_rc_command "$1" configuration - One of the most useful utilities in &os; is &man.cron.8;. + One of the most useful utilities in &os; is cron. This utility runs in the background and regularly checks /etc/crontab for tasks to execute and searches /var/cron/tabs for custom - &man.crontab.5; files. These files store information about - specific functions which &man.cron.8; is supposed to perform at - certain times. - - Two different types of configuration files are used by - &man.cron.8;: the system crontab and user - crontabs. These formats only differ in the - sixth field and later. In the system - crontab, &man.cron.8; runs the command as - the user specified in the sixth field. In a user - crontab, all commands run as the user who - created the crontab, so the sixth field is - the last field; this is an important security feature. The - final field is always the command to run. + crontab files. These files are used to schedule + tasks which cron runs at the + specified times. Each entry in a crontab defines a task to run + and is known as a cron job. + + Two different types of configuration files are used: + the system crontab, which should not be modified, and user + crontabs, which can be created and edited as needed. The format + used by these files is documented in &man.crontab.5;. The + format of the system crontab, /etc/crontab + includes a who column which does not exist in + user crontabs. In the system crontab, + cron runs the command as + the user specified in this column. In a user + crontab, all commands run as the user who + created the crontab. + + User crontabs allow + individual users to schedule their own tasks. The root user + can also have a user crontab which can be + used to schedule tasks that do not exist in the system + crontab. - - User crontabs allow individual users to schedule tasks - without the need for - root privileges. - Commands in a user's crontab run with the permissions of the - user who owns the crontab. - - The root user - can have a user crontab just like any - other user. The - root user - crontab is separate from the system - crontab, - /etc/crontab. Because the system - crontab invokes the specified commands as - root, there is - usually no need to create a user crontab - for root. - - - Here is a sample entry from + Here is a sample entry from the system crontab, /etc/crontab: # /etc/crontab - root's crontab for FreeBSD # # $FreeBSD$ # -# SHELL=/bin/sh PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin # @@ -288,7 +276,7 @@ PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin - Like most &os; configuration files, lines that begin + Lines that begin with the # character are comments. A comment can be placed in the file as a reminder of what and why a desired action is performed. Comments cannot be on @@ -302,91 +290,101 @@ PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin define any environment settings. In this example, it is used to define the SHELL and PATH. If the SHELL is - omitted, &man.cron.8; will use the default of &man.sh.1;. - If the PATH is omitted, no default will be - used and file locations will need to be absolute. + omitted, cron will use the default Bourne shell. + If the PATH is omitted, the full path must be given to the + command or script to run. - This line defines a total of seven fields: + This line defines the seven fields used in a system crontab: minute, hour, mday, month, wday, who, and command. - These are almost all self explanatory. - minute is the time in minutes when the - specified command will be run. hour is - the hour when the specified command will be run. - mday stands for day of the month and - month designates the month. The - wday option stands for day of the week. + The + minute field is the time in minutes when the + specified command will be run, the hour is + the hour when the specified command will be run, the + mday is the day of the month, + month is the month, and + wday is the day of the week. These fields must be numeric values, representing the twenty-four hour clock, or a *, representing all values for that field. The who field only exists in the system - crontab. This field specifies which user the command + crontab and specifies which user the command should be run as. The last field is the command to be executed. - This last line defines the values discussed above. - This example has a */5 listing,followed - by several more * characters. These - * characters mean - first-last, and can be interpreted as - every time. In this example, - &man.atrun.8; is invoked by + This entry defines the values for this cron job. + The */5, followed + by several more * characters, specifies that + /usr/libexec/atrun is invoked by root every five - minutes, regardless of the day or month. + minutes of every hour, of every day and day of the week, of + every month. - Commands can have any number of flags passed to them; - however, commands which extend to multiple lines need to be + Commands can include any number of switches. + However, commands which extend to multiple lines need to be broken with the backslash \ continuation character. - This is the basic setup for every &man.crontab.5;. - However, field number six, which specifies the username, only - exists in the system &man.crontab.5;. This field should be - omitted for individual user &man.crontab.5; files. - - Installing a Crontab + Creating a User Crontab - - Do not use the procedure described here to edit and - install the system crontab, - /etc/crontab. Instead, use an editor - and &man.cron.8; will notice that the file has changed and - immediately begin using the updated version. See this - FAQ entry for more information. - + To create a user crontab, invoke + crontab in editor mode: - To install a freshly written user &man.crontab.5;, use - an editor to create and save a file in the proper format. - Then, specify the file name with &man.crontab.1;: - - &prompt.user; crontab crontab-file - - In this example, crontab-file is the - filename of a &man.crontab.5; that was previously - created. - - To list installed &man.crontab.5; files, pass - to &man.crontab.1;. - - Users who wish to begin their own - crontab file from scratch, without the - use of a template, can use crontab -e. - This will invoke the default editor with an empty file. When - this file is saved, it will be automatically installed by - &man.crontab.1;. + &prompt.user; crontab -e - In order to remove a user &man.crontab.5; completely, - use crontab -r. + This will open the user's crontab using the default text + editor. The first time a user runs this command, it will open + an empty file. Once a user creates a crontab, this command + will open that file for editing. + + It is useful to add these lines to the top of the crontab + file in order to set the environment variables and to remember + the meanings of the fields in the crontab: + + SHELL=/bin/sh +PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin +# Order of crontab fields +# minute hour mday month wday command + + Then add a line for each command or script to run, + specifying the time to run the command. This example runs the + specified custom Bourne shell script every day at two in the + afternoon. Since the path to the script is not specified in + PATH, the full path to the script is + given: + + 0 14 * * * /usr/home/dru/bin/mycustomscript.sh + + + Before using a custom script, make sure it is executable + and test that it works as intended from the command line. + This is especially important if the script includes any + commands that deletes files using wildcards. + + + When finished editing the crontab, save the file. It + will automatically be installed and + cron will read the crontab and run + its cron jobs at their specified times. To list the cron jobs + in a crontab, use this command: + + &prompt.user; crontab -l +0 14 * * * /usr/home/dru/bin/mycustomscript.sh + + To remove all of the cron jobs in a user crontab: + + &prompt.user; crontab -l +remove crontab for dru? y +