/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 "2011-08-08">
 
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
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>
36
44
      <holder>Teddy Hogeborn</holder>
37
45
      <holder>Björn Påhlsson</holder>
38
46
    </copyright>
47
55
  <refnamediv>
48
56
    <refname><command>&COMMANDNAME;</command></refname>
49
57
    <refpurpose>
50
 
      Control the operation of the Mandos server
 
58
      Control or query the operation of the Mandos server
51
59
    </refpurpose>
52
60
  </refnamediv>
53
61
  
55
63
    <cmdsynopsis>
56
64
      <command>&COMMANDNAME;</command>
57
65
      <group>
58
 
        <arg choice="plain"><option>--enable</option></arg>
59
 
        <arg choice="plain"><option>-e</option></arg>
60
 
        <sbr/>
61
 
        <arg choice="plain"><option>--disable</option></arg>
62
 
        <arg choice="plain"><option>-d</option></arg>
63
 
      </group>
64
 
      <sbr/>
65
 
      <group>
66
 
        <arg choice="plain"><option>--bump-timeout</option></arg>
67
 
        <arg choice="plain"><option>-b</option></arg>
68
 
      </group>
69
 
      <sbr/>
70
 
      <group>
71
 
        <arg choice="plain"><option>--start-checker</option></arg>
72
 
      </group>
73
 
      <sbr/>
74
 
      <group>
75
 
        <arg choice="plain"><option>--stop-checker</option></arg>
76
 
      </group>
77
 
      <sbr/>
78
 
      <group>
79
 
        <arg choice="plain"><option>--remove</option></arg>
80
 
        <arg choice="plain"><option>-r</option></arg>
81
 
      </group>
82
 
      <sbr/>
83
 
      <group>
84
 
        <arg choice="plain"><option>--checker
85
 
        <replaceable>COMMAND</replaceable></option></arg>
86
 
        <arg choice="plain"><option>-c
87
 
        <replaceable>COMMAND</replaceable></option></arg>
88
 
      </group>
89
 
      <sbr/>
90
 
      <group>
91
 
        <arg choice="plain"><option>--timeout
92
 
        <replaceable>TIME</replaceable></option></arg>
93
 
        <arg choice="plain"><option>-t
94
 
        <replaceable>TIME</replaceable></option></arg>
95
 
      </group>
96
 
      <sbr/>
97
 
      <group>
98
 
        <arg choice="plain"><option>--extended-timeout
99
 
        <replaceable>TIME</replaceable></option></arg>
100
 
      </group>
101
 
      <sbr/>
102
 
      <group>
103
 
        <arg choice="plain"><option>--interval
104
 
        <replaceable>TIME</replaceable></option></arg>
105
 
        <arg choice="plain"><option>-i
106
 
        <replaceable>TIME</replaceable></option></arg>
107
 
      </group>
108
 
      <sbr/>
109
 
      <group>
110
 
        <arg choice="plain"><option>--approve-by-default</option
111
 
        ></arg>
112
 
        <sbr/>
113
 
        <arg choice="plain"><option>--deny-by-default</option></arg>
114
 
      </group>
115
 
      <sbr/>
116
 
      <group>
117
 
        <arg choice="plain"><option>--approval-delay
118
 
        <replaceable>TIME</replaceable></option></arg>
119
 
      </group>
120
 
      <sbr/>
121
 
      <group>
122
 
        <arg choice="plain"><option>--approval-duration
123
 
        <replaceable>TIME</replaceable></option></arg>
124
 
      </group>
125
 
      <sbr/>
126
 
      <group>
127
 
        <arg choice="plain"><option>--interval
128
 
        <replaceable>TIME</replaceable></option></arg>
129
 
        <arg choice="plain"><option>-i
130
 
        <replaceable>TIME</replaceable></option></arg>
131
 
      </group>
132
 
      <sbr/>
133
 
      <group>
134
 
        <arg choice="plain"><option>--host
135
 
        <replaceable>STRING</replaceable></option></arg>
136
 
        <arg choice="plain"><option>-H
137
 
        <replaceable>STRING</replaceable></option></arg>
138
 
      </group>
139
 
      <sbr/>
140
 
      <group>
141
 
        <arg choice="plain"><option>--secret
142
 
        <replaceable>FILENAME</replaceable></option></arg>
143
 
        <arg choice="plain"><option>-s
144
 
        <replaceable>FILENAME</replaceable></option></arg>
145
 
      </group>
146
 
      <sbr/>
147
 
      <group>
148
 
        <arg choice="plain"><option>--approve</option></arg>
149
 
        <arg choice="plain"><option>-A</option></arg>
150
 
        <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>
151
178
        <arg choice="plain"><option>--deny</option></arg>
