cfg-update(17)

NAME
cfg-update - An easy to use CLI/GUI alternative for etc-update with safe automatic update functionality.

SYNOPSIS
cfg-update [flags] [runmode]

DESCRIPTION

The cfg-update script is designed to be a safe and simple tool for updating configuration files in Gentoo Linux. The updating process consists of 5 stages:

Stage1: Automatic updating of unmodified files and binaries

Stage2: Automatic 3-way merging of modified files (uses backup as ancestor file)

Stage3: Manual 3-way merging of modified files (with merge conflicts in stage 2)

Stage4: Manual 2-way merging of modified files (that don't have backups yet)

Stage5: Manual updating of modified binaries and links

You can disable each stage in /etc/cfg-update.conf to suit your needs. So if you don't trust automatic 3-way merging, just disable stage2 and cfg-update will let you take care of these files manually in stage3. If the selected diff/merge tool doesn't support 3-way merging, cfg-update automatically disables stage3 and continues with stage4 for manual 2-way merging.

cfg-update also supports automatic-only updating for use with cronjobs or other automated system maintenance scripts. Just use the -a option and cfg-update will skip stages 3,4 and 5.

RUNMODES

-l, --list
    List configuration files that need to be updated.

-u, --update
    Update files in sequence or add a number from the -l output to update only that specific file.

-b, --backups
    List backup files from previous updates. These backups are stored in /var/lib/cfg-update/backups but you can change the location with the BACKUP_PATH variable in /etc/cfg-update.conf

-r, --restore [x]
    Add a number from the -b output to restore a specific file.

--mount
    Mounts the remote hosts specified in /etc/cfg-update.hosts

--check
    Checks the remote hosts for problems and shows their status.

--unmount
    Unmounts the remote hosts specified in /etc/cfg-update.hosts

OPTIONS

-v, --verbose
    Verbose output, makes various file operations visible and unhides STDERR messages. Use this if you experience problems with starting the GUI tool, it may give you useful clues in the STDERR messages.

-a, --automatic-only
    Force cfg-update to only use the automatic stages (1,2) for updating. (only useful in combination with the -u option)

-m, --manual-only
    Force cfg-update to only use the manual stages (3,4,5) for updating. (only useful in combination with the -u option)

-h, --host
    Include sshfs mounted remote hosts (combine with -l, -u, -b, -r). Add the number of a specific host or a range for multiple hosts. For more information see: /etc/cfg-update.hosts

-p, --pretend
    This option allows you to see what actions cfg-update will take on the configuration files.

-t, --tool
    Changes the default diff/merge tool for the duration of the session. (you can also permanently change the tool in /etc/cfg-update.conf)

-d, --debug
    With this option cfg-update will output tags when starting or finishing subroutines in the script. cfg-update will not suppress STDERR messages, it will show all calls to other programs and it prints subroutine tags for easy troubleshooting.

SPECIAL OPTIONS

-i, --index
    Check the index and rebuild if new packages have been installed (--index is used in the hooks for Portage and Paludis). The hook for Paludis will add an extra option --paludis behind --index.

-s, --show-protected-dirs
    List all protected directories on your system.

--optimize-backups
    Creates extra backups which can be used for future automatic 3-way merging, so you don't have to update them manually.

USAGE EXAMPLES

cfg-update -l
    Lists all updates.

cfg-update -v -l
    Lists all updates and shows which stage will handle the update.

cfg-update -p -u
    Pretends updating the configuration files.

cfg-update -u
    Starts the update session using the default tool.

cfg-update -v -u
    Starts the update session and makes file operations visible.

cfg-update -u -t /usr/bin/meld
    Starts the update session using the specified tool instead of the default MERGE_TOOL from /etc/cfg-update.conf

cfg-update -au
    Starts the update session in automatic-only mode. When this option is selected, cfg-update will only process stage1 and stage2. This mode can be used for cronjobs and other automated system maintenance scripts.

cfg-update -mu
    Starts the update session in manual-only mode. When this option is selected, cfg-update will only process stage3, stage4 and stage5.

cfg-update -b
    Lists all backups. You can take a number and use that with -r to restore that particular file.

cfg-update -r77
    This will restore the 77th backup listed in the -b output. cfg-update will restore both the previous configuration file and the previous ._cfg0000_file so that you'll be able to retry the update.

USAGE EXAMPLES FOR UPDATING MULTIPLE MACHINES

cfg-update -h0 -l
    Lists all updates for localhost.

cfg-update -h1 -l
    Lists all updates for remote host 1.

cfg-update -h0-100 -l
    Lists all updates for localhost and remote hosts 1 to 100.

cfg-update -h1-100 -l
    Lists all updates for remote hosts 1 to 100.

cfg-update -h1-100 -u
    Starts the update session for remote hosts 1 to 10.

cfg-update -h1 -b
    Lists all backups for remote host 1. You can take a number and use that with -r to restore that particular file.

cfg-update -h1 -r77
    This will restore the 77th backup on remote host 1, listed in the -b output. cfg-update will restore both the previous configuration file and the previous ._cfg0000_file so that you'll be able to retry the update.

STAGE1

In Stage1 cfg-update will look at the md5-checksum of the current configuration files. Portage stores these checksums when it installs files. If a checksum hasn't changed it means that the file hasn't been modified and does not contain customized settings. These files will be replaced with the new version automatically.

STAGE2

Stage2 uses a second automatic updating method. This stage tries to automatically update modified files. It looks for backups of previous updates and uses the previous update for a 3-way diff with the current file and the new update. The files are sent through the diff3 tool and the merged output is saved. If the merged output contains a merge-conflict it will cancel the automatic update and if there are no merge-conflicts it will complete the update.

STAGE3

Stage3 handles modified files with merge-conflicts. These files will be presented to you in the graphical diff/merge tool of your choice so you can solve the merge-conflicts by clicking on the lines that you want to include in the new file. If your tool doesn't support 3-way merging, cfg-update will skip this stage.

STAGE4

Stage4 allows you to update files that have not been updated before with cfg-update. It does the same as stage3 but now with only two files. You simply click on the lines that you want to include in the new file.

STAGE5

Stage5 let's you handle modified binaries, and updates that include symlinks. cfg-update will give you some advice and ask you what to do with the files.

MORE INFO

By default cfg-update makes backups of the current configuration file and the new ._cfg0000_ file so you can always restore both and try updating again. These backups are stored in /var/lib/cfg-update/backups.

The modification checking method for stage1 comes from Naan Yaar's post on the Gentoo Forums. Portage stores information about each installed package (in /var/db/pkg). The file called CONTENTS has a list containing MD5-checksums of all the files installed by that particular package. You can simply compare the checksum of the current configuration file with the checksum in the CONTENTS file to determine whether the file has been modified or not.

But... when you install a new package, and an update for one of the configuration files is placed in a protected directory, it's too late to get the checksum for the current configuration file because the CONTENTS file is already updated by Portage and contains the checksum of the update!

The solution is very simple; a backup is created of all the checksums that Portage has stored in the CONTENTS files. I chose to write all checksums found in /var/db/pkg/*/* to a single file and add the timestamp of the last installed package as an indicator that new packages have been installed. (/usr/lib/cfg-update/checksum.index) Creating this list only takes a couple of seconds even on an old Pentium. In earlier versions of cfg-update the index was updated by using an alias for emerge. Newer versions use the /etc/portage/bashrc file with a hook for the ebuild setup phase.

This enables cfg-update to update it's checksum index before one or more new packages are installed. But updating the index can only be done when there are no updates in the protected directories. So once an update is found cfg-update will not update the index until you have updated all your files.

SEE ALSO
/etc/cfg-update.conf /etc/cfg-update.hosts http://people.zeelandnet.nl/xentric/

LICENSE
This program is free software. You can redistribute it and/or modify it under the terms of the GNU General Public License v2 as published by the Free Software Foundation. This program is distributed in the hope that it will be useful, but without ANY warranty, without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License v2 for more details. You should have received a copy of the GNU General Public License v2 along with this program. If not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

REPORTING BUGS
Please report bugs via http://bugs.gentoo.org

AUTHOR
S. van Boven <sboven@zeelandnet.nl>