/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: 2016-06-03 17:27:03 UTC
  • Revision ID: teddy@recompile.se-20160603172703-mc6tjor6rhq4xy74
mandos: Bug fix: Do multiprocessing cleanup correctly on exit

* mandos (main): Save module "multiprocessing" and open file "wnull"
                 as scope variables accessible by function cleanup(),
                 since the module and global variable may not be
                 accessible when the cleanup() function is run as
                 scheduled by atexit().

Show diffs side-by-side

added added

removed removed

Lines of Context:
mandos-ctl.xml
 
1
<?xml version="1.0" encoding="UTF-8"?>
 
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
 
3
        "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
 
4
<!ENTITY COMMANDNAME "mandos-ctl">
 
5
<!ENTITY TIMESTAMP "2016-03-05">
 
6
<!ENTITY % common SYSTEM "common.ent">
 
7
%common;
 
8
]>
 
9
 
 
10
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
 
11
  <refentryinfo>
 
12
    <title>Mandos Manual</title>
 
13
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
 
14
    <productname>Mandos</productname>
 
15
    <productnumber>&version;</productnumber>
 
16
    <date>&TIMESTAMP;</date>
 
17
    <authorgroup>
 
18
      <author>
 
19
        <firstname>Björn</firstname>
 
20
        <surname>Påhlsson</surname>
 
21
        <address>
 
22
          <email>belorn@recompile.se</email>
 
23
        </address>
 
24
      </author>
 
25
      <author>
 
26
        <firstname>Teddy</firstname>
 
27
        <surname>Hogeborn</surname>
 
28
        <address>
 
29
          <email>teddy@recompile.se</email>
 
30
        </address>
 
31
      </author>
 
32
    </authorgroup>
 
33
    <copyright>
 
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
      <holder>Teddy Hogeborn</holder>
 
42
      <holder>Björn Påhlsson</holder>
 
43
    </copyright>
 
44
    <xi:include href="legalnotice.xml"/>
 
45
  </refentryinfo>
 
46
  
 
47
  <refmeta>
 
48
    <refentrytitle>&COMMANDNAME;</refentrytitle>
 
49
    <manvolnum>8</manvolnum>
 
50
  </refmeta>
 
51
  
 
52
  <refnamediv>
 
53
    <refname><command>&COMMANDNAME;</command></refname>
 
54
    <refpurpose>
 
55
      Control the operation of the Mandos server
 
56
    </refpurpose>
 
57
  </refnamediv>
 
58
  
 
59
  <refsynopsisdiv>
 
60
    <cmdsynopsis>
 
61
      <command>&COMMANDNAME;</command>
 
62
      <group>
 
63
        <arg choice="plain"><option>--enable</option></arg>
 
64
        <arg choice="plain"><option>-e</option></arg>
 
65
        <sbr/>
 
66
        <arg choice="plain"><option>--disable</option></arg>
 
67
        <arg choice="plain"><option>-d</option></arg>
 
68
      </group>
 
69
      <sbr/>
 
70
      <group>
 
71
        <arg choice="plain"><option>--bump-timeout</option></arg>
 
72
        <arg choice="plain"><option>-b</option></arg>
 
73
      </group>
 
74
      <sbr/>
 
75
      <group>
 
76
        <arg choice="plain"><option>--start-checker</option></arg>
 
77
      </group>
 
78
      <sbr/>
 
79
      <group>
 
80
        <arg choice="plain"><option>--stop-checker</option></arg>
 
81
      </group>
 
82
      <sbr/>
 
83
      <group>
 
84
        <arg choice="plain"><option>--remove</option></arg>
 
85
        <arg choice="plain"><option>-r</option></arg>
 
86
      </group>
 
87
      <sbr/>
 
88
      <group>
 
89
        <arg choice="plain"><option>--checker
 
90
        <replaceable>COMMAND</replaceable></option></arg>
 
91
        <arg choice="plain"><option>-c
 
92
        <replaceable>COMMAND</replaceable></option></arg>
 
93
      </group>
 
94
      <sbr/>
 
