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 "2012-06-22">
6
<!ENTITY % common SYSTEM "common.ent">
10
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
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>
19
<firstname>Björn</firstname>
20
<surname>Påhlsson</surname>
22
<email>belorn@recompile.se</email>
26
<firstname>Teddy</firstname>
27
<surname>Hogeborn</surname>
29
<email>teddy@recompile.se</email>
37
<holder>Teddy Hogeborn</holder>
38
<holder>Björn Påhlsson</holder>
40
<xi:include href="legalnotice.xml"/>
44
<refentrytitle>&COMMANDNAME;</refentrytitle>
45
<manvolnum>8</manvolnum>
49
<refname><command>&COMMANDNAME;</command></refname>
51
Control the operation of the Mandos server
57
<command>&COMMANDNAME;</command>
59
<arg choice="plain"><option>--enable</option></arg>
60
<arg choice="plain"><option>-e</option></arg>
62
<arg choice="plain"><option>--disable</option></arg>
63
<arg choice="plain"><option>-d</option></arg>
67
<arg choice="plain"><option>--bump-timeout</option></arg>
68
<arg choice="plain"><option>-b</option></arg>
72
<arg choice="plain"><option>--start-checker</option></arg>
76
<arg choice="plain"><option>--stop-checker</option></arg>
80
<arg choice="plain"><option>--remove</option></arg>
81
<arg choice="plain"><option>-r</option></arg>
85
<arg choice="plain"><option>--checker
86
<replaceable>COMMAND</replaceable></option></arg>
87
<arg choice="plain"><option>-c
88
<replaceable>COMMAND</replaceable></option></arg>
92
<arg choice="plain"><option>--timeout
93
<replaceable>TIME</replaceable></option></arg>
94
<arg choice="plain"><option>-t
95
<replaceable>TIME</replaceable></option></arg>
99
<arg choice="plain"><option>--extended-timeout
100
<replaceable>TIME</replaceable></option></arg>
104
<arg choice="plain"><option>--interval
105
<replaceable>TIME</replaceable></option></arg>
106
<arg choice="plain"><option>-i
107
<replaceable>TIME</replaceable></option></arg>
111
<arg choice="plain"><option>--approve-by-default</option
114
<arg choice="plain"><option>--deny-by-default</option></arg>
118
<arg choice="plain"><option>--approval-delay
119
<replaceable>TIME</replaceable></option></arg>
123
<arg choice="plain"><option>--approval-duration
124
<replaceable>TIME</replaceable></option></arg>
128
<arg choice="plain"><option>--interval
129
<replaceable>TIME</replaceable></option></arg>
130
<arg choice="plain"><option>-i
131
<replaceable>TIME</replaceable></option></arg>
135
<arg choice="plain"><option>--host
136
<replaceable>STRING</replaceable></option></arg>
137
<arg choice="plain"><option>-H
138
<replaceable>STRING</replaceable></option></arg>
142
<arg choice="plain"><option>--secret
143
<replaceable>FILENAME</replaceable></option></arg>
144
<arg choice="plain"><option>-s
145
<replaceable>FILENAME</replaceable></option></arg>
149
<arg choice="plain"><option>--approve</option></arg>
150
<arg choice="plain"><option>-A</option></arg>
152
<arg choice="plain"><option>--deny</option></arg>
153
<arg choice="plain"><option>-D</option></arg>
157
<arg choice="plain"><option>--all</option></arg>
158
<arg choice="plain"><option>-a</option></arg>
159
<arg rep='repeat' choice='plain'>
160
<replaceable>CLIENT</replaceable>
165
<command>&COMMANDNAME;</command>
167
<arg choice="plain"><option>--verbose</option></arg>
168
<arg choice="plain"><option>-v</option></arg>
171
<arg rep='repeat' choice='plain'>
172
<replaceable>CLIENT</replaceable>
177
<command>&COMMANDNAME;</command>
179
<arg choice="plain"><option>--is-enabled</option></arg>
180
<arg choice="plain"><option>-V</option></arg>
182
<arg choice='plain'><replaceable>CLIENT</replaceable></arg>
185
<command>&COMMANDNAME;</command>
187
<arg choice="plain"><option>--help</option></arg>
188
<arg choice="plain"><option>-h</option></arg>
192
<command>&COMMANDNAME;</command>
194
<arg choice="plain"><option>--version</option></arg>
195
<arg choice="plain"><option>-v</option></arg>
199
<command>&COMMANDNAME;</command>
200
<arg choice="plain"><option>--check</option></arg>
204
<refsect1 id="description">
205
<title>DESCRIPTION</title>
207
<command>&COMMANDNAME;</command> is a program to control the
208
operation of the Mandos server <citerefentry><refentrytitle
209
>mandos</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
212
This program can be used to change client settings, approve or
213
deny client requests, and to remove clients from the server.
217
<refsect1 id="purpose">
218
<title>PURPOSE</title>
220
The purpose of this is to enable <emphasis>remote and unattended
221
rebooting</emphasis> of client host computer with an
222
<emphasis>encrypted root file system</emphasis>. See <xref
223
linkend="overview"/> for details.
227
<refsect1 id="options">
228
<title>OPTIONS</title>
232
<term><option>--help</option></term>
233
<term><option>-h</option></term>
236
Show a help message and exit
242
<term><option>--enable</option></term>
243
<term><option>-e</option></term>
246
Enable client(s). An enabled client will be eligble to
253
<term><option>--disable</option></term>
254
<term><option>-d</option></term>
257
Disable client(s). A disabled client will not be eligble
258
to receive its secret, and no checkers will be started for
265
<term><option>--bump-timeout</option></term>
268
Bump the timeout of the specified client(s), just as if a
269
checker had completed successfully for it/them.
275
<term><option>--start-checker</option></term>
278
Start a new checker now for the specified client(s).
284
<term><option>--stop-checker</option></term>
287
Stop any running checker for the specified client(s).
293
<term><option>--remove</option></term>
294
<term><option>-r</option></term>
297
Remove the specified client(s) from the server.
303
<term><option>--checker
304
<replaceable>COMMAND</replaceable></option></term>
306
<replaceable>COMMAND</replaceable></option></term>
309
Set the <varname>checker</varname> option of the specified
310
client(s); see <citerefentry><refentrytitle
311
>mandos-clients.conf</refentrytitle><manvolnum
312
>5</manvolnum></citerefentry>.
318
<term><option>--timeout
319
<replaceable>TIME</replaceable></option></term>
321
<replaceable>TIME</replaceable></option></term>
324
Set the <varname>timeout</varname> option of the specified
325
client(s); see <citerefentry><refentrytitle
326
>mandos-clients.conf</refentrytitle><manvolnum
327
>5</manvolnum></citerefentry>.
333
<term><option>--extended-timeout
334
<replaceable>TIME</replaceable></option></term>
337
Set the <varname>extended_timeout</varname> option of the
338
specified client(s); see <citerefentry><refentrytitle
339
>mandos-clients.conf</refentrytitle><manvolnum
340
>5</manvolnum></citerefentry>.
346
<term><option>--interval
347
<replaceable>TIME</replaceable></option></term>
349
<replaceable>TIME</replaceable></option></term>
352
Set the <varname>interval</varname> option of the
353
specified client(s); see <citerefentry><refentrytitle
354
>mandos-clients.conf</refentrytitle><manvolnum
355
>5</manvolnum></citerefentry>.
361
<term><option>--approve-by-default</option></term>
362
<term><option>--deny-by-default</option></term>
365
Set the <varname>approved_by_default</varname> option of
366
the specified client(s) to <literal>True</literal> or
367
<literal>False</literal>, respectively; see
368
<citerefentry><refentrytitle
369
>mandos-clients.conf</refentrytitle><manvolnum
370
>5</manvolnum></citerefentry>.
376
<term><option>--approval-delay
377
<replaceable>TIME</replaceable></option></term>
380
Set the <varname>approval_delay</varname> option of the
381
specified client(s); see <citerefentry><refentrytitle
382
>mandos-clients.conf</refentrytitle><manvolnum
383
>5</manvolnum></citerefentry>.
389
<term><option>--approval-duration
390
<replaceable>TIME</replaceable></option></term>
393
Set the <varname>approval_duration</varname> option of the
394
specified client(s); see <citerefentry><refentrytitle
395
>mandos-clients.conf</refentrytitle><manvolnum
396
>5</manvolnum></citerefentry>.
403
<replaceable>STRING</replaceable></option></term>
405
<replaceable>STRING</replaceable></option></term>
408
Set the <varname>host</varname> option of the specified
409
client(s); see <citerefentry><refentrytitle
410
>mandos-clients.conf</refentrytitle><manvolnum
411
>5</manvolnum></citerefentry>.
417
<term><option>--secret
418
<replaceable>FILENAME</replaceable></option></term>
420
<replaceable>FILENAME</replaceable></option></term>
423
Set the <varname>secfile</varname> option of the specified
424
client(s); see <citerefentry><refentrytitle
425
>mandos-clients.conf</refentrytitle><manvolnum
426
>5</manvolnum></citerefentry>.
432
<term><option>--approve</option></term>
433
<term><option>-A</option></term>
436
Approve client(s) if currently waiting for approval.
442
<term><option>--deny</option></term>
443
<term><option>-D</option></term>
446
Deny client(s) if currently waiting for approval.
452
<term><option>--all</option></term>
453
<term><option>-a</option></term>
456
Make the client-modifying options modify <emphasis
457
>all</emphasis> clients.
463
<term><option>--verbose</option></term>
464
<term><option>-v</option></term>
467
Show all client settings, not just a subset.
473
<term><option>--is-enabled</option></term>
474
<term><option>-V</option></term>
477
Check if a single client is enabled or not, and exit with
478
a successful exit status only if the client is enabled.
484
<term><option>--check</option></term>
487
Run self-tests. This includes any unit tests, etc.
495
<refsect1 id="overview">
496
<title>OVERVIEW</title>
497
<xi:include href="overview.xml"/>
499
This program is a small utility to generate new OpenPGP keys for
500
new Mandos clients, and to generate sections for inclusion in
501
<filename>clients.conf</filename> on the server.
505
<refsect1 id="exit_status">
506
<title>EXIT STATUS</title>
508
If the <option>--is-enabled</option> option is used, the exit
509
status will be 0 only if the specified client is enabled.
513
<!-- <refsect1 id="bugs"> -->
514
<!-- <title>BUGS</title> -->
519
<refsect1 id="example">
520
<title>EXAMPLE</title>
526
<userinput>&COMMANDNAME;</userinput>
532
To list <emphasis>all</emphasis> settings for the clients
533
named <quote>foo1.example.org</quote> and <quote
534
>foo2.example.org</quote>:
538
<!-- do not wrap this line -->
539
<userinput>&COMMANDNAME; --verbose foo1.example.org foo2.example.org</userinput>
546
To enable all clients:
549
<userinput>&COMMANDNAME; --enable --all</userinput>
555
To change timeout and interval value for the clients
556
named <quote>foo1.example.org</quote> and <quote
557
>foo2.example.org</quote>:
561
<!-- do not wrap this line -->
562
<userinput>&COMMANDNAME; --timeout="5m" --interval="1m" foo1.example.org foo2.example.org</userinput>
569
To approve all clients currently waiting for it:
572
<userinput>&COMMANDNAME; --approve --all</userinput>
577
<refsect1 id="security">
578
<title>SECURITY</title>
580
This program must be permitted to access the Mandos server via
581
the D-Bus interface. This normally requires the root user, but
582
could be configured otherwise by reconfiguring the D-Bus server.
586
<refsect1 id="see_also">
587
<title>SEE ALSO</title>
589
<citerefentry><refentrytitle>intro</refentrytitle>
590
<manvolnum>8mandos</manvolnum></citerefentry>,
591
<citerefentry><refentrytitle>mandos</refentrytitle>
592
<manvolnum>8</manvolnum></citerefentry>,
593
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
594
<manvolnum>5</manvolnum></citerefentry>,
595
<citerefentry><refentrytitle>mandos-monitor</refentrytitle>
596
<manvolnum>8</manvolnum></citerefentry>
601
<!-- Local Variables: -->
602
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
603
<!-- time-stamp-end: "[\"']>" -->
604
<!-- time-stamp-format: "%:y-%02m-%02d" -->