/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-08-05 21:14:05 UTC
  • Revision ID: teddy@recompile.se-20190805211405-9m6hecekaihpttz9
Override lintian warnings about upgrading from old versions

There are some really things which are imperative that we fix in case
someone were to upgrade from a really old version.  We want to keep
these fixes in the postinst maintainer scripts, even though lintian
complains about such old upgrades not being supported by Debian in
general.  We prefer the code being there, for the sake of the users.

* debian/mandos-client.lintian-overrides
  (maintainer-script-supports-ancient-package-version): New.
  debian/mandos.lintian-overrides
  (maintainer-script-supports-ancient-package-version): - '' -

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 "2019-07-29">
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>
 
43
      <year>2019</year>
35
44
      <holder>Teddy Hogeborn</holder>
36
45
      <holder>Björn Påhlsson</holder>
37
46
    </copyright>
46
55
  <refnamediv>
47
56
    <refname><command>&COMMANDNAME;</command></refname>
48
57
    <refpurpose>
49
 
      Control the operation of the Mandos server
 
58
      Control or query the operation of the Mandos server
50
59
    </refpurpose>
51
60
  </refnamediv>
52
61
  
54
63
    <cmdsynopsis>
55
64
      <command>&COMMANDNAME;</command>
56
65
      <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/>
 
66
          <arg choice="plain"><option>--verbose</option></arg>
 
67
          <arg choice="plain"><option>-v</option></arg>
 
68
          <sbr/>
 
69
          <arg choice="plain"><option>--dump-json</option></arg>
 
70
          <arg choice="plain"><option>-j</option></arg>
 
71
      </group>
 
72
      <arg><option>--debug</option></arg>
 
73
      <group>
 
74
        <arg rep='repeat' choice='plain'>
 
75
          <replaceable>CLIENT</replaceable>
 
76
        </arg>
 
77
      </group>
 
78
    </cmdsynopsis>
 
79
    <cmdsynopsis>
 
80
      <command>&COMMANDNAME;</command>
 
81
      <group choice="req">
 
82
        <group>
 
83
          <arg choice="plain"><option>--enable</option></arg>
 
84
          <arg choice="plain"><option>-e</option></arg>
 
85
          <sbr/>
 
86
          <arg choice="plain"><option>--disable</option></arg>
 
87
          <arg choice="plain"><option>-d</option></arg>
 
88
        </group>
 
89
        <sbr/>
 
90
        <group>
 
91
          <arg choice="plain"><option>--bump-timeout</option></arg>
 
92
          <arg choice="plain"><option>-b</option></arg>
 
93
        </group>
 
94
        <sbr/>
 
95
        <group>
 
96
          <arg choice="plain"><option>--start-checker</option></arg>
 
97
          <arg choice="plain"><option>--stop-checker</option></arg>
 
98
        </group>
 
99
        <sbr/>
 
100
        <group>
 
101
          <arg choice="plain"><option>--checker
 
102
          <replaceable>COMMAND</replaceable></option></arg>
 
103
          <arg choice="plain"><option>-c
 
104
          <replaceable>COMMAND</replaceable></option></arg>
 
105
        </group>
 
106
        <sbr/>
 
107
        <group>
 
108
          <arg choice="plain"><option>--timeout
 
109
          <replaceable>TIME</replaceable></option></arg>
 
110
          <arg choice="plain"><option>-t
 
111
          <replaceable>TIME</replaceable></option></arg>
 
112
        </group>
 
113
        <sbr/>
 
114
        <group>
 
115
          <arg choice="plain"><option>--extended-timeout
 
116
          <replaceable>TIME</replaceable></option></arg>
 
117
        </group>
 
118
        <sbr/>
 
119
        <group>
 
120
          <arg choice="plain"><option>--interval
 
121
          <replaceable>TIME</replaceable></option></arg>
 
122
          <arg choice="plain"><option>-i
 
123
          <replaceable>TIME</replaceable></option></arg>
 
124
        </group>
 
125
        <sbr/>
 
126
        <group>
 
127
          <arg choice="plain"><option>--approve-by-default</option
 
128
          ></arg>
 
129
          <sbr/>
 
130
          <arg choice="plain"><option>--deny-by-default</option></arg>
 
131
        </group>
 
132
        <sbr/>
 
133
        <group>
 
134
          <arg choice="plain"><option>--approval-delay
 
135
          <replaceable>TIME</replaceable></option></arg>
 
136
        </group>
 
137
        <sbr/>
 
