diff options
Diffstat (limited to 'bin/rndc/rndc.docbook')
| -rw-r--r-- | bin/rndc/rndc.docbook | 506 |
1 files changed, 496 insertions, 10 deletions
diff --git a/bin/rndc/rndc.docbook b/bin/rndc/rndc.docbook index d407f2b515cbe..2b91d2d57accf 100644 --- a/bin/rndc/rndc.docbook +++ b/bin/rndc/rndc.docbook @@ -2,7 +2,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY mdash "—">]> <!-- - - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2004, 2005, 2007, 2013 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2000, 2001 Internet Software Consortium. - - Permission to use, copy, modify, and/or distribute this software for any @@ -21,7 +21,7 @@ <!-- $Id: rndc.docbook,v 1.21 2007/12/14 20:39:14 marka Exp $ --> <refentry id="man.rndc"> <refentryinfo> - <date>June 30, 2000</date> + <date>June 7, 2013</date> </refentryinfo> <refmeta> @@ -40,6 +40,7 @@ <year>2004</year> <year>2005</year> <year>2007</year> + <year>2013</year> <holder>Internet Systems Consortium, Inc. ("ISC")</holder> </copyright> <copyright> @@ -194,22 +195,507 @@ </varlistentry> </variablelist> + </refsect1> + <refsect1> + <title>COMMANDS</title> + <para> + A list of commands supported by <command>rndc</command> can + be seen by running <command>rndc</command> without arguments. + </para> <para> - For the complete set of commands supported by <command>rndc</command>, - see the BIND 9 Administrator Reference Manual or run - <command>rndc</command> without arguments to see its help - message. + Currently supported commands are: </para> + <variablelist> + <varlistentry> + <term><userinput>reload</userinput></term> + <listitem> + <para> + Reload configuration file and zones. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>reload <replaceable>zone</replaceable> <optional><replaceable>class</replaceable> <optional><replaceable>view</replaceable></optional></optional></userinput></term> + <listitem> + <para> + Reload the given zone. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>refresh <replaceable>zone</replaceable> <optional><replaceable>class</replaceable> <optional><replaceable>view</replaceable></optional></optional></userinput></term> + <listitem> + <para> + Schedule zone maintenance for the given zone. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>retransfer <replaceable>zone</replaceable> <optional><replaceable>class</replaceable> <optional><replaceable>view</replaceable></optional></optional></userinput></term> + <listitem> + <para> + Retransfer the given slave zone from the master server. + </para> + <para> + If the zone is configured to use + <command>inline-signing</command>, the signed + version of the zone is discarded; after the + retransfer of the unsigned version is complete, the + signed version will be regenerated with all new + signatures. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>sign <replaceable>zone</replaceable> <optional><replaceable>class</replaceable> <optional><replaceable>view</replaceable></optional></optional></userinput></term> + <listitem> + <para> + Fetch all DNSSEC keys for the given zone + from the key directory (see the + <command>key-directory</command> 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. + </para> + <para> + This command requires that the + <command>auto-dnssec</command> zone option be set + to <literal>allow</literal> or + <literal>maintain</literal>, + and also requires the zone to be configured to + allow dynamic DNS. + (See "Dynamic Update Policies" in the Administrator + Reference Manual for more details.) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>loadkeys <replaceable>zone</replaceable> <optional><replaceable>class</replaceable> <optional><replaceable>view</replaceable></optional></optional></userinput></term> + <listitem> + <para> + 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 <command>rndc + sign</command>, however, the zone is not + immediately re-signed by the new keys, but is + allowed to incrementally re-sign over time. + </para> + <para> + This command requires that the + <command>auto-dnssec</command> zone option + be set to <literal>maintain</literal>, + and also requires the zone to be configured to + allow dynamic DNS. + (See "Dynamic Update Policies" in the Administrator + Reference Manual for more details.) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>freeze <optional><replaceable>zone</replaceable> <optional><replaceable>class</replaceable> <optional><replaceable>view</replaceable></optional></optional></optional></userinput></term> + <listitem> + <para> + 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. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>thaw <optional><replaceable>zone</replaceable> <optional><replaceable>class</replaceable> <optional><replaceable>view</replaceable></optional></optional></optional></userinput></term> + <listitem> + <para> + 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 + <command>ixfr-from-differences</command> 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. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>sync <optional>-clean</optional> <optional><replaceable>zone</replaceable> <optional><replaceable>class</replaceable> <optional><replaceable>view</replaceable></optional></optional></optional></userinput></term> + <listitem> + <para> + 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. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>notify <replaceable>zone</replaceable> <optional><replaceable>class</replaceable> <optional><replaceable>view</replaceable></optional></optional></userinput></term> + <listitem> + <para> + Resend NOTIFY messages for the zone. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>reconfig</userinput></term> + <listitem> + <para> + 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 <command>reload</command> when there + is a large number of zones because it avoids the need + to examine the + modification times of the zones files. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>stats</userinput></term> + <listitem> + <para> + Write server statistics to the statistics file. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>querylog</userinput> <optional>on|off</optional> </term> + <listitem> + <para> + Enable or disable query logging. (For backward + compatibility, this command can also be used without + an argument to toggle query logging on and off.) + </para> + <para> + Query logging can also be enabled + by explicitly directing the <command>queries</command> + <command>category</command> to a + <command>channel</command> in the + <command>logging</command> section of + <filename>named.conf</filename> or by specifying + <command>querylog yes;</command> in the + <command>options</command> section of + <filename>named.conf</filename>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>dumpdb <optional>-all|-cache|-zone</optional> <optional><replaceable>view ...</replaceable></optional></userinput></term> + <listitem> + <para> + 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. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>secroots <optional><replaceable>view ...</replaceable></optional></userinput></term> + <listitem> + <para> + 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. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>stop <optional>-p</optional></userinput></term> + <listitem> + <para> + 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 <option>-p</option> is specified <command>named</command>'s process id is returned. + This allows an external process to determine when <command>named</command> + had completed stopping. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>halt <optional>-p</optional></userinput></term> + <listitem> + <para> + 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 <option>-p</option> is specified <command>named</command>'s process id is returned. + This allows an external process to determine when <command>named</command> + had completed halting. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>trace</userinput></term> + <listitem> + <para> + Increment the servers debugging level by one. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>trace <replaceable>level</replaceable></userinput></term> + <listitem> + <para> + Sets the server's debugging level to an explicit + value. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>notrace</userinput></term> + <listitem> + <para> + Sets the server's debugging level to 0. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>flush</userinput></term> + <listitem> + <para> + Flushes the server's cache. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>flushname</userinput> <replaceable>name</replaceable> <optional><replaceable>view</replaceable></optional> </term> + <listitem> + <para> + Flushes the given name from the server's DNS cache + and, if applicable, from the server's nameserver address + database or bad-server cache. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>flushtree</userinput> <replaceable>name</replaceable> <optional><replaceable>view</replaceable></optional> </term> + <listitem> + <para> + Flushes the given name, and all of its subdomains, + from the server's DNS cache. Note that this does + <emphasis>not</emphasis> affect he server's address + database or bad-server cache. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>status</userinput></term> + <listitem> + <para> + Display status of the server. + Note that the number of zones includes the internal <command>bind/CH</command> zone + and the default <command>./IN</command> + hint zone if there is not an + explicit root zone configured. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>recursing</userinput></term> + <listitem> + <para> + Dump the list of queries <command>named</command> is currently recursing + on. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>validation ( on | off | check ) <optional><replaceable>view ...</replaceable></optional> </userinput></term> + <listitem> + <para> + Enable, disable, or check the current status of + DNSSEC validation. + Note <command>dnssec-enable</command> also needs to be + set to <userinput>yes</userinput> or + <userinput>auto</userinput> to be effective. + It defaults to enabled. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>tsig-list</userinput></term> + <listitem> + <para> + List the names of all TSIG keys currently configured + for use by <command>named</command> in each view. The + list both statically configured keys and dynamic + TKEY-negotiated keys. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>tsig-delete</userinput> <replaceable>keyname</replaceable> <optional><replaceable>view</replaceable></optional></term> + <listitem> + <para> + Delete a given TKEY-negotiated key from the server. + (This does not apply to statically configured TSIG + keys.) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>addzone <replaceable>zone</replaceable> <optional><replaceable>class</replaceable> <optional><replaceable>view</replaceable></optional></optional> <replaceable>configuration</replaceable> </userinput></term> + <listitem> + <para> + Add a zone while the server is running. This + command requires the + <command>allow-new-zones</command> option to be set + to <userinput>yes</userinput>. The + <replaceable>configuration</replaceable> string + specified on the command line is the zone + configuration text that would ordinarily be + placed in <filename>named.conf</filename>. + </para> + <para> + The configuration is saved in a file called + <filename><replaceable>hash</replaceable>.nzf</filename>, + where <replaceable>hash</replaceable> is a + cryptographic hash generated from the name of + the view. When <command>named</command> is + restarted, the file will be loaded into the view + configuration, so that zones that were added + can persist after a restart. + </para> + <para> + This sample <command>addzone</command> command + would add the zone <literal>example.com</literal> + to the default view: + </para> + <para> +<prompt>$ </prompt><userinput>rndc addzone example.com '{ type master; file "example.com.db"; };'</userinput> + </para> + <para> + (Note the brackets and semi-colon around the zone + configuration text.) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>delzone <replaceable>zone</replaceable> <optional><replaceable>class</replaceable> <optional><replaceable>view</replaceable></optional></optional> </userinput></term> + <listitem> + <para> + Delete a zone while the server is running. + Only zones that were originally added via + <command>rndc addzone</command> can be deleted + in this manner. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>signing <optional>( -list | -clear <replaceable>keyid/algorithm</replaceable> | -clear <literal>all</literal> | -nsec3param ( <replaceable>parameters</replaceable> | <literal>none</literal> ) ) </optional> <replaceable>zone</replaceable> <optional><replaceable>class</replaceable> <optional><replaceable>view</replaceable></optional></optional> </userinput></term> + <listitem> + <para> + 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 + <command>sig-signing-type</command>. + <command>rndc signing -list</command> 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. + </para> + <para> + <command>rndc signing -clear</command> can remove + a single key (specified in the same format that + <command>rndc signing -list</command> 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. + </para> + <para> + <command>rndc signing -nsec3param</command> sets + the NSEC3 parameters for a zone. This is the + only supported mechanism for using NSEC3 with + <command>inline-signing</command> zones. + Parameters are specified in the same format as + an NSEC3PARAM resource record: hash algorithm, + flags, iterations, and salt, in that order. + </para> + <para> + Currently, the only defined value for hash algorithm + is <literal>1</literal>, representing SHA-1. + The <option>flags</option> may be set to + <literal>0</literal> or <literal>1</literal>, + depending on whether you wish to set the opt-out + bit in the NSEC3 chain. <option>iterations</option> + defines the number of additional times to apply + the algorithm when generating an NSEC3 hash. The + <option>salt</option> is a string of data expressed + in hexadecimal, or a hyphen (`-') if no salt is + to be used. + </para> + <para> + 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: + <command>rndc signing -nsec3param 1 0 10 FFFF <replaceable>zone</replaceable></command>. + To set the opt-out flag, 15 iterations, and no + salt, use: + <command>rndc signing -nsec3param 1 1 15 - <replaceable>zone</replaceable></command>. + </para> + <para> + <command>rndc signing -nsec3param none</command> + removes an existing NSEC3 chain and replaces it + with NSEC. + </para> + </listitem> + </varlistentry> + </variablelist> </refsect1> <refsect1> <title>LIMITATIONS</title> - <para><command>rndc</command> - does not yet support all the commands of - the BIND 8 <command>ndc</command> utility. - </para> <para> There is currently no way to provide the shared secret for a <option>key_id</option> without using the configuration file. |