PageRenderTime 65ms CodeModel.GetById 57ms app.highlight 3ms RepoModel.GetById 1ms app.codeStats 0ms

/contrib/bind9/bin/rndc/rndc.docbook

https://bitbucket.org/freebsd/freebsd-head/
Unknown | 253 lines | 232 code | 21 blank | 0 comment | 0 complexity | 778db76ff70cf682b4185a13769ec6f9 MD5 | raw file
  1<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
  2               "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
  3	       [<!ENTITY mdash "&#8212;">]>
  4<!--
  5 - Copyright (C) 2004, 2005, 2007  Internet Systems Consortium, Inc. ("ISC")
  6 - Copyright (C) 2000, 2001  Internet Software Consortium.
  7 -
  8 - Permission to use, copy, modify, and/or 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.21 2007/12/14 20:39:14 marka Exp $ -->
 22<refentry id="man.rndc">
 23  <refentryinfo>
 24    <date>June 30, 2000</date>
 25  </refentryinfo>
 26
 27  <refmeta>
 28    <refentrytitle><application>rndc</application></refentrytitle>
 29    <manvolnum>8</manvolnum>
 30    <refmiscinfo>BIND9</refmiscinfo>
 31  </refmeta>
 32
 33  <refnamediv>
 34    <refname><application>rndc</application></refname>
 35    <refpurpose>name server control utility</refpurpose>
 36  </refnamediv>
 37
 38  <docinfo>
 39    <copyright>
 40      <year>2004</year>
 41      <year>2005</year>
 42      <year>2007</year>
 43      <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
 44    </copyright>
 45    <copyright>
 46      <year>2000</year>
 47      <year>2001</year>
 48      <holder>Internet Software Consortium.</holder>
 49    </copyright>
 50  </docinfo>
 51
 52  <refsynopsisdiv>
 53    <cmdsynopsis>
 54      <command>rndc</command>
 55      <arg><option>-b <replaceable class="parameter">source-address</replaceable></option></arg>
 56      <arg><option>-c <replaceable class="parameter">config-file</replaceable></option></arg>
 57      <arg><option>-k <replaceable class="parameter">key-file</replaceable></option></arg>
 58      <arg><option>-s <replaceable class="parameter">server</replaceable></option></arg>
 59      <arg><option>-p <replaceable class="parameter">port</replaceable></option></arg>
 60      <arg><option>-V</option></arg>
 61      <arg><option>-y <replaceable class="parameter">key_id</replaceable></option></arg>
 62      <arg choice="req">command</arg>
 63    </cmdsynopsis>
 64  </refsynopsisdiv>
 65
 66  <refsect1>
 67    <title>DESCRIPTION</title>
 68    <para><command>rndc</command>
 69      controls the operation of a name
 70      server.  It supersedes the <command>ndc</command> utility
 71      that was provided in old BIND releases.  If
 72      <command>rndc</command> is invoked with no command line
 73      options or arguments, it prints a short summary of the
 74      supported commands and the available options and their
 75      arguments.
 76    </para>
 77    <para><command>rndc</command>
 78      communicates with the name server
 79      over a TCP connection, sending commands authenticated with
 80      digital signatures.  In the current versions of
 81      <command>rndc</command> and <command>named</command>,
 82      the only supported authentication algorithm is HMAC-MD5,
 83      which uses a shared secret on each end of the connection.
 84      This provides TSIG-style authentication for the command
 85      request and the name server's response.  All commands sent
 86      over the channel must be signed by a key_id known to the
 87      server.
 88    </para>
 89    <para><command>rndc</command>
 90      reads a configuration file to
 91      determine how to contact the name server and decide what
 92      algorithm and key it should use.
 93    </para>
 94  </refsect1>
 95
 96  <refsect1>
 97    <title>OPTIONS</title>
 98
 99    <variablelist>
