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