rc.subr(8)

NAME

rc.subr - functions used by system shell scripts

SYNOPSIS

. /etc/rc.subr
backup_file action file current backup
checkyesno var
check_pidfile pidfile procname [interpreter]
check_process procname [interpreter]
debug message
err exitval message
force_depend name
info message
load_rc_config command
mount_critical_filesystems type
rc_usage command ...
reverse_list item ...
run_rc_command argument
run_rc_script file argument
set_rcvar [base]
wait_for_pids [pid ...]
warn message

DESCRIPTION

The rc.subr script contains commonly used shell script func

tions and variable definitions which are used by various scripts such

as rc(8). Scripts required by ports in /usr/local/etc/rc.d will also

eventually be rewritten to make use of it.

The rc.subr functions were mostly imported from NetBSD and

it is intended that they remain synced between the two projects. With that

in mind there are several variable definitions that can help in this

regard. They are:

OSTYPE

Its value will be either "FreeBSD" or "NetBSD", de

pending on which

OS it is running on.

SYSCTL

The path to the sysctl(8) command.

SYSCTL_N

The path and argument list to display only the

sysctl(8) values

instead of a name=value pair.

SYSCTL_W

The path and argument to write or modify sysctl(8)

values.

The rc.subr functions are accessed by sourcing /etc/rc.subr

into the current shell.

The following shell functions are available:

backup_file action file current backup

Make a backup copy of file into current. If the

rc.conf(5) variable backup_uses_rcs is ``YES'', use rcs(1) to archive

the previous

version of current, otherwise save the previous ver

sion of current

as backup.

The action argument may be one of the following:

add file is now being backed up by or possibly

re-entered

into this backup mechanism. current is

created, and if

necessary, the rcs(1) files are created as

well.

update file has changed and needs to be backed

up. If current

exists, it is copied to backup or checked

into rcs(1)

(if the repository file is old), and then

file is

copied to current.

remove file is no longer being tracked by this

backup mecha

nism. If rcs(1) is being used, an empty

file is

checked in and current is removed, other

wise current is

moved to backup.

checkyesno var

Return 0 if var is defined to ``YES'', ``TRUE'',

``ON'', or `1'.

Return 1 if var is defined to ``NO'', ``FALSE'',

``OFF'', or `0'.

Otherwise, warn that var is not set correctly. The

values are case

insensitive.

check_pidfile pidfile procname [interpreter]

Parses the first word of the first line of pidfile for

a PID, and

ensures that the process with that PID is running and

its first

argument matches procname. Prints the matching PID if

successful,

otherwise nothing. If interpreter is provided, parse

the first

line of procname, ensure that the line is of the form:

#! interpreter [...]

and use interpreter with its optional arguments and

procname

appended as the process string to search for.

check_process procname [interpreter]

Prints the PIDs of any processes that are running with

a first

argument that matches procname. interpreter is han

dled as per

check_pidfile.

debug message

Display a debugging message to stderr, log it to the

system log

using logger(1), and return to the caller. The error

message consists of the script name (from $0), followed by ``:

DEBUG: '', and

then message. This function is intended to be used by

developers

as an aid to debugging scripts. It can be turned on

or off by the

rc.conf(5) variable rc_debug.

err exitval message

Display an error message to stderr, log it to the sys

tem log using

logger(1), and exit with an exit value of exitval.

The error message consists of the script name (from $0), followed

by ``: ERROR:

'', and then message.

force_depend name

Output an advisory message and force the name service

to start.

The name argument is the basename(1) component of the

path to the

script, usually /etc/rc.d/name. If the script fails

for any reason

it will output a warning and return with a return val

ue of 1. If

it was successful it will return 0.

info message

Display an informational message to stdout, and log it

to the system log using logger(1). The message consists of the

script name

(from $0), followed by ``: INFO: '', and then message.

The display

of this informational output can be turned on or off

by the

rc.conf(5) variable rc_info.

load_rc_config command

