.\"
.\" %FreeBSD: src/usr.sbin/ntp/doc/ntpdc.8,v 1.2.2.2 2000/05/15 11:53:05 sheldonh Exp %
.\"
.Dd January 7, 2000
.\" jpman %Id: ntpdc.8,v 1.4 2000/06/02 11:05:53 takamune Stab %
.\" WORD: dotted-quad form	ドットで 4 つの部分に区切られた形式
.\" WORD: local clock		ローカル時計
.\" WORD: request		リクエスト (名詞の場合)
.\" WORD: common key		共通鍵
.\" WORD: key identifier	鍵の識別子
.\" WORD: key number		鍵番号
.\" WORD: The following options are available:
.\" WORD:	以下のオプションが使用可能です:
.\" WORD: falsetick		偽時計
.\" WORD: the precision time kernel modifications are in use
.\" WORD:	カーネルに高精度な時刻保持のための変更がなされている
.\" WORD: discipline		規律
.\" WORD: association
.\" WORD:	無理に訳さなかった (ntp.conf.5, ntpq.8 とは不整合)
.\" WORD: reference clock	参照クロック
.\" WORD: symmetric active	対称的アクティブ
.\" WORD: symmetric passive	対称的パッシブ
.Dt NTPDC 8
.Os
.Sh 名称
.Nm ntpdc
.Nd NTP の特別な問い合わせプログラム
.Sh 書式
.Nm ntpdc
.Op Fl ilnps
.Op Fl c Ar command
.Op Ar host ...
.Sh 解説
.Nm
は
.Xr ntpd 8
デーモンの現在の状態について問い合わせたり、状態の変更を要求する際に使
われます。このプログラムは、対話的なモードでもコマンドライン引数を
使った制御でも動作させることができます。
広範囲にわたる状態や統計の情報が、
.Nm
のインタフェースを通じて提供されています。
それに加えて、
.Xr ntpd 8
の設定ファイルを使って起動時に指定できるほとんどすべて
のオプションが、
.Nm
を使って、実行時にも指定できます。
.Pp
.Nm
が実行されたとき、1 つ以上のリクエストオプションが、
コマンドラインに含まれる場合は、それぞれのリクエストは、コマンドライン
引数で与えられた各ホスト、またはデフォルトである
.Dq localhost
で動いている NTP サーバに送られます。
リクエストオプションが与えられなかった場合、
.Nm
は、コマンドを標準入力から読み込み、
コマンドラインで指定された最初のホストで動いている
NTP サーバに対して実行しようとします。
このときも、
ホストが指定されていないときは、デフォルトで
.Dq localhost
になります。
.Nm
は、標準入力が端末である場合は、プロンプトを出してコマンドを受け付けます。
.Pp
.Nm
は、NTP サーバとの通信に NTP モード 7 パケットを使うため、
ネットワーク上でそれを許すような互換サーバへの問い合わせに使用できます。
NTP は UDP のプロトコルなので、特にネットワークトポロジ的に
遠くにある場合は、この通信はやや信頼性に欠けるということに注意して
ください。
.Nm
は、リクエストを再送する試みを行ないません。適当な制限時間の
範囲内でリモートホストから返事がなかったときは、時間切れとなります。
.Pp
.Nm
の操作は
.Xr ntpd 8
に特有な実装に特化しており、このデーモンやいくつかの古いバージョンのもの
に対してしか動かないかもしれません。
リモートの
.Nm
からのリクエストがローカルサーバの状態を変更する場合は、
リモートプログラムとローカルサーバの両方が共通鍵と鍵の識別子を共有し、
それが認証される必要があります。
.Pp
.Fl i
または
.Fl n
以外のコマンドラインオプションを指定すると、指定したホスト (群) に、
指定した問い合わせ (または複数の問い合わせ) を直ちに送ることになります。
指定しなかった場合、
.Nm
は標準入力から対話的なフォーマットのコマンドを読み込もうとします。
以下のオプションが使用可能です:
.Bl -tag -width indent
.It Fl c Ar command
.Ar command
引数が対話的なフォーマットのコマンドとして解釈され、
指定されたホスト (群) に対して実行すべきコマンドのリストに
付け加えられます。
複数の
.Fl c
オプションを与えることもできます。
.It Fl i
.Nm
を強制的に対話的モードで動作させます。標準出力にプロンプトが
表示され、標準入力からコマンドが読み込まれます。
.It Fl l
サーバ (群) に既知な通信相手 (peer) のリストを取得します。このスイッチは、
.Dq Li -c listpeers
と同等です。
.It Fl n
すべてのホストアドレスを、ドットで 4 つの部分に区切られた数値の形式で出力し、
正規のホスト名に変換しません。
.It Fl p
サーバに既知な通信相手のリストと、それらの状態の概要を出力します。
これは、
.Dq Li -c peers
と同等です。
.It Fl s
サーバに既知な通信相手のリストと、それらの状態の概要を、
.Fl p
スイッチとは少し異なるフォーマットで出力します。
これは
.Dq Li -c dmpeers
と同等です。
.El
.Ss 対話的コマンド
対話的なフォーマットのコマンドは、キーワードとそれに続く 0 から 4 個の
引数から構成されます。キーワード全長のうち、他と区別できる文字数が
タイプされれば、有効になります。
コマンドの出力は通常標準出力に送られますが、コマンドライン上で
.Qq >
に続けてファイル名を指定することで、個々のコマンドの出力を
ファイルに送ることができます。
.Pp
いくつかの対話的フォーマットのコマンドは、
.Nm
プログラム自身の中で全体が実行され、サーバへの NTP モード 7 リクエストは
送られません。この種類のコマンドには以下のものがあります:
.Bl -tag -width indent
.It Ic ? Op Ar command_keyword
.It Ic help Op Ar command_keyword
単独の
.Ic ?
は、
.Nm
が知っているすべてのコマンドキーワードのリストを出力します。
.Ic ?
の後にコマンドキーワードが続くときは、コマンドの機能と用法を出力します。この
コマンドは、
.Nm
に関して、多分このマニュアルよりも良い情報源となるでしょう。
.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 quit
.Nm
を終了します。
.It Ic passwd
このコマンドは、認証設定リクエストに使われるパスワードの入力
(画面に表示されません) を求めるプロンプトを出します。
このリクエストが成功するためには、NTP サーバが認証のために使うよう
設定した鍵に、パスワードが対応していなければなりません。
.It Ic timeout Ar milliseconds
サーバへの問い合わせに対する応答の制限時間を指定します。デフォルト
は、約 5000 ミリ秒です。
.Nm
はそれぞれの問い合わせに対して時間切れを待ったあと再試行するため、
合計の待ち時間は設定された制限時間の値の 2 倍になることに注意してください。
.\" XXX retry しないんじゃなかったの？
.El
.Ss 制御メッセージコマンド
問い合わせコマンドは、情報を要求する NTP モード 7 パケットをサーバに送ります。
これらは、サーバの設定状態を変更しない
.Qq 読み込み専用
コマンドです。
.Bl -tag -width indent
.It Ic listpeers
サーバが状態を管理する通信相手の簡略なリストを得て、出力します。
これには、サーバが同期する予定の候補であるとみなす階層の通信相手を含めた、
すべての設定された通信相手を含んでいるはずです。
.It Ic peers
サーバが状態を管理する通信相手と、その状態の概要を出力します。
状態の概要は、以下のものを含みます。すなわち、リモートの通信相手のアドレス、
ローカルインタフェースアドレス (ローカルアドレスが決まっていないなら
0.0.0.0)、リモートの通信相手の階層 (階層 16 は、リモートの通信相手が同期し
ていない事を示します)、秒で表すポーリング間隔、8 進で表す到達可能性レジスタ、
通信相手の遅れ、オフセット、ばらつきを秒で表した現在の推定値です。
更に、左端の文字は、この通信相手エントリが操作しているモードを
示します。
.Qq +
は対称的アクティブを、
.Qq -
は対称的パッシブを表し、
.Qq =
は、リモートサーバがクライアントモードでポーリングされていることを意味し、
.Qq ^
は、サーバがこのアドレスにブロードキャストブロードキャストしていることを示し、
.Qq ~
は、リモートの通信相手がブロードキャストを送っていることを示し、
.Qq *
は、サーバが現在同期している通信相手であることを示します。
.Pp
ホストフィールドの内容は、ホスト名、IP アドレス、
参照クロック実装名とパラメータ、あるいは、
.Dq Li REFCLK(<implementation number>, <parameter>)
の 4 つの形のうち 1 つです。
.Qq hostnames no
の状態では、IP アドレスだけが表示されます。
.It Ic dmpeers
少々異なる通信相手概要リストです。
行の左端の文字以外は
.Em peers
と同じ出力になります。
文字は、時計選択アルゴリズムの最後のステージに含まれる通信相手の隣にだけ
現れます。
.Qq \&.
は、偽時計検出でこの通信相手が捨てられたことを、
.Qq +
は検出により同期対象として適切であると判断されたことを示します。
.Qq *
は、通信相手であるサーバは現在同期しているサーバであることを示しています。
.It Xo Ic showpeer
.Ar peer_address
.Op Ar ...
.Xc
1 つ以上の通信相手に対して、現在の通信相手の変数に関する詳細な内容を表示します。
値の多くに関しては、NTP バージョン 2 仕様書に詳しく述べられています。
.It Xo Ic pstats
.Ar peer_address
.Op Ar ...
.Xc
指定した通信相手に関連する統計カウンタを通信相手毎に表示します。
.It Xo Ic clockinfo
.Ar clock_peer_address
.Op Ar ...
.Xc
通信相手の時計に関する情報を得て、それを表示します。得られた値は、
設定上のあいまいな要因の情報と他の時計性能の情報を
提供してくれます。
.It Ic kerninfo
カーネルのフェーズロックループ操作パラメータを得て、それを表示します。
この情報は、精度の高い時刻保持機能のために、カーネルが特に
修正されている場合にだけ得られます。
.It Ic loopinfo Op Ar oneline | Ar multiline
選択されたループフィルタ変数の値を表示します。ループフィルタとは、
ローカルシステム時計の調節を行なう NTP の一部です。
.Qq offset
は、パケット処理コードによってループフィルタに与えられた最後のオフセットです。
.Qq frequency
は、100 万分の 1 (ppm) で表わされるローカル時計の周波数誤差です。
.Qq time_const
は、フェーズロックループの
.Qq 堅固さ (stiffness)
を制御し、その速度で発振器のゆらぎを調節します。
.Qq watchdog timer
の値は、ループフィルタに最後のサンプルのオフセットが与えられてから
経過した秒数です。
.Ar oneline
と
.Ar multiline
オプションはこの情報が
出力されるフォーマットの指定で、
.Ar multiline
がデフォルトです。
.It Ic sysinfo
システム状態変数、すなわち、ローカルサーバに関するさまざまな状態を表示します。
最後の 4 行以外は、皆 NTP バージョン 3 仕様である RFC 1305 で述べられています。
.Qq system flags
は、いろいろなシステムフラグを表示し、一部は
.Ic enable
及び
.Ic disable
設定コマンドで、それぞれの設定やクリアができます。
それらのフラグは auth, bclient, monitor, pll, pps, stats で、
後述する
.Sx Runtime Configuration Requests
節の
.Ic enable
コマンドにて説明されています。
その他に kernel_pll と kernel_pps という
読み込み専用のフラグが 2 つあります。
カーネルに高精度な時刻保持のための変更がなされている時に、
これらのフラグは同期状態を示します。
kernel_pll はローカル時計が kernel によって規律されていることを示し、
kernel_pps は kernel による規律が PPS 信号によってもたらされていることを
示します。
.Pp
.Qq stability
は、システム周波数の修正がされた後に残る残留周波数誤差で、
保守やデバッグに使われます。
多くのアーキテクチャでは、この値は初期の 500 ppm 程度から、.01 から 0.1 ppm
という低い範囲にまで減少します。
もしデーモンが起動されてからも、この値が高いままである場合は、
ローカルな時計がどこかおかしいか、カーネル変数
.Qq tick
が正しくないかもしれません。
.Pp
.Qq broadcastdelay
は、
.Qq broadcastdelay
設定オプションで設定されるデフォルトのブロードキャスト遅延時間を表示し、
.Qq authdelay
は、
.Qq authdelay
設定オプションで設定されるデフォルトの認証遅延時間を表示します。
.It Ic sysstats
プロトコルモジュールで管理される統計カウンタを表示します。
.It Ic memstats
メモリ割り当てコードに関する統計カウンタを表示します。
.It Ic iostats
入出力モジュールで管理される統計カウンタを表示します。
.It Ic timerstats
タイマ/イベントキューをサポートするコードで管理される統計カウンタを表示します。
.It Ic reslist
サーバの制限リストを得て、表示します。このリストは、
(通常) ソートされた順で出力され、制限がどのように適用されるかを
理解する助けになるかもしれません。
.It Ic monlist Op Ar version
モニタ機能により収集、管理されるトラフィックカウントの値を得て、表示します。
通常、バージョン番号は指定する必要がありません。
.It Xo Ic clkbug
.Ar clock_peer_address
.Op Ar ...
.Xc
参照クロックドライバのデバッグ情報を得ます。この情報は、
一部の時計ドライバでのみ提供され、
ドライバのソースのコピーが手元に無い場合、ほとんどデコードできません。
.El
.Ss 実行時設定リクエスト
サーバ内で状態を変更するようなリクエストは、すべてサーバが設定した
NTP 鍵を使って認証されます
(この機能はサーバ側で鍵を設定しないことにより、無効にすることもできます)。
鍵番号とそれに対応する鍵も、
.Nm
が知っていなければなりません。
これは、
.Ic keyid
と
.Ic passwd
コマンドを使えば可能で、後者では、暗号化鍵を使うために
パスワードを求めるプロンプトを端末に出します。
サーバへの認証されたリクエストを結果的に必要とするコマンドが最初に与えられた
時点でも、自動的に鍵番号とパスワード両方の入力が要求されます。
認証は、そのような変更をする権限を持っているリクエストであるかを
検証するだけでなく、送信エラーに対するより一層の保護を行う事になります。
.Pp
認証されたリクエストは、常にパケットデータの中に、認証コードの計算に
含まれているタイムスタンプを含んでいます。
このタイムスタンプは、サーバによって受信時刻と比較されます。この差がある小さな
値より大きければ、リクエストは拒否されます。これには 2 つの理由があります。
1 つ目は、あなたの LAN のトラフィックを盗み聞きできる誰かによるサーバへの
単純な繰り返しによる攻撃をより困難にします。2 つ目は、ネットワーク的に
離れたホストから、あなたのサーバへ設定変更リクエストを行なうことを
より困難にします。
再設定機能は、ローカルホストのサーバに対しては簡単で、時刻同期した
同じ LAN 上のホストでも普通に行なえますが、より離れたホストでは
非常にやりにくくなっています。
したがって、適当なパスワードを選択し、鍵の配布と防護に注意を払い、
適切な送信元アドレス制限が施されれば、実行時再設定の機能については
適切なセキュリティレベルにあることになります。
.Pp
以下のコマンドは皆、認証を必要とするリクエストです。
.Bl -tag -width indent
.It Xo Ic addpeer
.Ar peer_address
.Op Ar keyid
.Op Ar version
.Op Ar prefer
.Xc
与えられたアドレスを設定された通信相手として追加し、
対称的アクティブモードで動作します。
既に通信相手として設定されている通信相手を指定した場合、その通信相手は
このコマンドが実行されたときに削除
されるか、単に新しい設定に従うよう適当に変更されることに注意してください。
オプションの
.Ar keyid
が 0 でない整数の場合、リモートサーバに
出ていくすべてのパケットは、この鍵により暗号化された
認証フィールドを持つことになります。値が 0 の場合
(または指定されなかった場合)、認証は行なわれません。
.Ar version
は、1, 2, 3 のどれでもよく、デフォルトでは 3 になります。
.Ar prefer
キーワードは、優先する通信相手を示します
(その結果、可能であれば時計同期の主要元として使用されます)。
優先する通信相手は、 PPS 信号の信頼性も決めます。優先する通信相手が同期に
適している場合、PPS 信号も信頼できると判断されます。
.It Xo Ic addserver
.Ar peer_address
.Op Ar keyid
.Op Ar version
.Op Ar prefer
.Xc
操作モードがクライアントであること以外は、
.Ic addpeer
コマンドと同等です。
.It Xo Ic broadcast
.Ar peer_address
.Op Ar keyid
.Op Ar version
.Xc
操作モードがブロードキャストであること以外は、
.Ic addpeer
コマンドと同等です。この場合、正当な鍵の識別子と鍵が必要になります。
.Ar peer_address
パラメータは、ローカルネットワークのブロードキャストアドレスか、または
NTP に割り当てられたマルチキャストグループアドレスにできます。
マルチキャストアドレスの場合、マルチキャストに対応したカーネルが
必要になります。
.It Xo Ic unconfig
.Ar peer_address
.Op Ar ...
.Xc
このコマンドは、指定した通信相手 (群) から設定済みを表すビットを除去します。
多くの場合、これによって通信相手の設定が削除されることになります。
しかしながら、リモートの通信相手が未設定状態の継続を希望し、
それが適切である場合は、隣接関係は未設定モードのまま残る場合もあります。
.It Xo Ic fudge
.Ar peer_address
.Op Ar time1
.Op Ar time2
.Op Ar stratum
.Op Ar refid
.Xc
このコマンドは、あるデータを参照クロックとしてセットできるようにします。
詳細な情報は、ソースリストを参照してください。
.It Xo Ic enable
.Ar flag
.Op Ar ...
.Xc
.It Xo Ic disable
.Ar flag
.Op Ar ...
.Xc
これらのコマンドは
.Xr ntpd 8
の設定ファイルにおける
.Qq enable
や
.Qq disable
と同じ方法で操作します。
以下はフラグの説明です。
auth, bclient, monitor, pll, pps, stats フラグのみが
.Nm
で設定でき、pll_kernel, pps_kernel フラグは読み込み専用であることに
注意してください。
.Bl -tag -width indent
.It auth
通信相手が信頼できる鍵と
鍵の識別子を使って正しく認証されたときだけ、未設定の
通信相手にサーバを同期させるようにします。
デフォルトでは有効になっています。
.It bclient
.Qq mutlicastclient
設定オプションでのデフォルトアドレスと同じように、
ブロードキャストサーバやマルチキャストサーバからのメッセージを
聞く (listen) ようにします。
デフォルトでは無効になっています。
.\" .It pll の削除 (send-pr docs/17500)
.It monitor
.Ic monlist
コマンドに対して
モニタ機能を有効にします。
デフォルトでは有効になっています。
.\" .Ic -> .It の変更 (send-pr docs/17500)
.It pll
サーバが NTP を使ってローカル時計を合わせるようにします。
無効の場合は、ローカル時計は
内部の時間および周波数オフセットによって勝手に動作することになります。
このフラグは、ローカル時計が他のデバイスやプロトコルにより制御されていて、
NTP は他のクライアントが同期するためだけに使われるような場合に便利です。
この場合、ローカル時計ドライバが使用されます。
より詳細な情報は
.Qo
参照クロックドライバ
.Qc
のページを参照してください (
.Pa /usr/share/doc/ntp
にある HTML 文書の一部として参照可能です)。
デフォルトでは有効になっています。
.\" .Ic -> .It の変更 (send-pr docs/17500)
.It pps
高精度な時刻保持のための変更がなされたカーネルにより
周波数と時刻が規律されている場合に、
1 秒ごとのパルス信号 (PPS) を有効にします。
より詳細な情報は
.Qo
高精度な時刻保持のためのカーネルモデル
.Qc
のページを参照してください。
デフォルトでは無効になっています。
.\" .Ic -> .It の変更 (send-pr docs/17500)
.It stats
統計機能を有効にします。
より詳細な情報は
.Xr ntp.conf 5
マニュアルページの
.Qq 監視機能のサポート
節を参照してください。
デフォルトでは有効になっています。
.\" .Ic -> .It の変更 (send-pr docs/17500)
.It pll_kernel
高精度な時刻保持のための変更がカーネルになされている場合、
カーネルが時計の規律を制御していることを示します。
そうでない場合はデーモンが時計の規律を制御しています。
.\" .Ic -> .It の変更 (send-pr docs/17500)
.It pps_kernel
高精度な時刻保持のための変更がカーネルなされており、
また1 秒ごとのパルス信号 (PPS) が存在している場合、
PPS 信号が時計の規律を制御していることを示します。
そうでない場合は pll_kernel フラグの示すとおり、
デーモンまたはカーネルが時計の規律を制御しています。
.El
.It Xo Ic restrict
.Ar address
.Ar mask
.Ar flag
.Op Ar flag
.Xc
このコマンドは
.Xr ntpd 8
の
.Qq restrict
設定オプションと同じ方法で操作します。
.It Xo Ic unrestrict
.Ar address
.Ar mask
.Ar flag
.Op Ar flag
.Xc
制限リストにおいて、マッチしたエントリを無制限にします。
.It Xo Ic delrestrict
.Ar address
.Ar mask
.Op Ar ntpport
.Xc
制限リストから一致するエントリを削除します。
.It Ic readkeys
現在の認証鍵のセットを一掃し、鍵ファイル (これは
.Xr ntpd 8
設定ファイルの中で指定されていなければなりません) の
再読み込みを行なって新しいセットにします。
こうすることで、サーバを再スタートさせずに暗号化鍵の変更ができます。
.It Xo Ic trustkey
.Ar keyid
.Op Ar ...
.Xc
.It Xo Ic untrustkey
.Ar keyid
.Op Ar ...
.Xc
これらのコマンドは
.Xr ntpd 8
の
.Qq trustedkey
や
.Qq untrustkey
設定オプションと同じ方法で操作します。
.It Ic authinfo
既知の鍵や実行した暗号化、復号化の数を含む、認証モジュールに関する
情報を返します。
.It Ic traps
サーバに設定されているトラップを表示します。
詳細はソースリストを参照してください。
.It Xo Ic addtrap
.Ar address
.Op Ar port
.Op Ar interface
.Xc
非同期メッセージに対するトラップをセットします。
詳細はソースリストを参照してください。
.It Xo Ic clrtrap
.Ar address
.Op Ar port
.Op Ar interface
.Xc
非同期メッセージに対するトラップを解除します。
詳細はソースリストを参照してください。
.\" Ic の追加 (send-pr docs/17500)
.It Ic reset Ar counter Op Ar ...
サーバのいろいろなモジュールのなかの統計カウンタをクリアします。
詳細はソースリストを参照してください。
.El
.Sh 関連項目
.Xr ntp.conf 5 ,
.Xr ntpd 8
.Rs
.%A David L. Mills
.%T Network Time Protocol (Version 3)
.%O RFC1305
.Re
.Sh 歴史
Toronto 大学の
.An Dennis Ferguson
によって書かれました。
.Sh バグ
.Nm
は、未完成のハックです。表示される情報の多くは死ぬほど退屈で、実装した
人間だけに気に入られるものです。このプログラムは、新しい (そして一時的な)
仕様を追加しやすいようデザインされており、使いやすくするには手間が
かかります。それでも、このプログラムは、場合によっては有用です。