/mandos/release

To get this branch, use:
bzr branch http://bzr.recompile.se/loggerhead/mandos/release
237.2.197 by teddy at bsnet
* mandos-ctl.xml: New.
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">
237.7.355 by Teddy Hogeborn
Update copyright year.
5
<!ENTITY TIMESTAMP "2016-02-28">
237.2.197 by teddy at bsnet
* mandos-ctl.xml: New.
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>
237.11.2 by Teddy Hogeborn
Change "fukt.bsnet.se" to "recompile.se" throughout.
22
	  <email>belorn@recompile.se</email>
237.2.197 by teddy at bsnet
* mandos-ctl.xml: New.
23
	</address>
24
      </author>
25
      <author>
26
	<firstname>Teddy</firstname>
27
	<surname>Hogeborn</surname>
28
	<address>
237.11.2 by Teddy Hogeborn
Change "fukt.bsnet.se" to "recompile.se" throughout.
29
	  <email>teddy@recompile.se</email>
237.2.197 by teddy at bsnet
* mandos-ctl.xml: New.
30
	</address>
31
      </author>
32
    </authorgroup>
33
    <copyright>
34
      <year>2010</year>
237.7.14 by Teddy Hogeborn
Update copyright year to "2011" wherever appropriate.
35
      <year>2011</year>
237.7.92 by Teddy Hogeborn
Updated year in copyright notices.
36
      <year>2012</year>
237.7.326 by Teddy Hogeborn
Update copyright year.
37
      <year>2013</year>
38
      <year>2014</year>
39
      <year>2015</year>
237.7.355 by Teddy Hogeborn
Update copyright year.
40
      <year>2016</year>
237.2.197 by teddy at bsnet
* mandos-ctl.xml: New.
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>
24.1.179 by Björn Påhlsson
New feature:
103
	<arg choice="plain"><option>--extended-timeout
104
	<replaceable>TIME</replaceable></option></arg>
105
      </group>
106
      <sbr/>
107
      <group>
237.2.197 by teddy at bsnet
* mandos-ctl.xml: New.
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>
237.2.204 by Teddy Hogeborn
* mandos (ClientDBus.__init__): Bug fix: Translate "-" in client names
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>
237.2.197 by teddy at bsnet
* mandos-ctl.xml: New.
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>
237.7.156 by Teddy Hogeborn
* Makefile (check): Also check mandos-ctl.
202
    <cmdsynopsis>
203
      <command>&COMMANDNAME;</command>
204
      <arg choice="plain"><option>--check</option></arg>
205
    </cmdsynopsis>
237.2.197 by teddy at bsnet
* mandos-ctl.xml: New.
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
237.2.204 by Teddy Hogeborn
* mandos (ClientDBus.__init__): Bug fix: Translate "-" in client names
315
	    >mandos-clients.conf</refentrytitle><manvolnum
316
            >5</manvolnum></citerefentry>.
237.2.197 by teddy at bsnet
* mandos-ctl.xml: New.
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
237.2.204 by Teddy Hogeborn
* mandos (ClientDBus.__init__): Bug fix: Translate "-" in client names
330
	    >mandos-clients.conf</refentrytitle><manvolnum
331
            >5</manvolnum></citerefentry>.
237.2.197 by teddy at bsnet
* mandos-ctl.xml: New.
332
	  </para>
333
	</listitem>
334
      </varlistentry>
24.1.179 by Björn Påhlsson
New feature:
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>
237.2.197 by teddy at bsnet
* mandos-ctl.xml: New.
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>
237.2.204 by Teddy Hogeborn
* mandos (ClientDBus.__init__): Bug fix: Translate "-" in client names
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>.
237.2.197 by teddy at bsnet
* mandos-ctl.xml: New.
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
237.2.204 by Teddy Hogeborn
* mandos (ClientDBus.__init__): Bug fix: Translate "-" in client names
414
	    >mandos-clients.conf</refentrytitle><manvolnum
415
            >5</manvolnum></citerefentry>.
237.2.197 by teddy at bsnet
* mandos-ctl.xml: New.
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
237.2.204 by Teddy Hogeborn
* mandos (ClientDBus.__init__): Bug fix: Translate "-" in client names
429
	    >mandos-clients.conf</refentrytitle><manvolnum
