rc(8)

NAME

rc - command scripts for auto-reboot and daemon startup

SYNOPSIS

rc
rc.conf
rc.conf.local
rc.d/
rc.firewall
rc.local
rc.shutdown
rc.subr

DESCRIPTION

The rc utility is the command script which controls the au
tomatic boot
process after being called by init(8). The rc.local script
contains commands which are pertinent only to a specific site. Typical
ly, the
/usr/local/etc/rc.d/ mechanism is used instead of rc.local
these days but
if you want to use rc.local, it is still supported. In this
case, it
should source /etc/rc.conf and contain additional custom
startup code for
your system. The best way to handle rc.local, however, is
to separate it
out into rc.d/ style scripts and place them under
/usr/local/etc/rc.d/.
The rc.conf file contains the global system configuration
information
referenced by the startup scripts, while rc.conf.local con
tains the local
system configuration. See rc.conf(5) for more information.
The rc.d/ directories contain scripts which will be automat
ically executed at boot time and shutdown time.
Operation of rc

1. If autobooting, set autoboot=yes and enable a flag
(rc_fast=yes),
which prevents the rc.d/ scripts from performing the
check for
already running processes (thus speeding up the boot
process). This
rc_fast=yes speedup will not occur when rc is started
up after exiting the single-user shell.
2. Determine whether the system is booting diskless, and
if so run the
/etc/rc.initdiskless script.
3. Source /etc/rc.subr to load various rc.subr(8) shell
functions to
use.
4. Load the configuration files.
5. Determine if booting in a jail, and add ``nojail'' to
the list of
KEYWORDS to skip in rcorder(8).
6. Invoke rcorder(8) to order the files in /etc/rc.d/ that
do not have
a ``nostart'' KEYWORD (refer to rcorder(8)'s -s flag).
7. Call each script in turn using run_rc_script() (from
rc.subr(8)),
which sets $1 to ``start'', and sources the script in a
subshell.
If the script has a .sh suffix then it is sourced di
rectly into the
current shell. Stop processing when the script that is
the value of
the $early_late_divider has been run.
8. Re-run rcorder(8), this time including the scripts in
the
$local_startup directories. Ignore everything up to
the
$early_late_divider, then start executing the scripts
as described
above.
Operation of rc.shutdown

1. Source /etc/rc.subr to load various rc.subr(8) shell
functions to
use.
2. Load the configuration files.
3. Invoke rcorder(8) to order the files in /etc/rc.d/ and
the
$local_startup directories that have a ``shutdown''
KEYWORD (refer
to rcorder(8)'s -k flag), reverse that order, and as
sign the result
to a variable.
4. Call each script in turn using run_rc_script() (from
rc.subr(8)),
which sets $1 to ``stop'', and sources the script in a
subshell. If
the script has a .sh suffix then it is sourced directly
into the
current shell.
Contents of rc.d/
rc.d/ is located in /etc/rc.d/. The following file naming
conventions
are currently used in rc.d/:

ALLUPPERCASE Scripts that are ``placeholders'' to
ensure thatcertain operations are performed be
fore others.
In order of startup, these are:
NETWORKING Ensure basic network
services are
running, including
general network configuration.
SERVERS Ensure basic ser
vices exist for
services that start
early (such
as named), because
they are
required by DAEMON
below.
DAEMON Check-point before
all general
purpose daemons such
as lpd and
ntpd.
LOGIN Check-point before
user login
services (inetd and
sshd), as
well as services
which might run
commands as users
(cron and
sendmail).
foo.sh Scripts that are to be sourced into
the current
shell rather than a subshell have a
.sh suffix.
Extreme care must be taken in using
this, as the
startup sequence will terminate if
the script
does.
bar Scripts that are sourced in a sub
shell. These
can stop the boot if necessary with
the following
shell commands:

if [ "$autoboot" = yes ]; then
kill -TERM $$
fi
exit 1
Note that this should be used ex
tremely sparingly!
Each script should contain rcorder(8) keywords, especially
an appropriate
``PROVIDE'' entry, and if necessary ``REQUIRE'' and ``BE
FORE'' keywords.
Each script is expected to support at least the following
arguments,
which are automatically supported if it uses the
run_rc_command() function:

start Start the service. This should check
that the service
is to be started as specified by
rc.conf(5). Also
checks if the service is already running
and refuses
to start if it is. This latter check is
not performed
by standard FreeBSD scripts if the system
is starting
directly to multi-user mode, to speed up
the boot process. If forcestart is given, ignore the
rc.conf(5)
check and start anyway.
stop If the service is to be started as speci
fied by
rc.conf(5), stop the service. This
should check that
the service is running and complain if it
is not. If
forcestop is given, ignore the rc.conf(5)
check and
attempt to stop.
restart Perform a stop then a start.
status If the script starts a process (rather
than performing
a one-off operation), show the status of
the process.
Otherwise it is not necessary to support
this argument. Defaults to displaying the process
ID of the
program (if running).
poll If the script starts a process (rather
than performinga one-off operation), wait for the com
mand to exit.
Otherwise it is not necessary to support
this argument.
rcvar Display which rc.conf(5) variables are
used to control
the startup of the service (if any).
If a script must implement additional commands it can list
them in the
extra_commands variable, and define their actions in a vari
able constructed from the command name (see the EXAMPLES section).
The following key points apply to old-style scripts in
/usr/local/etc/rc.d/:
+o Scripts are only executed if their basename(1) matches
the shell
globbing pattern *.sh, and they are executable. Any
other files or
directories present within the directory are silently
ignored.
+o When a script is executed at boot time, it is passed the
string
``start'' as its first and only argument. At shutdown
time, it is
passed the string ``stop'' as its first and only argu
ment. All rc.d/
scripts are expected to handle these arguments appropri
ately. If no
action needs to be taken at a given time (either boot
time or shutdown time), the script should exit successfully and
without producing
an error message.
+o The scripts within each directory are executed in lexi
cographical
order. If a specific order is required, numbers may be
used as a
prefix to the existing filenames, so for example 100.foo
would be
executed before 200.bar; without the numeric prefixes
the opposite
would be true.
+o The output from each script is traditionally a space
character, fol
lowed by the name of the software package being started
or shut down,
without a trailing newline character (see the EXAMPLES
section).

SCRIPTS OF INTEREST

When an automatic reboot is in progress, rc is invoked with
the argument
autoboot. One of the scripts run from /etc/rc.d/ is
/etc/rc.d/fsck.
This script runs fsck(8) with option -p and -F to ``preen''
all the disks
of minor inconsistencies resulting from the last system
shutdown. If
this fails, then checks/repairs of serious inconsistencies
caused by
hardware or software failure will be performed in the back
ground at the
end of the booting process. If autoboot is not set, when
going from single-user to multi-user mode for example, the script does not
do anything.
The rc.early script is run very early in the startup pro
cess, immediately
before the file system check. The rc.early script is depre
cated. Any
commands in this file should be separated out into rc.d/
style scripts
and integrated into the rc system.
The /etc/rc.d/local script can execute scripts from multiple
rc.d/ directories. The default locations are /usr/local/etc/rc.d/ and /usr/X11R6/etc/rc.d/, but these may be overridden with the
local_startup
rc.conf(5) variable.
The /etc/rc.d/serial script is used to set any special con
figurations for
serial devices.
The rc.firewall script is used to configure rules for the
kernel based
firewall service. It has several possible options:

open will allow anyone in
client will try to protect just this machine
simple will try to protect a whole network
closed totally disables IP services except via
lo0 interface
UNKNOWN disables the loading of firewall rules filename will load the rules in the given file
name (full path
required).
The /etc/rc.d/atm* scripts are used to configure ATM network
interfaces.
The interfaces are configured in three passes. The first
pass performs
the initial interface configuration. The second pass com
pletes the
interface configuration and defines PVCs and permanent AT
MARP entries.
The third pass starts any ATM daemons.
Most daemons, including network related daemons, have their
own script in
/etc/rc.d/, which can be used to start, stop, and check the
status of the
service.
Any architecture specific scripts, such as /etc/rc.d/apm for
example,
specifically check that they are on that architecture before
starting the
daemon.
Following tradition, all startup files reside in /etc.

FILES

/etc/rc
/etc/rc.conf
/etc/rc.conf.local
/etc/rc.d/
/etc/rc.firewall
/etc/rc.local
/etc/rc.shutdown
/etc/rc.subr
/var/run/dmesg.boot dmesg(8) results soon af
ter the rc pro
cess begins. Useful when
dmesg(8)
buffer in the kernel no
longer has this
information.

EXAMPLES

The following is a minimal rc.d/ style script. Most scripts
require little more than the following.

#!/bin/sh
#
# PROVIDE: foo
# REQUIRE: bar_service_required_to_precede_foo
. /etc/rc.subr
name="foo"
rcvar=`set_rcvar`
command="/usr/local/bin/foo"
load_rc_config $name
run_rc_command "$1"
Certain scripts may want to provide enhanced functionality.
The user may
access this functionality through additional commands. The
script may
list and define as many commands at it needs.

#!/bin/sh
#
# PROVIDE: foo
# REQUIRE: bar_service_required_to_precede_foo
# BEFORE: baz_service_requiring_foo_to_precede_it
. /etc/rc.subr
name="foo"
rcvar=`set_rcvar`
command="/usr/local/bin/foo"
extra_commands="nop hello"
hello_cmd="echo Hello World."
nop_cmd="do_nop"
do_nop()
{
echo "I do nothing."
}
load_rc_config $name
run_rc_command "$1"
As all processes are killed by init(8) at shutdown, the ex
plicit kill(1)
is unnecessary, but is often included.

SEE ALSO

kill(1), rc.conf(5), init(8), rcorder(8), rc.subr(8), re
boot(8),
savecore(8)

HISTORY

The rc utility appeared in 4.0BSD.
BSD December 19, 2005
Copyright © 2010-2024 Platon Technologies, s.r.o.           Home | Man pages | tLDP | Documents | Utilities | About
Design by styleshout