/mandos/release

To get this branch, use:
bzr branch http://bzr.recompile.se/loggerhead/mandos/release

« back to all changes in this revision

Viewing changes to plugins.d/password-request.xml

  • Committer: Teddy Hogeborn
  • Date: 2008-09-02 13:04:42 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080902130442-ytnjsmllaph18e20
* plugin-runner.xml (PLUGINS/WRITING PLUGINS): New section.
  (BUGS): Commented out.  There are no bugs.
  (EXAMPLE): Added lots of examples.
  (SECURITY): Added text.
  (SEE ALSO): Added "crypttab(5)" and "execve(2)".

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-02">
 
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 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.
 
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.
173
132
    </para>
174
133
  </refsect1>
175
134
  
176
135
  <refsect1 id="options">
177
136
    <title>OPTIONS</title>
178
137
    <para>
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.
 
138
      Commonly not invoked as command lines but from configuration
 
139
      file of plugin runner.
186
140
    </para>
187
 
    
 
141
 
188
142
    <variablelist>
189
143
      <varlistentry>
190
144
        <term><option>--connect=<replaceable
195
149
        ><replaceable>PORT</replaceable></option></term>
196
150
        <listitem>
197
151
          <para>
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.
 
152
            Connect directly to a specified mandos server
206
153
          </para>
207
154
        </listitem>
208
155
      </varlistentry>
209
 
      
 
156
 
210
157
      <varlistentry>
211
158
        <term><option>--keydir=<replaceable
212
159
        >DIRECTORY</replaceable></option></term>
214
161
        <replaceable>DIRECTORY</replaceable></option></term>
215
162
        <listitem>
216
163
          <para>
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).
 
164
            Directory where the openpgp keyring is
222
165
          </para>
223
166
        </listitem>
224
167
      </varlistentry>
230
173
        <replaceable>NAME</replaceable></option></term>
231
174
        <listitem>
232
175
          <para>
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>.
 
176
            Interface that Avahi will connect through
236
177
          </para>
237
178
        </listitem>
238
179
      </varlistentry>
239
 
      
 
180
 
240
181
      <varlistentry>
241
182
        <term><option>--pubkey=<replaceable
242
183
        >FILE</replaceable></option></term>
244
185
        <replaceable>FILE</replaceable></option></term>
245
186
        <listitem>
246
187
          <para>
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>.
 
188
            Public openpgp key for gnutls authentication
251
189
          </para>
252
190
        </listitem>
253
191
      </varlistentry>
259
197
        <replaceable>FILE</replaceable></option></term>
260
198
        <listitem>
261
199
          <para>
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>.
 
200
            Secret OpenPGP key for GnuTLS authentication
266
201
          </para>
267
202
        </listitem>
268
203
      </varlistentry>
271
206
        <term><option>--priority=<replaceable
272
207
        >STRING</replaceable></option></term>
273
208
        <listitem>
274
 
          <xi:include href="mandos-options.xml" xpointer="priority"/>
 
209
          <para>
 
210
            GnuTLS priority
 
211
          </para>
275
212
        </listitem>
276
213
      </varlistentry>
277
214
 
280
217
        >BITS</replaceable></option></term>
281
218
        <listitem>
282
219
          <para>
283
 
            Sets the number of bits to use for the prime number in the
284
 
            TLS Diffie-Hellman key exchange.  Default is 1024.
 
220
            DH bits to use in gnutls communication
285
221
          </para>
286
222
        </listitem>
287
223
      </varlistentry>
290
226
        <term><option>--debug</option></term>
291
227
        <listitem>
292
228
          <para>
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.
 
229
            Debug mode
301
230
          </para>
302
231
        </listitem>
303
232
      </varlistentry>
307
236
        <term><option>-?</option></term>
308
237
        <listitem>
309
238
          <para>
310
 
            Gives a help message about options and their meanings.
 
239
            Gives a help message
311
240
          </para>
312
241
        </listitem>
313
242
      </varlistentry>
316
245
        <term><option>--usage</option></term>
317
246
        <listitem>
318
247
          <para>
319
 
            Gives a short usage message.
 
248
            Gives a short usage message
320
249
          </para>
321
250
        </listitem>
322
251
      </varlistentry>
326
255
        <term><option>-V</option></term>
327
256
        <listitem>
328
257
          <para>
329
 
            Prints the program version.
 
258
            Prints the program version
330
259
          </para>
331
260
        </listitem>
332
261
      </varlistentry>
336
265
  <refsect1 id="exit_status">
337
266
    <title>EXIT STATUS</title>
338
267
    <para>
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
 
  
 
268
    </para>
 
269
  </refsect1>
 
270
 
 
271
  <refsect1 id="environment">
 
272
    <title>ENVIRONMENT</title>
 
273
    <para>
 
274
    </para>
 
275
  </refsect1>
 
276
 
356
277
  <refsect1 id="file">
357
278
    <title>FILES</title>
358
279
    <para>