/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
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 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.
132
155
    </para>
133
156
  </refsect1>
134
157
  
135
158
  <refsect1 id="options">
136
159
    <title>OPTIONS</title>
137
160
    <para>
138
 
      Commonly not invoked as command lines but from configuration
139
 
      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.
140
168
    </para>
141
 
 
 
169
    
142
170
    <variablelist>
143
171
      <varlistentry>
144
172
        <term><option>--connect=<replaceable
145
 
        >IPADDR</replaceable><literal>:</literal><replaceable
 
173
        >ADDRESS</replaceable><literal>:</literal><replaceable
146
174
        >PORT</replaceable></option></term>
147
175
        <term><option>-c
148
 
        <replaceable>IPADDR</replaceable><literal>:</literal
 
176
        <replaceable>ADDRESS</replaceable><literal>:</literal
149
177
        ><replaceable>PORT</replaceable></option></term>
150
178
        <listitem>
151
179
          <para>
152
 
            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.
153
189
          </para>
154
190
        </listitem>
155
191
      </varlistentry>
156
 
 
 
192
      
157
193
      <varlistentry>
158
194
        <term><option>--keydir=<replaceable
159
195
        >DIRECTORY</replaceable></option></term>
161
197
        <replaceable>DIRECTORY</replaceable></option></term>
162
198
        <listitem>
163
199
          <para>
164
 
            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).
165
205
          </para>
166
206
        </listitem>
167
207
      </varlistentry>
173
213
        <replaceable>NAME</replaceable></option></term>
174
214
        <listitem>
175
215
          <para>
176
 
            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>.
177
219
          </para>
178
220
        </listitem>
179
221
      </varlistentry>
180
 
 
 
222
      
181
223
      <varlistentry>
182
224
        <term><option>--pubkey=<replaceable
183
225
        >FILE</replaceable></option></term>
185
227
        <replaceable>FILE</replaceable></option></term>
186
228
        <listitem>
187
229
          <para>
188
 
            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>.
189
234
          </para>
190
235
        </listitem>
191
236
      </varlistentry>
197
242
        <replaceable>FILE</replaceable></option></term>
198
243
        <listitem>
199
244
          <para>
200
 
            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>.
201
249
          </para>
202
250
        </listitem>
203
251
      </varlistentry>
206
254
        <term><option>--priority=<replaceable
207
255
        >STRING</replaceable></option></term>
208
256
        <listitem>
209
 
          <para>
210
 
            GnuTLS priority
211
 
          </para>
 
257
          <xi:include href="../mandos-options.xml"
 
258
                      xpointer="priority"/>
212
259
        </listitem>
213
260
      </varlistentry>
214
261
 
217
264
        >BITS</replaceable></option></term>
218
265
        <listitem>
219
266
          <para>
220
 
            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.
221
269
          </para>
222
270
        </listitem>
223
271
      </varlistentry>
226
274
        <term><option>--debug</option></term>
227
275
        <listitem>
228
276
          <para>
229
 
            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.
230
285
          </para>
231
286
        </listitem>
232
287
      </varlistentry>
236
291
        <term><option>-?</option></term>
237
292
        <listitem>
238
293
          <para>
239
 
            Gives a help message
 
294
            Gives a help message about options and their meanings.
240
295
          </para>
241
296
        </listitem>
242
297
      </varlistentry>
245
300
        <term><option>--usage</option></term>
246
301
        <listitem>
247
302
          <para>
248
 
            Gives a short usage message
 
303
            Gives a short usage message.
249
304
          </para>
250
305
        </listitem>
251
306
      </varlistentry>
255
310
        <term><option>-V</option></term>
256
311
        <listitem>
257
312
          <para>
258
 
            Prints the program version
 
313
            Prints the program version.
259
314
          </para>
260
315
        </listitem>
261
316
      </varlistentry>
262
317
    </variablelist>
263
318
  </refsect1>
264
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
  
265
339
  <refsect1 id="exit_status">
266
340
    <title>EXIT STATUS</title>
267
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.
268
349
    </para>
269
350
  </refsect1>
270
 
 
 
351
  
271
352
  <refsect1 id="environment">
272
353
    <title>ENVIRONMENT</title>
273
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>.
274
359
    </para>
275
360
  </refsect1>
276
 
 
 
361
  
277
362
  <refsect1 id="file">
278
363
    <title>FILES</title>
279
364
    <para>
324
409
      
325
410
      <listitem><para>
326
411
        <ulink
327
 
        url="http://www.gnupg.org/related_software/gpgme/">
328
 
        GPGME</ulink>
 
412
        url="http://www.gnupg.org/related_software/gpgme/"
 
413
        >GPGME</ulink>
329
414
      </para></listitem>
330
415
      
331
416
      <listitem><para>