cleanup: revamp the dnssec-dsfromkey man page and help output 1437/head
authorTony Finch <dot@dotat.at>
Thu, 31 Jan 2019 16:41:29 +0000 (16:41 +0000)
committerEvan Hunt <each@isc.org>
Wed, 6 Feb 2019 03:02:18 +0000 (19:02 -0800)
* Alphabetize the option lists in the man page and help text

* Make the synopses more consistent between the man page and help
  text, in particular the number of different modes

* Group mutually exclusive options in the man page synopses, and order
  options so that it is more clear which are available in every mode

* Expand the DESCRIPTION to provide an overview of the output modes
  and input modes

* Improve cross-references between options

* Leave RFC citations to the SEE ALSO section, and clarify which RFC
  specifies what

* Clarify list of digest algorithms in dnssec-dsfromkey and dnssec-cds
  man pages

bin/dnssec/dnssec-cds.docbook
bin/dnssec/dnssec-dsfromkey.c
bin/dnssec/dnssec-dsfromkey.docbook

index a6aef38..bc0b326 100644 (file)
            record. This option has no effect when using CDS records.
           </para>
           <para>
-           The <replaceable>algorithm</replaceable> must be one of SHA-1
-           (SHA1), SHA-256 (SHA256), or SHA-384 (SHA384). These
-           values are case insensitive. If no algorithm is specified,
+           The <replaceable>algorithm</replaceable> must be one of
+           SHA-1, SHA-256, or SHA-384.  These values are case insensitive,
+           and the hyphen may be omitted.  If no algorithm is specified,
            the default is SHA-256.
           </para>
         </listitem>
index 15eeafb..ae11561 100644 (file)
@@ -318,30 +318,27 @@ usage(void) ISC_PLATFORM_NORETURN_POST;
 static void
 usage(void) {
        fprintf(stderr, "Usage:\n");
-       fprintf(stderr, "    %s options [-K dir] keyfile\n\n", program);
-       fprintf(stderr, "    %s options [-K dir] [-c class] -s dnsname\n\n",
-               program);
-       fprintf(stderr, "    %s options -f zonefile (as zone name)\n\n", program);
-       fprintf(stderr, "    %s options -f zonefile zonename\n\n", program);
+       fprintf(stderr, "    %s [options] keyfile\n\n", program);
+       fprintf(stderr, "    %s [options] -f zonefile [zonename]\n\n", program);
+       fprintf(stderr, "    %s [options] -s dnsname\n\n", program);
+       fprintf(stderr, "    %s [-h|-V]\n\n", program);
        fprintf(stderr, "Version: %s\n", VERSION);
-       fprintf(stderr, "Options:\n");
-       fprintf(stderr, "    -v <verbose level>\n");
-       fprintf(stderr, "    -V: print version information\n");
-       fprintf(stderr, "    -K <directory>: directory in which to find "
-                       "key file or keyset file\n");
-       fprintf(stderr, "    -a algorithm: digest algorithm "
-                       "(SHA-1, SHA-256 or SHA-384)\n");
-       fprintf(stderr, "    -1: use SHA-1\n");
-       fprintf(stderr, "    -2: use SHA-256\n");
-       fprintf(stderr, "    -C: print CDS record\n");
-       fprintf(stderr, "    -l: add lookaside zone and print DLV records\n");
-       fprintf(stderr, "    -s: read keyset from keyset-<dnsname> file\n");
-       fprintf(stderr, "    -c class: rdata class for DS set (default: IN)\n");
-       fprintf(stderr, "    -T TTL\n");
-       fprintf(stderr, "    -f file: read keyset from zone file\n");
-       fprintf(stderr, "    -A: when used with -f, "
-                       "include all keys in DS set, not just KSKs\n");
-       fprintf(stderr, "Output: DS or DLV RRs\n");
+       fprintf(stderr, "Options:\n"
+"    -1: digest algorithm SHA-1\n"
+"    -2: digest algorithm SHA-256\n"
+"    -a algorithm: digest algorithm (SHA-1, SHA-256 or SHA-384)\n"
+"    -A: include all keys in DS set, not just KSKs (-f only)\n"
+"    -c class: rdata class for DS set (default IN) (-f or -s only)\n"
+"    -C: print CDS records\n"
+"    -f zonefile: read keys from a zone file\n"
+"    -h: print help information\n"
+"    -K directory: where to find key or keyset files\n"
+"    -l zone: print DLV records in the given lookaside zone\n"
+"    -s: read keys from keyset-<dnsname> file\n"
+"    -T: TTL of output records (omitted by default)\n"
+"    -v level: verbosity\n"
+"    -V: print version information\n");
+       fprintf(stderr, "Output: DS, DLV, or CDS RRs\n");
 
        exit (-1);
 }
