/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-ctl.xml

  • Committer: Teddy Hogeborn
  • Date: 2019-02-10 03:50:20 UTC
  • Revision ID: teddy@recompile.se-20190210035020-nttr1tybgwwixueu
http://bugs.debian.org/879538
http://bugs.debian.org/916673
Show debconf note about new TLS key IDs

If mandos-client did not see TLS keys and had to create them, or if
mandos sees GnuTLS version 3.6.6 or later, show an important notice on
package installation about the importance of adding the new key_id
options to clients.conf on the Mandos server.

* debian/control (Package: mandos, Package: mandos-client): Depend on
                                                            debconf.
* debian/mandos-client.lintian-overrides: Override warnings.
* debian/mandos-client.postinst (create_keys): Show notice if new TLS
                                               key files were created.
* debian/mandos-client.templates: New.
* debian/mandos.lintian-overrides: Override warnings.
* debian/mandos.postinst (configure): If GnuTLS 3.6.6 or later is
                                      detected, show an important
                                      notice (once) about the new
                                      key_id option required in
                                      clients.conf.
* debian/mandos.templates: New.

Show diffs side-by-side

added added

removed removed

Lines of Context:
mandos-ctl.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-ctl">
5
 
<!ENTITY TIMESTAMP "2010-09-21">
 
5
<!ENTITY TIMESTAMP "2018-02-08">
6
6
<!ENTITY % common SYSTEM "common.ent">
7
7
%common;
8
8
]>
19
19
        <firstname>Björn</firstname>
20
20
        <surname>Påhlsson</surname>
21
21
        <address>
22
 
          <email>belorn@fukt.bsnet.se</email>
 
22
          <email>belorn@recompile.se</email>
23
23
        </address>
24
24
      </author>
25
25
      <author>
26
26
        <firstname>Teddy</firstname>
27
27
        <surname>Hogeborn</surname>
28
28
        <address>
29
 
          <email>teddy@fukt.bsnet.se</email>
 
29
          <email>teddy@recompile.se</email>
30
30
        </address>
31
31
      </author>
32
32
    </authorgroup>
33
33
    <copyright>
34
34
      <year>2010</year>
 
35
      <year>2011</year>
 
36
      <year>2012</year>
 
37
      <year>2013</year>
 
38
      <year>2014</year>
 
39
      <year>2015</year>
 
40
      <year>2016</year>
 
41
      <year>2017</year>
 
42
      <year>2018</year>
35
43
      <holder>Teddy Hogeborn</holder>
36
44
      <holder>Björn Påhlsson</holder>
37
45
    </copyright>
46
54
  <refnamediv>
47
55
    <refname><command>&COMMANDNAME;</command></refname>
48
56
    <refpurpose>
49
 
      Control the operation of the Mandos server
 
57
      Control or query the operation of the Mandos server
50
58
    </refpurpose>
51
59
  </refnamediv>
52
60
  
53
61
  <refsynopsisdiv>
54
62
    <cmdsynopsis>
55
63
      <command>&COMMANDNAME;</command>
56
 
      <group>
57
 
        <arg choice="plain"><option>--enable</option></arg>
58
 
        <arg choice="plain"><option>-e</option></arg>
59
 
        <sbr/>
60
 
        <arg choice="plain"><option>--disable</option></arg>
61
 
        <arg choice="plain"><option>-d</option></arg>
62
 
      </group>
63
 
      <sbr/>
64
 
      <group>
65
 
        <arg choice="plain"><option>--bump-timeout</option></arg>
66
 
        <arg choice="plain"><option>-b</option></arg>
67
 
      </group>
68
 
      <sbr/>
69
 
      <group>
70
 
        <arg choice="plain"><option>--start-checker</option></arg>
71
 
      </group>
72
 
      <sbr/>
73
 
      <group>
74
 
        <arg choice="plain"><option>--stop-checker</option></arg>
75
 
      </group>
76
 
      <sbr/>
77
 
      <group>
78
 
        <arg choice="plain"><option>--remove</option></arg>
79
 
        <arg choice="plain"><option>-r</option></arg>
80
 
      </group>
81
 
      <sbr/>
82
 
      <group>
83
 
        <arg choice="plain"><option>--checker
84
 
        <replaceable>COMMAND</replaceable></option></arg>
