Re: Diff to stop using reserved words for smtpd.conf(5) examples
On Wed, Jul 24, 2019 at 09:28:26AM -0400, Kurt Mosiejczuk wrote: > Here's a diff that does that. Thanks, OK kn.
Re: Diff to stop using reserved words for smtpd.conf(5) examples
Hi Kurt, Kurt Mosiejczuk wrote on Wed, Jul 24, 2019 at 09:28:26AM -0400: > On Wed, Jul 24, 2019 at 02:17:47PM +0200, Klemens Nanni wrote: >> On Wed, Jul 24, 2019 at 01:32:52PM +0200, Gilles Chehade wrote: >>> Well I think we should remove the reserved keywords as suggested by Kurt >>> but keep the quotes in all examples to make it very explicit that we are >>> expecting a string literal at this point. >> I concur. > Here's a diff that does that. Looks good to me. Ingo > Index: etc/mail/smtpd.conf > === > RCS file: /cvs/src/etc/mail/smtpd.conf,v > retrieving revision 1.11 > diff -u -p -r1.11 smtpd.conf > --- etc/mail/smtpd.conf 4 Jun 2018 21:10:58 - 1.11 > +++ etc/mail/smtpd.conf 24 Jul 2019 13:20:51 - > @@ -9,11 +9,11 @@ table aliases file:/etc/mail/aliases > # > listen on lo0 > > -action "local" mbox alias > -action "relay" relay > +action "local_mail" mbox alias > +action "outbound" relay > > # Uncomment the following to accept external mail for domain "example.org" > # > -# match from any for domain "example.org" action "local" > -match for local action "local" > -match for any action "relay" > +# match from any for domain "example.org" action "local_mail" > +match for local action "local_mail" > +match for any action "outbound" > Index: usr.sbin/smtpd/smtpd.conf.5 > === > RCS file: /cvs/src/usr.sbin/smtpd/smtpd.conf.5,v > retrieving revision 1.210 > diff -u -p -r1.210 smtpd.conf.5 > --- usr.sbin/smtpd/smtpd.conf.5 22 Dec 2018 08:54:02 - 1.210 > +++ usr.sbin/smtpd/smtpd.conf.5 24 Jul 2019 13:20:51 - > @@ -871,12 +871,12 @@ table secrets file:/etc/mail/secrets > > listen on lo0 > > -action "local" mbox alias > -action "relay" relay host smtp+tls://b...@smtp.example.com \e > +action "local_mail" mbox alias > +action "outbound" relay host smtp+tls://b...@smtp.example.com \e > auth > > -match for local action "local" > -match for any action "relay" > +match for local action "local_mail" > +match for any action "outbound" > .Ed > .Pp > In this second example, > @@ -908,12 +908,12 @@ listen on egress tls pki mail.example.co > > action mda_with_aliases mda "/path/to/mda \-f \-" alias > action mda_without_aliases mda "/path/to/mda \-f \-" > -action "relay" relay > +action "outbound" relay > > match for local action mda_with_aliases > match from any for domain example.com action mda_without_aliases > -match for any action "relay" > -match auth from any for any action "relay" > +match for any action "outbound" > +match auth from any for any action "outbound" > .Ed > .Pp > For sites that wish to sign messages using DKIM, the > @@ -929,13 +929,13 @@ table aliases file:/etc/mail/aliases > listen on lo0 > listen on lo0 port 10028 tag DKIM > > -action "mbox" mbox alias > -action "relay" relay > -action relay_dkim relay host smtp://127.0.0.1:10027 > - > -match for local action "mbox" > -match tag DKIM for any action "relay" > -match for any action relay_dkim > +action "local_mail" mbox alias > +action "outbound" relay > +action "relay_dkim" relay host smtp://127.0.0.1:10027 > + > +match for local action "local_mail" > +match tag DKIM for any action "outbound" > +match for any action "relay_dkim" > .Ed > .Pp > Sites that accept non-local messages may be able to cut down on the > @@ -952,14 +952,14 @@ table other-relays file:/etc/mail/other- > listen on lo0 > listen on egress > > -action "mbox" mbox alias > -action "relay" relay > +action "local_mail" mbox alias > +action "outbound" relay > > -match for local action "mbox" > -match for any action "relay" > +match for local action "local_mail" > +match for any action "outbound" > match !from src mail\-from "@example.com" for any \e >reject > -match from any for domain example.com action "mbox" > +match from any for domain example.com action "local_mail" > .Ed > .Sh SEE ALSO > .Xr mailer.conf 5 ,
Re: Diff to stop using reserved words for smtpd.conf(5) examples
Yep, this keeps the quotes around the labels, and shows how the labels would be used in a real configuration. the ambiguity is gone. Imagine if other example files had stuff like table "table" something "something" Kurt Mosiejczuk wrote: > On Wed, Jul 24, 2019 at 02:17:47PM +0200, Klemens Nanni wrote: > > On Wed, Jul 24, 2019 at 01:32:52PM +0200, Gilles Chehade wrote: > > > > Well I think we should remove the reserved keywords as suggested by Kurt > > > but keep the quotes in all examples to make it very explicit that we are > > > expecting a string literal at this point. > > > I concur. > > Here's a diff that does that. > > --Kurt > > Index: etc/mail/smtpd.conf > === > RCS file: /cvs/src/etc/mail/smtpd.conf,v > retrieving revision 1.11 > diff -u -p -r1.11 smtpd.conf > --- etc/mail/smtpd.conf 4 Jun 2018 21:10:58 - 1.11 > +++ etc/mail/smtpd.conf 24 Jul 2019 13:20:51 - > @@ -9,11 +9,11 @@ table aliases file:/etc/mail/aliases > # > listen on lo0 > > -action "local" mbox alias > -action "relay" relay > +action "local_mail" mbox alias > +action "outbound" relay > > # Uncomment the following to accept external mail for domain "example.org" > # > -# match from any for domain "example.org" action "local" > -match for local action "local" > -match for any action "relay" > +# match from any for domain "example.org" action "local_mail" > +match for local action "local_mail" > +match for any action "outbound" > Index: usr.sbin/smtpd/smtpd.conf.5 > === > RCS file: /cvs/src/usr.sbin/smtpd/smtpd.conf.5,v > retrieving revision 1.210 > diff -u -p -r1.210 smtpd.conf.5 > --- usr.sbin/smtpd/smtpd.conf.5 22 Dec 2018 08:54:02 - 1.210 > +++ usr.sbin/smtpd/smtpd.conf.5 24 Jul 2019 13:20:51 - > @@ -871,12 +871,12 @@ table secrets file:/etc/mail/secrets > > listen on lo0 > > -action "local" mbox alias > -action "relay" relay host smtp+tls://b...@smtp.example.com \e > +action "local_mail" mbox alias > +action "outbound" relay host smtp+tls://b...@smtp.example.com \e > auth > > -match for local action "local" > -match for any action "relay" > +match for local action "local_mail" > +match for any action "outbound" > .Ed > .Pp > In this second example, > @@ -908,12 +908,12 @@ listen on egress tls pki mail.example.co > > action mda_with_aliases mda "/path/to/mda \-f \-" alias > action mda_without_aliases mda "/path/to/mda \-f \-" > -action "relay" relay > +action "outbound" relay > > match for local action mda_with_aliases > match from any for domain example.com action mda_without_aliases > -match for any action "relay" > -match auth from any for any action "relay" > +match for any action "outbound" > +match auth from any for any action "outbound" > .Ed > .Pp > For sites that wish to sign messages using DKIM, the > @@ -929,13 +929,13 @@ table aliases file:/etc/mail/aliases > listen on lo0 > listen on lo0 port 10028 tag DKIM > > -action "mbox" mbox alias > -action "relay" relay > -action relay_dkim relay host smtp://127.0.0.1:10027 > - > -match for local action "mbox" > -match tag DKIM for any action "relay" > -match for any action relay_dkim > +action "local_mail" mbox alias > +action "outbound" relay > +action "relay_dkim" relay host smtp://127.0.0.1:10027 > + > +match for local action "local_mail" > +match tag DKIM for any action "outbound" > +match for any action "relay_dkim" > .Ed > .Pp > Sites that accept non-local messages may be able to cut down on the > @@ -952,14 +952,14 @@ table other-relays file:/etc/mail/other- > listen on lo0 > listen on egress > > -action "mbox" mbox alias > -action "relay" relay > +action "local_mail" mbox alias > +action "outbound" relay > > -match for local action "mbox" > -match for any action "relay" > +match for local action "local_mail" > +match for any action "outbound" > match !from src mail\-from "@example.com" for any \e >reject > -match from any for domain example.com action "mbox" > +match from any for domain example.com action "local_mail" > .Ed > .Sh SEE ALSO > .Xr mailer.conf 5 , >
Re: Diff to stop using reserved words for smtpd.conf(5) examples
On Wed, Jul 24, 2019 at 01:32:52PM +0200, Gilles Chehade wrote: > Well I think we should remove the reserved keywords as suggested by Kurt > but keep the quotes in all examples to make it very explicit that we are > expecting a string literal at this point. I concur.
Re: Diff to stop using reserved words for smtpd.conf(5) examples
On Tue, Jul 23, 2019 at 08:51:38PM +0200, Ingo Schwarze wrote: > Hi Gilles, > > Gilles Chehade wrote on Tue, Jul 23, 2019 at 08:27:06AM +0200: > > On Mon, Jul 22, 2019 at 05:05:01PM -0400, Kurt Mosiejczuk wrote: > > >> This is a diff for that changes the example smtpd.conf and smtpd.conf.5 > >> so that it no longer uses words that are parts of the configuration > >> syntax as labels for actions. A large chunk of my delay to a release > >> with the new smtpd.conf configuration syntax was my confusion with the > >> examples. Even writing this diff I realized that the quotes were only > >> necessary in the examples because configuration grammar was being > >> reused as labels. > > > I'll let ingo and jmc comment on this, I think the rationale for > > using the quotes and the reserved words was precisely to show we > > should use the quotes at these places > > I do agree with showing quotes around action names and other > user-selected strings and identifiers. I think it helps understanding > by making keywords easier to distinguish from other, replaceable > strings. Even if in some cases, the syntax does not require the > quotes. > > > and that reserved words in quotes were acceptable. > > The smtpd.conf(5) manual explains that explicitly, and i think it > may make sense to show an example for it, even though i'm unsure > whether the practice of re-using reserved words as user-defined > identifiers should be recommended. > > But Theo's argument that it can be confusing to explain too many > different aspects in the same example makes sense to me, in particular > when the explanation of the example doesn't even mention all the > aspects being demonstrated. Also, Kurt's experience confirms that > this kind of confusion can indeed arise. > > > To be honest, ever since we made these examples, no one has ever > > mailed me with a broken config due to a reserved keyword whereas > > it used to be the case every now and then before. > > So, don't remove the quotes. > > Avoiding clashes that *require* quoting in most of the examples > as Kurt suggests might make sense. I don't feel strongly about > it either way. > > Also, giving one example (maybe at the end?) that explicitly shows > and mentions the possibility of using a quoted reserved word as > a user-selected string might make sense, too. Or maybe not, if > we do not want to encourage it? Do we? Not sure, no strong > feelings about that point either. > > I think there is a lot of room here for you to decide what you > consider good and robust style for writing this particular configuration > file. > Well I think we should remove the reserved keywords as suggested by Kurt but keep the quotes in all examples to make it very explicit that we are expecting a string literal at this point. I would be fine with his diff, where the new table names are enclosed in quotes. I don't think showing or hiding that we can use reserved words is really important, most people don't use reserved words, most people will either change the name or quote appropriately upon parse error, only a very few people need help with this, this is really a marginal case (people share a lot of smtpd.conf with me and I did some calls for sharing config when we were assessing the new configuration file format). -- Gilles Chehade @poolpOrg https://www.poolp.orgpatreon: https://www.patreon.com/gilles
Re: Diff to stop using reserved words for smtpd.conf(5) examples
Hi Gilles, Gilles Chehade wrote on Tue, Jul 23, 2019 at 08:27:06AM +0200: > On Mon, Jul 22, 2019 at 05:05:01PM -0400, Kurt Mosiejczuk wrote: >> This is a diff for that changes the example smtpd.conf and smtpd.conf.5 >> so that it no longer uses words that are parts of the configuration >> syntax as labels for actions. A large chunk of my delay to a release >> with the new smtpd.conf configuration syntax was my confusion with the >> examples. Even writing this diff I realized that the quotes were only >> necessary in the examples because configuration grammar was being >> reused as labels. > I'll let ingo and jmc comment on this, I think the rationale for > using the quotes and the reserved words was precisely to show we > should use the quotes at these places I do agree with showing quotes around action names and other user-selected strings and identifiers. I think it helps understanding by making keywords easier to distinguish from other, replaceable strings. Even if in some cases, the syntax does not require the quotes. > and that reserved words in quotes were acceptable. The smtpd.conf(5) manual explains that explicitly, and i think it may make sense to show an example for it, even though i'm unsure whether the practice of re-using reserved words as user-defined identifiers should be recommended. But Theo's argument that it can be confusing to explain too many different aspects in the same example makes sense to me, in particular when the explanation of the example doesn't even mention all the aspects being demonstrated. Also, Kurt's experience confirms that this kind of confusion can indeed arise. > To be honest, ever since we made these examples, no one has ever > mailed me with a broken config due to a reserved keyword whereas > it used to be the case every now and then before. So, don't remove the quotes. Avoiding clashes that *require* quoting in most of the examples as Kurt suggests might make sense. I don't feel strongly about it either way. Also, giving one example (maybe at the end?) that explicitly shows and mentions the possibility of using a quoted reserved word as a user-selected string might make sense, too. Or maybe not, if we do not want to encourage it? Do we? Not sure, no strong feelings about that point either. I think there is a lot of room here for you to decide what you consider good and robust style for writing this particular configuration file. Yours, Ingo
Re: Diff to stop using reserved words for smtpd.conf(5) examples
Gilles Chehade wrote: > On Mon, Jul 22, 2019 at 05:05:01PM -0400, Kurt Mosiejczuk wrote: > > This is a diff for that changes the example smtpd.conf and smtpd.conf.5 > > so that it no longer uses words that are parts of the configuration > > syntax as labels for actions. A large chunk of my delay to a release > > with the new smtpd.conf configuration syntax was my confusion with the > > examples. Even writing this diff I realized that the quotes were only > > necessary in the examples because configuration grammar was being > > reused as labels. > > > > I'll let ingo and jmc comment on this, I think the rationale for > using the quotes and the reserved words was precisely to show we > should use the quotes at these places and that reserved words in > quotes were acceptable. When trying to provide one lesson (how the configuration blocks work), is it wise to simultaneously show a second lesson? I think you risk confusing people rather than enlightening them.
Re: Diff to stop using reserved words for smtpd.conf(5) examples
On Mon, Jul 22, 2019 at 05:05:01PM -0400, Kurt Mosiejczuk wrote: > This is a diff for that changes the example smtpd.conf and smtpd.conf.5 > so that it no longer uses words that are parts of the configuration > syntax as labels for actions. A large chunk of my delay to a release > with the new smtpd.conf configuration syntax was my confusion with the > examples. Even writing this diff I realized that the quotes were only > necessary in the examples because configuration grammar was being > reused as labels. > I'll let ingo and jmc comment on this, I think the rationale for using the quotes and the reserved words was precisely to show we should use the quotes at these places and that reserved words in quotes were acceptable. To be honest, ever since we made these examples, no one has ever mailed me with a broken config due to a reserved keyword whereas it used to be the case every now and then before. > Index: etc/mail/smtpd.conf > === > RCS file: /cvs/src/etc/mail/smtpd.conf,v > retrieving revision 1.11 > diff -u -p -r1.11 smtpd.conf > --- etc/mail/smtpd.conf 4 Jun 2018 21:10:58 - 1.11 > +++ etc/mail/smtpd.conf 22 Jul 2019 20:58:24 - > @@ -9,11 +9,11 @@ table aliases file:/etc/mail/aliases > # > listen on lo0 > > -action "local" mbox alias > -action "relay" relay > +action local-mail mbox alias > +action inet-mail relay > > # Uncomment the following to accept external mail for domain "example.org" > # > -# match from any for domain "example.org" action "local" > -match for local action "local" > -match for any action "relay" > +# match from any for domain "example.org" action local-mail > +match for local action local-mail > +match for any action inet-mail > Index: usr.sbin/smtpd/smtpd.conf.5 > === > RCS file: /cvs/src/usr.sbin/smtpd/smtpd.conf.5,v > retrieving revision 1.210 > diff -u -p -r1.210 smtpd.conf.5 > --- usr.sbin/smtpd/smtpd.conf.5 22 Dec 2018 08:54:02 - 1.210 > +++ usr.sbin/smtpd/smtpd.conf.5 22 Jul 2019 20:58:24 - > @@ -871,12 +871,12 @@ table secrets file:/etc/mail/secrets > > listen on lo0 > > -action "local" mbox alias > -action "relay" relay host smtp+tls://b...@smtp.example.com \e > +action local-mail mbox alias > +action inet-mail relay host smtp+tls://b...@smtp.example.com \e > auth > > -match for local action "local" > -match for any action "relay" > +match for local action local-mail > +match for any action inet-mail > .Ed > .Pp > In this second example, > @@ -908,12 +908,12 @@ listen on egress tls pki mail.example.co > > action mda_with_aliases mda "/path/to/mda \-f \-" alias > action mda_without_aliases mda "/path/to/mda \-f \-" > -action "relay" relay > +action inet-mail relay > > match for local action mda_with_aliases > match from any for domain example.com action mda_without_aliases > -match for any action "relay" > -match auth from any for any action "relay" > +match for any action inet-mail > +match auth from any for any action inet-mail > .Ed > .Pp > For sites that wish to sign messages using DKIM, the > @@ -929,12 +929,12 @@ table aliases file:/etc/mail/aliases > listen on lo0 > listen on lo0 port 10028 tag DKIM > > -action "mbox" mbox alias > -action "relay" relay > +action local-mbox mbox alias > +action inet-mail relay > action relay_dkim relay host smtp://127.0.0.1:10027 > > -match for local action "mbox" > -match tag DKIM for any action "relay" > +match for local action local-mbox > +match tag DKIM for any action inet-mail > match for any action relay_dkim > .Ed > .Pp > @@ -952,14 +952,14 @@ table other-relays file:/etc/mail/other- > listen on lo0 > listen on egress > > -action "mbox" mbox alias > -action "relay" relay > +action local-mbox mbox alias > +action inet-mail relay > > -match for local action "mbox" > -match for any action "relay" > +match for local action local-mbox > +match for any action inet-mail > match !from src mail\-from "@example.com" for any \e >reject > -match from any for domain example.com action "mbox" > +match from any for domain example.com action local-mbox > .Ed > .Sh SEE ALSO > .Xr mailer.conf 5 , > -- Gilles Chehade @poolpOrg https://www.poolp.orgpatreon: https://www.patreon.com/gilles
Re: Diff to stop using reserved words for smtpd.conf(5) examples
On Mon, Jul 22, 2019 at 05:25:28PM -0400, Kurt Mosiejczuk wrote: > If you look at the existing man page, it is left off on the examples > where they aren't using reserved words. For a few seconds I thought it > was a sloppy examples, but then I realized the only reason the quotes > are there are because of the use of the reserved words. smtpd won't > accept those as labels without the quotes. It will flag it as a syntax > error. If you don't use configuration syntax for a label, you don't need > the quotes there. Yes, I get that smtpd won't accept such labels without quotes because they resemble reserved words. That is my point entirely: provide quotes where sensible to make it absoloutely obvious that the quoted text is not a grammatical keyword (but may very well be as long as it is quoted). I'll take the first example: table aliases file:/etc/mail/aliases table secrets file:/etc/mail/secrets listen on lo0 action "local" mbox alias action "relay" relay host smtp+tls://b...@smtp.example.com \ auth match for local action "local" match for any action "relay" Removing quotes will result in syntax errors as you noted. So I suggest leaving those quotes where they are because users should be able to copy these examples, substitute "local" with "local-mail" and be done with it. This example does not quote file paths but the next one does; this is inconsistent but I think of slightly less importance because it is even more obvious that "file:/something" is not a single reserved keyword. So I'm with you on providing sane examples, but removing quotes where not necessary is working against that goal - it simply does not buy you anything but potentially more trouble than current examples do.
Re: Diff to stop using reserved words for smtpd.conf(5) examples
On Mon, Jul 22, 2019 at 05:05:01PM -0400, Kurt Mosiejczuk wrote: > This is a diff for that changes the example smtpd.conf and smtpd.conf.5 > so that it no longer uses words that are parts of the configuration > syntax as labels for actions. A large chunk of my delay to a release > with the new smtpd.conf configuration syntax was my confusion with the > examples. Even writing this diff I realized that the quotes were only > necessary in the examples because configuration grammar was being > reused as labels. I get the point of not reusing reserved words but I am not convinced of "relay" -> "inet-mail" and the like, yet. Either ways, you should not omit quotes. They are not optional in every case; please provide properly quoted examples so people can safely substitute the text and easingly distinguish reserved words from arbitrary text.
