/mandos/trunk

To get this branch, use:
bzr branch http://bzr.recompile.se/loggerhead/mandos/trunk
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
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 COMMANDNAME "password-prompt">
397 by Teddy Hogeborn
* plugins.d/password-prompt.c: Use environment variables and prompt
5
<!ENTITY TIMESTAMP "2009-10-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>
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
12
    <title>Mandos Manual</title>
13
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
14
    <productname>Mandos</productname>
217 by Teddy Hogeborn
* .bzrignore: Added "man" directory (created by "make install-html").
15
    <productnumber>&version;</productnumber>
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
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>
246 by Teddy Hogeborn
* README: Update copyright year; add "2009".
35
      <year>2009</year>
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
36
      <holder>Teddy Hogeborn</holder>
37
      <holder>Björn Påhlsson</holder>
24.1.23 by Björn Påhlsson
Added manual pages for:
38
    </copyright>
131 by Teddy Hogeborn
* Makefile: Make all DocBook rules include legalnotice.xml as a
39
    <xi:include href="../legalnotice.xml"/>
24.1.23 by Björn Påhlsson
Added manual pages for:
40
  </refentryinfo>
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
41
  
24.1.23 by Björn Påhlsson
Added manual pages for:
42
  <refmeta>
43
    <refentrytitle>&COMMANDNAME;</refentrytitle>
44
    <manvolnum>8mandos</manvolnum>
45
  </refmeta>
46
  
47
  <refnamediv>
48
    <refname><command>&COMMANDNAME;</command></refname>
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
49
    <refpurpose>Prompt for a password and output it.</refpurpose>
24.1.23 by Björn Påhlsson
Added manual pages for:
50
  </refnamediv>
24.1.33 by Björn Påhlsson
synopsis changed
51
  
24.1.23 by Björn Påhlsson
Added manual pages for:
52
  <refsynopsisdiv>
53
    <cmdsynopsis>
54
      <command>&COMMANDNAME;</command>
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
55
      <group choice="opt">
122 by Teddy Hogeborn
* mandos-keygen.xml (SYNOPSIS): Put long options before short.
56
	<arg choice="plain"><option>--prefix <replaceable
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
57
	>PREFIX</replaceable></option></arg>
122 by Teddy Hogeborn
* mandos-keygen.xml (SYNOPSIS): Put long options before short.
58
	<arg choice="plain"><option>-p </option><replaceable
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
59
	>PREFIX</replaceable></arg>
60
      </group>
122 by Teddy Hogeborn
* mandos-keygen.xml (SYNOPSIS): Put long options before short.
61
      <sbr/>
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
62
      <arg choice="opt"><option>--debug</option></arg>
63
    </cmdsynopsis>
64
    <cmdsynopsis>
65
      <command>&COMMANDNAME;</command>
66
      <group choice="req">
122 by Teddy Hogeborn
* mandos-keygen.xml (SYNOPSIS): Put long options before short.
67
	<arg choice="plain"><option>--help</option></arg>
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
68
	<arg choice="plain"><option>-?</option></arg>
69
      </group>
70
    </cmdsynopsis>
71
    <cmdsynopsis>
72
      <command>&COMMANDNAME;</command>
73
      <arg choice="plain"><option>--usage</option></arg>
74
    </cmdsynopsis>
75
    <cmdsynopsis>
76
      <command>&COMMANDNAME;</command>
77
      <group choice="req">
122 by Teddy Hogeborn
* mandos-keygen.xml (SYNOPSIS): Put long options before short.
78
	<arg choice="plain"><option>--version</option></arg>
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
79
	<arg choice="plain"><option>-V</option></arg>
80
      </group>
118 by Teddy Hogeborn
* mandos-keygen.xml (SYNOPSIS): Fixed tags. Unify short and long
81
    </cmdsynopsis>
24.1.23 by Björn Påhlsson
Added manual pages for:
82
  </refsynopsisdiv>
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
83
  
24.1.23 by Björn Påhlsson
Added manual pages for:
84
  <refsect1 id="description">
85
    <title>DESCRIPTION</title>
86
    <para>
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
87
      All <command>&COMMANDNAME;</command> does is prompt for a
224 by Teddy Hogeborn
* mandos-keygen.xml (FILES): Fixed id to be "files", not "file".
88
      password and output any given password to standard output.
89
    </para>
90
    <para>
91
      This program is not very useful on its own.  This program is
92
      really meant to run as a plugin in the <application
93
      >Mandos</application> client-side system, where it is used as a
94
      fallback and alternative to retrieving passwords from a
95
      <application >Mandos</application> server.
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
96
    </para>
97
    <para>
98
      This program is little more than a <citerefentry><refentrytitle
99
      >getpass</refentrytitle><manvolnum>3</manvolnum></citerefentry>
100
      wrapper, although actual use of that function is not guaranteed
101
      or implied.
24.1.23 by Björn Påhlsson
Added manual pages for:
102
    </para>
