/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-08-31 14:00:36 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080831140036-5bruinjq267s5f8p
* mandos-clients.conf.xml: Changed all single quotes to double quotes
                           for consistency.
* mandos.conf.xml: - '' -
* plugin-runner.xml: - '' -
* plugins.d/password-request.xml: - '' -

Show diffs side-by-side

added added

removed removed

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