contrib/bind9/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  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 <!-- $Id: ddns-confgen.docbook,v 1.6 2009/09/18 22:08:55 fdupont Exp $ -->
  21 <refentry id="man.ddns-confgen">
  22   <refentryinfo>
  23     <date>Jan 29, 2009</date>
  24   </refentryinfo>
  25
  26   <refmeta>
  27     <refentrytitle><application>ddns-confgen</application></refentrytitle>
  28     <manvolnum>8</manvolnum>
  29     <refmiscinfo>BIND9</refmiscinfo>
  30   </refmeta>
  31
  32   <refnamediv>
  33     <refname><application>ddns-confgen</application></refname>
  34     <refpurpose>ddns key generation tool</refpurpose>
  35   </refnamediv>
  36
  37   <docinfo>
  38     <copyright>
  39       <year>2009</year>
  40       <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
  41     </copyright>
  42   </docinfo>
  43
  44   <refsynopsisdiv>
  45     <cmdsynopsis>
  46       <command>ddns-confgen</command>
  47       <arg><option>-a <replaceable class="parameter">algorithm</replaceable></option></arg>
  48       <arg><option>-h</option></arg>
  49       <arg><option>-k <replaceable class="parameter">keyname</replaceable></option></arg>
  50       <arg><option>-r <replaceable class="parameter">randomfile</replaceable></option></arg>
  51       <group>
  52         <arg choice="plain">-s <replaceable class="parameter">name</replaceable></arg>
  53         <arg choice="plain">-z <replaceable class="parameter">zone</replaceable></arg>
  54       </group>
  55       <arg><option>-q</option></arg>
  56       <arg choice="opt">name</arg>
  57     </cmdsynopsis>
  58   </refsynopsisdiv>
  59
  60   <refsect1>
  61     <title>DESCRIPTION</title>
  62     <para><command>ddns-confgen</command>
  63       generates a key for use by <command>nsupdate</command>
  64       and <command>named</command>.  It simplifies configuration
  65       of dynamic zones by generating a key and providing the
  66       <command>nsupdate</command> and <command>named.conf</command>
  67       syntax that will be needed to use it, including an example
  68       <command>update-policy</command> statement.
  69     </para>
  70
  71     <para>
  72       If a domain name is specified on the command line, it will
  73       be used in the name of the generated key and in the sample
  74       <command>named.conf</command> syntax.  For example,
  75       <command>ddns-confgen example.com</command> would
  76       generate a key called "ddns-key.example.com", and sample
  77       <command>named.conf</command> command that could be used
  78       in the zone definition for "example.com".
  79     </para>
  80
  81     <para>
  82       Note that <command>named</command> itself can configure a
  83       local DDNS key for use with <command>nsupdate -l</command>.
  84       <command>ddns-confgen</command> is only needed when a
  85       more elaborate configuration is required: for instance, if
  86       <command>nsupdate</command> is to be used from a remote system.
  87     </para>
  88   </refsect1>
  89
  90   <refsect1>
  91     <title>OPTIONS</title>
  92
  93     <variablelist>
  94       <varlistentry>
  95         <term>-a <replaceable class="parameter">algorithm</replaceable></term>
  96         <listitem>
  97           <para>
  98             Specifies the algorithm to use for the TSIG key.  Available
  99             choices are: hmac-md5, hmac-sha1, hmac-sha224, hmac-sha256,
 100             hmac-sha384 and hmac-sha512.  The default is hmac-sha256.
 101           </para>
 102         </listitem>
 103       </varlistentry>
 104
 105       <varlistentry>
 106         <term>-h</term>
 107         <listitem>
 108           <para>
 109             Prints a short summary of the options and arguments to
 110             <command>ddns-confgen</command>.
 111           </para>
 112         </listitem>
 113       </varlistentry>
 114
 115       <varlistentry>
 116         <term>-k <replaceable class="parameter">keyname</replaceable></term>
 117         <listitem>
 118           <para>
 119             Specifies the key name of the DDNS authentication key.
 120             The default is <constant>ddns-key</constant> when neither
 121             the <option>-s</option> nor <option>-z</option> option is
 122             specified; otherwise, the default
 123             is <constant>ddns-key</constant> as a separate label
 124             followed by the argument of the option, e.g.,
 125             <constant>ddns-key.example.com.</constant>
 126             The key name must have the format of a valid domain name,
 127             consisting of letters, digits, hyphens and periods.
 128           </para>
 129         </listitem>
 130       </varlistentry>
 131
 132       <varlistentry>
 133         <term>-q</term>
 134         <listitem>
 135           <para>
 136             Quiet mode:  Print only the key, with no explanatory text or
 137             usage examples.
 138           </para>
 139         </listitem>
 140       </varlistentry>
 141
 142       <varlistentry>
 143         <term>-r <replaceable class="parameter">randomfile</replaceable></term>
 144         <listitem>
 145           <para>
 146             Specifies a source of random data for generating the
 147             authorization.  If the operating system does not provide a
 148             <filename>/dev/random</filename> or equivalent device, the
 149             default source of randomness is keyboard input.
 150             <filename>randomdev</filename> specifies the name of a
 151             character device or file containing random data to be used
 152             instead of the default.  The special value
 153             <filename>keyboard</filename> indicates that keyboard input
 154             should be used.
 155           </para>
 156         </listitem>
 157       </varlistentry>
 158
 159       <varlistentry>
 160         <term>-s <replaceable class="parameter">name</replaceable></term>
 161         <listitem>
 162           <para>
 163             Single host mode: The example <command>named.conf</command> text
 164             shows how to set an update policy for the specified
 165             <replaceable class="parameter">name</replaceable>
 166             using the "name" nametype.
 167             The default key name is
 168             ddns-key.<replaceable class="parameter">name</replaceable>.
 169             Note that the "self" nametype cannot be used, since
 170             the name to be updated may differ from the key name.
 171             This option cannot be used with the <option>-z</option> option.
 172           </para>
 173         </listitem>
 174       </varlistentry>
 175
 176       <varlistentry>
 177         <term>-z <replaceable class="parameter">zone</replaceable></term>
 178         <listitem>
 179           <para>
 180             zone mode:  The example <command>named.conf</command> text
 181             shows how to set an update policy for the specified
 182             <replaceable class="parameter">zone</replaceable>
 183             using the "zonesub" nametype, allowing updates to all subdomain
 184             names within
 185             that <replaceable class="parameter">zone</replaceable>.
 186             This option cannot be used with the <option>-s</option> option.
 187           </para>
 188         </listitem>
 189       </varlistentry>
 190     </variablelist>
 191   </refsect1>
 192
 193   <refsect1>
 194     <title>SEE ALSO</title>
 195     <para><citerefentry>
 196         <refentrytitle>nsupdate</refentrytitle><manvolnum>1</manvolnum>
 197       </citerefentry>,
 198       <citerefentry>
 199         <refentrytitle>named.conf</refentrytitle><manvolnum>5</manvolnum>
 200       </citerefentry>,
 201       <citerefentry>
 202         <refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
 203       </citerefentry>,
 204       <citetitle>BIND 9 Administrator Reference Manual</citetitle>.
 205     </para>
 206   </refsect1>
 207
 208   <refsect1>
 209     <title>AUTHOR</title>
 210     <para><corpauthor>Internet Systems Consortium</corpauthor>
 211     </para>
 212   </refsect1>
 213
 214 </refentry><!--
 215  - Local variables:
 216  - mode: sgml
 217  - End:
 218 -->