On Thu, Apr 30, 2020 at 07:13:16PM +0200, clematis wrote:
> Hello,
>
> Following the previous thread about /etc/examples/doas.conf [1] ,
> I've noticed those example files aren't always listed in their
> respective manpage or without a description.
> This has been discussed here recently for bgpd.conf [2].
> Also noticed updates for some of them like acme-client.conf [3].
>
> Taking into account those email threads I would suggest the changes
> below:
>
> Adding FILES section with description for:
> - /usr.sbin/dhcpd/dhcpd.conf.5
> - /usr.sbin/httpd/httpd.conf.5
>
> Adding short description for:
> - /sbin/iked/iked.conf.5
> - /usr.sbin/inetd/inetd.8
> - /sbin/ipsecctl/ipsec.conf.5
> - /usr.bin/mandoc/man.conf.5
> - /usr.sbin/sasyncd/sasyncd.conf.5
> - /share/man/man5/sysctl.conf.5
> - /usr.sbin/vmd/vm.conf.5
> - /share/man/man5/wsconsctl.conf.5
>
> Other changes:
> - /usr.sbin/mrouted/mrouted.8
> +.Nm mrouted.conf + short description
> - /usr.sbin/rbootd/rbootd.8
> +.Nm rbootd.conf + minor description update
> - /share/man/man8/rc.shutdown.8
> adding example file + description
>
> The others examples file' man pages looked OK and consistent with
> this approach.
>
> Diff attached to this email. Please let me know if adjustments have to
> be made.
>
> [1] https://marc.info/?t=158783671100001&r=1&w=2
> [2] https://marc.info/?t=158120503900002&r=1&w=2
> [3]
> https://cvsweb.openbsd.org/cgi-bin/cvsweb/src/usr.sbin/acme-client/acme-client.conf.5.diff?r1=1.21&r2=1.22&f=h
>
> Thanks,
>
> --
> clematis (0xA2C87EDB507B4C53)
hi.
i'm broadly in favour. having said that, i have a horrible feeling this
has come up before and there was some reason not to.
supposing that no one has such a reason, i'd be happy to fix this.
however one thing bugs me - i don;t think the description in FILES
should attempt to outline the contents. it will just go out of date and
even if it doesn't, it's not the place. too wordy. i'd prefer to just
use a single, consistent, description. like "Example configuration
file." or somesuch.
jmc
> Index: dhcpd.conf.5
> ===================================================================
> RCS file: /cvs/src/usr.sbin/dhcpd/dhcpd.conf.5,v
> retrieving revision 1.25
> diff -u -p -r1.25 dhcpd.conf.5
> --- dhcpd.conf.5 17 Apr 2020 06:24:28 -0000 1.25
> +++ dhcpd.conf.5 30 Apr 2020 16:13:27 -0000
> @@ -885,6 +885,15 @@ the DHCP ACK or NAK reply sent to the cl
> DHCP option statements are documented in the
> .Xr dhcp-options 5
> manual page.
> +.Sh FILES
> +.Bl -tag -width /etc/examples/dhcpd.conf -compact
> +.It Pa /etc/dhcpd.conf
> +Default
> +.Xr dhcpd 8
> +configuration file.
> +.It Pa /etc/examples/dhcpd.conf
> +Example configuration file.
> +.El
> .Sh SEE ALSO
> .Xr dhcp-options 5 ,
> .Xr dhcpd.leases 5 ,
> Index: httpd.conf.5
> ===================================================================
> RCS file: /cvs/src/usr.sbin/httpd/httpd.conf.5,v
> retrieving revision 1.110
> diff -u -p -r1.110 httpd.conf.5
> --- httpd.conf.5 23 Apr 2020 21:10:53 -0000 1.110
> +++ httpd.conf.5 30 Apr 2020 16:16:57 -0000
> @@ -796,6 +796,15 @@ server "example.com" {
> }
> }
> .Ed
> +.Sh FILES
> +.Bl -tag -width /etc/examples/httpd.conf -compact
> +.It Pa /etc/httpd.conf
> +Default
> +.Xr httpd 8
> +configuration file.
> +.It Pa /etc/examples/httpd.conf
> +Example configuration file.
> +.El
> .Sh SEE ALSO
> .Xr htpasswd 1 ,
> .Xr patterns 7 ,
> Index: iked.conf.5
> ===================================================================
> RCS file: /cvs/src/sbin/iked/iked.conf.5,v
> retrieving revision 1.67
> diff -u -p -r1.67 iked.conf.5
> --- iked.conf.5 28 Apr 2020 15:18:52 -0000 1.67
> +++ iked.conf.5 30 Apr 2020 16:14:17 -0000
> @@ -937,7 +937,11 @@ backwards compatibility.
> .Sh FILES
> .Bl -tag -width /etc/examples/iked.conf -compact
> .It Pa /etc/iked.conf
> +Default
> +.Xr iked 8
> +configuration file.
> .It Pa /etc/examples/iked.conf
> +Example configuration file for EAP or pre-shared key authentification.
> .El
> .Sh EXAMPLES
> The first example is intended for a server with clients connecting to
> Index: inetd.8
> ===================================================================
> RCS file: /cvs/src/usr.sbin/inetd/inetd.8,v
> retrieving revision 1.42
> diff -u -p -r1.42 inetd.8
> --- inetd.8 10 Feb 2020 13:18:21 -0000 1.42
> +++ inetd.8 30 Apr 2020 16:19:39 -0000
> @@ -361,7 +361,11 @@ only IPv6 traffic will be routed to the
> .Sh FILES
> .Bl -tag -width /etc/examples/inetd.conf -compact
> .It Pa /etc/inetd.conf
> +Default
> +.Xr inetd 8
> +configuration file.
> .It Pa /etc/examples/inetd.conf
> +Example configuration file.
> .El
> .Sh SEE ALSO
> .Xr comsat 8 ,
> Index: ipsec.conf.5
> ===================================================================
> RCS file: /cvs/src/sbin/ipsecctl/ipsec.conf.5,v
> retrieving revision 1.159
> diff -u -p -r1.159 ipsec.conf.5
> --- ipsec.conf.5 16 Feb 2020 11:28:28 -0000 1.159
> +++ ipsec.conf.5 30 Apr 2020 16:15:24 -0000
> @@ -994,7 +994,13 @@ and
> .Sh FILES
> .Bl -tag -width /etc/examples/ipsec.conf -compact
> .It Pa /etc/ipsec.conf
> +Default configuration file.
> .It Pa /etc/examples/ipsec.conf
> +Example configuration file setting up tunnels with
> +.Xr isakmpd 8
> +or using the
> +.Xr ipsecctl 8
> +utility.
> .El
> .Sh SEE ALSO
> .Xr openssl 1 ,
> Index: man.conf.5
> ===================================================================
> RCS file: /cvs/src/usr.bin/mandoc/man.conf.5,v
> retrieving revision 1.8
> diff -u -p -r1.8 man.conf.5
> --- man.conf.5 10 Feb 2020 14:42:03 -0000 1.8
> +++ man.conf.5 30 Apr 2020 16:20:56 -0000
> @@ -105,7 +105,12 @@ manual.
> .Sh FILES
> .Bl -tag -width /etc/examples/man.conf -compact
> .It Pa /etc/man.conf
> +Default
> +.Xr man 1
> +configuration file.
> .It Pa /etc/examples/man.conf
> +Example configuration file illustrating possible search path ordering and
> +output options.
> .El
> .Sh EXAMPLES
> The following configuration file reproduces the defaults:
> Index: mrouted.8
> ===================================================================
> RCS file: /cvs/src/usr.sbin/mrouted/mrouted.8,v
> retrieving revision 1.27
> diff -u -p -r1.27 mrouted.8
> --- mrouted.8 10 Feb 2020 13:18:21 -0000 1.27
> +++ mrouted.8 30 Apr 2020 16:18:32 -0000
> @@ -10,6 +10,7 @@
> .Os
> .Sh NAME
> .Nm mrouted
> +.Nm mrouted.conf
> .Nd IP multicast routing daemon
> .Sh SYNOPSIS
> .Nm mrouted
> @@ -347,9 +348,15 @@ was invoked with a non-zero debug level)
> .Sh FILES
> .Bl -tag -width /etc/examples/mrouted.conf -compact
> .It Pa /etc/mrouted.conf
> +Default
> +.Xr mrouted 8
> +configuration file.
> .It Pa /etc/examples/mrouted.conf
> +Example configuration file.
> .It Pa /var/tmp/mrouted.cache
> +Internal cache tables.
> .It Pa /var/tmp/mrouted.dump
> +Internal routing tables.
> .El
> .Sh EXAMPLES
> The routing tables look like this:
> Index: rbootd.8
> ===================================================================
> RCS file: /cvs/src/usr.sbin/rbootd/rbootd.8,v
> retrieving revision 1.18
> diff -u -p -r1.18 rbootd.8
> --- rbootd.8 10 Feb 2020 13:18:21 -0000 1.18
> +++ rbootd.8 30 Apr 2020 16:25:20 -0000
> @@ -46,6 +46,7 @@
> .Os
> .Sh NAME
> .Nm rbootd
> +.Nm rbootd.conf
> .Nd HP remote boot server
> .Sh SYNOPSIS
> .Nm rbootd
> @@ -138,6 +139,8 @@ Turn off debugging, do nothing if alread
> .It Pa /dev/bpf
> packet-filter device
> .It Pa /etc/rbootd.conf
> +default
> +.Xr rbootd 8
> configuration file
> .It Pa /etc/examples/rbootd.conf
> example configuration file
> Index: rc.shutdown.8
> ===================================================================
> RCS file: /cvs/src/share/man/man8/rc.shutdown.8,v
> retrieving revision 1.15
> diff -u -p -r1.15 rc.shutdown.8
> --- rc.shutdown.8 13 Jul 2017 19:16:33 -0000 1.15
> +++ rc.shutdown.8 30 Apr 2020 16:26:49 -0000
> @@ -74,9 +74,11 @@ is exiting single-user mode it will also
> (saving random data),
> though not the latter.
> .Sh FILES
> -.Bl -tag -width "/etc/rc.shutdown"
> +.Bl -tag -width /etc/examples/rc.shutdown -compact
> .It Pa /etc/rc.shutdown
> Command script run at system shutdown.
> +.It Pa /etc/examples/rc.shutdown
> +Example script to run at system shutdown.
> .El
> .Sh SEE ALSO
> .Xr init 8 ,
> Index: sasyncd.conf.5
> ===================================================================
> RCS file: /cvs/src/usr.sbin/sasyncd/sasyncd.conf.5,v
> retrieving revision 1.19
> diff -u -p -r1.19 sasyncd.conf.5
> --- sasyncd.conf.5 10 Feb 2020 13:18:22 -0000 1.19
> +++ sasyncd.conf.5 30 Apr 2020 16:28:05 -0000
> @@ -179,7 +179,12 @@ or to turn it off to synchronize SAs onl
> .Sh FILES
> .Bl -tag -width /etc/examples/sasyncd.conf -compact
> .It Pa /etc/sasyncd.conf
> +Default
> +.Xr sasyncd 8
> +configuration file.
> .It Pa /etc/examples/sasyncd.conf
> +Example configuration file with identification of peers and shared AES
> +key.
> .El
> .Sh SEE ALSO
> .Xr chmod 1 ,
> Index: sysctl.conf.5
> ===================================================================
> RCS file: /cvs/src/share/man/man5/sysctl.conf.5,v
> retrieving revision 1.14
> diff -u -p -r1.14 sysctl.conf.5
> --- sysctl.conf.5 10 Feb 2020 13:18:20 -0000 1.14
> +++ sysctl.conf.5 30 Apr 2020 16:29:54 -0000
> @@ -37,7 +37,11 @@ with comments designated by a hash mark
> .Sh FILES
> .Bl -tag -width /etc/examples/sysctl.conf -compact
> .It Pa /etc/sysctl.conf
> +Default
> +.Xr sysctl 8
> +variables to set at system startup.
> .It Pa /etc/examples/sysctl.conf
> +Example configuration file illustrating a few available variables.
> .El
> .Sh EXAMPLES
> To turn on IP forwarding, one would use the following line:
> Index: vm.conf.5
> ===================================================================
> RCS file: /cvs/src/usr.sbin/vmd/vm.conf.5,v
> retrieving revision 1.53
> diff -u -p -r1.53 vm.conf.5
> --- vm.conf.5 16 Feb 2020 11:03:25 -0000 1.53
> +++ vm.conf.5 30 Apr 2020 16:31:08 -0000
> @@ -454,7 +454,11 @@ Stop the switch from forwarding packets.
> .Sh FILES
> .Bl -tag -width /etc/examples/vm.conf -compact
> .It Pa /etc/vm.conf
> +Default configuration file to setup the
> +.Xr vmm 4
> +subsystem.
> .It Pa /etc/examples/vm.conf
> +Example configuration file.
> .El
> .Sh EXAMPLES
> Create a new VM with 1GB memory, 1 network interface connected to
> Index: wsconsctl.conf.5
> ===================================================================
> RCS file: /cvs/src/share/man/man5/wsconsctl.conf.5,v
> retrieving revision 1.7
> diff -u -p -r1.7 wsconsctl.conf.5
> --- wsconsctl.conf.5 10 Feb 2020 13:18:20 -0000 1.7
> +++ wsconsctl.conf.5 30 Apr 2020 16:31:56 -0000
> @@ -52,7 +52,13 @@ with comments designated by a hash mark
> .Sh FILES
> .Bl -tag -width /etc/examples/wsconsctl.conf -compact
> .It Pa /etc/wsconsctl.conf
> +Default
> +.Xr wsconsctl 8
> +configuration file.
> .It Pa /etc/examples/wsconsctl.conf
> +Example
> +.Xr wsconsctl 8
> +keyboard and display configurable parameters to set at system startup.
> .El
> .Sh EXAMPLES
> To load a Russian keyboard encoding, one would use the following line:
