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