rndc-confgen.docbook 10.3 KB
Newer Older
1
<!--
2
 - Copyright (C) 2001, 2003-2005, 2007, 2009, 2013-2016  Internet Systems Consortium, Inc. ("ISC")
3
 -
4 5 6
 - This Source Code Form is subject to the terms of the Mozilla Public
 - License, v. 2.0. If a copy of the MPL was not distributed with this
 - file, You can obtain one at http://mozilla.org/MPL/2.0/.
7
-->
Tinderbox User's avatar
Tinderbox User committed
8

Evan Hunt's avatar
Evan Hunt committed
9 10 11 12 13
<!-- Converted by db4-upgrade version 1.0 -->
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="man.rndc-confgen">
  <info>
    <date>2013-03-14</date>
  </info>
14
  <refentryinfo>
Evan Hunt's avatar
Evan Hunt committed
15 16
    <corpname>ISC</corpname>
    <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
17 18 19 20 21 22 23 24 25 26 27 28 29
  </refentryinfo>

  <refmeta>
    <refentrytitle><application>rndc-confgen</application></refentrytitle>
    <manvolnum>8</manvolnum>
    <refmiscinfo>BIND9</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname><application>rndc-confgen</application></refname>
    <refpurpose>rndc key generation tool</refpurpose>
  </refnamediv>

30 31
  <docinfo>
    <copyright>
Automatic Updater's avatar
Automatic Updater committed
32 33 34
      <year>2004</year>
      <year>2005</year>
      <year>2007</year>
Automatic Updater's avatar
Automatic Updater committed
35
      <year>2009</year>
Tinderbox User's avatar
Tinderbox User committed
36
      <year>2013</year>
Tinderbox User's avatar
Tinderbox User committed
37
      <year>2014</year>
38
      <year>2015</year>
39
      <year>2016</year>
40 41
      <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
    </copyright>
Tinderbox User's avatar
Tinderbox User committed
42 43 44 45 46
    <copyright>
      <year>2001</year>
      <year>2003</year>
      <holder>Internet Software Consortium.</holder>
    </copyright>
47 48
  </docinfo>

49
  <refsynopsisdiv>
Evan Hunt's avatar
Evan Hunt committed
50
    <cmdsynopsis sepchar=" ">
51
      <command>rndc-confgen</command>
Evan Hunt's avatar
Evan Hunt committed
52 53 54 55 56 57 58 59 60 61 62
      <arg choice="opt" rep="norepeat"><option>-a</option></arg>
      <arg choice="opt" rep="norepeat"><option>-A <replaceable class="parameter">algorithm</replaceable></option></arg>
      <arg choice="opt" rep="norepeat"><option>-b <replaceable class="parameter">keysize</replaceable></option></arg>
      <arg choice="opt" rep="norepeat"><option>-c <replaceable class="parameter">keyfile</replaceable></option></arg>
      <arg choice="opt" rep="norepeat"><option>-h</option></arg>
      <arg choice="opt" rep="norepeat"><option>-k <replaceable class="parameter">keyname</replaceable></option></arg>
      <arg choice="opt" rep="norepeat"><option>-p <replaceable class="parameter">port</replaceable></option></arg>
      <arg choice="opt" rep="norepeat"><option>-r <replaceable class="parameter">randomfile</replaceable></option></arg>
      <arg choice="opt" rep="norepeat"><option>-s <replaceable class="parameter">address</replaceable></option></arg>
      <arg choice="opt" rep="norepeat"><option>-t <replaceable class="parameter">chrootdir</replaceable></option></arg>
      <arg choice="opt" rep="norepeat"><option>-u <replaceable class="parameter">user</replaceable></option></arg>
63 64 65
    </cmdsynopsis>
  </refsynopsisdiv>

Evan Hunt's avatar
Evan Hunt committed
66
  <refsection><info><title>DESCRIPTION</title></info>
67

