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