index ff664ab..7f0039e 100644 (file)
   <refsynopsisdiv>
     <cmdsynopsis sepchar=" ">
       <command>dnssec-dsfromkey</command>
-      <arg choice="opt" rep="norepeat"><option>-v <replaceable class="parameter">level</replaceable></option></arg>
-      <arg choice="opt" rep="norepeat"><option>-1</option></arg>
-      <arg choice="opt" rep="norepeat"><option>-2</option></arg>
-      <arg choice="opt" rep="norepeat"><option>-a <replaceable class="parameter">alg</replaceable></option></arg>
-      <arg choice="opt" rep="norepeat"><option>-C</option></arg>
-      <arg choice="opt" rep="norepeat"><option>-l <replaceable class="parameter">domain</replaceable></option></arg>
+      <group choice="opt">
+       <arg choice="plain"><option>-1</option></arg>
+       <arg choice="plain"><option>-2</option></arg>
+       <arg choice="plain"><option>-a <replaceable class="parameter">alg</replaceable></option></arg>
+      </group>
+      <group>
+       <arg choice="plain" rep="norepeat"><option>-C</option></arg>
+       <arg choice="plain" rep="norepeat"><option>-l <replaceable class="parameter">domain</replaceable></option></arg>
+      </group>
       <arg choice="opt" rep="norepeat"><option>-T <replaceable class="parameter">TTL</replaceable></option></arg>
+      <arg choice="opt" rep="norepeat"><option>-v <replaceable class="parameter">level</replaceable></option></arg>
+      <arg choice="opt" rep="norepeat"><option>-K <replaceable class="parameter">directory</replaceable></option></arg>
       <arg choice="req" rep="norepeat">keyfile</arg>
     </cmdsynopsis>
     <cmdsynopsis sepchar=" ">
       <command>dnssec-dsfromkey</command>
-      <arg choice="req" rep="norepeat">-s</arg>
-      <arg choice="opt" rep="norepeat"><option>-1</option></arg>
-      <arg choice="opt" rep="norepeat"><option>-2</option></arg>
-      <arg choice="opt" rep="norepeat"><option>-a <replaceable class="parameter">alg</replaceable></option></arg>
-      <arg choice="opt" rep="norepeat"><option>-K <replaceable class="parameter">directory</replaceable></option></arg>
-      <arg choice="opt" rep="norepeat"><option>-l <replaceable class="parameter">domain</replaceable></option></arg>
-      <arg choice="opt" rep="norepeat"><option>-s</option></arg>
-      <arg choice="opt" rep="norepeat"><option>-c <replaceable class="parameter">class</replaceable></option></arg>
+      <group choice="opt">
+       <arg choice="plain"><option>-1</option></arg>
+       <arg choice="plain"><option>-2</option></arg>
+       <arg choice="plain"><option>-a <replaceable class="parameter">alg</replaceable></option></arg>
+      </group>
+      <group>
+       <arg choice="plain" rep="norepeat"><option>-C</option></arg>
+       <arg choice="plain" rep="norepeat"><option>-l <replaceable class="parameter">domain</replaceable></option></arg>
+      </group>
       <arg choice="opt" rep="norepeat"><option>-T <replaceable class="parameter">TTL</replaceable></option></arg>
