Move the examples to the EXAMPLES section and add some actual

reference manual style documentation to the DESCRIPTION.
Feedback and OK rpe@ and ajacoutot@, also using feedback from deraadt@.

1 files changed, 161 insertions, 32 deletions

diff --git a/share/man/man8/rc.conf.8 b/share/man/man8/rc.conf.8
index 35d5782a2a3..d4375449515 100644
--- a/share/man/man8/rc.conf.8
+++ b/share/man/man8/rc.conf.8
@@ -1,6 +1,7 @@
-.\"	$OpenBSD: rc.conf.8,v 1.22 2014/07/13 10:05:49 jmc Exp $
+.\"	$OpenBSD: rc.conf.8,v 1.23 2014/08/20 22:13:24 schwarze Exp $
 .\"
 .\" Copyright (c) 1997 Ian F. Darwin
+.\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org>
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -27,7 +28,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: July 13 2014 $
+.Dd $Mdocdate: August 20 2014 $
 .Dt RC.CONF 8
 .Os
 .Sh NAME
@@ -50,7 +51,8 @@ It is advisable to leave
 untouched, and instead create and edit a new
 .Nm rc.conf.local
 file.
-Variables set in this file will override variables previously set in
+Since only the last assignment to any variable takes effect,
+variables set in this file override variables previously set in
 .Nm rc.conf .
 .Pp
 .Nm rc.conf
@@ -59,10 +61,148 @@ is made up of variable assignments
 with comments designated by a hash mark
 .Pq Sq # .
 .Pp
-Some variables are used to turn features on or off.
-For example, whether the system runs the
+.Sy Base system daemon
+configuration variables are used to enable and disable daemon programs
+that are installed by default, and to set their command line options.
+.Pp
+All of these variables follow the format
+.Dq Ar daemon Ns _flags
+where
+.Ar daemon
+is the name of one of the
+.Xr rc.d 8
+daemon control scripts.
+The list of base system daemons, including the information whether
+they are enabled by default and what typical command line options
+are, can be displayed with this command:
+.Pp
+.Dl grep _flags /etc/rc.conf
+.Pp
+If one of these variables is set to
+.Cm NO ,
+the respective
+.Ar daemon
+is disabled.
+If set to the empty string, the
+.Ar daemon
+is run with the default command line arguments defined in its
+.Xr rc.d 8
+.Ar daemon
+script, or without command line arguments if no such default exists.
+If set to any other value, including a string containing
+only a single blank character, the
+.Ar daemon
+is run with those command line arguments.
+.Pp
+.Sy Package daemon
+configuration variables are used to enable and disable
+daemon programs installed from
+.Xr packages 7 ,
+and to set their command line options.
+.Pp
+The special
+.Cm pkg_scripts
+variable lists
+.Xr rc.d 8
+.Ar daemon
+control scripts to be started in the specified order.
+For each
+.Ar daemon
+listed, its default command line options can optionally be overridden
+using the variable
+.Ar daemon Ns _flags
+as described above.
+.Pp
+.Sy Base system service
+configuration variables control features available by default
+that are not implemented as daemons.
+They can be set to either
+.Cm YES
+or
+.Cm NO .
+When set to
+.Cm YES ,
+they have the following effects:
+.Bl -tag -width check_quotas
+.It Cm accounting
+rc calls:
+.Xr accton 8
+.Pa /var/account/acct
+.It Cm check_quotas
+rc calls:
+.Xr quotacheck 8
+.Fl a ;
+.Xr quotaon 8
+.Fl a
+.It Cm ipsec
+rc calls:
+.Xr ipsecctl 8
+.Fl f Pf $ Brq Ar ipsec_rules
+.It Cm multicast_host , multicast_router
+See
+.Xr netstart 8 .
+.It Cm pf
+rc calls:
+.Xr pfctl 8
+.Fl ef
+.Pf $ Brq Ar pf_rules
+.It Cm spamd_black
+The script
+.Pa /etc/rc.d/spamd
+uses
+.Fl b
+in front of any other configured command line arguments when running
+.Xr spamd 8
+and
+.Xr spamd-setup 8 .
+.El
+.Pp
+.Sy Auxiliary
+configuration variables mostly determine
+the locations of specific configuration files.
+The boot scripts use them as follows:
+.Bl -tag -width ipsec_rules
+.It Cm amd_master
+The
+.Xr amd 8
+master map file.
+The script
+.Pa /etc/rc.d/amd
+appends its content to the command line when starting the auto mounter daemon.
+.It Cm pf_rules
+The
+.Xr pf 4
+packet filter rule file.
+If the
+.Cm pf
+service is enabled,
+rc calls:
+.Xr pfctl 8
+.Fl ef
+.Pf $ Brq Ar pf_rules
+.It Cm ipsec_rules
+The
+.Xr ipsec 4
+configuration file.
+If the
+.Cm ipsec
+service is enabled,
+rc calls:
+.Xr ipsecctl 8
+.Fl f
+.Pf $ Brq Ar ipsec_rules
+.It Cm shlib_dirs
+Extra shared library search path entries.
+rc calls:
+.Xr ldconfig 8
+.Pa /usr/X11R6/lib
+.Pa /usr/local/lib
+.Pf $ Brq Ar shlib_dirs
+.El
+.Sh EXAMPLES
+Do not start the
 .Xr dhcpd 8
-daemon is determined by the following line:
+daemon when booting the system:
 .Bd -literal -offset indent
 dhcpd_flags=NO
 .Ed
@@ -74,42 +214,31 @@ add the following line to
 dhcpd_flags=
 .Ed
 .Pp
-If instead some options are specified,
-then the dhcpd daemon will be started with those options.
-For example:
+To start it with some options:
 .Bd -literal -offset indent
 dhcpd_flags=-A abandoned
 .Ed
 .Pp
-Other variables specify a simple YES or NO,
-or simply determine the location of a file.
-For example, the location of the ruleset for
-.Xr pf 4
-is given thus:
-.Bd -literal -offset indent
-pf_rules=/etc/pf.conf           # Packet filter rules file
-.Ed
-.Pp
-Finally there is the
-.Va pkg_scripts
-variable, responsible for starting and stopping
-.Xr rc.d 8
-scripts installed by packages in the specified order.
-For example:
-.Bd -literal -offset indent
-pkg_scripts=dbus_daemon cupsd
-.Ed
-.Pp
-This will run
+Run
 .Pa /etc/rc.d/dbus_daemon
 then
 .Pa /etc/rc.d/cupsd
 with the
-.Va start
+.Cm start
 argument at boot time,
 and in reverse order with the
-.Va stop
-argument at shutdown.
+.Cm stop
+argument at shutdown:
+.Bd -literal -offset indent
+pkg_scripts=dbus_daemon cupsd
+.Ed
+.Pp
+The default location of the ruleset for
+.Xr pf 4
+is:
+.Bd -literal -offset indent
+pf_rules=/etc/pf.conf           # Packet filter rules file
+.Ed
 .Sh SEE ALSO
 .Xr init 8 ,
 .Xr intro 8 ,