/mandos/trunk

To get this branch, use:
bzr branch http://bzr.recompile.se/loggerhead/mandos/trunk
129 by Teddy Hogeborn
* mandos-clients.conf.xml: Changed all single quotes to double quotes
1
<?xml version="1.0" encoding="UTF-8"?>
24.1.23 by Björn Påhlsson
Added manual pages for:
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3
	"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
74 by Teddy Hogeborn
* Makefile (PREFIX, CONFDIR): New.
4
<!ENTITY COMMANDNAME "plugin-runner">
807 by Teddy Hogeborn
Update copyright year.
5
<!ENTITY TIMESTAMP "2016-02-28">
217 by Teddy Hogeborn
* .bzrignore: Added "man" directory (created by "make install-html").
6
<!ENTITY % common SYSTEM "common.ent">
7
%common;
24.1.23 by Björn Påhlsson
Added manual pages for:
8
]>
9
131 by Teddy Hogeborn
* Makefile: Make all DocBook rules include legalnotice.xml as a
10
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
24.1.23 by Björn Påhlsson
Added manual pages for:
11
  <refentryinfo>
112 by Teddy Hogeborn
* mandos-clients.conf.xml (/refentry/refentryinfo/title): Changed to
12
    <title>Mandos Manual</title>
129 by Teddy Hogeborn
* mandos-clients.conf.xml: Changed all single quotes to double quotes
13
    <!-- Nwalsh’s docbook scripts use this to generate the footer: -->
112 by Teddy Hogeborn
* mandos-clients.conf.xml (/refentry/refentryinfo/title): Changed to
14
    <productname>Mandos</productname>
217 by Teddy Hogeborn
* .bzrignore: Added "man" directory (created by "make install-html").
15
    <productnumber>&version;</productnumber>
111 by Teddy Hogeborn
* mandos-clients.conf.xml (ENTITY TIMESTAMP): New. Automatically
16
    <date>&TIMESTAMP;</date>
24.1.23 by Björn Påhlsson
Added manual pages for:
17
    <authorgroup>
18
      <author>
19
	<firstname>Björn</firstname>
20
	<surname>Påhlsson</surname>
21
	<address>
505.1.2 by Teddy Hogeborn
Change "fukt.bsnet.se" to "recompile.se" throughout.
22
	  <email>belorn@recompile.se</email>
24.1.23 by Björn Påhlsson
Added manual pages for:
23
	</address>
24
      </author>
25
      <author>
26
	<firstname>Teddy</firstname>
27
	<surname>Hogeborn</surname>
28
	<address>
505.1.2 by Teddy Hogeborn
Change "fukt.bsnet.se" to "recompile.se" throughout.
29
	  <email>teddy@recompile.se</email>
24.1.23 by Björn Påhlsson
Added manual pages for:
30
	</address>
31
      </author>
32
    </authorgroup>
33
    <copyright>
34
      <year>2008</year>
246 by Teddy Hogeborn
* README: Update copyright year; add "2009".
35
      <year>2009</year>
778 by Teddy Hogeborn
Update copyright year.
36
      <year>2010</year>
37
      <year>2011</year>
544 by Teddy Hogeborn
Updated year in copyright notices.
38
      <year>2012</year>
778 by Teddy Hogeborn
Update copyright year.
39
      <year>2013</year>
40
      <year>2014</year>
41
      <year>2015</year>
807 by Teddy Hogeborn
Update copyright year.
42
      <year>2016</year>
128 by Teddy Hogeborn
* plugin-runner.xml (/refentry/refentryinfo/copyright): Split
43
      <holder>Teddy Hogeborn</holder>
44
      <holder>Björn Påhlsson</holder>
24.1.23 by Björn Påhlsson
Added manual pages for:
45
    </copyright>
131 by Teddy Hogeborn
* Makefile: Make all DocBook rules include legalnotice.xml as a
46
    <xi:include href="legalnotice.xml"/>
24.1.23 by Björn Påhlsson
Added manual pages for:
47
  </refentryinfo>
182 by Teddy Hogeborn
* Makefile (install): Use "install-client-nokey".
48
  
24.1.23 by Björn Påhlsson
Added manual pages for:
49
  <refmeta>
50
    <refentrytitle>&COMMANDNAME;</refentrytitle>
51
    <manvolnum>8mandos</manvolnum>
52
  </refmeta>
53
  
54
  <refnamediv>
55
    <refname><command>&COMMANDNAME;</command></refname>
56
    <refpurpose>
156 by Teddy Hogeborn
* mandos-clients.conf.xml (OPTIONS): Improved spelling.
57
      Run Mandos plugins, pass data from first to succeed.
24.1.23 by Björn Påhlsson
Added manual pages for:
58
    </refpurpose>
59
  </refnamediv>
182 by Teddy Hogeborn
* Makefile (install): Use "install-client-nokey".
60
  
24.1.23 by Björn Påhlsson
Added manual pages for:
61
  <refsynopsisdiv>
62
    <cmdsynopsis>
63
      <command>&COMMANDNAME;</command>
121 by Teddy Hogeborn
* plugin-runner.xml (NAME): Improved wording.
64
      <group rep="repeat">
135 by Teddy Hogeborn
* plugin-runner.c (add_environment): Never insert existing environment
65
	<arg choice="plain"><option>--global-env=<replaceable
187 by Teddy Hogeborn
* debian/mandos-client.README.Debian: Document "eth0" default and how
66
	>ENV</replaceable><literal>=</literal><replaceable
121 by Teddy Hogeborn
* plugin-runner.xml (NAME): Improved wording.
67
	>value</replaceable></option></arg>
139 by Teddy Hogeborn
* plugin-runner.xml: Changed short option for "--global-env" to "-G",
68
	<arg choice="plain"><option>-G
