/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
1
1
<?xml version="1.0" encoding="UTF-8"?>
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
 
<!ENTITY VERSION "1.0">
5
4
<!ENTITY COMMANDNAME "mandos-keygen">
6
 
<!ENTITY TIMESTAMP "2008-09-20">
 
5
<!ENTITY TIMESTAMP "2019-07-18">
 
6
<!ENTITY % common SYSTEM "common.ent">
 
7
%common;
7
8
]>
8
9
 
9
10
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
11
12
    <title>Mandos Manual</title>
12
13
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
13
14
    <productname>Mandos</productname>
14
 
    <productnumber>&VERSION;</productnumber>
 
15
    <productnumber>&version;</productnumber>
15
16
    <date>&TIMESTAMP;</date>
16
17
    <authorgroup>
17
18
      <author>
18
19
        <firstname>Björn</firstname>
19
20
        <surname>Påhlsson</surname>
20
21
        <address>
21
 
          <email>belorn@fukt.bsnet.se</email>
 
22
          <email>belorn@recompile.se</email>
22
23
        </address>
23
24
      </author>
24
25
      <author>
25
26
        <firstname>Teddy</firstname>
26
27
        <surname>Hogeborn</surname>
27
28
        <address>
28
 
          <email>teddy@fukt.bsnet.se</email>
 
29
          <email>teddy@recompile.se</email>
29
30
        </address>
30
31
      </author>
31
32
    </authorgroup>
32
33
    <copyright>
33
34
      <year>2008</year>
 
35
      <year>2009</year>
 
36
      <year>2010</year>
 
37
      <year>2011</year>
 
38
      <year>2012</year>
 
39
      <year>2013</year>
 
40
      <year>2014</year>
 
41
      <year>2015</year>
 
42
      <year>2016</year>
 
43
      <year>2017</year>
 
44
      <year>2018</year>
 
45
      <year>2019</year>
34
46
      <holder>Teddy Hogeborn</holder>
35
47
      <holder>Björn Påhlsson</holder>
36
48
    </copyright>
115
127
        <replaceable>TIME</replaceable></option></arg>
116
128
      </group>
117
129
      <sbr/>
118
 
      <arg><option>--force</option></arg>
 
130
      <group>
 
131
        <arg choice="plain"><option>--tls-keytype
 
132
        <replaceable>KEYTYPE</replaceable></option></arg>
 
133
        <arg choice="plain"><option>-T
 
134
        <replaceable>KEYTYPE</replaceable></option></arg>
 
135
      </group>
 
136
      <sbr/>
 
137
      <group>
 
138
        <arg choice="plain"><option>--force</option></arg>
 
139
        <arg choice="plain"><option>-f</option></arg>
 
140
      </group>
119
141
    </cmdsynopsis>
120
142
    <cmdsynopsis>
121
143
      <command>&COMMANDNAME;</command>
141
163
        <arg choice="plain"><option>-n
142
164
        <replaceable>NAME</replaceable></option></arg>
143
165
      </group>
 
166
      <group>
 
167
        <arg choice="plain"><option>--no-ssh</option></arg>
 
168
        <arg choice="plain"><option>-S</option></arg>
 
169
      </group>
144
170
    </cmdsynopsis>
145
171
    <cmdsynopsis>
146
172
      <command>&COMMANDNAME;</command>
162
188
    <title>DESCRIPTION</title>
163
189
    <para>
164
190
      <command>&COMMANDNAME;</command> is a program to generate the
165
 
      OpenPGP key used by
 
191
      TLS and OpenPGP keys used by
166
192
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
167
 
      <manvolnum>8mandos</manvolnum></citerefentry>.  The key is
168
 
      normally written to /etc/mandos for later installation into the
169
 
      initrd image, but this, and most other things, can be changed
170
 
      with command line options.
 
193
      <manvolnum>8mandos</manvolnum></citerefentry>.  The keys are
 
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.
171
197
    </para>
172
198
    <para>
173
199
      This program can also be used with the
210
236
        <replaceable>DIRECTORY</replaceable></option></term>
211
237
        <listitem>
212
238
          <para>
213
 
            Target directory for key files.  Default is
214
 
            <filename>/etc/mandos</filename>.
 
239
            Target directory for key files.  Default is <filename
 
240
            class="directory">/etc/keys/mandos</filename>.
215
241
          </para>
