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