To get this branch, use:
bzr branch
http://bzr.recompile.se/loggerhead/mandos/release
« back to all changes in this revision
Viewing changes to mandos-ctl.xml
- browse files at revision 237.7.598
- compare with another revision
- download diff
- download tarball
- view history from revision 237.7.598
- Committer: Teddy Hogeborn
- Date: 2019-03-10 02:35:22 UTC
- mto: This revision was merged to the branch mainline in revision 382.
- Revision ID: teddy@recompile.se-20190310023522-cvos2tw2si6t7if3
mandos-ctl: Minimize number of D-Bus calls
* mandos-ctl (Command.run): Now takes a {objpath: properties} dict,
followed by optional "bus" and "mandos"
arguments. Use "bus" to connect to
clients when dispatching to method
run_on_one_client(). All callers changed.
(IsEnabledCmd.run): New.
(IsEnabledCmd.run_on_one_client): Remove.
(ApproveCmd.run_on_one_client): Add busname to debug output.
(DenyCmd.run_on_one_client): - '' -
(main): In D-Bus debug output, change "name" to "busname". Also,
don't connect to clients, just use the object path as the
key of the "clients" dict passed to Command.run().
(TestCmd.clients): Changed to an {objpath: properties} dict.
(TestCmd.one_client): - '' -
(TestCmd.bus): New mock bus object having a get_object() method.
* mandos-ctl (Command.run): Now takes a {objpath: properties} dict,
followed by optional "bus" and "mandos"
arguments. Use "bus" to connect to
clients when dispatching to method
run_on_one_client(). All callers changed.
(IsEnabledCmd.run): New.
(IsEnabledCmd.run_on_one_client): Remove.
(ApproveCmd.run_on_one_client): Add busname to debug output.
(DenyCmd.run_on_one_client): - '' -
(main): In D-Bus debug output, change "name" to "busname". Also,
don't connect to clients, just use the object path as the
key of the "clients" dict passed to Command.run().
(TestCmd.clients): Changed to an {objpath: properties} dict.
(TestCmd.one_client): - '' -
(TestCmd.bus): New mock bus object having a get_object() method.
- files added:
- DBUS-API
- debian/source
- debian/upstream
- network-hooks.d
- plugin-helpers
- files removed:
- initramfs-tools-hook-conf
- files modified:
- .bzrignore
added
removed
mandos-ctl.xml
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-09">
6
<!ENTITY % common SYSTEM "common.ent">
7
%common;
8
]>
9
10
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
11
<refentryinfo>
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>
17
<authorgroup>
18
<author>
19
<firstname>Björn</firstname>
20
<surname>Påhlsson</surname>
21
<address>
22
<email>belorn@recompile.se</email>
23
</address>
24
</author>
25
<author>
26
<firstname>Teddy</firstname>
27
<surname>Hogeborn</surname>
28
<address>
29
<email>teddy@recompile.se</email>
30
</address>
31
</author>
32
</authorgroup>
33
<copyright>
34
<year>2010</year>
35
<year>2011</year>
36
<year>2012</year>
37
<year>2013</year>
38
<year>2014</year>
39
<year>2015</year>
40
<year>2016</year>
41
<year>2017</year>
42
<year>2018</year>
43
<year>2019</year>
44
<holder>Teddy Hogeborn</holder>
45
<holder>Björn Påhlsson</holder>
46
</copyright>
47
<xi:include href="legalnotice.xml"/>
48
</refentryinfo>
49
50
<refmeta>
51
<refentrytitle>&COMMANDNAME;</refentrytitle>
52
<manvolnum>8</manvolnum>
53
</refmeta>
54
55
<refnamediv>
56
<refname><command>&COMMANDNAME;</command></refname>
57
<refpurpose>
58
Control or query the operation of the Mandos server
59
</refpurpose>
60
</refnamediv>
61
62
<refsynopsisdiv>
63
<cmdsynopsis>
64
<command>&COMMANDNAME;</command>
65
<group>
66
<arg choice="plain"><option>--verbose</option></arg>
67
<arg choice="plain"><option>-v</option></arg>
68
<sbr/>
69
<arg choice="plain"><option>--dump-json</option></arg>
70
<arg choice="plain"><option>-j</option></arg>
71
</group>
72
<arg><option>--debug</option></arg>
73
<group>
74
<arg rep='repeat' choice='plain'>
75
<replaceable>CLIENT</replaceable>
76
</arg>
77
</group>
78
</cmdsynopsis>
79
<cmdsynopsis>
80
<command>&COMMANDNAME;</command>
81
<group choice="req">
82
<group>
83
<arg choice="plain"><option>--enable</option></arg>
84
<arg choice="plain"><option>-e</option></arg>
85
<sbr/>
86
<arg choice="plain"><option>--disable</option></arg>
87
<arg choice="plain"><option>-d</option></arg>
88
</group>
89
<sbr/>
90
<group>
91
<arg choice="plain"><option>--bump-timeout</option></arg>
92
<arg choice="plain"><option>-b</option></arg>
93
</group>
94
<sbr/>
95
<group>
96
<arg choice="plain"><option>--start-checker</option></arg>
97
<arg choice="plain"><option>--stop-checker</option></arg>
98
</group>
99
<sbr/>
100
<group>
101
<arg choice="plain"><option>--checker
102
<replaceable>COMMAND</replaceable></option></arg>
103
<arg choice="plain"><option>-c
104
<replaceable>COMMAND</replaceable></option></arg>
105
</group>
106
<sbr/>
107
<group>
108
<arg choice="plain"><option>--timeout
109
<replaceable>TIME</replaceable></option></arg>
110
<arg choice="plain"><option>-t
111
<replaceable>TIME</replaceable></option></arg>
112
</group>
113
<sbr/>
114
<group>
115
<arg choice="plain"><option>--extended-timeout
116
<replaceable>TIME</replaceable></option></arg>
117
</group>
118
<sbr/>
119
<group>
120
<arg choice="plain"><option>--interval
121
<replaceable>TIME</replaceable></option></arg>
122
<arg choice="plain"><option>-i
123
<replaceable>TIME</replaceable></option></arg>
124
</group>
125
<sbr/>
126
<group>
127
<arg choice="plain"><option>--approve-by-default</option
128
></arg>
129
<sbr/>
130
<arg choice="plain"><option>--deny-by-default</option></arg>
131
</group>
132
<sbr/>
133
<group>
134
<arg choice="plain"><option>--approval-delay
135
<replaceable>TIME</replaceable></option></arg>
136
</group>
137
<sbr/>
138
<group>
139
<arg choice="plain"><option>--approval-duration
140
<replaceable>TIME</replaceable></option></arg>
141
</group>
142
<sbr/>
143
<group>
144
<arg choice="plain"><option>--host
145
<replaceable>STRING</replaceable></option></arg>
146
<arg choice="plain"><option>-H
147
<replaceable>STRING</replaceable></option></arg>
148
</group>
149
<sbr/>
150
<group>
151
<arg choice="plain"><option>--secret
152
<replaceable>FILENAME</replaceable></option></arg>
153
<arg choice="plain"><option>-s
154
<replaceable>FILENAME</replaceable></option></arg>
155
</group>
156
<sbr/>
157
<group>
158
<arg choice="plain"><option>--approve</option></arg>
159
<arg choice="plain"><option>-A</option></arg>
160
<sbr/>
161
<arg choice="plain"><option>--deny</option></arg>
162
<arg choice="plain"><option>-D</option></arg>
163
</group>
164
</group>
165
<sbr/>
166
<arg><option>--debug</option></arg>
167
<group choice="req">
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>
172
</arg>
173
</group>
174
</cmdsynopsis>
175
<cmdsynopsis>
176
<command>&COMMANDNAME;</command>
177
<group>
178
<arg choice="plain"><option>--deny</option></arg>
179
<arg choice="plain"><option>-D</option></arg>
180
</group>
181
<group choice="req">
182
<arg choice="plain"><option>--remove</option></arg>
183
<arg choice="plain"><option>-r</option></arg>
184
</group>
185
<sbr/>
186
<arg><option>--debug</option></arg>
187
<group choice="req">
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>
192
</arg>
193
</group>
194
</cmdsynopsis>
195
<cmdsynopsis>
196
<command>&COMMANDNAME;</command>
197
<group choice="req">
198
<arg choice="plain"><option>--is-enabled</option></arg>
199
<arg choice="plain"><option>-V</option></arg>
200
</group>
201
<arg><option>--debug</option></arg>
202
<arg choice='plain'><replaceable>CLIENT</replaceable></arg>
203
</cmdsynopsis>
204
<cmdsynopsis>
205
<command>&COMMANDNAME;</command>
206
<group choice="req">
207
<arg choice="plain"><option>--help</option></arg>
208
<arg choice="plain"><option>-h</option></arg>
209
</group>
210
</cmdsynopsis>
211
<cmdsynopsis>
212
<command>&COMMANDNAME;</command>
213
<group choice="req">
214
<arg choice="plain"><option>--version</option></arg>
215
<arg choice="plain"><option>-v</option></arg>
216
</group>
217
</cmdsynopsis>
218
<cmdsynopsis>
219
<command>&COMMANDNAME;</command>
220
<arg choice="plain"><option>--check</option></arg>
221
</cmdsynopsis>
222
</refsynopsisdiv>
223
224
<refsect1 id="description">
225
<title>DESCRIPTION</title>
226
<para>
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>.
231
</para>
232
<para>
233
This program can be used to change client settings, approve or
234
deny client requests, and to remove clients from the server.
235
</para>
236
</refsect1>
237
238
<refsect1 id="purpose">
239
<title>PURPOSE</title>
240
<para>
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.
245
</para>
246
</refsect1>
247
248
<refsect1 id="options">
249
<title>OPTIONS</title>
250
251
<variablelist>
252
<varlistentry>
253
<term><option>--help</option></term>
254
<term><option>-h</option></term>
255
<listitem>
256
<para>
257
Show a help message and exit
258
</para>
259
</listitem>
260
</varlistentry>
261
262
<varlistentry>
263
<term><option>--enable</option></term>
264
<term><option>-e</option></term>
265
<listitem>
266
<para>
267
Enable client(s). An enabled client will be eligble to
268
receive its secret.
269
</para>
270
</listitem>
271
</varlistentry>
272
273
<varlistentry>
274
<term><option>--disable</option></term>
275
<term><option>-d</option></term>
276
<listitem>
277
<para>
278
Disable client(s). A disabled client will not be eligble
279
to receive its secret, and no checkers will be started for
280
it.
281
</para>
282
</listitem>
283
</varlistentry>
284
285
<varlistentry>
286
<term><option>--bump-timeout</option></term>
287
<listitem>
288
<para>
289
Bump the timeout of the specified client(s), just as if a
290
checker had completed successfully for it/them.
291
</para>
292
</listitem>
293
</varlistentry>
294
295
<varlistentry>
296
<term><option>--start-checker</option></term>
297
<listitem>
298
<para>
299
Start a new checker now for the specified client(s).
300
</para>
301
</listitem>
302
</varlistentry>
303
304
<varlistentry>
305
<term><option>--stop-checker</option></term>
306
<listitem>
307
<para>
308
Stop any running checker for the specified client(s).
309
</para>
310
</listitem>
311
</varlistentry>
312
313
<varlistentry>
314
<term><option>--remove</option></term>
315
<term><option>-r</option></term>
316
<listitem>
317
<para>
318
Remove the specified client(s) from the server.
319
</para>
320
</listitem>
321
</varlistentry>
322
323
<varlistentry>
324
<term><option>--checker
325
<replaceable>COMMAND</replaceable></option></term>
326
<term><option>-c
327
<replaceable>COMMAND</replaceable></option></term>
328
<listitem>
329
<para>
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>.
334
</para>
335
</listitem>
336
</varlistentry>
337
338
<varlistentry>
339
<term><option>--timeout
340
<replaceable>TIME</replaceable></option></term>
341
<term><option>-t
342
<replaceable>TIME</replaceable></option></term>
343
<listitem>
344
<para>
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>.
349
</para>
350
</listitem>
351
</varlistentry>
352
353
<varlistentry>
354
<term><option>--extended-timeout
355
<replaceable>TIME</replaceable></option></term>
356
<listitem>
357
<para>
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>.
362
</para>
363
</listitem>
364
</varlistentry>
365
366
<varlistentry>
367
<term><option>--interval
368
<replaceable>TIME</replaceable></option></term>
369
<term><option>-i
370
<replaceable>TIME</replaceable></option></term>
371
<listitem>
372
<para>
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>.
377
</para>
378
</listitem>
379
</varlistentry>
380
381
<varlistentry>
382
<term><option>--approve-by-default</option></term>
383
<term><option>--deny-by-default</option></term>
384
<listitem>
385
<para>
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>.
392
</para>
393
</listitem>
394
</varlistentry>
395
396
<varlistentry>
397
<term><option>--approval-delay
398
<replaceable>TIME</replaceable></option></term>
399
<listitem>
400
<para>
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>.
405
</para>
406
</listitem>
407
</varlistentry>
408
409
<varlistentry>
410
<term><option>--approval-duration
411
<replaceable>TIME</replaceable></option></term>
412
<listitem>
413
<para>
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>.
418
</para>
419
</listitem>
420
</varlistentry>
421
422
<varlistentry>
423
<term><option>--host
424
<replaceable>STRING</replaceable></option></term>
425
<term><option>-H
426
<replaceable>STRING</replaceable></option></term>
427
<listitem>
428
<para>
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>.
433
</para>
434
</listitem>
435
</varlistentry>
436
437
<varlistentry>
438
<term><option>--secret
439
<replaceable>FILENAME</replaceable></option></term>
440
<term><option>-s
441
<replaceable>FILENAME</replaceable></option></term>
442
<listitem>
443
<para>
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>.
448
</para>
449
</listitem>
450
</varlistentry>
451
452
<varlistentry>
453
<term><option>--approve</option></term>
454
<term><option>-A</option></term>
455
<listitem>
456
<para>
457
Approve client(s) if currently waiting for approval.
458
</para>
459
</listitem>
460
</varlistentry>
461
462
<varlistentry>
463
<term><option>--deny</option></term>
464
<term><option>-D</option></term>
465
<listitem>
466
<para>
467
Deny client(s) if currently waiting for approval.
468
</para>
469
</listitem>
470
</varlistentry>
471
472
<varlistentry>
473
<term><option>--all</option></term>
474
<term><option>-a</option></term>
475
<listitem>
476
<para>
477
Make the client-modifying options modify <emphasis
478
>all</emphasis> clients.
479
</para>
480
</listitem>
481
</varlistentry>
482
483
<varlistentry>
484
<term><option>--verbose</option></term>
485
<term><option>-v</option></term>
486
<listitem>
487
<para>
488
Show all client settings, not just a subset.
489
</para>
490
</listitem>
491
</varlistentry>
492
493
<varlistentry>
494
<term><option>--dump-json</option></term>
495
<term><option>-j</option></term>
496
<listitem>
497
<para>
498
Dump client settings as JSON to standard output.
499
</para>
500
</listitem>
501
</varlistentry>
502
503
<varlistentry>
504
<term><option>--is-enabled</option></term>
505
<term><option>-V</option></term>
506
<listitem>
507
<para>
508
Check if a single client is enabled or not, and exit with
509
a successful exit status only if the client is enabled.
510
</para>
511
</listitem>
512
</varlistentry>
513
514
<varlistentry>
515
<term><option>--debug</option></term>
516
<listitem>
517
<para>
518
Show debug output; currently, this means show D-Bus calls.
519
</para>
520
</listitem>
521
</varlistentry>
522
523
<varlistentry>
524
<term><option>--check</option></term>
525
<listitem>
526
<para>
527
Run self-tests. This includes any unit tests, etc.
528
</para>
529
</listitem>
530
</varlistentry>
531
532
</variablelist>
533
</refsect1>
534
535
<refsect1 id="overview">
536
<title>OVERVIEW</title>
537
<xi:include href="overview.xml"/>
538
<para>
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.
542
</para>
543
</refsect1>
544
545
<refsect1 id="exit_status">
546
<title>EXIT STATUS</title>
547
<para>
548
If the <option>--is-enabled</option> option is used, the exit
549
status will be 0 only if the specified client is enabled.
550
</para>
551
</refsect1>
552
553
<refsect1 id="bugs">
554
<title>BUGS</title>
555
<xi:include href="bugs.xml"/>
556
</refsect1>
557
558
<refsect1 id="example">
559
<title>EXAMPLE</title>
560
<informalexample>
561
<para>
562
To list all clients:
563
</para>
564
<para>
565
<userinput>&COMMANDNAME;</userinput>
566
</para>
567
</informalexample>
568
569
<informalexample>
570
<para>
571
To list <emphasis>all</emphasis> settings for the clients
572
named <quote>foo1.example.org</quote> and <quote
573
>foo2.example.org</quote>:
574
</para>
575
<para>
576
577
<!-- do not wrap this line -->
578
<userinput>&COMMANDNAME; --verbose foo1.example.org foo2.example.org</userinput>
579
580
</para>
581
</informalexample>
582
583
<informalexample>
584
<para>
585
To enable all clients:
586
</para>
587
<para>
588
<userinput>&COMMANDNAME; --enable --all</userinput>
589
</para>
590
</informalexample>
591
592
<informalexample>
593
<para>
594
To change timeout and interval value for the clients
595
named <quote>foo1.example.org</quote> and <quote
596
>foo2.example.org</quote>:
597
</para>
598
<para>
599
600
<!-- do not wrap this line -->
601
<userinput>&COMMANDNAME; --timeout="PT5M" --interval="PT1M" foo1.example.org foo2.example.org</userinput>
602
603
</para>
604
</informalexample>
605
606
<informalexample>
607
<para>
608
To approve all clients currently waiting for it:
609
</para>
610
<para>
611
<userinput>&COMMANDNAME; --approve --all</userinput>
612
</para>
613
</informalexample>
614
</refsect1>
615
616
<refsect1 id="security">
617
<title>SECURITY</title>
618
<para>
619
This program must be permitted to access the Mandos server via
620
the D-Bus interface. This normally requires the root user, but
621
could be configured otherwise by reconfiguring the D-Bus server.
622
</para>
623
</refsect1>
624
625
<refsect1 id="see_also">
626
<title>SEE ALSO</title>
627
<para>
628
<citerefentry><refentrytitle>intro</refentrytitle>
629
<manvolnum>8mandos</manvolnum></citerefentry>,
630
<citerefentry><refentrytitle>mandos</refentrytitle>
631
<manvolnum>8</manvolnum></citerefentry>,
632
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
633
<manvolnum>5</manvolnum></citerefentry>,
634
<citerefentry><refentrytitle>mandos-monitor</refentrytitle>
635
<manvolnum>8</manvolnum></citerefentry>
636
</para>
637
</refsect1>
638
639
</refentry>
640
<!-- Local Variables: -->
641
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
642
<!-- time-stamp-end: "[\"']>" -->
643
<!-- time-stamp-format: "%:y-%02m-%02d" -->
644
<!-- End: -->
Loggerhead is a web-based interface for Breezy
Version: 2.0.2.dev0