clarify which of the rc.* files should/should not be edited;

- remove redundant (duplicate) section in afterboot(8)
- limit rc(8) SYNOPSIS to what the page actually describes
- grammar, formatting, etc.
- add FILES to rc(8)
- add securelevel(7) .Xr to SEE ALSO in rc(8)

requested by and ok henning@

2 files changed, 70 insertions, 32 deletions

diff --git a/share/man/man8/afterboot.8 b/share/man/man8/afterboot.8
index a893da5a9da..fed8975fa3b 100644
--- a/share/man/man8/afterboot.8
+++ b/share/man/man8/afterboot.8
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: afterboot.8,v 1.92 2004/07/07 06:01:02 henning Exp $
+.\"	$OpenBSD: afterboot.8,v 1.93 2004/07/08 10:56:22 jmc Exp $
 .\"
 .\" Copyright (c) 1997 Marshall M. Midden
 .\" All rights reserved.
@@ -136,15 +136,6 @@ Set the current date to January 27th, 1999 3:04pm:
 .Pp
 Set the time zone to Atlantic Standard Time:
 .Dl # ln -fs /usr/share/zoneinfo/Canada/Atlantic /etc/localtime
-.Ss System daemon configuration database
-The file
-.Pa /etc/rc.conf
-is used to configure the system daemons.
-Administrators should make changes to the default settings by editing a
-separate file,
-.Pa /etc/rc.conf.local
-.Pq this may need to be created from scratch .
-Values can then be added in as desired.
 .Ss Check hostname
 Use the
 .Ic hostname
@@ -465,14 +456,39 @@ Follow instructions for
 if using
 Kerberos
 for authentication.
-.Ss rc.conf, rc.conf.local, rc.local, rc.securelevel, rc.shutdown
-Check for any local changes needed in the files
-.Pa /etc/rc.conf ,
-.Pa /etc/rc.local ,
+.Ss System command scripts
+The
+.Pa /etc/rc.*\&
+scripts are invoked at boot time, after single user mode has exited,
+and at shutdown.
+The whole process is controlled, more or less, by the master script
+.Pa /etc/rc .
+This script should not be changed by administrators.
+.Pp
+.Pa /etc/rc
+is in turn influenced by the configuration variables present in
+.Pa /etc/rc.conf .
+Again this script should not be changed by administrators:
+site-specific changes should be made to
+.Pq freshly created if necessary
+.Pa /etc/rc.conf.local .
+.Pp
+Any commands which should be run before the system sets its
+secure level should be made to
 .Pa /etc/rc.securelevel ,
-and
+and commands to be run after the system sets its
+secure level should be made to
+.Pa /etc/rc.local .
+Commands to be run before system shutdown should be set in
 .Pa /etc/rc.shutdown .
 .Pp
+For more information about system startup/shutdown files, see
+.Xr rc 8 ,
+.Xr rc.conf 8 ,
+.Xr securelevel 7 ,
+and
+.Xr rc.shutdown 8 .
+.Pp
 If you've installed X, you may want to turn on
 .Xr xdm 1 ,
 the X Display Manager.
diff --git a/share/man/man8/rc.8 b/share/man/man8/rc.8
index 954c674ac95..4ba79ef556c 100644
--- a/share/man/man8/rc.8
+++ b/share/man/man8/rc.8
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: rc.8,v 1.21 2003/07/29 12:42:37 jmc Exp $
+.\"	$OpenBSD: rc.8,v 1.22 2004/07/08 10:56:22 jmc Exp $
 .\"
 .\" Copyright (c) 1980, 1991, 1993
 .\"	The Regents of the University of California.  All rights reserved.
@@ -37,21 +37,18 @@
 .Nd command scripts for system startup
 .Sh SYNOPSIS
 .Nm /etc/rc
-.Nm /etc/rc.conf
 .Nm /etc/rc.local
 .Nm /etc/rc.securelevel
-.Nm /etc/netstart
-.Nm /etc/rc.shutdown
 .Sh DESCRIPTION
 .Nm rc
 is the command script that is invoked by
 .Xr init 8
 during an automatic reboot and after single user mode is exited;
 it performs system housekeeping chores and starts up system daemons.
