Practical rc.d scripting in BSD

The historical BSD had a monolithic startup script, /etc/rc. It was invoked by init(8) at system boot time and performed all userland tasks required for multi-user operation: checking and mounting file systems, setting up the network, starting daemons, and so on. The precise list of tasks was not the same in every system; admins needed to customize it. With few exceptions, /etc/rc had to be modified, and true hackers liked it.

The real problem with the monolithic approach was that it provided no control over the individual components started from /etc/rc. For instance, /etc/rc could not restart a single daemon. The system admin had to find the daemon process by hand, kill it, wait until it actually exited, then browse through /etc/rc for the flags, and finally type the full command line to start the daemon again. The task would become even more difficult and prone to errors if the service to restart consisted of more than one daemon or demanded additional actions. In a few words, the single script failed to fulfil what scripts are for: to make the system admin's life easier.

Later there was an attempt to split out some parts of /etc/rc for the sake of starting the most important subsystems separately. The notorious example was /etc/netstart to bring up networking. It did allow for accessing the network from single-user mode, but it did not integrate well into the automatic startup process because parts of its code needed to interleave with actions essentially unrelated to networking. That was why /etc/netstart mutated into /etc/rc.network. The latter was no longer an ordinary script; it comprised of large, tangled sh(1) functions called from /etc/rc at different stages of system startup. However, as the startup tasks grew diverse and sophisticated, the “quasi-modular” approach became even more of a drag than the monolithic /etc/rc had been.

Without a clean and well-designed framework, the startup scripts had to bend over backwards to satisfy the needs of rapidly developing BSD-based operating systems. It became obvious at last that more steps are necessary on the way to a fine-grained and extensible rc system. Thus BSD rc.d was born. Its acknowledged fathers were Luke Mewburn and the NetBSD community. Later it was imported into FreeBSD. Its name refers to the location of system scripts for individual services, which is in /etc/rc.d. Soon we will learn about more components of the rc.d system and see how the individual scripts are invoked.

The basic ideas behind BSD rc.d are fine modularity and code reuse. Fine modularity means that each basic “service” such as a system daemon or primitive startup task gets its own sh(1) script able to start the service, stop it, reload it, check its status. A particular action is chosen by the command-line argument to the script. The /etc/rc script still drives system startup, but now it merely invokes the smaller scripts one by one with the start argument. It is easy to perform shutdown tasks as well by running the same set of scripts with the stop argument, which is done by /etc/rc.shutdown. Note how closely this follows the Unix way of having a set of small specialized tools, each fulfilling its task as well as possible. Code reuse means that common operations are implemented as sh(1) functions and collected in /etc/rc.subr. Now a typical script can be just a few lines' worth of sh(1) code. Finally, an important part of the rc.d framework is rcorder(8), which helps /etc/rc to run the small scripts orderly with respect to dependencies between them. It can help /etc/rc.shutdown, too, because the proper order for the shutdown sequence is opposite to that of startup.

The BSD rc.d design is described in the original article by Luke Mewburn, and the rc.d components are documented in great detail in the respective manual pages. However, it might not appear obvious to an rc.d newbie how to tie the numerous bits and pieces together in order to create a well-styled script for a particular task. Therefore this article will try a different approach to describe rc.d. It will show which features should be used in a number of typical cases, and why. Note that this is not a how-to document because our aim is not at giving ready-made recipes, but at showing a few easy entrances into the rc.d realm. Neither is this article a replacement for the relevant manual pages. Do not hesitate to refer to them for more formal and complete documentation while reading this article.

There are prerequisites to understanding this article. First of all, you should be familiar with the sh(1) scripting language in order to master rc.d. In addition, you should know how the system performs userland startup and shutdown tasks, which is described in rc(8).

This article focuses on the FreeBSD branch of rc.d. Nevertheless, it may be useful to NetBSD developers, too, because the two branches of BSD rc.d not only share the same design but also stay similar in their aspects visible to script authors.

A little consideration before starting $EDITOR will not hurt. In order to write a well-tempered rc.d script for a system service, we should be able to answer the following questions first:

From the examples that follow we will see why it is important to know the answers to these questions.

The following script just emits a message each time the system boots up:

#!/bin/sh

. /etc/rc.subr

name="dummy"
start_cmd="${name}_start"
stop_cmd=":"

dummy_start()
{
	echo "Nothing started."
}