95
      <group>
 
96
        <arg choice="plain"><option>--timeout
 
97
        <replaceable>TIME</replaceable></option></arg>
 
98
        <arg choice="plain"><option>-t
 
99
        <replaceable>TIME</replaceable></option></arg>
 
100
      </group>
 
101
      <sbr/>
 
102
      <group>
 
103
        <arg choice="plain"><option>--extended-timeout
 
104
        <replaceable>TIME</replaceable></option></arg>
 
105
      </group>
 
106
      <sbr/>
 
107
      <group>
 
108
        <arg choice="plain"><option>--interval
 
109
        <replaceable>TIME</replaceable></option></arg>
 
110
        <arg choice="plain"><option>-i
 
111
        <replaceable>TIME</replaceable></option></arg>
 
112
      </group>
 
113
      <sbr/>
 
114
      <group>
 
115
        <arg choice="plain"><option>--approve-by-default</option
 
116
        ></arg>
 
117
        <sbr/>
 
118
        <arg choice="plain"><option>--deny-by-default</option></arg>
 
119
      </group>
 
120
      <sbr/>
 
121
      <group>
 
122
        <arg choice="plain"><option>--approval-delay
 
123
        <replaceable>TIME</replaceable></option></arg>
 
124
      </group>
 
125
      <sbr/>
 
126
      <group>
 
127
        <arg choice="plain"><option>--approval-duration
 
128
        <replaceable>TIME</replaceable></option></arg>
 
129
      </group>
 
130
      <sbr/>
 
131
      <group>
 
132
        <arg choice="plain"><option>--interval
 
133
        <replaceable>TIME</replaceable></option></arg>
 
134
        <arg choice="plain"><option>-i
 
135
        <replaceable>TIME</replaceable></option></arg>
 
136
      </group>
 
137
      <sbr/>
 
138
      <group>
 
139
        <arg choice="plain"><option>--host
 
140
        <replaceable>STRING</replaceable></option></arg>
 
141
        <arg choice="plain"><option>-H
 
142
        <replaceable>STRING</replaceable></option></arg>
 
143
      </group>
 
144
      <sbr/>
 
145
      <group>
 
146
        <arg choice="plain"><option>--secret
 
147
        <replaceable>FILENAME</replaceable></option></arg>
 
148
        <arg choice="plain"><option>-s
 
149
        <replaceable>FILENAME</replaceable></option></arg>
 
150
      </group>
 
151
      <sbr/>
 
152
      <group>
 
153
        <arg choice="plain"><option>--approve</option></arg>
 
154
        <arg choice="plain"><option>-A</option></arg>
 
155
        <sbr/>
 
156
        <arg choice="plain"><option>--deny</option></arg>
 
157
        <arg choice="plain"><option>-D</option></arg>
 
158
      </group>
 
159
      <sbr/>
 
160
      <group choice="req">
 
161
        <arg choice="plain"><option>--all</option></arg>
 
162
        <arg choice="plain"><option>-a</option></arg>
 
163
        <arg rep='repeat' choice='plain'>
 
164
          <replaceable>CLIENT</replaceable>
 
165
        </arg>
 
166
      </group>
 
167
    </cmdsynopsis>
 
168
    <cmdsynopsis>
 
169
      <command>&COMMANDNAME;</command>
 
170
      <group>
 
171
        <arg choice="plain"><option>--verbose</option></arg>
 
172
        <arg choice="plain"><option>-v</option></arg>
 
173
      </group>
 
174
      <group>
 
175
        <arg rep='repeat' choice='plain'>
 
176
          <replaceable>CLIENT</replaceable>
 
177
        </arg>
 
178
      </group>
 
179
    </cmdsynopsis>
 
180
    <cmdsynopsis>
 
181
      <command>&COMMANDNAME;</command>
 
182
      <group choice="req">
 
183
        <arg choice="plain"><option>--is-enabled</option></arg>
 
184
        <arg choice="plain"><option>-V</option></arg>
 
185
      </group>
 
186
      <arg choice='plain'><replaceable>CLIENT</replaceable></arg>
 