216
242
        </listitem>
217
243
      </varlistentry>
223
249
        <replaceable>TYPE</replaceable></option></term>
224
250
        <listitem>
225
251
          <para>
226
 
            Key type.  Default is <quote>DSA</quote>.
 
252
            OpenPGP key type.  Default is <quote>RSA</quote>.
227
253
          </para>
228
254
        </listitem>
229
255
      </varlistentry>
235
261
        <replaceable>BITS</replaceable></option></term>
236
262
        <listitem>
237
263
          <para>
238
 
            Key length in bits.  Default is 2048.
 
264
            OpenPGP key length in bits.  Default is 4096.
239
265
          </para>
240
266
        </listitem>
241
267
      </varlistentry>
247
273
        <replaceable>KEYTYPE</replaceable></option></term>
248
274
        <listitem>
249
275
          <para>
250
 
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
251
 
            encryption-only).
 
276
            OpenPGP subkey type.  Default is <quote>RSA</quote>
252
277
          </para>
253
278
        </listitem>
254
279
      </varlistentry>
260
285
        <replaceable>BITS</replaceable></option></term>
261
286
        <listitem>
262
287
          <para>
263
 
            Subkey length in bits.  Default is 2048.
 
288
            OpenPGP subkey length in bits.  Default is 4096.
264
289
          </para>
265
290
        </listitem>
266
291
      </varlistentry>
284
309
        <replaceable>TEXT</replaceable></option></term>
285
310
        <listitem>
286
311
          <para>
287
 
            Comment field for key.  The default value is
288
 
            <quote><literal>Mandos client key</literal></quote>.
 
312
            Comment field for key.  Default is empty.
289
313
          </para>
290
314
        </listitem>
291
315
      </varlistentry>
305
329
      </varlistentry>
306
330
      
307
331
      <varlistentry>
 
332
        <term><option>--tls-keytype
 
333
        <replaceable>KEYTYPE</replaceable></option></term>
 
334
        <term><option>-T
 
335
        <replaceable>KEYTYPE</replaceable></option></term>
 
336
        <listitem>
 
337
          <para>
 
338
            TLS key type.  Default is <quote>ed25519</quote>
 
339
          </para>
 
340
        </listitem>
 
341
      </varlistentry>
 
342
      
 
343
      <varlistentry>
308
344
        <term><option>--force</option></term>
309
345
        <term><option>-f</option></term>
310
346
        <listitem>
319
355
        <listitem>
320
356
          <para>
321
357
            Prompt for a password and encrypt it with the key already
322
 
            present in either <filename>/etc/mandos</filename> or the
323
 
            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>
324
360
            option.  Outputs, on standard output, a section suitable
325
361
            for inclusion in <citerefentry><refentrytitle
326
362
            >mandos-clients.conf</refentrytitle><manvolnum
327
363
            >8</manvolnum></citerefentry>.  The host name or the name
328
364
            specified with the <option>--name</option> option is used
329
365
            for the section header.  All other options are ignored,
330
 
            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"/>.
331
369
          </para>
332
370
        </listitem>
333
371
      </varlistentry>
339
377
        <listitem>
340
378
          <para>
341
379
            The same as <option>--password</option>, but read from
342
 
            <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.
 
382
          </para>
 
383
        </listitem>
 
384
      </varlistentry>
 
385
      <varlistentry>
 
386
        <term><option>--no-ssh</option></term>
 
387
        <term><option>-S</option></term>
 
388
        <listitem>
 
389
          <para>
 
390
            When <option>--password</option> or
 
391
            <option>--passfile</option> is given, this option will
 
392
            prevent <command>&COMMANDNAME;</command> from calling
 
393
            <command>ssh-keyscan</command> to get an SSH fingerprint
 
394
            for this host and, if successful, output suitable config
 
395
            options to use this fingerprint as a
 
396
            <option>checker</option> option in the output.  This is
 
397
            otherwise the default behavior.
343
398
          </para>
344
399
        </listitem>
345
400
      </varlistentry>
350
405
    <title>OVERVIEW</title>
351
406
    <xi:include href="overview.xml"/>
352
407
    <para>
353
 
      This program is a small utility to generate new OpenPGP keys for
354
 
      new Mandos clients, and to generate sections for inclusion in
355
 
      <filename>clients.conf</filename> on the server.
 
