Hi Ingo, misc@ Thank you for taking the time to reply to my post too. I must say it appeared misplaced before having chance to read your good replies that pretty much explain it all (a note in the postscript[1] too).
> > 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. That's exactly what I meant: some programs need configuration (and benefit from examples) even if they are not daemons and services, and some even can not function without a configuration file. > > 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. For example here doas(1) is one exception to this presumption. It has no base configuration provided in /etc by default and neither a sample in in /etc/examples. And it requires one to be put into use. To begin using this program a user is facing 2 man pages doas(1) and doas.conf(5), the latter contains brief examples in the man page which (the example section) is not known how closely matches the code compared to a live use file in /etc and ready-to-use in /etc/example, 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, given su is enough already for them. So one option for a user in this case is to copy the example from the man page verbatim with a couple of tweaks (maybe), and that is if reasonable thinking (and time) permits it (pun intended). Then there are scattered blog posts and pseudo use case reports and mailing lists gotchas on line, way more than 2 places to look at. And a couple of books to read on system management and Unix history to make educated choices would come handy, before commenting with other users. > 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, and I agree completely. > 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 (concurs with your explanation mostly) 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. However, removing the need for the user to become a security expert overnight is good to apply in other perspectives too. It could further be extended to remove the need for them to know pitfalls of secure system management and best usage practices. Well, why not learn from OpenBSD the Unix ways, and feel good about it? Having to put the (educable) user through the process of reading complete man pages to create from scratch their own live configuration file in /etc (has its benefits though) where a sub-system or program can not work without a configuration file, and not providing a relatively good source of application notes (example section in the man page) and/or ready-to-apply samples (in /etc/examples) goes out of the above care taking. I would consider such a system where the user is required to manually create a number of configuration files before actual use of the system and watch out for pitfalls by copying examples bits from various locations incomplete and difficult to manage even on a smaller scale of machines. That would result in having to maintain user end one more configuration files copying them over and redistributing configuration files mindlessly (as an end practice), much in the dot and rc files tradition. I hear what you're saying there should be only one place for such an example (if there has to be an example), and still think maintaining these in the man page causes the user to start skipping docs. 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 implementation. In my again simplified thinking, unless the programmer starts using their own configuration files and domain specific languages on top of the program through mangling the code, the work is incomplete and not ready for others but still benefits attention to become more usable. All I'm saying (respectfully agreeing) is that we could still leave 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 as best intended use examples, where the respective program can not operate without a configuration file (because it must serve its purpose and not the user serve the program by learning its peculiar deficiencies). Missing on examples strains the users and they find the need to consult poor online sources, as a result less test cases and adoption of the programs and sub-systems. So, since the developer is already into it, better provide best possible documentation which includes example configuration file where one is required, or explain how to best use their program if deviations from the sane defaults are required. [1] P.S. Please excuse the carbon copying this direct to you. My posts usually get delayed several hours (tar pit against Google Apps hosted mail or whatever) and on top of this moderation halted my second post so this is a re-submission (to which I don't object or even care). If you find a good idea please feel welcomed to reply, or simply ignore if this is wasting time or already explained. Thank you for the wonderful work on Unix history, documentation and everything. Please have in mind the above is my own view and it does not imply anything other than sharing some ideas and personal views, and would be happy to have made the discussion more productive. Best regards, Anton