187
    </cmdsynopsis>
 
188
    <cmdsynopsis>
 
189
      <command>&COMMANDNAME;</command>
 
190
      <group choice="req">
 
191
        <arg choice="plain"><option>--help</option></arg>
 
192
        <arg choice="plain"><option>-h</option></arg>
 
193
      </group>
 
194
    </cmdsynopsis>
 
195
    <cmdsynopsis>
 
196
      <command>&COMMANDNAME;</command>
 
197
      <group choice="req">
 
198
        <arg choice="plain"><option>--version</option></arg>
 
199
        <arg choice="plain"><option>-v</option></arg>
 
200
      </group>
 
201
    </cmdsynopsis>
 
202
    <cmdsynopsis>
 
203
      <command>&COMMANDNAME;</command>
 
204
      <arg choice="plain"><option>--check</option></arg>
 
205
    </cmdsynopsis>
 
206
  </refsynopsisdiv>
 
207
  
 
208
  <refsect1 id="description">
 
209
    <title>DESCRIPTION</title>
 
210
    <para>
 
211
      <command>&COMMANDNAME;</command> is a program to control the
 
212
      operation of the Mandos server <citerefentry><refentrytitle
 
213
      >mandos</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 
214
    </para>
 
215
    <para>
 
216
      This program can be used to change client settings, approve or
 
217
      deny client requests, and to remove clients from the server.
 
218
    </para>
 
219
  </refsect1>
 
220
  
 
221
  <refsect1 id="purpose">
 
222
    <title>PURPOSE</title>
 
223
    <para>
 
224
      The purpose of this is to enable <emphasis>remote and unattended
 
225
      rebooting</emphasis> of client host computer with an
 
226
      <emphasis>encrypted root file system</emphasis>.  See <xref
 
227
      linkend="overview"/> for details.
 
228
    </para>
 
229
  </refsect1>
 
230
  
 
231
  <refsect1 id="options">
 
232
    <title>OPTIONS</title>
 
233
    
 
234
    <variablelist>
 
235
      <varlistentry>
 
236
        <term><option>--help</option></term>
 
237
        <term><option>-h</option></term>
 
238
        <listitem>
 
239
          <para>
 
240
            Show a help message and exit
 
241
          </para>
 
242
        </listitem>
 
243
      </varlistentry>
 
244
      
 
245
      <varlistentry>
 
246
        <term><option>--enable</option></term>
 
247
        <term><option>-e</option></term>
 
248
        <listitem>
 
249
          <para>
 
250
            Enable client(s).  An enabled client will be eligble to
 
251
            receive its secret.
 
252
          </para>
 
253
        </listitem>
 
254
      </varlistentry>
 
255
      
 
256
      <varlistentry>
 
257
        <term><option>--disable</option></term>
 
258
        <term><option>-d</option></term>
 
259
        <listitem>
 
260
          <para>
 
261
            Disable client(s).  A disabled client will not be eligble
 
262
            to receive its secret, and no checkers will be started for
 
263
            it.
 
264
          </para>
 
265
        </listitem>
 
266
      </varlistentry>
 
267
      
 
268
      <varlistentry>
 
269
        <term><option>--bump-timeout</option></term>
 
270
        <listitem>
 
271
          <para>
 
272
            Bump the timeout of the specified client(s), just as if a
 
273
            checker had completed successfully for it/them.
 
274
          </para>
 
275
        </listitem>
 
276
      </varlistentry>
 
277
      
 
278
      <varlistentry>
 
279
        <term><option>--start-checker</option></term>
 
280
        <listitem>
 
281
          <para>
 
282
            Start a new checker now for the specified client(s).
 
283
          </para>
 
284
        </listitem>
 
285
      </varlistentry>
 
286
      
 
287
      <varlistentry>
 
288
        <term><option>--stop-checker</option></term>
 
289
        <listitem>
 
290
          <para>
 
291
            Stop any running checker for the specified client(s).
 
292
          </para>
 
293
        </listitem>
 
294
      </varlistentry>
 
