/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
9
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
124
124
  <refsect1 id="description">
125
125
    <title>DESCRIPTION</title>
126
126
    <para>
127
 
      <command>&COMMANDNAME;</command> is a mandos plugin that works
128
 
      like a client program that through avahi detects mandos servers,
129
 
      sets up a gnutls connect and request a encrypted password. Any
130
 
      passwords given is automaticly decrypted and passed to
131
 
      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.
132
173
    </para>
133
174
  </refsect1>
134
175
  
135
176
  <refsect1 id="options">
136
177
    <title>OPTIONS</title>
137
178
    <para>
138
 
      Commonly not invoked as command lines but from configuration
139
 
      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.
140
186
    </para>
141
 
 
 
187
    
142
188
    <variablelist>
143
189
      <varlistentry>
144
190
        <term><option>--connect=<replaceable
149
195
        ><replaceable>PORT</replaceable></option></term>
150
196
        <listitem>
151
197
          <para>
152
 
            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.
153
206
          </para>
154
207
        </listitem>
155
208
      </varlistentry>
156
 
 
 
209
      
157
210
      <varlistentry>
158
211
        <term><option>--keydir=<replaceable
159
212
        >DIRECTORY</replaceable></option></term>
161
214
        <replaceable>DIRECTORY</replaceable></option></term>
162
215
        <listitem>
163
216
          <para>
164
 
            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).
165
222
          </para>
166
223
        </listitem>
167
224
      </varlistentry>
173
230
        <replaceable>NAME</replaceable></option></term>
174
231
        <listitem>
175
232
          <para>
176
 
            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>.
177
236
          </para>
178
237
        </listitem>
179
238
      </varlistentry>
180
 
 
 
239
      
181
240
      <varlistentry>
182
241
        <term><option>--pubkey=<replaceable
183
242
        >FILE</replaceable></option></term>
185
244
        <replaceable>FILE</replaceable></option></term>
186
245
        <listitem>
187
246
          <para>
188
 
            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>.
189
251
          </para>
190
252
        </listitem>
191
253
      </varlistentry>
197
259
        <replaceable>FILE</replaceable></option></term>
198
260
        <listitem>
199
261
          <para>
200
 
            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>.
201
266
          </para>
202
267
        </listitem>
203
268
      </varlistentry>
206
271
        <term><option>--priority=<replaceable
207
272
        >STRING</replaceable></option></term>
208
273
        <listitem>
209
 
          <para>
210
 
            GnuTLS priority
211
 
          </para>
 
274
          <xi:include href="mandos-options.xml" xpointer="priority"/>
212
275
        </listitem>
213
276
      </varlistentry>
214
277
 
217
280
        >BITS</replaceable></option></term>
218
281
        <listitem>
219
282
          <para>
220
 
            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.
221
285
          </para>
222
286
        </listitem>
223
287
      </varlistentry>
226
290
        <term><option>--debug</option></term>
227
291
        <listitem>
228
292
          <para>
229
 
            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.
230
301
          </para>
231
302
        </listitem>
232
303
      </varlistentry>
236
307
        <term><option>-?</option></term>
237
308
        <listitem>
238
309
          <para>
239
 
            Gives a help message
 
310
            Gives a help message about options and their meanings.
240
311
          </para>
241
312
        </listitem>
242
313
      </varlistentry>
245
316
        <term><option>--usage</option></term>
246
317
        <listitem>
247
318
          <para>
248
 
            Gives a short usage message
 
319
            Gives a short usage message.
249
320
          </para>
250
321
        </listitem>
251
322
      </varlistentry>
255
326
        <term><option>-V</option></term>
256
327
        <listitem>
257
328
          <para>
258
 
            Prints the program version
 
329
            Prints the program version.
259
330
          </para>
260
331
        </listitem>
261
332
      </varlistentry>
265
336
  <refsect1 id="exit_status">
266
337
    <title>EXIT STATUS</title>
267
338
    <para>
268
 
    </para>
269
 
  </refsect1>
270
 
 
271
 
  <refsect1 id="environment">
272
 
    <title>ENVIRONMENT</title>
273
 
    <para>
274
 
    </para>
275
 
  </refsect1>
276
 
 
 
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
  
277
356
  <refsect1 id="file">
278
357
    <title>FILES</title>
279
358
    <para>