7.3. Configuration Files

If your port installs configuration files to PREFIX/etc (or elsewhere) do not simply list them in the pkg-plist. That will cause pkg delete to remove the files carefully edited by the user, and a re-installation will wipe them out.

Instead, install sample file(s) as filename.sample, and for each sample file, add this line to your pkg-plist.

@sample etc/orbit.conf.sample

If there is a very good reason not to install a working configuration file by default, only list the sample filename in pkg-plist, without the @sample part, and add a message pointing out that the user must copy and edit the file before the software will work.


When a port installs its configuration in a subdirectory of ${PREFIX}/etc, it should be in ETCDIR, which defaults to ${PREFIX}/etc/${PORTNAME}, it can be overridden in the ports Makefile if there is a convention for the port to use some other directory. The %%ETCDIR%% macro should be used in its stead in the pkg-plist file.


The sample configuration files should always have the .sample suffix. If for some historical reason you cannot use the standard suffix, you can still use this construct:

@unexec if cmp -s %D/etc/orbit.conf-dist %D/etc/orbit.conf; then rm -f %D/etc/orbit.conf; fi
@exec if [ ! -f %D/etc/orbit.conf ] ; then cp -p %D/%F %B/orbit.conf; fi

The order of these lines is important. On deinstallation, the sample file is compared to the actual configuration file. If these files are identical, no changes have been made by the user and the actual file can be safely deleted. Because the sample file must still exist for the comparison, the @unexec line comes before the sample configuration file name. On installation, if an actual configuration file is not already present, the sample file is copied to the actual file. The sample file must be present before it can be copied, so the @exec line comes after the sample configuration file name.

To debug any issues, temporarily remove the -s flag to cmp(1) for more output.

See pkg-create(8) for more information on %D and related substitution markers.

All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.