85
 
        <arg choice="plain"><option>-c
86
 
        <replaceable>COMMAND</replaceable></option></arg>
87
 
      </group>
88
 
      <sbr/>
89
 
      <group>
90
 
        <arg choice="plain"><option>--timeout
91
 
        <replaceable>TIME</replaceable></option></arg>
92
 
        <arg choice="plain"><option>-t
93
 
        <replaceable>TIME</replaceable></option></arg>
94
 
      </group>
95
 
      <sbr/>
96
 
      <group>
97
 
        <arg choice="plain"><option>--interval
98
 
        <replaceable>TIME</replaceable></option></arg>
99
 
        <arg choice="plain"><option>-i
100
 
        <replaceable>TIME</replaceable></option></arg>
101
 
      </group>
102
 
      <sbr/>
103
 
      <group>
104
 
        <arg choice="plain"><option>--host
105
 
        <replaceable>STRING</replaceable></option></arg>
106
 
        <arg choice="plain"><option>-H
107
 
        <replaceable>STRING</replaceable></option></arg>
108
 
      </group>
109
 
      <sbr/>
110
 
      <group>
111
 
        <arg choice="plain"><option>--secret
112
 
        <replaceable>FILENAME</replaceable></option></arg>
113
 
        <arg choice="plain"><option>-s
114
 
        <replaceable>FILENAME</replaceable></option></arg>
115
 
      </group>
116
 
      <sbr/>
117
 
      <group>
118
 
        <arg choice="plain"><option>--approve</option></arg>
119
 
        <arg choice="plain"><option>-A</option></arg>
120
 
        <sbr/>
121
 
        <arg choice="plain"><option>--deny</option></arg>
122
 
        <arg choice="plain"><option>-D</option></arg>
 
64
      <group choice="req">
 
65
        <group>
 
66
          <arg choice="plain"><option>--enable</option></arg>
 
67
          <arg choice="plain"><option>-e</option></arg>
 
68
          <sbr/>
 
69
          <arg choice="plain"><option>--disable</option></arg>
 
70
          <arg choice="plain"><option>-d</option></arg>
 
71
        </group>
 
72
        <sbr/>
 
73
        <group>
 
74
          <arg choice="plain"><option>--bump-timeout</option></arg>
 
75
          <arg choice="plain"><option>-b</option></arg>
 
76
        </group>
 
77
        <sbr/>
 
78
        <group>
 
79
          <arg choice="plain"><option>--start-checker</option></arg>
 
80
        </group>
 
81
        <sbr/>
 
82
        <group>
 
83
          <arg choice="plain"><option>--stop-checker</option></arg>
 
84
        </group>
 
85
        <sbr/>
 
86
        <group>
 
87
          <arg choice="plain"><option>--remove</option></arg>
 
88
          <arg choice="plain"><option>-r</option></arg>
 
89
        </group>
 
90
        <sbr/>
 
91
        <group>
 
92
          <arg choice="plain"><option>--checker
 
93
          <replaceable>COMMAND</replaceable></option></arg>
 
94
          <arg choice="plain"><option>-c
 
95
          <replaceable>COMMAND</replaceable></option></arg>
 
96
        </group>
 
97
        <sbr/>
 
98
        <group>
 
99
          <arg choice="plain"><option>--timeout
 
100
          <replaceable>TIME</replaceable></option></arg>
 
101
          <arg choice="plain"><option>-t
 
102
          <replaceable>TIME</replaceable></option></arg>
 
103
        </group>
 
104
        <sbr/>
 
105
        <group>
 
106
          <arg choice="plain"><option>--extended-timeout
 
107
          <replaceable>TIME</replaceable></option></arg>
 
108
        </group>
 
109
        <sbr/>
 
110
        <group>
 
111
          <arg choice="plain"><option>--interval
 
112
          <replaceable>TIME</replaceable></option></arg>
 
113
          <arg choice="plain"><option>-i
 
114
          <replaceable>TIME</replaceable></option></arg>
 
115
        </group>
 
116
        <sbr/>
 
117
        <group>
 
118
          <arg choice="plain"><option>--approve-by-default</option
 
119
          ></arg>
 
120
          <sbr/>
 
121
          <arg choice="plain"><option>--deny-by-default</option></arg>
 
