Configuration file protection

Portage includes a system for configuration file protection which means ebuilds don't have to worry about accidentally clobbering files in /etc. This is known as 'protection', and it is controlled by the CONFIG_PROTECT and CONFIG_PROTECT_MASK variables.

Any directory which is listed in CONFIG_PROTECT (and any subdirectories thereof), except for any which are listed in CONFIG_PROTECT_MASK (and subdirectories) are automatically 'protected' by Portage when copying an image from DESTDIR to ROOT. Rather than installing protected files directly, Portage will install them as ._cfg0000_filename. These can then be processed by the etc-update or dispatch-conf files at the user's discretion.

Packages must not attempt to override this system via pkg_postinst or similar. If you need a file renamed, removed or changed in a particular way, you should display a message informing the user.

An ebuild can append to the CONFIG_PROTECT_MASK variable by using Portage's Environment files mechanism. The ebuild has to generate an env.d file, then install it using doenvd or newenvd. emerge shall call env-update and generate the proper environment for proceeding with its merge. The following snippet (from src_install) shall cause /etc/test.cfg to be auto-merged without needing to call etc-update after the package is merged:

	newenvd - 99my-pkg <<< "CONFIG_PROTECT_MASK=\"/etc/test.cfg\""