To get this branch, use:
bzr branch
http://bzr.recompile.se/loggerhead/mandos/trunk
« back to all changes in this revision
Viewing changes to mandos-ctl.xml
- browse files at revision 1312
- compare with another revision
- download diff
- download tarball
- view history from revision 1312
- Committer: Teddy Hogeborn
- Date: 2024-11-17 18:43:11 UTC
- Revision ID: teddy@recompile.se-20241117184311-ox25kvngy62h209g
Debian package: Avoid suggesting a C compiler unnecessarily
The list of suggested packages, meant to enable the "mandos" program
to find the correct value of SO_BINDTODEVICE by using a C compiler,
are not necessary when Python 3.3 or later is used, since it has the
SO_BINDTODEVICE constant defined in the "socket" module. Also, Python
2.6 or older has the same constant in the old "IN" module. Therefore,
we should suggest these Python versions as alternatives to a C
compiler, so that a C compiler is not installed unnecessarily.
debian/control (Package: mandos/Suggests): Add "python3 (>= 3.3)" and
"python (<= 2.6)" as alternatives to "libc6-dev | libc-dev" and
"c-compiler".
The list of suggested packages, meant to enable the "mandos" program
to find the correct value of SO_BINDTODEVICE by using a C compiler,
are not necessary when Python 3.3 or later is used, since it has the
SO_BINDTODEVICE constant defined in the "socket" module. Also, Python
2.6 or older has the same constant in the old "IN" module. Therefore,
we should suggest these Python versions as alternatives to a C
compiler, so that a C compiler is not installed unnecessarily.
debian/control (Package: mandos/Suggests): Add "python3 (>= 3.3)" and
"python (<= 2.6)" as alternatives to "libc6-dev | libc-dev" and
"c-compiler".
- files added:
- .bzr-builddeb
- debian
- debian/po
- debian/source
- debian/tests
- debian/upstream
- dracut-module
- network-hooks.d
- plugin-helpers
- files removed:
- initramfs-tools-hook-conf
- files renamed:
- plugins.d/password-request.c => plugins.d/mandos-client.c
- plugins.d/password-request.xml => plugins.d/mandos-client.xml
- 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-07-29">
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
<!-- 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. -->
563
<informalexample>
564
<!-- Test method: test_manual_page_example_1() -->
565
<para>
566
To list all clients:
567
</para>
568
<para>
569
<userinput>&COMMANDNAME;</userinput>
570
</para>
571
</informalexample>
572
573
<informalexample>
574
<!-- Test method: test_manual_page_example_2() -->
575
<para>
576
To list <emphasis>all</emphasis> settings for the clients
577
named <quote>foo1.example.org</quote> and <quote
578
>foo2.example.org</quote>:
579
</para>
580
<para>
581
582
<!-- do not wrap this line -->
583
<userinput>&COMMANDNAME; --verbose foo1.example.org foo2.example.org</userinput>
584
585
</para>
586
</informalexample>
587
588
<informalexample>
589
<!-- Test method: test_manual_page_example_3() -->
590
<para>
591
To enable all clients:
592
</para>
593
<para>
594
<userinput>&COMMANDNAME; --enable --all</userinput>
595
</para>
596
</informalexample>
597
598
<informalexample>
599
<!-- Test method: test_manual_page_example_4() -->
600
<para>
601
To change timeout and interval value for the clients
602
named <quote>foo1.example.org</quote> and <quote
603
>foo2.example.org</quote>:
604
</para>
605
<para>
606
607
<!-- do not wrap this line -->
608
<userinput>&COMMANDNAME; --timeout=PT5M --interval=PT1M foo1.example.org foo2.example.org</userinput>
609
610
</para>
611
</informalexample>
612
613
<informalexample>
614
<!-- Test method: test_manual_page_example_5() -->
615
<para>
616
To approve all clients currently waiting for approval:
617
</para>
618
<para>
619
<userinput>&COMMANDNAME; --approve --all</userinput>
620
</para>
621
</informalexample>
622
</refsect1>
623
624
<refsect1 id="security">
625
<title>SECURITY</title>
626
<para>
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.
630
</para>
631
</refsect1>
632
633
<refsect1 id="see_also">
634
<title>SEE ALSO</title>
635
<para>
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>
644
</para>
645
</refsect1>
646
647
</refentry>
648
<!-- Local Variables: -->
649
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
650
<!-- time-stamp-end: "[\"']>" -->
651
<!-- time-stamp-format: "%:y-%02m-%02d" -->
652
<!-- End: -->
Loggerhead is a web-based interface for Breezy
Version: 2.0.2.dev0