/mandos/trunk

To get this branch, use:
bzr branch http://bzr.recompile.se/loggerhead/mandos/trunk

« back to all changes in this revision

Viewing changes to mandos-keygen.xml

  • Committer: Teddy Hogeborn
  • Date: 2019-07-29 16:35:53 UTC
  • Revision ID: teddy@recompile.se-20190729163553-1i442i2cbx64c537
Make tests and man page examples match

Make the tests test_manual_page_example[1-5] match exactly what is
written in the manual page, and add comments to manual page as
reminders to keep tests and manual page examples in sync.

* mandos-ctl (Test_commands_from_options.test_manual_page_example_1):
  Remove "--verbose" option, since the manual does not have it as the
  first example, and change assertion to match.
* mandos-ctl.xml (EXAMPLE): Add comments to all examples documenting
  which test function they correspond to.  Also remove unnecessary
  quotes from option arguments in fourth example, and clarify language
  slightly in fifth example.

Show diffs side-by-side

added added

removed removed

Lines of Context:
mandos-keygen.xml
2
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3
3
        "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4
4
<!ENTITY COMMANDNAME "mandos-keygen">
5
 
<!ENTITY TIMESTAMP "2019-02-10">
 
5
<!ENTITY TIMESTAMP "2019-07-18">
6
6
<!ENTITY % common SYSTEM "common.ent">
7
7
%common;
8
8
]>
42
42
      <year>2016</year>
43
43
      <year>2017</year>
44
44
      <year>2018</year>
 
45
      <year>2019</year>
45
46
      <holder>Teddy Hogeborn</holder>
46
47
      <holder>Björn Påhlsson</holder>
47
48
    </copyright>
190
191
      TLS and OpenPGP keys used by
191
192
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
192
193
      <manvolnum>8mandos</manvolnum></citerefentry>.  The keys are
193
 
      normally written to /etc/mandos for later installation into the
194
 
      initrd image, but this, and most other things, can be changed
195
 
      with command line options.
 
194
      normally written to /etc/keys/mandos for later installation into
 
195
      the initrd image, but this, and most other things, can be
 
196
      changed with command line options.
196
197
    </para>
197
198
    <para>
198
199
      This program can also be used with the
235
236
        <replaceable>DIRECTORY</replaceable></option></term>
236
237
        <listitem>
237
238
          <para>
238
 
            Target directory for key files.  Default is
239
 
            <filename class="directory">/etc/mandos</filename>.
 
239
            Target directory for key files.  Default is <filename
 
240
            class="directory">/etc/keys/mandos</filename>.
240
241
          </para>
241
242
        </listitem>
242
243
      </varlistentry>
354
355
        <listitem>
355
356
          <para>
356
357
            Prompt for a password and encrypt it with the key already
357
 
            present in either <filename>/etc/mandos</filename> or the
358
 
            directory specified with the <option>--dir</option>
 
358
            present in either <filename>/etc/keys/mandos</filename> or
 
359
            the directory specified with the <option>--dir</option>
359
360
            option.  Outputs, on standard output, a section suitable
360
361
            for inclusion in <citerefentry><refentrytitle
361
362
            >mandos-clients.conf</refentrytitle><manvolnum
362
363
            >8</manvolnum></citerefentry>.  The host name or the name
363
364
            specified with the <option>--name</option> option is used
364
365
            for the section header.  All other options are ignored,
365
 
            and no key is created.
 
366
            and no key is created.  Note: white space is stripped from
 
367
            the beginning and from the end of the password; See <xref
 
368
            linkend="bugs"/>.
366
369
          </para>
367
370
        </listitem>
368
371
      </varlistentry>
374
377
        <listitem>
375
378
          <para>
376
379
            The same as <option>--password</option>, but read from
377
 
            <replaceable>FILE</replaceable>, not the terminal.
 
380
            <replaceable>FILE</replaceable>, not the terminal, and
 
381
            white space is not stripped from the password in any way.
378
382
          </para>
379
383
        </listitem>
380
384
      </varlistentry>
441
445
    </para>
442
446
    <variablelist>
443
447
      <varlistentry>
444
 
        <term><filename>/etc/mandos/seckey.txt</filename></term>
 
448
        <term><filename>/etc/keys/mandos/seckey.txt</filename></term>
445
449
        <listitem>
446
450
          <para>
447
451
            OpenPGP secret key file which will be created or
450
454
        </listitem>
451
455
      </varlistentry>
452
456
      <varlistentry>
453
 
        <term><filename>/etc/mandos/pubkey.txt</filename></term>
 
457
        <term><filename>/etc/keys/mandos/pubkey.txt</filename></term>
454
458
        <listitem>
455
459
          <para>
456
460
            OpenPGP public key file which will be created or
488
492
  
489
493
  <refsect1 id="bugs">
490
494
    <title>BUGS</title>
 
495
    <para>
 
496
      The <option>--password</option>/<option>-p</option> option
 
497
      strips white space from the start and from the end of the
 
498
      password before using it.  If this is a problem, use the
 
499
      <option>--passfile</option> option instead, which does not do
 
500
      this.
 
501
    </para>
491
502
    <xi:include href="bugs.xml"/>
492
503
  </refsect1>
493
504
  
515
526
    </informalexample>
516
527
    <informalexample>
517
528
      <para>
518
 
        Prompt for a password, encrypt it with the key in <filename
519
 
        class="directory">/etc/mandos</filename> and output a section
520
 
        suitable for <filename>clients.conf</filename>.
 
529
        Prompt for a password, encrypt it with the keys in <filename
 
530
        class="directory">/etc/keys/mandos</filename> and output a
 
531
        section suitable for <filename>clients.conf</filename>.
521
532
      </para>
522
533
      <para>
523
534
        <userinput>&COMMANDNAME; --password</userinput>
525
536
    </informalexample>
526
537
    <informalexample>
527
538
      <para>
528
 
        Prompt for a password, encrypt it with the key in the
 
539
        Prompt for a password, encrypt it with the keys in the
529
540
        <filename>client-key</filename> directory and output a section
530
541
        suitable for <filename>clients.conf</filename>.
531
542
      </para>