external/bsd/bind/dist/bin/confgen/ddns-confgen.docbook

   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) 2009, 2014  Internet Systems Consortium, Inc. ("ISC")
   6  -
   7  - Permission to use, copy, modify, and/or distribute this software for any
   8  - purpose with or without fee is hereby granted, provided that the above
   9  - copyright notice and this permission notice appear in all copies.
  10  -
  11  - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  12  - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  13  - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  14  - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  15  - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  16  - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  17  - PERFORMANCE OF THIS SOFTWARE.
  18 -->
  19
  20 <refentry id="man.ddns-confgen">
  21   <refentryinfo>
  22     <date>March 6, 2014</date>
  23   </refentryinfo>
  24
  25   <refmeta>
  26     <refentrytitle><application>ddns-confgen</application></refentrytitle>
  27     <manvolnum>8</manvolnum>
  28     <refmiscinfo>BIND9</refmiscinfo>
  29   </refmeta>
  30
  31   <refnamediv>
  32     <refname><application>ddns-confgen</application></refname>
  33     <refpurpose>ddns key generation tool</refpurpose>
  34   </refnamediv>
  35
  36   <docinfo>
  37     <copyright>
  38       <year>2009</year>
  39       <year>2014</year>
  40       <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
  41     </copyright>
  42   </docinfo>
  43
  44   <refsynopsisdiv>
  45     <cmdsynopsis>
  46       <command>tsig-keygen</command>
  47       <arg><option>-a <replaceable class="parameter">algorithm</replaceable></option></arg>
  48       <arg><option>-h</option></arg>
  49       <arg><option>-r <replaceable class="parameter">randomfile</replaceable></option></arg>
  50       <arg choice="opt">name</arg>
  51     </cmdsynopsis>
  52     <cmdsynopsis>
  53       <command>ddns-confgen</command>
  54       <arg><option>-a <replaceable class="parameter">algorithm</replaceable></option></arg>
  55       <arg><option>-h</option></arg>
  56       <arg><option>-k <replaceable class="parameter">keyname</replaceable></option></arg>
  57       <arg><option>-q</option></arg>
  58       <arg><option>-r <replaceable class="parameter">randomfile</replaceable></option></arg>
  59       <group>
  60         <arg choice="plain">-s <replaceable class="parameter">name</replaceable></arg>
  61         <arg choice="plain">-z <replaceable class="parameter">zone</replaceable></arg>
  62       </group>
  63     </cmdsynopsis>
  64   </refsynopsisdiv>
  65
  66   <refsect1>
  67     <title>DESCRIPTION</title>
  68     <para>
  69       <command>tsig-keygen</command> and <command>ddns-confgen</command>
  70       are invocation methods for a utility that generates keys for use
  71       in TSIG signing.  The resulting keys can be used, for example,
  72       to secure dynamic DNS updates to a zone or for the
  73       <command>rndc</command> command channel.
  74     </para>
  75
  76     <para>
  77       When run as <command>tsig-keygen</command>, a domain name
  78       can be specified on the command line which will be used as
  79       the name of the generated key.  If no name is specified,
  80       the default is <constant>tsig-key</constant>.
  81     </para>
  82
  83     <para>
  84       When run as <command>ddns-confgen</command>, the generated
  85       key is accompanied by configuration text and instructions
  86       that can be used with <command>nsupdate</command> and
  87       <command>named</command> when setting up dynamic DNS,
  88       including an example <command>update-policy</command>
  89       statement.  (This usage similar to the
  90       <command>rndc-confgen</command> command for setting
  91       up command channel security.)
  92     </para>
  93
  94     <para>
  95       Note that <command>named</command> itself can configure a
  96       local DDNS key for use with <command>nsupdate -l</command>:
  97       it does this when a zone is configured with
  98       <command>update-policy local;</command>.
  99       <command>ddns-confgen</command> is only needed when a
 100       more elaborate configuration is required: for instance,
 101       if <command>nsupdate</command> is to be used from a remote
 102       system.
 103     </para>
 104   </refsect1>
 105
 106   <refsect1>
 107     <title>OPTIONS</title>
 108
 109     <variablelist>
 110       <varlistentry>
 111         <term>-a <replaceable class="parameter">algorithm</replaceable></term>
 112         <listitem>
 113           <para>
 114             Specifies the algorithm to use for the TSIG key.  Available
 115             choices are: hmac-md5, hmac-sha1, hmac-sha224, hmac-sha256,
 116             hmac-sha384 and hmac-sha512.  The default is hmac-sha256.
 117             Options are case-insensitive, and the "hmac-" prefix
 118             may be omitted.
 119           </para>
 120         </listitem>
 121       </varlistentry>
 122
 123       <varlistentry>
 124         <term>-h</term>
 125         <listitem>
 126           <para>
 127             Prints a short summary of options and arguments.
 128           </para>
 129         </listitem>
 130       </varlistentry>
 131
 132       <varlistentry>
 133         <term>-k <replaceable class="parameter">keyname</replaceable></term>
 134         <listitem>
 135           <para>
 136             Specifies the key name of the DDNS authentication key.
 137             The default is <constant>ddns-key</constant> when neither
 138             the <option>-s</option> nor <option>-z</option> option is
 139             specified; otherwise, the default
 140             is <constant>ddns-key</constant> as a separate label
 141             followed by the argument of the option, e.g.,
 142             <constant>ddns-key.example.com.</constant>
 143             The key name must have the format of a valid domain name,
 144             consisting of letters, digits, hyphens and periods.
 145           </para>
 146         </listitem>
 147       </varlistentry>
 148
 149       <varlistentry>
 150         <term>-q</term>
 151         <listitem>
 152           <para>
 153             (<command>ddns-confgen</command> only.) Quiet mode:  Print
 154             only the key, with no explanatory text or usage examples;
 155             This is essentially identical to <command>tsig-keygen</command>.
 156           </para>
 157         </listitem>
 158       </varlistentry>
 159
 160       <varlistentry>
 161         <term>-r <replaceable class="parameter">randomfile</replaceable></term>
 162         <listitem>
 163           <para>
 164             Specifies a source of random data for generating the
 165             authorization.  If the operating system does not provide a
 166             <filename>/dev/random</filename> or equivalent device, the
 167             default source of randomness is keyboard input.
 168             <filename>randomdev</filename> specifies the name of a
 169             character device or file containing random data to be used
 170             instead of the default.  The special value
 171             <filename>keyboard</filename> indicates that keyboard input
 172             should be used.
 173           </para>
 174         </listitem>
 175       </varlistentry>
 176
 177       <varlistentry>
 178         <term>-s <replaceable class="parameter">name</replaceable></term>
 179         <listitem>
 180           <para>
 181             (<command>ddns-confgen</command> only.)
 182             Generate configuration example to allow dynamic updates
 183             of a single hostname.  The example <command>named.conf</command>
 184             text shows how to set an update policy for the specified
 185             <replaceable class="parameter">name</replaceable>
 186             using the "name" nametype.  The default key name is
 187             ddns-key.<replaceable class="parameter">name</replaceable>.
 188             Note that the "self" nametype cannot be used, since
 189             the name to be updated may differ from the key name.
 190             This option cannot be used with the <option>-z</option> option.
 191           </para>
 192         </listitem>
 193       </varlistentry>
 194
 195       <varlistentry>
 196         <term>-z <replaceable class="parameter">zone</replaceable></term>
 197         <listitem>
 198           <para>
 199             (<command>ddns-confgen</command> only.)
 200             Generate configuration example to allow dynamic updates
 201             of a zone:  The example <command>named.conf</command> text
 202             shows how to set an update policy for the specified
 203             <replaceable class="parameter">zone</replaceable>
 204             using the "zonesub" nametype, allowing updates to
 205             all subdomain names within that
 206             <replaceable class="parameter">zone</replaceable>.
 207             This option cannot be used with the <option>-s</option> option.
 208           </para>
 209         </listitem>
 210       </varlistentry>
 211     </variablelist>
 212   </refsect1>
 213
 214   <refsect1>
 215     <title>SEE ALSO</title>
 216     <para><citerefentry>
 217         <refentrytitle>nsupdate</refentrytitle><manvolnum>1</manvolnum>
 218       </citerefentry>,
 219       <citerefentry>
 220         <refentrytitle>named.conf</refentrytitle><manvolnum>5</manvolnum>
 221       </citerefentry>,
 222       <citerefentry>
 223         <refentrytitle>named</refentrytitle><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><corpauthor>Internet Systems Consortium</corpauthor>
 232     </para>
 233   </refsect1>
 234
 235 </refentry><!--
 236  - Local variables:
 237  - mode: sgml
 238  - End:
 239 -->