187 by Teddy Hogeborn
* debian/mandos-client.README.Debian: Document "eth0" default and how
69
	<replaceable>ENV</replaceable><literal>=</literal><replaceable
121 by Teddy Hogeborn
* plugin-runner.xml (NAME): Improved wording.
70
	>value</replaceable> </option></arg>
71
      </group>
72
      <sbr/>
73
      <group rep="repeat">
135 by Teddy Hogeborn
* plugin-runner.c (add_environment): Never insert existing environment
74
	<arg choice="plain"><option>--env-for=<replaceable
121 by Teddy Hogeborn
* plugin-runner.xml (NAME): Improved wording.
75
	>PLUGIN</replaceable><literal>:</literal><replaceable
76
	>ENV</replaceable><literal>=</literal><replaceable
77
	>value</replaceable></option></arg>
139 by Teddy Hogeborn
* plugin-runner.xml: Changed short option for "--global-env" to "-G",
78
	<arg choice="plain"><option>-E<replaceable>
121 by Teddy Hogeborn
* plugin-runner.xml (NAME): Improved wording.
79
	PLUGIN</replaceable><literal>:</literal><replaceable
80
	>ENV</replaceable><literal>=</literal><replaceable
81
	>value</replaceable> </option></arg>
82
      </group>
83
      <sbr/>
84
      <group rep="repeat">
85
	<arg choice="plain"><option>--global-options=<replaceable
86
	>OPTIONS</replaceable></option></arg>
87
	<arg choice="plain"><option>-g<replaceable>
88
	OPTIONS</replaceable> </option></arg>
89
      </group>
90
      <sbr/>
91
      <group rep="repeat">
92
	<arg choice="plain"><option>--options-for=<replaceable
93
	>PLUGIN</replaceable><literal>:</literal><replaceable
94
	>OPTIONS</replaceable></option></arg>
139 by Teddy Hogeborn
* plugin-runner.xml: Changed short option for "--global-env" to "-G",
95
	<arg choice="plain"><option>-o<replaceable>
121 by Teddy Hogeborn
* plugin-runner.xml (NAME): Improved wording.
96
	PLUGIN</replaceable><literal>:</literal><replaceable
97
	>OPTIONS</replaceable> </option></arg>
98
      </group>
99
      <sbr/>
100
      <group rep="repeat">
101
	<arg choice="plain"><option>--disable=<replaceable
102
	>PLUGIN</replaceable></option></arg>
103
	<arg choice="plain"><option>-d
104
	<replaceable>PLUGIN</replaceable> </option></arg>
105
      </group>
106
      <sbr/>
139 by Teddy Hogeborn
* plugin-runner.xml: Changed short option for "--global-env" to "-G",
107
      <group rep="repeat">
108
	<arg choice="plain"><option>--enable=<replaceable
109
	>PLUGIN</replaceable></option></arg>
110
	<arg choice="plain"><option>-e
111
	<replaceable>PLUGIN</replaceable> </option></arg>
112
      </group>
113
      <sbr/>
121 by Teddy Hogeborn
* plugin-runner.xml (NAME): Improved wording.
114
      <arg><option>--groupid=<replaceable
115
      >ID</replaceable></option></arg>
116
      <sbr/>
117
      <arg><option>--userid=<replaceable
118
      >ID</replaceable></option></arg>
119
      <sbr/>
120
      <arg><option>--plugin-dir=<replaceable
121
      >DIRECTORY</replaceable></option></arg>
122
      <sbr/>
738.1.1 by Teddy Hogeborn
Add a plugin helper directory, available to all plugins.
123
      <arg><option>--plugin-helper-dir=<replaceable
124
      >DIRECTORY</replaceable></option></arg>
125
      <sbr/>
139 by Teddy Hogeborn
* plugin-runner.xml: Changed short option for "--global-env" to "-G",
126
      <arg><option>--config-file=<replaceable
127
      >FILE</replaceable></option></arg>
128
      <sbr/>
121 by Teddy Hogeborn
* plugin-runner.xml (NAME): Improved wording.
129
      <arg><option>--debug</option></arg>
130
    </cmdsynopsis>
131
    <cmdsynopsis>
132
      <command>&COMMANDNAME;</command>
133
      <group choice="req">
129 by Teddy Hogeborn
* mandos-clients.conf.xml: Changed all single quotes to double quotes
134
	<arg choice="plain"><option>--help</option></arg>
135
	<arg choice="plain"><option>-?</option></arg>
121 by Teddy Hogeborn
* plugin-runner.xml (NAME): Improved wording.
136
      </group>
137
    </cmdsynopsis>
138
    <cmdsynopsis>
139
      <command>&COMMANDNAME;</command>
129 by Teddy Hogeborn
* mandos-clients.conf.xml: Changed all single quotes to double quotes
140
      <arg choice="plain"><option>--usage</option></arg>
121 by Teddy Hogeborn
* plugin-runner.xml (NAME): Improved wording.
141
    </cmdsynopsis>
142
    <cmdsynopsis>
143
      <command>&COMMANDNAME;</command>
144
      <group choice="req">
129 by Teddy Hogeborn
* mandos-clients.conf.xml: Changed all single quotes to double quotes
145
	<arg choice="plain"><option>--version</option></arg>
146
	<arg choice="plain"><option>-V</option></arg>
121 by Teddy Hogeborn
* plugin-runner.xml (NAME): Improved wording.
147
      </group>
118 by Teddy Hogeborn
* mandos-keygen.xml (SYNOPSIS): Fixed tags. Unify short and long
148
    </cmdsynopsis>
24.1.23 by Björn Påhlsson
Added manual pages for:
149
  </refsynopsisdiv>
134 by Teddy Hogeborn
* mandos.xml: Enclose "RAM" with <acronym>.
150
  