Source in the configuration files for command. First,

/etc/rc.conf

is sourced if it has not yet been read in. Then,

/etc/rc.conf.d/command is sourced if it is an existing

file. The

latter may also contain other variable assignments to

override

run_rc_command arguments defined by the calling

script, to provide

an easy mechanism for an administrator to override the

behaviour of

a given rc.d(8) script without requiring the editing

of that

script.

mount_critical_filesystems type

Go through a list of critical file systems, as found

in the

rc.conf(5) variable critical_filesystems_type, mount

ing each one

that is not currently mounted.

rc_usage command ...

Print a usage message for $0, with commands being the

list of valid

arguments prefixed by ``[fast|force|one]''.

reverse_list item ...

Print the list of items in reverse order.

run_rc_command argument

Run the argument method for the current rc.d(8)

script, based on

the settings of various shell variables.

run_rc_command is

extremely flexible, and allows fully functional

rc.d(8) scripts to

be implemented in a small amount of shell code.

argument is searched for in the list of supported com

mands, which

may be one of:

start Start the service. This should

check that the

service is to be started as speci

fied 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.

stop If the service is to be started as

specified by

rc.conf(5), stop the service. This

should check

that the service is running and

complain if it

is not.

restart Perform a stop then a start. De

faults to dis

playing the process ID of the pro

gram (if running).

rcvar Display which rc.conf(5) variables

are used to

control the startup of the service

(if any).

If pidfile or procname is set, also support:

poll Wait for the command to exit.

status Show the status of the process.

Other supported commands are listed in the optional

variable
extra_commands.

argument may have one of the following prefixes which

alters its operation:

fast Skip the check for an existing run

ning process,

and sets rc_fast=YES.

force Skip the checks for rcvar being set

to ``YES'',

and sets rc_force=YES. This ignores argument_precmd returning non-zero,

and ignores

any of the required_* tests failing,

and always

returns a zero exit status.

one Skip the checks for rcvar being set

to ``YES'',

but performs all the other prerequi

site tests.

run_rc_command uses the following shell variables to

control its behaviour. Unless otherwise stated, these are option

al.

name The name of this script. This is

not optional.

rcvar The value of rcvar is checked with

checkyesno

to determine if this method should

be run.

command Full path to the command. Not re

quired if

argument_cmd is defined for each

supported keyword. Can be overridden by

${name}_program.

command_args Optional arguments and/or shell

directives for

command.

command_interpreter

command is started with:

#! command_interpreter [...]

which results in its ps(1) command

being:

command_interpreter [...]

command

so use that string to find the

PID(s) of the

running command rather than

command.

extra_commands

Extra commands/keywords/arguments

supported.

pidfile Path to PID file. Used to deter

mine the PID(s)

of the running command. If

pidfile is set,

use:

check_pidfile $pidfile

$procname

to find the PID. Otherwise, if

command is set,

use:

check_process $procname

to find the PID.

procname Process name to check for. De

faults to the

value of command.

required_dirs

Check for the existence of the

listed directories before running the default

start method.

required_files

Check for the readability of the

listed files

before running the default start

method.

required_vars

Perform checkyesno on each of the

list variables before running the default

start method.

${name}_chdir

Directory to cd to before running

command, if

${name}_chroot is not provided.

${name}_chroot

Directory to chroot(8) to before

running

command. Only supported after

/usr is mounted.

${name}_flags

Arguments to call command with.

This is usually set in rc.conf(5), and not in

the rc.d(8)

script. The environment variable