138
        <group>
 
139
          <arg choice="plain"><option>--approval-duration
 
140
          <replaceable>TIME</replaceable></option></arg>
 
141
        </group>
 
142
        <sbr/>
 
143
        <group>
 
144
          <arg choice="plain"><option>--host
 
145
          <replaceable>STRING</replaceable></option></arg>
 
146
          <arg choice="plain"><option>-H
 
147
          <replaceable>STRING</replaceable></option></arg>
 
148
        </group>
 
149
        <sbr/>
 
150
        <group>
 
151
          <arg choice="plain"><option>--secret
 
152
          <replaceable>FILENAME</replaceable></option></arg>
 
153
          <arg choice="plain"><option>-s
 
154
          <replaceable>FILENAME</replaceable></option></arg>
 
155
        </group>
 
156
        <sbr/>
 
157
        <group>
 
158
          <arg choice="plain"><option>--approve</option></arg>
 
159
          <arg choice="plain"><option>-A</option></arg>
 
160
          <sbr/>
 
161
          <arg choice="plain"><option>--deny</option></arg>
 
162
          <arg choice="plain"><option>-D</option></arg>
 
163
        </group>
 
164
      </group>
 
165
      <sbr/>
 
166
      <arg><option>--debug</option></arg>
 
167
      <group choice="req">
 
168
        <arg choice="plain"><option>--all</option></arg>
 
169
        <arg choice="plain"><option>-a</option></arg>
 
170
        <arg rep='repeat' choice='plain'>
 
171
          <replaceable>CLIENT</replaceable>
 
172
        </arg>
 
173
      </group>
 
174
    </cmdsynopsis>
 
175
    <cmdsynopsis>
 
176
      <command>&COMMANDNAME;</command>
 
177
      <group>
121
178
        <arg choice="plain"><option>--deny</option></arg>
122
179
        <arg choice="plain"><option>-D</option></arg>
123
180
      </group>
 
181
      <group choice="req">
 
182
          <arg choice="plain"><option>--remove</option></arg>
 
183
          <arg choice="plain"><option>-r</option></arg>
 
184
      </group>
124
185
      <sbr/>
 
186
      <arg><option>--debug</option></arg>
125
187
      <group choice="req">
126
188
        <arg choice="plain"><option>--all</option></arg>
127
189
        <arg choice="plain"><option>-a</option></arg>
132
194
    </cmdsynopsis>
133
195
    <cmdsynopsis>
134
196
      <command>&COMMANDNAME;</command>
135
 
      <group>
136
 
        <arg choice="plain"><option>--verbose</option></arg>
137
 
        <arg choice="plain"><option>-v</option></arg>
138
 
      </group>
139
 
      <group>
140
 
        <arg rep='repeat' choice='plain'>
141
 
          <replaceable>CLIENT</replaceable>
142
 
        </arg>
143
 
      </group>
144
 
    </cmdsynopsis>
145
 
    <cmdsynopsis>
146
 
      <command>&COMMANDNAME;</command>
147
197
      <group choice="req">
148
198
        <arg choice="plain"><option>--is-enabled</option></arg>
149
199
        <arg choice="plain"><option>-V</option></arg>
150
200
      </group>
 
201
      <arg><option>--debug</option></arg>
151
202
      <arg choice='plain'><replaceable>CLIENT</replaceable></arg>
152
203
    </cmdsynopsis>
153
204
    <cmdsynopsis>
164
215
        <arg choice="plain"><option>-v</option></arg>
165
216
      </group>
166
217
    </cmdsynopsis>
 
218
    <cmdsynopsis>
 
219
      <command>&COMMANDNAME;</command>
 
220
      <arg choice="plain"><option>--check</option></arg>
 
221
    </cmdsynopsis>
167
222
  </refsynopsisdiv>
168
223
  
169
224
  <refsect1 id="description">
170
225
    <title>DESCRIPTION</title>
171
226
    <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>.
 
227
      <command>&COMMANDNAME;</command> is a program to control or
 
228
      query the operation of the Mandos server
 
229
      <citerefentry><refentrytitle>mandos</refentrytitle><manvolnum
 
230
      >8</manvolnum></citerefentry>.
175
231
    </para>
176
232
    <para>
177
233
      This program can be used to change client settings, approve or
273
329
          <para>
274
330
            Set the <varname>checker</varname> option of the specified
275
331
            client(s); see <citerefentry><refentrytitle
276
 
            >mandos-client.conf</refentrytitle><manvolnum>5</manvolnum
