/mandos/trunk

To get this branch, use:
bzr branch http://bzr.recompile.se/loggerhead/mandos/trunk

« back to all changes in this revision

Viewing changes to plugins.d/password-request.xml

  • Committer: Teddy Hogeborn
  • Date: 2008-09-02 17:42:53 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080902174253-p3wxrq7z6ccnv7fs
* plugins.d/password-request.c (main): Change default GnuTLS priority
                                       string to
                             "SECURE256":!CTYPE-X.509:+CTYPE-OPENPGP".

* plugins.d/password-request.xml (DESCRIPTION): Improve wording.
  (PURPOSE, OVERVIEW): New sections.
  (OPTIONS): Improved wording.
  (EXIT STATUS): Add text.
  (ENVIRONMENT): Commented out.

Show diffs side-by-side

added added

removed removed

Lines of Context:
plugins.d/password-request.xml
3
3
        "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4
4
<!ENTITY VERSION "1.0">
5
5
<!ENTITY COMMANDNAME "password-request">
6
 
<!ENTITY TIMESTAMP "2008-08-31">
 
6
<!ENTITY TIMESTAMP "2008-09-02">
7
7
]>
8
8
 
9
 
<refentry>
 
9
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
10
10
  <refentryinfo>
11
11
    <title>Mandos Manual</title>
12
12
    <!-- Nwalsh’s docbook scripts use this to generate the footer: -->
34
34
      <holder>Teddy Hogeborn</holder>
35
35
      <holder>Björn Påhlsson</holder>
36
36
    </copyright>
37
 
    <legalnotice>
38
 
      <para>
39
 
        This manual page is free software: you can redistribute it
40
 
        and/or modify it under the terms of the GNU General Public
41
 
        License as published by the Free Software Foundation,
42
 
        either version 3 of the License, or (at your option) any
43
 
        later version.
44
 
      </para>
45
 
 
46
 
      <para>
47
 
        This manual page is distributed in the hope that it will
48
 
        be useful, but WITHOUT ANY WARRANTY; without even the
49
 
        implied warranty of MERCHANTABILITY or FITNESS FOR A
50
 
        PARTICULAR PURPOSE.  See the GNU General Public License
51
 
        for more details.
52
 
      </para>
53
 
 
54
 
      <para>
55
 
        You should have received a copy of the GNU General Public
56
 
        License along with this program; If not, see
57
 
        <ulink url="http://www.gnu.org/licenses/"/>.
58
 
      </para>
59
 
    </legalnotice>
 
37
    <xi:include href="../legalnotice.xml"/>
60
38
  </refentryinfo>
61
39
 
62
40
  <refmeta>
146
124
  <refsect1 id="description">
147
125
    <title>DESCRIPTION</title>
148
126
    <para>
149
 
      <command>&COMMANDNAME;</command> is a mandos plugin that works
150
 
      like a client program that through avahi detects mandos servers,
151
 
      sets up a gnutls connect and request a encrypted password. Any
152
 
      passwords given is automaticly decrypted and passed to
153
 
      cryptsetup.
 
127
      <command>&COMMANDNAME;</command> is a client program that
 
128
      communicates with <citerefentry><refentrytitle
 
129
      >mandos</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 
130
      to get a password.  It uses IPv6 link-local addresses to get
 
131
      network connectivity, Zeroconf to find the server, and TLS with
 
132
      an OpenPGP key to ensure authenticity and confidentiality.  It
 
133
      keeps running, trying all servers on the network, until it
 
134
      receives a satisfactory reply.
 
135
    </para>
 
136
    <para>
 
137
      This program is not meant to be run directly; it is really meant
 
138
      to run as a plugin of the <application>Mandos</application>
 
139
      <citerefentry><refentrytitle>plugin-runner</refentrytitle>
 
140
      <manvolnum>8mandos</manvolnum></citerefentry>, which in turn
 
141
      runs as a <quote>keyscript</quote> specified in the
 
142
      <citerefentry><refentrytitle>crypttab</refentrytitle>
 
143
      <manvolnum>5</manvolnum></citerefentry> file.
 
144
    </para>
 
145
  </refsect1>
 