load_rc_config $name
run_rc_command "$1"

Things to note are:

# /etc/rc.d/dummy start

Now let us add some controls to our dummy script. As you may know, rc.d scripts are controlled with rc.conf(5). Fortunately, rc.subr(8) hides all the complications from us. The following script uses rc.conf(5) via rc.subr(8) to see whether it is enabled in the first place, and to fetch a message to show at boot time. These two tasks in fact are independent. On the one hand, an rc.d script can just support enabling and disabling its service. On the other hand, a mandatory rc.d script can have configuration variables. We will do both things in the same script though:

#!/bin/sh

. /etc/rc.subr

name=dummy
rcvar=dummy_enable

start_cmd="${name}_start"
stop_cmd=":"

load_rc_config $name
: ${dummy_enable:=no} 
: ${dummy_msg="Nothing started."}

dummy_start()
{
	echo "$dummy_msg"
}

run_rc_command "$1"

What changed in this example?

# /etc/rc.d/dummy onestart

start_cmd="echo \"$dummy_msg\""

We said earlier that rc.subr(8) could provide default methods. Obviously, such defaults cannot be too general. They are suited for the common case of starting and shutting down a simple daemon program. Let us assume now that we need to write an rc.d script for such a daemon called mumbled. Here it is:

#!/bin/sh

. /etc/rc.subr

name=mumbled
rcvar=mumbled_enable

command="/usr/sbin/${name}"

load_rc_config $name
run_rc_command "$1"

Pleasingly simple, isn't it? Let us examine our little script. The only new thing to note is as follows:

Let us add some meat onto the bones of the previous script and make it more complex and featureful. The default methods can do a good job for us, but we may need some of their aspects tweaked. Now we will learn how to tune the default methods to our needs.

#!/bin/sh

. /etc/rc.subr

name=mumbled
rcvar=mumbled_enable

command="/usr/sbin/${name}"
command_args="mock arguments > /dev/null 2>&1"

pidfile="/var/run/${name}.pid"

required_files="/etc/${name}.conf /usr/share/misc/${name}.rules"

sig_reload="USR1"

start_precmd="${name}_prestart"
stop_postcmd="echo Bye-bye"

extra_commands="reload plugh xyzzy"

plugh_cmd="mumbled_plugh"
xyzzy_cmd="echo 'Nothing happens.'"

mumbled_prestart()
{
	if checkyesno mumbled_smart; then
		rc_flags="-o smart ${rc_flags}"
	fi
	case "$mumbled_mode" in
	foo)
		rc_flags="-frotz ${rc_flags}"
		;;
	bar)
		rc_flags="-baz ${rc_flags}"
		;;
	*)
		warn "Invalid value for mumbled_mode"
		return 1
		;;
	esac
	run_rc_command xyzzy
	return 0
}

mumbled_plugh()
{
	echo 'A hollow voice says "plugh".'
}

load_rc_config $name
run_rc_command "$1"

# /etc/rc.d/mumbled
Usage: /etc/rc.d/mumbled [fast|force|one](start|stop|restart|rcvar|reload|plugh|xyzzy|status|poll)

if checkyesno mumbled_enable; then
        foo
fi

if checkyesno "${mumbled_enable}"; then
        foo
fi

After a script has been written, it needs to be integrated into rc.d. The crucial step is to install the script in /etc/rc.d (for the base system) or /usr/local/etc/rc.d (for ports). Both <bsd.prog.mk> and <bsd.port.mk> provide convenient hooks for that, and usually you do not have to worry about the proper ownership and mode. System scripts should be installed from src/etc/rc.d through the Makefile found there. Port scripts can be installed using USE_RC_SUBR as described in the Porter's Handbook.

However, we should consider beforehand the place of our script in the system startup sequence. The service handled by our script is likely to depend on other services. For instance, a network daemon cannot function without the network interfaces and routing up and running. Even if a service seems to demand nothing, it can hardly start before the basic filesystems have been checked and mounted.

We mentioned rcorder(8) already. Now it is time to have a close look at it. In a nutshell, rcorder(8) takes a set of files, examines their contents, and prints a dependency-ordered list of files from the set to stdout. The point is to keep dependency information inside the files so that each file can speak for itself only. A file can specify the following information:

