dispatch-conf

Portage - the heart of Gentoo
emerge — configuration — ebuild repository — dispatch-conf

world file — USE flags — ebuilds — profiles
upgrades — using testing packages — binary packages
tools — gentoolkit — eselect
Portage FAQ — cheat sheet — FAQ
all articles

Resources

Project

Package information

GitWeb

GitHub

Bugs (upstream)

This article has some todo items:

• how to revert a change
• how backups are made
• is archive-dir still an option ? it isn't in the config file by default

dispatch-conf is a utility included with Portage, used to safely and conveniently manage configuration files after package updates. It is an important tool to manage the issue of transitioning configuration across package updates, without the user needing to manually migrate changes.

dispatch-conf allows system administrators to review configuration file changes made by Portage, to gracefully manage changes to the structure of the configuration of an updated package, in a standard way. Portage will indicate when config files need updating, and running dispatch-conf will propse to either use the new configuration as-is, reject changes, or selectively merge modifications. dispatch-conf will automatically update config files that the user has never modified, or that differ from the current version only in CVS cruft, comments, or white space.

dispatch-conf keeps a history of changes and permits rollback to previous versions, so any mistakes can be reverted. Changes made to config files will be saved in the archive directory. Alternatively it can integrate with rcs to allow for version-controlled configuration file management.

dispatch-conf は、CONFIG_PROTECT 環境変数内のすべてのディレクトリの変更をチェックします。CONFIG_PROTECT_MASK 環境変数内のパスの中にあるコンフィグファイルは、保護されず自動的に上書きされます。

The configuration management problem with updates

Configuration migration is a general problem with any software update process: some version changes will modify behavior, such that the previous configuration parameters become no longer pertinent to the new version. New configuration options may be added, removed, their meaning may be changed or the names or the format of each directive may change.

Each software project manages this in its own way. Some projects have robust configuration version tracking and can automatically transfer configuration from one version to another; some projects may have issues between major versions, or if updating from much older versions; for some projects, updating while trying to preserve previous configurations may cause issues or even be impossible.

There is a long-standing Unix convention of using plain text files, often with a semi-standard syntax, for storing configuration. Major updates could require manual migration of these files, or risk them becoming outdated. This may seem cumbersome today, but it remains a very robust way to manage configuration, and avoids ambiguity of how the configuration directives may change between versions, which is important for many - sometimes critical - services such as Internet servers.

設定

ファイル

dispatch-conf の設定ファイルは /etc/dispatch-conf.conf です。このファイル内で archive-dir 変数が参照するディレクトリを作成しておく必要があるかもしれません。

RCS (revision control system) との統合

警告
RCS を使用するように設定した場合、アーカイブされたファイルの読み込みおよび実行権限は、ファイルの初回のチェックイン時から引き継がれるかもしれません。作業中のファイルの権限がそれ以降変更されても、初回のチェックインの権限はそのままかもしれません - これは思わぬセキュリティ問題を引き起こすおそれがあります。RCS ファイルへのアクセスは、親ディレクトリの権限を設定することで制御することができます。

dispatch-conf が rcs と統合するように設定されると、/etc/config-archive にすべての変更が保管されるでしょう。

revision control system をインストールしてください:

root #emerge --ask dev-vcs/rcs

この設定プロセスは単純に、設定ファイルに以下の内容を含めるだけです:

ファイル /etc/dispatch-conf.conf

use-rcs=yes

Administrators can then view the differences using the rcs utilities like rlog as well as roll-back changes using co. The rcs utilities work with file locking itself, so the moment it is needed for administrative tasks, understand that:

• dispatch-conf only stores the changes made when the package suggests to alter the file. Changes made afterwards are not registered yet
• when checking out a file, rcs will want to write the file to the file system, so make sure to backup existing files first, or work with standard output (see later)
• to check in a file, a lock must first be taken on said file. Also, make sure not to remove the working file

To view the commit history on /etc/conf.d/udev:

user $rlog /etc/config-archive/etc/conf.d/udev,v

RCS file: /etc/config-archive/etc/conf.d/udev,v
Working file: udev
head: 1.1
branch:
locks: strict
access list:
symbolic names:
keyword substitution: kv
total revisions: 2;     selected revisions: 2
description:
Archived config file.
----------------------------
revision 1.1
date: 2011/06/15 18:14:59;  author: root;  state: Exp;
branches:  1.1.1;
dispatch-conf update.
----------------------------
revision 1.1.1.1
date: 2011/06/15 18:14:59;  author: root;  state: Exp;  lines: +3 -2
dispatch-conf update.
=============================================================================

