/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 06:03:08 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080902060308-8uhgsfjiwixuvz6j
* plugin-runner.c (main/parse_opt): Removed code for "--config-file".
  (main/parse_opt_config_file): New function only for "--config-file".
  (main): Parse options first using "parse_opt_config_file", then from
          the config file, and lastly from the command line.

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-09-03">
 
6
<!ENTITY TIMESTAMP "2008-08-31">
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 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.
 
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.
155
132
    </para>
156
133
  </refsect1>
157
134
  
158
135
  <refsect1 id="options">
159
136
    <title>OPTIONS</title>
160
137
    <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.
 
138
      Commonly not invoked as command lines but from configuration
 
139
      file of plugin runner.
168
140
    </para>
169
 
    
 
141
 
170
142
    <variablelist>
171
143
      <varlistentry>
172
144
        <term><option>--connect=<replaceable
173
 
        >ADDRESS</replaceable><literal>:</literal><replaceable
 
145
        >IPADDR</replaceable><literal>:</literal><replaceable
174
146
        >PORT</replaceable></option></term>
175
147
        <term><option>-c
176
 
        <replaceable>ADDRESS</replaceable><literal>:</literal
 
148
        <replaceable>IPADDR</replaceable><literal>:</literal
177
149
        ><replaceable>PORT</replaceable></option></term>
178
150
        <listitem>
179
151
          <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.
 
152
            Connect directly to a specified mandos server
189
153
          </para>
190
154
        </listitem>
191
155
      </varlistentry>
192
 
      
 
156
 
193
157
      <varlistentry>
194
158
        <term><option>--keydir=<replaceable
195
159
        >DIRECTORY</replaceable></option></term>
197
161
        <replaceable>DIRECTORY</replaceable></option></term>
198
162
        <listitem>
199
163
          <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).
 
164
            Directory where the openpgp keyring is
205
165
          </para>
206
166
        </listitem>
207
167
      </varlistentry>
213
173
        <replaceable>NAME</replaceable></option></term>
214
174
        <listitem>
215
175
          <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>.
 
176
            Interface that Avahi will connect through
219
177
          </para>
220
178
        </listitem>
221
179
      </varlistentry>
222
 
      
 
180
 
223
181
      <varlistentry>
224
182
        <term><option>--pubkey=<replaceable
225
183
        >FILE</replaceable></option></term>
227
185
        <replaceable>FILE</replaceable></option></term>
228
186
        <listitem>
229
187
          <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>.
 
188
            Public openpgp key for gnutls authentication
234
189
          </para>
235
190
        </listitem>
236
191
      </varlistentry>
242
197
        <replaceable>FILE</replaceable></option></term>
243
198
        <listitem>
244
199
          <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>.
 
200
            Secret OpenPGP key for GnuTLS authentication
249
201
          </para>
250
202
        </listitem>
251
203
      </varlistentry>
254
206
        <term><option>--priority=<replaceable
255
207
        >STRING</replaceable></option></term>
256
208
        <listitem>
257
 
          <xi:include href="../mandos-options.xml"
258
 
                      xpointer="priority"/>
 
209
          <para>
 
210
            GnuTLS priority
 
211
          </para>
259
212
        </listitem>
260
213
      </varlistentry>
261
214
 
264
217
        >BITS</replaceable></option></term>
265
218
        <listitem>
266
219
          <para>
267
 
            Sets the number of bits to use for the prime number in the
268
 
            TLS Diffie-Hellman key exchange.  Default is 1024.
 
220
            DH bits to use in gnutls communication
269
221
          </para>
270
222
        </listitem>
271
223
      </varlistentry>
274
226
        <term><option>--debug</option></term>
275
227
        <listitem>
276
228
          <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.
 
229
            Debug mode
285
230
          </para>
286
231
        </listitem>
287
232
      </varlistentry>
291
236
        <term><option>-?</option></term>
292
237
        <listitem>
293
238
          <para>
294
 
            Gives a help message about options and their meanings.
 
239
            Gives a help message
295
240
          </para>
296
241
        </listitem>
297
242
      </varlistentry>
300
245
        <term><option>--usage</option></term>
301
246
        <listitem>
302
247
          <para>
303
 
            Gives a short usage message.
 
248
            Gives a short usage message
304
249
          </para>
305
250
        </listitem>
306
251
      </varlistentry>
310
255
        <term><option>-V</option></term>
311
256
        <listitem>
312
257
          <para>
313
 
            Prints the program version.
 
258
            Prints the program version
314
259
          </para>
315
260
        </listitem>
316
261
      </varlistentry>
317
262
    </variablelist>
318
263
  </refsect1>
319
264
 
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 a password for the encrypted root disk at
333
 
      the console, since this program does not read from the console
334
 
      at all.  This is why a separate plugin does that, which will be
335
 
      run in parallell to this one by the plugin runner.
336
 
    </para>
337
 
  </refsect1>
338
 
  
339
265
  <refsect1 id="exit_status">
340
266
    <title>EXIT STATUS</title>
341
267
    <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>Mandos</application> servers as they appear, trying
348
 
      to get a decryptable password.
349
268
    </para>
350
269
  </refsect1>
351
 
  
 
270
 
352
271
  <refsect1 id="environment">
353
272
    <title>ENVIRONMENT</title>
354
273
    <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
274
    </para>
360
275
  </refsect1>
361
 
  
 
276
 
362
277
  <refsect1 id="file">
363
278
    <title>FILES</title>
364
279
    <para>
409
324
      
410
325
      <listitem><para>
411
326
        <ulink
412
 
        url="http://www.gnupg.org/related_software/gpgme/"
413
 
        >GPGME</ulink>
 
327
        url="http://www.gnupg.org/related_software/gpgme/">
 
328
        GPGME</ulink>
414
329
      </para></listitem>
415
330
      
416
331
      <listitem><para>