/mandos/trunk

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

  • Committer: Teddy Hogeborn
  • Date: 2019-02-09 23:23:26 UTC
  • Revision ID: teddy@recompile.se-20190209232326-z1z2kzpgfixz7iaj
Add support for using raw public keys in TLS (RFC 7250)

Since GnuTLS removed support for OpenPGP keys in TLS (RFC 6091), and
no other library supports it, we have to change the protocol to use
something else.  We choose to use "raw public keys" (RFC 7250).  Since
we still use OpenPGP keys to decrypt the secret password, this means
that each client will have two keys: One OpenPGP key and one TLS
public/private key, and the key ID of the latter key is used to
identify clients instead of the fingerprint of the OpenPGP key.

Note that this code is still compatible with GnuTLS before version
3.6.0 (when OpenPGP key support was removed).  This commit merely adds
support for using raw pulic keys instead with GnuTLS 3.6.6. or later.

* DBUS-API (Signals/ClientNotFound): Change name of first parameter
                                     from "Fingerprint" to "KeyID".
  (Mandos Client Interface/Properties/KeyID): New.
* INSTALL: Document conflict with GnuTLS 3.6.0 (which removed OpenPGP
           key support) up until 3.6.6, when support for raw public
           keys was added.  Also document new dependency of client on
           "gnutls-bin" package (for certtool).
* Makefile (run-client): Depend on TLS key files, and also pass them
                         as arguments to client.
  (keydir/tls-privkey.pem, keydir/tls-pubkey.pem): New.
  (confdir/clients.conf): Add dependency on TLS public key.
  (purge-client): Add removal of TLS key files.
* clients.conf ([foo]/key_id, [bar]/key_id): New.
* debian/control (Source: mandos/Build-Depends): Also allow
                                                 libgnutls30 (>= 3.6.6)
  (Package: mandos/Depends): - '' -
  (Package: mandos/Description): Alter description to match new
                                 design.
  (Package: mandos-client/Description): - '' -
  (Package: mandos-client/Depends): Move "gnutls-bin | openssl" to
                                    here from "Recommends".
* debian/mandos-client.README.Debian: Add --tls-privkey and
                                      --tls-pubkey options to test
                                      command.
* debian/mandos-client.postinst (create_key): Renamed to "create_keys"
                                             (all callers changed),
                                             and also create TLS key.
* debian/mandos-client.postrm (purge): Also remove TLS key files.
* intro.xml (DESCRIPTION): Describe new dual-key design.
* mandos (GnuTLS): Define different functions depending on whether
                   support for raw public keys is detected.
  (Client.key_id): New attribute.
  (ClientDBus.KeyID_dbus_property): New method.
  (ProxyClient.__init__): Take new "key_id" parameter.
  (ClientHandler.handle): Use key IDs when using raw public keys and
                          use fingerprints when using OpenPGP keys.
  (ClientHandler.peer_certificate): Also handle raw public keys.
  (ClientHandler.key_id): New.
  (MandosServer.handle_ipc): Pass key ID over the pipe IPC.  Also
                             check for key ID matches when looking up
                             clients.
  (main): Default GnuTLS priority string depends on whether we are
          using raw public keys or not.  When unpickling clients, set
          key_id if not set in the pickle.
  (main/MandosDBusService.ClientNotFound): Change name of first
                                           parameter from
                                           "Fingerprint" to "KeyID".
* mandos-clients.conf.xml (OPTIONS): Document new "key_id" option.
  (OPTIONS/secret): Mention new key ID matchning.
  (EXPANSION/RUNTIME EXPANSION): Add new "key_id" option.
  (EXAMPLE): - '' -
* mandos-ctl (tablewords, main/keywords): Add new "KeyID" property.
* mandos-keygen: Create TLS key files.  New "--tls-keytype" (-T)
                 option.  Alter help text to be more clear about key
                 types.  When in password mode, also output "key_id"
                 option.
* mandos-keygen.xml (SYNOPSIS): Add new "--tls-keytype" (-T) option.
  (DESCRIPTION): Alter to match new dual-key design.
  (OVERVIEW): - '' -
  (FILES): Add TLS key files.
* mandos-options.xml (priority): Document new default priority string
                                 when using raw public keys.
