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

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

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