unbound-control

Section: unbound 1.4.13 (8)
Updated: Sep 15, 2011

名前

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コールとは異なります。libunboundでは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。
get_option opt
オプションの値を得ます。’:'なしでオプション名を与えます。その値が出力されます。値が”"であれば、何も出力されず、接続は閉じます。エラー時には、’error …’が出力されます（見知らぬオプションによる文法エラーを与えます）。オプションによっては、各行に一つずつのような値の一覧が出力されます。そのオプションはset_optionで修正された設定ファイルから見えます。For some options an override may have been taken that does not show up with this command, not results from e.g. the verbosity and forward control commands. Not all options work, see list_stubs, list_forwards, list_local_zones and list_local_data for those.
list_stubs
利用中のスタブ ゾーンの一覧を表示します。出力に1つずつ表示されます。これには利用中のルート ヒントも含まれます。
list_forwards
利用中のフォワード ゾーンの一覧を表示します。出力にゾーン毎に表示されます。
list_local_zones
利用中のローカル ゾーンの一覧を表示します。ゾーン タイプと共に行毎に一つづつ表示されます。
list_local_data
利用中のローカル データのリソース レコードの一覧を表示します。そのリソース レコードが表示されます。
forward [off | addr ... ]
フォワードのモードを設定します。サーバが他の上流のネームサーバに尋ねるべきかを設定します。インターネット ルート ネームサーバ自身に行くべきか、あるいは現在の設定を見せます。DHCP更新の後にネームサーバを渡すことができます。
引数が無い場合には、すべてのクエリーをフォワードするために使われている現在のアドレスの一覧が表示されます。起動時にはforward-zoneは”.”です。その後、状態を見せます。フォワードが使われていなければ、出力しません。
offが渡されたら、フォワードは無効にされ、ルート ネームサーバが使われます。これはバギーなネームサーバやDHCPから返されたDNSSECをサポートしていないネームサーバを避けるために使うこともできます。しかし、ホテルやホットスポットでは働かないかもしれません。
一つ以上のIPv4やIPv6のアドレスが渡されたら、クエリーをフォワードするのに使われます。このとき、アドレスはスペース区切りです。’@port’でポート番号が正しく設定されます（デフォルトのポートは53（DNS）です。）
デフォルトでは、ルート”.”のためには、設定ファイルからのフォワーダーの情報が使われます。設定ファイルは変更されません。そのため、リロード後にこれらの変更は消えます。設定ファイルでの他のフォワード ゾーンはこのコマンドにより影響を受けません。

終了コード

unbound-controlプログラムは、エラーのときにはステータスコード1で、成功のときにはステータスコード0で終了します。

セットアップ

セットアップはサーバとクライアントの両方に自己署名証明書と秘密鍵を要求します。スクリプトunbound-control-setupはデフォルトの実行ディレクトリ、あるいは-dで指定した別のディレクトリにそれらを生成します。鍵ファイルへのアクセス制御の権限を変更すれば、全てのユーザではなくデフォルトの所有者とグループによりunbound-controlを誰が使うかをきめることができます。Run the script under the same username as you have configured in unbound.conf or as root, so that the daemon is permitted to read the files, for example with:

    sudo -u unbound unbound-control-setup

If you have not configured a username in unbound.conf, the keys need read permission for the user credentials under which the daemon is started. The script preserves private keys present in the directory. After running the script as root, turn on control-enable in unbound.conf.

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).