名称

ntpq — NTP の標準問い合わせプログラム

書式

ntpq	[ -inp][ -c command][ host][ ...]

解説

ntpq ユーティリティは、NTP デーモン ntpd(8) の動作をモニタして、性能を測定するために使用されます。それは、NTPv3 仕様 RFC1305 の Appendix B で定義された標準の NTP モード 6 制御メッセージ形式を使用します。同じ形式は NTPv4 で使用されますが、いくつかの変数は変更され新しいものが追加されます。このページでの説明は NTPv4 変数のためのものです。

対話型モードまたはコマンドライン引数を使用して制御するどちらでも、このプログラムを実行することができます。利用可能な生のまま、または綺麗な印刷出力オプションを使用して、任意の変数を読み書きする要求を組み立てることができます。また、 ntpq は、複数の問い合わせをサーバに送ることによって、通信相手 (peer) のリストを取得して、共通の形式で印刷 (表示) することができます。

ntpq が実行されたとき、1 つ以上の要求オプションが、コマンドラインに含まれる場合は、それぞれの要求は、コマンドライン引数で与えられた各ホスト、またはデフォルトである localhost で動いている NTP サーバに送られます。要求オプションが与えられなかった場合、 ntpq は、コマンドを標準入力から読み込み、コマンドラインで指定された最初のホストで動いている NTP サーバに対して実行しようとします。このときも、ホストが指定されていないときは、デフォルトで localhost になります。 ntpq ユーティリティは標準入力が端末である場合は、プロンプトを出してコマンドを受け付けます。

ntpq ユーティリティは NTP サーバとの通信に、NTP モード 6 パケットを使うため、ネットワーク上でそれを許すような互換サーバへの問い合わせに使用できます。 NTP は UDP のプロトコルなので、特にネットワークトポロジ的に遠くにある場合は、この通信はやや信頼性に欠けるということに注意してください。 ntpq ユーティリティは、要求を再送する試みを一度行ない、適当な制限時間の範囲内でリモートホストから返事がなかったときは、その要求は時間切れとなります。

例と使用法については、“NTP デバッグ技術”のページを参照してください ( /usr/share/doc/ntp に提供される HTML 文書の一部が利用可能です)。

以下のオプションが使用可能です:

ホスト名が予想されるコンテキストで、ホスト名に先行する -4 修飾子は IPv4 名前空間に DNS 解決を強制し、 -6 修飾子は IPv6 名前空間に DNS 解決を強制することに注意してください。 -i または -n 以外のコマンド行オプションを指定することにより、指定されたホストに指定された問い合わせ (群) が直ちに送信されます。それ以外の場合、 ntpq は標準入力から対話的フォーマットコマンドを読み込もうとします。

内部コマンド

対話的なフォーマットのコマンドは、キーワードとそれに続く 0 から 4 個の引数から構成されます。キーワード全長のうち、他と区別できる文字数がタイプされれば、有効になります。コマンドの出力は通常標準出力に送られますが、コマンドライン上で‘ >’に続けてファイル名を指定することで、個々のコマンドの出力をファイルに送ることができます。いくつかの対話的フォーマットのコマンドは、 ntpq ユーティリティ自身の中で全体が実行され、サーバへの NTP モード 6 要求は送られません。この種類のコマンドには以下のものがあります。