430
            >5</manvolnum></citerefentry>.
237.2.197 by teddy at bsnet
* mandos-ctl.xml: New.
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
      
237.7.156 by Teddy Hogeborn
* Makefile (check): Also check mandos-ctl.
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
      
237.2.197 by teddy at bsnet
* mandos-ctl.xml: New.
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
<!--     <para> -->
520
<!--     </para> -->
521
<!--   </refsect1> -->
522
  
523
  <refsect1 id="example">
524
    <title>EXAMPLE</title>
525
    <informalexample>
526
      <para>
237.2.201 by Teddy Hogeborn
* mandos (Client.runtime_expansions): New attribute containing the
527
	To list all clients:
237.2.197 by teddy at bsnet
* mandos-ctl.xml: New.
528
      </para>
529
      <para>
530
	<userinput>&COMMANDNAME;</userinput>
531
      </para>
532
    </informalexample>
237.2.201 by Teddy Hogeborn
* mandos (Client.runtime_expansions): New attribute containing the
533
    
534
    <informalexample>
535
      <para>
536
	To list <emphasis>all</emphasis> settings for the clients
537
        named <quote>foo1.example.org</quote> and <quote
538
        >foo2.example.org</quote>:
539
      </para>
540
      <para>
541
542
<!-- do not wrap this line -->
543
<userinput>&COMMANDNAME; --verbose foo1.example.org foo2.example.org</userinput>
544
545
      </para>
546
    </informalexample>
547
    
548
    <informalexample>
549
      <para>
550
	To enable all clients:
551
      </para>
552
      <para>
553
	<userinput>&COMMANDNAME; --enable --all</userinput>
554
      </para>
555
    </informalexample>
556
    
557
    <informalexample>
558
      <para>
559
	To change timeout and interval value for the clients
560
        named <quote>foo1.example.org</quote> and <quote
561
        >foo2.example.org</quote>:
562
      </para>
563
      <para>
564
565
<!-- do not wrap this line -->
566
<userinput>&COMMANDNAME; --timeout="5m" --interval="1m" foo1.example.org foo2.example.org</userinput>
567
568
      </para>
569
    </informalexample>
570
    
571
    <informalexample>
572
      <para>
573
	To approve all clients currently waiting for it:
574
      </para>
575
      <para>
237.2.204 by Teddy Hogeborn
* mandos (ClientDBus.__init__): Bug fix: Translate "-" in client names
576
	<userinput>&COMMANDNAME; --approve --all</userinput>
237.2.197 by teddy at bsnet
* mandos-ctl.xml: New.
577
      </para>
578
    </informalexample>
579
  </refsect1>
580
  
581
  <refsect1 id="security">
582
    <title>SECURITY</title>
583
    <para>
584
      This program must be permitted to access the Mandos server via
585
      the D-Bus interface.  This normally requires the root user, but
586
      could be configured otherwise by reconfiguring the D-Bus server.
587
    </para>
588
  </refsect1>
589
  
590
  <refsect1 id="see_also">
591
    <title>SEE ALSO</title>
592
    <para>
237.7.41 by Teddy Hogeborn
* Makefile (DOCS): Added "intro.8mandos".
593
      <citerefentry><refentrytitle>intro</refentrytitle>
594
      <manvolnum>8mandos</manvolnum></citerefentry>,
237.2.197 by teddy at bsnet
* mandos-ctl.xml: New.
595
      <citerefentry><refentrytitle>mandos</refentrytitle>
596
      <manvolnum>8</manvolnum></citerefentry>,
597
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
598
      <manvolnum>5</manvolnum></citerefentry>,
599
      <citerefentry><refentrytitle>mandos-monitor</refentrytitle>
600
      <manvolnum>8</manvolnum></citerefentry>
601
    </para>
602
  </refsect1>
603
  
604
</refentry>
605
<!-- Local Variables: -->
606
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
607
<!-- time-stamp-end: "[\"']>" -->
608
<!-- time-stamp-format: "%:y-%02m-%02d" -->
609
<!-- End: -->