122
        </group>
 
123
        <sbr/>
 
124
        <group>
 
125
          <arg choice="plain"><option>--approval-delay
 
126
          <replaceable>TIME</replaceable></option></arg>
 
127
        </group>
 
128
        <sbr/>
 
129
        <group>
 
130
          <arg choice="plain"><option>--approval-duration
 
131
          <replaceable>TIME</replaceable></option></arg>
 
132
        </group>
 
133
        <sbr/>
 
134
        <group>
 
135
          <arg choice="plain"><option>--interval
 
136
          <replaceable>TIME</replaceable></option></arg>
 
137
          <arg choice="plain"><option>-i
 
138
          <replaceable>TIME</replaceable></option></arg>
 
139
        </group>
 
140
        <sbr/>
 
141
        <group>
 
142
          <arg choice="plain"><option>--host
 
143
          <replaceable>STRING</replaceable></option></arg>
 
144
          <arg choice="plain"><option>-H
 
145
          <replaceable>STRING</replaceable></option></arg>
 
146
        </group>
 
147
        <sbr/>
 
148
        <group>
 
149
          <arg choice="plain"><option>--secret
 
150
          <replaceable>FILENAME</replaceable></option></arg>
 
151
          <arg choice="plain"><option>-s
 
152
          <replaceable>FILENAME</replaceable></option></arg>
 
153
        </group>
 
154
        <sbr/>
 
155
        <group>
 
156
          <arg choice="plain"><option>--approve</option></arg>
 
157
          <arg choice="plain"><option>-A</option></arg>
 
158
          <sbr/>
 
159
          <arg choice="plain"><option>--deny</option></arg>
 
160
          <arg choice="plain"><option>-D</option></arg>
 
161
        </group>
123
162
      </group>
124
163
      <sbr/>
125
164
      <group choice="req">
133
172
    <cmdsynopsis>
134
173
      <command>&COMMANDNAME;</command>
135
174
      <group>
136
 
        <arg choice="plain"><option>--verbose</option></arg>
137
 
        <arg choice="plain"><option>-v</option></arg>
 
175
          <arg choice="plain"><option>--verbose</option></arg>
 
176
          <arg choice="plain"><option>-v</option></arg>
 
177
          <sbr/>
 
178
          <arg choice="plain"><option>--dump-json</option></arg>
 
179
          <arg choice="plain"><option>-j</option></arg>
138
180
      </group>
139
181
      <group>
140
182
        <arg rep='repeat' choice='plain'>
164
206
        <arg choice="plain"><option>-v</option></arg>
165
207
      </group>
166
208
    </cmdsynopsis>
 
209
    <cmdsynopsis>
 
210
      <command>&COMMANDNAME;</command>
 
211
      <arg choice="plain"><option>--check</option></arg>
 
212
    </cmdsynopsis>
167
213
  </refsynopsisdiv>
168
214
  
169
215
  <refsect1 id="description">
170
216
    <title>DESCRIPTION</title>
171
217
    <para>
172
 
      <command>&COMMANDNAME;</command> is a program to control the
173
 
      operation of the Mandos server <citerefentry><refentrytitle
174
 
      >mandos</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 
218
      <command>&COMMANDNAME;</command> is a program to control or
 
219
      query the operation of the Mandos server
 
220
      <citerefentry><refentrytitle>mandos</refentrytitle><manvolnum
 
221
      >8</manvolnum></citerefentry>.
175
222
    </para>
176
223
    <para>
177
224
      This program can be used to change client settings, approve or
273
320
          <para>
274
321
            Set the <varname>checker</varname> option of the specified
275
322
            client(s); see <citerefentry><refentrytitle
276
 
            >mandos-client.conf</refentrytitle><manvolnum>5</manvolnum
277
 
            ></citerefentry>.
 
323
            >mandos-clients.conf</refentrytitle><manvolnum
 
324
            >5</manvolnum></citerefentry>.
278
325
          </para>
279
326
        </listitem>
280
327
      </varlistentry>
288
335
          <para>
289
336
            Set the <varname>timeout</varname> option of the specified
290
337
            client(s); see <citerefentry><refentrytitle
291
 
            >mandos-client.conf</refentrytitle><manvolnum>5</manvolnum
