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