68 69 70 71 72 73 74 75 76 77 78 79
    <para><command>rndc-confgen</command>
      generates configuration files
      for <command>rndc</command>.  It can be used as a
      convenient alternative to writing the
      <filename>rndc.conf</filename> file
      and the corresponding <command>controls</command>
      and <command>key</command>
      statements in <filename>named.conf</filename> by hand.
      Alternatively, it can be run with the <command>-a</command>
      option to set up a <filename>rndc.key</filename> file and
      avoid the need for a <filename>rndc.conf</filename> file
      and a <command>controls</command> statement altogether.
80 81
    </para>

Evan Hunt's avatar
Evan Hunt committed
82
  </refsection>
83

Evan Hunt's avatar
Evan Hunt committed
84
  <refsection><info><title>OPTIONS</title></info>
85

86 87 88 89

    <variablelist>
      <varlistentry>
        <term>-a</term>
90
        <listitem>
91
          <para>
92 93 94 95 96 97 98 99 100 101 102 103 104
            Do automatic <command>rndc</command> configuration.
            This creates a file <filename>rndc.key</filename>
            in <filename>/etc</filename> (or whatever
            <varname>sysconfdir</varname>
            was specified as when <acronym>BIND</acronym> was
            built)
            that is read by both <command>rndc</command>
            and <command>named</command> on startup.  The
            <filename>rndc.key</filename> file defines a default
            command channel and authentication key allowing
            <command>rndc</command> to communicate with
            <command>named</command> on the local host
            with no further configuration.
105
          </para>
106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125
          <para>
            Running <command>rndc-confgen -a</command> allows
            BIND 9 and <command>rndc</command> to be used as
            drop-in
            replacements for BIND 8 and <command>ndc</command>,
            with no changes to the existing BIND 8
            <filename>named.conf</filename> file.
          </para>
          <para>
            If a more elaborate configuration than that
            generated by <command>rndc-confgen -a</command>
            is required, for example if rndc is to be used remotely,
            you should run <command>rndc-confgen</command> without
            the
            <command>-a</command> option and set up a
            <filename>rndc.conf</filename> and
            <filename>named.conf</filename>
            as directed.
          </para>
        </listitem>
126 127
      </varlistentry>

128 129 130 131 132 133 134 135 136 137 138
      <varlistentry>
        <term>-A <replaceable class="parameter">algorithm</replaceable></term>
        <listitem>
          <para>
            Specifies the algorithm to use for the TSIG key.  Available
            choices are: hmac-md5, hmac-sha1, hmac-sha224, hmac-sha256,
            hmac-sha384 and hmac-sha512.  The default is hmac-md5.
          </para>
        </listitem>
      </varlistentry>

139 140
      <varlistentry>
        <term>-b <replaceable class="parameter">keysize</replaceable></term>
141 142 143
        <listitem>
          <para>
            Specifies the size of the authentication key in bits.
144 145
            Must be between 1 and 512 bits; the default is the
            hash size.
146 147
          </para>
        </listitem>
148 149 150 151
      </varlistentry>

      <varlistentry>
        <term>-c <replaceable class="parameter">keyfile</replaceable></term>
152 153 154 155 156 157
        <listitem>
          <para>
            Used with the <command>-a</command> option to specify
            an alternate location for <filename>rndc.key</filename>.
          </para>
        </listitem>
158 159 160 161
      </varlistentry>

      <varlistentry>
        <term>-h</term>
162 163 164 165 166 167
        <listitem>
          <para>
            Prints a short summary of the options and arguments to
            <command>rndc-confgen</command>.
          </para>
        </listitem>
168 169 170 171
      </varlistentry>

      <varlistentry>
        <term>-k <replaceable class="parameter">keyname</replaceable></term>
172 173 174 175 176 177 178
        <listitem>
          <para>
            Specifies the key name of the rndc authentication key.
            This must be a valid domain name.
            The default is <constant>rndc-key</constant>.
          </para>
        </listitem>