24.1.23 by Björn Påhlsson
Added manual pages for:
151
  <refsect1 id="description">
152
    <title>DESCRIPTION</title>
153
    <para>
134 by Teddy Hogeborn
* mandos.xml: Enclose "RAM" with <acronym>.
154
      <command>&COMMANDNAME;</command> is a program which is meant to
155 by Teddy Hogeborn
* README: Improved wording.
155
      be specified as a <quote>keyscript</quote> for the root disk in
156
      <citerefentry><refentrytitle>crypttab</refentrytitle>
157
      <manvolnum>5</manvolnum></citerefentry>.  The aim of this
158
      program is therefore to output a password, which then
159
      <citerefentry><refentrytitle>cryptsetup</refentrytitle>
140 by Teddy Hogeborn
* plugin-runner.xml (PLUGINS/WRITING PLUGINS): New section.
160
      <manvolnum>8</manvolnum></citerefentry> will use to unlock the
161
      root disk.
134 by Teddy Hogeborn
* mandos.xml: Enclose "RAM" with <acronym>.
162
    </para>
163
    <para>
164
      This program is not meant to be invoked directly, but can be in
165
      order to test it.  Note that any password obtained will simply
166
      be output on standard output.
167
    </para>
168
  </refsect1>
169
  
170
  <refsect1 id="purpose">
171
    <title>PURPOSE</title>
172
    <para>
173
      The purpose of this is to enable <emphasis>remote and unattended
174
      rebooting</emphasis> of client host computer with an
175
      <emphasis>encrypted root file system</emphasis>.  See <xref
176
      linkend="overview"/> for details.
177
    </para>
178
  </refsect1>
179
  
24.1.38 by Björn Påhlsson
changed description to better fit role
180
  <refsect1>
181
    <title>OPTIONS</title>
24.1.23 by Björn Påhlsson
Added manual pages for:
182
    <variablelist>
183
      <varlistentry>
135 by Teddy Hogeborn
* plugin-runner.c (add_environment): Never insert existing environment
184
	<term><option>--global-env
187 by Teddy Hogeborn
* debian/mandos-client.README.Debian: Document "eth0" default and how
185
	<replaceable>ENV</replaceable><literal>=</literal><replaceable
135 by Teddy Hogeborn
* plugin-runner.c (add_environment): Never insert existing environment
186
	>value</replaceable></option></term>
140 by Teddy Hogeborn
* plugin-runner.xml (PLUGINS/WRITING PLUGINS): New section.
187
	<term><option>-G
187 by Teddy Hogeborn
* debian/mandos-client.README.Debian: Document "eth0" default and how
188
	<replaceable>ENV</replaceable><literal>=</literal><replaceable
135 by Teddy Hogeborn
* plugin-runner.c (add_environment): Never insert existing environment
189
	>value</replaceable></option></term>
190
	<listitem>
191
	  <para>
136 by Teddy Hogeborn
* plugin-runner.c (add_environment): Override existing environment
192
	    This option will add an environment variable setting to
193
	    all plugins.  This will override any inherited environment
194
	    variable.
135 by Teddy Hogeborn
* plugin-runner.c (add_environment): Never insert existing environment
195
	  </para>
196
	</listitem>
197
      </varlistentry>
198
      
199
      <varlistentry>
200
	<term><option>--env-for
201
	<replaceable>PLUGIN</replaceable><literal>:</literal
202
	><replaceable>ENV</replaceable><literal>=</literal
203
	><replaceable>value</replaceable></option></term>
140 by Teddy Hogeborn
* plugin-runner.xml (PLUGINS/WRITING PLUGINS): New section.
204
	<term><option>-E
135 by Teddy Hogeborn
* plugin-runner.c (add_environment): Never insert existing environment
205
	<replaceable>PLUGIN</replaceable><literal>:</literal
206
	><replaceable>ENV</replaceable><literal>=</literal
207
	><replaceable>value</replaceable></option></term>
208
	<listitem>
209
	  <para>
136 by Teddy Hogeborn
* plugin-runner.c (add_environment): Override existing environment
210
	    This option will add an environment variable setting to
211
	    the <replaceable>PLUGIN</replaceable> plugin.  This will
212
	    override any inherited environment variables or
213
	    environment variables specified using
214
	    <option>--global-env</option>.
135 by Teddy Hogeborn
* plugin-runner.c (add_environment): Never insert existing environment
215
	  </para>
216
	</listitem>
217
      </varlistentry>
218
      
219
      <varlistentry>
125 by Teddy Hogeborn
* plugin-runner.xml (OPTIONS): Use <option> tags instead of
220
	<term><option>--global-options
221
	<replaceable>OPTIONS</replaceable></option></term>
222
	<term><option>-g
223
	<replaceable>OPTIONS</replaceable></option></term>
24.1.23 by Björn Påhlsson
Added manual pages for:
224
	<listitem>
225
	  <para>
134 by Teddy Hogeborn
* mandos.xml: Enclose "RAM" with <acronym>.
226
	    Pass some options to <emphasis>all</emphasis> plugins.
227
	    <replaceable>OPTIONS</replaceable> is a comma separated
228
	    list of options.  This is not a very useful option, except
229
	    for specifying the <quote><option>--debug</option></quote>
140 by Teddy Hogeborn
* plugin-runner.xml (PLUGINS/WRITING PLUGINS): New section.
230
	    option to all plugins.
134 by Teddy Hogeborn
* mandos.xml: Enclose "RAM" with <acronym>.
231
	  </para>
24.1.23 by Björn Påhlsson
Added manual pages for:
232
	</listitem>
233
      </varlistentry>
134 by Teddy Hogeborn
* mandos.xml: Enclose "RAM" with <acronym>.
234
      
24.1.23 by Björn Påhlsson
Added manual pages for:
235
      <varlistentry>