24.1.55 by Björn Påhlsson
updated some partial manual pages
103
  </refsect1>
104
  
105
  <refsect1 id="options">
106
    <title>OPTIONS</title>
107
    <para>
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
108
      This program is commonly not invoked from the command line; it
109
      is normally started by the <application>Mandos</application>
110
      plugin runner, see <citerefentry><refentrytitle
111
      >plugin-runner</refentrytitle><manvolnum>8mandos</manvolnum>
112
      </citerefentry>.  Any command line options this program accepts
113
      are therefore normally provided by the plugin runner, and not
114
      directly.
24.1.55 by Björn Påhlsson
updated some partial manual pages
115
    </para>
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
116
    
24.1.23 by Björn Påhlsson
Added manual pages for:
117
    <variablelist>
118
      <varlistentry>
126 by Teddy Hogeborn
* plugins.d/password-prompt.xml (OPTIONS): Move <replaceable> tags to
119
	<term><option>--prefix=<replaceable
120
	>PREFIX</replaceable></option></term>
121
	<term><option>-p
122
	<replaceable>PREFIX</replaceable></option></term>
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
123
	<listitem>
124
	  <para>
125
	    Prefix string shown before the password prompt.
126
	  </para>
127
	</listitem>
128
      </varlistentry>
129
      
130
      <varlistentry>
131
	<term><option>--debug</option></term>
132
	<listitem>
133
	  <para>
134
	    Enable debug mode.  This will enable a lot of output to
135
	    standard error about what the program is doing.  The
136
	    program will still perform all other functions normally.
137
	  </para>
138
	</listitem>
139
      </varlistentry>
140
      
141
      <varlistentry>
126 by Teddy Hogeborn
* plugins.d/password-prompt.xml (OPTIONS): Move <replaceable> tags to
142
	<term><option>--help</option></term>
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
143
	<term><option>-?</option></term>
144
	<listitem>
145
	  <para>
146
	    Gives a help message about options and their meanings.
147
	  </para>
148
	</listitem>
149
      </varlistentry>
150
      
151
      <varlistentry>
152
	<term><option>--usage</option></term>
153
	<listitem>
154
	  <para>
155
	    Gives a short usage message.
156
	  </para>
157
	</listitem>
158
      </varlistentry>
159
      
160
      <varlistentry>
126 by Teddy Hogeborn
* plugins.d/password-prompt.xml (OPTIONS): Move <replaceable> tags to
161
	<term><option>--version</option></term>
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
162
	<term><option>-V</option></term>
163
	<listitem>
164
	  <para>
165
	    Prints the program version.
24.1.23 by Björn Påhlsson
Added manual pages for:
166
	  </para>
167
	</listitem>
118 by Teddy Hogeborn
* mandos-keygen.xml (SYNOPSIS): Fixed tags. Unify short and long
168
      </varlistentry>
24.1.23 by Björn Påhlsson
Added manual pages for:
169
    </variablelist>
170
  </refsect1>
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
171
  
24.1.55 by Björn Påhlsson
updated some partial manual pages
172
  <refsect1 id="exit_status">
173
    <title>EXIT STATUS</title>
174
    <para>
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
175
      If exit status is 0, the output from the program is the password
176
      as it was read.  Otherwise, if exit status is other than 0, the
177
      program has encountered an error, and any output so far could be
178
      corrupt and/or truncated, and should therefore be ignored.
24.1.55 by Björn Påhlsson
updated some partial manual pages
179
    </para>
180
  </refsect1>
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
181
  
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
182
  <refsect1 id="environment">
183
    <title>ENVIRONMENT</title>
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
184
    <variablelist>
185
      <varlistentry>
397 by Teddy Hogeborn
* plugins.d/password-prompt.c: Use environment variables and prompt
186
	<term><envar>CRYPTTAB_SOURCE</envar></term>
187
	<term><envar>CRYPTTAB_NAME</envar></term>
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
188
	<listitem>
189
	  <para>
190
	    If set, these environment variables will be assumed to
191
	    contain the source device name and the target device
192
	    mapper name, respectively, and will be shown as part of
193
	    the prompt.
194
	</para>
195
	<para>
196
	  These variables will normally be inherited from
197
	  <citerefentry><refentrytitle>plugin-runner</refentrytitle>
198
	  <manvolnum>8mandos</manvolnum></citerefentry>, which will
199
	  normally have inherited them from
200
	  <filename>/scripts/local-top/cryptroot</filename> in the
134 by Teddy Hogeborn
* mandos.xml: Enclose "RAM" with <acronym>.
201
	  initial <acronym>RAM</acronym> disk environment, which will
202
	  have set them from parsing kernel arguments and
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
203
	  <filename>/conf/conf.d/cryptroot</filename> (also in the
204
	  initial RAM disk environment), which in turn will have been
205
	  created when the initial RAM disk image was created by
206
	  <filename
207
	  >/usr/share/initramfs-tools/hooks/cryptroot</filename>, by
208
	  extracting the information of the root file system from
