diff options
Diffstat (limited to 'bin/rndc/rndc.conf.docbook')
| -rw-r--r-- | bin/rndc/rndc.conf.docbook | 262 |
1 files changed, 144 insertions, 118 deletions
diff --git a/bin/rndc/rndc.conf.docbook b/bin/rndc/rndc.conf.docbook index 16b9caf4..38e7eb5e 100644 --- a/bin/rndc/rndc.conf.docbook +++ b/bin/rndc/rndc.conf.docbook @@ -18,9 +18,8 @@ - PERFORMANCE OF THIS SOFTWARE. --> -<!-- $Id: rndc.conf.docbook,v 1.4.206.4 2005/05/12 21:36:04 sra Exp $ --> - -<refentry> +<!-- $Id: rndc.conf.docbook,v 1.5.18.7 2005/07/19 05:55:43 marka Exp $ --> +<refentry id="man.rndc.conf"> <refentryinfo> <date>June 30, 2000</date> </refentryinfo> @@ -31,6 +30,11 @@ <refmiscinfo>BIND9</refmiscinfo> </refmeta> + <refnamediv> + <refname><filename>rndc.conf</filename></refname> + <refpurpose>rndc configuration file</refpurpose> + </refnamediv> + <docinfo> <copyright> <year>2004</year> @@ -44,11 +48,6 @@ </copyright> </docinfo> - <refnamediv> - <refname><filename>rndc.conf</filename></refname> - <refpurpose>rndc configuration file</refpurpose> - </refnamediv> - <refsynopsisdiv> <cmdsynopsis> <command>rndc.conf</command> @@ -57,152 +56,183 @@ <refsect1> <title>DESCRIPTION</title> - <para> - <filename>rndc.conf</filename> is the configuration file - for <command>rndc</command>, the BIND 9 name server control - utility. This file has a similar structure and syntax to - <filename>named.conf</filename>. Statements are enclosed - in braces and terminated with a semi-colon. Clauses in - the statements are also semi-colon terminated. The usual - comment styles are supported: - </para> - <para> - C style: /* */ - </para> - <para> - C++ style: // to end of line - </para> - <para> - Unix style: # to end of line - </para> - <para> - <filename>rndc.conf</filename> is much simpler than - <filename>named.conf</filename>. The file uses three - statements: an options statement, a server statement - and a key statement. - </para> - <para> - The <option>options</option> statement contains three clauses. - The <option>default-server</option> clause is followed by the - name or address of a name server. This host will be used when - no name server is given as an argument to - <command>rndc</command>. The <option>default-key</option> - clause is followed by the name of a key which is identified by - a <option>key</option> statement. If no - <option>keyid</option> is provided on the rndc command line, - and no <option>key</option> clause is found in a matching - <option>server</option> statement, this default key will be - used to authenticate the server's commands and responses. The - <option>default-port</option> clause is followed by the port - to connect to on the remote name server. If no - <option>port</option> option is provided on the rndc command - line, and no <option>port</option> clause is found in a - matching <option>server</option> statement, this default port - will be used to connect. - </para> - <para> - After the <option>server</option> keyword, the server statement - includes a string which is the hostname or address for a name - server. The statement has two possible clauses: - <option>key</option> and <option>port</option>. The key name must - match the name of a key statement in the file. The port number - specifies the port to connect to. - </para> - <para> - The <option>key</option> statement begins with an identifying - string, the name of the key. The statement has two clauses. - <option>algorithm</option> identifies the encryption algorithm - for <command>rndc</command> to use; currently only HMAC-MD5 is - supported. This is followed by a secret clause which contains - the base-64 encoding of the algorithm's encryption key. The - base-64 string is enclosed in double quotes. - </para> - <para> - There are two common ways to generate the base-64 string for the - secret. The BIND 9 program <command>rndc-confgen</command> can - be used to generate a random key, or the - <command>mmencode</command> program, also known as - <command>mimencode</command>, can be used to generate a base-64 - string from known input. <command>mmencode</command> does not - ship with BIND 9 but is available on many systems. See the - EXAMPLE section for sample command lines for each. + <para><filename>rndc.conf</filename> is the configuration file + for <command>rndc</command>, the BIND 9 name server control + utility. This file has a similar structure and syntax to + <filename>named.conf</filename>. Statements are enclosed + in braces and terminated with a semi-colon. Clauses in + the statements are also semi-colon terminated. The usual + comment styles are supported: + </para> + <para> + C style: /* */ + </para> + <para> + C++ style: // to end of line + </para> + <para> + Unix style: # to end of line + </para> + <para><filename>rndc.conf</filename> is much simpler than + <filename>named.conf</filename>. The file uses three + statements: an options statement, a server statement + and a key statement. + </para> + <para> + The <option>options</option> statement contains five clauses. + The <option>default-server</option> clause is followed by the + name or address of a name server. This host will be used when + no name server is given as an argument to + <command>rndc</command>. The <option>default-key</option> + clause is followed by the name of a key which is identified by + a <option>key</option> statement. If no + <option>keyid</option> is provided on the rndc command line, + and no <option>key</option> clause is found in a matching + <option>server</option> statement, this default key will be + used to authenticate the server's commands and responses. The + <option>default-port</option> clause is followed by the port + to connect to on the remote name server. If no + <option>port</option> option is provided on the rndc command + line, and no <option>port</option> clause is found in a + matching <option>server</option> statement, this default port + will be used to connect. + The <option>default-source-address</option> and + <option>default-source-address-v6</option> clauses which + can be used to set the IPv4 and IPv6 source addresses + respectively. + </para> + <para> + After the <option>server</option> keyword, the server + statement includes a string which is the hostname or address + for a name server. The statement has three possible clauses: + <option>key</option>, <option>port</option> and + <option>addresses</option>. The key name must match the + name of a key statement in the file. The port number + specifies the port to connect to. If an <option>addresses</option> + clause is supplied these addresses will be used instead of + the server name. Each address can take a optional port. + If an <option>source-address</option> or <option>source-address-v6</option> + of supplied then these will be used to specify the IPv4 and IPv6 + source addresses respectively. + </para> + <para> + The <option>key</option> statement begins with an identifying + string, the name of the key. The statement has two clauses. + <option>algorithm</option> identifies the encryption algorithm + for <command>rndc</command> to use; currently only HMAC-MD5 + is + supported. This is followed by a secret clause which contains + the base-64 encoding of the algorithm's encryption key. The + base-64 string is enclosed in double quotes. + </para> + <para> + There are two common ways to generate the base-64 string for the + secret. The BIND 9 program <command>rndc-confgen</command> + can + be used to generate a random key, or the + <command>mmencode</command> program, also known as + <command>mimencode</command>, can be used to generate a + base-64 + string from known input. <command>mmencode</command> does + not + ship with BIND 9 but is available on many systems. See the + EXAMPLE section for sample command lines for each. </para> </refsect1> <refsect1> <title>EXAMPLE</title> - <programlisting> - options { + <para><programlisting> + options { default-server localhost; default-key samplekey; }; - +</programlisting> + </para> + <para><programlisting> server localhost { key samplekey; }; - +</programlisting> + </para> + <para><programlisting> + server testserver { + key testkey; + addresses { localhost port 5353; }; + }; +</programlisting> + </para> + <para><programlisting> key samplekey { algorithm hmac-md5; - secret "c3Ryb25nIGVub3VnaCBmb3IgYSBtYW4gYnV0IG1hZGUgZm9yIGEgd29tYW4K"; + secret "6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz"; }; +</programlisting> + </para> + <para><programlisting> + key testkey { + algorithm hmac-md5; + secret "R3HI8P6BKw9ZwXwN3VZKuQ=="; + } </programlisting> + </para> <para> - In the above example, <command>rndc</command> will by default use - the server at localhost (127.0.0.1) and the key called samplekey. - Commands to the localhost server will use the samplekey key, which - must also be defined in the server's configuration file with the - same name and secret. The key statement indicates that samplekey - uses the HMAC-MD5 algorithm and its secret clause contains the - base-64 encoding of the HMAC-MD5 secret enclosed in double quotes. + In the above example, <command>rndc</command> will by + default use + the server at localhost (127.0.0.1) and the key called samplekey. + Commands to the localhost server will use the samplekey key, which + must also be defined in the server's configuration file with the + same name and secret. The key statement indicates that samplekey + uses the HMAC-MD5 algorithm and its secret clause contains the + base-64 encoding of the HMAC-MD5 secret enclosed in double quotes. </para> <para> - To generate a random secret with <command>rndc-confgen</command>: + If <command>rndc -s testserver</command> is used then <command>rndc</command> will + connect to server on localhost port 5353 using the key testkey. </para> <para> - <userinput>rndc-confgen</userinput> + To generate a random secret with <command>rndc-confgen</command>: </para> - <para> - A complete <filename>rndc.conf</filename> file, including the - randomly generated key, will be written to the standard - output. Commented out <option>key</option> and - <option>controls</option> statements for - <filename>named.conf</filename> are also printed. + <para><userinput>rndc-confgen</userinput> </para> <para> - To generate a base-64 secret with <command>mmencode</command>: + A complete <filename>rndc.conf</filename> file, including + the + randomly generated key, will be written to the standard + output. Commented out <option>key</option> and + <option>controls</option> statements for + <filename>named.conf</filename> are also printed. </para> <para> - <userinput>echo "known plaintext for a secret" | mmencode</userinput> + To generate a base-64 secret with <command>mmencode</command>: + </para> + <para><userinput>echo "known plaintext for a secret" | mmencode</userinput> </para> </refsect1> <refsect1> <title>NAME SERVER CONFIGURATION</title> <para> - The name server must be configured to accept rndc connections and - to recognize the key specified in the <filename>rndc.conf</filename> - file, using the controls statement in <filename>named.conf</filename>. - See the sections on the <option>controls</option> statement in the - BIND 9 Administrator Reference Manual for details. + The name server must be configured to accept rndc connections and + to recognize the key specified in the <filename>rndc.conf</filename> + file, using the controls statement in <filename>named.conf</filename>. + See the sections on the <option>controls</option> statement in the + BIND 9 Administrator Reference Manual for details. </para> </refsect1> <refsect1> <title>SEE ALSO</title> - <para> - <citerefentry> - <refentrytitle>rndc</refentrytitle> - <manvolnum>8</manvolnum> + <para><citerefentry> + <refentrytitle>rndc</refentrytitle><manvolnum>8</manvolnum> </citerefentry>, <citerefentry> - <refentrytitle>rndc-confgen</refentrytitle> - <manvolnum>8</manvolnum> + <refentrytitle>rndc-confgen</refentrytitle><manvolnum>8</manvolnum> </citerefentry>, <citerefentry> - <refentrytitle>mmencode</refentrytitle> - <manvolnum>1</manvolnum> + <refentrytitle>mmencode</refentrytitle><manvolnum>1</manvolnum> </citerefentry>, <citetitle>BIND 9 Administrator Reference Manual</citetitle>. </para> @@ -210,16 +240,12 @@ <refsect1> <title>AUTHOR</title> - <para> - <corpauthor>Internet Systems Consortium</corpauthor> + <para><corpauthor>Internet Systems Consortium</corpauthor> </para> </refsect1> -</refentry> - -<!-- +</refentry><!-- - Local variables: - mode: sgml - End: --> - |