125 by Teddy Hogeborn
* plugin-runner.xml (OPTIONS): Use <option> tags instead of
236
	<term><option>--options-for
237
	<replaceable>PLUGIN</replaceable><literal>:</literal
238
	><replaceable>OPTION</replaceable></option></term>
239
	<term><option>-o
240
	<replaceable>PLUGIN</replaceable><literal>:</literal
241
	><replaceable>OPTION</replaceable></option></term>
24.1.23 by Björn Påhlsson
Added manual pages for:
242
	<listitem>
243
	  <para>
134 by Teddy Hogeborn
* mandos.xml: Enclose "RAM" with <acronym>.
244
	    Pass some options to a specific plugin.  <replaceable
245
	    >PLUGIN</replaceable> is the name (file basename) of a
246
	    plugin, and <replaceable>OPTIONS</replaceable> is a comma
247
	    separated list of options.
248
	  </para>
249
	  <para>
250
	    Note that since options are not split on whitespace, the
251
	    way to pass, to the plugin
252
	    <quote><filename>foo</filename></quote>, the option
253
	    <option>--bar</option> with the option argument
254
	    <quote>baz</quote> is either
255
	    <userinput>--options-for=foo:--bar=baz</userinput> or
140 by Teddy Hogeborn
* plugin-runner.xml (PLUGINS/WRITING PLUGINS): New section.
256
	    <userinput>--options-for=foo:--bar,baz</userinput>.  Using
257
	    <userinput>--options-for="foo:--bar baz"</userinput>. will
258
	    <emphasis>not</emphasis> work.
134 by Teddy Hogeborn
* mandos.xml: Enclose "RAM" with <acronym>.
259
	  </para>
24.1.23 by Björn Påhlsson
Added manual pages for:
260
	</listitem>
118 by Teddy Hogeborn
* mandos-keygen.xml (SYNOPSIS): Fixed tags. Unify short and long
261
      </varlistentry>
182 by Teddy Hogeborn
* Makefile (install): Use "install-client-nokey".
262
      
24.1.23 by Björn Påhlsson
Added manual pages for:
263
      <varlistentry>
139 by Teddy Hogeborn
* plugin-runner.xml: Changed short option for "--global-env" to "-G",
264
	<term><option>--disable
125 by Teddy Hogeborn
* plugin-runner.xml (OPTIONS): Use <option> tags instead of
265
	<replaceable>PLUGIN</replaceable></option></term>
266
	<term><option>-d
267
	<replaceable>PLUGIN</replaceable></option></term>
24.1.23 by Björn Påhlsson
Added manual pages for:
268
	<listitem>
269
	  <para>
134 by Teddy Hogeborn
* mandos.xml: Enclose "RAM" with <acronym>.
270
	    Disable the plugin named
271
	    <replaceable>PLUGIN</replaceable>.  The plugin will not be
272
	    started.
505.1.4 by Teddy Hogeborn
Removed superflous white space.
273
	  </para>
24.1.23 by Björn Påhlsson
Added manual pages for:
274
	</listitem>
275
      </varlistentry>
182 by Teddy Hogeborn
* Makefile (install): Use "install-client-nokey".
276
      
24.1.23 by Björn Påhlsson
Added manual pages for:
277
      <varlistentry>
139 by Teddy Hogeborn
* plugin-runner.xml: Changed short option for "--global-env" to "-G",
278
	<term><option>--enable
279
	<replaceable>PLUGIN</replaceable></option></term>
280
	<term><option>-e
281
	<replaceable>PLUGIN</replaceable></option></term>
282
	<listitem>
283
	  <para>
284
	    Re-enable the plugin named
285
	    <replaceable>PLUGIN</replaceable>.  This is only useful to
286
	    undo a previous <option>--disable</option> option, maybe
156 by Teddy Hogeborn
* mandos-clients.conf.xml (OPTIONS): Improved spelling.
287
	    from the configuration file.
139 by Teddy Hogeborn
* plugin-runner.xml: Changed short option for "--global-env" to "-G",
288
	  </para>
289
	</listitem>
290
      </varlistentry>
182 by Teddy Hogeborn
* Makefile (install): Use "install-client-nokey".
291
      
139 by Teddy Hogeborn
* plugin-runner.xml: Changed short option for "--global-env" to "-G",
292
      <varlistentry>
125 by Teddy Hogeborn
* plugin-runner.xml (OPTIONS): Use <option> tags instead of
293
	<term><option>--groupid
294
	<replaceable>ID</replaceable></option></term>
24.1.23 by Björn Påhlsson
Added manual pages for:
295
	<listitem>
296
	  <para>
134 by Teddy Hogeborn
* mandos.xml: Enclose "RAM" with <acronym>.
297
	    Change to group ID <replaceable>ID</replaceable> on
298
	    startup.  The default is 65534.  All plugins will be
299
	    started using this group ID.  <emphasis>Note:</emphasis>
300
	    This must be a number, not a name.
24.1.23 by Björn Påhlsson
Added manual pages for:
301
	  </para>
302
	</listitem>
118 by Teddy Hogeborn
* mandos-keygen.xml (SYNOPSIS): Fixed tags. Unify short and long
303
      </varlistentry>
182 by Teddy Hogeborn
* Makefile (install): Use "install-client-nokey".
304
      
24.1.23 by Björn Påhlsson
Added manual pages for:
305
      <varlistentry>
125 by Teddy Hogeborn
* plugin-runner.xml (OPTIONS): Use <option> tags instead of
306
	<term><option>--userid
307
	<replaceable>ID</replaceable></option></term>
24.1.23 by Björn Påhlsson
Added manual pages for:
308
	<listitem>
309
	  <para>
