"Chatty" config files in /etc

[Tom Rhodes]

On Wed, 30 Aug 2006 20:15:57 -0400
Garance A Drosehn <gad at FreeBSD.org> wrote:

> At 12:28 AM +0400 8/31/06, Ruslan Ermilov wrote:
> >On Wed, Aug 30, 2006 at 01:41:51PM -0400, Garance A Drosehn wrote:
> >
> >  > ...   I wonder if it would be better to
> >  > have the comments and examples as files under /etc/defaults.  I
> >  > suppose they could also go under /usr/share/examples, but for
> >  > these files I think there is some advantage that the comments
> >  > and examples be on '/', and not on '/usr'.
> >  >
> >>  Also, if the comment+example files are under /etc/defaults, then
> >>  changes to them *will* come up in mergemaster.  It's just that
> >>  now they will show up in a file that has no local changes, so
> >>  the user can just read the change, instead of having to "merge"
> >  > all their local changes with the new official version.
> >
> >I think they should be moved to /usr/share/examples/etc/ (like
> >make.conf), with files in /etc/ representing good (short) defaults
> >with a minimum of comments and probably references to examples.
> 
> Well, my thinking was something like:
> 
> a) these example/comment files are for "system" things.  Many
>     people mount their /usr directories from somewhere else,
>     thus /usr might not be an exact match for the running kernel.
>     (note that make.conf makes sense for /usr/share/examples,
>     because the `make` command is also under /usr).
> b) by putting them in /etc/defaults, users do *see* the changes
>     when they run mergemaster, even though they won't have to
>     merge those changes with local changes.  In some cases the
>     changes to the comments or examples will suggest some change
>     that the user should be making to their own already-working
>     configuration, even though their configuration won't match
>     the default system-config.  I'm thinking when some comment
>     is added like:
>         # NOTE: Please see pf.conf(5) BUGS section before
>         # using user/group rules.
> 
>      As a sysadmin, I do not stop and read every man page when
>      it changes.  But if I see a comment like that added to
>      pf.conf when I run mergemaster, then I *will* take the
>      time to read pf.conf(5) to see what this (possibly new)
>      issue is.
> 
> So the file we install as /etc/pf.conf could easily be changed to:
> 
> #       $FreeBSD: src/etc/pf.conf,v 1.---- 2006/04/04 20:31:20 mlaier Exp $
> #
> # See pf.conf(5) for syntax, and /etc/defaults/pf.conf for a detailed
> # example of this file.  The directory /usr/share/examples/pf contains
> # some additional example configurations.
> 
> # Required order: options, normalization, queueing, translation, filtering.
> # Macros and tables may be defined and used anywhere.
> # Note: translation rules are first match while filter rules are last match.
> 
> # Filtering: the implicit first two rules are
> #pass in all
> #pass out all
> 
> ......  and that's all.  Just a 13-line file, with almost no
> specific details in it.  The few comments that are left are ones
> which would always be helpful to have there as reminders, and
> which are not likely to change over time.  With any luck, we
> should be able to go a few years without changing this file.

I'm digging this idea.  There are a lot of "basic" configuration
files which either get modified or completely re-written. Perhaps
we should start looking over those and consider moving them to
defaults/ and have rc.conf default to there.  We already do this
with some files (rc.conf comes to mind) so why not all?  ;)

-- 
Tom Rhodes