295
      
 
296
      <varlistentry>
 
297
        <term><option>--remove</option></term>
 
298
        <term><option>-r</option></term>
 
299
        <listitem>
 
300
          <para>
 
301
            Remove the specified client(s) from the server.
 
302
          </para>
 
303
        </listitem>
 
304
      </varlistentry>
 
305
      
 
306
      <varlistentry>
 
307
        <term><option>--checker
 
308
        <replaceable>COMMAND</replaceable></option></term>
 
309
        <term><option>-c
 
310
        <replaceable>COMMAND</replaceable></option></term>
 
311
        <listitem>
 
312
          <para>
 
313
            Set the <varname>checker</varname> option of the specified
 
314
            client(s); see <citerefentry><refentrytitle
 
315
            >mandos-clients.conf</refentrytitle><manvolnum
 
316
            >5</manvolnum></citerefentry>.
 
317
          </para>
 
318
        </listitem>
 
319
      </varlistentry>
 
320
      
 
321
      <varlistentry>
 
322
        <term><option>--timeout
 
323
        <replaceable>TIME</replaceable></option></term>
 
324
        <term><option>-t
 
325
        <replaceable>TIME</replaceable></option></term>
 
326
        <listitem>
 
327
          <para>
 
328
            Set the <varname>timeout</varname> option of the specified
 
329
            client(s); see <citerefentry><refentrytitle
 
330
            >mandos-clients.conf</refentrytitle><manvolnum
 
331
            >5</manvolnum></citerefentry>.
 
332
          </para>
 
333
        </listitem>
 
334
      </varlistentry>
 
335
 
 
336
      <varlistentry>
 
337
        <term><option>--extended-timeout
 
338
        <replaceable>TIME</replaceable></option></term>
 
339
        <listitem>
 
340
          <para>
 
341
            Set the <varname>extended_timeout</varname> option of the
 
342
            specified client(s); see <citerefentry><refentrytitle
 
343
            >mandos-clients.conf</refentrytitle><manvolnum
 
344
            >5</manvolnum></citerefentry>.
 
345
          </para>
 
346
        </listitem>
 
347
      </varlistentry>
 
348
      
 
349
      <varlistentry>
 
350
        <term><option>--interval
 
351
        <replaceable>TIME</replaceable></option></term>
 
352
        <term><option>-i
 
353
        <replaceable>TIME</replaceable></option></term>
 
354
        <listitem>
 
355
          <para>
 
356
            Set the <varname>interval</varname> option of the
 
357
            specified client(s); see <citerefentry><refentrytitle
 
358
            >mandos-clients.conf</refentrytitle><manvolnum
 
359
            >5</manvolnum></citerefentry>.
 
360
          </para>
 
361
        </listitem>
 
362
      </varlistentry>
 
363
      
 
364
      <varlistentry>
 
365
        <term><option>--approve-by-default</option></term>
 
366
        <term><option>--deny-by-default</option></term>
 
367
        <listitem>
 
368
          <para>
 
369
            Set the <varname>approved_by_default</varname> option of
 
370
            the specified client(s) to <literal>True</literal> or
 
371
            <literal>False</literal>, respectively; see
 
372
            <citerefentry><refentrytitle
 
373
            >mandos-clients.conf</refentrytitle><manvolnum
 
374
            >5</manvolnum></citerefentry>.
 
375
          </para>
 
376
        </listitem>
 
377
      </varlistentry>
 
378
      
 
379
      <varlistentry>
 
380
        <term><option>--approval-delay
 
381
        <replaceable>TIME</replaceable></option></term>
 
382
        <listitem>
 
383
          <para>
 
384
            Set the <varname>approval_delay</varname> option of the
 
385
            specified client(s); see <citerefentry><refentrytitle
 
386
            >mandos-clients.conf</refentrytitle><manvolnum
 
387
            >5</manvolnum></citerefentry>.
 
388
          </para>
 
389
        </listitem>
 
390
      </varlistentry>
 
391
      
 
392
      <varlistentry>
 
393
        <term><option>--approval-duration
 