134 by Teddy Hogeborn
* mandos.xml: Enclose "RAM" with <acronym>.
310
	    Change to user ID <replaceable>ID</replaceable> on
311
	    startup.  The default is 65534.  All plugins will be
312
	    started using this user ID.  <emphasis>Note:</emphasis>
313
	    This must be a number, not a name.
24.1.23 by Björn Påhlsson
Added manual pages for:
314
	  </para>
315
	</listitem>
118 by Teddy Hogeborn
* mandos-keygen.xml (SYNOPSIS): Fixed tags. Unify short and long
316
      </varlistentry>
182 by Teddy Hogeborn
* Makefile (install): Use "install-client-nokey".
317
      
24.1.23 by Björn Påhlsson
Added manual pages for:
318
      <varlistentry>
125 by Teddy Hogeborn
* plugin-runner.xml (OPTIONS): Use <option> tags instead of
319
	<term><option>--plugin-dir
320
	<replaceable>DIRECTORY</replaceable></option></term>
24.1.23 by Björn Påhlsson
Added manual pages for:
321
	<listitem>
322
	  <para>
134 by Teddy Hogeborn
* mandos.xml: Enclose "RAM" with <acronym>.
323
	    Specify a different plugin directory.  The default is
324
	    <filename>/lib/mandos/plugins.d</filename>, which will
325
	    exist in the initial <acronym>RAM</acronym> disk
326
	    environment.
24.1.23 by Björn Påhlsson
Added manual pages for:
327
	  </para>
328
	</listitem>
118 by Teddy Hogeborn
* mandos-keygen.xml (SYNOPSIS): Fixed tags. Unify short and long
329
      </varlistentry>
24.1.23 by Björn Påhlsson
Added manual pages for:
330
      
331
      <varlistentry>
738.1.1 by Teddy Hogeborn
Add a plugin helper directory, available to all plugins.
332
	<term><option>--plugin-helper-dir
333
	<replaceable>DIRECTORY</replaceable></option></term>
334
	<listitem>
335
	  <para>
336
	    Specify a different plugin helper directory.  The default
337
	    is <filename>/lib/mandos/plugin-helpers</filename>, which
338
	    will exist in the initial <acronym>RAM</acronym> disk
339
	    environment.  (This will simply be passed to all plugins
340
	    via the <envar>MANDOSPLUGINHELPERDIR</envar> environment
341
	    variable.  See <xref linkend="writing_plugins"/>)
342
	  </para>
343
	</listitem>
344
      </varlistentry>
345
      
346
      <varlistentry>
139 by Teddy Hogeborn
* plugin-runner.xml: Changed short option for "--global-env" to "-G",
347
	<term><option>--config-file
348
	<replaceable>FILE</replaceable></option></term>
349
	<listitem>
350
	  <para>
351
	    Specify a different file to read additional options from.
352
	    See <xref linkend="files"/>.  Other command line options
353
	    will override options specified in the file.
354
	  </para>
355
	</listitem>
356
      </varlistentry>
357
      
358
      <varlistentry>
125 by Teddy Hogeborn
* plugin-runner.xml (OPTIONS): Use <option> tags instead of
359
	<term><option>--debug</option></term>
24.1.23 by Björn Påhlsson
Added manual pages for:
360
	<listitem>
361
	  <para>
134 by Teddy Hogeborn
* mandos.xml: Enclose "RAM" with <acronym>.
362
	    Enable debug mode.  This will enable a lot of output to
363
	    standard error about what the program is doing.  The
364
	    program will still perform all other functions normally.
365
	    The default is to <emphasis>not</emphasis> run in debug
366
	    mode.
367
	  </para>
368
	  <para>
369
	    The plugins will <emphasis>not</emphasis> be affected by
370
	    this option.  Use
371
	    <userinput><option>--global-options=--debug</option></userinput>
372
	    if complete debugging eruption is desired.
24.1.23 by Björn Påhlsson
Added manual pages for:
373
	  </para>
374
	</listitem>
375
      </varlistentry>
376
      
377
      <varlistentry>
125 by Teddy Hogeborn
* plugin-runner.xml (OPTIONS): Use <option> tags instead of
378
	<term><option>--help</option></term>
379
	<term><option>-?</option></term>
24.1.23 by Björn Påhlsson
Added manual pages for:
380
	<listitem>
381
	  <para>
134 by Teddy Hogeborn
* mandos.xml: Enclose "RAM" with <acronym>.
382
	    Gives a help message about options and their meanings.
24.1.23 by Björn Påhlsson
Added manual pages for:
383
	  </para>
384
	</listitem>
385
      </varlistentry>
386
      
387
      <varlistentry>
125 by Teddy Hogeborn
* plugin-runner.xml (OPTIONS): Use <option> tags instead of
388
	<term><option>--usage</option></term>
24.1.23 by Björn Påhlsson
Added manual pages for:
389
	<listitem>
390
	  <para>
134 by Teddy Hogeborn
* mandos.xml: Enclose "RAM" with <acronym>.
391
	    Gives a short usage message.
24.1.23 by Björn Påhlsson
Added manual pages for:
392
	  </para>
393
	</listitem>
394
      </varlistentry>
182 by Teddy Hogeborn
* Makefile (install): Use "install-client-nokey".
395
      
24.1.23 by Björn Påhlsson
Added manual pages for:
396
      <varlistentry>
125 by Teddy Hogeborn
* plugin-runner.xml (OPTIONS): Use <option> tags instead of
397
	<term><option>--version</option></term>
398
	<term><option>-V</option></term>
24.1.23 by Björn Påhlsson
Added manual pages for:
399
	<listitem>
400
	  <para>
134 by Teddy Hogeborn
* mandos.xml: Enclose "RAM" with <acronym>.
401
	    Prints the program version.
24.1.23 by Björn Påhlsson
Added manual pages for:
402
	  </para>
