path: root/static/freebsd/man8/rc.8 3.html

<table class="head">
  <tr>
    <td class="head-ltitle">RC(8)</td>
    <td class="head-vol">System Manager's Manual</td>
    <td class="head-rtitle">RC(8)</td>
  </tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">rc</code> &#x2014; <span class="Nd">command
    scripts for auto-reboot and daemon startup</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<table class="Nm">
  <tr>
    <td><code class="Nm">rc</code></td>
    <td></td>
  </tr>
</table>
<br/>
<table class="Nm">
  <tr>
    <td><code class="Nm">rc.conf</code></td>
    <td></td>
  </tr>
</table>
<br/>
<table class="Nm">
  <tr>
    <td><code class="Nm">rc.conf.local</code></td>
    <td></td>
  </tr>
</table>
<br/>
<table class="Nm">
  <tr>
    <td><code class="Nm">rc.d/</code></td>
    <td></td>
  </tr>
</table>
<br/>
<table class="Nm">
  <tr>
    <td><code class="Nm">rc.firewall</code></td>
    <td></td>
  </tr>
</table>
<br/>
<table class="Nm">
  <tr>
    <td><code class="Nm">rc.local</code></td>
    <td></td>
  </tr>
</table>
<br/>
<table class="Nm">
  <tr>
    <td><code class="Nm">rc.resume</code></td>
    <td></td>
  </tr>
</table>
<br/>
<table class="Nm">
  <tr>
    <td><code class="Nm">rc.shutdown</code></td>
    <td></td>
  </tr>
</table>
<br/>
<table class="Nm">
  <tr>
    <td><code class="Nm">rc.subr</code></td>
    <td></td>
  </tr>
</table>
<br/>
<table class="Nm">
  <tr>
    <td><code class="Nm">rc.suspend</code></td>
    <td></td>
  </tr>
</table>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The <code class="Nm">rc</code> utility is the command script which
    controls the automatic boot process after being called by
    <a class="Xr">init(8)</a>. The <code class="Nm">rc.local</code> script
    contains commands which are pertinent only to a specific site. Typically,
    the <span class="Pa">/usr/local/etc/rc.d/</span> mechanism is used instead
    of <code class="Nm">rc.local</code> these days but if you want to use
    <code class="Nm">rc.local</code>, it is still supported. In this case, it
    should source <span class="Pa">/etc/rc.conf</span> and contain additional
    custom startup code for your system. The best way to handle
    <code class="Nm">rc.local</code>, however, is to separate it out into
    <code class="Nm">rc.d/</code> style scripts and place them under
    <span class="Pa">/usr/local/etc/rc.d/</span>. The
    <code class="Nm">rc.conf</code> file contains the global system
    configuration information referenced by the startup scripts, while
    <code class="Nm">rc.conf.local</code> contains the local system
    configuration. See <a class="Xr">rc.conf(5)</a> for more information.</p>
<p class="Pp">The <code class="Nm">rc.d/</code> directories contain scripts
    which will be automatically executed at boot time and shutdown time.</p>
<p class="Pp">The <a class="Xr">service(8)</a> command provides a convenient
    interface to manage rc.d services.</p>
<p class="Pp">The <a class="Xr">sysrc(8)</a> command provides a scripting
    interface to modify system config files.</p>
<section class="Ss">
<h2 class="Ss" id="Operation_of_rc"><a class="permalink" href="#Operation_of_rc">Operation
  of <code class="Nm">rc</code></a></h2>