* mandos.xml (NETWORK PROTOCOL): Describe new protocol using key ID.
  (BUGS): Remove issue about checking expire times of OpenPGP keys,
          since TLS public keys do not have expiration times.
  (SECURITY/CLIENT): Alter description to match new design.
  (SEE ALSO/GnuTLS): - '' -
  (SEE ALSO): Add reference to RFC 7250, and alter description of when
              RFC 6091 is used.
* overview.xml: Alter text to match new design.
* plugin-runner.xml (EXAMPLE): Add --tls-pubkey and --tls-privkey
                               options to mandos-client options.
* plugins.d/mandos-client.c: Use raw public keys when compiling with
                             supporting GnuTLS versions. Add new
                             "--tls-pubkey" and "--tls-privkey"
                             options (which do nothing if GnuTLS
                             library does not support raw public
                             keys).  Alter text throughout to reflect
                             new design.  Only generate new DH
                             parameters (based on size of OpenPGP key)
                             when using OpenPGP in TLS.  Default
                             GnuTLS priority string depends on whether
                             we are using raw public keys or not.
* plugins.d/mandos-client.xml (SYNOPSIS): Add new "--tls-privkey" (-t)
                                          and "--tls-pubkey" (-T)
                                          options.
  (DESCRIPTION): Describe new dual-key design.
  (OPTIONS): Document new "--tls-privkey" (-t) and "--tls-pubkey" (-T)
             options.
  (OPTIONS/--dh-bits): No longer necessarily depends on OpenPGP key
                       size.
  (FILES): Add default locations for TLS public and private key files.
  (EXAMPLE): Use new --tls-pubkey and --tls-privkey options.
  (SECURITY): Alter wording slightly to reflect new dual-key design.
  (SEE ALSO/GnuTLS): Alter description to match new design.
  (SEE ALSO): Add reference to RFC 7250, and alter description of when
              RFC 6091 is used.

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
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">
 
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
      <holder>Teddy Hogeborn</holder>
 
44
      <holder>Björn Påhlsson</holder>
 
45
    </copyright>
 
46
    <xi:include href="legalnotice.xml"/>
 
47
  </refentryinfo>
 
48
  
 
49
  <refmeta>
 
50
    <refentrytitle>&COMMANDNAME;</refentrytitle>
 
51
    <manvolnum>8</manvolnum>
 
52
  </refmeta>
 
53
  
 
54
  <refnamediv>
 
55
    <refname><command>&COMMANDNAME;</command></refname>
 
56
    <refpurpose>
 
57
      Control or query the operation of the Mandos server
 
58
    </refpurpose>
 
59
  </refnamediv>
 
60
  
 
61
  <refsynopsisdiv>
 
62
    <cmdsynopsis>
 
63
      <command>&COMMANDNAME;</command>
 
64
      <group choice="req">
 
65
        <group>
 
66
          <arg choice="plain"><option>--enable</option></arg>
 
67
          <arg choice="plain"><option>-e</option></arg>
 
68
          <sbr/>
 
69
          <arg choice="plain"><option>--disable</option></arg>
 
70
          <arg choice="plain"><option>-d</option></arg>
 
71
        </group>
 
72
        <sbr/>
 
73
        <group>
 
74
          <arg choice="plain"><option>--bump-timeout</option></arg>
 
75
          <arg choice="plain"><option>-b</option></arg>
 
76
        </group>
 
77
        <sbr/>
 
78
        <group>
 
79
          <arg choice="plain"><option>--start-checker</option></arg>
 
80
        </group>
 
81
        <sbr/>
 
82
        <group>
 
83
          <arg choice="plain"><option>--stop-checker</option></arg>
 
84
        </group>
 
85
        <sbr/>
 
86
        <group>
 
87
          <arg choice="plain"><option>--remove</option></arg>
 
88
          <arg choice="plain"><option>-r</option></arg>
 
89
        </group>
 
90
        <sbr/>
 
91
        <group>
 
92
          <arg choice="plain"><option>--checker
 
93
          <replaceable>COMMAND</replaceable></option></arg>
 
94
          <arg choice="plain"><option>-c
 
95
          <replaceable>COMMAND</replaceable></option></arg>
 