-As well,
+Additionally,
 .Nm rc
 is intricately tied to the
-.Nm netstart
+.Xr netstart 8
 script, which runs commands and daemons pertaining to the network.
 The
 .Nm rc.securelevel
@@ -61,8 +58,10 @@ scripts hold commands which are pertinent only to a specific site.
 .Pp
 All four of these startup scripts are (or can be) controlled to some
 extent by variables defined in
-.Nm rc.conf ,
-which specifies which daemons and services are to be run.
+.Xr rc.conf 8
+and
+.Xr rc.conf.local 8 ,
+which specify which daemons and services to run.
 .Pp
 When an automatic reboot is in progress,
 .Nm rc
@@ -97,7 +96,7 @@ which is run after an auto-reboot succeeds and also if
 is invoked when a single user shell terminates (see
 .Xr init 8 ) ,
 then asks
-.Nm rc.conf
+.Xr rc.conf 8
 for configuration variables,
 mounts filesystems, starts system daemons,
 preserves editor files,
@@ -116,25 +115,28 @@ is executed.
 .Nm rc.securelevel
 is executed by
 .Nm rc
-to start daemons that must run before the security level changes.
+to start daemons that must be run before the security level changes.
 Following this,
 .Nm rc
 then sets the security level to the value specified in the
 .Va securelevel
 variable in that file.
+See
+.Xr securelevel 7
+for the effects of setting the security level.
 .Pp
 .Nm rc.local
 is executed towards the end of
 .Nm rc
 (it is not the very last as there are a few services that must be
-the started at the very end).
+started at the very end).
 Normally,
 .Nm rc.local
 contains commands and daemons that are not part of the
 stock installation.
 .Sh CONFIGURATION EXAMPLES
 The
-.Nm rc.conf
+.Xr rc.conf 8
 file contains a series of Bourne-shell syntax assignments that
 are used to configure kernel configurations, network configuration,
 and various other system daemons.
@@ -143,14 +145,14 @@ As described above, this file is sourced (using
 of course) by
 .Pa /etc/rc .
 Various comments in
-.Nm rc.conf
+.Xr rc.conf 8
 make it clear what each variable does.
 Refer to the specific man pages for each daemon to determine what that
 subsystem does.
 .Pp
 For example, the
 .Xr lpd 8
-daemon is controlled by the line
+daemon is controlled by the following line:
 .Bd -literal -offset indent
 lpd_flags=NO        # for normal use: "" (or "-l" for debugging)
 .Ed
@@ -160,7 +162,7 @@ This does not start
 at system startup.
 To start
 .Xr lpd 8 ,
-the following entry can be used.
+the following entry can be used:
 .Bd -literal -offset indent
 lpd_flags=""        # for normal use: "" (or "-l" for debugging)
 .Ed
@@ -169,7 +171,7 @@ Alternately,
 .Xr lpd 8
 can be started with the
 .Fl l
-flag (to log remote connections).
+flag (to log remote connections):
 .Bd -literal -offset indent
 lpd_flags="-l"      # for normal use: "" (or "-l" for debugging)
 .Ed
@@ -181,10 +183,30 @@ starts
 it sets the process priority, umask, and resource limits according to the
 .Dq daemon
 login class as described in
-.Pa /etc/login.conf .
+.Xr login.conf 5 .
+.Sh FILES
+.Bl -tag -width "/etc/rc.securelevelXX" -compact
+.It /etc/rc
+Command scripts for system startup.
+.It /etc/rc.local
+Site specific command scripts for system startup.
+.It /etc/rc.conf
+System daemon configuration database.
+.It /etc/rc.conf.local
+Site specific daemon configuration database.
+.It /etc/rc.securelevel
+Commands run before the security level changes.
+.It /etc/rc.shutdown
+Commands run at system shutdown.
+.It /etc/login.conf
+Login class capability database.
+.It /etc/netstart
+Command script for network startup.
+.El
 .Sh SEE ALSO
 .Xr login.conf 5 ,
 .Xr sysctl.conf 5 ,
+.Xr securelevel 7 ,
 .Xr init 8 ,
 .Xr netstart 8 ,
 .Xr rc.conf 8 ,