292
 
            ></citerefentry>.
 
338
            >mandos-clients.conf</refentrytitle><manvolnum
 
339
            >5</manvolnum></citerefentry>.
 
340
          </para>
 
341
        </listitem>
 
342
      </varlistentry>
 
343
 
 
344
      <varlistentry>
 
345
        <term><option>--extended-timeout
 
346
        <replaceable>TIME</replaceable></option></term>
 
347
        <listitem>
 
348
          <para>
 
349
            Set the <varname>extended_timeout</varname> option of the
 
350
            specified client(s); see <citerefentry><refentrytitle
 
351
            >mandos-clients.conf</refentrytitle><manvolnum
 
352
            >5</manvolnum></citerefentry>.
293
353
          </para>
294
354
        </listitem>
295
355
      </varlistentry>
301
361
        <replaceable>TIME</replaceable></option></term>
302
362
        <listitem>
303
363
          <para>
304
 
            Set the <varname>interval</varname> option of the specified
305
 
            client(s); see <citerefentry><refentrytitle
306
 
            >mandos-client.conf</refentrytitle><manvolnum>5</manvolnum
307
 
            ></citerefentry>.
 
364
            Set the <varname>interval</varname> option of the
 
365
            specified client(s); see <citerefentry><refentrytitle
 
366
            >mandos-clients.conf</refentrytitle><manvolnum
 
367
            >5</manvolnum></citerefentry>.
 
368
          </para>
 
369
        </listitem>
 
370
      </varlistentry>
 
371
      
 
372
      <varlistentry>
 
373
        <term><option>--approve-by-default</option></term>
 
374
        <term><option>--deny-by-default</option></term>
 
375
        <listitem>
 
376
          <para>
 
377
            Set the <varname>approved_by_default</varname> option of
 
378
            the specified client(s) to <literal>True</literal> or
 
379
            <literal>False</literal>, respectively; see
 
380
            <citerefentry><refentrytitle
 
381
            >mandos-clients.conf</refentrytitle><manvolnum
 
382
            >5</manvolnum></citerefentry>.
 
383
          </para>
 
384
        </listitem>
 
385
      </varlistentry>
 
386
      
 
387
      <varlistentry>
 
388
        <term><option>--approval-delay
 
389
        <replaceable>TIME</replaceable></option></term>
 
390
        <listitem>
 
391
          <para>
 
392
            Set the <varname>approval_delay</varname> option of the
 
393
            specified client(s); see <citerefentry><refentrytitle
 
394
            >mandos-clients.conf</refentrytitle><manvolnum
 
395
            >5</manvolnum></citerefentry>.
 
396
          </para>
 
397
        </listitem>
 
398
      </varlistentry>
 
399
      
 
400
      <varlistentry>
 
401
        <term><option>--approval-duration
 
402
        <replaceable>TIME</replaceable></option></term>
 
403
        <listitem>
 
404
          <para>
 
405
            Set the <varname>approval_duration</varname> option of the
 
406
            specified client(s); see <citerefentry><refentrytitle
 
407
            >mandos-clients.conf</refentrytitle><manvolnum
 
408
            >5</manvolnum></citerefentry>.
308
409
          </para>
309
410
        </listitem>
310
411
      </varlistentry>
318
419
          <para>
319
420
            Set the <varname>host</varname> option of the specified
320
421
            client(s); see <citerefentry><refentrytitle
321
 
            >mandos-client.conf</refentrytitle><manvolnum>5</manvolnum
322
 
            ></citerefentry>.
 
422
            >mandos-clients.conf</refentrytitle><manvolnum
 
423
            >5</manvolnum></citerefentry>.
323
424
          </para>
324
425
        </listitem>
325
426
      </varlistentry>
333
434
          <para>
334
435
            Set the <varname>secfile</varname> option of the specified
335
436
            client(s); see <citerefentry><refentrytitle
336
 
            >mandos-client.conf</refentrytitle><manvolnum>5</manvolnum
337
 
            ></citerefentry>.
 
437
            >mandos-clients.conf</refentrytitle><manvolnum
 
438
            >5</manvolnum></citerefentry>.
338
439
          </para>
339
440
        </listitem>
340
441
      </varlistentry>
381
482
      </varlistentry>
382
483
      
