/mandos/release

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