To roll back to a particular version, a simple way to do so is to check out a previous version:

root #cp udev udev.orig

root #co -p -r1.1.1.1 /etc/config-archive/etc/conf.d/udev,v > udev

etc/config-archive/etc/conf.d/udev,v  -->  standard output
revision 1.1.1.

After making final changes (it is possible to use the backup udev.orig to merge any changes made later), check in the file again:

root #co -p -l /etc/config-archive/etc/conf.d/udev,v

Edit the file, and finally check in the changes:

root #ci -l /etc/config-archive/etc/conf.d/udev,v

/etc/config-archive/etc/conf.d/udev,v  <--  udev
new revision: 1.2; previous revision: 1.1
enter log message, terminated with single '.' or end of file:
>> Merged changes for persistant rules
>> .
done

diff または merge ツールを変更する

diff の出力に色を付ける

すべてが灰色のテキストで変更を読むのはちょっとうっとおしいです。幸運にも、sys-apps/diffutils の現代的なバージョンには --color スイッチがあり、これで変更の種類ごとに異なる色を付けて表示できます。設定は単純です - 設定ファイル内の diff の行を次のように変更してください:

ファイル /etc/dispatch-conf.conf

diff="diff --color=always -Nu '%s' '%s'"

それか、パッケージ app-misc/colordiff を使用することもできます。次で colordiff をインストールして:

root #emerge --ask app-misc/colordiff

それを使用するように設定を変更してください:

ファイル /etc/dispatch-conf.conf

diff="colordiff -Nu '%s' '%s'"

変更をマージするために (g)vimdiff を使う

ファイルをマージするデフォルトの方法の代わりに、vimdiff/gvimdiff を使用することができます。これを行うには、/etc/dispatch-conf.conf 設定ファイルの merge の行を変更してください:

ファイル /etc/dispatch-conf.conf

merge="vimdiff -c'saveas %s' -c next -c'setlocal noma readonly' -c prev %s %s"

vimdiff (gvimdiff ではさらに -f オプションを使用してください) は変更をマージするのにも使用できます。Neovim を使用する場合は、末尾の %s %s を -d %s %s で置き換えてください。

メモ
マージ結果として保存されるオリジナルの設定ファイルは左側のペインに保持されているので、左側のペインに変更を加えて保存してください。その助けとなるように、右側のペイン (新しい設定ファイルを含んでいます) は編集不可の読み込み専用としてマークされていることを覚えておいてください。

マージに関連して vimdiff で使えるいくつかのコマンドです:

"]c" : 次の変更にジャンプする
"[c" : 前の変更にジャンプする
"CTRL-W <Right>" または "CTRL-W <Left>" : もう一方のウィンドウに移動する
"do" (diff obtain): ハイライトされたブロックのテキストをもう一方のウィンドウから取得する
"dp" (diff put) : ハイライトされたブロックのテキストをもう一方のウィンドウに送る
"zo" : カーソルの下の折り畳みを開く
"zc" : カーソルの下の折り畳みを閉じる
"zr" : すべての折り畳みを開く
":wqa" : 保存して終了する

さらなるヘルプについては Vim のドキュメンテーションを参照してください。

変更をマージするために imediff2 を使う

さらに別の merge の代替として dev-util/imediff2 があります。このシンプルなツールを使用すると、わずかなキー操作で選択肢を切り換えることができます。これは主に a または b キーで行われます。さらに手動でマージするために、e キーを押すことで、EDITOR シェル変数に設定されているユーザの好みのエディタを開きます。

これを dispatch-conf と併用するためには、まず imediff2 をインストールしてください:

root #emerge --ask dev-util/imediff2

そして、/etc/dispatch-conf.conf を設定してください:

ファイル /etc/dispatch-conf.conf

merge="imediff2 -c -N --output='%s' '%s' '%s'"

使い方

呼び出し

設定ファイルは通常 root が所有しているので、dispatch-conf は root として実行すべきです:

root #dispatch-conf

AMD64 ハンドブックと man ページには使い方についてのさらなる情報が含まれています:

user $man 1 dispatch-conf

ヒント

git リポジトリ内に設定の変更を記録する

On installation, etckeeper will hook into dispatch-conf to make backups of configuration files upon each invocation.

関連項目

• etc-update (AMD64 ハンドブック)
• cfg-update — a utility used on Gentoo to manage configuration file updates.