/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-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-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-26">
 
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>--approve-by-default</option
105
 
        ></arg>
106
 
        <sbr/>
107
 
        <arg choice="plain"><option>--deny-by-default</option></arg>
108
 
      </group>
109
 
      <sbr/>
110
 
      <group>
111
 
        <arg choice="plain"><option>--approval-delay
112
 
        <replaceable>TIME</replaceable></option></arg>
113
 
      </group>
114
 
      <sbr/>
115
 
      <group>
116
 
        <arg choice="plain"><option>--approval-duration
117
 
        <replaceable>TIME</replaceable></option></arg>
118
 
      </group>
119
 
      <sbr/>
120
 
      <group>
121
 
        <arg choice="plain"><option>--interval
122
 
        <replaceable>TIME</replaceable></option></arg>
123
 
        <arg choice="plain"><option>-i
124
 
        <replaceable>TIME</replaceable></option></arg>
125
 
      </group>
126
 
      <sbr/>
127
 
      <group>
128
 
        <arg choice="plain"><option>--host
129
 
        <replaceable>STRING</replaceable></option></arg>
130
 
        <arg choice="plain"><option>-H
131
 
        <replaceable>STRING</replaceable></option></arg>
132
 
      </group>
133
 
      <sbr/>
134
 
      <group>
135
 
        <arg choice="plain"><option>--secret
136
 
        <replaceable>FILENAME</replaceable></option></arg>
137
 
        <arg choice="plain"><option>-s
138
 
        <replaceable>FILENAME</replaceable></option></arg>
139
 
      </group>
140
 
      <sbr/>
141
 
      <group>
142
 
        <arg choice="plain"><option>--approve</option></arg>
143
 
        <arg choice="plain"><option>-A</option></arg>
144
 
        <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>
145
178
        <arg choice="plain"><option>--deny</option></arg>
146
179
        <arg choice="plain"><option>-D</option></arg>
147
180
      </group>
 
181
      <group choice="req">
 
182
          <arg choice="plain"><option>--remove</option></arg>
 
183
          <arg choice="plain"><option>-r</option></arg>
 
184
      </group>
148
185
      <sbr/>
 
186
      <arg><option>--debug</option></arg>
149
187
      <group choice="req">
150
188
        <arg choice="plain"><option>--all</option></arg>
151
189
        <arg choice="plain"><option>-a</option></arg>
156
194
    </cmdsynopsis>
157
195
    <cmdsynopsis>
158
196
      <command>&COMMANDNAME;</command>
159
 
      <group>
160
 
        <arg choice="plain"><option>--verbose</option></arg>
161
 
        <arg choice="plain"><option>-v</option></arg>
162
 
      </group>
163
 
      <group>
164
 
        <arg rep='repeat' choice='plain'>
165
 
          <replaceable>CLIENT</replaceable>
166
 
        </arg>
167
 
      </group>
168
 
    </cmdsynopsis>
169
 
    <cmdsynopsis>
170
 
      <command>&COMMANDNAME;</command>
171
197
      <group choice="req">
172
198
        <arg choice="plain"><option>--is-enabled</option></arg>
173
199
        <arg choice="plain"><option>-V</option></arg>
174
200
      </group>
 
201
      <arg><option>--debug</option></arg>
175
202
      <arg choice='plain'><replaceable>CLIENT</replaceable></arg>
176
203
    </cmdsynopsis>
177
204
    <cmdsynopsis>
188
215
        <arg choice="plain"><option>-v</option></arg>
189
216
      </group>
190
217
    </cmdsynopsis>
 
218
    <cmdsynopsis>
 
219
      <command>&COMMANDNAME;</command>
 
220
      <arg choice="plain"><option>--check</option></arg>
 
221
    </cmdsynopsis>
191
222
  </refsynopsisdiv>
192
223
  
193
224
  <refsect1 id="description">
194
225
    <title>DESCRIPTION</title>
195
226
    <para>
196
 
      <command>&COMMANDNAME;</command> is a program to control the
197
 
      operation of the Mandos server <citerefentry><refentrytitle
198
 
      >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>.
199
231
    </para>
200
232
    <para>
201
233
      This program can be used to change client settings, approve or
317
349
          </para>
318
350
        </listitem>
319
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>.
 
362
          </para>
 
363
        </listitem>
 
364
      </varlistentry>
320
365
      
321
366
      <varlistentry>
322
367
        <term><option>--interval
446
491
      </varlistentry>
447
492
      
448
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>
449
504
        <term><option>--is-enabled</option></term>
450
505
        <term><option>-V</option></term>
451
506
        <listitem>
456
511
        </listitem>
457
512
      </varlistentry>
458
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
      
459
532
    </variablelist>
460
533
  </refsect1>
461
534
  
477
550
    </para>
478
551
  </refsect1>
479
552
  
480
 
<!--   <refsect1 id="bugs"> -->
481
 
<!--     <title>BUGS</title> -->
482
 
<!--     <para> -->
483
 
<!--     </para> -->
484
 
<!--   </refsect1> -->
 
553
  <refsect1 id="bugs">
 
554
    <title>BUGS</title>
 
555
    <xi:include href="bugs.xml"/>
 
556
  </refsect1>
485
557
  
486
558
  <refsect1 id="example">
487
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. -->
488
563
    <informalexample>
 
564
      <!-- Test method: test_manual_page_example_1() -->
489
565
      <para>
490
566
        To list all clients:
491
567
      </para>
495
571
    </informalexample>
496
572
    
497
573
    <informalexample>
 
574
      <!-- Test method: test_manual_page_example_2() -->
498
575
      <para>
499
576
        To list <emphasis>all</emphasis> settings for the clients
500
577
        named <quote>foo1.example.org</quote> and <quote
509
586
    </informalexample>
510
587
    
511
588
    <informalexample>
 
589
      <!-- Test method: test_manual_page_example_3() -->
512
590
      <para>
513
591
        To enable all clients:
514
592
      </para>
518
596
    </informalexample>
519
597
    
520
598
    <informalexample>
 
599
      <!-- Test method: test_manual_page_example_4() -->
521
600
      <para>
522
601
        To change timeout and interval value for the clients
523
602
        named <quote>foo1.example.org</quote> and <quote
526
605
      <para>
527
606
 
528
607
<!-- do not wrap this line -->
529
 
<userinput>&COMMANDNAME; --timeout="5m" --interval="1m" foo1.example.org foo2.example.org</userinput>
 
608
<userinput>&COMMANDNAME; --timeout=PT5M --interval=PT1M foo1.example.org foo2.example.org</userinput>
530
609
 
531
610
      </para>
532
611
    </informalexample>
533
612
    
534
613
    <informalexample>
 
614
      <!-- Test method: test_manual_page_example_5() -->
535
615
      <para>
536
 
        To approve all clients currently waiting for it:
 
616
        To approve all clients currently waiting for approval:
537
617
      </para>
538
618
      <para>
539
619
        <userinput>&COMMANDNAME; --approve --all</userinput>
553
633
  <refsect1 id="see_also">
554
634
    <title>SEE ALSO</title>
555
635
    <para>
 
636
      <citerefentry><refentrytitle>intro</refentrytitle>
 
637
      <manvolnum>8mandos</manvolnum></citerefentry>,
556
638
      <citerefentry><refentrytitle>mandos</refentrytitle>
557
639
      <manvolnum>8</manvolnum></citerefentry>,
558
640
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>