/mandos/release

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