179 180 181 182
      </varlistentry>

      <varlistentry>
        <term>-p <replaceable class="parameter">port</replaceable></term>
183 184 185 186 187 188 189
        <listitem>
          <para>
            Specifies the command channel port where <command>named</command>
            listens for connections from <command>rndc</command>.
            The default is 953.
          </para>
        </listitem>
190 191 192 193
      </varlistentry>

      <varlistentry>
        <term>-r <replaceable class="parameter">randomfile</replaceable></term>
194 195 196 197 198 199 200 201 202 203 204 205 206 207
        <listitem>
          <para>
            Specifies a source of random data for generating the
            authorization.  If the operating
            system does not provide a <filename>/dev/random</filename>
            or equivalent device, the default source of randomness
            is keyboard input.  <filename>randomdev</filename>
            specifies
            the name of a character device or file containing random
            data to be used instead of the default.  The special value
            <filename>keyboard</filename> indicates that keyboard
            input should be used.
          </para>
        </listitem>
208 209 210 211
      </varlistentry>

      <varlistentry>
        <term>-s <replaceable class="parameter">address</replaceable></term>
212 213 214 215 216 217 218 219
        <listitem>
          <para>
            Specifies the IP address where <command>named</command>
            listens for command channel connections from
            <command>rndc</command>.  The default is the loopback
            address 127.0.0.1.
          </para>
        </listitem>
220 221 222 223
      </varlistentry>

      <varlistentry>
        <term>-t <replaceable class="parameter">chrootdir</replaceable></term>
224 225 226 227 228 229 230 231 232
        <listitem>
          <para>
            Used with the <command>-a</command> option to specify
            a directory where <command>named</command> will run
            chrooted.  An additional copy of the <filename>rndc.key</filename>
            will be written relative to this directory so that
            it will be found by the chrooted <command>named</command>.
          </para>
        </listitem>
233 234 235 236
      </varlistentry>

      <varlistentry>
        <term>-u <replaceable class="parameter">user</replaceable></term>
237 238 239 240 241 242 243 244 245 246 247
        <listitem>
          <para>
            Used with the <command>-a</command> option to set the
            owner
            of the <filename>rndc.key</filename> file generated.
            If
            <command>-t</command> is also specified only the file
            in
            the chroot area has its owner changed.
          </para>
        </listitem>
248 249 250
      </varlistentry>

    </variablelist>
Evan Hunt's avatar
Evan Hunt committed
251
  </refsection>
252

Evan Hunt's avatar
Evan Hunt committed
253
  <refsection><info><title>EXAMPLES</title></info>
254

255
    <para>
256 257
      To allow <command>rndc</command> to be used with
      no manual configuration, run
258
    </para>
259
    <para><userinput>rndc-confgen -a</userinput>
260 261
    </para>
    <para>
262 263 264 265
      To print a sample <filename>rndc.conf</filename> file and
      corresponding <command>controls</command> and <command>key</command>
      statements to be manually inserted into <filename>named.conf</filename>,
      run
266
    </para>
267
    <para><userinput>rndc-confgen</userinput>
268
    </para>
Evan Hunt's avatar
Evan Hunt committed
269
  </refsection>
270

Evan Hunt's avatar
Evan Hunt committed
271
  <refsection><info><title>SEE ALSO</title></info>
272

273 274
    <para><citerefentry>
        <refentrytitle>rndc</refentrytitle><manvolnum>8</manvolnum>
275 276
      </citerefentry>,
      <citerefentry>
277
        <refentrytitle>rndc.conf</refentrytitle><manvolnum>5</manvolnum>
278 279
      </citerefentry>,
      <citerefentry>
280
        <refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
281 282 283
      </citerefentry>,
      <citetitle>BIND 9 Administrator Reference Manual</citetitle>.
    </para>
Evan Hunt's avatar
Evan Hunt committed
284
  </refsection>
285

Evan Hunt's avatar
Evan Hunt committed
286
</refentry>