unbound-control(8)
unbound-control
Section: unbound 1.4.17 (8)
Updated: May 24, 2012
名前
unbound-control, unbound-control-setup - Unboundリモートサーバー制御ユーティリティ
書式
unbound-control [-h] [-c cfgfile] [-s server] command
説明
Unbound-controlはunbound(8) DNSサーバーのリモート管理を行います。設定ファイルを読み込み、unboundサーバーにSSL越しで接続し、コマンドを送り、結果を表示します。
利用できるオプションは以下の通りです。
- -h
- バージョンとコマンドライン オプションのヘルプを表示します。
- -c cfgfile
- 設定を読み込む設定ファイル。省略したら、デフォルトの設定ファイルが使われます。
- -s server[@port]
- 接続するサーバーのIPv4かIPv6のアドレス。省略したら、アドレスは設定ファイルから読まれます。
コマンド
以下のコマンドが利用できます。
- start
- サーバーを起動します。単にunbound(8)を実行します。unboundの実行ファイルは環境変数PATHから検索します。-cを使って指定した設定ファイルかデフォルトの設定ファイルを使って起動します。
- stop
- サーバーを停止します。サーバー・デーモンが終了します
- reload
- サーバーをリロードします。これはキャッシュを削除し、新しい設定ファイルを読み込みます。
- verbosity number
- ログ出力の饒舌さの値を変更します。unbound.conf(5)におけるverbosityキーワードと同じ値です。サーバーがreload（設定ファイルの再読込）制御コマンドか次のverbosity制御コマンドが発行されるまでこの新しい設定値は続きます。
- log_reopen
- ログファイルを開き直します。一度閉じてから開きます。ログ出力しているファイルをデーモンが離すので、ログローテーションに役に足ります。syslogを使っているのであれば、syslogを閉じて、開き直すのを試みます。ただし、chrootのときはうまく動かないかもしれません。
- stats
- 統計を出力します。統計を出力します。内部カウンタを0にリセットします。これはstatistics-cumulative設定オプションを使って制御できます。統計は行毎に[名前]: [値]の形式で出力されます。
- stats_noreset
- 統計を覗きます。statsコマンドと同じように出力します。しかし、内部カウンタを0にリセットしません。
- status
- サーバーの状態を表示します。（ポートへの接続が拒否されて）動かなければ終了コードは3、エラーは1、動けば0です。
- local_zone name type
- 名前とタイプを伴ったローカル・ゾーンを追加します。local-zone設定オプションと同じです。そのゾーンがすでに存在していたら、タイプは与えられた引数に変更されます。
- local_zone_remove name
- 与えられた名前のローカル・ゾーンを削除します。そのゾーン内の全てのローカル・データも削除します。そのゾーンが存在しなかったら、コマンドは成功します。
- local_data RR data...
- 新しいローカル・データ、すなわち与えられたリソース・レコードを追加します。そのゾーンが存在しないときを除いて、local-data設定オプションと同じです。この場合は、このリモート制御コマンドはこのレコードと同じ名前のtransparentゾーンを生成します。このコマンドは詳細な文法エラーを返すことはしません。
- local_data_remove name
- ローカル名から全てのリソース・レコードのデータを削除します。その名前が項目をすでに持っていなければ、何も起きません。（staticゾーンでは）その名前に対して結果はNXDOMAINになります。しかし、その名前が空の終端でないもの（削除された名前の下のドメイン名にまだデータがある）になれば、NOERRORデータなしという回答がその名前に対しての結果になります。
- dump_cache
- キャッシュの内容が標準出力にテキスト形式で出力されます。ファイルにキャッシュを保存するため、ファイルにリダイレクトできます。
- load_cache
- キャッシュの内容を標準入力から読み込みます。dump_cacheと同じ形式を使います。古いか間違ったデータのキャッシュを読み込むことは、古いか間違ったデータをクライアントに返すという結果になります。このようにキャッシュにデータを読み込むことはデバッグを手助けするために用意されています。
- lookup name
- 指定した名前を検索するのに使われたネームサーバーを標準出力に出力します。
- flush name
- キャッシュからその名前を削除します。タイプとしてA, AAAA, NS, SOA, CNAME, DNAME, MX, PTR, SRV, NAPTRを削除します。それは速く行えます。他のレコード・タイプはflush_typeやflush_zoneを使って削除できます。
- flush_type name type
- キャッシュからその名前とタイプの情報を削除します。
- flush_zone name
- キャッシュからその名前以下の全ての情報を削除します。新しい検索が行われるように、そのRRsetとキー・エントリは削除されます。これは、キャッシュ全体を歩き、検査する必要があり、動作が遅いです。
- flush_stats
- 統計を0にリセットします。
- flush_requestlist
- 実行中のクエリーを落とします。サーバーが実行中のクエリーの実行を止めます。キャッシュは影響を受けません。これらのクエリーに対して返答は送られません。おそらく、後ほど再びこれらのユーザのリクエストが行われます。より高い饒舌さのレベルのような新しい設定でクエリーに働くようにサーバーを再起動させるのに役に立ちます。
- dump_requestlist
- 何を処理しているかを見せます。サーバーが処理している最中のすべてのクエリーを出力します。ユーザが待たされている時間を出力します。内部のリクエストでは、時間は出力されません。それから、モジュールの状態を出力します。
- flush_infra all|IP
- allであれば、全てのインフラ キャッシュが空にされます。特定のIPアドレスであれば、そのアドレスのエントリーがキャッシュから削除されます。これには、EDNS、ping、不完全データが含まれます。
- dump_infra
- インフラ キャッシュの内容を見せます。
- set_option opt: val
- 再読込なしに与えられた値をオプションに設定します。それ故に、キャッシュは流されません。オプションは':'で終わり、空白がそのオプションと値の間になければなりません。このように設定しても、値によっては効果がないものもあります。新しい値は設定ファイルに書き込まれません。すべてのオプションがサポートされるわけでもありません。これはlibunboundのset_optionコールとは異なります。unboundは初期化されていないため、すべての値が使えます。
- 使える値は次の通りです: statistics-interval, statistics-cumulative, do-not-query-localhost, harden-short-bufsize, harden-large-queries, harden-glue, harden-dnssec-stripped, harden-below-nxdomain, harden-referral-path, prefetch, prefetch-key, log-queries, hide-identity, hide-version, identity, version, val-log-level, val-log-squelch, ignore-cd-flag, add-holddown, del-holddown, keep-missing, tcp-upstream, ssl-upstream。
- get_option opt
- オプションの値を得ます。':'なしでオプション名を与えます。その値が出力されます。値が""であれば、何も出力されず、接続は閉じます。エラー時には、'error ...'が出力されます（見知らぬオプションによる文法エラーを与えます）。オプションによっては、各行に一つずつのような値の一覧が出力されます。そのオプションはset_optionで修正された設定ファイルから見えます。オーバーライドが行われてもよいオプションによっては、このコマンド（例えば、verbosityやforwardの制御コマンドの結果）では現れません。すべてのオプションが使えるわけではありません。list_stubsとlist_forwardsとlist_local_zonesとlist_local_data for thoseを参照してください。
- list_stubs
- 利用中のスタブ ゾーンの一覧を表示します。出力に1つずつ表示されます。これには利用中のルート ヒントも含まれます。
- list_forwards
- 利用中のフォワード ゾーンの一覧を表示します。出力にゾーン毎に表示されます。
- list_local_zones
- 利用中のローカル ゾーンの一覧を表示します。ゾーン タイプと共に行毎に一つづつ表示されます。
- list_local_data
- 利用中のローカル データのリソース レコードの一覧を表示します。そのリソース レコードが表示されます。
- forward_add [+i] zone addr ...
- 動作中のunboundに新しいフォワード ゾーンを追加します。 さらに、+i オプションを付けると、ゾーンに対して（他の名前のためにDNSSECルート トラストアンカーを持っていればinsecureで解決できる）domain-insecureを追加します。unbound.confのforward-zoneの設定のように、アドレスはIPv4 でも IPv6 でもネームサーバーのホスト名でもよいです。
- forward_remove [+i] zone
- 動作中のunboundからフォワード ゾーンを削除します。さらに、+iオプションも付けると、ゾーンに対してdomain-insecureを削除します。
- stub_add [+ip] zone addr ...
- 動作中のunboundに新しいスタブ ゾーンを追加します。さらに、+iオプションも付けると、ゾーンに対してdomain-insecureを追加します。+pオプションを付けるとそのスタブゾーンはprimeに設定されます。付けなければnotprimeに設定されます。unbound.confのstub-zoneの設定のように、アドレスはIPv4 でも IPv6 でもネームサーバーのホスト名でもよいです。
- stub_remove [+i] zone
- 動作中のunboundからスタブ ゾーンを削除します。さらに、+iオプションも付けると、ゾーンに対してdomain-insecureを削除します。
- forward [off | addr ... ]
- フォワードのモードを設定します。サーバーが他の上流のネームサーバーに尋ねるべきかを設定します。インターネット ルート ネームサーバー自身に行くべきか、あるいは現在の設定を見せます。DHCP更新の後にネームサーバーを渡すことができます。
- 引数が無い場合には、すべてのクエリーをフォワードするために使われている現在のアドレスの一覧が表示されます。起動時にはforward-zoneは"."です。その後、状態を見せます。フォワードが使われていなければ、出力しません。
- offが渡されたら、フォワードは無効にされ、ルート ネームサーバーが使われます。これはバギーなネームサーバーやDHCPから返されたDNSSECをサポートしていないネームサーバーを避けるために使うこともできます。しかし、ホテルやホットスポットでは働かないかもしれません。
- 一つ以上のIPv4やIPv6のアドレスが渡されたら、クエリーをフォワードするのに使われます。このとき、アドレスはスペース区切りです。'@port'でポート番号が正しく設定されます（デフォルトのポートは53（DNS）です。）
- デフォルトでは、ルート"."のためには、設定ファイルからのフォワーダーの情報が使われます。設定ファイルは変更されません。そのため、リロード後にこれらの変更は消えます。設定ファイルでの他のフォワード ゾーンはこのコマンドにより影響を受けません。
終了コード
unbound-controlプログラムは、エラーのときにはステータスコード1で、成功のときにはステータスコード0で終了します。
セットアップ
セットアップはサーバーとクライアントの両方に自己署名証明書とプライベート鍵を要求します。スクリプトunbound-control-setupはデフォルトの実行ディレクトリ、あるいは-dで指定した別のディレクトリにそれらを生成します。鍵ファイルへのアクセス制御の権限を変更すれば、全てのユーザではなくデフォルトの所有者とグループによりunbound-controlを誰が使うかを決めることができます。デーモンがファイルを読み込むのを許可されるように、unbound.confで設定したのと同じユーザ名あるいはrootとしてスクリプトを実行します。例えば次のように実行します:
sudo -u unbound unbound-control-setup
unbound.confでユーザ名を設定していなければ、デーモンを起動させたユーザの証明のために鍵は読み込み権限を必要とします。スクリプトはディレクトリに存在するプライベート鍵を保存します。rootとしてスクリプトを動かした後に、unbound.confでcontrol-enableをオンにしてください。
STATISTIC COUNTERS
The stats command shows a number of statistic counters.
- threadX.num.queries
- number of queries received by thread
- threadX.num.cachehits
- number of queries that were successfully answered using a cache lookup
- threadX.num.cachemiss
- number of queries that needed recursive processing
- threadX.num.prefetch
- number of cache prefetches performed. This number is included in cachehits, as the original query had the unprefetched answer from cache, and resulted in recursive processing, taking a slot in the requestlist. Not part of the recursivereplies (or the histogram thereof) or cachemiss, as a cache response was sent.
- threadX.num.recursivereplies
- The number of replies sent to queries that needed recursive processing. Could be smaller than threadX.num.cachemiss if due to timeouts no replies were sent for some queries.
- threadX.requestlist.avg
- The average number of requests in the internal recursive processing request list on insert of a new incoming recursive processing query.
- threadX.requestlist.max
- Maximum size attained by the internal recursive processing request list.
- threadX.requestlist.overwritten
- Number of requests in the request list that were overwritten by newer entries. This happens if there is a flood of queries that recursive processing and the server has a hard time.
- threadX.requestlist.exceeded
- Queries that were dropped because the request list was full. This happens if a flood of queries need recursive processing, and the server can not keep up.
- threadX.requestlist.current.all
- Current size of the request list, includes internally generated queries (such as priming queries and glue lookups).
- threadX.requestlist.current.user
- Current size of the request list, only the requests from client queries.
- threadX.recursion.time.avg
- Average time it took to answer queries that needed recursive processing. Note that queries that were answered from the cache are not in this average.
- threadX.recursion.time.median
- The median of the time it took to answer queries that needed recursive processing. The median means that 50% of the user queries were answered in less than this time. Because of big outliers (usually queries to non responsive servers), the average can be bigger than the median. This median has been calculated by interpolation from a histogram.
- total.num.queries
- summed over threads.
- total.num.cachehits
- summed over threads.
- total.num.cachemiss
- summed over threads.
- total.num.prefetch
- summed over threads.
- total.num.recursivereplies
- summed over threads.
- total.requestlist.avg
- averaged over threads.
- total.requestlist.max
- the maximum of the thread requestlist.max values.
- total.requestlist.overwritten
- summed over threads.
- total.requestlist.exceeded
- summed over threads.
- total.requestlist.current.all
- summed over threads.
- total.recursion.time.median
- averaged over threads.
- time.now
- current time in seconds since 1970.
- time.up
- uptime since server boot in seconds.
- time.elapsed
- time since last statistics printout, in seconds.
EXTENDED STATISTICS
- mem.total.sbrk
- If sbrk(2) is available, an estimate of the heap size of the program in number of bytes. Close to the total memory used by the program, as reported by top and ps. Could be wrong if the OS allocates memory non-contiguously.
- mem.cache.rrset
- Memory in bytes in use by the RRset cache.
- mem.cache.message
- Memory in bytes in use by the message cache.
- mem.mod.iterator
- Memory in bytes in use by the iterator module.
- mem.mod.validator
- Memory in bytes in use by the validator module. Includes the key cache and negative cache.
- histogram.<sec>.<usec>.to.<sec>.<usec>
- Shows a histogram, summed over all threads. Every element counts the recursive queries whose reply time fit between the lower and upper bound. Times larger or equal to the lowerbound, and smaller than the upper bound. There are 40 buckets, with bucket sizes doubling.
- num.query.type.A
- The total number of queries over all threads with query type A. Printed for the other query types as well, but only for the types for which queries were received, thus =0 entries are omitted for brevity.
- num.query.type.other
- Number of queries with query types 256-65535.
- num.query.class.IN
- The total number of queries over all threads with query class IN (internet). Also printed for other classes (such as CH (CHAOS) sometimes used for debugging), or NONE, ANY, used by dynamic update. num.query.class.other is printed for classes 256-65535.
- num.query.opcode.QUERY
- The total number of queries over all threads with query opcode QUERY. Also printed for other opcodes, UPDATE, ...
- num.query.tcp
- Number of queries that were made using TCP towards the unbound server.
- num.query.ipv6
- Number of queries that were made using IPv6 towards the unbound server.
- num.query.flags.RD
- The number of queries that had the RD flag set in the header. Also printed for flags QR, AA, TC, RA, Z, AD, CD. Note that queries with flags QR, AA or TC may have been rejected because of that.
- num.query.edns.present
- number of queries that had an EDNS OPT record present.
- num.query.edns.DO
- number of queries that had an EDNS OPT record with the DO (DNSSEC OK) bit set. These queries are also included in the num.query.edns.present number.
- num.answer.rcode.NXDOMAIN
- The number of answers to queries, from cache or from recursion, that had the return code NXDOMAIN. Also printed for the other return codes.
- num.answer.rcode.nodata
- The number of answers to queries that had the pseudo return code nodata. This means the actual return code was NOERROR, but additionally, no data was carried in the answer (making what is called a NOERROR/NODATA answer). These queries are also included in the num.answer.rcode.NOERROR number. Common for AAAA lookups when an A record exists, and no AAAA.
- num.answer.secure
- Number of answers that were secure. The answer validated correctly. The AD bit might have been set in some of these answers, where the client signalled (with DO or AD bit in the query) that they were ready to accept the AD bit in the answer.
- num.answer.bogus
- Number of answers that were bogus. These answers resulted in SERVFAIL to the client because the answer failed validation.
- num.rrset.bogus
- The number of rrsets marked bogus by the validator. Increased for every RRset inspection that fails.
- unwanted.queries
- Number of queries that were refused or dropped because they failed the access control settings.
- unwanted.replies
- Replies that were unwanted or unsolicited. Could have been random traffic, delayed duplicates, very late answers, or could be spoofing attempts. Some low level of late answers and delayed duplicates are to be expected with the UDP protocol. Very high values could indicate a threat (spoofing).
ファイル
- /etc/unbound/unbound.conf
- unboundの設定ファイル。
- /var/unbound
- プライベート鍵(unbound_server.keyとunbound_control.key)と自己署名証明書(unbound_server.pemとunbound_control.pem)を置くディレクトリ。
関連項目
unbound.conf(5), unbound(8).