403
	</listitem>
118 by Teddy Hogeborn
* mandos-keygen.xml (SYNOPSIS): Fixed tags. Unify short and long
404
      </varlistentry>
24.1.23 by Björn Påhlsson
Added manual pages for:
405
    </variablelist>
406
  </refsect1>
182 by Teddy Hogeborn
* Makefile (install): Use "install-client-nokey".
407
  
134 by Teddy Hogeborn
* mandos.xml: Enclose "RAM" with <acronym>.
408
  <refsect1 id="overview">
409
    <title>OVERVIEW</title>
410
    <xi:include href="overview.xml"/>
411
    <para>
412
      This program will run on the client side in the initial
413
      <acronym>RAM</acronym> disk environment, and is responsible for
414
      getting a password.  It does this by running plugins, one of
415
      which will normally be the actual client program communicating
416
      with the server.
417
    </para>
418
  </refsect1>
419
  <refsect1 id="plugins">
420
    <title>PLUGINS</title>
421
    <para>
422
      This program will get a password by running a number of
423
      <firstterm>plugins</firstterm>, which are simply executable
424
      programs in a directory in the initial <acronym>RAM</acronym>
425
      disk environment.  The default directory is
426
      <filename>/lib/mandos/plugins.d</filename>, but this can be
427
      changed with the <option>--plugin-dir</option> option.  The
428
      plugins are started in parallel, and the first plugin to output
135 by Teddy Hogeborn
* plugin-runner.c (add_environment): Never insert existing environment
429
      a password <emphasis>and</emphasis> exit with a successful exit
430
      code will make this plugin-runner output the password from that
431
      plugin, stop any other plugins, and exit.
134 by Teddy Hogeborn
* mandos.xml: Enclose "RAM" with <acronym>.
432
    </para>
182 by Teddy Hogeborn
* Makefile (install): Use "install-client-nokey".
433
    
140 by Teddy Hogeborn
* plugin-runner.xml (PLUGINS/WRITING PLUGINS): New section.
434
    <refsect2 id="writing_plugins">
435
      <title>WRITING PLUGINS</title>
436
      <para>
437
	A plugin is simply a program which prints a password to its
438
	standard output and then exits with a successful (zero) exit
439
	status.  If the exit status is not zero, any output on
440
	standard output will be ignored by the plugin runner.  Any
441
	output on its standard error channel will simply be passed to
442
	the standard error of the plugin runner, usually the system
443
	console.
444
      </para>
445
      <para>
168 by Teddy Hogeborn
* initramfs-tools-hook: Use long options where available. Use only
446
	If the password is a single-line, manually entered passprase,
447
	a final trailing newline character should
448
	<emphasis>not</emphasis> be printed.
449
      </para>
450
      <para>
140 by Teddy Hogeborn
* plugin-runner.xml (PLUGINS/WRITING PLUGINS): New section.
451
	The plugin will run in the initial RAM disk environment, so
452
	care must be taken not to depend on any files or running
738.1.1 by Teddy Hogeborn
Add a plugin helper directory, available to all plugins.
453
	services not available there.  Any helper executables required
454
	by the plugin (which are not in the <envar>PATH</envar>) can
455
	be placed in the plugin helper directory, the name of which
456
	will be made available to the plugin via the
457
	<envar>MANDOSPLUGINHELPERDIR</envar> environment variable.
140 by Teddy Hogeborn
* plugin-runner.xml (PLUGINS/WRITING PLUGINS): New section.
458
      </para>
459
      <para>
460
	The plugin must exit cleanly and free all allocated resources
461
	upon getting the TERM signal, since this is what the plugin
462
	runner uses to stop all other plugins when one plugin has
463
	output a password and exited cleanly.
464
      </para>
465
      <para>
466
	The plugin must not use resources, like for instance reading
155 by Teddy Hogeborn
* README: Improved wording.
467
	from the standard input, without knowing that no other plugin
468
	is also using it.
140 by Teddy Hogeborn
* plugin-runner.xml (PLUGINS/WRITING PLUGINS): New section.
469
      </para>
470
      <para>
471
	It is useful, but not required, for the plugin to take the
472
	<option>--debug</option> option.
473
      </para>
474
    </refsect2>
134 by Teddy Hogeborn
* mandos.xml: Enclose "RAM" with <acronym>.
475
  </refsect1>
476
  
135 by Teddy Hogeborn
* plugin-runner.c (add_environment): Never insert existing environment
477
  <refsect1 id="fallback">
134 by Teddy Hogeborn
* mandos.xml: Enclose "RAM" with <acronym>.
478
    <title>FALLBACK</title>
479
    <para>
135 by Teddy Hogeborn
* plugin-runner.c (add_environment): Never insert existing environment
480
      If no plugins succeed, this program will, as a fallback, ask for
481
      a password on the console using <citerefentry><refentrytitle
482
      >getpass</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
483
      and output it.  This is not meant to be the normal mode of
484
      operation, as there is a separate plugin for getting a password
485
      from the console.
134 by Teddy Hogeborn
* mandos.xml: Enclose "RAM" with <acronym>.
486
    </para>
487
  </refsect1>
135 by Teddy Hogeborn
* plugin-runner.c (add_environment): Never insert existing environment
488
  
24.1.39 by Björn Påhlsson
Added all sections needed for mandos-client manual page
489
  <refsect1 id="exit_status">
490
    <title>EXIT STATUS</title>
491
    <para>
135 by Teddy Hogeborn
* plugin-runner.c (add_environment): Never insert existing environment
492
      Exit status of this program is zero if no errors were
493
      encountered, and otherwise not.  The fallback (see <xref
494
      linkend="fallback"/>) may or may not have succeeded in either
495
      case.
496
    </para>
