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-02-10">
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>
67
<arg choice="plain"><option>--enable</option></arg>
68
<arg choice="plain"><option>-e</option></arg>
70
<arg choice="plain"><option>--disable</option></arg>
71
<arg choice="plain"><option>-d</option></arg>
75
<arg choice="plain"><option>--bump-timeout</option></arg>
76
<arg choice="plain"><option>-b</option></arg>
80
<arg choice="plain"><option>--start-checker</option></arg>
84
<arg choice="plain"><option>--stop-checker</option></arg>
88
<arg choice="plain"><option>--remove</option></arg>
89
<arg choice="plain"><option>-r</option></arg>
93
<arg choice="plain"><option>--checker
94
<replaceable>COMMAND</replaceable></option></arg>
95
<arg choice="plain"><option>-c
96
<replaceable>COMMAND</replaceable></option></arg>
100
<arg choice="plain"><option>--timeout
101
<replaceable>TIME</replaceable></option></arg>
102
<arg choice="plain"><option>-t
103
<replaceable>TIME</replaceable></option></arg>
107
<arg choice="plain"><option>--extended-timeout
108
<replaceable>TIME</replaceable></option></arg>
112
<arg choice="plain"><option>--interval
113
<replaceable>TIME</replaceable></option></arg>
114
<arg choice="plain"><option>-i
115
<replaceable>TIME</replaceable></option></arg>
119
<arg choice="plain"><option>--approve-by-default</option
122
<arg choice="plain"><option>--deny-by-default</option></arg>
126
<arg choice="plain"><option>--approval-delay
127
<replaceable>TIME</replaceable></option></arg>
131
<arg choice="plain"><option>--approval-duration
132
<replaceable>TIME</replaceable></option></arg>
136
<arg choice="plain"><option>--interval
137
<replaceable>TIME</replaceable></option></arg>
138
<arg choice="plain"><option>-i
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>--verbose</option></arg>
177
<arg choice="plain"><option>-v</option></arg>
179
<arg choice="plain"><option>--dump-json</option></arg>
180
<arg choice="plain"><option>-j</option></arg>
183
<arg rep='repeat' choice='plain'>
184
<replaceable>CLIENT</replaceable>
189
<command>&COMMANDNAME;</command>
191
<arg choice="plain"><option>--is-enabled</option></arg>
192
<arg choice="plain"><option>-V</option></arg>
194
<arg choice='plain'><replaceable>CLIENT</replaceable></arg>
197
<command>&COMMANDNAME;</command>
199
<arg choice="plain"><option>--help</option></arg>
200
<arg choice="plain"><option>-h</option></arg>
204
<command>&COMMANDNAME;</command>
206
<arg choice="plain"><option>--version</option></arg>
207
<arg choice="plain"><option>-v</option></arg>
211
<command>&COMMANDNAME;</command>
212
<arg choice="plain"><option>--check</option></arg>
216
<refsect1 id="description">
217
<title>DESCRIPTION</title>
219
<command>&COMMANDNAME;</command> is a program to control or
220
query the operation of the Mandos server
221
<citerefentry><refentrytitle>mandos</refentrytitle><manvolnum
222
>8</manvolnum></citerefentry>.
225
This program can be used to change client settings, approve or
226
deny client requests, and to remove clients from the server.
230
<refsect1 id="purpose">
231
<title>PURPOSE</title>
233
The purpose of this is to enable <emphasis>remote and unattended
234
rebooting</emphasis> of client host computer with an
235
<emphasis>encrypted root file system</emphasis>. See <xref
236
linkend="overview"/> for details.
240
<refsect1 id="options">
241
<title>OPTIONS</title>
245
<term><option>--help</option></term>
246
<term><option>-h</option></term>
249
Show a help message and exit
255
<term><option>--enable</option></term>
256
<term><option>-e</option></term>
259
Enable client(s). An enabled client will be eligble to
266
<term><option>--disable</option></term>
267
<term><option>-d</option></term>
270
Disable client(s). A disabled client will not be eligble
271
to receive its secret, and no checkers will be started for
278
<term><option>--bump-timeout</option></term>
281
Bump the timeout of the specified client(s), just as if a
282
checker had completed successfully for it/them.
288
<term><option>--start-checker</option></term>
291
Start a new checker now for the specified client(s).
297
<term><option>--stop-checker</option></term>
300
Stop any running checker for the specified client(s).
306
<term><option>--remove</option></term>
307
<term><option>-r</option></term>
310
Remove the specified client(s) from the server.
316
<term><option>--checker
317
<replaceable>COMMAND</replaceable></option></term>
319
<replaceable>COMMAND</replaceable></option></term>
322
Set the <varname>checker</varname> option of the specified
323
client(s); see <citerefentry><refentrytitle
324
>mandos-clients.conf</refentrytitle><manvolnum
325
>5</manvolnum></citerefentry>.
331
<term><option>--timeout
332
<replaceable>TIME</replaceable></option></term>
334
<replaceable>TIME</replaceable></option></term>
337
Set the <varname>timeout</varname> option of the specified
338
client(s); see <citerefentry><refentrytitle
339
>mandos-clients.conf</refentrytitle><manvolnum
340
>5</manvolnum></citerefentry>.
346
<term><option>--extended-timeout
347
<replaceable>TIME</replaceable></option></term>
350
Set the <varname>extended_timeout</varname> option of the
351
specified client(s); see <citerefentry><refentrytitle
352
>mandos-clients.conf</refentrytitle><manvolnum
353
>5</manvolnum></citerefentry>.
359
<term><option>--interval
360
<replaceable>TIME</replaceable></option></term>
362
<replaceable>TIME</replaceable></option></term>
365
Set the <varname>interval</varname> option of the
366
specified client(s); see <citerefentry><refentrytitle
367
>mandos-clients.conf</refentrytitle><manvolnum
368
>5</manvolnum></citerefentry>.
374
<term><option>--approve-by-default</option></term>
375
<term><option>--deny-by-default</option></term>
378
Set the <varname>approved_by_default</varname> option of
379
the specified client(s) to <literal>True</literal> or
380
<literal>False</literal>, respectively; see
381
<citerefentry><refentrytitle
382
>mandos-clients.conf</refentrytitle><manvolnum
383
>5</manvolnum></citerefentry>.
389
<term><option>--approval-delay
390
<replaceable>TIME</replaceable></option></term>
393
Set the <varname>approval_delay</varname> option of the
394
specified client(s); see <citerefentry><refentrytitle
395
>mandos-clients.conf</refentrytitle><manvolnum
396
>5</manvolnum></citerefentry>.
402
<term><option>--approval-duration
403
<replaceable>TIME</replaceable></option></term>
406
Set the <varname>approval_duration</varname> option of the
407
specified client(s); see <citerefentry><refentrytitle
408
>mandos-clients.conf</refentrytitle><manvolnum
409
>5</manvolnum></citerefentry>.
416
<replaceable>STRING</replaceable></option></term>
418
<replaceable>STRING</replaceable></option></term>
421
Set the <varname>host</varname> option of the specified
422
client(s); see <citerefentry><refentrytitle
423
>mandos-clients.conf</refentrytitle><manvolnum
424
>5</manvolnum></citerefentry>.
430
<term><option>--secret
431
<replaceable>FILENAME</replaceable></option></term>
433
<replaceable>FILENAME</replaceable></option></term>
436
Set the <varname>secfile</varname> option of the specified
437
client(s); see <citerefentry><refentrytitle
438
>mandos-clients.conf</refentrytitle><manvolnum
439
>5</manvolnum></citerefentry>.
445
<term><option>--approve</option></term>
446
<term><option>-A</option></term>
449
Approve client(s) if currently waiting for approval.
455
<term><option>--deny</option></term>
456
<term><option>-D</option></term>
459
Deny client(s) if currently waiting for approval.
465
<term><option>--all</option></term>
466
<term><option>-a</option></term>
469
Make the client-modifying options modify <emphasis
470
>all</emphasis> clients.
476
<term><option>--verbose</option></term>
477
<term><option>-v</option></term>
480
Show all client settings, not just a subset.
486
<term><option>--dump-json</option></term>
487
<term><option>-j</option></term>
490
Dump client settings as JSON to standard output.
496
<term><option>--is-enabled</option></term>
497
<term><option>-V</option></term>
500
Check if a single client is enabled or not, and exit with
501
a successful exit status only if the client is enabled.
507
<term><option>--check</option></term>
510
Run self-tests. This includes any unit tests, etc.
518
<refsect1 id="overview">
519
<title>OVERVIEW</title>
520
<xi:include href="overview.xml"/>
522
This program is a small utility to generate new OpenPGP keys for
523
new Mandos clients, and to generate sections for inclusion in
524
<filename>clients.conf</filename> on the server.
528
<refsect1 id="exit_status">
529
<title>EXIT STATUS</title>
531
If the <option>--is-enabled</option> option is used, the exit
532
status will be 0 only if the specified client is enabled.
538
<xi:include href="bugs.xml"/>
541
<refsect1 id="example">
542
<title>EXAMPLE</title>
548
<userinput>&COMMANDNAME;</userinput>
554
To list <emphasis>all</emphasis> settings for the clients
555
named <quote>foo1.example.org</quote> and <quote
556
>foo2.example.org</quote>:
560
<!-- do not wrap this line -->
561
<userinput>&COMMANDNAME; --verbose foo1.example.org foo2.example.org</userinput>
568
To enable all clients:
571
<userinput>&COMMANDNAME; --enable --all</userinput>
577
To change timeout and interval value for the clients
578
named <quote>foo1.example.org</quote> and <quote
579
>foo2.example.org</quote>:
583
<!-- do not wrap this line -->
584
<userinput>&COMMANDNAME; --timeout="5m" --interval="1m" foo1.example.org foo2.example.org</userinput>
591
To approve all clients currently waiting for it:
594
<userinput>&COMMANDNAME; --approve --all</userinput>
599
<refsect1 id="security">
600
<title>SECURITY</title>
602
This program must be permitted to access the Mandos server via
603
the D-Bus interface. This normally requires the root user, but
604
could be configured otherwise by reconfiguring the D-Bus server.
608
<refsect1 id="see_also">
609
<title>SEE ALSO</title>
611
<citerefentry><refentrytitle>intro</refentrytitle>
612
<manvolnum>8mandos</manvolnum></citerefentry>,
613
<citerefentry><refentrytitle>mandos</refentrytitle>
614
<manvolnum>8</manvolnum></citerefentry>,
615
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
616
<manvolnum>5</manvolnum></citerefentry>,
617
<citerefentry><refentrytitle>mandos-monitor</refentrytitle>
618
<manvolnum>8</manvolnum></citerefentry>
623
<!-- Local Variables: -->
624
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
625
<!-- time-stamp-end: "[\"']>" -->
626
<!-- time-stamp-format: "%:y-%02m-%02d" -->