? [ command_keyword]
help [ command_keyword]: 単独の‘ ?’は、 ntpq が知っているすべてのコマンドキーワードのリストを出力します。‘ ?’の後にコマンドキーワードが続くときは、コマンドの機能と用法を出力します。このコマンドは、 ntpq に関して、多分このマニュアルよりも良い情報源となるでしょう。
addvars variable_name[ = value ...]
rmvars variable_name ...
clearvars: NTP モード 6 メッセージが運ぶデータは、次の形の項目のリストから成ります。‘ variable_name=value’ここで、サーバの変数を読み込み要求では、この‘ =value’は無視されるので、省略することができます。 ntpq ユーティリティは、制御メッセージに含まれるデータを組み立てるための内部リストを保持しており、以下に述べる readlist や writelist コマンドを使って送ります。 addvars コマンドで、このリストに、変数と省略可能な値を追加することができます。 1 つより多くの変数を追加するときには、リストはコンマで区切り、空白を含んではいけません。 rmvars コマンドは、個々の変数をリストから削除するために用い、 clearlist コマンドは、リストからすべての変数を削除します。
cooked: 問い合わせコマンドからの出力を、「加工済み (cooked)」形式にします。その結果、 ntpq が認識した変数については、人間に使える形に再整形されます。 ntpq が、その変数は本来デコードできる値を持っていると判断したのに、デコードされていないものには、その後に‘ ?’が付けられます。
debug more | less | off: 内部の問い合わせプログラムのデバッグをオンまたはオフにします。
delay milliseconds: 認証を求める要求に含まれるタイムスタンプに加えられる時間間隔を指定します。これは、長い遅延のあるネットワーク経路や時計の同期していないマシン間で (信頼できない) サーバの再設定ができるようにするために使われます。実際にはもうサーバは認証要求においてタイムスタンプを要求しませんので、このコマンドは今後廃止されるかもしれません。
host hostname: 今後問い合わせを送るホストを指定します。 hostname は、ホスト名でも数値アドレスでもかまいません。
hostnames yes | no: yes が指定されると、情報の表示の際、ホスト名が使用されます。 no が与えられると、代わりに数値アドレスが使用されます。コマンド行の -n スイッチによって変えられていなければ、デフォルトは yes になります。
keyid keyid: このコマンドは、設定要求を認証するために使用されるキー番号を指定します。これは、サーバがこのために使用する設定されたキー番号に対応しなければなりません。
ntpversion 1 | 2 | 3 | 4: ntpq がパケットの中で自称する NTP のバージョン番号をセットします。デフォルトでは 3 になります。モード 6 制御メッセージ (詳しく言うとモードも) は、 NTP バージョン 1 には存在しなかったことに注意してください。バージョン 1 を必要とするサーバは残っていないようですが。
passwd: このコマンドは、設定要求を認証するために使用されるパスワード (エコーされない) のためのプロンプトを表示します。パスワードは、このために NTP サーバのために設定されたキーに対応しなければなりません。
quit: ntpq を終了します。
raw: 問い合わせコマンドに対するすべての出力を、リモートサーバから受け取った通りに出力します。データに対して行なわれる唯一の整形と解釈は、印字可能 (しかしめったに理解できない) 形式になるように、ASCII 文字でないデータを変換することだけです。
timeout milliseconds: サーバへの問い合わせに対する応答の制限時間を指定します。デフォルトは、約 5000 ミリ秒です。 ntpq はそれぞれの問い合わせに対して時間切れを待ったあと再試行するため、合計の待ち時間は設定された制限時間の値の 2 倍になることに注意してください。

制御メッセージコマンド

NTP サーバに知られている各アソシエーションは、16 ビットの整数アソシエーション (関連付け, association) 識別子があります。通信相手の変数 (peer variables) を伝える NTP 制御メッセージは、アソシエーション ID を含んでいることによって対応する通信相手の値を識別しなければなりません。 0 のアソシエーション ID は、特別であり、変数は、名前が個別の名前空間から得られるシステム変数であることを示します。

制御メッセージコマンドは、サーバに 1 つ以上の NTP モード 6 メッセージを送り、戻ってきたデータを何らかの書式で出力します。現在実装されているほとんどのコマンドは、 1 つのメッセージを送って、1 つの応答を受け取ります。今のところ例外は、必要なデータを得るためにあらかじめプログラムされた一連のメッセージを送る peers コマンドと、ある範囲のアソシエーションそれぞれに対し処理を繰り返す mreadlist と mreadvar コマンドです。