<ol class="Bl-enum">
  <li>If autobooting, set
      <var class="Va">autoboot</var>=<code class="Li">yes</code> and enable a
      flag (<var class="Va">rc_fast</var>=<code class="Li">yes</code>), which
      prevents the <code class="Nm">rc.d/</code> scripts from performing the
      check for already running processes (thus speeding up the boot process).
      This <var class="Va">rc_fast</var>=<code class="Li">yes</code> speedup
      will not occur when <code class="Nm">rc</code> is started up after exiting
      the single-user shell.</li>
  <li>Determine whether the system is booting diskless, and if so run the
      <span class="Pa">/etc/rc.initdiskless</span> script.</li>
  <li>Source <span class="Pa">/etc/rc.subr</span> to load various
      <a class="Xr">rc.subr(8)</a> shell functions to use.</li>
  <li>Load the configuration files (see below for reloading).</li>
  <li>Determine if booting in a jail, and add
      &#x201C;<code class="Li">nojail</code>&#x201D; (no jails allowed) or
      &#x201C;<code class="Li">nojailvnet</code>&#x201D; (only allow
      vnet-enabled jails) to the list of KEYWORDS to skip in
      <a class="Xr">rcorder(8)</a>.</li>
  <li>If the file <var class="Va">${firstboot_sentinel}</var> does not exist,
      add &#x201C;<code class="Li">firstboot</code>&#x201D; to the list of
      KEYWORDS to skip in <a class="Xr">rcorder(8)</a>.</li>
  <li>Invoke <a class="Xr">rcorder(8)</a> to order the files in
      <span class="Pa">/etc/rc.d/</span> that do not have a
      &#x201C;<code class="Li">nostart</code>&#x201D; KEYWORD (refer to
      <a class="Xr">rcorder(8)</a>'s <code class="Fl">-s</code> flag).</li>
  <li id="run_rc_scripts">Call
      <a class="permalink" href="#run_rc_scripts"><code class="Fn">run_rc_scripts</code></a>()
      with the list of scripts to be run.
    <p class="Pp" id="run_rc_script">For each script that will call
        <a class="permalink" href="#run_rc_script"><code class="Fn">run_rc_script</code></a>()
        (both functions are from <a class="Xr">rc.subr(8)</a>), which sets
        <var class="Va">$1</var> to
        &#x201C;<code class="Li">start</code>&#x201D;, and sources the script in
        a subshell. Stop processing when the script that is the value of the
        <var class="Va">$early_late_divider</var> has been run.</p>
  </li>
  <li>Check again to see if the file <var class="Va">${firstboot_sentinel}</var>
      exists (in case it is located on a newly mounted file system) and adjust
      the list of KEYWORDs to skip appropriately.</li>
  <li>Re-run <a class="Xr">rcorder(8)</a>, this time including the scripts in
      the <var class="Va">$local_startup</var> directories. Call
      <code class="Fn">run_rc_scripts</code>() again with the new list of
      scripts. It will skip any that have already been run and execute the rest
      as described above.</li>
  <li>If the file <var class="Va">${firstboot_sentinel}</var> exists, delete it.
      If the file <var class="Va">${firstboot_sentinel}-reboot</var> also exists
      (because it was created by a script), then delete it and reboot.</li>
</ol>
</section>
<section class="Ss">
<h2 class="Ss" id="Operation_of_rc.shutdown"><a class="permalink" href="#Operation_of_rc.shutdown">Operation
  of <code class="Nm">rc.shutdown</code></a></h2>
<ol class="Bl-enum">
  <li>Set <var class="Va">rc_shutdown</var> to the value of the first argument
      passed to <code class="Nm">rc.shutdown</code> or to
      &#x201C;<code class="Li">unspecified</code>&#x201D; if no argument was
      passed.</li>
  <li>Source <span class="Pa">/etc/rc.subr</span> to load various
      <a class="Xr">rc.subr(8)</a> shell functions to use.</li>
  <li>Load the configuration files.</li>
  <li>Invoke <a class="Xr">rcorder(8)</a> to order the files in
      <span class="Pa">/etc/rc.d/</span> and the
      <var class="Va">$local_startup</var> directories that have a
      &#x201C;<code class="Li">shutdown</code>&#x201D; KEYWORD (refer to
      <a class="Xr">rcorder(8)</a>'s <code class="Fl">-k</code> flag), reverse
      that order, and assign the result to a variable.</li>
  <li>Call each script in turn using <code class="Fn">run_rc_script</code>()
      (from <a class="Xr">rc.subr(8)</a>), which sets <var class="Va">$1</var>
      to &#x201C;<code class="Li">faststop</code>&#x201D;, and sources the
      script in a subshell.</li>
