/mandos/release

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

  • Committer: Teddy Hogeborn
  • Date: 2008-08-16 03:29:08 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080816032908-ihw7c05r2mnyk389
Add feature to specify custom environment variables for plugins.

* plugin-runner.c (plugin): New members "environ" and "envc" to
                            contain possible custom environment.
  (getplugin): Return NULL on failure instead of doing exit(); all
               callers changed.
  (add_to_char_array): New helper function for "add_argument" and
                       "add_environment".
  (addargument): Renamed to "add_argument".  Return bool.  Call
                 "add_to_char_array" to actually do things.
  (add_environment): New; analogous to "add_argument".
  (addcustomargument): Renamed to "add_to_argv" to avoid confusion
                       with "add_argument".
  (main): New options "--global-envs" and "--envs-for" to specify
          custom environment for plugins.  Print environment for
          plugins in debug mode.  Use asprintf instead of strcpy and
          strcat.  Use execve() for plugins with custom environments.
          Free environment for plugin when freeing plugin list.

Show diffs side-by-side

added added

removed removed

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