doas needs doas.conf

[Jan Stary]

Say explicitly that doas needs doas.conf to exist,
and point to the example one.

        Jan


Index: doas.1
===================================================================
RCS file: /cvs/src/usr.bin/doas/doas.1,v
retrieving revision 1.25
diff -u -p -r1.25 doas.1
--- doas.1 16 Jan 2021 09:18:41 -0000 1.25
+++ doas.1 19 Feb 2021 19:20:58 -0000
@@ -43,6 +43,15 @@ is specified.
 The user will be required to authenticate by entering their password,
 unless configured otherwise.
 .Pp
+.Nm
+will not execute the
+.Ar command
+if the file
+.Pa /etc/doas.conf
+does not exist.
+An example is provided in
+.Pa /etc/examples/ .
+.Pp
 By default, a new environment is created.
 The variables
 .Ev HOME ,
@@ -110,6 +119,11 @@ or
 Execute the command as
 .Ar user .
 The default is root.
+.El
+.Sh FILES
+.Bl -tag -compact
+.It Pa /etc/doas.conf
+.It Pa /etc/examples/doas.conf
 .El
 .Sh EXIT STATUS
 .Ex -std doas

[Theo de Raadt-2]

Jan Stary <[hidden email]> wrote:

> Say explicitly that doas needs doas.conf to exist,
> and point to the example one.
>
> Jan
>
>
> Index: doas.1
> ===================================================================
> RCS file: /cvs/src/usr.bin/doas/doas.1,v
> retrieving revision 1.25
> diff -u -p -r1.25 doas.1
> --- doas.1 16 Jan 2021 09:18:41 -0000 1.25
> +++ doas.1 19 Feb 2021 19:20:58 -0000
> @@ -43,6 +43,15 @@ is specified.
>  The user will be required to authenticate by entering their password,
>  unless configured otherwise.
>  .Pp
> +.Nm
> +will not execute the
> +.Ar command
> +if the file
> +.Pa /etc/doas.conf
> +does not exist.

I disagree.  It is immediately obvious that doas requires explicit
configuration.

In use, this is quickly discovered by trying to use doas:

% doas sadf
doas: doas is not enabled, /etc/doas.conf: No such file or directory

I think you took some time trying to figure out where to add the sentence.
Early on it does not work.  But later on, I think it doesn't work either.

Some text which might work would be

    The doas utility executes the given command as another user, based
    upon explicit configuration.
or
    The doas utility executes the given command as another user, based
    upon explicit configuration in /etc/doas.conf.

> +An example is provided in
> +.Pa /etc/examples/ .
> +.Pp
...
> +.Sh FILES
> +.Bl -tag -compact
> +.It Pa /etc/doas.conf
> +.It Pa /etc/examples/doas.conf
>  .El

This is already documented in doas.conf(5)

FILES
     /etc/doas.conf           doas(1) configuration file.
     /etc/examples/doas.conf  Example configuration file.

That is how we do it in other subsystems, for example bgpd(8) mentions

    FILES
         /etc/bgpd.conf         default bgpd configuration file
         /var/run/bgpd.sock     default bgpd control socket
   
    SEE ALSO
         bgpd.conf(5), bgpctl(8), bgplg(8), bgplgsh(8)
   
and then bgpd.conf(5) points at the example

    FILES
         /etc/bgpd.conf           bgpd(8) configuration file.
         /etc/examples/bgpd.conf  Example configuration file.

We have intentionally documented the examples at the end of the
documentation chain.  Noone should be looking at or using an example
configuration, until they have completed reading the configuration docs.
The use of examples without comprehension is very dangerous, and nearly
stopped us from including examples at all...