277
 
            ></citerefentry>.
 
332
            >mandos-clients.conf</refentrytitle><manvolnum
 
333
            >5</manvolnum></citerefentry>.
278
334
          </para>
279
335
        </listitem>
280
336
      </varlistentry>
288
344
          <para>
289
345
            Set the <varname>timeout</varname> option of the specified
290
346
            client(s); see <citerefentry><refentrytitle
291
 
            >mandos-client.conf</refentrytitle><manvolnum>5</manvolnum
292
 
            ></citerefentry>.
 
347
            >mandos-clients.conf</refentrytitle><manvolnum
 
348
            >5</manvolnum></citerefentry>.
 
349
          </para>
 
350
        </listitem>
 
351
      </varlistentry>
 
352
 
 
353
      <varlistentry>
 
354
        <term><option>--extended-timeout
 
355
        <replaceable>TIME</replaceable></option></term>
 
356
        <listitem>
 
357
          <para>
 
358
            Set the <varname>extended_timeout</varname> option of the
 
359
            specified client(s); see <citerefentry><refentrytitle
 
360
            >mandos-clients.conf</refentrytitle><manvolnum
 
361
            >5</manvolnum></citerefentry>.
293
362
          </para>
294
363
        </listitem>
295
364
      </varlistentry>
301
370
        <replaceable>TIME</replaceable></option></term>
302
371
        <listitem>
303
372
          <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>.
 
373
            Set the <varname>interval</varname> option of the
 
374
            specified client(s); see <citerefentry><refentrytitle
 
375
            >mandos-clients.conf</refentrytitle><manvolnum
 
376
            >5</manvolnum></citerefentry>.
 
377
          </para>
 
378
        </listitem>
 
379
      </varlistentry>
 
380
      
 
381
      <varlistentry>
 
382
        <term><option>--approve-by-default</option></term>
 
383
        <term><option>--deny-by-default</option></term>
 
384
        <listitem>
 
385
          <para>
 
386
            Set the <varname>approved_by_default</varname> option of
 
387
            the specified client(s) to <literal>True</literal> or
 
388
            <literal>False</literal>, respectively; see
 
389
            <citerefentry><refentrytitle
 
390
            >mandos-clients.conf</refentrytitle><manvolnum
 
391
            >5</manvolnum></citerefentry>.
 
392
          </para>
 
393
        </listitem>
 
394
      </varlistentry>
 
395
      
 
396
      <varlistentry>
 
397
        <term><option>--approval-delay
 
398
        <replaceable>TIME</replaceable></option></term>
 
399
        <listitem>
 
400
          <para>
 
401
            Set the <varname>approval_delay</varname> option of the
 
402
            specified client(s); see <citerefentry><refentrytitle
 
403
            >mandos-clients.conf</refentrytitle><manvolnum
 
404
            >5</manvolnum></citerefentry>.
 
405
          </para>
 
406
        </listitem>
 
407
      </varlistentry>
 
408
      
 
409
      <varlistentry>
 
410
        <term><option>--approval-duration
 
411
        <replaceable>TIME</replaceable></option></term>
 
412
        <listitem>
 
413
          <para>
 
414
            Set the <varname>approval_duration</varname> option of the
 
415
            specified client(s); see <citerefentry><refentrytitle
 
416
            >mandos-clients.conf</refentrytitle><manvolnum
 
417
            >5</manvolnum></citerefentry>.
308
418
          </para>
309
419
        </listitem>
310
420
      </varlistentry>
318
428
          <para>
319
429
            Set the <varname>host</varname> option of the specified
320
430
            client(s); see <citerefentry><refentrytitle
321
 
            >mandos-client.conf</refentrytitle><manvolnum>5</manvolnum
322
 
            ></citerefentry>.
 
431
            >mandos-clients.conf</refentrytitle><manvolnum
 
432
            >5</manvolnum></citerefentry>.
323
433
          </para>
324
434
        </listitem>
325
435
      </varlistentry>
333
443
          <para>
334
444
            Set the <varname>secfile</varname> option of the specified
335
445
            client(s); see <citerefentry><refentrytitle
336
 
            >mandos-client.conf</refentrytitle><manvolnum>5</manvolnum
337
 
            ></citerefentry>.
 
446
            >mandos-clients.conf</refentrytitle><manvolnum
 
447
            >5</manvolnum></citerefentry>.
338
448
          </para>
339
449
        </listitem>
340
450
      </varlistentry>
