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