394
        <replaceable>TIME</replaceable></option></term>
 
395
        <listitem>
 
396
          <para>
 
397
            Set the <varname>approval_duration</varname> option of the
 
398
            specified client(s); see <citerefentry><refentrytitle
 
399
            >mandos-clients.conf</refentrytitle><manvolnum
 
400
            >5</manvolnum></citerefentry>.
 
401
          </para>
 
402
        </listitem>
 
403
      </varlistentry>
 
404
      
 
405
      <varlistentry>
 
406
        <term><option>--host
 
407
        <replaceable>STRING</replaceable></option></term>
 
408
        <term><option>-H
 
409
        <replaceable>STRING</replaceable></option></term>
 
410
        <listitem>
 
411
          <para>
 
412
            Set the <varname>host</varname> option of the specified
 
413
            client(s); see <citerefentry><refentrytitle
 
414
            >mandos-clients.conf</refentrytitle><manvolnum
 
415
            >5</manvolnum></citerefentry>.
 
416
          </para>
 
417
        </listitem>
 
418
      </varlistentry>
 
419
      
 
420
      <varlistentry>
 
421
        <term><option>--secret
 
422
        <replaceable>FILENAME</replaceable></option></term>
 
423
        <term><option>-s
 
424
        <replaceable>FILENAME</replaceable></option></term>
 
425
        <listitem>
 
426
          <para>
 
427
            Set the <varname>secfile</varname> option of the specified
 
428
            client(s); see <citerefentry><refentrytitle
 
429
            >mandos-clients.conf</refentrytitle><manvolnum
 
430
            >5</manvolnum></citerefentry>.
 
431
          </para>
 
432
        </listitem>
 
433
      </varlistentry>
 
434
      
 
435
      <varlistentry>
 
436
        <term><option>--approve</option></term>
 
437
        <term><option>-A</option></term>
 
438
        <listitem>
 
439
          <para>
 
440
            Approve client(s) if currently waiting for approval.
 
441
          </para>
 
442
        </listitem>
 
443
      </varlistentry>
 
444
      
 
445
      <varlistentry>
 
446
        <term><option>--deny</option></term>
 
447
        <term><option>-D</option></term>
 
448
        <listitem>
 
449
          <para>
 
450
            Deny client(s) if currently waiting for approval.
 
451
          </para>
 
452
        </listitem>
 
453
      </varlistentry>
 
454
      
 
455
      <varlistentry>
 
456
        <term><option>--all</option></term>
 
457
        <term><option>-a</option></term>
 
458
        <listitem>
 
459
          <para>
 
460
            Make the client-modifying options modify <emphasis
 
461
            >all</emphasis> clients.
 
462
          </para>
 
463
        </listitem>
 
464
      </varlistentry>
 
465
      
 
466
      <varlistentry>
 
467
        <term><option>--verbose</option></term>
 
468
        <term><option>-v</option></term>
 
469
        <listitem>
 
470
          <para>
 
471
            Show all client settings, not just a subset.
 
472
          </para>
 
473
        </listitem>
 
474
      </varlistentry>
 
475
      
 
476
      <varlistentry>
 
477
        <term><option>--is-enabled</option></term>
 
478
        <term><option>-V</option></term>
 
479
        <listitem>
 
480
          <para>
 
481
            Check if a single client is enabled or not, and exit with
 
482
            a successful exit status only if the client is enabled.
 
483
          </para>
 
484
        </listitem>
 
485
      </varlistentry>
 
486
      
 
487
      <varlistentry>
 
488
        <term><option>--check</option></term>
 
489
        <listitem>
 
490
          <para>
 
491
            Run self-tests.  This includes any unit tests, etc.
 
492
          </para>
 
493
        </listitem>
 
494
      </varlistentry>
 
495
      
 
496
    </variablelist>
 
497
  </refsect1>
 
498
  
 
499
  <refsect1 id="overview">
 
500
    <title>OVERVIEW</title>
 
501
    <xi:include href="overview.xml"/>
 
502
    <para>
 
