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 "2018-02-08">
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>
43
<holder>Teddy Hogeborn</holder>
44
<holder>Björn Påhlsson</holder>
46
<xi:include href="legalnotice.xml"/>
50
<refentrytitle>&COMMANDNAME;</refentrytitle>
51
<manvolnum>8</manvolnum>
55
<refname><command>&COMMANDNAME;</command></refname>
57
Control or query the operation of the Mandos server
63
<command>&COMMANDNAME;</command>
66
<arg choice="plain"><option>--enable</option></arg>
67
<arg choice="plain"><option>-e</option></arg>
69
<arg choice="plain"><option>--disable</option></arg>
70
<arg choice="plain"><option>-d</option></arg>
74
<arg choice="plain"><option>--bump-timeout</option></arg>
75
<arg choice="plain"><option>-b</option></arg>
79
<arg choice="plain"><option>--start-checker</option></arg>
83
<arg choice="plain"><option>--stop-checker</option></arg>
87
<arg choice="plain"><option>--remove</option></arg>
88
<arg choice="plain"><option>-r</option></arg>
92
<arg choice="plain"><option>--checker
93
<replaceable>COMMAND</replaceable></option></arg>
94
<arg choice="plain"><option>-c
95
<replaceable>COMMAND</replaceable></option></arg>
99
<arg choice="plain"><option>--timeout
100
<replaceable>TIME</replaceable></option></arg>
101
<arg choice="plain"><option>-t
102
<replaceable>TIME</replaceable></option></arg>
106
<arg choice="plain"><option>--extended-timeout
107
<replaceable>TIME</replaceable></option></arg>
111
<arg choice="plain"><option>--interval
112
<replaceable>TIME</replaceable></option></arg>
113
<arg choice="plain"><option>-i
114
<replaceable>TIME</replaceable></option></arg>
118
<arg choice="plain"><option>--approve-by-default</option
121
<arg choice="plain"><option>--deny-by-default</option></arg>
125
<arg choice="plain"><option>--approval-delay
126
<replaceable>TIME</replaceable></option></arg>
130
<arg choice="plain"><option>--approval-duration
131
<replaceable>TIME</replaceable></option></arg>
135
<arg choice="plain"><option>--interval
136
<replaceable>TIME</replaceable></option></arg>
137
<arg choice="plain"><option>-i
138
<replaceable>TIME</replaceable></option></arg>
142
<arg choice="plain"><option>--host
143
<replaceable>STRING</replaceable></option></arg>
144
<arg choice="plain"><option>-H
145
<replaceable>STRING</replaceable></option></arg>
149
<arg choice="plain"><option>--secret
150
<replaceable>FILENAME</replaceable></option></arg>
151
<arg choice="plain"><option>-s
152
<replaceable>FILENAME</replaceable></option></arg>
156
<arg choice="plain"><option>--approve</option></arg>
157
<arg choice="plain"><option>-A</option></arg>
159
<arg choice="plain"><option>--deny</option></arg>
160
<arg choice="plain"><option>-D</option></arg>
165
<arg choice="plain"><option>--all</option></arg>
166
<arg choice="plain"><option>-a</option></arg>
167
<arg rep='repeat' choice='plain'>
168
<replaceable>CLIENT</replaceable>
173
<command>&COMMANDNAME;</command>
175
<arg choice="plain"><option>--verbose</option></arg>
176
<arg choice="plain"><option>-v</option></arg>
178
<arg choice="plain"><option>--dump-json</option></arg>
179
<arg choice="plain"><option>-j</option></arg>
182
<arg rep='repeat' choice='plain'>
183
<replaceable>CLIENT</replaceable>
188
<command>&COMMANDNAME;</command>
190
<arg choice="plain"><option>--is-enabled</option></arg>
191
<arg choice="plain"><option>-V</option></arg>
193
<arg choice='plain'><replaceable>CLIENT</replaceable></arg>
196
<command>&COMMANDNAME;</command>
198
<arg choice="plain"><option>--help</option></arg>
199
<arg choice="plain"><option>-h</option></arg>
203
<command>&COMMANDNAME;</command>
205
<arg choice="plain"><option>--version</option></arg>
206
<arg choice="plain"><option>-v</option></arg>
210
<command>&COMMANDNAME;</command>
211
<arg choice="plain"><option>--check</option></arg>
215
<refsect1 id="description">
216
<title>DESCRIPTION</title>
218
<command>&COMMANDNAME;</command> is a program to control or
219
query the operation of the Mandos server
220
<citerefentry><refentrytitle>mandos</refentrytitle><manvolnum
221
>8</manvolnum></citerefentry>.
224
This program can be used to change client settings, approve or
225
deny client requests, and to remove clients from the server.
229
<refsect1 id="purpose">
230
<title>PURPOSE</title>
232
The purpose of this is to enable <emphasis>remote and unattended
233
rebooting</emphasis> of client host computer with an
234
<emphasis>encrypted root file system</emphasis>. See <xref
235
linkend="overview"/> for details.
239
<refsect1 id="options">
240
<title>OPTIONS</title>
244
<term><option>--help</option></term>
245
<term><option>-h</option></term>
248
Show a help message and exit
254
<term><option>--enable</option></term>
255
<term><option>-e</option></term>
258
Enable client(s). An enabled client will be eligble to
265
<term><option>--disable</option></term>
266
<term><option>-d</option></term>
269
Disable client(s). A disabled client will not be eligble
270
to receive its secret, and no checkers will be started for
277
<term><option>--bump-timeout</option></term>
280
Bump the timeout of the specified client(s), just as if a
281
checker had completed successfully for it/them.
287
<term><option>--start-checker</option></term>
290
Start a new checker now for the specified client(s).
296
<term><option>--stop-checker</option></term>
299
Stop any running checker for the specified client(s).
305
<term><option>--remove</option></term>
306
<term><option>-r</option></term>
309
Remove the specified client(s) from the server.
315
<term><option>--checker
316
<replaceable>COMMAND</replaceable></option></term>
318
<replaceable>COMMAND</replaceable></option></term>
321
Set the <varname>checker</varname> option of the specified
322
client(s); see <citerefentry><refentrytitle
323
>mandos-clients.conf</refentrytitle><manvolnum
324
>5</manvolnum></citerefentry>.
330
<term><option>--timeout
331
<replaceable>TIME</replaceable></option></term>
333
<replaceable>TIME</replaceable></option></term>
336
Set the <varname>timeout</varname> option of the specified
337
client(s); see <citerefentry><refentrytitle
338
>mandos-clients.conf</refentrytitle><manvolnum
339
>5</manvolnum></citerefentry>.
345
<term><option>--extended-timeout
346
<replaceable>TIME</replaceable></option></term>
349
Set the <varname>extended_timeout</varname> option of the
350
specified client(s); see <citerefentry><refentrytitle
351
>mandos-clients.conf</refentrytitle><manvolnum
352
>5</manvolnum></citerefentry>.
358
<term><option>--interval
359
<replaceable>TIME</replaceable></option></term>
361
<replaceable>TIME</replaceable></option></term>
364
Set the <varname>interval</varname> option of the
365
specified client(s); see <citerefentry><refentrytitle
366
>mandos-clients.conf</refentrytitle><manvolnum
367
>5</manvolnum></citerefentry>.
373
<term><option>--approve-by-default</option></term>
374
<term><option>--deny-by-default</option></term>
377
Set the <varname>approved_by_default</varname> option of
378
the specified client(s) to <literal>True</literal> or
379
<literal>False</literal>, respectively; see
380
<citerefentry><refentrytitle
381
>mandos-clients.conf</refentrytitle><manvolnum
382
>5</manvolnum></citerefentry>.
388
<term><option>--approval-delay
389
<replaceable>TIME</replaceable></option></term>
392
Set the <varname>approval_delay</varname> option of the
393
specified client(s); see <citerefentry><refentrytitle
394
>mandos-clients.conf</refentrytitle><manvolnum
395
>5</manvolnum></citerefentry>.
401
<term><option>--approval-duration
402
<replaceable>TIME</replaceable></option></term>
405
Set the <varname>approval_duration</varname> option of the
406
specified client(s); see <citerefentry><refentrytitle
407
>mandos-clients.conf</refentrytitle><manvolnum
408
>5</manvolnum></citerefentry>.
415
<replaceable>STRING</replaceable></option></term>
417
<replaceable>STRING</replaceable></option></term>
420
Set the <varname>host</varname> option of the specified
421
client(s); see <citerefentry><refentrytitle
422
>mandos-clients.conf</refentrytitle><manvolnum
423
>5</manvolnum></citerefentry>.
429
<term><option>--secret
430
<replaceable>FILENAME</replaceable></option></term>
432
<replaceable>FILENAME</replaceable></option></term>
435
Set the <varname>secfile</varname> option of the specified
436
client(s); see <citerefentry><refentrytitle
437
>mandos-clients.conf</refentrytitle><manvolnum
438
>5</manvolnum></citerefentry>.
444
<term><option>--approve</option></term>
445
<term><option>-A</option></term>
448
Approve client(s) if currently waiting for approval.
454
<term><option>--deny</option></term>
455
<term><option>-D</option></term>
458
Deny client(s) if currently waiting for approval.
464
<term><option>--all</option></term>
465
<term><option>-a</option></term>
468
Make the client-modifying options modify <emphasis
469
>all</emphasis> clients.
475
<term><option>--verbose</option></term>
476
<term><option>-v</option></term>
479
Show all client settings, not just a subset.
485
<term><option>--dump-json</option></term>
486
<term><option>-j</option></term>
489
Dump client settings as JSON to standard output.
495
<term><option>--is-enabled</option></term>
496
<term><option>-V</option></term>
499
Check if a single client is enabled or not, and exit with
500
a successful exit status only if the client is enabled.
506
<term><option>--check</option></term>
509
Run self-tests. This includes any unit tests, etc.
517
<refsect1 id="overview">
518
<title>OVERVIEW</title>
519
<xi:include href="overview.xml"/>
521
This program is a small utility to generate new OpenPGP keys for
522
new Mandos clients, and to generate sections for inclusion in
523
<filename>clients.conf</filename> on the server.
527
<refsect1 id="exit_status">
528
<title>EXIT STATUS</title>
530
If the <option>--is-enabled</option> option is used, the exit
531
status will be 0 only if the specified client is enabled.
537
<xi:include href="bugs.xml"/>
540
<refsect1 id="example">
541
<title>EXAMPLE</title>
547
<userinput>&COMMANDNAME;</userinput>
553
To list <emphasis>all</emphasis> settings for the clients
554
named <quote>foo1.example.org</quote> and <quote
555
>foo2.example.org</quote>:
559
<!-- do not wrap this line -->
560
<userinput>&COMMANDNAME; --verbose foo1.example.org foo2.example.org</userinput>
567
To enable all clients:
570
<userinput>&COMMANDNAME; --enable --all</userinput>
576
To change timeout and interval value for the clients
577
named <quote>foo1.example.org</quote> and <quote
578
>foo2.example.org</quote>:
582
<!-- do not wrap this line -->
583
<userinput>&COMMANDNAME; --timeout="5m" --interval="1m" foo1.example.org foo2.example.org</userinput>
590
To approve all clients currently waiting for it:
593
<userinput>&COMMANDNAME; --approve --all</userinput>
598
<refsect1 id="security">
599
<title>SECURITY</title>
601
This program must be permitted to access the Mandos server via
602
the D-Bus interface. This normally requires the root user, but
603
could be configured otherwise by reconfiguring the D-Bus server.
607
<refsect1 id="see_also">
608
<title>SEE ALSO</title>
610
<citerefentry><refentrytitle>intro</refentrytitle>
611
<manvolnum>8mandos</manvolnum></citerefentry>,
612
<citerefentry><refentrytitle>mandos</refentrytitle>
613
<manvolnum>8</manvolnum></citerefentry>,
614
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
615
<manvolnum>5</manvolnum></citerefentry>,
616
<citerefentry><refentrytitle>mandos-monitor</refentrytitle>
617
<manvolnum>8</manvolnum></citerefentry>
622
<!-- Local Variables: -->
623
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
624
<!-- time-stamp-end: "[\"']>" -->
625
<!-- time-stamp-format: "%:y-%02m-%02d" -->