/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: Björn Påhlsson
  • Date: 2008-07-20 02:52:20 UTC
  • Revision ID: belorn@braxen-20080720025220-r5u0388uy9iu23h6
Added following support:
Pluginbased client handler
rewritten Mandos client
       Avahi instead of udp server discovery
       openpgp encrypted key support
Passprompt stand alone application for direct console input
Added logging for Mandos server

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: -->