new rc.conf(8) manual

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

new rc.conf(8) manual

Ingo Schwarze
Hi,

while working on rcctl(8), i noticed that the rc.conf(8) manual
is of...  err, how can i express it politely...  somewhat doubtful
quality.  Here is a stab at it.

As a first step, i moved all the examples from the DESCRIPTION to
the EXAMPLES esction.  After that, the DESCRIPTION section was
basically empty, so i had clean earth to till.

Do not attempt to read the diff.  Just apply it and read the result.

OK?
  Ingo


Index: rc.conf.8
===================================================================
RCS file: /cvs/src/share/man/man8/rc.conf.8,v
retrieving revision 1.22
diff -u -r1.22 rc.conf.8
--- rc.conf.8 13 Jul 2014 10:05:49 -0000 1.22
+++ rc.conf.8 19 Aug 2014 20:30:41 -0000
@@ -59,10 +59,162 @@
 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
+There are four classes of variables:
+.Bl -enum -compact
+.It
+.Sx Base system daemon configuration variables
+.It
+.Sx Package daemon configuration variables
+.It
+.Sx Base system service configuration variables
+.It
+.Sx Auxiliary configuration variables
+.El
+.Ss Base system daemon configuration variables
+These 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.
+.Ss Package daemon configuration variables
+These 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 for
+.Sx Base system daemon configuration variables .
+.Ss Base system service configuration variables
+These 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
+.Xr rc 8
+calls:
+.Xr accton 8
+.Pa /var/account/acct
+.It Cm check_quotas
+.Xr rc 8
+calls:
+.Xr quotacheck 8
+.Fl a ;
+.Xr quotaon 8
+.Fl a
+.It Cm ipsec
+.Xr rc 8
+calls:
+.Xr ipsecctl 8
+.Fl f Pf $ Brq Ar ipsec_rules
+.It Cm multicast_host , multicast_router
+See
+.Xr netstart 8 .
+.It Cm pf
+.Xr rc 8
+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
+.Ss Auxiliary configuration variables
+The boot scripts use the following variables in the following ways.
+Most of them determine the locations of specific configuration files.
+.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,
+.Xr rc 8
+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,
+.Xr rc 8
+calls:
+.Xr ipsecctl 8
+.Fl f
+.Pf $ Brq Ar ipsec_rules
+.It Cm shlib_dirs
+Extra shared library search path entries.
+.Xr rc 8
+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 +226,31 @@
 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 ,

Reply | Threaded
Open this post in threaded view
|

Re: new rc.conf(8) manual

Robert Peichaer
On Tue, Aug 19, 2014 at 10:44:54PM +0200, Ingo Schwarze wrote:

> Hi,
>
> while working on rcctl(8), i noticed that the rc.conf(8) manual
> is of...  err, how can i express it politely...  somewhat doubtful
> quality.  Here is a stab at it.
>
> As a first step, i moved all the examples from the DESCRIPTION to
> the EXAMPLES esction.  After that, the DESCRIPTION section was
> basically empty, so i had clean earth to till.
>
> Do not attempt to read the diff.  Just apply it and read the result.
>
> OK?
>   Ingo

Hi Ingo

In the "Base system daemon configuration variables" section, in the
last paragraph this is incorrect.

... including a string containing only a single blank character, ...

Looking at the _rc_parse_conf() code in rc.subr says, that any leading
and trailing blanks on the value side of key=value get stripped away.

And maybe it's worth a note that in case of multiple lines with the same
key, only the last is used.

Besides that OK rpe@

Reply | Threaded
Open this post in threaded view
|

Re: new rc.conf(8) manual

Ingo Schwarze
Hi Robert,

Robert Peichaer wrote on Wed, Aug 20, 2014 at 12:39:51AM +0200:

> In the "Base system daemon configuration variables" section, in the
> last paragraph this is incorrect.
>
> ... including a string containing only a single blank character, ...
>
> Looking at the _rc_parse_conf() code in rc.subr says, that any leading
> and trailing blanks on the value side of key=value get stripped away.

ischwarze@isnote $ grep ^tftpd /etc/rc.conf.local            
tftpd_flags=" "
ischwarze@isnote $ sudo /etc/rc.d/tftpd -d start > /dev/null
usage: tftpd [-46cdv] [-l address] [-p port] [-r socket] directory
ischwarze@isnote $ sudoedit /etc/rc.conf.local
ischwarze@isnote $ grep ^tftpd /etc/rc.conf.local            
tftpd_flags=""
ischwarze@isnote $ sudo /etc/rc.d/tftpd -d start > /dev/null
ischwarze@isnote $ ps ax | grep tftp
 8194 ??  Is      0:00.00 /usr/sbin/tftpd /tftpboot

Works for me...

I don't understand why it doesn't work for you.

> And maybe it's worth a note that in case of multiple lines with the same
> key, only the last is used.

Well, you might already implicitly conclude that from the second
paragraph:

     It is advisable to leave rc.conf untouched, and instead create
     and edit a new rc.conf.local file.  Variables set in this file
     will override variables previously set in rc.conf.

But we could make that more explicit:

     It is advisable to leave rc.conf untouched, and instead create
     and edit a new rc.conf.local file.  Since only the last assignment
     to any variable takes effect, variables set in this file override
     variables previously set in rc.conf.

> Besides that OK rpe@

Thanks for checking!

Yours,
  Ingo