-      <arg choice="opt" rep="norepeat"><option>-f <replaceable class="parameter">file</replaceable></option></arg>
+      <arg choice="opt" rep="norepeat"><option>-v <replaceable class="parameter">level</replaceable></option></arg>
+      <arg choice="opt" rep="norepeat"><option>-c <replaceable class="parameter">class</replaceable></option></arg>
       <arg choice="opt" rep="norepeat"><option>-A</option></arg>
+      <arg choice="req" rep="norepeat"><option>-f <replaceable class="parameter">file</replaceable></option></arg>
+      <arg choice="opt" rep="norepeat">dnsname</arg>
+    </cmdsynopsis>
+    <cmdsynopsis sepchar=" ">
+      <command>dnssec-dsfromkey</command>
+      <group choice="opt">
+       <arg choice="plain"><option>-1</option></arg>
+       <arg choice="plain"><option>-2</option></arg>
+       <arg choice="plain"><option>-a <replaceable class="parameter">alg</replaceable></option></arg>
+      </group>
+      <group>
+       <arg choice="plain" rep="norepeat"><option>-C</option></arg>
+       <arg choice="plain" rep="norepeat"><option>-l <replaceable class="parameter">domain</replaceable></option></arg>
+      </group>
+      <arg choice="opt" rep="norepeat"><option>-T <replaceable class="parameter">TTL</replaceable></option></arg>
       <arg choice="opt" rep="norepeat"><option>-v <replaceable class="parameter">level</replaceable></option></arg>
+      <arg choice="opt" rep="norepeat"><option>-c <replaceable class="parameter">class</replaceable></option></arg>
+      <arg choice="opt" rep="norepeat"><option>-K <replaceable class="parameter">directory</replaceable></option></arg>
+      <arg choice="req" rep="norepeat">-s</arg>
       <arg choice="req" rep="norepeat">dnsname</arg>
-   </cmdsynopsis>
+    </cmdsynopsis>
     <cmdsynopsis sepchar=" ">
       <command>dnssec-dsfromkey</command>
-      <arg choice="opt" rep="norepeat"><option>-h</option></arg>
-      <arg choice="opt" rep="norepeat"><option>-V</option></arg>
-   </cmdsynopsis>
+      <group choice="opt">
+       <arg choice="plain" rep="norepeat"><option>-h</option></arg>
+       <arg choice="plain" rep="norepeat"><option>-V</option></arg>
+      </group>
+    </cmdsynopsis>
   </refsynopsisdiv>
 
   <refsection><info><title>DESCRIPTION</title></info>
 
-    <para><command>dnssec-dsfromkey</command>
-      outputs the Delegation Signer (DS) resource record (RR), as defined in
-      RFC 3658 and RFC 4509, for the given key(s).
+    <para>
+      The <command>dnssec-dsfromkey</command> command outputs DS (Delegation
+      Signer) resource records (RRs) and other similarly-constructed RRs:
+      with the <option>-l</option> option it outputs DLV (DNSSEC Lookaside
+      Validation) RRs; or with the <option>-C</option> it outputs CDS (Child
+      DS) RRs.
+    </para>
+
+    <para>
+      The input keys can be specified in a number of ways:
     </para>
+
+    <para>
+      By default, <command>dnssec-dsfromkey</command> reads a key file
+      named like <filename>Knnnn.+aaa+iiiii.key</filename>, as generated
+      by <command>dnssec-keygen</command>.
+    </para>
+
+    <para>
+      With the <option>-f <replaceable>file</replaceable></option>
+      option, <command>dnssec-dsfromkey</command> reads keys from a zone file
+      or partial zone file (which can contain just the DNSKEY records).
+    </para>
+
+    <para>
+      With the <option>-s</option>
+      option, <command>dnssec-dsfromkey</command> reads
+      a <filename>keyset-</filename> file, as generated
+      by <command>dnssec-keygen</command> <option>-C</option>.
+    </para>
+
   </refsection>
 
   <refsection><info><title>OPTIONS</title></info>
 
-
     <variablelist>
       <varlistentry>
        <term>-1</term>
        <listitem>
          <para>
