In most cases files prefixed with  ._cfg*  will be created because the user did change a config file. Means the existing config file is different from the one shipped by Gentoo. In practice it is really hard - hard in the sense of big effort and redundant work - to handle such a kind of update. Changes made by a user are usually persistent - thus the user have to do the same steps after each update to prevent that the changes will be overwritten. The not satisfying situation even growth, as such prefixed files are will or could be created, for though the user didn't touch the corresponding config file at all.

Before going on I want to do some naming conventions:

• config file - the existing config file protected by the CONFIG_PROTECT variable (example:  /etc/vnstat.conf )
• prefixed file - the file with a prefix  ._cfg  which is designated to replace the corresponding config file (example:  /etc/._cfg0000_vnstat.conf )

There are some tools available to handle config file updates, but non of them does the job really good. Some of them did integrate  sdiff  for 3-way-diffs, but I question if this is an effective way for most cases. Sure some manual investigation can't be excluded always. It would go much to far here to do an analysis of what was going wrong there and to philosophize about the reasons behind. At least I think the basic approach was wrong, so let me present a different solution.

The goals we want to reach are:

• automate updates of config files as far as possible
• keep changes done by the user (in any case)
• manual investigation have to be prevented except on an error

The challenge is how to handle config files which are present on the system against them provided by Gentoo in their latest version after an update. Update means that the user did run basically an

$ emerge -u <whatever>

where the  <whatever>  stands for additional options and/or parameters, include the name of ebuilds/packages.

1. Compare an prefixed file against the last version of the corresponding config file from Gentoo and detect the changes.
2. Apply the detected changes against the present config file without losing the changes done by the user

Really simple - or it is confusing? For the second I will present an

The example is generic.  qrtconf  has some options to change the process!

Our example config file calls  /etc/vsftpd.conf  and (after an update) the corresponding cfg file is  /etc/._cfg0000_vsftpd.conf  exists. I divided the processing into 3 stages. A higher stage will be reached only, if the actual stage wasn't successful - or in other words: couldn't finish.

A backup of the last version of each config file provided from the distribution will be created automatically at time the corresponding prefixed file was created and handled by qrtconf.

We invoke qrtconf and it searches for prefixed files. It did find  /etc/._cfg0000_vsftpd.conf . Now it looks in  /var/lib/qrtools/  if there does exist a corresponding file  /etc/vnstatd.conf .

The backup'd files will be stored in  /var/lib/qrtools/  (default) - from this starting point the folder/file hierarchy is the same like in  /etc .

qrtconf proceeds to

There is no corresponding file. qrtconf moves  /etc/._cfg0000_vnstatd.conf  to  /var/lib/qrtools/etc/vnstatd.conf . The processing is finished. Otherwise - in case there is a corresponding file - we go on to

A corresponding file  /var/lib/qrtools/etc/vnstatd.conf  exists. qrtconf uses  diff  to determine differences between  /etc/._cfg0000_vnstatd.conf  and  /var/lib/qrtools/etc/vnstatd.conf . If there is no difference, then the prefixed file has the same content as the last config file provided by Gentoo. Thus we come to the following Conclusion: There are no changes from site of Gentoo, changes MUST be done by the user. It is save to delete the prefixed file  /etc/._cfg0000_vnstatd.conf .

qrtconf deletes the prefixed file and doesn't touch the config file  /etc/vnstatd.conf . Thus the processing is finished, otherwise we have to proceed with

The last possible reason that the prefixed file was created is now, that Gentoo did made changes in their provided config file. qrtconf creates a (temporarily) patch between  /var/lib/qrtools/etc/vnstatd.conf  (input file 1) and  /etc/._cfg0000_vnstatd.conf  (input file 2). Afterwards qrtconf applies the patch to  /etc/vnstatd.conf . Last step is to move the prefixed file to  /var/lib/qrtools/etc/vnstatd.conf  by replacing the former (old) backup'd file.

That's all, processing finished.

From the above we have seen that there are two types of changes which we will name and handle:

• Gentoo changes - apply changes over an existing config file
• User changes - keep these in the existing config file always

Now we can abstract to have and run into one of 4 plus 2 situations (or a maybe in a combination of some):

1. There are no user changes in the config file(s)
2. There doesn't exist a config file but a corresponding prefixed file
3. You did made user changes in a config file, but either
   1. Your config files are up-do-date and you did run 3-way-diffs regularly
   2. Your config files differs from provided ones, because you never did update them
4. All three files involved - config file, prefixed file and the backup'd file - are different of each other
5. qrtconf couldn't do the update and runs into an error

Situation 1: This is the easiest situation and like basic functionality of  etc-update  the existing config file will be replaced.

Situation 2: This is close to point 1. As there is nothing to replace, a new config file will be created.

Situation 3a): This is the typical use case qrtconf expects and it is the status qrtconf creates after it did run successful.

Situation 3b): Depending on how many changes and how big are the differences are, qrtconf could fail here. Anyhow, qrtconf leaves the config file and the prefixed file untouched then. Usually there is a manual investigation required once.

Situation 4: This isn't a typical use case but it could happen under some circumstances. qrtconf could solve this automatically. Depending on the complexity qrtconf will need 2 update cycles. The config file will may be untouched after the first cycle, but this shouldn't be a issue in most cases - it is just like the prefixed file will be deleted without any other action.

Situation 5: This is an error! It have to be solved manually.

It is much harder to describe (and even understand) all of this than writing the code of qrtconf! But the thoughts behind HAVE TO be clear to prevent circular changes and misunderstandings.

qrtconf has some options (see qrtconf.8). The build-in default values could be overwritten in the config file  /etc/portage/qrtools.conf/qrtconf.conf  (see qrtconf.5). Command line options overwrites config file values. Invalid values causes default values or an error.

By default qrtconf is in interactive mode. This can be deactivated by setting  INTERACTIVE=0  in the config file (recommended). The command line switch  -i  enables the interactive mode only. In interactive mode the verbosity level 0 will be increased to level 1 automatically.

qrtconf has 3 verbosity levels 0 (silent), 1 (verbose) and 2 (more verbose). Default is 1. This setting could be changed via config file or command line switch  -v <N> , where <N> is a level number.

• put individual changes at the end of a config file

qrtconf