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-07">
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>
44
<holder>Teddy Hogeborn</holder>
45
<holder>Björn Påhlsson</holder>
47
<xi:include href="legalnotice.xml"/>
51
<refentrytitle>&COMMANDNAME;</refentrytitle>
52
<manvolnum>8</manvolnum>
56
<refname><command>&COMMANDNAME;</command></refname>
58
Control or query the operation of the Mandos server
64
<command>&COMMANDNAME;</command>
66
<arg choice="plain"><option>--verbose</option></arg>
67
<arg choice="plain"><option>-v</option></arg>
69
<arg choice="plain"><option>--dump-json</option></arg>
70
<arg choice="plain"><option>-j</option></arg>
73
<arg rep='repeat' choice='plain'>
74
<replaceable>CLIENT</replaceable>
79
<command>&COMMANDNAME;</command>
82
<arg choice="plain"><option>--enable</option></arg>
83
<arg choice="plain"><option>-e</option></arg>
85
<arg choice="plain"><option>--disable</option></arg>
86
<arg choice="plain"><option>-d</option></arg>
90
<arg choice="plain"><option>--bump-timeout</option></arg>
91
<arg choice="plain"><option>-b</option></arg>
95
<arg choice="plain"><option>--start-checker</option></arg>
96
<arg choice="plain"><option>--stop-checker</option></arg>
100
<arg choice="plain"><option>--checker
101
<replaceable>COMMAND</replaceable></option></arg>
102
<arg choice="plain"><option>-c
103
<replaceable>COMMAND</replaceable></option></arg>
107
<arg choice="plain"><option>--timeout
108
<replaceable>TIME</replaceable></option></arg>
109
<arg choice="plain"><option>-t
110
<replaceable>TIME</replaceable></option></arg>
114
<arg choice="plain"><option>--extended-timeout
115
<replaceable>TIME</replaceable></option></arg>
119
<arg choice="plain"><option>--interval
120
<replaceable>TIME</replaceable></option></arg>
121
<arg choice="plain"><option>-i
122
<replaceable>TIME</replaceable></option></arg>
126
<arg choice="plain"><option>--approve-by-default</option
129
<arg choice="plain"><option>--deny-by-default</option></arg>
133
<arg choice="plain"><option>--approval-delay
134
<replaceable>TIME</replaceable></option></arg>
138
<arg choice="plain"><option>--approval-duration
139
<replaceable>TIME</replaceable></option></arg>
143
<arg choice="plain"><option>--host
144
<replaceable>STRING</replaceable></option></arg>
145
<arg choice="plain"><option>-H
146
<replaceable>STRING</replaceable></option></arg>
150
<arg choice="plain"><option>--secret
151
<replaceable>FILENAME</replaceable></option></arg>
152
<arg choice="plain"><option>-s
153
<replaceable>FILENAME</replaceable></option></arg>
157
<arg choice="plain"><option>--approve</option></arg>
158
<arg choice="plain"><option>-A</option></arg>
160
<arg choice="plain"><option>--deny</option></arg>
161
<arg choice="plain"><option>-D</option></arg>
166
<arg choice="plain"><option>--all</option></arg>
167
<arg choice="plain"><option>-a</option></arg>
168
<arg rep='repeat' choice='plain'>
169
<replaceable>CLIENT</replaceable>
174
<command>&COMMANDNAME;</command>
176
<arg choice="plain"><option>--deny</option></arg>
177
<arg choice="plain"><option>-D</option></arg>
180
<arg choice="plain"><option>--remove</option></arg>
181
<arg choice="plain"><option>-r</option></arg>
184
<arg choice="plain"><option>--all</option></arg>
185
<arg choice="plain"><option>-a</option></arg>
186
<arg rep='repeat' choice='plain'>
187
<replaceable>CLIENT</replaceable>
192
<command>&COMMANDNAME;</command>
194
<arg choice="plain"><option>--is-enabled</option></arg>
195
<arg choice="plain"><option>-V</option></arg>
197
<arg choice='plain'><replaceable>CLIENT</replaceable></arg>
200
<command>&COMMANDNAME;</command>
202
<arg choice="plain"><option>--help</option></arg>
203
<arg choice="plain"><option>-h</option></arg>
207
<command>&COMMANDNAME;</command>
209
<arg choice="plain"><option>--version</option></arg>
210
<arg choice="plain"><option>-v</option></arg>
214
<command>&COMMANDNAME;</command>
215
<arg choice="plain"><option>--check</option></arg>
219
<refsect1 id="description">
220
<title>DESCRIPTION</title>
222
<command>&COMMANDNAME;</command> is a program to control or
223
query the operation of the Mandos server
224
<citerefentry><refentrytitle>mandos</refentrytitle><manvolnum
225
>8</manvolnum></citerefentry>.
228
This program can be used to change client settings, approve or
229
deny client requests, and to remove clients from the server.
233
<refsect1 id="purpose">
234
<title>PURPOSE</title>
236
The purpose of this is to enable <emphasis>remote and unattended
237
rebooting</emphasis> of client host computer with an
238
<emphasis>encrypted root file system</emphasis>. See <xref
239
linkend="overview"/> for details.
243
<refsect1 id="options">
244
<title>OPTIONS</title>
248
<term><option>--help</option></term>
249
<term><option>-h</option></term>
252
Show a help message and exit
258
<term><option>--enable</option></term>
259
<term><option>-e</option></term>
262
Enable client(s). An enabled client will be eligble to
269
<term><option>--disable</option></term>
270
<term><option>-d</option></term>
273
Disable client(s). A disabled client will not be eligble
274
to receive its secret, and no checkers will be started for
281
<term><option>--bump-timeout</option></term>
284
Bump the timeout of the specified client(s), just as if a
285
checker had completed successfully for it/them.
291
<term><option>--start-checker</option></term>
294
Start a new checker now for the specified client(s).
300
<term><option>--stop-checker</option></term>
303
Stop any running checker for the specified client(s).
309
<term><option>--remove</option></term>
310
<term><option>-r</option></term>
313
Remove the specified client(s) from the server.
319
<term><option>--checker
320
<replaceable>COMMAND</replaceable></option></term>
322
<replaceable>COMMAND</replaceable></option></term>
325
Set the <varname>checker</varname> option of the specified
326
client(s); see <citerefentry><refentrytitle
327
>mandos-clients.conf</refentrytitle><manvolnum
328
>5</manvolnum></citerefentry>.
334
<term><option>--timeout
335
<replaceable>TIME</replaceable></option></term>
337
<replaceable>TIME</replaceable></option></term>
340
Set the <varname>timeout</varname> option of the specified
341
client(s); see <citerefentry><refentrytitle
342
>mandos-clients.conf</refentrytitle><manvolnum
343
>5</manvolnum></citerefentry>.
349
<term><option>--extended-timeout
350
<replaceable>TIME</replaceable></option></term>
353
Set the <varname>extended_timeout</varname> option of the
354
specified client(s); see <citerefentry><refentrytitle
355
>mandos-clients.conf</refentrytitle><manvolnum
356
>5</manvolnum></citerefentry>.
362
<term><option>--interval
363
<replaceable>TIME</replaceable></option></term>
365
<replaceable>TIME</replaceable></option></term>
368
Set the <varname>interval</varname> option of the
369
specified client(s); see <citerefentry><refentrytitle
370
>mandos-clients.conf</refentrytitle><manvolnum
371
>5</manvolnum></citerefentry>.
377
<term><option>--approve-by-default</option></term>
378
<term><option>--deny-by-default</option></term>
381
Set the <varname>approved_by_default</varname> option of
382
the specified client(s) to <literal>True</literal> or
383
<literal>False</literal>, respectively; see
384
<citerefentry><refentrytitle
385
>mandos-clients.conf</refentrytitle><manvolnum
386
>5</manvolnum></citerefentry>.
392
<term><option>--approval-delay
393
<replaceable>TIME</replaceable></option></term>
396
Set the <varname>approval_delay</varname> option of the
397
specified client(s); see <citerefentry><refentrytitle
398
>mandos-clients.conf</refentrytitle><manvolnum
399
>5</manvolnum></citerefentry>.
405
<term><option>--approval-duration
406
<replaceable>TIME</replaceable></option></term>
409
Set the <varname>approval_duration</varname> option of the
410
specified client(s); see <citerefentry><refentrytitle
411
>mandos-clients.conf</refentrytitle><manvolnum
412
>5</manvolnum></citerefentry>.
419
<replaceable>STRING</replaceable></option></term>
421
<replaceable>STRING</replaceable></option></term>
424
Set the <varname>host</varname> option of the specified
425
client(s); see <citerefentry><refentrytitle
426
>mandos-clients.conf</refentrytitle><manvolnum
427
>5</manvolnum></citerefentry>.
433
<term><option>--secret
434
<replaceable>FILENAME</replaceable></option></term>
436
<replaceable>FILENAME</replaceable></option></term>
439
Set the <varname>secfile</varname> option of the specified
440
client(s); see <citerefentry><refentrytitle
441
>mandos-clients.conf</refentrytitle><manvolnum
442
>5</manvolnum></citerefentry>.
448
<term><option>--approve</option></term>
449
<term><option>-A</option></term>
452
Approve client(s) if currently waiting for approval.
458
<term><option>--deny</option></term>
459
<term><option>-D</option></term>
462
Deny client(s) if currently waiting for approval.
468
<term><option>--all</option></term>
469
<term><option>-a</option></term>
472
Make the client-modifying options modify <emphasis
473
>all</emphasis> clients.
479
<term><option>--verbose</option></term>
480
<term><option>-v</option></term>
483
Show all client settings, not just a subset.
489
<term><option>--dump-json</option></term>
490
<term><option>-j</option></term>
493
Dump client settings as JSON to standard output.
499
<term><option>--is-enabled</option></term>
500
<term><option>-V</option></term>
503
Check if a single client is enabled or not, and exit with
504
a successful exit status only if the client is enabled.
510
<term><option>--check</option></term>
513
Run self-tests. This includes any unit tests, etc.
521
<refsect1 id="overview">
522
<title>OVERVIEW</title>
523
<xi:include href="overview.xml"/>
525
This program is a small utility to generate new OpenPGP keys for
526
new Mandos clients, and to generate sections for inclusion in
527
<filename>clients.conf</filename> on the server.
531
<refsect1 id="exit_status">
532
<title>EXIT STATUS</title>
534
If the <option>--is-enabled</option> option is used, the exit
535
status will be 0 only if the specified client is enabled.
541
<xi:include href="bugs.xml"/>
544
<refsect1 id="example">
545
<title>EXAMPLE</title>
551
<userinput>&COMMANDNAME;</userinput>
557
To list <emphasis>all</emphasis> settings for the clients
558
named <quote>foo1.example.org</quote> and <quote
559
>foo2.example.org</quote>:
563
<!-- do not wrap this line -->
564
<userinput>&COMMANDNAME; --verbose foo1.example.org foo2.example.org</userinput>
571
To enable all clients:
574
<userinput>&COMMANDNAME; --enable --all</userinput>
580
To change timeout and interval value for the clients
581
named <quote>foo1.example.org</quote> and <quote
582
>foo2.example.org</quote>:
586
<!-- do not wrap this line -->
587
<userinput>&COMMANDNAME; --timeout="PT5M" --interval="PT1M" foo1.example.org foo2.example.org</userinput>
594
To approve all clients currently waiting for it:
597
<userinput>&COMMANDNAME; --approve --all</userinput>
602
<refsect1 id="security">
603
<title>SECURITY</title>
605
This program must be permitted to access the Mandos server via
606
the D-Bus interface. This normally requires the root user, but
607
could be configured otherwise by reconfiguring the D-Bus server.
611
<refsect1 id="see_also">
612
<title>SEE ALSO</title>
614
<citerefentry><refentrytitle>intro</refentrytitle>
615
<manvolnum>8mandos</manvolnum></citerefentry>,
616
<citerefentry><refentrytitle>mandos</refentrytitle>
617
<manvolnum>8</manvolnum></citerefentry>,
618
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
619
<manvolnum>5</manvolnum></citerefentry>,
620
<citerefentry><refentrytitle>mandos-monitor</refentrytitle>
621
<manvolnum>8</manvolnum></citerefentry>
626
<!-- Local Variables: -->
627
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
628
<!-- time-stamp-end: "[\"']>" -->
629
<!-- time-stamp-format: "%:y-%02m-%02d" -->