doc/ja/man/man8/ntpq.8

.\"
.\"	%Id: ntpq.8,v 1.5.2.1 1999/05/02 12:14:35 kris Exp %
.\"
.\" jpman %Id: ntpq.8,v 1.3 1997/09/21 12:35:15 seki Stab %
.\"
.\" 対訳覚え書き (seki@sysrap.cs.fujitsu.co.jp 作成)
.\" association		アソシエーション
.\" association identifier	アソシエーション番号 (訳しすぎか?)
.\" authentication	認証
.\" clock		時計
.\" dispersion		ばらつき
.\" fuzzball		fuzzball (固有名詞; xntpd ベースでない NTP サーバ)
.\" offset		ずれ
.\" peer		peer のまま
.\" poll		ポーリングする
.\" query		問い合わせ
.\" reference clock	参照時計
.\" request		要求
.\" status word		状態ワード
.\" time out (名詞)	制限時間
.Dd December 21, 1993
.Dt NTPQ 8
.Os
.Sh 名称
.Nm ntpq
.Nd ネットワークタイムプロトコルの標準問い合わせプログラム
.Sh 書式
.Nm
.Op Fl inp
.Op Fl c Ar command
.Op Ar host ...
.Sh 解説
.Nm ntpq
は、
推奨されている NTP モード 6 制御メッセージフォーマットを実装する NTP サーバに、
現在の状態について問い合わせを行なったり、
状態の変更を要求するために使われます。
このプログラムは対話的モードでも、
コマンドラインの引数を使っても走らせることができます。
任意の変数を読み書きする要求を組み立てることができ、
生のまま、または綺麗に整形して出力するオプションがあります。
.Nm ntpq
は、サーバに複数の問い合わせを送ることで、共通フォーマットにした
peer のリストを得て、出力することができます。
.Pp
.Nm ntpq
を実行するときに一つ以上の要求オプションがコマンドラインに含まれていれば、
それぞれの要求は、
コマンドラインで指定された各ホストで走っている NTP サーバ、
またはデフォルトでは
.Ar localhost
で走っている NTP サーバに送られます。
要求オプションが与えられなかった場合、
.Nm ntpq
は、コマンドを標準入力から読み込み、
コマンドラインで指定された最初のホストで走っている
NTP サーバに対して実行しようとします。
このときも、
ホストが指定されていないときは、デフォルトで
.Ar localhost
になります。
標準入力が端末装置である場合は、
.Nm ntpq
はコマンドを求めるプロンプトを出します。
.Pp
NTP サーバと通信するために、
.Nm ntpq
は NTP モード 6 パケットを使います。
それゆえ、許可されていれば、
互換のあるどんなネットワーク上のサーバにでも問い合わせることができます。
NTP は UDP のプロトコルなので、特にネットワークトポロジ的に
遠くにある場合は、この伝達はやや信頼性に欠けるということを覚えておいて
下さい。
.Nm ntpq
は、要求を再送する試みを一度行ない、
適当な制限時間の範囲内でリモートホストから返事がなかったときは、
その要求は時間切れとなります。
.Pp
コマンドラインオプションは以下の通りです。
.Fl i
または
.Fl n
以外のコマンドラインオプションを指定すると、指定したホスト (群) に、
指定した問い合わせ (または複数の問い合わせ) を直ちに送ることになります。
そうでなければ
.Nm ntpq
は、標準入力から対話形式のコマンドを読み込もうとします。
以下のオプションが利用可能です。
.Bl -tag -width indent
.It Fl c Ar command
後に続く引数は、対話形式の
.Ar コマンド
として解釈され、
指定されたホスト (群) に対して実行すべきコマンドのリストに
付け加えられます。
複数の
.Fl c
オプションも与えることができます。
.It Fl i
.Nm ntpq
の操作を強制的に対話モードにします。標準出力にプロンプトが書き出され、
標準入力からコマンドが読み込まれます。
.It Fl n
すべてのホストアドレスを数字四つを点で区切った形式で出力し、
正規のホスト名に変換しません。
.It Fl p
そのサーバに知られている peer の一覧を、その状態の概要と共に出力します。
これは、対話コマンド
.Em peers
と同等です。
.El
.Sh 内部コマンド
.Pp
対話形式コマンドは、キーワードとそれに続く 0 個から 4 個の
引数からなります。
キーワードの単語のうち、他に同じものがないとわかる数の文字がタイプされ
ていれば大丈夫です。コマンドの出力は、通常標準出力に出力されますが、
コマンドラインの後に
.Qq >
とファイル名をつけると、
個々のコマンドの出力をファイルに出力することもできます。
.Pp
多くの対話形式コマンドは、
.Nm ntpq
プログラム自身の中で実行されてしまい、
サーバへ送られる NTP モード 6 リクエストとはなりません。
この種のコマンドを以下に挙げます。
.Pp
.Bl -tag -width indent
.It ? Op Ar command_keyword
単独の
.Qq ?
は、現在の
.Nm ntpq
のすべてのコマンドキーワードの一覧を出力します。
.Qq ?
の後にコマンドキーワードが続くときは、関数とコマンドの使いかた
を出力します。このコマンドは、
.Nm ntpq
について、多分このマニュアルよりも良い情報源になります。
.Pp
.It timeout Ar millseconds
サーバへの問い合わせに対する応答の、制限時間の長さを指定します。
デフォルトは約 5000 ミリ秒です。
.Nm ntpq
は制限時間が過ぎるとそれぞれの問い合わせを一回リトライするので、
合計の待ち時間は設定された制限時間の値の 2 倍になることを覚えておいて下さい。
.It delay Ar milliseconds
認証を必要とする要求に含めるタイムスタンプに追加すべき時間間隔を指定します。
これは、長い遅延のあるネットワーク経路や時計が同期していない
マシン間での (信頼性の低い) サーバの再設定を可能にするために
使われます。
実際には、サーバは、今では認証される要求のタイムスタンプを必要としません。
そのため、このコマンドは、すたれているかもしれません。
.It host Ar hostname
問い合わせを送るホストをセットします。
.Ar hostname
はホスト名でも数値アドレスでもかまいません。
.It Xo poll
.Op Ar #
.Op Ar verbose
.Xc
クライアントモードで現在のサーバをポーリングします。最初の引数はポーリングする
回数 (デフォルトは 1) であり、 2 番目の引数は結果の出力をより詳しく
得るために与えることができます。
このコマンドは、今のところ希望的観測でしかありません。
.It keyid Ar #
このコマンドは、設定要求を認証するために用いるキー番号を指定します。
これは、この目的で使うためにサーバに設定されているキー番号に
対応していなければなりません。
.It passwd
このコマンドは、設定要求を認証するために使われるパスワード
(画面に表示されません) の入力を求めるプロンプトを出します。
その要求を成功させるためには、
このパスワードが、
NTP サーバがこの目的で使うように設定されたキーに
対応していなければなりません。
.It hostnames Ar yes | no
.Ar yes
が指定されると、情報を表示するときにホスト名が出力されます。
.Ar no
が与えられると、代わりに数値アドレスが表示されます。
コマンドラインの
.Fl n
スイッチが使われなければ、デフォルトは
.Ar yes
になります。
.It raw
問い合わせコマンドに対するすべての出力を、リモートサーバから受け取った
通りに出力します。
データに対して行なわれる唯一の整形/解釈は、印字できる
(しかしめったに理解できない) 形になるように、アスキー文字でないデータを
変換することです。
.It cooked
問い合わせコマンドからの出力を、 
.Qq 加工済み (cooked)
形にします。
サーバに認識された変数は、人間に使える形に再整形された値に
なります。
.Nm ntpq
が、その変数は本来デコードできる値を持っていると判断したのに、
デコードされていないものには、その後に
.Qq ?
が付けられます。
.It ntpversion Ar 1 | Ar 2 | Ar 3
.Nm ntpq
がパケットの中で自称する NTP のバージョン番号をセットします。
デフォルトでは 3 です。
モード 6 制御メッセージ (詳しく言うとモードも) は、 
NTP バージョン 1 には存在しなかったことに注意して下さい。
バージョン 1 を必要とするサーバは残っていないようですが。
.It authenticate Ar yes | Ar no
通常、
.Nm ntpq
は、
書き込み要求でない限り要求を認証しません。
コマンド 
.Em authenticate yes
は、
.Nm ntpq
が生成するすべての要求に認証をつけて送るようにします。
認証された要求は、サーバによっては少し異なって扱われます。
もしも peer 表示を行う前に認証をオンにすると、
時々 fuzzball の CPU を溶かしてしまうかもしれません。
.It Xo addvars
.Aq variable_name Ns
.Op = Ns Aq value> Ns
.Op ,...
.Xc
.It Xo rmvars
.Aq variable_name Ns
.Op ,...
.Xc
.It clearvars
NTP モード 6 メッセージが運ぶデータは、次の形の
項目のリストから成ります。
.Xo Aq variable_name Ns
.Pf = Aq value
.Xc
ここで、サーバの変数を読み取る要求では、この
.Qq = Ns Aq value
は無視されるので、省略することができます。
.Nm ntpq
は、制御メッセージに含まれるデータを組み立てるための内部リストを保持しており、
以下に述べる
.Em readlist
や
.Em writelist
コマンドを使って送ります。
.Em addvars
コマンドで、このリストに、変数と省略可能な値を追加することができます。
一つ以上の変数を追加するときには、リストはコンマで区切り、
空白を含んではいけません。
.Em rmvars
コマンドは、個々の変数をリストから削除するために用い、
.Em clearlist
コマンドは、リストからすべての変数を削除します。
.It debug Ar more | Ar less | Ar off
問い合わせプログラムの内部のデバッグをオンまたはオフにします。
.It quit
.Nm ntpq
を終了します。
.El
.Sh 制御メッセージコマンド
ある NTP サーバが知っている各 peer には、
.Em アソシエーション番号
.Em (association identifier)
という 16 ビット整数が割り当てられています。
peer 変数を使う NTP 制御メッセージは、
アソシエーション番号を含めることによって、
その値が対応する peer を識別しなければなりません。
0 というアソシエーション番号は特別で、
その変数がシステム変数であることを表します。
システム変数の名前は、独立した名前空間から取りだされます。
.Pp
制御メッセージコマンドは、
サーバに一つ以上の NTP モード 6 メッセージを送り、
戻ってきたデータを何らかの書式で出力します。
現在実装されているほとんどのコマンドは、
一つのメッセージを送って、一つの応答を受け取ります。
今のところ例外は、必要なデータを得るためにあらかじめプログラムされた一連の
メッセージを送る
.Em peers
コマンドと、
アソシエーションをある範囲で変えながら繰り返す
.Em mreadlist
と
.Em mreadvar
コマンドです。
.Bl -tag -width indent
.It associations
問い合わせ対象のサーバの規格内 (in\-spec) の peer についての、
アソシエーション番号と peer の状態の一覧を得て出力します。
一覧は複数の欄から成っています。
最初の欄は、内部で使用のために 1 から振ったアソシエーションの索引番号 (index)、
2 番目はサーバから返って来た実際のアソシエーション番号、
3 番目は peer の状態ワードです。
その後に、状態ワードをデコードしたデータを含む欄がいくつか続きます。
\*(L"associations\*(R" コマンドによって返されたデータは
.Nm ntpq
の内部でキャッシュされるということを覚えておいて下さい。
このため、索引番号は、
人間にはほとんど打ち込むることができないアソシエーション番号を使う
愚かなサーバを相手にするときに役立ちます。
すなわち、
それ以降の任意のコマンドが引数としてアソシエーション番号を必要とするときに、
代わりに
.Em &index
という形を使うことができます。
.It lassocations
.Pp
サーバが状態を保持しているすべてのアソシエーションについて
アソシエーション番号と peer の状態の一覧を得て、出力します。
このコマンドと
.Em associations
コマンドは、
規格外 (out\-of\-spec) のクライアントのアソシエーション
の状態を保持するサーバ (つまり fuzzball) の場合にだけ異なります。
.Em associations
コマンドが使われたとき、通常そういう関係は
表示から省略されますが、
.Em lassociations
の出力には含まれます。
.It passociations
内部でキャッシュされたアソシエーションの一覧から、
規格内 (in\-spec) の peer に関する 
アソシエーションのデータを出力します。
このコマンドは、新しい問い合わせをするのではなく
内部に蓄えられたデータを表示するということを除けば、
.Em associations
と同じに働きます。
.It lpassociations
規格外 (out\-of\-spec) のクライアントとのアソシエーションを含む
全てのアソシエーションに関するデータを、
内部にキャッシュされたアソシエーションの一覧から出力します。
このコマンドは、fuzzball を扱う場合だけ、
.Em passociations
と異なります。
.It pstatus Ar assocID
与えられたアソシエーションに対応するサーバに対し、
状態読み取り要求を送ります。
返された peer 変数の名前と値を出力します。
変数の前に、ヘッダから得た状態ワードが 16 進数と下手な英語で
表示されることに注意して下さい。
.It Xo readvar
.Op Ar assocID Ns
.Pf [ Aq variable_name Ns
.Op = Ns Aq value Ns
.Op ,...]
.Xc
変数読み取り要求を送ることで、指定した変数の値を返すようにサーバに要求します。
アソシエーション番号 (assocID) を省略するか 0 を指定したならば、
変数はシステム変数です。
そうでなければ peer 変数であり、
返される値は対応する peer のものとなります。
変数のリストを省略すると、データ無しの要求を送ります。
これは、サーバにデフォルトのディスプレイを返させます。
.It Xo rv
.Op Ar assocID Ns
.Pf [ Aq variable_name Ns
.Op = Ns Aq value Ns
.Op ,...]
.Xc
.Em readvar
コマンドの打ちやすい短縮形です。
.It Xo writevar
.Ar assocID
.Aq variable_name Ns
.Pf = Ns Aq value Ns
.Op ,...
.Xc
.Em readvar
リクエストと似ていますが、
指定した変数を読み取る代わりに書き込みます。
.It readlist Op Ar assocID
内部の変数リストの中の変数の値を返すようにサーバに要求します。
アソシエーション番号が省略されるか 0 の場合、
変数はシステム変数であるとみなされます。
そうでなければ、 peer 変数として扱われます。
内部の変数リストが空の場合は、
要求はデータ無しで送られます。
これは、リモートサーバにデフォルトのディスプレイを返させます。
.It rl Op Ar assocID
.Em readlist
コマンドの打ちやすい短縮形です。
.It writelist Op Ar assocID
.Em readlist
リクエストと似ていますが、
内部のリストの変数を読み取る代わりに書き込みます。
.It Xo mreadvar
.Ar assocID assocID [
.Aq variable_name Ns
.Op = Ns Aq value Ns
.Op ,...]
.Xc
.Em readvar
コマンドと似ていますが、
問い合わせを (0でない) アソシエーション番号の範囲のそれぞれに
行ないます。
ここで言う範囲は、直前に実行された
.Em associations
コマンドでキャッシュされたアソシエーションの一覧から決めます。
.It Xo mrv
.Ar assocID assocID [
.Aq variable_name Ns
.Op = Ns Aq value Ns
.Op ,...]
.Xc
.Em mreadvar
コマンドの打ちやすい短縮形です。
.It mreadlist Ar assocID assocID
.Em readlist
コマンドと似ていますが、
(0 でない) アソシエーション番号の範囲のそれぞれに問い合わせを行います。
ここで言う範囲は、直前に実行された
.Em associations
コマンドでキャッシュされたアソシエーションの一覧から決めます。
.It mrl Ar assocID assocID
.Em mreadlist
コマンドの打ちやすい短縮形です。
.It Xo clockvar
.Op Ar assocID Ns
.Pf [ Aq variable_name Ns
.Op = Ns Aq value Ns
.Op ,...]
.Xc
サーバの時計変数 (clock variable) の一覧を送るように要求します。
ラジオ時計や他の外部同期機構を持っているサーバは、
このコマンドに肯定的に応答します。
アソシエーション番号が省略されるか 0 だと、
要求は
.Qq システム時計
の変数に対するものとなり、
一般に、時計を持つすべてのサーバから肯定的な応答が得られるでしょう。
サーバが時計を擬似的な peer として扱い、
結果として一度に二つ以上の時計を接続することができるようになっていれば、
適切な peer のアソシエーション番号を参照すれば
特定の時計の変数が表示されます。
変数のリストを省略すると、サーバはデフォルトの変数のディスプレイを
返すことになります。
.It Xo cv
.Op Ar assocID Ns
.Pf [ Aq variable_name Ns
.Op = Ns Aq value Ns
.Op ,...]
.Xc
.Em clockvar
コマンドの打ちやすい短縮形です。
.It peers
サーバの規格内の peer の一覧を、各 peer の状態の概要と共に得ます。
概要の情報には、リモート peer のアドレス、
参照 ID (参照 IDが不明のときは 0.0.0.0)、
リモート peer の階層 (stratum)、
peer の種類
(ローカル、ユニキャスト、マルチキャスト、ブロードキャストのいずれか)、
最後のパケットを受信した時間、
秒単位のポーリング間隔、
8 進数表記の到達可能性レジスタ
そして、その peer に関する
(全て秒単位で)
現在の遅延の推定値、ずれ (offset)、ばらつき (dispersion) を含んでいます。
.Pp
左端の文字は、時計選択処理におけるこの peer の運命を示します。
コードの意味は以下です:
<sp> 階層が高いか、または妥当性のチェックにより捨てられたもの;
.Qq x
交差アルゴリスムにより指示された誤りのチェッカ (falsticker);
.Qq \&.
候補リストの最後から間引かれたもの;
.Qq -
クラスタリングアルゴリスムにより捨てられたもの;
.Qq +
最終の選択セットに含まれたもの;
.Qq #
同期用に選択されたが隔たりが最大値を越えるもの;
.Qq *
同期用に選択されたもの;
.Qq o
同期用に選択され pps シグナル使用中のもの。
.Em peers
コマンドは、得られた応答の中の値を解析できるかどうかに依るため、
データ形式の制御が貧弱なサーバでは、時々動作に失敗するかも
しれません。
.Pp
ホストフィールドの内容は、次の四つの型のうちの一つになります。
ホスト名、
IP アドレス、
参照時計 (reference clock) の実装名とパラメタ、
.Qq REFCLK(<実装番号>, <パラメータ>)
のいずれかです。
.Qq hostnames no
が設定されているときには、IP アドレスだけが表示されます。
.It lpeers
.Em peers
と似ていますが、
サーバが状態を保持しているすべてのアソシエーションの概要を出力します。
これは fuzzball サーバの、より長い peer のリストを生成することがあります。
.It opeers
古い型の
.Em peers
コマンドで、
参照 ID がローカルのインタフェースアドレスになります。
.El
.Sh 歴史
Toronto 大学の Dennis Ferguson によって書かれました。
.Sh バグ
.Em peers
コマンドは不可分 (atomic) ではないため、
不正なアソシエーションという誤ったエラーメッセージが発生し
コマンドが終了することがあります。
.Pp
時間切れまでの時間は固定された定数です。
これは、ある種の最悪の場合を考えてあるため、
時間切れになるまで長時間待たされることになります。
このプログラムは、
特定のホストへ何回も問い合わせを送る間に
制限時間の見積もりを改善すべきですが、
実際には行なっていません。