146
  
 
147
  <refsect1 id="purpose">
 
148
    <title>PURPOSE</title>
 
149
    <para>
 
150
      The purpose of this is to enable <emphasis>remote and unattended
 
151
      rebooting</emphasis> of client host computer with an
 
152
      <emphasis>encrypted root file system</emphasis>.  See <xref
 
153
      linkend="overview"/> for details.
 
154
    </para>
 
155
  </refsect1>
 
156
  
 
157
  <refsect1 id="overview">
 
158
    <title>OVERVIEW</title>
 
159
    <xi:include href="overview.xml"/>
 
160
    <para>
 
161
      This program is the client part.  It is a plugin started by
 
162
      <citerefentry><refentrytitle>plugin-runner</refentrytitle>
 
163
      <manvolnum>8mandos</manvolnum></citerefentry> which will run in
 
164
      an initial <acronym>RAM</acronym> disk environment.
 
165
    </para>
 
166
    <para>
 
167
      This program could, theoretically, be used as a keyscript in
 
168
      <filename>/etc/crypttab</filename>, but it would then be
 
169
      impossible to enter the encrypted root disk password at the
 
170
      console, since this program does not read from the console at
 
171
      all.  This is why a separate plugin does that, which will be run
 
172
      in parallell to this one.
154
173
    </para>
155
174
  </refsect1>
156
175
  
157
176
  <refsect1 id="options">
158
177
    <title>OPTIONS</title>
159
178
    <para>
160
 
      Commonly not invoked as command lines but from configuration
161
 
      file of plugin runner.
 
179
      This program is commonly not invoked from the command line; it
 
180
      is normally started by the <application>Mandos</application>
 
181
      plugin runner, see <citerefentry><refentrytitle
 
182
      >plugin-runner</refentrytitle><manvolnum>8mandos</manvolnum>
 
183
      </citerefentry>.  Any command line options this program accepts
 
184
      are therefore normally provided by the plugin runner, and not
 
185
      directly.
162
186
    </para>
163
 
 
 
187
    
164
188
    <variablelist>
165
189
      <varlistentry>
166
190
        <term><option>--connect=<replaceable
171
195
        ><replaceable>PORT</replaceable></option></term>
172
196
        <listitem>
173
197
          <para>
174
 
            Connect directly to a specified mandos server
 
198
            Do not use Zeroconf to locate servers.  Connect directly
 
199
            to only one specified <application>Mandos</application>
 
200
            server.  Note that an IPv6 address has colon characters in
 
201
            it, so the <emphasis>last</emphasis> colon character is
 
202
            assumed to separate the address from the port number.
 
203
          </para>
 
204
          <para>
 
205
            This option is normally only useful for debugging.
175
206
          </para>
176
207
        </listitem>
177
208
      </varlistentry>
178
 
 
 
209
      
179
210
      <varlistentry>
180
211
        <term><option>--keydir=<replaceable
181
212
        >DIRECTORY</replaceable></option></term>
183
214
        <replaceable>DIRECTORY</replaceable></option></term>
184
215
        <listitem>
185
216
          <para>
186
 
            Directory where the openpgp keyring is
 
217
            Directory to read the OpenPGP key files
 
218
            <filename>pubkey.txt</filename> and
 
219
            <filename>seckey.txt</filename> from.  The default is
 
220
            <filename>/conf/conf.d/mandos</filename> (in the initial
 
221
            <acronym>RAM</acronym> disk environment).
187
222
          </para>
188
223
        </listitem>
189
224
      </varlistentry>
195
230
        <replaceable>NAME</replaceable></option></term>
196
231
        <listitem>
197
232
          <para>
198
 
            Interface that Avahi will connect through
 
233
            Network interface that will be brought up and scanned for
 
234
            Mandos servers to connect to.  The default it
 
235
            <quote><literal>eth0</literal></quote>.
199
236
          </para>
200
237
        </listitem>
201
238
      </varlistentry>
202
 
 
 
239
      
203
240
      <varlistentry>
204
241
        <term><option>--pubkey=<replaceable
205
242
        >FILE</replaceable></option></term>
207
244
        <replaceable>FILE</replaceable></option></term>
208
245
        <listitem>