152
179
        <arg choice="plain"><option>-D</option></arg>
153
180
      </group>
 
181
      <group choice="req">
 
182
          <arg choice="plain"><option>--remove</option></arg>
 
183
          <arg choice="plain"><option>-r</option></arg>
 
184
      </group>
154
185
      <sbr/>
 
186
      <arg><option>--debug</option></arg>
155
187
      <group choice="req">
156
188
        <arg choice="plain"><option>--all</option></arg>
157
189
        <arg choice="plain"><option>-a</option></arg>
162
194
    </cmdsynopsis>
163
195
    <cmdsynopsis>
164
196
      <command>&COMMANDNAME;</command>
165
 
      <group>
166
 
        <arg choice="plain"><option>--verbose</option></arg>
167
 
        <arg choice="plain"><option>-v</option></arg>
168
 
      </group>
169
 
      <group>
170
 
        <arg rep='repeat' choice='plain'>
171
 
          <replaceable>CLIENT</replaceable>
172
 
        </arg>
173
 
      </group>
174
 
    </cmdsynopsis>
175
 
    <cmdsynopsis>
176
 
      <command>&COMMANDNAME;</command>
177
197
      <group choice="req">
178
198
        <arg choice="plain"><option>--is-enabled</option></arg>
179
199
        <arg choice="plain"><option>-V</option></arg>
180
200
      </group>
 
201
      <arg><option>--debug</option></arg>
181
202
      <arg choice='plain'><replaceable>CLIENT</replaceable></arg>
182
203
    </cmdsynopsis>
183
204
    <cmdsynopsis>
194
215
        <arg choice="plain"><option>-v</option></arg>
195
216
      </group>
196
217
    </cmdsynopsis>
 
218
    <cmdsynopsis>
 
219
      <command>&COMMANDNAME;</command>
 
220
      <arg choice="plain"><option>--check</option></arg>
 
221
    </cmdsynopsis>
197
222
  </refsynopsisdiv>
198
223
  
199
224
  <refsect1 id="description">
200
225
    <title>DESCRIPTION</title>
201
226
    <para>
202
 
      <command>&COMMANDNAME;</command> is a program to control the
203
 
      operation of the Mandos server <citerefentry><refentrytitle
204
 
      >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>.
205
231
    </para>
206
232
    <para>
207
233
      This program can be used to change client settings, approve or
465
491
      </varlistentry>
466
492
      
467
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>
468
504
        <term><option>--is-enabled</option></term>
469
505
        <term><option>-V</option></term>
470
506
        <listitem>
475
511
        </listitem>
476
512
      </varlistentry>
477
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
      
478
532
    </variablelist>
479
533
  </refsect1>
480
534
  
496
550
    </para>
497
551
  </refsect1>
498
552
  
499
 
<!--   <refsect1 id="bugs"> -->
500
 
<!--     <title>BUGS</title> -->
501
 
<!--     <para> -->
502
 
<!--     </para> -->
503
 
<!--   </refsect1> -->
 
553
  <refsect1 id="bugs">
 
554
    <title>BUGS</title>
 
555
    <xi:include href="bugs.xml"/>
 
556
  </refsect1>
504
557
  
505
558
  <refsect1 id="example">
506
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. -->
507
563
    <informalexample>
 
564
      <!-- Test method: test_manual_page_example_1() -->
508
565
      <para>
509
566
        To list all clients:
510
567
      </para>
514
571
    </informalexample>
515
572
    
516
573
    <informalexample>
 
574
      <!-- Test method: test_manual_page_example_2() -->
517
575
      <para>
518
576
        To list <emphasis>all</emphasis> settings for the clients
519
577
        named <quote>foo1.example.org</quote> and <quote
528
586
    </informalexample>
529
587
    
530
588
    <informalexample>
 
589
      <!-- Test method: test_manual_page_example_3() -->
531
590
      <para>
532
591
        To enable all clients:
533
592
      </para>
537
596
    </informalexample>
538
597
    
539
598
    <informalexample>
 
599
      <!-- Test method: test_manual_page_example_4() -->
540
600
      <para>
541
601
        To change timeout and interval value for the clients
542
602
        named <quote>foo1.example.org</quote> and <quote
545
605
      <para>
546
606
 
547
607
<!-- do not wrap this line -->
548
 
<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>
549
609
 
550
610
      </para>
551
611
    </informalexample>
552
612
    
553
613
    <informalexample>
 
614
      <!-- Test method: test_manual_page_example_5() -->
554
615
      <para>
555
 
        To approve all clients currently waiting for it:
 
616
        To approve all clients currently waiting for approval:
556
617
      </para>
557
618
      <para>
558
619
        <userinput>&COMMANDNAME; --approve --all</userinput>