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