contrib/bind9/bin/confgen/ddns-confgen.docbook

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