/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-03 05:04:40 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080903050440-7cwzxestx6pvdy1i
* Makefile (mandos.8): Add dependency on "overview.xml" and
                       "legalnotice.xml".
  (mandos-keygen.8): New target.
  (mandos-conf.5): Added dependency on "legalnotice.xml".
  (plugin-runner.8mandos): New target
  (plugins.d/password-request.8mandos): - '' -

* mandos-options.xml (priority): Make wording server/client neutral.

* plugins.d/password-request.c (main): Changed .arg fields of the argp
                                       options struct to be more
                                       consistent with the manual.

* plugins.d/password-request.xml (OVERVIEW): Moved to after "OPTIONS".
  (OPTIONS): Improved wording and names of replaceables.

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-03">
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 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.
154
155
    </para>
155
156
  </refsect1>
156
157
  
157
158
  <refsect1 id="options">
158
159
    <title>OPTIONS</title>
159
160
    <para>
160
 
      Commonly not invoked as command lines but from configuration
161
 
      file of plugin runner.
 
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
168
    </para>
163
 
 
 
169
    
164
170
    <variablelist>
165
171
      <varlistentry>
166
172
        <term><option>--connect=<replaceable
167
 
        >IPADDR</replaceable><literal>:</literal><replaceable
 
173
        >ADDRESS</replaceable><literal>:</literal><replaceable
168
174
        >PORT</replaceable></option></term>
169
175
        <term><option>-c
170
 
        <replaceable>IPADDR</replaceable><literal>:</literal
 
176
        <replaceable>ADDRESS</replaceable><literal>:</literal
171
177
        ><replaceable>PORT</replaceable></option></term>
172
178
        <listitem>
173
179
          <para>
174
 
            Connect directly to a specified mandos server
 
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.
175
189
          </para>
176
190
        </listitem>
177
191
      </varlistentry>
178
 
 
 
192
      
179
193
      <varlistentry>
180
194
        <term><option>--keydir=<replaceable
181
195
        >DIRECTORY</replaceable></option></term>
183
197
        <replaceable>DIRECTORY</replaceable></option></term>
184
198
        <listitem>
185
199
          <para>
186
 
            Directory where the openpgp keyring is
 
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).
187
205
          </para>
188
206
        </listitem>
189
207
      </varlistentry>
195
213
        <replaceable>NAME</replaceable></option></term>
196
214
        <listitem>
197
215
          <para>
198
 
            Interface that Avahi will connect through
 
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>.
199
219
          </para>
200
220
        </listitem>
201
221
      </varlistentry>
202
 
 
 
222
      
203
223
      <varlistentry>
204
224
        <term><option>--pubkey=<replaceable
205
225
        >FILE</replaceable></option></term>
207
227
        <replaceable>FILE</replaceable></option></term>
208
228
        <listitem>
209
229
          <para>
210
 
            Public openpgp key for gnutls authentication
 
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>.
211
234
          </para>
212
235
        </listitem>
213
236
      </varlistentry>
219
242
        <replaceable>FILE</replaceable></option></term>
220
243
        <listitem>
221
244
          <para>
222
 
            Secret OpenPGP key for GnuTLS authentication
 
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>.
223
249
          </para>
224
250
        </listitem>
225
251
      </varlistentry>
228
254
        <term><option>--priority=<replaceable
229
255
        >STRING</replaceable></option></term>
230
256
        <listitem>
231
 
          <para>
232
 
            GnuTLS priority
233
 
          </para>
 
257
          <xi:include href="../mandos-options.xml"
 
258
                      xpointer="priority"/>
234
259
        </listitem>
235
260
      </varlistentry>
236
261
 
239
264
        >BITS</replaceable></option></term>
240
265
        <listitem>
241
266
          <para>
242
 
            DH bits to use in gnutls communication
 
267
            Sets the number of bits to use for the prime number in the
 
268
            TLS Diffie-Hellman key exchange.  Default is 1024.
243
269
          </para>
244
270
        </listitem>
245
271
      </varlistentry>
248
274
        <term><option>--debug</option></term>
249
275
        <listitem>
250
276
          <para>
251
 
            Debug mode
 
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.
252
285
          </para>
253
286
        </listitem>
254
287
      </varlistentry>
258
291
        <term><option>-?</option></term>
259
292
        <listitem>
260
293
          <para>
261
 
            Gives a help message
 
294
            Gives a help message about options and their meanings.
262
295
          </para>
263
296
        </listitem>
264
297
      </varlistentry>
267
300
        <term><option>--usage</option></term>
268
301
        <listitem>
269
302
          <para>
270
 
            Gives a short usage message
 
303
            Gives a short usage message.
271
304
          </para>
272
305
        </listitem>
273
306
      </varlistentry>
277
310
        <term><option>-V</option></term>
278
311
        <listitem>
279
312
          <para>
280
 
            Prints the program version
 
313
            Prints the program version.
281
314
          </para>
282
315
        </listitem>
283
316
      </varlistentry>
284
317
    </variablelist>
285
318
  </refsect1>
286
319
 
 
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
  
287
339
  <refsect1 id="exit_status">
288
340
    <title>EXIT STATUS</title>
289
341
    <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.
290
349
    </para>
291
350
  </refsect1>
292
 
 
 
351
  
293
352
  <refsect1 id="environment">
294
353
    <title>ENVIRONMENT</title>
295
354
    <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>.
296
359
    </para>
297
360
  </refsect1>
298
 
 
 
361
  
299
362
  <refsect1 id="file">
300
363
    <title>FILES</title>
301
364
    <para>
346
409
      
347
410
      <listitem><para>
348
411
        <ulink
349
 
        url="http://www.gnupg.org/related_software/gpgme/">
350
 
        GPGME</ulink>
 
412
        url="http://www.gnupg.org/related_software/gpgme/"
 
413
        >GPGME</ulink>
351
414
      </para></listitem>
352
415
      
353
416
      <listitem><para>