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