associations: 問い合わせ対象のサーバの規格内 (in-spec) の通信相手についての、アソシエーション識別子と通信相手の状態の一覧を得て出力します。一覧は複数の欄から成っています。最初の欄は、内部使用のために 1 から振ったアソシエーションのインデックス、 2 番目はサーバから返って来た実際のアソシエーション識別子、 3 番目は通信相手の状態ワードです。その後に、状態ワードをデコードしたデータを含む欄がいくつか続きます。‘condition’フィールドのデコードについては、 peers コマンドを参照してください。 associations コマンドによって返されたデータは ntpq の内部でキャッシュされるということに注意してください。形式とインデックスが代替手段として使用される引数としてアソシエーション識別子を必要とするその後のコマンドのために、人間がタイプしにくいアソシエーション識別子を使用する愚かなサーバに対処するとき、インデックスは役に立ちます。
clockvar [ assocID][ variable_name[ = value ...]] ...
cv [ assocID][ variable_name[ = value ...]] ...: サーバの時計変数 (clock variable) の一覧を送るように要求します。ラジオ時計や他の外部同期機構を持っているサーバは、このコマンドに肯定的に応答します。アソシエーション識別子が省略されるか 0 だと、要求は‘システム時計’の変数に対するものとなり、一般に、時計を持つすべてのサーバから肯定的な応答が得られるでしょう。サーバが時計を擬似的な通信相手として扱い、結果として一度に 2 つ以上の時計を接続することができるようになっていれば、適切な通信相手のアソシエーション識別子を参照すれば特定の時計の変数が表示されます。変数のリストを省略すると、サーバはデフォルトの変数の表示を返すことになります。
lassociations: サーバが状態を保持しているすべてのアソシエーションについて、アソシエーション識別子と通信相手の状態の一覧を得て、出力します。このコマンドと associations コマンドは、規格外 (out-of-spec) のクライアントのアソシエーションの状態を保持するサーバ (つまり fuzzball) の場合にだけ異なります。 associations コマンドが使われたとき、通常そういうアソシエーションは表示から省略されますが、 lassociations の出力には含まれます。
lpassociations: 規格外 (out-of-spec) のクライアントとのアソシエーションを含む全てのアソシエーションに関するデータを、内部にキャッシュされたアソシエーションの一覧から出力します。このコマンドは、fuzzball を扱う場合だけ、 passociations と異なります。
lpeers: peers と似ていますが、サーバが状態を保持しているすべてのアソシエーションの概要を出力します。これは fuzzball サーバの、より長い通信相手のリストを生成することがあります。
mreadlist assocID assocID
mrl assocID assocID: readlist コマンドと似ていますが、問い合わせを (0 でない) アソシエーション識別子の範囲のそれぞれに行ないます。ここで言う範囲は、直前に実行された associations コマンドでキャッシュされたアソシエーションの一覧から決められます。
mreadvar assocID assocID [ variable_name[ = value ...]]
mrv assocID assocID [ variable_name[ = value ...]]: readvar コマンドと似ていますが、問い合わせを (0 でない) アソシエーション識別子の範囲のそれぞれに行ないます。ここで言う範囲は、直前に実行された associations コマンドでキャッシュされたアソシエーションの一覧から決められます。
opeers: 古い形式の peers コマンドで、参照 ID の代わりにローカルのインタフェースアドレスを使用します。
passociations: 内部でキャッシュされたアソシエーションの一覧から、規格内 (in-spec) の通信相手に関するアソシエーションのデータを出力します。このコマンドは、新しい問い合わせをするのではなく内部に蓄えられたデータを表示するということを除けば、 associations と同じに働きます。
peers: サーバの現在の通信相手の一覧を、各通信相手の状態の概要と共に得ます。概要情報には、リモートの通信相手のアドレス、参照 ID (不明なら 0.0.0.0)、リモート通信相手の階層 (stratum)、通信相手のタイプ (ローカル、ユニキャスト、マルチキャストまたはブロードキャスト)、最後のパケットを受信したとき、秒単位のポーリング間隔、 8 進表記の可到達性レジスタ、およびミリ秒単位の現在の推定される遅れ、通信相手のオフセットと分散を含んでいます。各行の左マージンにある文字は、アソシエーションの同期状態を示す、役に立つ診断ツールです。タリー (符号, tally) コードと呼ばれるこの文字のエンコードと意味は、このページの後で説明されます。
pstatus assocID: 与えられたアソシエーションのために読み込み状態要求をサーバに送信します。返された通信相手の名前と値が印刷 (表示) されます。ヘッダの状態ワードは、両方とも 16 進数とピジン英語 (文法も発音もくずれた英語) で先行された変数が表示されることに注意してください。
readlist assocID
rl assocID: 内部変数リスト中の変数の値がサーバによって返えされることを要求します。アソシエーション ID が省略されるか 0 であるなら、変数はシステム変数であると仮定されます。そうでなければ、それらは通信相手の変数として扱われます。内部の変数リストが空であるなら、要求は、データ無しで送信され、リモートサーバは、デフォルトの表示を返すべきです。
readvar assocID variable_name[ = value] ...
rv assocID variable_name[ = value] ...: 変数読み込み要求を送信することによって、指定された変数の値がサーバによって返されることを要求します。アソシエーション ID が省略されるか、または 0 として与えるなら、変数はシステム変数で、そうでなければ、それらは通信相手の変数で、返される値は対応する通信相手のものになります。変数リストを省略すると、データ無しの要求が送信され、サーバは、デフォルトの表示を返すべきです。 NTPv3 に由来する変数のエンコードと意味は、RFC-1305 で説明されます。追加の NTPv4 変数のエンコードと意味は、このページの後で説明されます。
writevar assocID variable_name[ = value] ...: 指定された変数が読み込みの代わりに書き込まれることを除いて、 readvar 要求に似ています。
writelist [ assocID]: 内部のリストの変数が読み込みの代わりに書き込まれることを除いて、 readlist 要求に似ています。

