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