Source string Read only

(itstool) path: listitem/para
37/370
Context English State
NetBSD is a registered trademark of the NetBSD Foundation.
Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this document, and the FreeBSD Project was aware of the trademark claim, the designations have been followed by the <quote>™</quote> or the <quote>®</quote> symbol.
$FreeBSD: head/en_US.ISO8859-1/articles/rc-scripting/article.xml 44709 2014-04-29 21:39:27Z wblock $
Beginners may find it difficult to relate the facts from the formal documentation on the BSD <filename>rc.d</filename> framework with the practical tasks of <filename>rc.d</filename> scripting. In this article, we consider a few typical cases of increasing complexity, show <filename>rc.d</filename> features suited for each case, and discuss how they work. Such an examination should provide reference points for further study of the design and efficient application of <filename>rc.d</filename>.
Introduction
The historical BSD had a monolithic startup script, <filename>/etc/rc</filename>. It was invoked by <citerefentry><refentrytitle>init</refentrytitle><manvolnum>8</manvolnum></citerefentry> 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, <filename>/etc/rc</filename> 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 <filename>/etc/rc</filename>. For instance, <filename>/etc/rc</filename> 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 <filename>/etc/rc</filename> 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 <filename>/etc/rc</filename> for the sake of starting the most important subsystems separately. The notorious example was <filename>/etc/netstart</filename> 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 <filename>/etc/netstart</filename> mutated into <filename>/etc/rc.network</filename>. The latter was no longer an ordinary script; it comprised of large, tangled <citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></citerefentry> functions called from <filename>/etc/rc</filename> at different stages of system startup. However, as the startup tasks grew diverse and sophisticated, the <quote>quasi-modular</quote> approach became even more of a drag than the monolithic <filename>/etc/rc</filename> 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 <filename>rc</filename> system. Thus BSD <filename>rc.d</filename> 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 <filename>/etc/rc.d</filename>. Soon we will learn about more components of the <filename>rc.d</filename> system and see how the individual scripts are invoked.
The basic ideas behind BSD <filename>rc.d</filename> are <emphasis>fine modularity</emphasis> and <emphasis>code reuse</emphasis>. <emphasis>Fine modularity</emphasis> means that each basic <quote>service</quote> such as a system daemon or primitive startup task gets its own <citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></citerefentry> 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 <filename>/etc/rc</filename> script still drives system startup, but now it merely invokes the smaller scripts one by one with the <option>start</option> argument. It is easy to perform shutdown tasks as well by running the same set of scripts with the <option>stop</option> argument, which is done by <filename>/etc/rc.shutdown</filename>. Note how closely this follows the Unix way of having a set of small specialized tools, each fulfilling its task as well as possible. <emphasis>Code reuse</emphasis> means that common operations are implemented as <citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></citerefentry> functions and collected in <filename>/etc/rc.subr</filename>. Now a typical script can be just a few lines' worth of <citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></citerefentry> code. Finally, an important part of the <filename>rc.d</filename> framework is <citerefentry><refentrytitle>rcorder</refentrytitle><manvolnum>8</manvolnum></citerefentry>, which helps <filename>/etc/rc</filename> to run the small scripts orderly with respect to dependencies between them. It can help <filename>/etc/rc.shutdown</filename>, too, because the proper order for the shutdown sequence is opposite to that of startup.
The BSD <filename>rc.d</filename> design is described in <link linkend="lukem">the original article by Luke Mewburn</link>, and the <filename>rc.d</filename> components are documented in great detail in <link linkend="manpages">the respective manual pages</link>. However, it might not appear obvious to an <filename>rc.d</filename> 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 <filename>rc.d</filename>. 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 <filename>rc.d</filename> 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 <citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></citerefentry> scripting language in order to master <filename>rc.d</filename>. In addition, you should know how the system performs userland startup and shutdown tasks, which is described in <citerefentry><refentrytitle>rc</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
This article focuses on the FreeBSD branch of <filename>rc.d</filename>. Nevertheless, it may be useful to NetBSD developers, too, because the two branches of BSD <filename>rc.d</filename> not only share the same design but also stay similar in their aspects visible to script authors.
Outlining the task
A little consideration before starting <envar>$EDITOR</envar> will not hurt. In order to write a well-tempered <filename>rc.d</filename> script for a system service, we should be able to answer the following questions first:
Is the service mandatory or optional?
Will the script serve a single program, e.g., a daemon, or perform more complex actions?
Which other services will our service depend on, and vice versa?
From the examples that follow we will see why it is important to know the answers to these questions.
A dummy script
The following script just emits a message each time the system boots up:
#!/bin/sh<co xml:id="rcng-dummy-shebang"/>