-           Use SHA-1 as the digest algorithm (the default is to use
-           both SHA-1 and SHA-256).
+           An abbreviation for <option>-a SHA1</option>
          </para>
        </listitem>
       </varlistentry>
        <term>-2</term>
        <listitem>
          <para>
-           Use SHA-256 as the digest algorithm.
+           An abbreviation for <option>-a SHA-256</option>
          </para>
        </listitem>
       </varlistentry>
        <term>-a <replaceable class="parameter">algorithm</replaceable></term>
        <listitem>
          <para>
-           Select the digest algorithm. The value of
-           <option>algorithm</option> must be one of SHA-1 (SHA1),
-           SHA-256 (SHA256) or SHA-384 (SHA384).
-           These values are case insensitive.
+           Specify a digest algorithm to use when converting DNSKEY
+           records to DS records. This option can be repeated, so
+           that multiple DS records are created for each DNSKEY
+           record.
+          </para>
+          <para>
+           The <replaceable>algorithm</replaceable> must be one of
+           SHA-1, SHA-256, or SHA-384.  These values are case insensitive,
+           and the hyphen may be omitted.  If no algorithm is specified,
+           the default is SHA-256.
          </para>
        </listitem>
       </varlistentry>
 
       <varlistentry>
-       <term>-C</term>
-       <listitem>
-         <para>
-           Generate CDS records rather than DS records.  This is mutually
-           exclusive with generating lookaside records.
-         </para>
-       </listitem>
+        <term>-A</term>
+        <listitem>
+          <para>
+            Include ZSKs when generating DS records. Without this option, only
+            keys which have the KSK flag set will be converted to DS records
+            and printed. Useful only in <option>-f</option> zone file mode.
+          </para>
+        </listitem>
       </varlistentry>
 
       <varlistentry>
-       <term>-T <replaceable class="parameter">TTL</replaceable></term>
+       <term>-c <replaceable class="parameter">class</replaceable></term>
        <listitem>
          <para>
-           Specifies the TTL of the DS records.
+           Specifies the DNS class (default is IN). Useful only
+           in <option>-s</option> keyset or <option>-f</option>
+           zone file mode.
          </para>
          </listitem>
       </varlistentry>
 
       <varlistentry>
-       <term>-K <replaceable class="parameter">directory</replaceable></term>
+       <term>-C</term>
        <listitem>
          <para>
-           Look for key files (or, in keyset mode,
-           <filename>keyset-</filename> files) in
-           <option>directory</option>.
+           Generate CDS records rather than DS records. This is mutually
+           exclusive with the <option>-l</option> option for generating DLV
+           records.
          </para>
        </listitem>
       </varlistentry>
        <term>-f <replaceable class="parameter">file</replaceable></term>
        <listitem>
          <para>
-           Zone file mode: in place of the keyfile name, the argument is
-           the DNS domain name of a zone master file, which can be read
+           Zone file mode: <command>dnssec-dsfromkey</command>'s
+           final <replaceable>dnsname</replaceable> argument is
+           the DNS domain name of a zone whose master file can be read
            from <option>file</option>.  If the zone name is the same as
            <option>file</option>, then it may be omitted.
          </para>
          <para>
-           If <option>file</option> is set to <literal>"-"</literal>, then
+           If <replaceable>file</replaceable> is <literal>"-"</literal>, then
            the zone data is read from the standard input.  This makes it
            possible to use the output of the <command>dig</command>
            command as input, as in:
       </varlistentry>
 
       <varlistentry>
-        <term>-A</term>
-        <listitem>
-          <para>
-            Include ZSKs when generating DS records.  Without this option,
-            only keys which have the KSK flag set will be converted to DS
-            records and printed.  Useful only in zone file mode.
-          </para>
-        </listitem>
+       <term>-h</term>
+       <listitem>
+         <para>
+           Prints usage information.
+         </para>
+       </listitem>
       </varlistentry>
 
       <varlistentry>
-       <term>-l <replaceable class="parameter">domain</replaceable></term>
+       <term>-K <replaceable class="parameter">directory</replaceable></term>
        <listitem>
          <para>