</ol>
</section>
<section class="Ss">
<h2 class="Ss" id="Contents_of_rc.d/"><a class="permalink" href="#Contents_of_rc.d/">Contents
  of <code class="Nm">rc.d/</code></a></h2>
<p class="Pp"><code class="Nm">rc.d/</code> is located in
    <span class="Pa">/etc/rc.d/</span>. The following file naming conventions
    are currently used in <code class="Nm">rc.d/</code>:</p>
<div class="Bd-indent">
<dl class="Bl-tag">
  <dt><span class="Pa">ALLUPPERCASE</span></dt>
  <dd>Scripts that are &#x201C;placeholders&#x201D; to ensure that certain
      operations are performed before others. In order of startup, these are:
    <dl class="Bl-tag">
      <dt><span class="Pa">FILESYSTEMS</span></dt>
      <dd>Ensure that root and other critical file systems are mounted. This is
          the default <var class="Va">$early_late_divider</var>.</dd>
      <dt><span class="Pa">NETWORKING</span></dt>
      <dd>Ensure basic network services are running, including general network
          configuration.</dd>
      <dt><span class="Pa">SERVERS</span></dt>
      <dd>Ensure basic services exist for services that start early (such as
          <span class="Pa">nisdomain</span>), because they are required by
          <span class="Pa">DAEMON</span> below.</dd>
      <dt><span class="Pa">DAEMON</span></dt>
      <dd>Check-point before all general purpose daemons such as
          <span class="Pa">lpd</span> and <span class="Pa">ntpd</span>.</dd>
      <dt><span class="Pa">LOGIN</span></dt>
      <dd>Check-point before user login services (<span class="Pa">inetd</span>
          and <span class="Pa">sshd</span>), as well as services which might run
          commands as users (<span class="Pa">cron</span> and
          <span class="Pa">sendmail</span>).</dd>
    </dl>
  </dd>
  <dt id="stop_boot"><span class="Pa">bar</span></dt>
  <dd>Scripts that are sourced in a subshell. The boot does not stop if such a
      script terminates with a non-zero status, but a script can stop the boot
      if necessary by invoking the
      <a class="permalink" href="#stop_boot"><code class="Fn">stop_boot</code></a>()
      function (from <a class="Xr">rc.subr(8)</a>).</dd>
</dl>
</div>
<p class="Pp">Each script should contain <a class="Xr">rcorder(8)</a> keywords,
    especially an appropriate &#x201C;<code class="Li">PROVIDE</code>&#x201D;
    entry, and if necessary &#x201C;<code class="Li">REQUIRE</code>&#x201D; and
    &#x201C;<code class="Li">BEFORE</code>&#x201D; keywords.</p>
<p class="Pp" id="run_rc_command">Each script is expected to support at least
    the following arguments, which are automatically supported if it uses the
    <a class="permalink" href="#run_rc_command"><code class="Fn">run_rc_command</code></a>()
    function:</p>
