Annotation of wikisrc/guide/rc.mdwn, revision 1.6

1.4       jdf         1: **Contents**
                      2: 
                      3: [[!toc levels=3]]
                      4: 
1.1       jdf         5: # The rc.d System
                      6: 
1.3       jdf         7: NetBSD uses individual scripts for controlling system and service startup,
1.1       jdf         8: similar to System V, but without runlevels.
1.3       jdf         9: Nowadays, most Linux distributions switched to systemd, which is a different
                     10: approach: It does not use scripts anymore, but tries to have everything binary.
                     11: It also serves for several other purposes, while NetBSD's rc.d system just
1.1       jdf        12: serves for starting up services at system startup or by user intervention.
                     13: 
                     14: This chapter is an overview of NetBSD's rc.d system and its configuration.
                     15: 
                     16: ## Basics
                     17: 
                     18: The system startup files reside in the `/etc` directory. They are:
                     19: 
                     20:  * `/etc/rc`
                     21:  * `/etc/rc.conf`
                     22:  * `/etc/rc.d/*`
                     23:  * `/etc/rc.local`
                     24:  * `/etc/rc.shutdown`
                     25:  * `/etc/rc.subr`
                     26:  * `/etc/defaults/*`
                     27:  * `/etc/rc.conf.d/*`
                     28: 
1.3       jdf        29: First, a look at controlling and supporting scripts (also documented in
1.5       plunky     30: [[!template id=man name="rc" section="8"]]):
1.1       jdf        31: 
1.3       jdf        32:  * After the kernel has initialized all devices at startup, it starts
1.5       plunky     33:    [[!template id=man name="init" section="8"]],
1.1       jdf        34:    which in turn runs `/etc/rc`.
1.3       jdf        35: 
                     36:  * `/etc/rc` sorts the scripts in `/etc/rc.d` using
1.5       plunky     37:    [[!template id=man name="rcorder" section="8"]]
1.1       jdf        38:    and then runs them in that order. See below and the manpage for details of
                     39:    how the order of rc.d scripts is determined.
1.3       jdf        40: 
                     41:  * `/etc/rc.subr` contains common functions used by `/etc/rc` and various rc.d
1.1       jdf        42:    scripts.
1.3       jdf        43: 
                     44:  * When shutting down the system with
1.5       plunky     45:    [[!template id=man name="shutdown" section="8"]],
1.1       jdf        46:    `/etc/rc.shutdown` is run, which runs the scripts in `/etc/rc.d` in
1.3       jdf        47:    reverse order (as defined by
1.5       plunky     48:    [[!template id=man name="rcorder" section="8"]]).
1.3       jdf        49: 
                     50:    *Note*: If you shut down the system using the
1.5       plunky     51:    [[!template id=man name="halt" section="8"]]
1.1       jdf        52:    command, these scripts will not be run.
                     53: 
                     54: There are some special scripts outside the `rc.d` directory, which are also
                     55: run:
                     56: 
1.3       jdf        57:  * `/etc/rc.local` is almost the last script called at boot up. This script can
1.1       jdf        58:    be edited by the administrator to start local daemons that don't fit the
                     59:    rc.d model, or do maintenance that should be done only once at startup.
                     60: 
1.3       jdf        61: rc.d scripts are controlled by a central configuration file, `/etc/rc.conf`,
                     62: which loads its default settings from `/etc/defaults/rc.conf`. If you want to
                     63: change a default setting, do not edit `/etc/defaults/rc.conf`; instead, override
1.1       jdf        64: the setting in `/etc/rc.conf`.
                     65: 
1.3       jdf        66: It is a good idea to read the
1.5       plunky     67: [[!template id=man name="rc.conf" section="5"]]
1.1       jdf        68: man page to learn about the services that are by default available to you.
                     69: 
1.3       jdf        70: The following example shows how to enable the SSH daemon, which is disabled by
1.1       jdf        71: default:
                     72: 
                     73:     # cd /etc; grep ssh defaults/rc.conf
                     74:     sshd=NO                 sshd_flags=""
                     75:     # echo "sshd=YES" >> rc.conf
                     76: 
1.5       plunky     77: Now [[!template id=man name="sshd" section="8"]]
1.3       jdf        78: will be started automatically at system startup. The next section describes how
1.1       jdf        79: to start and stop services at any time.
                     80: 
1.3       jdf        81: Last but not least, files can be created in the `/etc/rc.conf.d/` directory to
1.1       jdf        82: override the behavior of a given rc.d script without editing the script itself.
                     83: 
                     84: ## The rc.d scripts
                     85: 
1.3       jdf        86: The actual scripts that control services are in `/etc/rc.d`. These scripts are
                     87: automatically run at boot time, but they can be called manually if necessary.
                     88: The following example shows how to start the SSH daemon that we enabled in the
1.1       jdf        89: previous section:
                     90: 
                     91:     # /etc/rc.d/sshd start
                     92:     Starting sshd.
                     93: 
                     94: Later, if you wish to stop the SSH daemon, run the following command:
                     95: 
                     96:     # /etc/rc.d/sshd stop
                     97:     Stopping sshd.
                     98:     Waiting for PIDS: 123.
                     99: 
                    100: The rc.d scripts take one of the following arguments:
                    101: 
                    102:  * `start`
                    103:  * `stop`
                    104:  * `restart`
                    105:  * `status`
                    106: 
