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

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:     ...
        !           155:      PROVIDE: nfsd
        !           156:      REQUIRE: rpcbind mountd
        !           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