]> CyberLeo.Net >> Repos - FreeBSD/FreeBSD.git/blob - contrib/bind9/bin/rndc/rndc.docbook
This commit was generated by cvs2svn to compensate for changes in r169962,
[FreeBSD/FreeBSD.git] / contrib / bind9 / bin / rndc / rndc.docbook
1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
2                "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
3                [<!ENTITY mdash "&#8212;">]>
4 <!--
5  - Copyright (C) 2004, 2005  Internet Systems Consortium, Inc. ("ISC")
6  - Copyright (C) 2000, 2001  Internet Software Consortium.
7  -
8  - Permission to use, copy, modify, and distribute this software for any
9  - purpose with or without fee is hereby granted, provided that the above
10  - copyright notice and this permission notice appear in all copies.
11  -
12  - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
13  - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
14  - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
15  - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
16  - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
17  - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
18  - PERFORMANCE OF THIS SOFTWARE.
19 -->
20
21 <!-- $Id: rndc.docbook,v 1.7.206.4 2005/05/12 21:36:05 sra Exp $ -->
22
23 <refentry>
24   <refentryinfo>
25     <date>June 30, 2000</date>
26   </refentryinfo>
27
28   <refmeta>
29     <refentrytitle><application>rndc</application></refentrytitle>
30     <manvolnum>8</manvolnum>
31     <refmiscinfo>BIND9</refmiscinfo>
32   </refmeta>
33
34   <docinfo>
35     <copyright>
36       <year>2004</year>
37       <year>2005</year>
38       <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
39     </copyright>
40     <copyright>
41       <year>2000</year>
42       <year>2001</year>
43       <holder>Internet Software Consortium.</holder>
44     </copyright>
45   </docinfo>
46
47   <refnamediv>
48     <refname><application>rndc</application></refname>
49     <refpurpose>name server control utility</refpurpose>
50   </refnamediv>
51
52   <refsynopsisdiv>
53     <cmdsynopsis>
54       <command>rndc</command>
55       <arg><option>-c <replaceable class="parameter">config-file</replaceable></option></arg>
56       <arg><option>-k <replaceable class="parameter">key-file</replaceable></option></arg>
57       <arg><option>-s <replaceable class="parameter">server</replaceable></option></arg>
58       <arg><option>-p <replaceable class="parameter">port</replaceable></option></arg>
59       <arg><option>-V</option></arg>
60       <arg><option>-y <replaceable class="parameter">key_id</replaceable></option></arg>
61       <arg choice="req">command</arg>
62     </cmdsynopsis>
63   </refsynopsisdiv>
64
65   <refsect1>
66     <title>DESCRIPTION</title>
67     <para>
68         <command>rndc</command> controls the operation of a name
69         server.  It supersedes the <command>ndc</command> utility
70         that was provided in old BIND releases.  If
71         <command>rndc</command> is invoked with no command line
72         options or arguments, it prints a short summary of the
73         supported commands and the available options and their
74         arguments.
75     </para>
76     <para>
77         <command>rndc</command> communicates with the name server
78         over a TCP connection, sending commands authenticated with
79         digital signatures.  In the current versions of
80         <command>rndc</command> and <command>named</command> named
81         the only supported authentication algorithm is HMAC-MD5,
82         which uses a shared secret on each end of the connection.
83         This provides TSIG-style authentication for the command
84         request and the name server's response.  All commands sent
85         over the channel must be signed by a key_id known to the
86         server.
87     </para>
88     <para>
89         <command>rndc</command> reads a configuration file to
90         determine how to contact the name server and decide what
91         algorithm and key it should use.
92     </para>
93   </refsect1>
94
95   <refsect1>
96     <title>OPTIONS</title>
97
98     <variablelist>
99       <varlistentry>
100         <term>-c <replaceable class="parameter">config-file</replaceable></term>
101         <listitem>
102           <para>
103               Use <replaceable class="parameter">config-file</replaceable>
104               as the configuration file instead of the default,
105               <filename>/etc/rndc.conf</filename>.
106           </para>
107         </listitem>
108       </varlistentry>
109
110       <varlistentry>
111         <term>-k <replaceable class="parameter">key-file</replaceable></term>
112         <listitem>
113           <para>
114               Use <replaceable class="parameter">key-file</replaceable>
115               as the key file instead of the default,
116               <filename>/etc/rndc.key</filename>.  The key in
117               <filename>/etc/rndc.key</filename> will be used to authenticate
118               commands sent to the server if the <replaceable class="parameter">config-file</replaceable>
119               does not exist.
120           </para>
121         </listitem>
122       </varlistentry>
123
124       <varlistentry>
125         <term>-s <replaceable class="parameter">server</replaceable></term>
126         <listitem>
127           <para>
128                <replaceable class="parameter">server</replaceable> is
129                the name or address of the server which matches a
130                server statement in the configuration file for
131                <command>rndc</command>.  If no server is supplied on the
132                command line, the host named by the default-server clause
133                in the option statement of the configuration file will be
134                used.
135           </para>
136         </listitem>
137       </varlistentry>
138
139       <varlistentry>
140         <term>-p <replaceable class="parameter">port</replaceable></term>
141         <listitem>
142           <para>
143                Send commands to TCP port
144                <replaceable class="parameter">port</replaceable> instead
145                of BIND 9's default control channel port, 953.
146           </para>
147         </listitem>
148       </varlistentry>
149
150       <varlistentry>
151         <term>-V</term>
152         <listitem>
153           <para>
154                Enable verbose logging.
155           </para>
156         </listitem>
157       </varlistentry>
158
159       <varlistentry>
160         <term>-y <replaceable class="parameter">keyid</replaceable></term>
161         <listitem>
162           <para>
163                Use the key <replaceable class="parameter">keyid</replaceable>
164                from the configuration file.
165                <replaceable class="parameter">keyid</replaceable> must be
166                known by named with the same algorithm and secret string
167                in order for control message validation to succeed.
168                If no <replaceable class="parameter">keyid</replaceable>
169                is specified, <command>rndc</command> will first look
170                for a key clause in the server statement of the server
171                being used, or if no server statement is present for that
172                host, then the default-key clause of the options statement.
173                Note that the configuration file contains shared secrets
174                which are used to send authenticated control commands
175                to name servers.  It should therefore not have general read
176                or write access.
177           </para>
178         </listitem>
179       </varlistentry>
180
181     </variablelist>
182
183     <para>
184       For the complete set of commands supported by <command>rndc</command>,
185       see the BIND 9 Administrator Reference Manual or run
186       <command>rndc</command> without arguments to see its help message.
187     </para>
188
189   </refsect1>
190
191   <refsect1>
192     <title>LIMITATIONS</title>
193     <para>
194         <command>rndc</command> does not yet support all the commands of
195         the BIND 8 <command>ndc</command> utility.
196     </para>
197     <para>
198         There is currently no way to provide the shared secret for a
199         <option>key_id</option> without using the configuration file.
200     </para>
201     <para>
202         Several error messages could be clearer.
203     </para>
204   </refsect1>
205
206   <refsect1>
207     <title>SEE ALSO</title>
208     <para>
209       <citerefentry>
210         <refentrytitle>rndc.conf</refentrytitle>
211         <manvolnum>5</manvolnum>
212       </citerefentry>,
213       <citerefentry>
214         <refentrytitle>named</refentrytitle>
215         <manvolnum>8</manvolnum>
216       </citerefentry>,
217       <citerefentry>
218         <refentrytitle>named.conf</refentrytitle>
219         <manvolnum>5</manvolnum>
220       </citerefentry>
221       <citerefentry>
222         <refentrytitle>ndc</refentrytitle>
223         <manvolnum>8</manvolnum>
224       </citerefentry>,
225       <citetitle>BIND 9 Administrator Reference Manual</citetitle>.
226     </para>
227   </refsect1>
228
229   <refsect1>
230     <title>AUTHOR</title>
231     <para>
232         <corpauthor>Internet Systems Consortium</corpauthor>
233     </para>
234   </refsect1>
235
236 </refentry>
237
238 <!--
239  - Local variables:
240  - mode: sgml
241  - End:
242 -->
243