209
246
          <para>
210
 
            Public openpgp key for gnutls authentication
 
247
            OpenPGP public key file name.  This will be combined with
 
248
            the directory from the <option>--keydir</option> option to
 
249
            form an absolute file name.  The default name is
 
250
            <quote><literal>pubkey.txt</literal></quote>.
211
251
          </para>
212
252
        </listitem>
213
253
      </varlistentry>
219
259
        <replaceable>FILE</replaceable></option></term>
220
260
        <listitem>
221
261
          <para>
222
 
            Secret OpenPGP key for GnuTLS authentication
 
262
            OpenPGP secret key file name.  This will be combined with
 
263
            the directory from the <option>--keydir</option> option to
 
264
            form an absolute file name.  The default name is
 
265
            <quote><literal>seckey.txt</literal></quote>.
223
266
          </para>
224
267
        </listitem>
225
268
      </varlistentry>
228
271
        <term><option>--priority=<replaceable
229
272
        >STRING</replaceable></option></term>
230
273
        <listitem>
231
 
          <para>
232
 
            GnuTLS priority
233
 
          </para>
 
274
          <xi:include href="mandos-options.xml" xpointer="priority"/>
234
275
        </listitem>
235
276
      </varlistentry>
236
277
 
239
280
        >BITS</replaceable></option></term>
240
281
        <listitem>
241
282
          <para>
242
 
            DH bits to use in gnutls communication
 
283
            Sets the number of bits to use for the prime number in the
 
284
            TLS Diffie-Hellman key exchange.  Default is 1024.
243
285
          </para>
244
286
        </listitem>
245
287
      </varlistentry>
248
290
        <term><option>--debug</option></term>
249
291
        <listitem>
250
292
          <para>
251
 
            Debug mode
 
293
            Enable debug mode.  This will enable a lot of output to
 
294
            standard error about what the program is doing.  The
 
295
            program will still perform all other functions normally.
 
296
          </para>
 
297
          <para>
 
298
            It will also enable debug mode in the Avahi and GnuTLS
 
299
            libraries, making them print large amounts of debugging
 
300
            output.
252
301
          </para>
253
302
        </listitem>
254
303
      </varlistentry>
258
307
        <term><option>-?</option></term>
259
308
        <listitem>
260
309
          <para>
261
 
            Gives a help message
 
310
            Gives a help message about options and their meanings.
262
311
          </para>
263
312
        </listitem>
264
313
      </varlistentry>
267
316
        <term><option>--usage</option></term>
268
317
        <listitem>
269
318
          <para>
270
 
            Gives a short usage message
 
319
            Gives a short usage message.
271
320
          </para>
272
321
        </listitem>
273
322
      </varlistentry>
277
326
        <term><option>-V</option></term>
278
327
        <listitem>
279
328
          <para>
280
 
            Prints the program version
 
329
            Prints the program version.
281
330
          </para>
282
331
        </listitem>
283
332
      </varlistentry>
287
336
  <refsect1 id="exit_status">
288
337
    <title>EXIT STATUS</title>
289
338
    <para>
290
 
    </para>
291
 
  </refsect1>
292
 
 
293
 
  <refsect1 id="environment">
294
 
    <title>ENVIRONMENT</title>
295
 
    <para>
296
 
    </para>
297
 
  </refsect1>
298
 
 
 
339
      This program will exit with a successful (zero) exit status if a
 
340
      server could be found and the password received from it could be
 
341
      successfully decrypted and output on standard output.  The
 
342
      program will exit with a non-zero exit status only if a critical
 
343
      error occurs.  Otherwise, it will forever connect to new
 
344
      <application>Mandosservers</application> servers as they appear,
 
345
      trying to get a decryptable password.
 
346
    </para>
 
347
  </refsect1>
 
348
  
 
349
<!--   <refsect1 id="environment"> -->
 
350
<!--     <title>ENVIRONMENT</title> -->
 
351
<!--     <para> -->
 
352
<!--       This program does not use any environment variables. -->
 
353
<!--     </para> -->
 
354
<!--   </refsect1> -->
 
355
  
299
356
  <refsect1 id="file">
300
357
    <title>FILES</title>
301
358
    <para>