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