408
      This program is a small utility to generate new TLS and OpenPGP
 
409
      keys for new Mandos clients, and to generate sections for
 
410
      inclusion in <filename>clients.conf</filename> on the server.
356
411
    </para>
357
412
  </refsect1>
358
413
  
381
436
    </variablelist>
382
437
  </refsect1>
383
438
  
384
 
  <refsect1 id="file">
 
439
  <refsect1 id="files">
385
440
    <title>FILES</title>
386
441
    <para>
387
442
      Use the <option>--dir</option> option to change where
390
445
    </para>
391
446
    <variablelist>
392
447
      <varlistentry>
393
 
        <term><filename>/etc/mandos/seckey.txt</filename></term>
 
448
        <term><filename>/etc/keys/mandos/seckey.txt</filename></term>
394
449
        <listitem>
395
450
          <para>
396
451
            OpenPGP secret key file which will be created or
399
454
        </listitem>
400
455
      </varlistentry>
401
456
      <varlistentry>
402
 
        <term><filename>/etc/mandos/pubkey.txt</filename></term>
 
457
        <term><filename>/etc/keys/mandos/pubkey.txt</filename></term>
403
458
        <listitem>
404
459
          <para>
405
460
            OpenPGP public key file which will be created or
408
463
        </listitem>
409
464
      </varlistentry>
410
465
      <varlistentry>
411
 
        <term><filename>/tmp</filename></term>
 
466
        <term><filename>/etc/keys/mandos/tls-privkey.pem</filename></term>
 
467
        <listitem>
 
468
          <para>
 
469
            Private key file which will be created or overwritten.
 
470
          </para>
 
471
        </listitem>
 
472
      </varlistentry>
 
473
      <varlistentry>
 
474
        <term><filename>/etc/keys/mandos/tls-pubkey.pem</filename></term>
 
475
        <listitem>
 
476
          <para>
 
477
            Public key file which will be created or overwritten.
 
478
          </para>
 
479
        </listitem>
 
480
      </varlistentry>
 
481
      <varlistentry>
 
482
        <term><filename class="directory">/tmp</filename></term>
412
483
        <listitem>
413
484
          <para>
414
485
            Temporary files will be written here if
419
490
    </variablelist>
420
491
  </refsect1>
421
492
  
422
 
<!--   <refsect1 id="bugs"> -->
423
 
<!--     <title>BUGS</title> -->
424
 
<!--     <para> -->
425
 
<!--     </para> -->
426
 
<!--   </refsect1> -->
 
493
  <refsect1 id="bugs">
 
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>
 
502
    <xi:include href="bugs.xml"/>
 
503
  </refsect1>
427
504
  
428
505
  <refsect1 id="example">
429
506
    <title>EXAMPLE</title>
449
526
    </informalexample>
450
527
    <informalexample>
451
528
      <para>
452
 
        Prompt for a password, encrypt it with the key in
453
 
        <filename>/etc/mandos</filename> and output a section suitable
454
 
        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>.
455
532
      </para>
456
533
      <para>
457
534
        <userinput>&COMMANDNAME; --password</userinput>
459
536
    </informalexample>
460
537
    <informalexample>
461
538
      <para>
462
 
        Prompt for a password, encrypt it with the key in the
 
539
        Prompt for a password, encrypt it with the keys in the
463
540
        <filename>client-key</filename> directory and output a section
464
541
        suitable for <filename>clients.conf</filename>.
465
542
      </para>
490
567
  <refsect1 id="see_also">
491
568
    <title>SEE ALSO</title>
492
569
    <para>
 
570
      <citerefentry><refentrytitle>intro</refentrytitle>
 
571
      <manvolnum>8mandos</manvolnum></citerefentry>,
493
572
      <citerefentry><refentrytitle>gpg</refentrytitle>
494
573
      <manvolnum>1</manvolnum></citerefentry>,
495
574
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
497
576
      <citerefentry><refentrytitle>mandos</refentrytitle>
498
577
      <manvolnum>8</manvolnum></citerefentry>,
499
578
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
500
 
      <manvolnum>8mandos</manvolnum></citerefentry>
 
579
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
580
      <citerefentry><refentrytitle>ssh-keyscan</refentrytitle>
 
581
      <manvolnum>1</manvolnum></citerefentry>
501
582
    </para>
502
583
  </refsect1>
503
584