383
484
      <varlistentry>
 
485
        <term><option>--dump-json</option></term>
 
486
        <term><option>-j</option></term>
 
487
        <listitem>
 
488
          <para>
 
489
            Dump client settings as JSON to standard output.
 
490
          </para>
 
491
        </listitem>
 
492
      </varlistentry>
 
493
      
 
494
      <varlistentry>
384
495
        <term><option>--is-enabled</option></term>
385
496
        <term><option>-V</option></term>
386
497
        <listitem>
391
502
        </listitem>
392
503
      </varlistentry>
393
504
      
 
505
      <varlistentry>
 
506
        <term><option>--check</option></term>
 
507
        <listitem>
 
508
          <para>
 
509
            Run self-tests.  This includes any unit tests, etc.
 
510
          </para>
 
511
        </listitem>
 
512
      </varlistentry>
 
513
      
394
514
    </variablelist>
395
515
  </refsect1>
396
516
  
412
532
    </para>
413
533
  </refsect1>
414
534
  
415
 
<!--   <refsect1 id="bugs"> -->
416
 
<!--     <title>BUGS</title> -->
417
 
<!--     <para> -->
418
 
<!--     </para> -->
419
 
<!--   </refsect1> -->
 
535
  <refsect1 id="bugs">
 
536
    <title>BUGS</title>
 
537
    <xi:include href="bugs.xml"/>
 
538
  </refsect1>
420
539
  
421
540
  <refsect1 id="example">
422
541
    <title>EXAMPLE</title>
423
542
    <informalexample>
424
543
      <para>
425
 
        List all clients with some of their settings:
 
544
        To list all clients:
426
545
      </para>
427
546
      <para>
428
547
        <userinput>&COMMANDNAME;</userinput>
429
548
      </para>
430
549
    </informalexample>
431
 
    <informalexample>
432
 
      <para>
433
 
        Show all settings for the clients named <quote>foo</quote> and
434
 
        <quote>bar</quote>:
435
 
      </para>
436
 
      <para>
437
 
 
438
 
<!-- do not wrap this line -->
439
 
<userinput>&COMMANDNAME; --verbose foo bar</userinput>
440
 
 
 
550
    
 
551
    <informalexample>
 
552
      <para>
 
553
        To list <emphasis>all</emphasis> settings for the clients
 
554
        named <quote>foo1.example.org</quote> and <quote
 
555
        >foo2.example.org</quote>:
 
556
      </para>
 
557
      <para>
 
558
 
 
559
<!-- do not wrap this line -->
 
560
<userinput>&COMMANDNAME; --verbose foo1.example.org foo2.example.org</userinput>
 
561
 
 
562
      </para>
 
563
    </informalexample>
 
564
    
 
565
    <informalexample>
 
566
      <para>
 
567
        To enable all clients:
 
568
      </para>
 
569
      <para>
 
570
        <userinput>&COMMANDNAME; --enable --all</userinput>
 
571
      </para>
 
572
    </informalexample>
 
573
    
 
574
    <informalexample>
 
575
      <para>
 
576
        To change timeout and interval value for the clients
 
577
        named <quote>foo1.example.org</quote> and <quote
 
578
        >foo2.example.org</quote>:
 
579
      </para>
 
580
      <para>
 
581
 
 
582
<!-- do not wrap this line -->
 
583
<userinput>&COMMANDNAME; --timeout="5m" --interval="1m" foo1.example.org foo2.example.org</userinput>
 
584
 
 
585
      </para>
 
586
    </informalexample>
 
587
    
 
588
    <informalexample>
 
589
      <para>
 
590
        To approve all clients currently waiting for it:
 
591
      </para>
 
592
      <para>
 
593
        <userinput>&COMMANDNAME; --approve --all</userinput>
441
594
      </para>
442
595
    </informalexample>
443
596
  </refsect1>
454
607
  <refsect1 id="see_also">
455
608
    <title>SEE ALSO</title>
456
609
    <para>
 
610
      <citerefentry><refentrytitle>intro</refentrytitle>
 
611
      <manvolnum>8mandos</manvolnum></citerefentry>,
457
612
      <citerefentry><refentrytitle>mandos</refentrytitle>
458
613
      <manvolnum>8</manvolnum></citerefentry>,
459
614
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>