feat: Added FreeBSD man pages

1 files changed, 587 insertions, 0 deletions

diff --git a/static/freebsd/man8/rc.8 b/static/freebsd/man8/rc.8
new file mode 100644
index 00000000..a68878f0
--- /dev/null
+++ b/static/freebsd/man8/rc.8
@@ -0,0 +1,587 @@
+.\" Copyright (c) 1980, 1991, 1993
+.\"	The Regents of the University of California.  All rights reserved.
+.\"
+.\" Portions of this manual page are Copyrighted by
+.\"	The NetBSD Foundation.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.Dd September 20, 2024
+.Dt RC 8
+.Os
+.Sh NAME
+.Nm rc
+.Nd command scripts for auto-reboot and daemon startup
+.Sh SYNOPSIS
+.Nm
+.Nm rc.conf
+.Nm rc.conf.local
+.Nm rc.d/
+.Nm rc.firewall
+.Nm rc.local
+.Nm rc.resume
+.Nm rc.shutdown
+.Nm rc.subr
+.Nm rc.suspend
+.Sh DESCRIPTION
+The
+.Nm
+utility is the command script which controls the automatic boot process
+after being called by
+.Xr init 8 .
+The
+.Nm rc.local
+script contains commands which are pertinent only
+to a specific site.
+Typically, the
+.Pa /usr/local/etc/rc.d/
+mechanism is used instead of
+.Nm rc.local
+these days but if
+you want to use
+.Nm rc.local ,
+it is still supported.
+In this case, it should source
+.Pa /etc/rc.conf
+and contain additional custom startup code for your system.
+The best way to handle
+.Nm rc.local ,
+however, is to separate it out into
+.Nm rc.d/
+style scripts and place them under
+.Pa /usr/local/etc/rc.d/ .
+The
+.Nm rc.conf
+file contains the global system configuration information referenced
+by the startup scripts, while
+.Nm rc.conf.local
+contains the local system configuration.
+See
+.Xr rc.conf 5
+for more information.
+.Pp
+The
+.Nm rc.d/
+directories contain scripts which will be automatically
+executed at boot time and shutdown time.
+.Pp
+The
+.Xr service 8
+command provides a convenient interface to manage rc.d services.
+.Pp
+The
+.Xr sysrc 8
+command provides a scripting interface to modify system config files.
+.Ss Operation of Nm
+.Bl -enum
+.It
+If autobooting, set
+.Va autoboot Ns = Ns Li yes
+and enable a flag
+.Pq Va rc_fast Ns = Ns Li yes ,
+which prevents the
+.Nm rc.d/
+scripts from performing the check for already running processes
+(thus speeding up the boot process).
+This
+.Va rc_fast Ns = Ns Li yes
+speedup will not occur when
+.Nm
+is started up after exiting the single-user shell.
+.It
+Determine whether the system is booting diskless,
+and if so run the
+.Pa /etc/rc.initdiskless
+script.
+.It
+Source
+.Pa /etc/rc.subr
+to load various
+.Xr rc.subr 8
+shell functions to use.
+.It
+Load the configuration files (see below for reloading).
+.It
+Determine if booting in a jail, and add
+.Dq Li nojail
+(no jails allowed) or
+.Dq Li nojailvnet
+(only allow vnet-enabled jails) to the list of KEYWORDS to skip in
+.Xr rcorder 8 .
+.It
+If the file
+.Va ${firstboot_sentinel}
+does not exist, add
+.Dq Li firstboot
+to the list of KEYWORDS to skip in
+.Xr rcorder 8 .
+.It
+Invoke
+.Xr rcorder 8
+to order the files in
+.Pa /etc/rc.d/
+that do not have a
+.Dq Li nostart
+KEYWORD (refer to
+.Xr rcorder 8 Ns 's
+.Fl s
+flag).
+.It
+Call
+.Fn run_rc_scripts
+with the list of scripts to be run.
+.Pp
+For each script that will call
+.Fn run_rc_script
+(both functions are from
+.Xr rc.subr 8 ) ,
+which sets
+.Va $1
+to
+.Dq Li start ,
+and sources the script in a subshell.
+Stop processing when the script that is the value of the
+.Va $early_late_divider
+has been run.
+.It
+Check again to see if the file
+.Va ${firstboot_sentinel}
+exists (in case it is located on a newly mounted file system)
+and adjust the list of KEYWORDs to skip appropriately.
+.It
+Re-run
+.Xr rcorder 8 ,
+this time including the scripts in the
+.Va $local_startup
+directories.
+Call
+.Fn run_rc_scripts
+again with the new list of scripts.
+It will skip any that have already been run and
+execute the rest as described above.
+.It
+If the file
+.Va ${firstboot_sentinel}
+exists, delete it.
+If the file
+.Va ${firstboot_sentinel}-reboot
+also exists (because it was created by a script), then delete it and reboot.
+.El
+.Ss Operation of Nm rc.shutdown
+.Bl -enum
+.It
+Set
+.Va rc_shutdown
+to the value of the first argument passed to
+.Nm rc.shutdown
+or to
+.Dq Li unspecified
+if no argument was passed.
+.It
+Source
+.Pa /etc/rc.subr
+to load various
+.Xr rc.subr 8
+shell functions to use.
+.It
+Load the configuration files.
+.It
+Invoke
+.Xr rcorder 8
+to order the files in
+.Pa /etc/rc.d/
+and the
+.Va $local_startup
+directories
+that have a
+.Dq Li shutdown
+KEYWORD (refer to
+.Xr rcorder 8 Ns 's
+.Fl k
+flag),
+reverse that order, and assign the result to a variable.
+.It
+Call each script in turn using
+.Fn run_rc_script
+(from
+.Xr rc.subr 8 ) ,
+which sets
+.Va $1
+to
+.Dq Li faststop ,
+and sources the script in a subshell.
+.El
+.Ss Contents of Nm rc.d/
+.Nm rc.d/
+is located in
+.Pa /etc/rc.d/ .
+The following file naming conventions are currently used in
+.Nm rc.d/ :
+.Bl -tag -width ".Pa ALLUPPERCASE" -offset indent
+.It Pa ALLUPPERCASE
+Scripts that are
+.Dq placeholders
+to ensure that certain operations are performed before others.
+In order of startup, these are:
+.Bl -tag -width ".Pa FILESYSTEMS"
+.It Pa FILESYSTEMS
+Ensure that root and other critical file systems are mounted.
+This is the default
+.Va $early_late_divider .
+.It Pa NETWORKING
+Ensure basic network services are running, including general
+network configuration.
+.It Pa SERVERS
+Ensure basic services
+exist for services that start early (such as
+.Pa nisdomain ) ,
+because they are required by
+.Pa DAEMON
+below.
+.It Pa DAEMON
+Check-point before all general purpose daemons such as
+.Pa lpd
+and
+.Pa ntpd .
+.It Pa LOGIN
+Check-point before user login services
+.Pa ( inetd
+and
+.Pa sshd ) ,
+as well as services which might run commands as users
+.Pa ( cron
+and
+.Pa sendmail ) .
+.El
+.It Pa bar
+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
+.Fn stop_boot
+function (from
+.Xr rc.subr 8 ) .
+.El
+.Pp
+Each script should contain
+.Xr rcorder 8
+keywords, especially an appropriate
+.Dq Li PROVIDE
+entry, and if necessary
+.Dq Li REQUIRE
+and
+.Dq Li BEFORE
+keywords.
+.Pp
+Each script is expected to support at least the following arguments, which
+are automatically supported if it uses the
+.Fn run_rc_command
+function:
+.Bl -tag -width ".Cm restart" -offset indent
+.It Cm start
+Start the service.
+This should check that the service is to be started as specified by
+.Xr rc.conf 5 .
+Also checks if the service is already running and refuses to start if
+it is.
+This latter check is not performed by standard
+.Fx
+scripts if the system is starting directly to multi-user mode, to
+speed up the boot process.
+If
+.Cm forcestart
+is given, ignore the
+.Xr rc.conf 5
+check and start anyway.
+.It Cm stop
+If the service is to be started as specified by
+.Xr rc.conf 5 ,
+stop the service.
+This should check that the service is running and complain if it is not.
+If
+.Cm forcestop
+is given, ignore the
+.Xr rc.conf 5
+check and attempt to stop.
+.It Cm restart
+Perform a
+.Cm stop
+then a
+.Cm start .
+.It Cm status
+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).
+.It Cm enable
+Enable the service in
+.Xr rc.conf 5 .
+.It Cm disable
+Disable the service in
+.Xr rc.conf 5 .
+.It Cm delete
+Remove the service from
+.Xr rc.conf 5 .
+If
+.Ql Li service_delete_empty
+is set to
+.Dq Li YES ,
+.Pa /etc/rc.conf.d/$servicename
+will be deleted if empty after modification.
+.It Cm describe
+Print a short description of what the script does.
+.It Cm extracommands
+Print the script's non-standard commands.
+.It Cm poll
+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.
+.It Cm enabled
+Return 0 if the service is enabled and 1 if it is not.
+This command does not print anything.
+.It Cm rcvar
+Display which
+.Xr rc.conf 5
+variables are used to control the startup of the service (if any).
+.El
+.Pp
+If a script must implement additional commands it can list them in
+the
+.Va extra_commands
+variable, and define their actions in a variable constructed from
+the command name (see the
+.Sx EXAMPLES
+section).
+.Pp
+The configuration files are normally read only once at the start of a boot
+sequence; if a script needs to
+.Cm enable
+or
+.Cm disable
+any other script that would run later in the sequence, it must send a
+.Dv SIGALRM
+to the rc process (identified by
+.Ev $RC_PID )
+to have it re-read the files.
+.Pp
+The following key points apply to old-style scripts in
+.Pa /usr/local/etc/rc.d/ :
+.Bl -bullet
+.It
+Scripts are only executed if their
+.Xr basename 1
+matches the shell globbing pattern
+.Pa *.sh ,
+and they are executable.
+Any other files or directories present within the directory are silently
+ignored.
+.It
+When a script is executed at boot time, it is passed the string
+.Dq Li start
+as its first and only argument.
+At shutdown time, it is passed the string
+.Dq Li stop
+as its first and only argument.
+All
+.Nm rc.d/
+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.
+.It
+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
+.Pa 100.foo
+would be executed before
+.Pa 200.bar ;
+without the numeric prefixes the opposite would be true.
+.It
+The output from each script is traditionally a space character,
+followed by the name of the software package being started or shut down,
+.Em without
+a trailing newline character.
+.El
+.Sh SCRIPTS OF INTEREST
+When an automatic reboot is in progress,
+.Nm
+is invoked with the argument
+.Cm autoboot .
+One of the scripts run from
+.Pa /etc/rc.d/
+is
+.Pa /etc/rc.d/fsck .
+This script runs
+.Xr fsck 8
+with option
+.Fl p
+and
+.Fl F
+to
+.Dq preen
+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
+.Cm autoboot
+is not set, when going from single-user to multi-user mode for example,
+the script does not do anything.
+.Pp
+The
+.Pa /etc/rc.d/serial
+script is used to set any special configurations for serial devices.
+.Pp
+The
+.Nm rc.firewall
+script is used to configure rules for the kernel based firewall
+service.
+It has several possible options:
+.Pp
+.Bl -tag -width ".Ar filename" -compact -offset indent
+.It Cm open
+will allow anyone in
+.It Cm client
+will try to protect just this machine
+.It Cm simple
+will try to protect a whole network
+.It Cm closed
+totally disables IP services except via
+.Pa lo0
+interface
+.It Cm UNKNOWN
+disables the loading of firewall rules
+.It Ar filename
+will load the rules in the given filename (full path required).
+.El
+.Pp
+Most daemons, including network related daemons, have their own script in
+.Pa /etc/rc.d/ ,
+which can be used to start, stop, and check the status of the service.
+.Pp
+Any architecture specific scripts, such as
+.Pa /etc/rc.d/apm
+for example, specifically check that they are on that architecture
+before starting the daemon.
+.Pp
+Following tradition, all startup files reside in
+.Pa /etc .
+.Sh FILES
+.Bl -tag -compact -width Pa
+.It Pa /etc/rc
+.It Pa /etc/rc.conf
+.It Pa /etc/rc.conf.local
+.It Pa /etc/rc.d/
+.It Pa /etc/rc.firewall
+.It Pa /etc/rc.local
+.It Pa /etc/rc.shutdown
+.It Pa /etc/rc.subr
+.It Pa /var/run/dmesg.boot
+.Xr dmesg 8
+results soon after the
+.Nm
+process begins.
+Useful when
+.Xr dmesg 8
+buffer in the kernel no longer has this information.
+.El
+.Sh EXAMPLES
+The following is a minimal
+.Nm rc.d/
+style script.
+Most scripts require little more than the following.
+.Bd -literal -offset indent
+#!/bin/sh
+#
+
+# PROVIDE: foo
+# REQUIRE: bar_service_required_to_precede_foo
+
+\&. /etc/rc.subr
+
+name="foo"
+rcvar=foo_enable
+command="/usr/local/bin/foo"
+
+load_rc_config $name
+run_rc_command "$1"
+.Ed
+.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.
+.Bd -literal -offset indent
+#!/bin/sh
+#
+
+# PROVIDE: foo
+# REQUIRE: bar_service_required_to_precede_foo
+# BEFORE:  baz_service_requiring_foo_to_precede_it
+
+\&. /etc/rc.subr
+
+name="foo"
+rcvar=foo_enable
+command="/usr/local/bin/foo"
+extra_commands="nop hello"
+hello_cmd="echo Hello World."
+nop_cmd="do_nop"
+
+do_nop()
+{
+	echo "I do nothing."
+}
+
+load_rc_config $name
+run_rc_command "$1"
+.Ed
+.Pp
+As all processes are killed by
+.Xr init 8
+at shutdown, the explicit
+.Xr kill 1
+is unnecessary, but is often included.
+.Sh SEE ALSO
+.Xr kill 1 ,
+.Xr rc.conf 5 ,
+.Xr init 8 ,
+.Xr rc.resume 8 ,
+.Xr rc.subr 8 ,
+.Xr rcorder 8 ,
+.Xr reboot 8 ,
+.Xr savecore 8 ,
+.Xr service 8 ,
+.Xr sysrc 8
+.Pp
+.Rs
+.%T Practical rc.d scripting in BSD
+.%U <https://docs.freebsd.org/en/articles/rc-scripting/>
+.Re
+.Sh HISTORY
+The
+.Nm
+utility appeared in
+.Bx 4.0 .