NTPQ(8)

名称
ntpq - NTP の標準問い合わせプログラム

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

解説
ntpq ユーティリティは、 推奨されている NTP モード 6 制御メッセージフォーマットを実装する NTP サーバに、 現在の状態について問い合わせを行なったり、 状態の変更を要求するために使います。 このプログラムは、対話的モードでもコマンドライン引数を 使った制御でも動作させることができます。 任意の変数を読み書きするリクエストを組み立てることができ、 生のまま、または綺麗に整形して出力するオプションがあります。 ntpq ユーティリティは、サーバに複数の問い合わせを送ることで 通信相手 (peer) のリストを得て、共通なフォーマットで出力することができます。

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

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

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

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

-c command
    後に続く引数は、対話的なフォーマットのコマンドとして解釈され、 指定されたホスト (群) に対して実行すべきコマンドのリストに 付け加えられます。 複数の -c オプションを与えることもできます。

-i  ntpq を強制的に対話的モードで動作させます。標準出力にプロンプトが 表示され、標準入力からコマンドが読み込まれます。

-n  すべてのホストアドレスを、ドットで 4 つの部分に区切られた数値の形式で出力し、 正規のホスト名に変換しません。

-p  サーバに既知な通信相手のリストと、それらの状態の概要を出力します。 これは、対話コマンド peers と同等です。

-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 コマンドは、リストからすべての変数を削除します。

authenticate yes | no
    通常、 ntpq は、 書き込みリクエストでない限りリクエストを認証しません。 コマンド ‘authenticate yes’ は、 ntpq が生成するすべてのリクエストに認証をつけて送るようにします。 認証されたリクエストの扱いはサーバによって少し異なります。 もしも 通信相手 の表示を行う前に認証をオンにすると、 fuzzball の CPU を溶かしてしまうことがあるかもしれません。

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 を必要とするサーバは残っていないようですが。

quit
    ntpq を終了します。

passwd
    このコマンドは、認証設定リクエストに使われるパスワードの入力 (画面に表示されません) を求めるプロンプトを出します。 このリクエストが成功するためには、NTP サーバが認証のために使うよう 設定した鍵に、パスワードが対応していなければなりません。

raw 問い合わせコマンドに対するすべての出力を、リモートサーバから受け取った 通りに出力します。 データに対して行なわれる唯一の整形と解釈は、印字可能 (しかしめったに理解できない) 形式になるように、ASCII 文字でないデータを 変換することだけです。

timeout milliseconds
    サーバへの問い合わせに対する応答の制限時間を指定します。デフォルト は、約 5000 ミリ秒です。 ntpq はそれぞれの問い合わせに対して時間切れを待ったあと再試行するため、 合計の待ち時間は設定された制限時間の値の 2 倍になることに注意してください。

  制御メッセージコマンド
ある NTP サーバが知っている各通信相手には、 アソシエーション識別子 (association identifier) という 16 ビット整数が割り当てられています。 通信相手変数 (peer variable) を使う NTP 制御メッセージは、 アソシエーション識別子を含めることによって、 その値が対応する通信相手を識別しなければなりません。 0 というアソシエーション識別子は特別で、 その変数がシステム変数であることを表します。 システム変数の名前は、独立した名前空間から取りだされます。

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

