"Chatty" config files in /etc

[Garance A Drosehn]

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.

-- 
Garance Alistair Drosehn     =               drosehn at rpi.edu
Senior Systems Programmer               or   gad at FreeBSD.org
Rensselaer Polytechnic Institute;             Troy, NY;  USA