general-concepts/config-protect/text.xml


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

<?xml version="1.0" encoding="UTF-8"?>
<guide self="general-concepts/config-protect/">
<chapter>
<title>Configuration File Protection</title>
<body>

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

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

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

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

<codesample lang="ebuild">
	newenvd - 99my-pkg &lt;&lt;&lt; "CONFIG_PROTECT_MASK=\"/etc/test.cfg\""
</codesample>

</body>
</chapter>
</guide>