associations
    問い合わせ対象のサーバの規格内 (in-spec) の通信相手についての、 アソシエーション識別子と通信相手の状態の一覧を得て出力します。 一覧は複数の欄から成っています。 最初の欄は、内部使用のために 1 から振ったアソシエーションの索引番号 (index)、 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 進数表記の到達可能性レジスタ、 そして、その通信相手の 現在の遅れ、オフセット、ばらつきをミリ秒単位で表した推定値を含んでいます。 左端の文字は、時計選択処理におけるこの通信相手の運命を示します。 以下はこれらの文字のリストと、 rv コマンドで使用される片言の英語、および 状態を示す短い説明文です。

    空白  (reject) 通信相手は到達できないか、このサーバに同期しているか (同期ループ)、あるいは 無茶な同期距離のために捨てられました。

    x   (falsetick) 通信相手は交差アルゴリスムにより偽時計として捨てられました。

    .   (excess) 通信相手は同期距離によって並べ換えられたなかで、 最初の 10 個に入らなかったため捨てられました。 このためこれ以上検討するには不十分な候補です。

    -   (outlyer) 通信相手はクラスタリングアルゴリズムにより遠くにあるものとして捨てられました。

    +   (candidate) 通信相手は生き残り、結合アルゴリズムへの候補となりました。

    #   (selected) 通信相手は生き残りましたが、 同期距離によって並べ換えられたなかで最初の 6 個に入りませんでした。 アソシエーションが短命だった場合、 リソースを節約するために解散させられるかもしれません。

    *   (peer) 通信相手はシステム通信相手として宣言されており、 その変数をシステム変数に与えています。

    o   ((pps.peer)) 通信相手はシステム通信相手として宣言されており、 その変数をシステム変数に与えています。 しかし、システムの実際の同期は 1 秒ごとのパルス (PPS) 参照クロックドライバより間接的に、 あるいはカーネルインタフェースより直接、 PPS 信号で得ています。

flash 変数はデバッグを支援する貴重なものです。 NTP 仕様 RFC-1305 と NTP Version 4 で追加された仕様が 定義する本来の正常性チェックの結果を表示します。 TEST1 から TEST11 まで 11 個のテストが定義されています。 偶然の誤りからも故意の誤りからも自分を守りながら、 診断情報が最大限得られるある順序で、テストは実行されます。 flash 変数は最初に 0 に初期化されます。テストのセット 1 つを終えたあと、 1 つまたは複数のビットが設定されると、そのパケットを破棄します。

テスト TEST4 と TEST5 はアクセス権限と暗号化メッセージダイジェストをチェックします。 このテストのあとどれかのビットが設定されると、そのパケットを 破棄します。 テスト TEST10 と TEST11 は ntp.conf(5) のセクション 認証オプション で説明されている、 Autokey 公開鍵暗号化を使った認証確認状態をチェックします。 どれかのビットが設定され、アソシエーションが事前に到達可能との 印が付けられていると、そのパケットを破棄します。それ以外の場合、 NTP プロトコルが要求する通り、 送信元のタイムスタンプと受信側のタイムスタンプを保存し、 処理を続けます。

テスト TEST1 から TEST3 までは、オフセットと遅延を計算するパケットのタイムスタンプを チェックします。 どれかのビットが設定されると、そのパケットを破棄します。それ以外の 場合、パケットヘッダ変数を保存します。 テスト TEST6 から TEST8 までは、サーバの健全性をチェックします。 どれかのビットがセットされると、そのパケットを破棄します。 それ以外の場合、サーバに対するオフセットと遅延を計算し、 保存します。 テスト TEST9 は、アソシエーションそのものの健全性をチェックします。 どれかのビットが設定されると、そのパケットを破棄します。それ以外の 場合、保存されている変数を時計フィルタと緩和アルゴリズムに 回します。

各テストに対する flash のビットは、最下位ビットから昇順で次のように定義されます。

TEST1
    パケットが重複しています。 このパケットは、ひいき目で見ても偶然の再送によるものですし、 最悪の場合は、悪意を持って再送信されたものです。

TEST2
    間違ったパケットです。 以前に送ったメッセージに対する返答ではありません。 NTP デーモンが再起動されていて、通信相手以外の誰かが 気付く前だったときに起こります。

TEST3
    同期していません。 1 つ以上のタイムスタンプ・フィールドが不正です。 通常、通信相手からの最初のパケットを受信したときに起こります。

TEST4
    アクセスが拒否されました。 "アクセス制御" のページを参照してください。

TEST5
    暗号化認証に失敗しました。 ntp.conf(5) マニュアルページの 認証機能オプション 節を参照してください。

TEST6
    サーバが同期していません。 サーバの時計のネジを先に巻いてください。

TEST7
    サーバの階層が最大で 15 より大きいです。 サーバはおそらく同期しておらず、サーバの時計のネジを 巻く必要があるでしょう。

TEST8
    root の遅延または root のばらつきが 1 秒よりも長いです。 通信相手が火星と同期していない限り、こういうことが起きそうには ないのですが。

