File:  [NetBSD Developer Wiki] / wikisrc / guide / rc.mdwn
Revision 1.5: download - view: text, annotated - select for diffs
Fri Jun 19 19:18:31 2015 UTC (6 years, 3 months ago) by plunky
Branches: MAIN
CVS tags: HEAD
replace direct links to manpages on netbsd.gw.com with templates

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

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