On Sun, Feb 09, 2020 at 01:15:59AM +0100, Ingo Schwarze wrote: > Hi, > > Theo de Raadt wrote on Sat, Feb 08, 2020 at 04:39:42PM -0700: > > > For complicated configurations, the text could explain the reason the > > example is valuable -- for instance > > > > .It Pa /etc/examples/bgpd.conf > > Example configuration file demonstrating IBGP mesh, multiple transits, > > RPKI filtering, and other best practices. > > I like that. It gives the reader an idea of how interesting the file > might be without even opening it. > > We have to be careful to not make the comment too long, or FILES > might look bad, but your text still looks reasonable to me. > > I think it's sufficient to have this wording in bgpd.conf(5); > in bgpd(8), mentioning the existence of the example seems fair, but > the exact contents seem more tangential there. I guess network > admins running that beast will have to look at bgpd.conf(5) anyway. > > > I applied Jason's recommendation to remove the "do not edit"; > probably he is right that it isn't required. > > Regarding benno@'s comment: /etc/exanmples/ is already mentioned > in hier(7) and yet some people missed it. I wouldn't blame them. > Also, you don't really need to look into /etc/examples/ for all > programs; if we point to it from where it matters, that's even > better usability. Still, i think it would *also* make sense to > mention the directory in a FILES section in help(1), and optionally > also in afterboot(8), though the latter seems less relevant. I'm > not feeling strongly about that, and one doesn't exclude the other. > Pointers are cheap and can be added whereever they help, only not > in such an amount that they would become a distraction. > > Updated patch: still OK? > Ingo >
morning. here's some issues i see. i'll concentrate on bgpd to keep it simple: - bgpd.8 refers to /etc/bgpd.conf. that file doesn;t exist by default. - i'm not convinced bgpd.8 needs to refer to the example file. - only root can view the example file. i understand why, but in itself it's not that helpful. - we've seen from this thread that people are missing the existence of /etc/examples/bgpd.conf. that's a shame because it looks like a nicely written file. the essential issue is we want people to find the examples. the least amount of work to achieve that is just for bgpd.conf.5 to mention it. adding extra stuff about what's in there is a lot of work and sets us up for things going out of date in the future. and although it might work well for bgpd - a big, complex, piece of software, it will probably make less sense for most other software. leaving us with a divided strategy. it'd be good to have a clear idea of which pages we're planning to change, and how, so that it's clear for other authors. for bgpd i propose: - no change to bgpd.8. i don;t have a solution to the fact that we moved its config file to examples/ so there isn;t an /etc/bgpd.conf file. i suppose everyone understands what is happening. - for bgpd.conf.5, add an entry to FILES "example configuration file". no more. - i'm not the right person to judge the existence of individual example files. ratchov already indicated he doesn;t see the point of examples/mixerctl.conf. i guess individual devs get to judge this. - i think an addition to afterboot.8 totally makes sense. it's what it's there for. - i don;t think an addition to help.1 makes sense. that is just trying to tell people how to use unix, and no one reads it anyway. jmc > > Index: bgpd.8 > =================================================================== > RCS file: /cvs/src/usr.sbin/bgpd/bgpd.8,v > retrieving revision 1.62 > diff -u -p -r1.62 bgpd.8 > --- bgpd.8 10 Nov 2019 20:51:53 -0000 1.62 > +++ bgpd.8 8 Feb 2020 23:52:00 -0000 > @@ -205,11 +205,13 @@ Only check the configuration file for va > Produce more verbose output. > .El > .Sh FILES > -.Bl -tag -width "/var/run/bgpd.sockXXX" -compact > +.Bl -tag -width "/etc/examples/bgpd.conf" -compact > .It Pa /etc/bgpd.conf > default > .Nm > configuration file > +.It Pa /etc/examples/bgpd.conf > +example configuration file > .It Pa /var/run/bgpd.sock > default > .Nm > Index: bgpd.conf.5 > =================================================================== > RCS file: /cvs/src/usr.sbin/bgpd/bgpd.conf.5,v > retrieving revision 1.199 > diff -u -p -r1.199 bgpd.conf.5 > --- bgpd.conf.5 25 Jan 2020 12:07:28 -0000 1.199 > +++ bgpd.conf.5 8 Feb 2020 23:52:00 -0000 > @@ -1883,10 +1883,13 @@ For prefixes with equally long paths, th > is selected. > .El > .Sh FILES > -.Bl -tag -width "/etc/bgpd.conf" -compact > +.Bl -tag -width "/etc/examples/bgpd.conf" -compact > .It Pa /etc/bgpd.conf > .Xr bgpd 8 > configuration file > +.It Pa /etc/examples/bgpd.conf > +example configuration file demonstrating IBGP mesh, multiple transits, > +RPKI filtering, and other best practices > .El > .Sh SEE ALSO > .Xr strftime 3 , >
