From: Evan Hunt Date: Mon, 10 Jun 2013 21:43:52 +0000 (-0700) Subject: [v9_9] move rndc command documentation to "man rndc" X-Git-Tag: v9.9.4b1~28 X-Git-Url: http://git.ipfire.org/gitweb/?a=commitdiff_plain;h=a7daffaf4eb40d6e7b60d2a399748dfbc6dd8322;p=thirdparty%2Fbind9.git [v9_9] move rndc command documentation to "man rndc" 3592. [doc] Moved documentation of rndc command options to the rndc man page. [RT #33506] (cherry picked from commit 1b2a4ce2b112ec91b0f13c411144e721c7952914) --- diff --git a/CHANGES b/CHANGES index 97f67d9cb03..c3cd483bdaa 100644 --- a/CHANGES +++ b/CHANGES @@ -1,3 +1,6 @@ +3592. [doc] Moved documentation of rndc command options to the + rndc man page. [RT #33506] + 3590. [bug] When using RRL on recursive servers, defer rate-limiting until after recursion is complete; also, use correct rcode for slipped NXDOMAIN diff --git a/bin/rndc/rndc.docbook b/bin/rndc/rndc.docbook index d407f2b515c..c3d4c4a8d9e 100644 --- a/bin/rndc/rndc.docbook +++ b/bin/rndc/rndc.docbook @@ -21,7 +21,7 @@ - June 30, 2000 + June 7, 2013 @@ -194,22 +194,499 @@ + + + COMMANDS + + A list of commands supported by rndc can + be seen by running rndc without arguments. + - For the complete set of commands supported by rndc, - see the BIND 9 Administrator Reference Manual or run - rndc without arguments to see its help - message. + Currently supported commands are: + + + reload + + + Reload configuration file and zones. + + + + + + reload zone class view + + + Reload the given zone. + + + + + + refresh zone class view + + + Schedule zone maintenance for the given zone. + + + + + + retransfer zone class view + + + Retransfer the given zone from the master. + + + + + + sign zone class view + + + Fetch all DNSSEC keys for the given zone + from the key directory (see the + key-directory option in + the BIND 9 Administrator Reference Manual). If they are within + their publication period, merge them into the + zone's DNSKEY RRset. If the DNSKEY RRset + is changed, then the zone is automatically + re-signed with the new key set. + + + This command requires that the + auto-dnssec zone option be set + to allow or + maintain, + and also requires the zone to be configured to + allow dynamic DNS. + (See "Dynamic Update Policies" in the Administrator + Reference Manual for more details.) + + + + + + loadkeys zone class view + + + Fetch all DNSSEC keys for the given zone + from the key directory. If they are within + their publication period, merge them into the + zone's DNSKEY RRset. Unlike rndc + sign, however, the zone is not + immediately re-signed by the new keys, but is + allowed to incrementally re-sign over time. + + + This command requires that the + auto-dnssec zone option + be set to maintain, + and also requires the zone to be configured to + allow dynamic DNS. + (See "Dynamic Update Policies" in the Administrator + Reference Manual for more details.) + + + + + + freeze zone class view + + + Suspend updates to a dynamic zone. If no zone is + specified, then all zones are suspended. This allows + manual edits to be made to a zone normally updated by + dynamic update. It also causes changes in the + journal file to be synced into the master file. + All dynamic update attempts will be refused while + the zone is frozen. + + + + + + thaw zone class view + + + Enable updates to a frozen dynamic zone. If no + zone is specified, then all frozen zones are + enabled. This causes the server to reload the zone + from disk, and re-enables dynamic updates after the + load has completed. After a zone is thawed, + dynamic updates will no longer be refused. If + the zone has changed and the + ixfr-from-differences option is + in use, then the journal file will be updated to + reflect changes in the zone. Otherwise, if the + zone has changed, any existing journal file will be + removed. + + + + + + sync -clean zone class view + + + Sync changes in the journal file for a dynamic zone + to the master file. If the "-clean" option is + specified, the journal file is also removed. If + no zone is specified, then all zones are synced. + + + + + + notify zone class view + + + Resend NOTIFY messages for the zone. + + + + + + reconfig + + + Reload the configuration file and load new zones, + but do not reload existing zone files even if they + have changed. + This is faster than a full reload when there + is a large number of zones because it avoids the need + to examine the + modification times of the zones files. + + + + + + stats + + + Write server statistics to the statistics file. + + + + + + querylog on|off + + + Enable or disable query logging. (For backward + compatibility, this command can also be used without + an argument to toggle query logging on and off.) + + + Query logging can also be enabled + by explicitly directing the queries + category to a + channel in the + logging section of + named.conf or by specifying + querylog yes; in the + options section of + named.conf. + + + + + + dumpdb -all|-cache|-zone view ... + + + Dump the server's caches (default) and/or zones to + the + dump file for the specified views. If no view is + specified, all + views are dumped. + + + + + + secroots view ... + + + Dump the server's security roots to the secroots + file for the specified views. If no view is + specified, security roots for all + views are dumped. + + + + + + stop -p + + + Stop the server, making sure any recent changes + made through dynamic update or IXFR are first saved to + the master files of the updated zones. + If is specified named's process id is returned. + This allows an external process to determine when named + had completed stopping. + + + + + + halt -p + + + Stop the server immediately. Recent changes + made through dynamic update or IXFR are not saved to + the master files, but will be rolled forward from the + journal files when the server is restarted. + If is specified named's process id is returned. + This allows an external process to determine when named + had completed halting. + + + + + + trace + + + Increment the servers debugging level by one. + + + + + + trace level + + + Sets the server's debugging level to an explicit + value. + + + + + + notrace + + + Sets the server's debugging level to 0. + + + + + + flush + + + Flushes the server's cache. + + + + + + flushname name view + + + Flushes the given name from the server's DNS cache + and, if applicable, from the server's nameserver address + database or bad-server cache. + + + + + + flushtree name view + + + Flushes the given name, and all of its subdomains, + from the server's DNS cache. Note that this does + not affect he server's address + database or bad-server cache. + + + + + + status + + + Display status of the server. + Note that the number of zones includes the internal bind/CH zone + and the default ./IN + hint zone if there is not an + explicit root zone configured. + + + + + + recursing + + + Dump the list of queries named is currently recursing + on. + + + + + + validation ( on | off | check ) view ... + + + Enable, disable, or check the current status of + DNSSEC validation. + Note dnssec-enable also needs to be + set to yes or + auto to be effective. + It defaults to enabled. + + + + + + tsig-list + + + List the names of all TSIG keys currently configured + for use by named in each view. The + list both statically configured keys and dynamic + TKEY-negotiated keys. + + + + + + tsig-delete keyname view + + + Delete a given TKEY-negotiated key from the server. + (This does not apply to statically configured TSIG + keys.) + + + + + + addzone zone class view configuration + + + Add a zone while the server is running. This + command requires the + allow-new-zones option to be set + to yes. The + configuration string + specified on the command line is the zone + configuration text that would ordinarily be + placed in named.conf. + + + The configuration is saved in a file called + hash.nzf, + where hash is a + cryptographic hash generated from the name of + the view. When named is + restarted, the file will be loaded into the view + configuration, so that zones that were added + can persist after a restart. + + + This sample addzone command + would add the zone example.com + to the default view: + + +$ rndc addzone example.com '{ type master; file "example.com.db"; };' + + + (Note the brackets and semi-colon around the zone + configuration text.) + + + + + + delzone zone class view + + + Delete a zone while the server is running. + Only zones that were originally added via + rndc addzone can be deleted + in this manner. + + + + + + signing ( -list | -clear keyid/algorithm | -clear all | -nsec3param ( parameters | none ) ) zone class view + + + List, edit, or remove the DNSSEC signing state for + the specified zone. The status of ongoing DNSSEC + operations (such as signing or generating + NSEC3 chains) is stored in the zone in the form + of DNS resource records of type + sig-signing-type. + rndc signing -list converts + these records into a human-readable form, + indicating which keys are currently signing + or have finished signing the zone, and which NSEC3 + chains are being created or removed. + + + rndc signing -clear can remove + a single key (specified in the same format that + rndc signing -list uses to + display it), or all keys. In either case, only + completed keys are removed; any record indicating + that a key has not yet finished signing the zone + will be retained. + + + rndc signing -nsec3param sets + the NSEC3 parameters for a zone. This is the + only supported mechanism for using NSEC3 with + inline-signing zones. + Parameters are specified in the same format as + an NSEC3PARAM resource record: hash algorithm, + flags, iterations, and salt, in that order. + + + Currently, the only defined value for hash algorithm + is 1, representing SHA-1. + The may be set to + 0 or 1, + depending on whether you wish to set the opt-out + bit in the NSEC3 chain. + defines the number of additional times to apply + the algorithm when generating an NSEC3 hash. The + is a string of data expressed + in hexidecimal, or a hyphen (`-') if no salt is + to be used. + + + So, for example, to create an NSEC3 chain using + the SHA-1 hash algorithm, no opt-out flag, + 10 iterations, and a salt value of "FFFF", use: + rndc signing -nsec3param 1 0 10 FFFF zone. + To set the opt-out flag, 15 iterations, and no + salt, use: + rndc signing -nsec3param 1 1 15 - zone. + + + rndc signing -nsec3param none + removes an existing NSEC3 chain and replaces it + with NSEC. + + + + LIMITATIONS - rndc - does not yet support all the commands of - the BIND 8 ndc utility. - There is currently no way to provide the shared secret for a without using the configuration file. diff --git a/doc/arm/Bv9ARM-book.xml b/doc/arm/Bv9ARM-book.xml index 679b16d16c5..27a7befe3b6 100644 --- a/doc/arm/Bv9ARM-book.xml +++ b/doc/arm/Bv9ARM-book.xml @@ -1124,544 +1124,14 @@ zone "eng.example.com" { command command - The command - is one of the following: - - - - - - reload - - - Reload configuration file and zones. - - - - - - reload zone - class - view - - - Reload the given zone. - - - - - - refresh zone - class - view - - - Schedule zone maintenance for the given zone. - - - - - - retransfer zone - - class - view - - - Retransfer the given zone from the master. - - - - - - sign zone - class - view - - - Fetch all DNSSEC keys for the given zone - from the key directory (see - key-directory in - ). If they are within - their publication period, merge them into the - zone's DNSKEY RRset. If the DNSKEY RRset - is changed, then the zone is automatically - re-signed with the new key set. - - - This command requires that the - auto-dnssec zone option be set - to allow or - maintain, - and also requires the zone to be configured to - allow dynamic DNS. - See for - more details. - - - - - - loadkeys zone - class - view - - - Fetch all DNSSEC keys for the given zone - from the key directory (see - key-directory in - ). If they are within - their publication period, merge them into the - zone's DNSKEY RRset. Unlike rndc - sign, however, the zone is not - immediately re-signed by the new keys, but is - allowed to incrementally re-sign over time. - - - This command requires that the - auto-dnssec zone option - be set to maintain, - and also requires the zone to be configured to - allow dynamic DNS. - See for - more details. - - - - - - freeze - zone - class - view - - - Suspend updates to a dynamic zone. If no zone is - specified, then all zones are suspended. This allows - manual edits to be made to a zone normally updated by - dynamic update. It also causes changes in the - journal file to be synced into the master file. - All dynamic update attempts will be refused while - the zone is frozen. - - - - - - thaw - zone - class - view - - - Enable updates to a frozen dynamic zone. If no - zone is specified, then all frozen zones are - enabled. This causes the server to reload the zone - from disk, and re-enables dynamic updates after the - load has completed. After a zone is thawed, - dynamic updates will no longer be refused. If - the zone has changed and the - ixfr-from-differences option is - in use, then the journal file will be updated to - reflect changes in the zone. Otherwise, if the - zone has changed, any existing journal file will be - removed. - - - - - - sync - -clean - zone - class - view - - - Sync changes in the journal file for a dynamic zone - to the master file. If the "-clean" option is - specified, the journal file is also removed. If - no zone is specified, then all zones are synced. - - - - - - notify zone - class - view - - - Resend NOTIFY messages for the zone. - - - - - - reconfig - - - Reload the configuration file and load new zones, - but do not reload existing zone files even if they - have changed. - This is faster than a full reload when there - is a large number of zones because it avoids the need - to examine the - modification times of the zones files. - - - - - - stats - - - Write server statistics to the statistics file. - - - - - - querylog - on|off - - - - Enable or disable query logging. (For backward - compatibility, this command can also be used without - an argument to toggle query logging on and off.) - - - Query logging can also be enabled - by explicitly directing the queries - category to a - channel in the - logging section of - named.conf or by specifying - querylog yes; in the - options section of - named.conf. - - - - - - dumpdb - -all|-cache|-zone - view ... - - - Dump the server's caches (default) and/or zones to - the - dump file for the specified views. If no view is - specified, all - views are dumped. - - - - - - secroots - view ... - - - Dump the server's security roots to the secroots - file for the specified views. If no view is - specified, security roots for all - views are dumped. - - - - - - stop -p - - - Stop the server, making sure any recent changes - made through dynamic update or IXFR are first saved to - the master files of the updated zones. - If is specified named's process id is returned. - This allows an external process to determine when named - had completed stopping. - - - - - - halt -p - - - Stop the server immediately. Recent changes - made through dynamic update or IXFR are not saved to - the master files, but will be rolled forward from the - journal files when the server is restarted. - If is specified named's process id is returned. - This allows an external process to determine when named - had completed halting. - - - - - - trace - - - Increment the servers debugging level by one. - - - - - - trace level - - - Sets the server's debugging level to an explicit - value. - - - - - - notrace - - - Sets the server's debugging level to 0. - - - - - - flush - - - Flushes the server's cache. - - - - - - flushname - name - view - - - - Flushes the given name from the server's DNS cache, - and from the server's nameserver address database - if applicable. - - - - - - flushtree - name - view - - - - Flushes the given name, and all of its subdomains, - from the server's DNS cache. (The server's - nameserver address database is not affected.) - - - - - - status - - - Display status of the server. - Note that the number of zones includes the internal bind/CH zone - and the default ./IN - hint zone if there is not an - explicit root zone configured. - - - - - - recursing - - - Dump the list of queries named is currently recursing - on. - - - - - - validation - on|off - view ... - - - - Enable or disable DNSSEC validation. - Note dnssec-enable also needs to be - set to yes to be effective. - It defaults to enabled. - - - - - - tsig-list - - - List the names of all TSIG keys currently configured - for use by named in each view. The - list both statically configured keys and dynamic - TKEY-negotiated keys. - - - - - - tsig-delete - keyname - view - - - Delete a given TKEY-negotiated key from the server. - (This does not apply to statically configured TSIG - keys.) - - - - - - addzone - zone - class - view - configuration - - - - Add a zone while the server is running. This - command requires the - allow-new-zones option to be set - to yes. The - configuration string - specified on the command line is the zone - configuration text that would ordinarily be - placed in named.conf. - - - The configuration is saved in a file called - hash.nzf, - where hash is a - cryptographic hash generated from the name of - the view. When named is - restarted, the file will be loaded into the view - configuration, so that zones that were added - can persist after a restart. - - - This sample addzone command - would add the zone example.com - to the default view: - - -$ rndc addzone example.com '{ type master; file "example.com.db"; };' - - - (Note the brackets and semi-colon around the zone - configuration text.) - - - - - - delzone - zone - class - view - - - - Delete a zone while the server is running. - Only zones that were originally added via - rndc addzone can be deleted - in this matter. - - - - - - signing - ( -list | -clear keyid/algorithm | -clear all | -nsec3param ( parameters | none ) ) - zone - class - view - - - - List, edit, or remove the DNSSEC signing state for - the specified zone. The status of ongoing DNSSEC - operations (such as signing or generating - NSEC3 chains) is stored in the zone in the form - of DNS resource records of type - sig-signing-type. - rndc signing -list converts - these records into a human-readable form, - indicating which keys are currently signing - or have finished signing the zone, and which NSEC3 - NSEC3 chains are being created or removed. - - - rndc signing -clear can remove - a single key (specified in the same format that - rndc signing -list uses to - display it), or all keys. In either case, only - completed keys are removed; any record indicating - that a key has not yet finished signing the zone - will be retained. - - - rndc signing -nsec3param sets - the NSEC3 parameters for a zone. This is the - only supported mechanism for using NSEC3 with - inline-signing zones. - Parameters are specified in the same format as - an NSEC3PARAM resource record: hash algorithm, - flags, iterations, and salt, in that order. - - - Currently, the only defined value for hash algorithm - is 1, representing SHA-1. - The may be set to - 0 or 1, - depending on whether you wish to set the opt-out - bit in the NSEC3 chain. - defines the number of additional times to apply - the algorithm when generating an NSEC3 hash. The - is a string of data expressed - in hexidecimal, or a hyphen (`-') if no salt is - to be used. - - - So, for example, to create an NSEC3 chain using - the SHA-1 hash algorithm, no opt-out flag, - 10 iterations, and a salt value of "FFFF", use: - rndc signing -nsec3param 1 0 10 FFFF <zone>. - To set the opt-out flag, 15 iterations, and no - salt, use: - rndc signing -nsec3param 1 1 15 - <zone>. - - - rndc signing -nsec3param none - removes an existing NSEC3 chain and replaces it - with NSEC. - - - - + See for details of + the available rndc commands. + - A configuration file is required, since all + rndc requires a configuration file, + since all communication with the server is authenticated with digital signatures that rely on a shared secret, and there is no way to provide that secret other than with a