Porters handbook: dealing with configuration files

Packages should only install files under ${PREFIX}, which is /usr/local by default. On the other hand, the OpenBSD policy is to install most configuration files under ${SYSCONFDIR}, which is /etc by default.

Note that it is perfectly acceptable for a binary package to have both ${PREFIX} and ${SYSCONFDIR} hardcoded: PREFIX and SYSCONFDIR are mostly user settings that influence the build of the package.

@sample explained

Packing-lists contain a specific @sample mechanism to deal with configuration files:

During fake installation, the port should install a sample configuration file, for instance as ${PREFIX}/share/examples/PKGNAME/foo.rc.
The packing-list should contain a @sample ${SYSCONFDIR}/foo.rc right under the sample configuration file.
During installation, the default example configuration file will be copied into the actual location where the configuration file should live.
During updates and deinstallation, an existing configuration file will be compared with the default example file. If they differ, the package tools will inform the user and let him perform the update/removal himself. If they are identical, the package tools know they can proceed and update/remove the configuration files without any further precautions.

more @sample specificities

Contrary to other files in a packing-list, @sample entries can have an absolute path name.

Some big packages will also need their own configuration directory, @sample ${SYSCONFDIR}/directory/ will deal with that.

Using @sample directory/ to create port specific directories that do not hold any configuration files is perfectly good style. @sample correctly interprets correct @mode, @owner, @group annotations. This can be a bit cumbersome, because you will often need to switch back and forth between a default mode and a configuration file specific mode.

Special tricks

make update-plist knows how to copy @sample annotations over, but it does not know how to create them, so they have to be written in the first place.

Note the distinction between configuration files and example configuration files: the port must be configured to find its files under ${SYSCONFDIR}, it is only the fake installation stage that must put stuff under ${PREFIX}/share/examples. One simple way to handle that is to copy the files over in a post-install.

A neat trick which often works is to look at a program's makefile, and override the configuration directory in the fake installation stage by using specific FAKE_FLAGS, for instance:

FAKE_FLAGS=DESTDIR=${WRKINST} sysconfdir=${WRKINST}${TRUEPREFIX}/share/examples/PKGNAME

You just need to watch out for programs that write the configuration directory down in specific files during their install stage.

Examples

The security/integrit port uses a configuration directory with a few files. Its packing-list looks like this:

@comment $OpenBSD: config.html,v 1.3 2010/07/18 06:24:17 lum Exp $
@bin bin/i-ls
@info info/integrit.info
@man man/man1/i-ls.1
@man man/man1/i-viewdb.1
@man man/man1/integrit.1
@bin sbin/i-viewdb
@bin sbin/integrit
share/doc/integrit/
share/doc/integrit/README
share/doc/integrit/crontab
share/doc/integrit/install_db
share/doc/integrit/integrit_check
share/doc/integrit/viewreport
share/examples/integrit/
@sample ${SYSCONFDIR}/integrit/
share/examples/integrit/root.conf
@sample ${SYSCONFDIR}/integrit/root.conf
share/examples/integrit/src.conf
@sample ${SYSCONFDIR}/integrit/src.conf
share/examples/integrit/usr.conf
@sample ${SYSCONFDIR}/integrit/usr.conf

The security/nessus port uses @sample dir/ to create private directories.

...
sbin/uninstall-nessus
@sample ${SYSCONFDIR}/nessus/
@mode 0700
@sample /var/nessus/
@sample /var/nessus/jobs/
@sample /var/nessus/logs/
@sample /var/nessus/users/
@extraunexec rm -fr %D/lib/nessus/plugins/*
@extraunexec rm -fr %D/nessus
@extraunexec rm -fr /var/nessus

The sysutils/nut port uses a specific owner for its configuration files.

@comment $OpenBSD: config.html,v 1.3 2010/07/18 06:24:17 lum Exp $
@conflict upsd-*
@newuser ${NUT_USER}:${NUT_ID}:::UPS User:/var/empty:/sbin/nologin
...
share/examples/nut/
@sample ${SYSCONFDIR}/nut/
@owner ${NUT_USER}
share/examples/nut/ups.conf
@sample ${SYSCONFDIR}/nut/ups.conf
share/examples/nut/upsd.conf
@mode 600
@sample ${SYSCONFDIR}/nut/upsd.conf
@mode
share/examples/nut/upsd.users
@mode 600
@sample ${SYSCONFDIR}/nut/upsd.users
@mode
share/examples/nut/upsmon.conf
@mode 600
@sample ${SYSCONFDIR}/nut/upsmon.conf
@mode
share/examples/nut/upssched.conf
@sample ${SYSCONFDIR}/nut/upssched.conf
@mode 700
@sample /var/db/nut/
@mode
@owner
share/ups/
share/ups/cmdvartab
share/ups/driver.list

www@openbsd.org
$OpenBSD: config.html,v 1.3 2010/07/18 06:24:17 lum Exp $