タリー (tally) コード

タリーコードと呼ばれる、‘peers’掲示板 (billboard) の左マージンの文字は、クロック選択プロセスの各アソシエーションの運命を示します。次は、これらの文字のリスト、 rv コマンドで使用されるピジン英語 (文法も発音もくずれた英語)、明らかにされた状態の短い説明です。

システム変数

status, leap, stratum, precision, rootdelay, rootdispersion, refid, reftime, poll, offset と frequency 変数は、RFC-1305 仕様に記述されています。追加の NTPv4 システム変数には次を含んでいます。

NTPv4 デーモンが OpenSSL ソフトウェアライブラリでコンパイルされるとき、追加システム変数は、特定のダンス (dance) に応じて、次のいくらか、またはすべてを含んで表示されます: 訳注: dance は何かのスペルミスと思われる。

通信相手変数

status, srcadr, srcport, dstadr, dstport, leap, stratum, precision, rootdelay, rootdispersion, readh, hmode, pmode, hpoll, ppoll, offset, delay, dspersion, reftime 変数は、タイムスタンプ org, rec と xmt のように、RFC-1305 仕様に記述されています。追加の NTPv4 システム変数には次を含んでいます。

NTPv4 デーモンが OpenSSL ソフトウェアライブラリでコンパイルされるとき、次を含んで、追加の通信相手変数が表示されます:

フラッシュ (flash) コード

flash コードは、接続相手の変数リストに表示される重要なデバッグの助けとなるものです。 NTP 仕様 RFC-1305 と NTPv4 で追加された追加仕様で定義されたオリジナルの判断が正しいかどうかチェック (sanity check) した結果を表示します。 TEST1 から TEST12 で指定された 12 個のテストがあります。テストは、偶然、または、悪意のあるエラーから保護しながら、最大の診断情報が得られるように設計された特定の順序で実行されます。各パケットが受信されるとき、 flash 変数は 0 に初期化されます。各テストの組の後に 1 つ以上のビットが設定されるなら、パケットは破棄されれます。

