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