It is no surprise that rcorder(8) can handle only text files with a syntax close to that of sh(1). That is, special lines understood by rcorder(8) look like sh(1) comments. The syntax of such special lines is rather rigid to simplify their processing. See rcorder(8) for details.

Besides using rcorder(8) special lines, a script can insist on its dependency upon another service by just starting it forcibly. This can be needed when the other service is optional and will not start by itself because the system admin has disabled it mistakenly in rc.conf(5).

With this general knowledge in mind, let us consider the simple daemon script enhanced with dependency stuff:

#!/bin/sh

# PROVIDE: mumbled oldmumble 
# REQUIRE: DAEMON cleanvar frotz
# BEFORE:  LOGIN
# KEYWORD: nojail shutdown

. /etc/rc.subr

name=mumbled
rcvar=mumbled_enable

command="/usr/sbin/${name}"
start_precmd="${name}_prestart"

mumbled_prestart()
{
	if ! checkyesno frotz_enable && \
	    ! /etc/rc.d/frotz forcestatus 1>/dev/null 2>&1; then
		force_depend frotz || return 1
	fi
	return 0
}

load_rc_config $name
run_rc_command "$1"

As before, detailed analysis follows:

When invoked during startup or shutdown, an rc.d script is supposed to act on the entire subsystem it is responsible for. E.g., /etc/rc.d/netif should start or stop all network interfaces described by rc.conf(5). Either task can be uniquely indicated by a single command argument such as start or stop. Between startup and shutdown, rc.d scripts help the admin to control the running system, and it is when the need for more flexibility and precision arises. For instance, the admin may want to add the settings of a new network interface to rc.conf(5) and then to start it without interfering with the operation of the existing interfaces. Next time the admin may need to shut down a single network interface. In the spirit of the command line, the respective rc.d script calls for an extra argument, the interface name.

Fortunately, rc.subr(8) allows for passing any number of arguments to script's methods (within the system limits). Due to that, the changes in the script itself can be minimal.

How can rc.subr(8) gain access to the extra command-line arguments. Should it just grab them directly? Not by any means. Firstly, an sh(1) function has no access to the positional parameters of its caller, but rc.subr(8) is just a sack of such functions. Secondly, the good manner of rc.d dictates that it is for the main script to decide which arguments are to be passed to its methods.

So the approach adopted by rc.subr(8) is as follows: run_rc_command passes on all its arguments but the first one to the respective method verbatim. The first, omitted, argument is the name of the method itself: start, stop, etc. It will be shifted out by run_rc_command, so what is $2 in the original command line will be presented as $1 to the method, and so on.

To illustrate this opportunity, let us modify the primitive dummy script so that its messages depend on the additional arguments supplied. Here we go:

#!/bin/sh

. /etc/rc.subr

name="dummy"
start_cmd="${name}_start"
stop_cmd=":"
kiss_cmd="${name}_kiss"
extra_commands="kiss"

dummy_start()
{
        if [ $# -gt 0 ]; then
                echo "Greeting message: $*"
        else
                echo "Nothing started."
        fi
}

dummy_kiss()
{
        echo -n "A ghost gives you a kiss"
        if [ $# -gt 0 ]; then
                echo -n " and whispers: $*"
        fi
        case "$*" in
        *[.!?])
                echo
                ;;
        *)
                echo .
                ;;
        esac
}

load_rc_config $name
run_rc_command "$@"

What essential changes can we notice in the script?

# /etc/rc.d/dummy start
Nothing started.
# /etc/rc.d/dummy start Hello world!
Greeting message: Hello world!

# /etc/rc.d/dummy kiss
A ghost gives you a kiss.
# /etc/rc.d/dummy kiss Once I was Etaoin Shrdlu...
A ghost gives you a kiss and whispers: Once I was Etaoin Shrdlu...

The original article by Luke Mewburn offers a general overview of rc.d and detailed rationale for its design decisions. It provides insight on the whole rc.d framework and its place in a modern BSD operating system.

The manual pages rc(8), rc.subr(8), and rcorder(8) document the rc.d components in great detail. You cannot fully use the rc.d power without studying the manual pages and referring to them while writing your own scripts.

The major source of working, real-life examples is /etc/rc.d in a live system. Its contents are easy and pleasant to read because most rough corners are hidden deep in rc.subr(8). Keep in mind though that the /etc/rc.d scripts were not written by angels, so they might suffer from bugs and suboptimal design decisions. Now you can improve them!