497
  </refsect1>
498
  
499
  <refsect1 id="environment">
500
    <title>ENVIRONMENT</title>
501
    <para>
139 by Teddy Hogeborn
* plugin-runner.xml: Changed short option for "--global-env" to "-G",
502
      This program does not use any environment variables itself, it
503
      only passes on its environment to all the plugins.  The
504
      environment passed to plugins can be modified using the
505
      <option>--global-env</option> and <option>--env-for</option>
738.1.1 by Teddy Hogeborn
Add a plugin helper directory, available to all plugins.
506
      options.  Also, the <option>--plugin-helper-dir</option> option
507
      will affect the environment variable
508
      <envar>MANDOSPLUGINHELPERDIR</envar> for the plugins.
135 by Teddy Hogeborn
* plugin-runner.c (add_environment): Never insert existing environment
509
    </para>
510
  </refsect1>
511
  
139 by Teddy Hogeborn
* plugin-runner.xml: Changed short option for "--global-env" to "-G",
512
  <refsect1 id="files">
24.1.39 by Björn Påhlsson
Added all sections needed for mandos-client manual page
513
    <title>FILES</title>
514
    <para>
135 by Teddy Hogeborn
* plugin-runner.c (add_environment): Never insert existing environment
515
      <variablelist>
516
	<varlistentry>
517
	  <term><filename
518
	  >/conf/conf.d/mandos/plugin-runner.conf</filename></term>
519
	  <listitem>
520
	    <para>
521
	      Since this program will be run as a keyscript, there is
522
	      little to no opportunity to pass command line arguments
523
	      to it.  Therefore, it will <emphasis>also</emphasis>
524
	      read this file and use its contents as
525
	      whitespace-separated command line options.  Also,
526
	      everything from a <quote>#</quote> character to the end
527
	      of a line is ignored.
528
	    </para>
136 by Teddy Hogeborn
* plugin-runner.c (add_environment): Override existing environment
529
	    <para>
139 by Teddy Hogeborn
* plugin-runner.xml: Changed short option for "--global-env" to "-G",
530
	      This program is meant to run in the initial RAM disk
531
	      environment, so that is where this file is assumed to
532
	      exist.  The file does not need to exist in the normal
533
	      file system.
534
	    </para>
535
	    <para>
136 by Teddy Hogeborn
* plugin-runner.c (add_environment): Override existing environment
536
	      This file will be processed <emphasis>before</emphasis>
537
	      the normal command line options, so the latter can
538
	      override the former, if need be.
539
	    </para>
139 by Teddy Hogeborn
* plugin-runner.xml: Changed short option for "--global-env" to "-G",
540
	    <para>
541
	      This file name is the default; the file to read for
542
	      arguments can be changed using the
543
	      <option>--config-file</option> option.
544
	    </para>
135 by Teddy Hogeborn
* plugin-runner.c (add_environment): Never insert existing environment
545
	  </listitem>
546
	</varlistentry>
547
      </variablelist>
24.1.55 by Björn Påhlsson
updated some partial manual pages
548
    </para>
24.1.39 by Björn Påhlsson
Added all sections needed for mandos-client manual page
549
  </refsect1>
550
  
157 by Teddy Hogeborn
* plugin-runner.xml (BUGS): Document the non-recursiveness of the
551
  <refsect1 id="bugs">
552
    <title>BUGS</title>
553
    <para>
554
      The <option>--config-file</option> option is ignored when
555
      specified from within a configuration file.
556
    </para>
557
  </refsect1>
135 by Teddy Hogeborn
* plugin-runner.c (add_environment): Never insert existing environment
558
  
24.1.39 by Björn Påhlsson
Added all sections needed for mandos-client manual page
559
  <refsect1 id="examples">
113 by Teddy Hogeborn
* mandos-keygen.xml (EXAMPLE): Replaced all occurrences of command
560
    <title>EXAMPLE</title>
140 by Teddy Hogeborn
* plugin-runner.xml (PLUGINS/WRITING PLUGINS): New section.
561
    <informalexample>
562
      <para>
563
	Normal invocation needs no options:
564
      </para>
565
      <para>
566
	<userinput>&COMMANDNAME;</userinput>
567
      </para>
568
    </informalexample>
569
    <informalexample>
570
      <para>
571
	Run the program, but not the plugins, in debug mode:
572
      </para>
573
      <para>
574
	
575
	<!-- do not wrap this line -->
576
	<userinput>&COMMANDNAME; --debug</userinput>
577
	
578
      </para>
579
    </informalexample>
580
    <informalexample>
581
      <para>
582
	Run all plugins, but run the <quote>foo</quote> plugin in
583
	debug mode:
584
      </para>
585
      <para>
586
	
587
	<!-- do not wrap this line -->
588
	<userinput>&COMMANDNAME; --options-for=foo:--debug</userinput>
589
	
590
      </para>
591
    </informalexample>
592
    <informalexample>
593
      <para>
594
	Run all plugins, but not the program, in debug mode:
595
      </para>
596
      <para>
597
	
598
	<!-- do not wrap this line -->
599
	<userinput>&COMMANDNAME; --global-options=--debug</userinput>
600
	
601
      </para>
602
    </informalexample>
603
    <informalexample>
604
      <para>
758 by Teddy Hogeborn
plugin-runner.xml (EXAMPLE): Use the /usr/lib/<arch> directory.
605
	Read a different configuration file, run plugins from a
606
	different directory, specify an alternate plugin helper
607
	directory and add two options to the
171 by Teddy Hogeborn
Renamed "password-request" to "mandos-client".
608
	<citerefentry><refentrytitle >mandos-client</refentrytitle>
140 by Teddy Hogeborn
* plugin-runner.xml (PLUGINS/WRITING PLUGINS): New section.
609
	<manvolnum>8mandos</manvolnum></citerefentry> plugin:
610
      </para>
611
      <para>
612
613
<!-- do not wrap this line -->
758 by Teddy Hogeborn
plugin-runner.xml (EXAMPLE): Use the /usr/lib/<arch> directory.
614
<userinput>cd /etc/keys/mandos; &COMMANDNAME;  --config-file=/etc/mandos/plugin-runner.conf --plugin-dir /usr/lib/x86_64-linux-gnu/mandos/plugins.d --plugin-helper-dir /usr/lib/x86_64-linux-gnu/mandos/plugin-helpers --options-for=mandos-client:--pubkey=pubkey.txt,--seckey=seckey.txt</userinput>
140 by Teddy Hogeborn
* plugin-runner.xml (PLUGINS/WRITING PLUGINS): New section.
615
616
      </para>
617
    </informalexample>
24.1.39 by Björn Påhlsson
Added all sections needed for mandos-client manual page
618
  </refsect1>
619
  <refsect1 id="security">
620
    <title>SECURITY</title>
621
    <para>
140 by Teddy Hogeborn
* plugin-runner.xml (PLUGINS/WRITING PLUGINS): New section.
622
      This program will, when starting, try to switch to another user.
623
      If it is started as root, it will succeed, and will by default
624
      switch to user and group 65534, which are assumed to be
625
      non-privileged.  This user and group is then what all plugins
626
      will be started as.  Therefore, the only way to run a plugin as
627
      a privileged user is to have the set-user-ID or set-group-ID bit
164 by Teddy Hogeborn
* mandos: Open the PID file before daemonizing, but write to it
628
      set on the plugin executable file (see <citerefentry>
140 by Teddy Hogeborn
* plugin-runner.xml (PLUGINS/WRITING PLUGINS): New section.
629
      <refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum>
630
      </citerefentry>).
631
    </para>
632
    <para>
633
      If this program is used as a keyscript in <citerefentry
634
      ><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum>
156 by Teddy Hogeborn
* mandos-clients.conf.xml (OPTIONS): Improved spelling.
635
      </citerefentry>, there is a slight risk that if this program
636
      fails to work, there might be no way to boot the system except
637
      for booting from another media and editing the initial RAM disk
140 by Teddy Hogeborn
* plugin-runner.xml (PLUGINS/WRITING PLUGINS): New section.
638
      image to not run this program.  This is, however, unlikely,
639
      since the <citerefentry><refentrytitle
640
      >password-prompt</refentrytitle><manvolnum>8mandos</manvolnum>
641
      </citerefentry> plugin will read a password from the console in
642
      case of failure of the other plugins, and this plugin runner
643
      will also, in case of catastrophic failure, itself fall back to
644
      asking and outputting a password on the console (see <xref
645
      linkend="fallback"/>).
24.1.55 by Björn Påhlsson
updated some partial manual pages
646
    </para>
24.1.39 by Björn Påhlsson
Added all sections needed for mandos-client manual page
647
  </refsect1>
135 by Teddy Hogeborn
* plugin-runner.c (add_environment): Never insert existing environment
648
  
24.1.39 by Björn Påhlsson
Added all sections needed for mandos-client manual page
649
  <refsect1 id="see_also">
650
    <title>SEE ALSO</title>
651
    <para>
493 by Teddy Hogeborn
* Makefile (DOCS): Added "intro.8mandos".
652
      <citerefentry><refentrytitle>intro</refentrytitle>
653
      <manvolnum>8mandos</manvolnum></citerefentry>,
114 by Teddy Hogeborn
* mandos-clients.conf.xml (SEE ALSO): Alphabetized, as per
654
      <citerefentry><refentrytitle>cryptsetup</refentrytitle>
655
      <manvolnum>8</manvolnum></citerefentry>,
140 by Teddy Hogeborn
* plugin-runner.xml (PLUGINS/WRITING PLUGINS): New section.
656
      <citerefentry><refentrytitle>crypttab</refentrytitle>
657
      <manvolnum>5</manvolnum></citerefentry>,
658
      <citerefentry><refentrytitle>execve</refentrytitle>
659
      <manvolnum>2</manvolnum></citerefentry>,
24.1.41 by Björn Påhlsson
updated mandos-client sections and added see also stuff
660
      <citerefentry><refentrytitle>mandos</refentrytitle>
114 by Teddy Hogeborn
* mandos-clients.conf.xml (SEE ALSO): Alphabetized, as per
661
      <manvolnum>8</manvolnum></citerefentry>,
662
      <citerefentry><refentrytitle>password-prompt</refentrytitle>
113 by Teddy Hogeborn
* mandos-keygen.xml (EXAMPLE): Replaced all occurrences of command
663
      <manvolnum>8mandos</manvolnum></citerefentry>,
171 by Teddy Hogeborn
Renamed "password-request" to "mandos-client".
664
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
114 by Teddy Hogeborn
* mandos-clients.conf.xml (SEE ALSO): Alphabetized, as per
665
      <manvolnum>8mandos</manvolnum></citerefentry>
24.1.41 by Björn Påhlsson
updated mandos-client sections and added see also stuff
666
    </para>
24.1.39 by Björn Påhlsson
Added all sections needed for mandos-client manual page
667
  </refsect1>
135 by Teddy Hogeborn
* plugin-runner.c (add_environment): Never insert existing environment
668
  
24.1.23 by Björn Påhlsson
Added manual pages for:
669
</refentry>
111 by Teddy Hogeborn
* mandos-clients.conf.xml (ENTITY TIMESTAMP): New. Automatically
670
<!-- Local Variables: -->
671
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
672
<!-- time-stamp-end: "[\"']>" -->
673
<!-- time-stamp-format: "%:y-%02m-%02d" -->
674
<!-- End: -->