doc/ja_JP.eucJP/man/man8/ntpq.8

.\"
.\" %FreeBSD: src/usr.sbin/ntp/doc/ntpq.8,v 1.3.2.5 2001/03/06 14:21:28 ru Exp %
.\"
.\" $FreeBSD$
.Dd January 7, 2000
.\" 対訳覚え書き (seki@sysrap.cs.fujitsu.co.jp 作成)
.\" WORD: dotted-quad form	ドットで 4 つの部分に区切られた形式
.\" WORD: association		アソシエーション[NTP]
.\" WORD: association identifier	アソシエーション識別子[NTP]
.\" WORD: key identifier	鍵の識別子
.\" WORD: key number		鍵番号
.\" WORD: authentication	認証
.\" WORD: clock			時計
.\" WORD: reference clock	参照クロック
.\" WORD: falsetick		偽時計
.\" WORD: dispersion		ばらつき
.\" WORD: fuzzball		fuzzball (固有名詞; ntpd ベースでない NTP サーバ)
.\" WORD: offset		ずれ
.\" WORD: poll			ポーリングする
.\" WORD: query			問い合わせ
.\" WORD: status word		状態ワード
.\" WORD: time out (名詞)	制限時間
.\" WORD: time out (動詞)	時間切れ
.\" WORD: intersection algorithm	交差アルゴリズム
.Dt NTPQ 8
.Os
.Sh 名称
.Nm ntpq
.Nd NTP の標準問い合わせプログラム
.Sh 書式
.Nm
.Op Fl inp
.Op Fl c Ar command
.Op Ar host ...
.Sh 解説
.Nm
は、
推奨されている NTP モード 6 制御メッセージフォーマットを実装する NTP サーバに、
現在の状態について問い合わせを行なったり、
状態の変更を要求するために使います。
このプログラムは、対話的モードでもコマンドライン引数を
使った制御でも動作させることができます。
任意の変数を読み書きするリクエストを組み立てることができ、
生のまま、または綺麗に整形して出力するオプションがあります。
.Nm
は、サーバに複数の問い合わせを送ることで
通信相手 (peer) のリストを得て、共通なフォーマットで出力することができます。
.Pp
.Nm
が実行されたとき、1 つ以上のリクエストオプションが、
コマンドラインに含まれる場合は、それぞれのリクエストは、コマンドライン
引数で与えられた各ホスト、またはデフォルトである
.Dq localhost
で動いている NTP サーバに送られます。
リクエストオプションが与えられなかった場合、
.Nm
は、コマンドを標準入力から読み込み、
コマンドラインで指定された最初のホストで動いている
NTP サーバに対して実行しようとします。
このときも、
ホストが指定されていないときは、デフォルトで
.Dq localhost
になります。
.Nm
は標準入力が端末である場合は、プロンプトを出してコマンドを受け付けます。
.Pp
.Nm
は NTP サーバとの通信に、NTP モード 6 パケットを使うため、
ネットワーク上でそれを許すような互換サーバへの問い合わせに使用できます。
NTP は UDP のプロトコルなので、特にネットワークトポロジ的に
遠くにある場合は、この通信はやや信頼性に欠けるということに注意して
ください。
.Nm
は、リクエストを再送する試みを一度行ない、
適当な制限時間の範囲内でリモートホストから返事がなかったときは、
そのリクエストは時間切れとなります。
.Pp
コマンドラインオプションは以下の通りです。
.Fl i
または
.Fl n
以外のコマンドラインオプションを指定すると、指定したホスト (群) に、
指定した問い合わせ (または複数の問い合わせ) を直ちに送ることになります。
指定しなかった場合、
.Nm
は標準入力から対話的なフォーマットのコマンドを読み込もうとします。
以下のオプションが使用可能です:
.Bl -tag -width indent
.It Fl c Ar command
後に続く引数は、対話的なフォーマットのコマンドとして解釈され、
指定されたホスト (群) に対して実行すべきコマンドのリストに
付け加えられます。
複数の
.Fl c
オプションを与えることもできます。
.It Fl i
.Nm
を強制的に対話的モードで動作させます。標準出力にプロンプトが
表示され、標準入力からコマンドが読み込まれます。
.It Fl n
すべてのホストアドレスを、ドットで 4 つの部分に区切られた数値の形式で出力し、
正規のホスト名に変換しません。
.It Fl p
サーバに既知な通信相手のリストと、それらの状態の概要を出力します。
これは、対話コマンド
.Ic peers
と同等です。
.El
.Ss 内部コマンド
対話的なフォーマットのコマンドは、キーワードとそれに続く 0 から 4 個の
引数から構成されます。キーワード全長のうち、他と区別できる文字数が
タイプされれば、有効になります。
コマンドの出力は通常標準出力に送られますが、コマンドライン上で
.Qq >
に続けてファイル名を指定することで、個々のコマンドの出力を
ファイルに送ることができます。
いくつかの対話的フォーマットのコマンドは、
.Nm
プログラム自身の中で全体が実行され、サーバへの NTP モード 6 リクエストは
送られません。この種類のコマンドには以下のものがあります。
.Bl -tag -width indent
.It Ic ?\& Op Ar command_keyword
.It Ic help Op Ar command_keyword
単独の
.Ic ?\&
は、
.Nm
が知っているすべてのコマンドキーワードのリストを出力します。
.Ic ?\&
の後にコマンドキーワードが続くときは、コマンドの機能と用法を出力します。この
コマンドは、
.Nm
に関して、多分このマニュアルよりも良い情報源となるでしょう。
.\"
.\" XXX Both variable_name and value below should be arguments,
.\"	not angle-quoted text.
.\"
.It Xo Ic addvars
.Aq variable_name Ns
.Op = Ns Aq value Ns
.Op ,...
.Xc
.It Xo Ic rmvars
.Aq variable_name Ns
.Op ,...
.Xc
.It Ic clearvars
NTP モード 6 メッセージが運ぶデータは、次の形の
項目のリストから成ります。
.Sm off
.Ao variable_name Ac = Aq value
.Sm on
ここで、サーバの変数を読み取るリクエストでは、この
.Qq = Ns Aq value
は無視されるので、省略することができます。
.Nm
は、制御メッセージに含まれるデータを組み立てるための内部リストを保持しており、
以下に述べる
.Ic readlist
や
.Ic writelist
コマンドを使って送ります。
.Ic addvars
コマンドで、このリストに、変数と省略可能な値を追加することができます。
1 つより多くの変数を追加するときには、リストはコンマで区切り、
空白を含んではいけません。
.Ic rmvars
コマンドは、個々の変数をリストから削除するために用い、
.Ic clearvars
コマンドは、リストからすべての変数を削除します。
.It Ic authenticate Ar yes | Ar no
通常、
.Nm
は、
書き込みリクエストでない限りリクエストを認証しません。
コマンド
.Dq Li authenticate yes
は、
.Nm
が生成するすべてのリクエストに認証をつけて送るようにします。
認証されたリクエストの扱いはサーバによって少し異なります。
もしも通信相手の表示を行う前に認証をオンにすると、
時々 fuzzball の CPU を溶かしてしまうかもしれません。
.It Ic cooked
問い合わせコマンドからの出力を、
.Qq 加工済み (cooked)
形式にします。
サーバに認識された変数は、人間に使える形に再整形された値に
なります。
.Nm
が、その変数は本来デコードできる値を持っていると判断したのに、
デコードされていないものには、その後に
.Qq ?
が付けられます。
.It Ic debug Xo
.Ar more | Ar less | Ar off
.Xc
内部の問い合わせプログラムのデバッグをオンまたはオフにします。
.It Ic delay Ar milliseconds
認証を求めるリクエストに含まれるタイムスタンプに加えられる時間間隔を
指定します。これは、長い遅延のあるネットワーク経路や時計の同期していない
マシン間で (信頼できない) サーバの再設定ができるようにするために
使われます。
実際にはもうサーバは認証リクエストにおいてタイムスタンプを要求しませんので、
このコマンドはもはや用いられないかもしれません。
.It Ic host Ar hostname
今後問い合わせを送るホストを指定します。
与える
.Ar hostname
は、ホスト名でも数値アドレスでもかまいません。
.It Ic hostnames Ar yes | Ar no
.Ar yes
が指定されると、情報の表示の際、ホスト名が使用されます。
.Ar no
が与えられると、代わりに数値アドレスが使用されます。
コマンドラインの
.Fl n
スイッチによって変えられていなければ、
デフォルトは
.Ar yes
になります。
.It Ic keyid Ar keyid
このコマンドで、認証設定リクエストに使われる鍵番号を指定できます。
この番号は、サーバが認証のために使うよう設定した鍵番号に対応して
いなければなりません。
.It Ic ntpversion Xo
.Ar 1 | Ar 2 |
.Ar 3 | Ar 4
.Xc
.Nm
がパケットの中で自称する NTP のバージョン番号をセットします。
デフォルトでは 3 になります。
モード 6 制御メッセージ (詳しく言うとモードも) は、
NTP バージョン 1 には存在しなかったことに注意してください。
バージョン 1 を必要とするサーバは残っていないようですが。
.It Ic quit
.Nm
を終了します。
.It Ic passwd
このコマンドは、認証設定リクエストに使われるパスワードの入力
(画面に表示されません) を求めるプロンプトを出します。
このリクエストが成功するためには、NTP サーバが認証のために使うよう
設定した鍵に、パスワードが対応していなければなりません。
.It Ic raw
問い合わせコマンドに対するすべての出力を、リモートサーバから受け取った
通りに出力します。
データに対して行なわれる唯一の整形と解釈は、印字できる
(しかしめったに理解できない) 形になるように、ASCII 文字でないデータを
変換することだけです。
.It Ic timeout Ar milliseconds
サーバへの問い合わせに対する応答の制限時間を指定します。デフォルト
は、約 5000 ミリ秒です。
.Nm
はそれぞれの問い合わせに対して時間切れを待ったあと再試行するため、
合計の待ち時間は設定された制限時間の値の 2 倍になることに注意してください。
.El
.Ss 制御メッセージコマンド
ある NTP サーバが知っている各通信相手には、
アソシエーション識別子
(association identifier)
という 16 ビット整数が割り当てられています。
peer 変数を使う NTP 制御メッセージは、
アソシエーション識別子を含めることによって、
その値が対応する通信相手を識別しなければなりません。
0 というアソシエーション識別子は特別で、
その変数がシステム変数であることを表します。
システム変数の名前は、独立した名前空間から取りだされます。
.Pp
制御メッセージコマンドは、
サーバに 1 つ以上の NTP モード 6 メッセージを送り、
戻ってきたデータを何らかの書式で出力します。
現在実装されているほとんどのコマンドは、
1 つのメッセージを送って、1 つの応答を受け取ります。
今のところ例外は、必要なデータを得るためにあらかじめプログラムされた一連の
メッセージを送る
.Ic peers
コマンドと、
アソシエーションを越えた範囲で繰り返す
.Ic mreadlist
と
.Ic mreadvar
コマンドです。
.Bl -tag -width indent
.It Ic associations
問い合わせ対象のサーバの規格内 (in-spec) の通信相手についての、
アソシエーション識別子と通信相手の状態の一覧を得て出力します。
一覧は複数の欄から成っています。
最初の欄は、内部使用のために 1 から振ったアソシエーションの索引番号 (index)、
2 番目はサーバから返って来た実際のアソシエーション識別子、
3 番目は通信相手の状態ワードです。
その後に、状態ワードをデコードしたデータを含む欄がいくつか続きます。
.Ic associations
コマンドによって返されたデータは
.Nm
の内部でキャッシュされるということに注意してください。
このため、索引番号は、
人間にはほとんど打ち込むることができないアソシエーション識別子を使う
愚かなサーバを相手にするときに役立ちます。
すなわち、
それ以降の任意のコマンドが引数としてアソシエーション識別子を必要とするときに、
代わりに
.Dq Li &index
という形を使うことができます。
.\"
.\" XXX Both variable_name and value below should be arguments,
.\"	not angle-quoted text.
.\"
.It Xo Ic clockvar
.Op Ar assocID Ns
.Pf [ Aq variable_name Ns
.Op = Ns Aq value Ns
.Op ,...]
.Xc
.It Xo Ic cv
.Op Ar assocID Ns
.Pf [ Aq variable_name Ns
.Op = Ns Aq value Ns
.Op ,...]
.Xc
サーバの時計変数 (clock variable) の一覧を送るように要求します。
ラジオ時計や他の外部同期機構を持っているサーバは、
このコマンドに肯定的に応答します。
アソシエーション識別子が省略されるか 0 だと、
リクエストは
.Qq システム時計
の変数に対するものとなり、
一般に、時計を持つすべてのサーバから肯定的な応答が得られるでしょう。
サーバが時計を擬似的な通信相手として扱い、
結果として一度に 2 つ以上の時計を接続することができるようになっていれば、
適切な通信相手のアソシエーション識別子を参照すれば
特定の時計の変数が表示されます。
変数のリストを省略すると、サーバはデフォルトの変数の表示を
返すことになります。
.\" assocation -> association (send-pr docs/17501)
.It Ic lassociations
サーバが状態を保持しているすべてのアソシエーションについて
アソシエーション識別子と通信相手の状態の一覧を得て、出力します。
このコマンドと
.Ic associations
コマンドは、
規格外 (out-of-spec) のクライアントのアソシエーション
の状態を保持するサーバ (つまり fuzzball) の場合にだけ異なります。
.Ic associations
コマンドが使われたとき、通常そういうアソシエーションは
表示から省略されますが、
.Ic lassociations
の出力には含まれます。
.It Ic lpassociations
規格外 (out-of-spec) のクライアントとのアソシエーションを含む
全てのアソシエーションに関するデータを、
内部にキャッシュされたアソシエーションの一覧から出力します。
このコマンドは、fuzzball を扱う場合だけ、
.Ic passociations
と異なります。
.It Ic lpeers
.Ic peers
と似ていますが、
サーバが状態を保持しているすべてのアソシエーションの概要を出力します。
これは fuzzball サーバの、より長い通信相手のリストを生成することがあります。
.It Ic mreadlist Ar assocID assocID
.It Ic mrl Ar assocID assocID
.Ic readlist
コマンドと似ていますが、
問い合わせを (0 でない) アソシエーション識別子の範囲のそれぞれに
行ないます。
ここで言う範囲は、直前に実行された
.Ic associations
コマンドでキャッシュされたアソシエーションの一覧から決められます。
.It Xo Ic mreadvar
.Ar assocID assocID Oo
.Aq variable_name Ns
.Op = Ns Aq value Ns
.Op ,... Oc
.Xc
.It Xo Ic mrv
.Ar assocID assocID Oo
.Aq variable_name Ns
.Op = Ns Aq value Ns
.Op ,... Oc
.Xc
.Ic readvar
コマンドと似ていますが、
問い合わせを (0でない) アソシエーション識別子の範囲のそれぞれに
行ないます。
ここで言う範囲は、直前に実行された
.Ic associations
コマンドでキャッシュされたアソシエーションの一覧から決められます。
.It Ic opeers
古い形式の
.Ic peers
コマンドで、
参照 ID の代わりにローカルのインタフェースアドレスを使用します。
.It Ic passociations
内部でキャッシュされたアソシエーションの一覧から、
規格内 (in-spec) の通信相手に関する
アソシエーションのデータを出力します。
このコマンドは、新しい問い合わせをするのではなく
内部に蓄えられたデータを表示するということを除けば、
.Ic associations
と同じに働きます。
.It Ic peers
サーバの規格内の通信相手の一覧を、各通信相手の状態の概要と共に得ます。
概要の情報には、リモートの通信相手のアドレス、
参照 ID (不明のときは 0.0.0.0)、
リモートの通信相手の階層 (stratum)、
通信相手の種類
(ローカル、ユニキャスト、マルチキャスト、ブロードキャストのいずれか)、
最後のパケットを受信した時間、
秒単位のポーリング間隔、
8 進数表記の到達可能性レジスタ、
そして、その通信相手の
現在の遅れ、オフセット、ばらつきをミリ秒単位で表した推定値を含んでいます。
.Pp
左端の文字は、時計選択処理におけるこの通信相手の運命を示します。
以下はこれらの文字のリストと、
.Ic rv
.\" pidgeon ← pidgin ?  もともと誤用なので辞書に載ってない綴でもいいことに
.\" する
コマンドで使用される片言の英語、および
状態を示す短い説明文です。
.Bl -tag -width indent
.It 空白
.Pq reject
通信相手は到達できないか、このサーバに同期しているか (同期ループ)、あるいは
無茶な同期距離のために捨てられました。
.It x
.Pq falsetick
通信相手は交差アルゴリスムにより偽時計として捨てられました。
.It .
.Pq excess
通信相手は同期距離によって並べ換えられたなかで、
最初の 10 個に入らなかったため捨てられました。
このためこれ以上検討するには不十分な候補です。
.It -
.Pq outlyer
通信相手はクラスタリングアルゴリズムにより遠くにあるものとして捨てられました。
.It +
.Pq candidate
通信相手は生き残り、結合アルゴリズムへの候補となりました。
.It #
.Pq selected
通信相手は生き残りましたが、
同期距離によって並べ換えられたなかで最初の 6 個に入りませんでした。
アソシエーションが短命だった場合、
リソースを節約するために解散させられるかもしれません。
.\" assocation -> association (send-pr docs/17501)
.It *
.Pq sys.peer
通信相手はシステム通信相手として宣言されており、
その変数をシステム変数に与えています。
.It o
.Pq pps.peer
通信相手はシステム通信相手として宣言されており、
その変数をシステム変数に与えています。
しかし、システムの実際の同期は
1 秒ごとのパルス (PPS) 参照クロックドライバより間接的に、
あるいはカーネルインタフェースより直接、
PPS 信号で得ています。
.El
.Pp
flash 変数は NTP 仕様書では定義されていませんが、
デバッグを助ける貴重なものとして含められています。
この変数は NTP 仕様書で TEST1 から TEST9 まで定義されている
パケットの健全性チェックの結果を表示します。
各テストのビットは最も重要でないビットから順番に増え、
また以下のように定義されています。
.Pp
以下の TEST1 から TEST4 は手続きエラーを列挙します。
パケットのタイムスタンプは信用されたりされなかったりしますが、
残っているヘッダデータは無視されます。
.Bl -tag -width indent
.It TEST1
パケットが重複しています。
どこかからのコピーです。
.It TEST2
間違ったパケットです。
以前に送ったメッセージに対する返答ではありません。
NTP デーモンが再起動されていて、通信相手が気付く前だったときに
起こります。
.It TEST3
同期していません。
1 つ以上のタイムスタンプ・フィールドがありません。
通常、通信相手からの最初のパケットが受けとられた時に起こります。
.It TEST4
通信相手の遅延または通信相手のばらつきのどちらかが 1 秒よりも長いです。
冗談はやめてください。
.El
.Pp
以下の TEST5 から TEST10 はパケットヘッダのエラーを列挙します。
パケットは中身を調べることなく捨てられます。
.Bl -tag -width indent
.It TEST5
暗号認証に失敗しました。
.Xr ntp.conf 5
マニュアルページの
.Qq 認証機能のサポート
節を参照してください。
.It TEST6
通信相手は同期していません。
先に通信相手の時計のネジを巻いてください。
.It TEST7
通信相手の階層が 15 よりも大きいです。
通信相手はおそらく同期していません。
.It TEST8
root の遅延または root のばらつきが 1 秒よりも長いです。
家から遠すぎます。
.It TEST9
通信相手の暗号認証に失敗しました。
鍵の識別子または鍵が間違っているか、誰かがパケットを壊しています。
.It TEST10
アクセスが拒否されました。
.Xr ntp.conf 5
マニュアルページの
.Qq アクセス制御機能のサポート
節を参照してください
.El
.It Ic pstatus Ar assocID
与えられたアソシエーションに対応するサーバに対し、
状態読み取りリクエストを送ります。
返された peer 変数の名前と値を出力します。
変数の前に、ヘッダから得た状態ワードが 16 進数と片言の英語で
表示されることに注意してください。
.It Ic readlist Op Ar assocID
.It Ic rl Op Ar assocID
内部変数リストの中の変数の値を返すようにサーバに要求します。
アソシエーション識別子が省略されるか 0 の場合、
変数はシステム変数であるとみなされます。
そうでなければ、 peer 変数として扱われます。
.\"
.\" 以下の文はおそらく不要(原文の誤り)
.\"
内部変数リストが空の場合は、
リクエストはデータ無しで送られ、
リモートサーバはデフォルトの表示を返します。
.\"
.\" XXX Both variable_name and value below should be arguments,
.\"	not angle-quoted text.
.\"
.It Xo Ic readvar
.Op Ar assocID Ns
.Pf [ Aq variable_name Ns
.Op = Ns Aq value Ns
.Op ,...]
.Xc
.It Xo Ic rv
.Op Ar assocID Ns
.Pf [ Aq variable_name Ns
.Op = Ns Aq value Ns
.Op ,...]
.Xc
変数読み取りリクエストを送ることで、
指定した変数の値を返すようにサーバに要求します。
アソシエーション識別子を省略するか 0 を指定した場合、
変数はシステム変数です。
そうでなければ peer 変数であり、
返される値は対応する通信相手のものとなります。
変数のリストを省略すると、データ無しのリクエストを送り、
サーバはデフォルトの表示を返します。
.It Xo Ic writevar
.Ar assocID
.Aq variable_name Ns
.Pf = Ns Aq value Ns
.Op ,...
.Xc
.Ic readvar
リクエストと似ていますが、
指定した変数を読み取る代わりに書き込みます。
.It Ic writelist Op Ar assocID
.Em readlist
リクエストと似ていますが、
内部のリストの変数を読み取る代わりに書き込みます。
.El
.Sh 関連項目
.Xr ntp.conf 5 ,
.Xr ntpd 8 ,
.Xr ntpdc 8
.Sh 歴史
Toronto 大学の
.An Dennis Ferguson
によって書かれました。
.Sh バグ
.Ic peers
コマンドは不可分 (atomic) ではないため、
不正なアソシエーションという誤ったエラーメッセージが発生し
コマンドが終了することがあります。
時間切れまでの時間は固定された定数です。
これは、ある種の最悪の場合を考えてあるため、
時間切れになるまで長時間待たされることになります。
このプログラムは、
特定のホストへ何回も問い合わせを送る間に
制限時間の見積もりを改善すべきですが、
実際には行なっていません。