100      <varlistentry>
101        <term>-b <replaceable class="parameter">source-address</replaceable></term>
102        <listitem>
103          <para>
104            Use <replaceable class="parameter">source-address</replaceable>
105            as the source address for the connection to the server.
106            Multiple instances are permitted to allow setting of both
107            the IPv4 and IPv6 source addresses.
108          </para>
109        </listitem>
110      </varlistentry>
111
112      <varlistentry>
113        <term>-c <replaceable class="parameter">config-file</replaceable></term>
114        <listitem>
115          <para>
116            Use <replaceable class="parameter">config-file</replaceable>
117            as the configuration file instead of the default,
118            <filename>/etc/rndc.conf</filename>.
119          </para>
120        </listitem>
121      </varlistentry>
122
123      <varlistentry>
124        <term>-k <replaceable class="parameter">key-file</replaceable></term>
125        <listitem>
126          <para>
127            Use <replaceable class="parameter">key-file</replaceable>
128            as the key file instead of the default,
129            <filename>/etc/rndc.key</filename>.  The key in
130            <filename>/etc/rndc.key</filename> will be used to
131            authenticate
132            commands sent to the server if the <replaceable class="parameter">config-file</replaceable>
133            does not exist.
134          </para>
135        </listitem>
136      </varlistentry>
137
138      <varlistentry>
139        <term>-s <replaceable class="parameter">server</replaceable></term>
140        <listitem>
141          <para><replaceable class="parameter">server</replaceable> is
142            the name or address of the server which matches a
143            server statement in the configuration file for
144            <command>rndc</command>.  If no server is supplied on the
145            command line, the host named by the default-server clause
146            in the options statement of the <command>rndc</command>
147	    configuration file will be used.
148          </para>
149        </listitem>
150      </varlistentry>
151
152      <varlistentry>
153        <term>-p <replaceable class="parameter">port</replaceable></term>
154        <listitem>
155          <para>
156            Send commands to TCP port
157            <replaceable class="parameter">port</replaceable>
158            instead
159            of BIND 9's default control channel port, 953.
160          </para>
161        </listitem>
162      </varlistentry>
163
164      <varlistentry>
165        <term>-V</term>
166        <listitem>
167          <para>
168            Enable verbose logging.
169          </para>
170        </listitem>
171      </varlistentry>
172
173      <varlistentry>
174        <term>-y <replaceable class="parameter">key_id</replaceable></term>
175        <listitem>
176          <para>
177            Use the key <replaceable class="parameter">key_id</replaceable>
178            from the configuration file.
179            <replaceable class="parameter">key_id</replaceable>
180            must be
181            known by named with the same algorithm and secret string
182            in order for control message validation to succeed.
183            If no <replaceable class="parameter">key_id</replaceable>
184            is specified, <command>rndc</command> will first look
185            for a key clause in the server statement of the server
186            being used, or if no server statement is present for that
187            host, then the default-key clause of the options statement.
188            Note that the configuration file contains shared secrets
189            which are used to send authenticated control commands
190            to name servers.  It should therefore not have general read
191            or write access.
192          </para>
193        </listitem>
194      </varlistentry>
195
196    </variablelist>
197
198    <para>
199      For the complete set of commands supported by <command>rndc</command>,
200      see the BIND 9 Administrator Reference Manual or run
201      <command>rndc</command> without arguments to see its help
202      message.
203    </para>
204
205  </refsect1>
206
207  <refsect1>
208    <title>LIMITATIONS</title>
209    <para><command>rndc</command>
210      does not yet support all the commands of
211      the BIND 8 <command>ndc</command> utility.
212    </para>
213    <para>
214      There is currently no way to provide the shared secret for a
215      <option>key_id</option> without using the configuration file.
216    </para>
217    <para>
218      Several error messages could be clearer.
219    </para>
220  </refsect1>
221
222  <refsect1>
223    <title>SEE ALSO</title>
224    <para><citerefentry>
225        <refentrytitle>rndc.conf</refentrytitle><manvolnum>5</manvolnum>
226      </citerefentry>,
227      <citerefentry>
228        <refentrytitle>rndc-confgen</refentrytitle><manvolnum>8</manvolnum>
229      </citerefentry>,
230      <citerefentry>
231        <refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
232      </citerefentry>,
233      <citerefentry>
234        <refentrytitle>named.conf</refentrytitle><manvolnum>5</manvolnum>
235      </citerefentry>,
236      <citerefentry>
237        <refentrytitle>ndc</refentrytitle><manvolnum>8</manvolnum>
238      </citerefentry>,
239      <citetitle>BIND 9 Administrator Reference Manual</citetitle>.
240    </para>
241  </refsect1>
242
243  <refsect1>
244    <title>AUTHOR</title>
245    <para><corpauthor>Internet Systems Consortium</corpauthor>
246    </para>
247  </refsect1>
248
249</refentry><!--
250 - Local variables:
251 - mode: sgml
252 - End:
253-->