. /etc/rc.subr<co xml:id="rcng-dummy-include"/>

name="dummy"<co xml:id="rcng-dummy-name"/>
start_cmd="${name}_start"<co xml:id="rcng-dummy-startcmd"/>
stop_cmd=":"<co xml:id="rcng-dummy-stopcmd"/>

dummy_start()<co xml:id="rcng-dummy-startfn"/>
{
echo "Nothing started."
}

load_rc_config $name<co xml:id="rcng-dummy-loadconfig"/>
run_rc_command "$1"<co xml:id="rcng-dummy-runcommand"/>
Things to note are:
An interpreted script should begin with the magic <quote>shebang</quote> line. That line specifies the interpreter program for the script. Due to the shebang line, the script can be invoked exactly like a binary program provided that it has the execute bit set. (See <citerefentry><refentrytitle>chmod</refentrytitle><manvolnum>1</manvolnum></citerefentry>.) For example, a system admin can run our script manually, from the command line:
<prompt>#</prompt> <userinput>/etc/rc.d/dummy start</userinput>
In order to be properly managed by the <filename>rc.d</filename> framework, its scripts need to be written in the <citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></citerefentry> language. If you have a service or port that uses a binary control utility or a startup routine written in another language, install that element in <filename>/usr/sbin</filename> (for the system) or <filename>/usr/local/sbin</filename> (for ports) and call it from a <citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></citerefentry> script in the appropriate <filename>rc.d</filename> directory.
If you would like to learn the details of why <filename>rc.d</filename> scripts must be written in the <citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></citerefentry> language, see how <filename>/etc/rc</filename> invokes them by means of <function>run_rc_script</function>, then study the implementation of <function>run_rc_script</function> in <filename>/etc/rc.subr</filename>.
In <filename>/etc/rc.subr</filename>, a number of <citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></citerefentry> functions are defined for an <filename>rc.d</filename> script to use. The functions are documented in <citerefentry><refentrytitle>rc.subr</refentrytitle><manvolnum>8</manvolnum></citerefentry>. While it is theoretically possible to write an <filename>rc.d</filename> script without ever using <citerefentry><refentrytitle>rc.subr</refentrytitle><manvolnum>8</manvolnum></citerefentry>, its functions prove extremely handy and make the job an order of magnitude easier. So it is no surprise that everybody resorts to <citerefentry><refentrytitle>rc.subr</refentrytitle><manvolnum>8</manvolnum></citerefentry> in <filename>rc.d</filename> scripts. We are not going to be an exception.
An <filename>rc.d</filename> script must <quote>source</quote> <filename>/etc/rc.subr</filename> (include it using <quote><command>.</command></quote>) <emphasis>before</emphasis> it calls <citerefentry><refentrytitle>rc.subr</refentrytitle><manvolnum>8</manvolnum></citerefentry> functions so that <citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></citerefentry> has an opportunity to learn the functions. The preferred style is to source <filename>/etc/rc.subr</filename> first of all.
Some useful functions related to networking are provided by another include file, <filename>/etc/network.subr</filename>.
<anchor xml:id="name-var"/>The mandatory variable <envar>name</envar> specifies the name of our script. It is required by <citerefentry><refentrytitle>rc.subr</refentrytitle><manvolnum>8</manvolnum></citerefentry>. That is, each <filename>rc.d</filename> script <emphasis>must</emphasis> set <envar>name</envar> before it calls <citerefentry><refentrytitle>rc.subr</refentrytitle><manvolnum>8</manvolnum></citerefentry> functions.

Loading…

No matching activity found.

Browse all component changes

Glossary

English English
No related strings found in the glossary.

Source information

Source string comment
(itstool) path: listitem/para
Flags
read-only
Source string location
article.translate.xml:177
String age
a year ago
Source string age
a year ago
Translation file
articles/rc-scripting.pot, string 22