`flags' can

be used to override this.

${name}_nice nice(1) level to run command as.

Only sup

ported after /usr is mounted.

${name}_program

Full path to the command. Over

rides command if

both are set, but has no effect if

command is

unset. As a rule, command should

be set in the

script while ${name}_program

should be set in

rc.conf(5).

${name}_user User to run command as, using ch

root(8). if

${name}_chroot is set, otherwise

uses su(1).

Only supported after /usr is

mounted.

${name}_group

Group to run the chrooted command

as.

${name}_groups

Comma separated list of supplemen

tary groups to

run the chrooted command with.

argument_cmd Shell commands which override the

default

method for argument.

argument_precmd

Shell commands to run just before

running

argument_cmd or the default method

for

argument. If this returns a non

zero exit

code, the main method is not per

formed. If the

default method is being executed,

this check is

performed after the required_*

checks and process (non-)existence checks.

argument_postcmd

Shell commands to run if running

argument_cmd

or the default method for argument

returned a

zero exit code.

sig_stop Signal to send the processes to

stop in the

default stop method. Defaults to

SIGTERM.

sig_reload Signal to send the processes to

reload in the

default reload method. Defaults

to SIGHUP.

For a given method argument, if argument_cmd is not

defined, then a
default method is provided by run_rc_command:

Argument Default method

start If command is not running and

checkyesno rcvar

succeeds, start command.

stop Determine the PIDs of command with

check_pidfile or check_process (as

appropriate), kill sig_stop those PIDs,

and run

wait_for_pids on those PIDs.

reload Similar to stop, except that it

uses sig_reload

instead, and does not run

wait_for_pids.

Another difference from stop is

that reload is

not provided by default. It can

be enabled via

extra_commands if appropriate:

extra_commands=reload

restart Runs the stop method, then the

start method.

status Show the PID of command, or some

other script

specific status operation.

poll Wait for command to exit.

rcvar Display which rc.conf(5) variable

is used (if

any). This method always works,

even if the

appropriate rc.conf(5) variable is

set to

``NO''.

The following variables are available to the methods

(such as
argument_cmd) as well as after run_rc_command has com

pleted:

rc_arg Argument provided to

run_rc_command, after fast

and force processing has been per

formed.

rc_flags Flags to start the default command

with.

Defaults to ${name}_flags, unless

overridden by

the environment variable `flags'.

This variable may be changed by the

argument_precmd

method.

rc_pid PID of command (if appropriate).

rc_fast Not empty if ``fast'' prefix was

used.

rc_force Not empty if ``force'' prefix was

used.

run_rc_script file argument

Start the script file with an argument of argument,

and handle the

return value from the script.

Various shell variables are unset before file is

started:

name, command, command_args,

command_interpreter,

extra_commands, pidfile, rcvar, required_dirs, required_files, required_vars, argument_cmd,

argument_precmd.

argument_postcmd.

The startup behaviour of file depends upon the follow

ing checks:

1. If file ends in .sh, it is sourced into the cur

rent shell.

2. If file appears to be a backup or scratch file

(e.g., with a suffix of ~, #, .OLD, or .orig), ignore it.

3. If file is not executable, ignore it.

4. If the rc.conf(5) variable rc_fast_and_loose is

empty, source file in a sub shell, otherwise source file into

the current shell.

set_rcvar [base]
Set the variable name required to start a service. In

FreeBSD a daemon is usually controlled by an rc.conf(5) variable

consisting of a daemon's name postfixed by the string ``_en

able''. This is not the case in NetBSD. When the following line is

included in a script:

rcvar=`set_rcvar`

this function will use the value of the $name vari

able, which should be defined by the calling script, to construct

the appropriate rc.conf(5) knob. If the base argument is set it

will use base instead of $name.

wait_for_pids [pid ...]
Wait until all of the provided pids do not exist any

more, printing the list of outstanding pids every two seconds.

warn message
Display a warning message to stderr and log it to the

system log using logger(1). The warning message consists of the

script name (from $0), followed by ``: WARNING: '', and then

message.

FILES

/etc/rc.subr The rc.subr file resides in /etc.

HISTORY

The rc.subr script appeared in NetBSD 1.3. The rc.d(8) sup
port functions
appeared in NetBSD 1.5. The rc.subr script first appeared
in FreeBSD 5.0.
BSD February 22, 2006

docs.sk

komplexný repozitár dokumentácie