96
        </group>
 
97
        <sbr/>
 
98
        <group>
 
99
          <arg choice="plain"><option>--timeout
 
100
          <replaceable>TIME</replaceable></option></arg>
 
101
          <arg choice="plain"><option>-t
 
102
          <replaceable>TIME</replaceable></option></arg>
 
103
        </group>
 
104
        <sbr/>
 
105
        <group>
 
106
          <arg choice="plain"><option>--extended-timeout
 
107
          <replaceable>TIME</replaceable></option></arg>
 
108
        </group>
 
109
        <sbr/>
 
110
        <group>
 
111
          <arg choice="plain"><option>--interval
 
112
          <replaceable>TIME</replaceable></option></arg>
 
113
          <arg choice="plain"><option>-i
 
114
          <replaceable>TIME</replaceable></option></arg>
 
115
        </group>
 
116
        <sbr/>
 
117
        <group>
 
118
          <arg choice="plain"><option>--approve-by-default</option
 
119
          ></arg>
 
120
          <sbr/>
 
121
          <arg choice="plain"><option>--deny-by-default</option></arg>
 
122
        </group>
 
123
        <sbr/>
 
124
        <group>
 
125
          <arg choice="plain"><option>--approval-delay
 
126
          <replaceable>TIME</replaceable></option></arg>
 
127
        </group>
 
128
        <sbr/>
 
129
        <group>
 
130
          <arg choice="plain"><option>--approval-duration
 
131
          <replaceable>TIME</replaceable></option></arg>
 
132
        </group>
 
133
        <sbr/>
 
134
        <group>
 
135
          <arg choice="plain"><option>--interval
 
136
          <replaceable>TIME</replaceable></option></arg>
 
137
          <arg choice="plain"><option>-i
 
138
          <replaceable>TIME</replaceable></option></arg>
 
139
        </group>
 
140
        <sbr/>
 
141
        <group>
 
142
          <arg choice="plain"><option>--host
 
143
          <replaceable>STRING</replaceable></option></arg>
 
144
          <arg choice="plain"><option>-H
 
145
          <replaceable>STRING</replaceable></option></arg>
 
146
        </group>
 
147
        <sbr/>
 
148
        <group>
 
149
          <arg choice="plain"><option>--secret
 
150
          <replaceable>FILENAME</replaceable></option></arg>
 
151
          <arg choice="plain"><option>-s
 
152
          <replaceable>FILENAME</replaceable></option></arg>
 
153
        </group>
 
154
        <sbr/>
 
155
        <group>
 
156
          <arg choice="plain"><option>--approve</option></arg>
 
157
          <arg choice="plain"><option>-A</option></arg>
 
158
          <sbr/>
 
159
          <arg choice="plain"><option>--deny</option></arg>
 
160
          <arg choice="plain"><option>-D</option></arg>
 
161
        </group>
 
162
      </group>
 
163
      <sbr/>
 
164
      <group choice="req">
 
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>
 
169
        </arg>
 
170
      </group>
 
171
    </cmdsynopsis>
 
172
    <cmdsynopsis>
 
173
      <command>&COMMANDNAME;</command>
 
174
      <group>
 
175
          <arg choice="plain"><option>--verbose</option></arg>
 
176
          <arg choice="plain"><option>-v</option></arg>
 
177
          <sbr/>
 
178
          <arg choice="plain"><option>--dump-json</option></arg>
 
179
          <arg choice="plain"><option>-j</option></arg>
 
180
      </group>
 
181
      <group>
 
182
        <arg rep='repeat' choice='plain'>
 
183
          <replaceable>CLIENT</replaceable>
 
184
        </arg>
 
185
      </group>
 
186
    </cmdsynopsis>
 
187
    <cmdsynopsis>
 
188
      <command>&COMMANDNAME;</command>
 
189
      <group choice="req">
 
190
        <arg choice="plain"><option>--is-enabled</option></arg>
 
191
        <arg choice="plain"><option>-V</option></arg>
 
192
      </group>
 
193
      <arg choice='plain'><replaceable>CLIENT</replaceable></arg>
 
194
    </cmdsynopsis>
 
195
    <cmdsynopsis>
 
196
      <command>&COMMANDNAME;</command>
 
