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