TEST9
    通信相手の遅延または通信相手のばらつきが 1 秒よりも長いです。 通信相手が火星上にでもない限り、こういうことが起きそうには ないのですが。

TEST10
    autokey プロトコルが認証失敗を検出しました。 ntp.conf(5) マニュアルページの 認証オプション 節を参照してください。

TEST11
    サーバまたは通信相手の認証が大丈夫か、 正当な公開鍵証明書を保持しているかを、 autokey プロトコルが確認していません。 ntp.conf(5) マニュアルページの 認証オプション 節を参照してください。

NTP バージョン 4 の Autokey サポートで使用されるシステム変数の追加は 以下のものが含まれます。

certificate filestamp
    証明ファイルが生成された時の NTP 秒を示します。

hostname host
    Unix の gethostname(3) ライブラリ関数が返すホスト名を示します。

flags hex
    現在のフラグビットを示します。ここで hex ビットは次に示すように解釈されます。

    0x01
        autokey が有効です。

    0x02
        RSA 公開鍵/暗号鍵ファイルが存在します。

    0x04
        PKI 確認ファイルが存在します。

    0x08
        Deffie-Hellman のパラメータファイルが存在します。

    0x10
        NIST 閏秒表ファイルが存在します。

leapseconds filestamp
    NIST 閏秒表ファイルが作成されたときの NTP 秒を表示します。

params filestamp
    Diffie-Hellman の協定パラメータファイルが生成されたときの NTP 秒を表示します。

publickey filestamp
    RSA 公開鍵/秘密鍵ファイルが生成されたときの NTP 秒を表示します。

refresh filestamp
    公開暗号値が更新、署名されたときの NTP 秒を表示します。

tay offset
    NIST 閏秒表を入手したときの TAI-UTC オフセットを秒単位で表示します。

さらに、NTP バージョン 4 Autokey サポートで使用される 通信相手変数の追加には以下のものが含まれます。

certificate filestamp
    認証証明ファイルが生成されたときのNTP 秒を表示します。

flags hex
    現在のフラグビットを表示します。ここで、 hex ビットは同名のシステム変数と同様に解釈します。 これらのビットはサーバから受信した最初の autokey メッセージの 中に設定され、次いで、サーバからそれに関連したデータを受信、 格納した際にリセットされます。

hcookie hex
    鍵協定アルゴリズムで用いられるホストクッキーを表示します。

initkey key
    autokey プロトコルの鍵リスト生成器により使用される鍵の初期値を 表示します。

initsequence index
    autokey プロトコルの鍵リスト生成器により使用されるインデックスの 初期値を表示します。

pcookie hex
    鍵リスト生成器により使用される通信相手のクッキーを指定します。

timestamp time
    最新の autokey 鍵リストが生成され署名されたときの NTP 秒を表示します。

pstatus assocID
    与えられたアソシエーションに対応するサーバに対し、 状態読み取りリクエストを送ります。 返された通信相手変数の名前と値を出力します。 変数の前に、ヘッダから得た状態ワードが 16 進数と片言の英語で 表示されることに注意してください。

readlist assocID

rl assocID
    内部変数リストの中の変数の値を返すようにサーバに要求します。 アソシエーション識別子が省略されるか 0 の場合、 変数はシステム変数であるとみなされます。 そうでなければ、 通信相手変数として扱われます。 内部変数リストが空の場合は、 リクエストはデータ無しで送られ、 リモートサーバはデフォルトの表示を返します。

readvar assocID
    variable_name[=value] ...

rv assocID
    variable_name[=value] ... 変数読み取りリクエストを送ることで、 指定した変数の値を返すようにサーバに要求します。 アソシエーション識別子を省略するか 0 を指定した場合、 変数はシステム変数です。 そうでなければ通信相手変数であり、 返される値は対応する通信相手のものとなります。 変数のリストを省略すると、データ無しのリクエストを送り、 サーバはデフォルトの表示を返します。

writevar assocID
    variable_name[=value] ... readvar リクエストと似ていますが、 指定した変数を読み取る代わりに書き込みます。

writelist [assocID]
    readlist リクエストと似ていますが、 内部のリストの変数を読み取る代わりに書き込みます。

関連項目
ntp.conf(5), ntpd(8), ntpdc(8)

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