テスト TEST1 から TEST3 は、オフセットと遅延を計算するパケットのタイムスタンプをチェックします。いずれかのビットが設定されているなら、そのパケットは破棄されます。そうでなければ、パケットヘッダ変数は保存されます。 TEST4 と TEST5 は、アクセス制御と暗号化認証に関連付けられます。いずれかのビットが設定されているなら、そのパケットは、何も変更せずに直ちに破棄されれます。

テスト TEST6 から TEST8 は、サーバの健全性をチェックします。いずれかのビットが設定されているなら、そのパケットは破棄されます。そうでなければ、サーバに関連するオフセットと遅延が計算され、保存されます。 TEST9 は、アソシエーション自体の健全性をチェックします。いずれかのビットが設定されているなら、そのパケットは破棄されます。そうでなければ、保存された変数は、クロックフィルタと緩和アルゴリズムに渡されます。

テスト TEST10 から TEST12 は、 ntp.conf(5) の 「認証コマンド」 セクションで説明されるように、Autokey 公開キー暗号を使用して認証状態をチェックします。いずれかのビットが設定されて、アソシエーションが以前に到達可能とマークされていたなら、そのパケットは破棄されます。そうでなければ、送信元であり受信されたタイムスタンプは、 NTP プロトコルによって要求されるように保存され、処理は続行します。

各テストのための flash ビットは次のように定義されています。

0x001: (TEST1) 重複パケット。パケットは、よくても偶然の再転送であり、最悪の場合、悪意がある応答です。
0x002: (TEST2) 偽のパケット。パケットは、以前に送信したメッセージに対する応答ではありません。 NTP デーモンが再開され、他の誰かが気付く前に、これは起こるかもしれません。
0x004: (TEST3) 同期されていません。 1 つ以上のタイムスタンプフィールドが無効です。通常、通信相手からの最初のパケットが受信されたとき、起こります。
0x008: (TEST4) アクセスは拒否されます。 ntp.conf(5) の 「アクセス制御サポート」 セクションを参照してください。
0x010: (TEST5) 暗号の認証は失敗します。 ntp.conf(5) の 「認証コマンド」 セクションを参照してください。
0x020: (TEST6) サーバは同期していません。最初に、そのクロックのねじを巻いてください。
0x040: (TEST7) サーバの階層は、最大で 15 より大です。たぶん同期しておらず、クロックのねじを巻く必要があります。
0x080: (TEST8) root の遅延または分散のいずれかは、通信相手が火星と同期していないなら、全くありそうにない、1 秒以上です。
0x100: (TEST9) 通信相手の遅延または分散のいずれかは、通信相手が火星でないなら、全くありそうにない、1 秒以上です。
0x200: (TEST10) autokey プロトコルは認証失敗を検出しました。 ntp.conf(5) の 「認証コマンド」 セクションを参照してください。
0x400: (TEST11) autokey プロトコルは、サーバを検証していないか、または、通信相手が証明されていて、有効な公開キー資格証明書があります。 ntp.conf(5) の 「認証コマンド」 セクションを参照してください。
0x800: (TEST12) プロトコルまたは設定エラーが公開キーアルゴリズムで起こったか、またはあり得る侵入イベントが検出されました。 ntp.conf(5) の 「認証コマンド」 セクションを参照してください。

バグ

peers コマンドは不可分 (atomic) ではないため、不正なアソシエーションという誤ったエラーメッセージが発生しコマンドが終了することがあります。時間切れまでの時間は固定された定数です。これは、ある種の最悪の場合を考えてあるため、時間切れになるまで長時間待たされることになります。このプログラムは、特定のホストへ何回も問い合わせを送る間に制限時間の見積もりを改善すべきですが、実際には行なっていません。

May 17, 2006

FreeBSD

YOS OPENSONAR

名称

書式

解説