Hi Ingo, Thank you for taking the time to reply to my post too which I must say did appear a bit off and misplaced, since I cross posted (timing) before having chance to read your good posts, that pretty much explain it all.
> > Is examples a good candidate for samples of everything etc that the > > user may be wondering about compared to only contain examples for base > > system daemons? > > Of course. For example, /etc/examples/pf.conf is not misplaced, > even though pf(4) is not a daemon. Thanks for considering the suggested cases. > > Would the user benefit from a sane starting point for other configs, > > optionally when none are already in etc? > > Usually, no. > > We strive for "sane and secure by default", for all subsystems. > Ideally, that works with no configuration file whatsoever. Here doas(1) is an exception to this presumption. It has no base configuration in /etc and neither an example in /etc/example, so a start up user is facing 2 man pages doas(1) and doas.conf(5) and scratching head worrying what would be best practice to begin with (not featured in one of Michael's books yet). And that is if they discover doas(1) in the first place, when in need of a method to perform actions without assuming root all the time. So the option for a user in this case is copying the example from the man page verbatim with a couple of tweaks maybe, and that is if reasonable thinking permits it. > Ideally, if a user has one special need, they create a configuration > file from scratch putting in just that one setting, so they get a > configuration file of less than five lines. If five users have > five different special needs, ideally, their configuration files > won't have a single line in common. If a service needs a substantial > configuration file for standard operation, it's ill-designed. Understood what you mean, thanks. > Of course, there are exceptions for unusually complex services. > For example, you can't possibly run bgpd(8) without providing > a substantial amount of information in the configuration file > about your site, your neigbors and peers. But having a file > in /etc/examples/ ought to be the exception rather than the > rule for a service. In my simple thinking, that concurs with your explanation, having things work out of the box with as little tuning and/or configuration tweaking should (could, and would) work sane and reasonably secure by default. Removing the need for the user to become a security expert overnight is good to apply in other perspectives. It can further be extended to remove the need for them to know pitfalls of secure system management and best usage practices. Having to put the user through the process of reading man pages to create their own configuration file from scratch where a sub-system can not work without a configuration file and not providing a relatively good source in the man page and/or sample in examples goes out of the above care taking. But I hear what you're saying there should be only one place for such an example, and still think maintaining these in the man page causes the user to start skipping docs. So ideally the specs start as man pages, and sample configurations which are then parsed and implemented as code, and since it's too good to be true in reality different type of reference material follow the implementation. All I'm saying is that respectfully agreeing still leaves room for considering ways to make the man pages the true source of examples which probably will not hurt to be available to the user if auto-generated and/or kept in sync. Best regards, Anton
