/mandos/release

To get this branch, use:
bzr branch http://bzr.recompile.se/loggerhead/mandos/release

« back to all changes in this revision

Viewing changes to mandos-ctl.xml

Merge new wireless network hook.  Fix bridge network hook to use
hardware addresses instead of interface names.  Implement and document
new "CONNECT" environment variable for network hooks.

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