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-07-29">
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>
72
<arg><option>--debug</option></arg>
74
<arg rep='repeat' choice='plain'>
75
<replaceable>CLIENT</replaceable>
80
<command>&COMMANDNAME;</command>
83
<arg choice="plain"><option>--enable</option></arg>
84
<arg choice="plain"><option>-e</option></arg>
86
<arg choice="plain"><option>--disable</option></arg>
87
<arg choice="plain"><option>-d</option></arg>
91
<arg choice="plain"><option>--bump-timeout</option></arg>
92
<arg choice="plain"><option>-b</option></arg>
96
<arg choice="plain"><option>--start-checker</option></arg>
97
<arg choice="plain"><option>--stop-checker</option></arg>
101
<arg choice="plain"><option>--checker
102
<replaceable>COMMAND</replaceable></option></arg>
103
<arg choice="plain"><option>-c
104
<replaceable>COMMAND</replaceable></option></arg>
108
<arg choice="plain"><option>--timeout
109
<replaceable>TIME</replaceable></option></arg>
110
<arg choice="plain"><option>-t
111
<replaceable>TIME</replaceable></option></arg>
115
<arg choice="plain"><option>--extended-timeout
116
<replaceable>TIME</replaceable></option></arg>
120
<arg choice="plain"><option>--interval
121
<replaceable>TIME</replaceable></option></arg>
122
<arg choice="plain"><option>-i
123
<replaceable>TIME</replaceable></option></arg>
127
<arg choice="plain"><option>--approve-by-default</option
130
<arg choice="plain"><option>--deny-by-default</option></arg>
134
<arg choice="plain"><option>--approval-delay
135
<replaceable>TIME</replaceable></option></arg>
139
<arg choice="plain"><option>--approval-duration
140
<replaceable>TIME</replaceable></option></arg>
144
<arg choice="plain"><option>--host
145
<replaceable>STRING</replaceable></option></arg>
146
<arg choice="plain"><option>-H
147
<replaceable>STRING</replaceable></option></arg>
151
<arg choice="plain"><option>--secret
152
<replaceable>FILENAME</replaceable></option></arg>
153
<arg choice="plain"><option>-s
154
<replaceable>FILENAME</replaceable></option></arg>
158
<arg choice="plain"><option>--approve</option></arg>
159
<arg choice="plain"><option>-A</option></arg>
161
<arg choice="plain"><option>--deny</option></arg>
162
<arg choice="plain"><option>-D</option></arg>
166
<arg><option>--debug</option></arg>
168
<arg choice="plain"><option>--all</option></arg>
169
<arg choice="plain"><option>-a</option></arg>
170
<arg rep='repeat' choice='plain'>
171
<replaceable>CLIENT</replaceable>
176
<command>&COMMANDNAME;</command>
178
<arg choice="plain"><option>--deny</option></arg>
179
<arg choice="plain"><option>-D</option></arg>
182
<arg choice="plain"><option>--remove</option></arg>
183
<arg choice="plain"><option>-r</option></arg>
186
<arg><option>--debug</option></arg>
188
<arg choice="plain"><option>--all</option></arg>
189
<arg choice="plain"><option>-a</option></arg>
190
<arg rep='repeat' choice='plain'>
191
<replaceable>CLIENT</replaceable>
196
<command>&COMMANDNAME;</command>
198
<arg choice="plain"><option>--is-enabled</option></arg>
199
<arg choice="plain"><option>-V</option></arg>
201
<arg><option>--debug</option></arg>
202
<arg choice='plain'><replaceable>CLIENT</replaceable></arg>
205
<command>&COMMANDNAME;</command>
207
<arg choice="plain"><option>--help</option></arg>
208
<arg choice="plain"><option>-h</option></arg>
212
<command>&COMMANDNAME;</command>
214
<arg choice="plain"><option>--version</option></arg>
215
<arg choice="plain"><option>-v</option></arg>
219
<command>&COMMANDNAME;</command>
220
<arg choice="plain"><option>--check</option></arg>
224
<refsect1 id="description">
225
<title>DESCRIPTION</title>
227
<command>&COMMANDNAME;</command> is a program to control or
228
query the operation of the Mandos server
229
<citerefentry><refentrytitle>mandos</refentrytitle><manvolnum
230
>8</manvolnum></citerefentry>.
233
This program can be used to change client settings, approve or
234
deny client requests, and to remove clients from the server.
238
<refsect1 id="purpose">
239
<title>PURPOSE</title>
241
The purpose of this is to enable <emphasis>remote and unattended
242
rebooting</emphasis> of client host computer with an
243
<emphasis>encrypted root file system</emphasis>. See <xref
244
linkend="overview"/> for details.
248
<refsect1 id="options">
249
<title>OPTIONS</title>
253
<term><option>--help</option></term>
254
<term><option>-h</option></term>
257
Show a help message and exit
263
<term><option>--enable</option></term>
264
<term><option>-e</option></term>
267
Enable client(s). An enabled client will be eligble to
274
<term><option>--disable</option></term>
275
<term><option>-d</option></term>
278
Disable client(s). A disabled client will not be eligble
279
to receive its secret, and no checkers will be started for
286
<term><option>--bump-timeout</option></term>
289
Bump the timeout of the specified client(s), just as if a
290
checker had completed successfully for it/them.
296
<term><option>--start-checker</option></term>
299
Start a new checker now for the specified client(s).
305
<term><option>--stop-checker</option></term>
308
Stop any running checker for the specified client(s).
314
<term><option>--remove</option></term>
315
<term><option>-r</option></term>
318
Remove the specified client(s) from the server.
324
<term><option>--checker
325
<replaceable>COMMAND</replaceable></option></term>
327
<replaceable>COMMAND</replaceable></option></term>
330
Set the <varname>checker</varname> option of the specified
331
client(s); see <citerefentry><refentrytitle
332
>mandos-clients.conf</refentrytitle><manvolnum
333
>5</manvolnum></citerefentry>.
339
<term><option>--timeout
340
<replaceable>TIME</replaceable></option></term>
342
<replaceable>TIME</replaceable></option></term>
345
Set the <varname>timeout</varname> option of the specified
346
client(s); see <citerefentry><refentrytitle
347
>mandos-clients.conf</refentrytitle><manvolnum
348
>5</manvolnum></citerefentry>.
354
<term><option>--extended-timeout
355
<replaceable>TIME</replaceable></option></term>
358
Set the <varname>extended_timeout</varname> option of the
359
specified client(s); see <citerefentry><refentrytitle
360
>mandos-clients.conf</refentrytitle><manvolnum
361
>5</manvolnum></citerefentry>.
367
<term><option>--interval
368
<replaceable>TIME</replaceable></option></term>
370
<replaceable>TIME</replaceable></option></term>
373
Set the <varname>interval</varname> option of the
374
specified client(s); see <citerefentry><refentrytitle
375
>mandos-clients.conf</refentrytitle><manvolnum
376
>5</manvolnum></citerefentry>.
382
<term><option>--approve-by-default</option></term>
383
<term><option>--deny-by-default</option></term>
386
Set the <varname>approved_by_default</varname> option of
387
the specified client(s) to <literal>True</literal> or
388
<literal>False</literal>, respectively; see
389
<citerefentry><refentrytitle
390
>mandos-clients.conf</refentrytitle><manvolnum
391
>5</manvolnum></citerefentry>.
397
<term><option>--approval-delay
398
<replaceable>TIME</replaceable></option></term>
401
Set the <varname>approval_delay</varname> option of the
402
specified client(s); see <citerefentry><refentrytitle
403
>mandos-clients.conf</refentrytitle><manvolnum
404
>5</manvolnum></citerefentry>.
410
<term><option>--approval-duration
411
<replaceable>TIME</replaceable></option></term>
414
Set the <varname>approval_duration</varname> option of the
415
specified client(s); see <citerefentry><refentrytitle
416
>mandos-clients.conf</refentrytitle><manvolnum
417
>5</manvolnum></citerefentry>.
424
<replaceable>STRING</replaceable></option></term>
426
<replaceable>STRING</replaceable></option></term>
429
Set the <varname>host</varname> option of the specified
430
client(s); see <citerefentry><refentrytitle
431
>mandos-clients.conf</refentrytitle><manvolnum
432
>5</manvolnum></citerefentry>.
438
<term><option>--secret
439
<replaceable>FILENAME</replaceable></option></term>
441
<replaceable>FILENAME</replaceable></option></term>
444
Set the <varname>secfile</varname> option of the specified
445
client(s); see <citerefentry><refentrytitle
446
>mandos-clients.conf</refentrytitle><manvolnum
447
>5</manvolnum></citerefentry>.
453
<term><option>--approve</option></term>
454
<term><option>-A</option></term>
457
Approve client(s) if currently waiting for approval.
463
<term><option>--deny</option></term>
464
<term><option>-D</option></term>
467
Deny client(s) if currently waiting for approval.
473
<term><option>--all</option></term>
474
<term><option>-a</option></term>
477
Make the client-modifying options modify <emphasis
478
>all</emphasis> clients.
484
<term><option>--verbose</option></term>
485
<term><option>-v</option></term>
488
Show all client settings, not just a subset.
494
<term><option>--dump-json</option></term>
495
<term><option>-j</option></term>
498
Dump client settings as JSON to standard output.
504
<term><option>--is-enabled</option></term>
505
<term><option>-V</option></term>
508
Check if a single client is enabled or not, and exit with
509
a successful exit status only if the client is enabled.
515
<term><option>--debug</option></term>
518
Show debug output; currently, this means show D-Bus calls.
524
<term><option>--check</option></term>
527
Run self-tests. This includes any unit tests, etc.
535
<refsect1 id="overview">
536
<title>OVERVIEW</title>
537
<xi:include href="overview.xml"/>
539
This program is a small utility to generate new OpenPGP keys for
540
new Mandos clients, and to generate sections for inclusion in
541
<filename>clients.conf</filename> on the server.
545
<refsect1 id="exit_status">
546
<title>EXIT STATUS</title>
548
If the <option>--is-enabled</option> option is used, the exit
549
status will be 0 only if the specified client is enabled.
555
<xi:include href="bugs.xml"/>
558
<refsect1 id="example">
559
<title>EXAMPLE</title>
560
<!-- Name of test methods in class Test_commands_from_options are
561
written in comments below. When adding an example, add a
562
test too which tests the documented behavior. -->
564
<!-- Test method: test_manual_page_example_1() -->
569
<userinput>&COMMANDNAME;</userinput>
574
<!-- Test method: test_manual_page_example_2() -->
576
To list <emphasis>all</emphasis> settings 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; --verbose foo1.example.org foo2.example.org</userinput>
589
<!-- Test method: test_manual_page_example_3() -->
591
To enable all clients:
594
<userinput>&COMMANDNAME; --enable --all</userinput>
599
<!-- Test method: test_manual_page_example_4() -->
601
To change timeout and interval value for the clients
602
named <quote>foo1.example.org</quote> and <quote
603
>foo2.example.org</quote>:
607
<!-- do not wrap this line -->
608
<userinput>&COMMANDNAME; --timeout=PT5M --interval=PT1M foo1.example.org foo2.example.org</userinput>
614
<!-- Test method: test_manual_page_example_5() -->
616
To approve all clients currently waiting for approval:
619
<userinput>&COMMANDNAME; --approve --all</userinput>
624
<refsect1 id="security">
625
<title>SECURITY</title>
627
This program must be permitted to access the Mandos server via
628
the D-Bus interface. This normally requires the root user, but
629
could be configured otherwise by reconfiguring the D-Bus server.
633
<refsect1 id="see_also">
634
<title>SEE ALSO</title>
636
<citerefentry><refentrytitle>intro</refentrytitle>
637
<manvolnum>8mandos</manvolnum></citerefentry>,
638
<citerefentry><refentrytitle>mandos</refentrytitle>
639
<manvolnum>8</manvolnum></citerefentry>,
640
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
641
<manvolnum>5</manvolnum></citerefentry>,
642
<citerefentry><refentrytitle>mandos-monitor</refentrytitle>
643
<manvolnum>8</manvolnum></citerefentry>
648
<!-- Local Variables: -->
649
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
650
<!-- time-stamp-end: "[\"']>" -->
651
<!-- time-stamp-format: "%:y-%02m-%02d" -->