197
      <group choice="req">
 
198
        <arg choice="plain"><option>--help</option></arg>
 
199
        <arg choice="plain"><option>-h</option></arg>
 
200
      </group>
 
201
    </cmdsynopsis>
 
202
    <cmdsynopsis>
 
203
      <command>&COMMANDNAME;</command>
 
204
      <group choice="req">
 
205
        <arg choice="plain"><option>--version</option></arg>
 
206
        <arg choice="plain"><option>-v</option></arg>
 
207
      </group>
 
208
    </cmdsynopsis>
 
209
    <cmdsynopsis>
 
210
      <command>&COMMANDNAME;</command>
 
211
      <arg choice="plain"><option>--check</option></arg>
 
212
    </cmdsynopsis>
 
213
  </refsynopsisdiv>
 
214
  
 
215
  <refsect1 id="description">
 
216
    <title>DESCRIPTION</title>
 
217
    <para>
 
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>.
 
222
    </para>
 
223
    <para>
 
224
      This program can be used to change client settings, approve or
 
225
      deny client requests, and to remove clients from the server.
 
226
    </para>
 
227
  </refsect1>
 
228
  
 
229
  <refsect1 id="purpose">
 
230
    <title>PURPOSE</title>
 
231
    <para>
 
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.
 
236
    </para>
 
237
  </refsect1>
 
238
  
 
239
  <refsect1 id="options">
 
240
    <title>OPTIONS</title>
 
241
    
 
242
    <variablelist>
 
243
      <varlistentry>
 
244
        <term><option>--help</option></term>
 
245
        <term><option>-h</option></term>
 
246
        <listitem>
 
247
          <para>
 
248
            Show a help message and exit
 
249
          </para>
 
250
        </listitem>
 
251
      </varlistentry>
 
252
      
 
253
      <varlistentry>
 
254
        <term><option>--enable</option></term>
 
255
        <term><option>-e</option></term>
 
256
        <listitem>
 
257
          <para>
 
258
            Enable client(s).  An enabled client will be eligble to
 
259
            receive its secret.
 
260
          </para>
 
261
        </listitem>
 
262
      </varlistentry>
 
263
      
 
264
      <varlistentry>
 
265
        <term><option>--disable</option></term>
 
266
        <term><option>-d</option></term>
 
267
        <listitem>
 
268
          <para>
 
269
            Disable client(s).  A disabled client will not be eligble
 
270
            to receive its secret, and no checkers will be started for
 
271
            it.
 
272
          </para>
 
273
        </listitem>
 
274
      </varlistentry>
 
275
      
 
276
      <varlistentry>
 
277
        <term><option>--bump-timeout</option></term>
 
278
        <listitem>
 
279
          <para>
 
280
            Bump the timeout of the specified client(s), just as if a
 
281
            checker had completed successfully for it/them.
 
282
          </para>
 
283
        </listitem>
 
284
      </varlistentry>
 
285
      
 
286
      <varlistentry>
 
287
        <term><option>--start-checker</option></term>
 
288
        <listitem>
 
289
          <para>
 
290
            Start a new checker now for the specified client(s).
 
291
          </para>
 
292
        </listitem>
 
293
      </varlistentry>
 
294
      
 
295
      <varlistentry>
 
296
        <term><option>--stop-checker</option></term>
 
297
        <listitem>
 
298
          <para>
 
299
            Stop any running checker for the specified client(s).
 
300
          </para>
 
301
        </listitem>
 
302
      </varlistentry>
 
303
      
 
304
      <varlistentry>
 
305
        <term><option>--remove</option></term>
 
306
        <term><option>-r</option></term>
 
307
        <listitem>
 
308
          <para>
 
309
            Remove the specified client(s) from the server.
 
310
          </para>
 
311
        </listitem>
 
312
      </varlistentry>
 
313
      
 
314
      <varlistentry>
 
315
        <term><option>--checker
 
316
        <replaceable>COMMAND</replaceable></option></term>
 
317
        <term><option>-c
 
318
        <replaceable>COMMAND</replaceable></option></term>
 
319
        <listitem>
 
320
          <para>
 
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>.
 
325
          </para>
 
326
        </listitem>
 
327
      </varlistentry>
 
