/mandos/release

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