503
      This program is a small utility to generate new OpenPGP keys for
 
504
      new Mandos clients, and to generate sections for inclusion in
 
505
      <filename>clients.conf</filename> on the server.
 
506
    </para>
 
507
  </refsect1>
 
508
  
 
509
  <refsect1 id="exit_status">
 
510
    <title>EXIT STATUS</title>
 
511
    <para>
 
512
      If the <option>--is-enabled</option> option is used, the exit
 
513
      status will be 0 only if the specified client is enabled.
 
514
    </para>
 
515
  </refsect1>
 
516
  
 
517
  <refsect1 id="bugs">
 
518
    <title>BUGS</title>
 
519
    <xi:include href="bugs.xml"/>
 
520
  </refsect1>
 
521
  
 
522
  <refsect1 id="example">
 
523
    <title>EXAMPLE</title>
 
524
    <informalexample>
 
525
      <para>
 
526
        To list all clients:
 
527
      </para>
 
528
      <para>
 
529
        <userinput>&COMMANDNAME;</userinput>
 
530
      </para>
 
531
    </informalexample>
 
532
    
 
533
    <informalexample>
 
534
      <para>
 
535
        To list <emphasis>all</emphasis> settings for the clients
 
536
        named <quote>foo1.example.org</quote> and <quote
 
537
        >foo2.example.org</quote>:
 
538
      </para>
 
539
      <para>
 
540
 
 
541
<!-- do not wrap this line -->
 
542
<userinput>&COMMANDNAME; --verbose foo1.example.org foo2.example.org</userinput>
 
543
 
 
544
      </para>
 
545
    </informalexample>
 
546
    
 
547
    <informalexample>
 
548
      <para>
 
549
        To enable all clients:
 
550
      </para>
 
551
      <para>
 
552
        <userinput>&COMMANDNAME; --enable --all</userinput>
 
553
      </para>
 
554
    </informalexample>
 
555
    
 
556
    <informalexample>
 
557
      <para>
 
558
        To change timeout and interval value for the clients
 
559
        named <quote>foo1.example.org</quote> and <quote
 
560
        >foo2.example.org</quote>:
 
561
      </para>
 
562
      <para>
 
563
 
 
564
<!-- do not wrap this line -->
 
565
<userinput>&COMMANDNAME; --timeout="5m" --interval="1m" foo1.example.org foo2.example.org</userinput>
 
566
 
 
567
      </para>
 
568
    </informalexample>
 
569
    
 
570
    <informalexample>
 
571
      <para>
 
572
        To approve all clients currently waiting for it:
 
573
      </para>
 
574
      <para>
 
575
        <userinput>&COMMANDNAME; --approve --all</userinput>
 
576
      </para>
 
577
    </informalexample>
 
578
  </refsect1>
 
579
  
 
580
  <refsect1 id="security">
 
581
    <title>SECURITY</title>
 
582
    <para>
 
583
      This program must be permitted to access the Mandos server via
 
584
      the D-Bus interface.  This normally requires the root user, but
 
585
      could be configured otherwise by reconfiguring the D-Bus server.
 
586
    </para>
 
587
  </refsect1>
 
588
  
 
589
  <refsect1 id="see_also">
 
590
    <title>SEE ALSO</title>
 
591
    <para>
 
592
      <citerefentry><refentrytitle>intro</refentrytitle>
 
593
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
594
      <citerefentry><refentrytitle>mandos</refentrytitle>
 
595
      <manvolnum>8</manvolnum></citerefentry>,
 
596
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
 
597
      <manvolnum>5</manvolnum></citerefentry>,
 
598
      <citerefentry><refentrytitle>mandos-monitor</refentrytitle>
 
599
      <manvolnum>8</manvolnum></citerefentry>
 
600
    </para>
 
601
  </refsect1>
 
602
  
 
603
</refentry>
 
604
<!-- Local Variables: -->
 
605
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
 
606
<!-- time-stamp-end: "[\"']>" -->
 
607
<!-- time-stamp-format: "%:y-%02m-%02d" -->
 
608
<!-- End: -->