<div class="Bd-indent">
<dl class="Bl-tag">
  <dt id="start"><a class="permalink" href="#start"><code class="Cm">start</code></a></dt>
  <dd>Start the service. This should check that the service is to be started as
      specified by <a class="Xr">rc.conf(5)</a>. Also checks if the service is
      already running and refuses to start if it is. This latter check is not
      performed by standard <span class="Ux">FreeBSD</span> scripts if the
      system is starting directly to multi-user mode, to speed up the boot
      process. If <code class="Cm">forcestart</code> is given, ignore the
      <a class="Xr">rc.conf(5)</a> check and start anyway.</dd>
  <dt id="stop"><a class="permalink" href="#stop"><code class="Cm">stop</code></a></dt>
  <dd>If the service is to be started as specified by
      <a class="Xr">rc.conf(5)</a>, stop the service. This should check that the
      service is running and complain if it is not. If
      <code class="Cm">forcestop</code> is given, ignore the
      <a class="Xr">rc.conf(5)</a> check and attempt to stop.</dd>
  <dt id="restart"><a class="permalink" href="#restart"><code class="Cm">restart</code></a></dt>
  <dd>Perform a <code class="Cm">stop</code> then a
      <code class="Cm">start</code>.</dd>
  <dt id="status"><a class="permalink" href="#status"><code class="Cm">status</code></a></dt>
  <dd>If the script starts a process (rather than performing a one-off
      operation), show the status of the process. Otherwise it is not necessary
      to support this argument. Defaults to displaying the process ID of the
      program (if running).</dd>
  <dt id="enable"><a class="permalink" href="#enable"><code class="Cm">enable</code></a></dt>
  <dd>Enable the service in <a class="Xr">rc.conf(5)</a>.</dd>
  <dt id="disable"><a class="permalink" href="#disable"><code class="Cm">disable</code></a></dt>
  <dd>Disable the service in <a class="Xr">rc.conf(5)</a>.</dd>
  <dt id="delete"><a class="permalink" href="#delete"><code class="Cm">delete</code></a></dt>
  <dd>Remove the service from <a class="Xr">rc.conf(5)</a>. If
      &#x2018;<code class="Li"><code class="Li">service_delete_empty</code></code>&#x2019;
      is set to &#x201C;<code class="Li">YES</code>&#x201D;,
      <span class="Pa">/etc/rc.conf.d/$servicename</span> will be deleted if
      empty after modification.</dd>
  <dt id="describe"><a class="permalink" href="#describe"><code class="Cm">describe</code></a></dt>
  <dd>Print a short description of what the script does.</dd>
  <dt id="extracommands"><a class="permalink" href="#extracommands"><code class="Cm">extracommands</code></a></dt>
  <dd>Print the script's non-standard commands.</dd>
  <dt id="poll"><a class="permalink" href="#poll"><code class="Cm">poll</code></a></dt>
  <dd>If the script starts a process (rather than performing a one-off
      operation), wait for the command to exit. Otherwise it is not necessary to
      support this argument.</dd>
  <dt id="enabled"><a class="permalink" href="#enabled"><code class="Cm">enabled</code></a></dt>
  <dd>Return 0 if the service is enabled and 1 if it is not. This command does
      not print anything.</dd>
  <dt id="rcvar"><a class="permalink" href="#rcvar"><code class="Cm">rcvar</code></a></dt>
  <dd>Display which <a class="Xr">rc.conf(5)</a> variables are used to control
      the startup of the service (if any).</dd>
</dl>
</div>
<p class="Pp">If a script must implement additional commands it can list them in
    the <var class="Va">extra_commands</var> variable, and define their actions
    in a variable constructed from the command name (see the
    <a class="Sx" href="#EXAMPLES">EXAMPLES</a> section).</p>
<p class="Pp">The configuration files are normally read only once at the start
    of a boot sequence; if a script needs to <code class="Cm">enable</code> or
    <code class="Cm">disable</code> any other script that would run later in the
    sequence, it must send a <code class="Dv">SIGALRM</code> to the rc process
    (identified by <code class="Ev">$RC_PID</code>) to have it re-read the
    files.</p>
<p class="Pp">The following key points apply to old-style scripts in
    <span class="Pa">/usr/local/etc/rc.d/</span>:</p>