381
491
      </varlistentry>
382
492
      
383
493
      <varlistentry>
 
494
        <term><option>--dump-json</option></term>
 
495
        <term><option>-j</option></term>
 
496
        <listitem>
 
497
          <para>
 
498
            Dump client settings as JSON to standard output.
 
499
          </para>
 
500
        </listitem>
 
501
      </varlistentry>
 
502
      
 
503
      <varlistentry>
384
504
        <term><option>--is-enabled</option></term>
385
505
        <term><option>-V</option></term>
386
506
        <listitem>
391
511
        </listitem>
392
512
      </varlistentry>
393
513
      
 
514
      <varlistentry>
 
515
        <term><option>--debug</option></term>
 
516
        <listitem>
 
517
          <para>
 
518
            Show debug output; currently, this means show D-Bus calls.
 
519
          </para>
 
520
        </listitem>
 
521
      </varlistentry>
 
522
      
 
523
      <varlistentry>
 
524
        <term><option>--check</option></term>
 
525
        <listitem>
 
526
          <para>
 
527
            Run self-tests.  This includes any unit tests, etc.
 
528
          </para>
 
529
        </listitem>
 
530
      </varlistentry>
 
531
      
394
532
    </variablelist>
395
533
  </refsect1>
396
534
  
412
550
    </para>
413
551
  </refsect1>
414
552
  
415
 
<!--   <refsect1 id="bugs"> -->
416
 
<!--     <title>BUGS</title> -->
417
 
<!--     <para> -->
418
 
<!--     </para> -->
419
 
<!--   </refsect1> -->
 
553
  <refsect1 id="bugs">
 
554
    <title>BUGS</title>
 
555
    <xi:include href="bugs.xml"/>
 
556
  </refsect1>
420
557
  
421
558
  <refsect1 id="example">
422
559
    <title>EXAMPLE</title>
 
560
    <!-- Name of test methods in class Test_commands_from_options are
 
561
         written in comments below.  When adding an example, add a
 
562
         test too which tests the documented behavior. -->
423
563
    <informalexample>
 
564
      <!-- Test method: test_manual_page_example_1() -->
424
565
      <para>
425
 
        List all clients with some of their settings:
 
566
        To list all clients:
426
567
      </para>
427
568
      <para>
428
569
        <userinput>&COMMANDNAME;</userinput>
429
570
      </para>
430
571
    </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
 
 
 
572
    
 
573
    <informalexample>
 
574
      <!-- Test method: test_manual_page_example_2() -->
 
575
      <para>
 
576
        To list <emphasis>all</emphasis> settings 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; --verbose foo1.example.org foo2.example.org</userinput>
 
584
 
 
585
      </para>
 
586
    </informalexample>
 
587
    
 
588
    <informalexample>
 
589
      <!-- Test method: test_manual_page_example_3() -->
 
590
      <para>
 
591
        To enable all clients:
 
592
      </para>
 
593
      <para>
 
594
        <userinput>&COMMANDNAME; --enable --all</userinput>
 
595
      </para>
 
596
    </informalexample>
 
597
    
 
598
    <informalexample>
 
599
      <!-- Test method: test_manual_page_example_4() -->
 
600
      <para>
 
601
        To change timeout and interval value for the clients
 
602
        named <quote>foo1.example.org</quote> and <quote
 
603
        >foo2.example.org</quote>:
 
604
      </para>
 
605
      <para>
 
606
 
 
607
<!-- do not wrap this line -->
 
608
<userinput>&COMMANDNAME; --timeout=PT5M --interval=PT1M foo1.example.org foo2.example.org</userinput>
 
609
 
 
610
      </para>
 
611
    </informalexample>
 
612
    
 
613
    <informalexample>
 
614
      <!-- Test method: test_manual_page_example_5() -->
 
615
      <para>
 
616
        To approve all clients currently waiting for approval:
 
617
      </para>
 
618
      <para>
 
619
        <userinput>&COMMANDNAME; --approve --all</userinput>
441
620
      </para>
442
621
    </informalexample>
443
622
  </refsect1>
454
633
  <refsect1 id="see_also">
455
634
    <title>SEE ALSO</title>
456
635
    <para>
 
636
      <citerefentry><refentrytitle>intro</refentrytitle>
 
637
      <manvolnum>8mandos</manvolnum></citerefentry>,
457
638
      <citerefentry><refentrytitle>mandos</refentrytitle>
458
639
      <manvolnum>8</manvolnum></citerefentry>,
459
640
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>