328
      
 
329
      <varlistentry>
 
330
        <term><option>--timeout
 
331
        <replaceable>TIME</replaceable></option></term>
 
332
        <term><option>-t
 
333
        <replaceable>TIME</replaceable></option></term>
 
334
        <listitem>
 
335
          <para>
 
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>.
 
340
          </para>
 
341
        </listitem>
 
342
      </varlistentry>
 
343
 
 
344
      <varlistentry>
 
345
        <term><option>--extended-timeout
 
346
        <replaceable>TIME</replaceable></option></term>
 
347
        <listitem>
 
348
          <para>
 
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>.
 
353
          </para>
 
354
        </listitem>
 
355
      </varlistentry>
 
356
      
 
357
      <varlistentry>
 
358
        <term><option>--interval
 
359
        <replaceable>TIME</replaceable></option></term>
 
360
        <term><option>-i
 
361
        <replaceable>TIME</replaceable></option></term>
 
362
        <listitem>
 
363
          <para>
 
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>.
 
368
          </para>
 
369
        </listitem>
 
370
      </varlistentry>
 
371
      
 
372
      <varlistentry>
 
373
        <term><option>--approve-by-default</option></term>
 
374
        <term><option>--deny-by-default</option></term>
 
375
        <listitem>
 
376
          <para>
 
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>.
 
383
          </para>
 
384
        </listitem>
 
385
      </varlistentry>
 
386
      
 
387
      <varlistentry>
 
388
        <term><option>--approval-delay
 
389
        <replaceable>TIME</replaceable></option></term>
 
390
        <listitem>
 
391
          <para>
 
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>.
 
396
          </para>
 
397
        </listitem>
 
398
      </varlistentry>
 
399
      
 
400
      <varlistentry>
 
401
        <term><option>--approval-duration
 
402
        <replaceable>TIME</replaceable></option></term>
 
403
        <listitem>
 
404
          <para>
 
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>.
 
409
          </para>
 
410
        </listitem>
 
411
      </varlistentry>
 
412
      
 
413
      <varlistentry>
 
414
        <term><option>--host
 
415
        <replaceable>STRING</replaceable></option></term>
 
416
        <term><option>-H
 
417
        <replaceable>STRING</replaceable></option></term>
 
418
        <listitem>
 
419
          <para>
 
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>.
 
424
          </para>
 
425
        </listitem>
 
426
      </varlistentry>
 
427
      
 
428
      <varlistentry>
 
429
        <term><option>--secret
 
430
        <replaceable>FILENAME</replaceable></option></term>
 
431
        <term><option>-s
 
432
        <replaceable>FILENAME</replaceable></option></term>
 
433
        <listitem>
 
434
          <para>
 
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>.
 
439
          </para>
 
440
        </listitem>
 
441
      </varlistentry>
 
442
      
 
443
      <varlistentry>
 
444
        <term><option>--approve</option></term>
 
445
        <term><option>-A</option></term>
 
446
        <listitem>
 
447
          <para>
 
448
            Approve client(s) if currently waiting for approval.
 
449
          </para>
 
450
        </listitem>
 
451
      </varlistentry>
 
452
      
 
453
      <varlistentry>
 
454
        <term><option>--deny</option></term>
 
455
        <term><option>-D</option></term>
 
456
        <listitem>
 
457
          <para>
 
458
            Deny client(s) if currently waiting for approval.
 
459
          </para>
 
460
        </listitem>
 
461
      </varlistentry>
 
462
      
 
463
      <varlistentry>
 
464
        <term><option>--all</option></term>
 
465
        <term><option>-a</option></term>
 
466
        <listitem>
 
467
          <para>
 
468
            Make the client-modifying options modify <emphasis
 
469
            >all</emphasis> clients.
 
470
          </para>
 
471
        </listitem>
 
472
      </varlistentry>
 
473
      
 
474
      <varlistentry>
 
475
        <term><option>--verbose</option></term>
 
476
        <term><option>-v</option></term>
 
477
        <listitem>
 
478
          <para>
 
479
            Show all client settings, not just a subset.
 
480
          </para>
 
481
        </listitem>
 
482
      </varlistentry>
 
483
      
 
484
      <varlistentry>
 