<ul class="Bl-bullet">
  <li>Scripts are only executed if their <a class="Xr">basename(1)</a> matches
      the shell globbing pattern <span class="Pa">*.sh</span>, and they are
      executable. Any other files or directories present within the directory
      are silently ignored.</li>
  <li>When a script is executed at boot time, it is passed the string
      &#x201C;<code class="Li">start</code>&#x201D; as its first and only
      argument. At shutdown time, it is passed the string
      &#x201C;<code class="Li">stop</code>&#x201D; as its first and only
      argument. All <code class="Nm">rc.d/</code> scripts are expected to handle
      these arguments appropriately. If no action needs to be taken at a given
      time (either boot time or shutdown time), the script should exit
      successfully and without producing an error message.</li>
  <li>The scripts within each directory are executed in lexicographical order.
      If a specific order is required, numbers may be used as a prefix to the
      existing filenames, so for example <span class="Pa">100.foo</span> would
      be executed before <span class="Pa">200.bar</span>; without the numeric
      prefixes the opposite would be true.</li>
  <li id="without">The output from each script is traditionally a space
      character, followed by the name of the software package being started or
      shut down,
      <a class="permalink" href="#without"><i class="Em">without</i></a> a
      trailing newline character.</li>
</ul>
</section>
</section>
<section class="Sh">
<h1 class="Sh" id="SCRIPTS_OF_INTEREST"><a class="permalink" href="#SCRIPTS_OF_INTEREST">SCRIPTS
  OF INTEREST</a></h1>
<p class="Pp">When an automatic reboot is in progress,
    <code class="Nm">rc</code> is invoked with the argument
    <code class="Cm">autoboot</code>. One of the scripts run from
    <span class="Pa">/etc/rc.d/</span> is
    <span class="Pa">/etc/rc.d/fsck</span>. This script runs
    <a class="Xr">fsck(8)</a> with option <code class="Fl">-p</code> and
    <code class="Fl">-F</code> to &#x201C;preen&#x201D; all the disks of minor
    inconsistencies resulting from the last system shutdown. If this fails, then
    checks/repairs of serious inconsistencies caused by hardware or software
    failure will be performed in the background at the end of the booting
    process. If <code class="Cm">autoboot</code> is not set, when going from
    single-user to multi-user mode for example, the script does not do
  anything.</p>
<p class="Pp">The <span class="Pa">/etc/rc.d/serial</span> script is used to set
    any special configurations for serial devices.</p>
<p class="Pp">The <code class="Nm">rc.firewall</code> script is used to
    configure rules for the kernel based firewall service. It has several
    possible options:</p>
<p class="Pp"></p>
<div class="Bd-indent">
<dl class="Bl-tag Bl-compact">
  <dt id="open"><a class="permalink" href="#open"><code class="Cm">open</code></a></dt>
  <dd>will allow anyone in</dd>
  <dt id="client"><a class="permalink" href="#client"><code class="Cm">client</code></a></dt>
  <dd>will try to protect just this machine</dd>
  <dt id="simple"><a class="permalink" href="#simple"><code class="Cm">simple</code></a></dt>
  <dd>will try to protect a whole network</dd>
  <dt id="closed"><a class="permalink" href="#closed"><code class="Cm">closed</code></a></dt>
  <dd>totally disables IP services except via <span class="Pa">lo0</span>
      interface</dd>
  <dt id="UNKNOWN"><a class="permalink" href="#UNKNOWN"><code class="Cm">UNKNOWN</code></a></dt>
  <dd>disables the loading of firewall rules</dd>
  <dt><var class="Ar">filename</var></dt>
  <dd>will load the rules in the given filename (full path required).</dd>
</dl>
</div>
<p class="Pp">Most daemons, including network related daemons, have their own
    script in <span class="Pa">/etc/rc.d/</span>, which can be used to start,
    stop, and check the status of the service.</p>
<p class="Pp">Any architecture specific scripts, such as
    <span class="Pa">/etc/rc.d/apm</span> for example, specifically check that
    they are on that architecture before starting the daemon.</p>
<p class="Pp">Following tradition, all startup files reside in
    <span class="Pa">/etc</span>.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1>
