.\" Copyright 1996,1997, 1998, 1999 John D. Polstra.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgment:
.\"      This product includes software developed by John D. Polstra.
.\" 4. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" $Id: cvsup.1,v 1.2 2003/12/12 13:06:59 takei Exp $
.\"
.\" translated Sun Jan 23 03:13:03 JST 2000
.\"         by FUJIWARA Teruyoshi <fujiwara@linux.or.jp>
.\"
.Dd August 31, 1999
.Os FreeBSD
.Dt CVSUP 1
.Sh 名称
.Nm cvsup
.Nd CVS リポジトリ用のネットワーク配布パッケージ
.Sh 書式
.Nm
.Op Fl 1aDeEgksvzZ
.Op Fl A Ar addr
.Op Fl b Ar base
.Op Fl c Ar collDir
.Op Fl d Ar delLimit
.Op Fl h Ar host
.Op Fl i Ar pattern
.Op Fl l Ar lockfile
.Op Fl L Ar verbosity
.Op Fl p Ar port
.Op Fl P Ar m|a|port|lo-hi|-
.Op Fl r Ar maxRetries
.Ar supfile
.Op Ar destDir
.Sh 解説
.Nm CVSup
は、ファイル群の配布と更新をネットワーク上で行うための
ソフトウェアパッケージです。
.Nm CVSup
という名前はパッケージ全体を指します。
.Nm CVSup
はクライアントプログラムである
.Nm cvsup
とサーバプログラムである
.Nm cvsupd
からできています。
このマニュアルページは、
.Nm CVSup
パッケージの概要を説明し、クライアントプログラムである
.Nm
特有の事項も説明します。
.Nm cvsupd
の詳しい説明については、
.Xr cvsupd 8
をご覧ください。
.Pp
.Nm rdist
や
.Nm sup
のような、より伝統的なネットワーク配布パッケージと異なり、
.Nm CVSup
は特に CVS リポジトリの配布のために作られています。
.Nm CVSup
は
CVS リポジトリとリポジトリに含まれるファイル(特に RCS ファイル)の
特性を生かし、伝統的なシステムよりもずっと高速な更新を可能にしています。
.Sh オプション
クライアントプログラム
.Nm
は、少なくとも一つの引数
.Ar supfile
を必要とします。
これは、サーバからの転送や更新が行われる 1 つ以上のファイルを記述した
ファイルです。
.Ar supfile
は、
.Nm sup
で使われる同じ目的のファイルに似た形式です。
ほとんどの場合、
.Nm
は既存の
.Nm sup Ar supfiles
を使えます。
.Pp
省略可能な引数
.Ar destDir
も指定できます。
指定された場合には、この引数は更新された全てのファイルが置かれる
ディレクトリを指定します。
.Ar destDir
が指定されると、クライアントの元のファイルはそのまま残されます。
この機能は主にテストのためのものです。
.Pp
.Nm cvsup
は以下のオプションをサポートしています:
.Bl -tag -width Fl
.It Fl 1
一時的な失敗が起き、かつ GUI が使われていない時の自動リトライを無効に
します。このオプションを指定しないと、ネットワーク接続の切断といった
一時的な失敗が起きた時、
.Nm
はリトライを繰り返し行います。リトライの際には
ランダム化された指数的な一時退避(randomized exponential backoff)
アルゴリズムを用いてリトライの間隔を確保します。
このオプションは
.Fl r Cm 0
と同等であり、GUI を使う時には暗黙的に指定されたことになります。
.It Fl a
クライアントに対して自分自身の認証すること(自分が何であるかを示すこと)
をサーバに要求します。サーバの認証が失敗すると、更新はキャンセル
されます。
後述の
.Sx 認証
を見てください。
.It Fl A Ar addr
サーバに接続する時に割り当てるローカルのアドレス
(ドット区切りの 4 つの数値、またはホスト名)を指定します。このオプショ
ンは、ホストが複数個の IP アドレスを持っている場合に便利です。
.It Fl b Ar base
.Nm
が管理する記録ファイルを置くベースディレクトリを指定します。
この際には、
.Ar supfile
による
.Cm base
の指定は全て上書きされます。
.It Fl c Ar collDir
コレクションに関する情報を管理する、
.Ar base
のサブディレクトリを指定します。
デフォルト値は
.Pa sup
です。
.It Fl d Ar delLimit
更新を 1 回実行した際に削除できるファイル数の上限を指定します。
この上限を超えるファイル削除の試みは致命的なエラーとなります。
このオプションを使うと、サーバ上の一時的な設定ミスによる被害を、
ある程度防げます。
デフォルトでは無制限です。
.It Fl D
.Nm
にファイルの削除だけを行わせ、どんな種類の更新も行いません。
このオプションは、クライアントのディスク容量が非常に少ないといった状況
で役に立ちます。ユーザはまず
.Fl D
オプションを使って
.Nm
を実行してできる限りの容量を空けます。次にもう一度
.Nm
を実行しますが、今度は
.Fl D
オプションは使いません。サーバ上でファイルやディレクトリの名前が変更さ
れた場合は、この方法を取ることにより、クライアント上で新しいファイルが
生成されるよりも前に、全ての古いファイルが削除されることが保証されます。
このオプションは、チェックアウトモードではまだ実装されていません。
.It Fl e
サーバから受け取ったシェルコマンドを、
.Ar supfile
中の全てのコレクションに
.Cm execute
キーワードが追加されたかのように実行機能を有効にします。
.It Fl E
サーバから受け取ったシェルコマンドを、
.Ar supfile
中の全てのコレクションに
.Cm execute
キーワードが追加されたかのように実行する機能を無効にします。
.It Fl g
GUI を使わないようにします。
.Ev DISPLAY
環境変数が設定されていなければ、このオプションが暗黙的に指定されます。
.It Fl h Ar host
接続するサーバホストを指定します。
.Ar supfile
における
.Cm host
の指定は全て上書きされます。
.It Fl i Ar pattern
.Ar pattern
にマッチするファイルとディレクトリだけを更新対象にするように
.Nm
に指定します。ディレクトリがパターンにマッチする場合は、
そのディレクトリをルートとするサブツリー全体が含まれます。
このオプションが複数回指定された場合は、パターンは
.Ql or
操作で結合されます。
.Fl i
オプションが指定されない場合のデフォルト動作では、各コレクションに含ま
れる全てのファイルが更新されます。
.Pp
.Ar pattern
は標準のファイル名パターンです。
これはコレクションのプレフィックスディレクトリからの相対パスで
解釈されます。
スラッシュ文字は、パターン中に陽にスラッシュが書かれた場合だけ
マッチします。
ファイル名の先頭にピリオドがあっても、特別扱いはされません。
.Pp
GUI には、パターンを編集できる入力フィールドがあります。
.It Fl k
チェックサムの不一致が起きた時、間違って編集されたファイル全ての一時的
なコピーを保存するようにします。
このオプションはデバッグ用のものであり、どうしてファイルが誤って編集さ
れたのかを突き止める役に立ちます。
このオプションが指定されているかどうかに関わらず、不正なファイルが
ずっと残っているものは、ファイルを丸ごと転送することによって取得した
正しいファイルに置き換えられます。
このような転送はフィックスアップ(fixup, 修理の意味)と言います。
.It Fl l Ar lockfile
.Ar lockfile
の生成し、更新が行われている間のロックを行います。
.Ar lockfile
が既にロックされていると、
.Nm
は自動的なリトライを行うことなく失敗します。
このオプションが役に立つのは、
.Nm cron
を使って
.Nm
を定期的に実行する時です。
これは、あるジョブが、ネットワークの問題で予想以上の時間がかかっている
以前のジョブの邪魔をするのを防ぎます。
.Pp
POSIX 形式のファイルロッキングが使われます。これは
.Xr fcntl 2
で説明されています。
プロセス ID は、ロックファイルが正常に取得できた時に、このファイルに
テキスト形式で書き込まれます。
更新の終了時にロックファイルは削除されます。
.It Fl L Ar verbosity
GUI でない出力の詳しさを設定します。
レベル 0 では、エラーが起こらない限り
.Nm
は何も出力しません。
レベル 1 (デフォルト値)では、更新されたそれぞれのファイルが出力されます。
レベル 2 では、それぞれのファイルに対して行われた更新に関するさらに
詳しい情報が出力されます。
メッセージは全て、標準出力に出力されます。
GUI が使われる場合は、このオプションは無視されます。
.It Fl p Ar port
.Nm
が接続を試みるサーバホストの TCP ポートを設定します。
この機能は主にテスト用です。デフォルト値は 5999 です。
passive モード(
.Fl P
オプションの説明を参照)でなければ、サーバはこれより一つ小さい番号の
ポートを使って、クライアント向きの 2 つ目の接続を確立します。
.It Fl P Ar m|a|port|lo-hi|-
クライアントとサーバ間の情報のやりとりに使う補助的な TCP 接続の確立を
制御します。
全体では、クライアントとサーバは通信するために 4 つの片方向のチャネルを
必要とします: 2 つはクライアントからサーバへの接続で、2 つはサーバから
クライアントへの接続です。
色々な防火壁の設定に対応するために、これら 4 つの片方向チャネルには色々
な設定ができます。
このために用意されたモードは、multiplexed モード, passive モード、
SOCKS モード、active モードです。
multiplexed モードを除く全てのモードは、古くなっています。
multiplexed モードは、他のモードが扱える全ての状況に対応しています。
.Pp
デフォルトでは、サーバが十分新しければチャネルは multiplexed モードで
確立します。
multiplexed モードは、1 つの TCP 接続を用いて 4 つのチャネルを作ります。
組み込みのパケット多重化層は、TCP 接続上にある異なる論理チャネルを
多重化します。これは
.Nm ssh Ns No \&'s
のポート転送機能とは異なるやり方で行われます。
これにより、非常に小さい(1% 未満)通信オーバーヘッドとごくわずかの CPU 
負荷がかかりますが、ほとんどどんな防火壁の中でも動作するはずです。
防火壁は、クライアントホストがサーバホストの 5999 番ポートへ接続を開始
することを許可していなければなりません。
これ以外には、特殊な許可は全く必要ありません。
明示的に multiplexed モードを指定するには、
.Fl P Cm m
オプションを使います。
.Pp
multiplexed モードは SOCKS プロキシサーバと組み合わせて使えます。
組み合わせて使うには、単に
.Nm m3socks
コマンドの元で
.Nm
を実行し、
.Fl P Cm m
オプションを指定します。
.Pp
active モードは、双方向の TCP 接続を 2 つ使って 4 つの片方向チャネルを
作ります。
クライアントからサーバへの元の接続は 2 つのチャネルを作り、
2 番目の TCP 接続が残りの 2 つのチャネルを作ります。
2 番目の TCP 接続を確立するために、サーバからクライアントへの接続が行
われます。
.Fl P Ar a
で、クライアントはオペレーティングシステムが選んだポート上で
接続を待ちます。
多くのオペレーティングシステムは、この目的には 1024-5000 の範囲の
ポートを使います。
ユーザは
.Fl P Ar port
を使って特定のポートを指定できますし、
.Fl P Ar lo-hi
を使ってある範囲のポートも指定できます。
これらのポート指定は SOCKS プロキシサーバでは使えません。
.Pp
passive モードは、4 つの片方向チャネルを作るために TCP 接続を使うとい
う点では似ています。
しかし、passive モードでは 2 番目の TCP 接続を作るための接続は
クライアントからサーバに対して行われます。
passive モードは、外向きの接続は許可するけれど内向きの接続は禁止してい
る防火壁の中にクライアントがいる場合に便利です。
passive モードを選択するには、
.Fl P Cm -
オプションを使います。
passive モードは SOCKS プロキシサーバでは使えません。
.Pp
SOCKS プロキシサーバを使うための別モードです。
SOCKS モードでは、4 つの TCP 接続が使われます。これらは全て片方向接続
だけです。
4 つの片方向 TCP 接続を使うことにより、SOCKS プロキシサーバの制限を
回避します。これを行わなければ、デッドロックが起こってしまいます。
(信じるかどうかは別にして、SOCKS サーバはブロッキング I/O コールを使い
ます。)
SOCKS モードは、
.Nm
が
.Nm m3socks
コマンドの元で実行され、かつ
.Fl P
オプションが指定されていない時に選択されます。
後述の
.Sx SOCKS と組み合わせての CVSup の利用
もご覧ください。
.It Fl r Ar maxRetries
自動リトライの回数を制限します。自動リトライは、ネットワーク接続が
切れるといった一時的なエラーが起きた時に試みられます。
デフォルトでは、GUI を使っていない時、
.Nm
は更新がうまく完了するまで何度でもリトライを行います。
リトライの間隔は、ランダム化された指数的な一時退避アルゴリズムを使って
決められます。
GUI を使うと、暗黙的に
.Fl r Cm 0
が指定されます。
.Fl r Cm 0
は
.Fl 1
オプションと同じ意味である点に注意してください。
.It Fl s
リストファイルの記録に対しての各クライアントファイルの状態のチェックを
行いません。チェックをしない代わりに、リストファイルは正確であるものと
仮定します。このオプションはディスクアクセスの量を大幅に減らし、
小さなクライアントホストの負荷で高速に更新を行います。しかし、
このオプションは、クライアントのファイルがローカルで修正されていない場
合に限って使うべきです。ミラーサイトは、このオプションを使うと
システムのディスク負荷を減るので利益があるでしょう。安全のために、
ミラーサイトであっても時々(一日一度くらい)は
.Fl s
オプションなしで
.Nm
を実行すべきです。
.Pp
.Fl s
オプションを指定しないと、
.Nm
はファイルごとに
.Xr stat 2
システムコールを実行し、ファイルの属性がリストファイルの記録と一致する
かどうかを確認します。これにより、
.Nm CVSup
外部でのファイル変更は全て検出・訂正されることが保証されます。
.Pp
.Fl s
オプションを指定し、かつローカルでファイルが 1 つ以上変更された時の
結果は未定義です。ローカルファイルの損傷が訂正されないまま残ったり、
更新を取りこぼしたり、
.Nm
が実行途中で異常終了するかもしれません。
.It Fl v
バージョン番号を表示して終了します。サーバへの接続は行いません。
.It Fl z
全てのコレクションの圧縮を有効にします。この動作は、
.Ar supfile
において、
.Cm compress
キーワードを全てのコレクションに追加した時と同様です。
.It Fl Z
全てのコレクションの圧縮を無効にします。この動作は、
.Ar supfile
において、
.Cm compress
キーワードを全てのコレクションから削除した時と同様です。
.El
.Pp
.Ar supfile
は、更新すべきファイルのコレクションを指定するテキストファイルです。
コメントは
.Ql #
で始まり、その行の最後まで続きます。コメントと空白を除くと空である行は
無視されます。残りのそれぞれの行は、サーバ定義のファイルのコレクション
で始まります。この行でコレクション名の後に続くのは、0 個以上のキーワード
または「キーワード=値」の組です。
.Pp
デフォルトの設定は、コレクション名が
.Cm *default
である行で指定できます。
このデフォルトは、
.Ar supfile
内のそれ以降の行に適用されます。
.Cm *default
行は複数個あっても構いません。
新しい値は、
.Ar supfile
で前に指定されたデフォルト値に追加されるか、デフォルト値を上書きします。
コレクションに対して明示的に指定された値は、全てのデフォルト値を
上書きします。
.Pp
特によく使われるキーワードを以下に示します:
.Bl -tag -width Fl
.It Cm release= Ns Ar releaseName
これはコレクション内のファイルのリリースを指定します。
コレクション名と同じく、リリース名もサーバの設定ファイル内で定義されて
います。普通は各コレクション内に 1 つのリリースしか含まれていませんが、
何個含んでもかまいません。CVS リポジトリから得たコレクションでは、
慣習的に
.Cm release=cvs
をよく使います。CVS でないコレクションでは、慣習的に
.Cm release=current
を使います。
.It Cm base= Ns Ar base
これは
.Nm cvsup
が記録ファイルを置いて管理するディレクトリを指定します。
記録ファイルには、クライアントマシン上にある各コレクションの状態が
書かれます。
.Ar base
ディレクトリは既に存在していなければなりません。
.Nm
がこのディレクトリを作成することはありません。
.Ar base
ディレクトリのデフォルト値は
.Pa /usr/local/etc/cvsup
です。
.It Cm prefix= Ns Ar prefix
これは、更新されたファイルが置かれるディレクトリです。
デフォルトでは、これは
.Ar base
と同じです。
絶対パスで指定しなければ、
.Ar base
からの相対パスと解釈されます。
.Ar prefix
ディレクトリは既に存在していなければなりません。
.Nm
がこのディレクトリを作成することはありません。
.Pp
特殊な場合として、
.Ar prefix
が
.Ql SKIP
という名の存在しないファイルを指すシンボリックリンクである場合は、
.Nm
はそのコレクションをスキップします。
この場合でもコレクションに関係するパラメータの正しさはチェックされます
が、コレクションのファイルは全く更新されません。
この機能を使うと、一つのサイトの複数のマシンで標準の
.Ar supfile
を使いながら、更新するコレクションをマシンごとに制御することができます。
.It Cm host= Ns Ar hostname
このオプションは、全てのファイルを取り寄せる元となるサーバマシンを
指定します。
.Nm
は、1 回の実行における全てのコレクションを同じホストから得ることを
必要とします。
異なる複数のホストからコレクションを更新したければ、
.Nm
を複数回実行しなければなりません。
.It Cm delete
このキーワードがあると、
.Nm
はファイルの削除を許可します。
このキーワードがなければ、ファイルは全く削除されません。
.Pp
.Cm delete
キーワードがあると、
.Nm
はいわゆる
.Em exact
モードに入ります。exact モードでは、
.Nm CVSup
はできるだけクライアント側のファイルをサーバ側のファイルに対応させよう
とします。
これは、RCS ファイルから個々の差分とシンボリックなタグを消すことと、
ファイル全体を消すことを含みます。
exact モードでは、
.Nm CVSup
は編集されたそれぞれのファイルをチェックサムを使って調べ、編集によって
サーバ上にあるマスターコピーと同一のファイルができることを保証します。
あるファイルについてチェックサムのテストが失敗したら、
.Nm CVSup
は最後の手段としてファイル全体を転送します。
.Pp
一般的には、
.Nm CVSup
はサーバが知っているファイルだけを削除します。
クライアントのツリーに入っている追加のファイルは、excact モードであっ
てもそのまま残されます。
より正確に述べると、
.Nm CVSup
が消そうとするファイルは 2 種類です:
.Bl -bullet -compact
.It
過去に
.Nm CVSup
自身が生成または更新したファイル。
.It
サーバ上で不要の印が付けられたチェックアウト済みバージョンのファイル。
.El
.It Cm use-rel-suffix
リリースとタグから作ったサフィックスが
.Nm
が管理している各ファイルの名前に追加されるようにします。
詳しくは
.Sx リストファイル
を参照してください。
.It Cm compress
ネットワーク上で送られるデータが全て圧縮されるようにします。
圧縮は非常に有効であり、圧縮しなかった場合に必要な転送量と比べて
普通は 65% から 75% のバイトデータを削減できます。
しかし、クラアイントとサーバ両方の CPU 時間という点ではコストがかかり
ます。
LAN では、圧縮は一般的に生産性を落とします。実際にはファイルの更新が
遅くなってしまいます。
56K ビット/秒あるいはそれ以下の速度の接続では、圧縮はほぼ確実に
得になります。
これら両極端なケースの中間の速度のネットワーク接続では、実験を
行って参考としましょう。
.Pp
.Fl z
コマンドラインオプションは、全てのコレクションに対して
.Cm compress
キーワードを有効にします。supfile での指定とは無関係です。
同様に
.Fl Z
コマンドラインオプションは、全てのコレクションに対して
.Cm compress
オプションを無効にします。
.It Cm norcs
RCS ファイルの特別扱いをなくします。RCS ファイルは他のファイルと
同じように扱われます。
.It Cm norsync
通常の(RCS でない)ファイルの更新の際に、Tridgell と Mackerras の
.Em rsync
アルゴリズムを使いません。
このアルゴリズムはどんな種類のファイルでも正しく動作しますが、
圧縮された tar アーカイブのようなファイルに対しては、
効率的ではありませんし計算的にもコストが高く付きます。
.It Cm strictrcs
更新された RCS ファイルをバイト単位の厳密な MD5 チェックサムで
確認します。通常、
.Nm CVSup
は RCS ファイルに対してもっと緩いチェックサムを用います。これは、
空白文字による無意味な違いを無視します。異なるバージョンの
CVS と RCS は、同じ RCS ファイルに対しても空白が様々に異なります。
したがって厳密なチェックサムを取ると、論理的には同じであるファイルに対
して意味がない不一致を報告するかもしれません。これにより不要な
.Dq fixups
が大量に行われ、更新が遅くなることがあります。
.It Cm nocheckrcs
更新された RCS ファイルに対して、MD5 チェックサムの比較を行いません。
.Cm delete
キーワードが指定されていなければ、このオプションが自動的に
有効になります。
.It Cm execute
サーバから受け取ったシェルコマンドを実行できるようにします。
このオプションは注意して使うべきです。というのも、セキュリティな危険を
及ぼすかもしれないからです。
.It Cm preserve
.Nm
に、可能な全ての属性をサーバからクライアントに転送しようと試みさせます。
サポートされる属性はホストのプラットフォームとクライアントのプラットフォーム
に依存します。FreeBSD システムでは、以下の属性がサポートされています:
.Bl -bullet -compact
.It
所有者
.It
グループ
.It
パーミッション
.It
フラグ
.It
修正時刻
.El
.Pp
これらのうち、最初の 4 つの属性は
.Cm preserve
キーワードで制御します。5 つ目はどんな場合でも保存されます。
.Pp
.Cm preserve
キーワードは、ユーザファイルや CVS リポジトリの更新に使うためのもので
はありません。
これは、ホストの全体のファイルツリーを正確に複製するといった特殊な目的
のためだけに使われます。
.Cm preserve
が指定されていると、サーバホストとクライアントホストの何らかの違いが
問題を起こすかもしれません。
例えば、クライアントマシン上に存在しない所有者が所有するファイルを
クライアントが受け取った場合、オーナを保存することはできません。
同様にこれによって意図しないパーミッションが設定されることがあります。
さらに、それ以降の更新では、毎回クライアント上のファイルの所有者を訂正
しようとして失敗し、時間と帯域幅を無駄にしてしまうでしょう。
最後になりますが、
.Cm preserve
モードはネットワークのトラフィックを増大させ、更新を遅くします。
.Pp
.Cm preserve
モードを正しく機能させるためには、クライアントは root のアクセス権限で
実行しなければなりません。
クライアントが root でなければ、所有者、グループ、フラグの情報を保存し
ようとする機能は無効になります。
.Pp
.Cm preserve
キーワードは、checkout モードでは無視されます。
.It Cm umask= Ns Ar n
コレクション内のファイルを更新する時、
.Nm
に umask 値
.Ar n
(8 進値)を使わせます。
このオプションは、
.Cm preserve
が指定されていると無視されます。
.El
.Pp
いくつかの追加的で、より専門的なキーワードについては後述します。
.Nm sup
との後方互換性のため、認識できなかったキーワードは黙って無視されます。
.Sh 操作
.Nm
は GUI(グラフィカルユーザインタフェース)を持っており、これを使うとユー
ザは更新中の進行状況と処理を監視できます。この GUI は、コマンドライン
オプション
.Fl g
が指定されるか、
.Ev DISPLAY
環境変数が設定されていなければ無効になります。
GUI には、
.Dq Filter
入力フィールドがあります。ここにパターンを入力して、更新するファイルを
制限することができます。
パターンは
.Fl i
オプションの指定と同様に記述します。
複数のパターンを入力する際には、空白で区切らなければなりません。
.Pp
現在のところは、
.Ar supfile
で指定されたパラメータを GUI で変更することはできません。
この点は将来のリリースでの計画になっています。
どちらかというと必要ないものではありますが、GUI は見て楽しいものです。
.Sh CVS モード
.Nm CVSup
は、2 つの主な動作モードをサポートしています。
これらは
.Em CVS
モードと
.Em checkout
モードと呼ばれるものです。
.Pp
CVS モードでは、クライアントはマスターの CVS リポジトリを構成している
実際の RCS ファイルのコピーを受信します。CVS モードはデフォルトの動作
モードです。
このモードは、CVS リポジトリの完全なコピーをクライアントマシン上でメン
テナンスしようとユーザが考えている場合には適しています。
.Pp
CVS モードは、CVS リポジトリベースでないファイルのコレクションに対して
もうまく使えます。この場合にはファイルは解釈されることなく、単にそのま
ま転送されます。
.Sh checkout モード
checkout モードでは、クライアントは特定のリビジョンのファイルを受信し
ます。これはサーバの CVS リポジトリから直接チェックアウトされます。
checkout モードを使うと、クライアントは任意のバージョンをリポジトリか
ら取得できます。この際、チェックアウトされる時の形で複数個のバージョン
をサーバ上に持つ必要はありません。
しかし、checkout モードでは、その基本機能よりもずっと柔軟に動作させる
ことができます。
います。
クライアントは CVS のシンボリックタグを指定できますし、任意の日付の指
定もできます。両方を指定することもできます。また
.Nm CVSup
は、この指定に対応するファイルをリポジトリ内からチェックアウト形式で取
り出すことができます。
.Pp
checkout モードはコレクション別に指定します。指定は、
.Ar supfile
内に以下のキーワードの一つあるいは両方を含めることによって行います:
.Bl -tag -width Fl
.It Cm tag= Ns Ar tagname
シンボリックタグを指定します。このタグは、CVS リポジトリから取り出すリ
ビジョンを選択するために使わなければなりません。
このタグはブランチまたは特定のリビジョンを示すことができます。
タグはシンボリックでなければなりません。つまり、数値のリビジョン番号は
サポートされていません。
.Pp
FreeBSD のソースリポジトリの場合は、以下のタグがよく使われます:
.Bl -tag -width RELENG_3
.It Li RELENG_3
.Ql stable
ブランチ。
.It Li \&.
メインブランチ(
.Ql current
リリース)。
.Cm date
キーワードだけが指定されると、こちらがデフォルトです。
.El
.Sm off
.It Xo Cm date=
.Op Ar cc
.Ar yy.mm.dd.hh.mm.ss
.Xc
.Sm on
これは、CVS リポジトリからチェックアウトするリビジョンの選択に使う日付
を指定します。
クライアントは実際には、指定された日付と時刻のリビジョンを受け取ります。
.Pp
現時点では、日付のフォーマットは柔軟ではありません。17 文字あるいは 19 
文字の全てを、説明したフォーマットで正確に指定しなければなりません。
2000 年以降の場合は、世紀を
.Ar cc
で指定します。
これより前の年の場合は、最後の 2 桁だけを
.Ar yy
で指定します。
日付と時刻は GMT で扱います。
デフォルトの日付は
.Ql \&.
です。これは
.Dq できるだけ新しいもの
という意味です。
.El
.Pp
checkout モードを有効にするためには、少なくともこれらのキーワードの
いずれかを指定しなければなりません。
どちらも指定されていなければ、
.Nm CVSup
はデフォルトの CVS モードで動作します。
.Pp
ブランチタグと日付が両方とも指定されると、指定されたブランチ上の
指定された日付の時点のリビジョンがチェックアウトされます。
日付を特定のリリースタグに付けて指定することもできますが、あまり役には
立たないでしょう。
.Pp
checkout モードでは、タグや日付を更新と更新の間に変えられます。
例えば、
.Ql tag=.
という指定を使ってコレクションが転送されたとしましょう。
ユーザは後から指定を
.Ql tag=RELENG_3
に変えられます。
これを指定すると、
.Nm CVSup
はチェックアウトされたファイルを編集し、
.Ql current
バージョンが
.Ql stable
バージョンになるようにします。
一般的には、
.Nm CVSup
はどんなタグ/日付の組合せであっても、他のタグ/日付の組合せに変換してく
れます。変換は、両者の間にある RCS の差分を既存のファイルに適用するこ
とによって行います。
.Pp
チェックアウトされたファイルのコレクションを、あるタグから別のタグに
変換するときには、変換の前後で必ず同じリストファイルが使われるようにす
るため、
.Ar supfile
ファイル中で
.Cm list
キーワードを指定することが重要です。
リストファイルは次の
.Sx リストファイル
の節で説明します。
.SH リストファイル
効率のため、
.Nm
は各コレクションについての記録ファイルを管理しています。
これをリストファイルと呼びます。
リストファイルには、クライアントが現在持っているファイルとリビジョンに
関する情報が書かれています。
このファイルには、クライアントのツリーに入っている実際のファイルと
リストファイルが一致していることを確認するための情報も書かれています。
.Pp
厳密に言うとリストファイルは必要ではありません。このファイルが削除され
るか、クライアントが持っている実際のファイルとの不一致が起こると、
.Nm
は最後の手段として少し効率の悪い方法でクライアント側のファイルの識別と
更新を行います。
この際には、
.Nm CVSup
の動作モードによって、タイムスタンプ、チェックサム、RCS ファイルの
解析結果などが使われます。
.Pp
リストファイルは不可欠ではないので、
.Nm
は FTP や CD-ROM から入手した既存のファイルツリーを「利用」できます。
.Nm
はクライアント側のファイルのバージョンを識別し、必要に応じてこれを更新
します。さらに、将来使うためにリストファイルを生成します。
他のシステムが作ったファイルツリーを使う場合の動作は、通常の更新ほど
高速ではありません。
また、サーバにかかる負荷も高くなります。
リストファイルはコレクション固有のディレクトリに保存されます。詳しくは
.Sx ファイル
セクションをご覧ください。
リストファイルの名前は必ず
.Ql checkouts
で始まります。
.Ar supfile
内でキーワード
.Cm use-rel-suffix
が指定されていると、リリースとタグから作ったサフィックスがファイル名に
追加されます。
デフォルトのサフィックスは、
.Ar supfile 
で明示的にサフィックスを指定することにより上書きされます:
.Bl -tag -width Fl
.It Cm list= Ns Ar suffix
これはリストファイルの名前に付けるサフィックスの指定です。サフィックス
の先頭のドットは自動的に付けられます。
例えば、
.Ql list=stable
とすると、
.Pa checkouts.stable
という名前のリストファイルが作られます。この場合には、リリース、タグ、
.Cm use-rel-suffix
キーワードは関係ありません。
.El
.Sh refuse ファイル
ユーザは受け取りたくないファイルの集合を指定できます。
こういったファイルは、いわゆる
.Em refuse
ファイル内でファイル名パターンとして指定されます。
パターンは空白文字で区切られ、各行には複数個のパターンを置くことができます。
パターンにマッチするファイルとディレクトリは、更新も削除もされません。
これらのファイルは単に無視されます。
.Pp
現在は、refuse ファイル内にコメントに書く方法はありません。
.Pp
パターンは
.Xr sh 1
のそれと似ていますが、スラッシュの特別扱いや、ピリオドで始まるファイル
の特別扱いがない点が異なります。
例えば、パターン
.Ql *.c
は
.Ql \&.c
で終わる全てのファイルにマッチします。これには
.Ql foo/bar/lam.c
といったサブディレクトリ内のファイルも含まれます。
全てのパターンはコレクションのプレフィックスディレクトリからの相対パス
として解釈されます。
.Pp
これらファイルが CVS リポジトリから得たものならば——普通はそうなのです
が——これらは RCS ファイルとなります。これらのファイルには、
.Ql \&,v
というサフィックスが付きます。パターンについてはサフィックスも考慮に入
れなければなりません。例えば、FreeBSD の文書ファイルは
.Ql doc
という
.Ar base
ディレクトリのサブディレクトリに入っています。
そのディレクトリにある
.Ql Makefile
が不要な場合に
.Pp 
.Bl -item -compact -offset indent
.It 
.Pa doc/Makefile
.El
.Pp
と指定してもうまく動作しません。なぜなら、サーバ上にあるファイルは
.Ql Makefile,v
だからです。
もっとよい解決方法は、
.Pp
.Bl -item -compact -offset indent
.It
.Pa doc/Makefile*
.El 
.Pp 
と指定することです。この指定であれば、
.Ql Makefile
が RCS ファイルであろうとなかろうとマッチします。
.Pp
別の例としては、日本語、ロシア語、中国語の翻訳を避けて FreeBSD 文書
ファイルを取得するには、以下の行を含む refuse ファイルを作ります:
.Pp
.Bl -item -compact -offset indent
.It
.Pa doc/ja*
.It
.Pa doc/ru*
.It
.Pa doc/zh*
.El 
.Pp
それぞれの
.Ar supfile
行は、3 つの refuse ファイルによって調べられます。
大域的な refuse ファイルとして
.Sm off
.Ar base / Ar collDir Pa /refuse
.Sm on
があります。これは全てのコレクションとリリースに適用されます。
コレクション別の refuse ファイルとして
.Sm off
.Xo Ar base / Ar collDir / Ar collection
.Pa /refuse
.Xc
.Sm on
があります。これは特定のコレクションに適用されます。
最後に、リリースとタグ別の refuse ファイルがあります。これは、
コレクション内の指定されたリリース/タグの組み合わせに対してのみ適用さ
れます。
最後の refuse ファイルの名前は、コレクション別の refuse ファイルの名
前にサフィックスを加えることによって付けられます。これは先に説明したリ
ストファイルと同じ方法です。
どんな種類の refuse ファイルも存在しなくてもかまいません。
.Pp
.Nm
は、
.Ar collDir
に対する
.Ar base
と
.Ar sup
の組み込みのデフォルト値を
.Ar /usr/local/etc/cvsup
に持っていますが、どちらの値も上書き可能です。
.Ar base
の値は
.Fl b
オプションまたは
.Ar supfile
ファイル中の
.Ar base=pathname
エントリで変更できます。
(両方指定した場合は、
.Fl b
オプションの方が
.Ar supfile
のエントリよりも優先されます。)
.Ar collDir
の値は
.Fl c
オプションでしか変更できません。これを変更する
.Ar supfile
コマンドはありません。
.Pp
例えば、
.Ar base
と
.Ar collDir
の両方にデフォルト値が設定されており、コレクションが
.Ql src-all
でリリースが
.Ql cvs
である場合を考えます。
さらに、
.Ql tag=RELENG_3
に対して checkout モードが使われているものとします。
この場合、refuse ファイルの名前としては以下の 3 つが考えられます:
.Pp
.Bl -item -compact -offset indent
.It
.Pa /usr/local/etc/cvsup/sup/refuse
.It
.Pa /usr/local/etc/cvsup/sup/src-all/refuse
.It
.Pa /usr/local/etc/cvsup/sup/src-all/refuse.cvs:RELENG_3
.El
.Pp
.Ar supfile
がコマンド
.Ar base=/foo
を含んでいる場合、refuse ファイルは以下のようになります:
.Pp
.Bl -item -compact -offset indent
.It
.Pa /foo/sup/refuse
.It
.Pa /foo/sup/src-all/refuse
.It
.Pa /foo/sup/src-all/refuse.cvs:RELENG_3
.El
.Pp
.Fl b
.Ar /bar
が使われている場合(
.Ar supfile
ファイル中に
.Ar base=/foo
コマンドがあっても):
.Pp
.Bl -item -compact -offset indent
.It
.Pa /bar/sup/refuse                
.It
.Pa /bar/sup/src-all/refuse                
.It
.Pa /bar/sup/src-all/refuse.cvs:RELENG_3                
.El
.Pp
そして
.Fl c
.Ar stool
も使われている場合:
.Pp
.Bl -item -compact -offset indent
.It
.Pa /bar/stool/refuse
.It 
.Pa /bar/stool/src-all/refuse
.It
.Pa /bar/stool/src-all/refuse.cvs:RELENG_3
.Sh 認証
.Nm CVSup
は認証機構を備えており、これを使ってクライアントとサーバがお互いの身元
を確認することができます。この機構は、パケット盗聴やリプレイ攻撃の影響
を受けない challenge-response プロトコルを用いています。ネットワーク上
では、パスワードはどちらの向きにも流れません。クライアントとサーバのい
ずれも、お互いの身元を独立に確認できます。
.Pp
ファイル
.Li $ Ns Ev HOME Ns Pa /.cvsup/auth
には認証に使われる情報が書かれています。このファイルには、クライアント
がアクセス可能な各サーバについてのレコードが入っています。それぞれの
レコードは、ファイル中に 1 行で書かれます。
.Ql #
で始まる行は無視されます。空白文字だけの行も同様です。ただし、ファイル
中の他の場所では空白文字も意味を持ちます。フィールドは
.Ql \&:
文字で区切られます。
.Pp
ファイルの各レコードは以下の形式です:
.Bd -literal -offset indent
.Sm off
.Xo Ar serverName No : Ar clientName No :
.Ar password No : Ar comment
.Xc
.Sm on 
.Ed 
.Pp 
たとえ空であっても、全てのフィールドは存在しなければなりません。
.Ar ServerName
はレコードが適用されるサーバ名です。慣習的に、これはカノニカルかつ完全
にドメイン名が指定されたサーバ名です(例:
.Ql CVSup177.FreeBSD.ORG
)。
これはサーバが自分の名前と考えているホスト名でなければなりません。
名前については大文字・小文字は区別されません。
.Pp
.Ar ClientName
はクライアントがサーバへのアクセス権を得るときに使う名前です。慣習的に、
クライアント名には全て e-mail アドレスが使われます(例:
.Ql BillyJoe@FreeBSD.ORG
)。クライアント名では大文字・小文字は区別されません。
.Pp
.Ar Password
は秘密の文字列であり、クライアントが身元を証明するために使います。
パスワード文字列は
.Ql \&:
や改行文字を含んではいけません。
.Pp
.Ar Comment
はレコードを識別するための付加的な情報を持ちます。プログラムに解釈され
ることはありません。
.Pp
指定されたサーバに対する認証の設定を行うには、以下の手順を実行しなけれ
ばなりません:
.Bl -enum
.It
サーバ管理者または別の情報源から公式な
.Ar serverName
を取得します。
.It
適切な
.Ar clientName
を選びます。
これは有効な電子メールアドレスの形式にすべきです。これは、サーバ管理者
が必要に応じてユーザに連絡しやすくするためです。
.It
秘密の
.Ar password
として任意の文字列を選びます。
.It
.Nm cvpasswd
ユーティリティを実行し、質問に対して
.Ar パスワード
を入力します。このユーティリティはサーバの管理者に送る行を出力し、
それからユーザの
.Li $ Ns Ev HOME Ns Pa /.cvsup/auth
ファイルの修正手順を示します。この行をサーバ管理者に送るには、安全な
手段を使うべきです。
.El
.Pp
.Li $ Ns Ev HOME Ns Pa /.cvsup/auth
にはパスワードが入っているので、必ず自分以外には誰も読めないようにして
ください。
.Pp
認証はそれぞれの向きで独立に動作します。サーバの管理者は、
ユーザが身元を証明しなければならないかどうかを制御します。
ユーザはサーバの身元をチェックするかどうかを制御します。制御には
.Fl a
コマンドラインオプションを使います。
.Sh ミラーリングのための CVSup の使用
.Nm CVSup
は CVS リポジトリ用に最適化されているので、汎用的なミラーリングとして
非常にうまく動作します。
.Nm CVSup
はどんな種類のファイルの更新にも使えます。
.Bl -bullet -compact
.It
RCS ファイルの更新は、個々のタグと差分の転送および、これらの
クライアント側のファイルへのマージによって行われます。
.It
通常ファイルは、可能であれば rsync アルゴリズムを使って更新されます。
rsync アルゴリズムが無効にされている場合、追加されたデータを持つサーバ
上のファイル(例: ログファイル)は、新しく加わった末尾の部分だけを受け取
ります。
他の通常ファイルはまるごと置き換えられます。
.It
空のディレクトリは残されます。
.It
シンボリックリンクは、サーバの設定ファイル内で
.Cm symlink
と
.Cm rsymlink
コマンドが指定されていると更新されます。詳しくは
.Xr cvsupd 8
をご覧ください。
.It
ハードリンクはそれぞれのコレクション内では保存されますが、コレクション
間では保存されません。
.It
デバイスノードはメジャー番号とマイナー番号を使って更新されます。
クライアントのホストとサーバのホストで異なるオペレーティングシステムが
動作していると、これは望ましい結果とならないことがあります。
.El
.Sh CVSup と防火壁
.Nm
は、様々な設定の防火壁を超えるために数多くのモードを用意しています。
これらのモードは
.Fl P
オプションか、
.Nm m3socks
コマンドを使って制御できます。
.Nm
を使えるようにするには、防火壁はサーバホストの 5999 番ポートへの外向き
の接続を最低限許可しなければなりません。
この条件が満たされていれば、SOCKS の有無に関わらず多重モード
.Pq Fl P Cm m
が動作するはずです。
.Pp
もう少し防火壁の制限が緩ければ、passive モードや他のモードの一つを使っ
て、効率を少し上げることができます。
詳しくは
.Fl P
オプションの説明をご覧ください。
.Pp
特定の種類の防火壁と CVSup を組み合わせて使う際の情報については、
.Aq http://www.polstra.com/projects/freeware/CVSup/
にある CVSup FAQ をご覧ください。
.Sh SOCKS と組み合わせての CVSup の利用
SOCKS プロキシサーバ経由での通信は、現在は FreeBSD 上でしかサポートさ
れていません。
これを用いるためには、port として用意されている
修正版の Modula-3 の実行時システム(
.Pa lang/modula-3-lib
)とアドオンの SOCKS ライブラリ(
.Pa lang/modula-3-socks
)が必要です。
また、SOCKS ライブラリは動的リンク技術を使うので、
.Nm
の実行ファイルは完全に動的リンクされている必要があります。
FreeBSD の port の
.Pa net/cvsup
は、必要に応じて
.Nm
を完全に動的にリンクします。
.Pp
SOCKS の動作を有効にするには、単に
.Pa lang/modula-3-socks
パッケージに含まれる
.Cm m3socks
と組み合わせて
.Nm
を実行してください。
詳細については
.Xr m3socks 1
をご覧ください。
.Sh ssh を使ったポート転送
防火壁の内側のユーザは、SOCKS の代替品として、Secure Shell パッケージの
.Nm ssh
が持っている TCP ポート転送機能を使って防火壁を通過できます。
これを行うためには、ユーザは
.Nm CVSup
のサーバホストにログインアカウントが必要です。
手順を以下に示します:
.Bl -enum
.It
以下のようにして、
.Nm ssh
を使ってサーバホストとの接続を確立します:
.Bd -literal
ssh -f -x -L 5999:localhost:5999 serverhost sleep 60
.Ed
.Pp
普通は
.Ar serverhost
を CVSup サーバのホスト名に置き換えるのですが、ここでは
.Ql localhost
を入力します。
これにより、ポート転送に必要な設定ができます。
60 秒経って
.Nm sleep
が終わるまでに
.Nm
を起動しなければなりません。
いったん更新が始まると、
.Nm ssh
は必要な間、転送チャネルをオープンした状態を保ちます。
.It
ローカルホストで
.Nm
を実行します。コマンドラインには以下の行を含めます:
.Ql -h localhost -P m
.El
.Sh ファイル
.Bl -tag -width base/sup/collection/checkouts*xx -compact
.It Pa /usr/local/etc/cvsup
デフォルトの
.Ar base
ディレクトリ。
.It Pa sup
デフォルトの
.Ar collDir
サブディレクトリ。
.Sm off
.It Xo Ar base / Ar collDir / Ar collection
.Pa /checkouts*
.Xc
.Sm on
リストファイル。
.Sm off
.It Ar base / Ar collDir Pa /refuse
.Sm on
グローバルの refuse ファイル。
.Sm off
.It Xo Ar base / Ar collDir / Ar collection
.Pa /refuse*
.Xc
.Sm on
コレクション別の refuse ファイルと、リリースとタグ別の refuse ファイル。
.It Li $ Ns Ev HOME Ns Pa /.cvsup/auth
認証用のパスワードファイル。
.El
.Sh 関連項目
.Xr ctm 1 ,
.Xr cvpasswd 1 , 
.Xr cvs 1 ,
.Xr cvsupd 8 ,
.Xr m3socks 1 ,
.Xr rcsintro 1 ,
.Xr ssh 1
.Pp
.Bd -literal
http://www.polstra.com/projects/freeware/CVSup/
.Ed
.Sh 作者
.An John Polstra Aq jdp@polstra.com
.Sh バグ
RCS ファイルは
.Ql \&,v
で終わっていなければ RCS ファイルと認識されません。
.Pp
.Ql Attic
という名前のディレクトリは CVS Attic として特別扱いされます。
.Pp
SOCKS ライブラリまたはサーバのバグのため、大部分の形式の
.Fl P
オプションは SOCKS では使えません。
多重モード
.Pq Fl P Cm m
を使えますが、他の形式の
.Fl P
オプションは受け付けられません。
.Pp
GUI と一部のウィンドウマネージャ(特に FVWM)の相性が良くありません。
FVWM のバージョン 1, 2 のどちらでも問題が起こるのですが、バージョン 2
の方がまだましのようです。
.Pp
.Dl Style \&"cvsup\&" ClickToFocus
.Pp
という行を FVWM2 の
.Pa .fvwmrc
に追加するとかなりよくなります。
この問題はどうやらウィンドウマネージャのバグが原因らしく、GUI が
.Ql WM_TAKE_FOCUS
プロトコルを使うと起こるようです。
回避策としては、
.Fl g
オプションを使って、GUI を完全に無効にするとよいでしょう。