1.3       jdf       107: Some scripts may support other arguments (e.g., `reload`), but every script will
1.1       jdf       108: support at least the above commands.
                    109: 
1.3       jdf       110: As an example, after adding a new record to a
1.5       plunky    111: [[!template id=man name="named" section="8"]]
1.3       jdf       112: database, the daemon can be told to reload its configuration files with the
1.1       jdf       113: following command:
                    114: 
                    115:     # /etc/rc.d/named reload
                    116:     Reloading named config files.
                    117: 
1.3       jdf       118: Note that all of the commands discussed above will only take action if the
                    119: particular service is enabled in `/etc/rc.conf`. It is possible to bypass this
1.1       jdf       120: requirement by prepending `one` to the command, as in:
                    121: 
                    122:     # /etc/rc.d/httpd start
                    123:     $httpd is not enabled - see rc.conf(5).
                    124:     Use the following if you wish to perform the operation:
                    125:       /etc/rc.d/httpd onestart
                    126:     # /etc/rc.d/httpd onestart
                    127:     Starting httpd.
                    128: 
1.3       jdf       129: The above command will allow you to start the
1.5       plunky    130: [[!template id=man name="httpd" section="8"]]
1.3       jdf       131: service one time. To stop a service that has been started in this manner, pass
1.1       jdf       132: `onestop` to the script.
                    133: 
                    134: ## Order/dependencies of start determined by rcorder
                    135: 
1.3       jdf       136: The startup system of every Unix system determines, in one way or another, the
                    137: order in which services are started. On some Unix systems this is done by
                    138: numbering the files and/or putting them in separate run level directories.
                    139: Solaris relies on wildcards like `/etc/rc[23].d/S*` being sorted numerically
                    140: when expanded. Some simply put all the commands that should be started into a
                    141: single monolithic script (this is the traditional BSD method, and is what NetBSD
                    142: did before the rc.d system). On modern NetBSD this is done by the rc.d scripts
                    143: and their contents. Please note that NetBSD does not have multiple runlevels as
1.1       jdf       144: found in SysV-style systems like Solaris and Linux.
                    145: 
1.3       jdf       146: At the beginning of each rc.d script there is a series of commented out lines
1.1       jdf       147: that have one of the following items in them:
                    148: 
                    149:  * `REQUIRE`
                    150:  * `PROVIDE`
                    151:  * `BEFORE`
                    152:  * `KEYWORD`
                    153: 
1.3       jdf       154: These describe the dependencies of that particular script and allow rcorder to
                    155: easily work either `up` or `down` as the situation requires. As an example, here
1.1       jdf       156: is the ordering information contained in `/etc/rc.d/nfsd`:
                    157: 
                    158:     ...
1.2       jdf       159:     # PROVIDE: nfsd
                    160:     # REQUIRE: rpcbind mountd
1.1       jdf       161:     ...
                    162: 
1.3       jdf       163: Here we can see that this script provides the `nfsd` service and that it
                    164: requires `rpcbind` and `mountd` to be running first. The
1.5       plunky    165: [[!template id=man name="rcorder" section="8"]]
1.3       jdf       166: utility is used at system startup time to read through all the rc.d scripts and
1.1       jdf       167: determine the order in which they should be run.
                    168: 
                    169: ## rc.d scripts of additional services
                    170: 
                    171: Packages you install additionally won't be listed in the rc.conf(5) manpage.
                    172: Packages installing services which can be started with an rc.d script tell you
                    173: so after they are installed, along with the variable that is used for starting
                    174: them (usually, it has the same name as the service itself).
                    175: 
                    176: Then, you usually have to copy them from `/usr/pkg/share/examples/rc.d` to
                    177: `/etc/rc.d` for `rc` to automatically find them, or add the line
                    178: 
                    179:     rc_directories="/etc/rc.d /usr/pkg/share/examples/rc.d"
                    180: 
                    181: to your `/etc/rc.conf`.
                    182: 
                    183: If you forgot the name of the service variable, you can have a look at the rc.d
                    184: script itself. The variable `rcvar` (usually set to `$name`) will tell you.
                    185: E.g., to find the name of variable to start fscd, run
                    186: 
                    187:     $ grep ^rcvar /etc/rc.d/fscd
                    188:        rcvar=${name}
                    189:        $ grep ^name /etc/rc.d/fscd   # Aaaw, no direct rcvar.
                    190:        name="fscd"
                    191: 
                    192: Thus, you need in your `/etc/rc.conf` the entry:
                    193: 
                    194:     fscd="YES"
                    195: 
                    196: ## Additional Reading
                    197: 
1.3       jdf       198: Luke Mewburn, one of the principal designers of the rc.d system, gave a
                    199: presentation on the system at USENIX 2001. It is available in
1.1       jdf       200: [PDF](http://www.mewburn.net/luke/papers/rc.d.pdf) format.
                    201: 

CVSweb for NetBSD wikisrc <wikimaster@NetBSD.org> software: FreeBSD-CVSweb