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