<dl class="Bl-tag Bl-compact">
  <dt><span class="Pa">/etc/rc</span></dt>
  <dd style="width: auto;">&#x00A0;</dd>
  <dt><span class="Pa">/etc/rc.conf</span></dt>
  <dd style="width: auto;">&#x00A0;</dd>
  <dt><span class="Pa">/etc/rc.conf.local</span></dt>
  <dd style="width: auto;">&#x00A0;</dd>
  <dt><span class="Pa">/etc/rc.d/</span></dt>
  <dd style="width: auto;">&#x00A0;</dd>
  <dt><span class="Pa">/etc/rc.firewall</span></dt>
  <dd style="width: auto;">&#x00A0;</dd>
  <dt><span class="Pa">/etc/rc.local</span></dt>
  <dd style="width: auto;">&#x00A0;</dd>
  <dt><span class="Pa">/etc/rc.shutdown</span></dt>
  <dd style="width: auto;">&#x00A0;</dd>
  <dt><span class="Pa">/etc/rc.subr</span></dt>
  <dd style="width: auto;">&#x00A0;</dd>
  <dt><span class="Pa">/var/run/dmesg.boot</span></dt>
  <dd><a class="Xr">dmesg(8)</a> results soon after the
      <code class="Nm">rc</code> process begins. Useful when
      <a class="Xr">dmesg(8)</a> buffer in the kernel no longer has this
      information.</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1>
<p class="Pp">The following is a minimal <code class="Nm">rc.d/</code> style
    script. Most scripts require little more than the following.</p>
<div class="Bd Pp Bd-indent Li">
<pre>#!/bin/sh
#

# PROVIDE: foo
# REQUIRE: bar_service_required_to_precede_foo

. /etc/rc.subr

name=&quot;foo&quot;
rcvar=foo_enable
command=&quot;/usr/local/bin/foo&quot;

load_rc_config $name
run_rc_command &quot;$1&quot;</pre>
</div>
<p class="Pp">Certain scripts may want to provide enhanced functionality. The
    user may access this functionality through additional commands. The script
    may list and define as many commands at it needs.</p>
<div class="Bd Pp Bd-indent Li">
<pre>#!/bin/sh
#

# PROVIDE: foo
# REQUIRE: bar_service_required_to_precede_foo
# BEFORE:  baz_service_requiring_foo_to_precede_it

. /etc/rc.subr

name=&quot;foo&quot;
rcvar=foo_enable
command=&quot;/usr/local/bin/foo&quot;
extra_commands=&quot;nop hello&quot;
hello_cmd=&quot;echo Hello World.&quot;
nop_cmd=&quot;do_nop&quot;

do_nop()
{
	echo &quot;I do nothing.&quot;
}

load_rc_config $name
run_rc_command &quot;$1&quot;</pre>
</div>
<p class="Pp">As all processes are killed by <a class="Xr">init(8)</a> at
    shutdown, the explicit <a class="Xr">kill(1)</a> is unnecessary, but is
    often included.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
  ALSO</a></h1>
<p class="Pp"><a class="Xr">kill(1)</a>, <a class="Xr">rc.conf(5)</a>,
    <a class="Xr">init(8)</a>, <a class="Xr">rc.resume(8)</a>,
    <a class="Xr">rc.subr(8)</a>, <a class="Xr">rcorder(8)</a>,
    <a class="Xr">reboot(8)</a>, <a class="Xr">savecore(8)</a>,
    <a class="Xr">service(8)</a>, <a class="Xr">sysrc(8)</a></p>
<p class="Pp"></p>
<p class="Pp"><cite class="Rs"><span class="RsT">Practical rc.d scripting in
    BSD</span>,
    <a class="RsU" href="&lt;https://docs.freebsd.org/en/articles/rc-scripting/&gt;">&lt;https://docs.freebsd.org/en/articles/rc-scripting/&gt;</a>.</cite></p>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp">The <code class="Nm">rc</code> utility appeared in
    <span class="Ux">4.0BSD</span>.</p>
</section>
</div>
<table class="foot">
  <tr>
    <td class="foot-date">September 20, 2024</td>
    <td class="foot-os">FreeBSD 15.0</td>
  </tr>
</table>