-           Generate a DLV set instead of a DS set.  The specified
-           <option>domain</option> is appended to the name for each
-           record in the set.
-           The DNSSEC Lookaside Validation (DLV) RR is described
-           in RFC 4431.  This is mutually exclusive with generating
-           CDS records.
+           Look for key files or <filename>keyset-</filename> files in
+           <option>directory</option>.
          </para>
        </listitem>
       </varlistentry>
 
       <varlistentry>
-       <term>-s</term>
+       <term>-l <replaceable class="parameter">domain</replaceable></term>
        <listitem>
          <para>
-           Keyset mode: in place of the keyfile name, the argument is
-           the DNS domain name of a keyset file.
+           Generate a DLV set instead of a DS set. The specified
+           <replaceable>domain</replaceable> is appended to the name for each
+           record in the set.
+           This is mutually exclusive with the <option>-C</option> option
+           for generating CDS records.
          </para>
        </listitem>
       </varlistentry>
 
       <varlistentry>
-       <term>-c <replaceable class="parameter">class</replaceable></term>
+       <term>-s</term>
        <listitem>
          <para>
-           Specifies the DNS class (default is IN).  Useful only
-           in keyset or zone file mode.
+           Keyset mode: <command>dnssec-dsfromkey</command>'s
+           final <replaceable>dnsname</replaceable> argument is the DNS
+           domain name used to locate a <filename>keyset-</filename> file.
          </para>
-         </listitem>
+       </listitem>
       </varlistentry>
 
       <varlistentry>
-       <term>-v <replaceable class="parameter">level</replaceable></term>
+       <term>-T <replaceable class="parameter">TTL</replaceable></term>
        <listitem>
          <para>
-           Sets the debugging level.
+           Specifies the TTL of the DS records. By default the TTL is omitted.
          </para>
-       </listitem>
+         </listitem>
       </varlistentry>
 
       <varlistentry>
-       <term>-h</term>
+       <term>-v <replaceable class="parameter">level</replaceable></term>
        <listitem>
          <para>
-           Prints usage information.
+           Sets the debugging level.
          </para>
        </listitem>
       </varlistentry>
     <para>
       To build the SHA-256 DS RR from the
       <userinput>Kexample.com.+003+26160</userinput>
-      keyfile name, the following command would be issued:
+      keyfile name, you can issue the following command:
     </para>
     <para><userinput>dnssec-dsfromkey -2 Kexample.com.+003+26160</userinput>
     </para>
     <para>
       The command would print something like:
     </para>
-    <para><userinput>example.com. IN DS 26160 5 2 3A1EADA7A74B8D0BA86726B0C227AA85AB8BBD2B2004F41A868A54F0 C5EA0B94</userinput>
+    <para><userinput>example.com. IN DS 26160 5 2 3A1EADA7A74B8D0BA86726B0C227AA85AB8BBD2B2004F41A868A54F0C5EA0B94</userinput>
     </para>
+
   </refsection>
 
   <refsection><info><title>FILES</title></info>
 
     <para>
-      The keyfile can be designed by the key identification
+      The keyfile can be designated by the key identification
       <filename>Knnnn.+aaa+iiiii</filename> or the full file name
       <filename>Knnnn.+aaa+iiiii.key</filename> as generated by
       <refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>.
        <refentrytitle>dnssec-signzone</refentrytitle><manvolnum>8</manvolnum>
       </citerefentry>,
       <citetitle>BIND 9 Administrator Reference Manual</citetitle>,
-      <citetitle>RFC 3658</citetitle>,
-      <citetitle>RFC 4431</citetitle>.
-      <citetitle>RFC 4509</citetitle>.
+      <citetitle>RFC 3658</citetitle> (DS RRs),
+      <citetitle>RFC 4431</citetitle> (DLV RRs),
+      <citetitle>RFC 4509</citetitle> (SHA-256 for DS RRs),
+      <citetitle>RFC 6605</citetitle> (SHA-384 for DS RRs),
+      <citetitle>RFC 7344</citetitle> (CDS and CDNSKEY RRs).
     </para>
   </refsection>