209
	  <filename >/etc/crypttab</filename>.
210
	</para>
211
	<para>
212
	  This behavior is meant to exactly mirror the behavior of
213
	  <command>askpass</command>, the default password prompter.
214
	</para>
215
	</listitem>
216
      </varlistentry>
217
    </variablelist>
24.1.55 by Björn Påhlsson
updated some partial manual pages
218
  </refsect1>
219
  
220
  <refsect1 id="bugs">
221
    <title>BUGS</title>
222
    <para>
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
223
      None are known at this time.
24.1.55 by Björn Påhlsson
updated some partial manual pages
224
    </para>
118 by Teddy Hogeborn
* mandos-keygen.xml (SYNOPSIS): Fixed tags. Unify short and long
225
  </refsect1>
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
226
  
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
227
  <refsect1 id="example">
228
    <title>EXAMPLE</title>
24.1.55 by Björn Påhlsson
updated some partial manual pages
229
    <para>
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
230
      Note that normally, command line options will not be given
231
      directly, but via options for the Mandos <citerefentry
232
      ><refentrytitle>plugin-runner</refentrytitle>
233
      <manvolnum>8mandos</manvolnum></citerefentry>.
24.1.55 by Björn Påhlsson
updated some partial manual pages
234
    </para>
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
235
    <informalexample>
236
      <para>
237
	Normal invocation needs no options:
238
      </para>
239
      <para>
240
	<userinput>&COMMANDNAME;</userinput>
241
      </para>
242
    </informalexample>
243
    <informalexample>
244
      <para>
245
	Show a prefix before the prompt; in this case, a host name.
246
	It might be useful to be reminded of which host needs a
156 by Teddy Hogeborn
* mandos-clients.conf.xml (OPTIONS): Improved spelling.
247
	password, in case of <acronym>KVM</acronym> switches, etc.
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
248
      </para>
249
      <para>
250
251
<!-- do not wrap this line -->
252
<userinput>&COMMANDNAME; --prefix=host.example.org:</userinput>
253
254
      </para>
255
    </informalexample>
256
    <informalexample>
257
      <para>
258
	Run in debug mode.
259
      </para>
260
      <para>
261
	<!-- do not wrap this line -->
262
	<userinput>&COMMANDNAME; --debug</userinput>
263
      </para>
264
    </informalexample>
24.1.55 by Björn Påhlsson
updated some partial manual pages
265
  </refsect1>
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
266
  
24.1.55 by Björn Påhlsson
updated some partial manual pages
267
  <refsect1 id="security">
268
    <title>SECURITY</title>
269
    <para>
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
270
      On its own, this program is very simple, and does not exactly
271
      present any security risks.  The one thing that could be
272
      considered worthy of note is this: This program is meant to be
273
      run by <citerefentry><refentrytitle
274
      >plugin-runner</refentrytitle><manvolnum>8mandos</manvolnum>
275
      </citerefentry>, and will, when run standalone, outside, in a
276
      normal environment, immediately output on its standard output
156 by Teddy Hogeborn
* mandos-clients.conf.xml (OPTIONS): Improved spelling.
277
      any presumably secret password it just received.  Therefore,
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
278
      when running this program standalone (which should never
279
      normally be done), take care not to type in any real secret
280
      password by force of habit, since it would then immediately be
281
      shown as output.
282
    </para>
283
    <para>
284
      To further alleviate any risk of being locked out of a system,
285
      the <citerefentry><refentrytitle>plugin-runner</refentrytitle>
286
      <manvolnum>8mandos</manvolnum></citerefentry> has a fallback
287
      mode which does the same thing as this program, only with less
288
      features.
24.1.55 by Björn Påhlsson
updated some partial manual pages
289
    </para>
290
  </refsect1>
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
291
  
24.1.55 by Björn Påhlsson
updated some partial manual pages
292
  <refsect1 id="see_also">
293
    <title>SEE ALSO</title>
294
    <para>
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
295
      <citerefentry><refentrytitle>crypttab</refentrytitle>
296
      <manvolnum>5</manvolnum></citerefentry>
171 by Teddy Hogeborn
Renamed "password-request" to "mandos-client".
297
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
24.1.55 by Björn Påhlsson
updated some partial manual pages
298
      <manvolnum>8mandos</manvolnum></citerefentry>
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
299
      <citerefentry><refentrytitle>plugin-runner</refentrytitle>
300
      <manvolnum>8mandos</manvolnum></citerefentry>,
24.1.55 by Björn Påhlsson
updated some partial manual pages
301
    </para>
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
302
  </refsect1>
24.1.23 by Björn Påhlsson
Added manual pages for:
303
</refentry>
110 by Teddy Hogeborn
* mandos.xml (EXAMPLE): Replaced all occurences of command name with
304
<!-- Local Variables: -->
305
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
306
<!-- time-stamp-end: "[\"']>" -->
307
<!-- time-stamp-format: "%:y-%02m-%02d" -->
308
<!-- End: -->