485
        <term><option>--dump-json</option></term>
 
486
        <term><option>-j</option></term>
 
487
        <listitem>
 
488
          <para>
 
489
            Dump client settings as JSON to standard output.
 
490
          </para>
 
491
        </listitem>
 
492
      </varlistentry>
 
493
      
 
494
      <varlistentry>
 
495
        <term><option>--is-enabled</option></term>
 
496
        <term><option>-V</option></term>
 
497
        <listitem>
 
498
          <para>
 
499
            Check if a single client is enabled or not, and exit with
 
500
            a successful exit status only if the client is enabled.
 
501
          </para>
 
502
        </listitem>
 
503
      </varlistentry>
 
504
      
 
505
      <varlistentry>
 
506
        <term><option>--check</option></term>
 
507
        <listitem>
 
508
          <para>
 
509
            Run self-tests.  This includes any unit tests, etc.
 
510
          </para>
 
511
        </listitem>
 
512
      </varlistentry>
 
513
      
 
514
    </variablelist>
 
515
  </refsect1>
 
516
  
 
517
  <refsect1 id="overview">
 
518
    <title>OVERVIEW</title>
 
519
    <xi:include href="overview.xml"/>
 
520
    <para>
 
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.
 
524
    </para>
 
525
  </refsect1>
 
526
  
 
527
  <refsect1 id="exit_status">
 
528
    <title>EXIT STATUS</title>
 
529
    <para>
 
530
      If the <option>--is-enabled</option> option is used, the exit
 
531
      status will be 0 only if the specified client is enabled.
 
532
    </para>
 
533
  </refsect1>
 
534
  
 
535
  <refsect1 id="bugs">
 
536
    <title>BUGS</title>
 
537
    <xi:include href="bugs.xml"/>
 
538
  </refsect1>
 
539
  
 
540
  <refsect1 id="example">
 
541
    <title>EXAMPLE</title>
 
542
    <informalexample>
 
543
      <para>
 
544
        To list all clients:
 
545
      </para>
 
546
      <para>
 
547
        <userinput>&COMMANDNAME;</userinput>
 
548
      </para>
 
549
    </informalexample>
 
550
    
 
551
    <informalexample>
 
552
      <para>
 
553
        To list <emphasis>all</emphasis> settings for the clients
 
554
        named <quote>foo1.example.org</quote> and <quote
 
555
        >foo2.example.org</quote>:
 
556
      </para>
 
557
      <para>
 
558
 
 
559
<!-- do not wrap this line -->
 
560
<userinput>&COMMANDNAME; --verbose foo1.example.org foo2.example.org</userinput>
 
561
 
 
562
      </para>
 
563
    </informalexample>
 
564
    
 
565
    <informalexample>
 
566
      <para>
 
567
        To enable all clients:
 
568
      </para>
 
569
      <para>
 
570
        <userinput>&COMMANDNAME; --enable --all</userinput>
 
571
      </para>
 
572
    </informalexample>
 
573
    
 
574
    <informalexample>
 
575
      <para>
 
576
        To change timeout and interval value 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; --timeout="5m" --interval="1m" foo1.example.org foo2.example.org</userinput>
 
584
 
 
585
      </para>
 
586
    </informalexample>
 
587
    
 
588
    <informalexample>
 
589
      <para>
 
590
        To approve all clients currently waiting for it:
 
591
      </para>
 
592
      <para>
 
593
        <userinput>&COMMANDNAME; --approve --all</userinput>
 
594
      </para>
 
595
    </informalexample>
 
596
  </refsect1>
 
597
  
 
598
  <refsect1 id="security">
 
599
    <title>SECURITY</title>
 
600
    <para>
 
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.
 
604
    </para>
 
605
  </refsect1>
 
606
  
 
607
  <refsect1 id="see_also">
 
608
    <title>SEE ALSO</title>
 
609
    <para>
 
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>
 
618
    </para>
 
619
  </refsect1>
 
620
  
 
621
</refentry>
 
622
<!-- Local Variables: -->
 
623
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
 
624
<!-- time-stamp-end: "[\"']>" -->
 
625
<!-- time-stamp-format: "%:y-%02m-%02d" -->
 
626
<!-- End: -->