/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 mandos.xml

  • Committer: Teddy Hogeborn
  • Date: 2008-08-17 06:01:58 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080817060158-o5xakkih6t3br9yq
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
            GPGME_CFLAGS, GPGME_LIBS): New; use libgnutls-config,
                                       pkg-config, and gpgme-config to
                                       get the correct compiler and
                                       linker flags.
  (MANPOST): New post-processing stage to man pages to fix a bug with
             having "\n" in the DocBook pages.
  (objects): Use $(addsuffix) instead of a for loop in a subshell.
  (plugin-runner, plugins.d/password-prompt): Removed; targets no
                                              longer necessary.
  (.PHONY): Added "doc".

* mandos.xml: Much improved.

* plugins.d/password-request.xml: Improved SEE ALSO section.

Show diffs side-by-side

added added

removed removed

Lines of Context:
mandos.xml
31
31
    </authorgroup>
32
32
    <copyright>
33
33
      <year>2008</year>
34
 
      <holder>Teddy Hogeborn &amp; Björn Påhlsson</holder>
 
34
      <holder>Teddy Hogeborn</holder>
 
35
      <holder>Björn Påhlsson</holder>
35
36
    </copyright>
36
37
    <legalnotice>
37
38
      <para>
66
67
  <refnamediv>
67
68
    <refname><command>&COMMANDNAME;</command></refname>
68
69
    <refpurpose>
69
 
      Sends encrypted passwords to authenticated mandos clients
 
70
      Sends encrypted passwords to authenticated Mandos clients
70
71
    </refpurpose>
71
72
  </refnamediv>
72
73
 
83
84
    </cmdsynopsis>
84
85
    <cmdsynopsis>
85
86
      <command>&COMMANDNAME;</command>
 
87
      <arg choice='opt'>-i<arg choice='plain'>IF</arg></arg>
 
88
      <arg choice='opt'>-a<arg choice='plain'>ADDRESS</arg></arg>
 
89
      <arg choice='opt'>-p<arg choice='plain'>PORT</arg></arg>
 
90
      <arg choice='opt'>--priority<arg choice='plain'>PRIORITY</arg></arg>
 
91
      <arg choice='opt'>--servicename<arg choice='plain'>NAME</arg></arg>
 
92
      <arg choice='opt'>--configdir<arg choice='plain'>DIRECTORY</arg></arg>
 
93
      <arg choice='opt'>--debug</arg>
 
94
    </cmdsynopsis>
 
95
    <cmdsynopsis>
 
96
      <command>&COMMANDNAME;</command>
86
97
      <arg choice='plain'>--help</arg>
87
98
    </cmdsynopsis>
88
99
    <cmdsynopsis>
98
109
  <refsect1 id="description">
99
110
    <title>DESCRIPTION</title>
100
111
    <para>
101
 
      <command>&COMMANDNAME;</command> is a server daemon that handels
102
 
      incomming passwords request for passwords. Mandos use avahi to
103
 
      announce the service, and through gnutls authenticates
104
 
      clients. Any authenticated client is then given its encrypted
105
 
      password.
106
 
    </para>
 
112
      <command>&COMMANDNAME;</command> is a server daemon which
 
113
      handles incoming request for passwords for a pre-defined list of
 
114
      client host computers.  The Mandos server uses Zeroconf to
 
115
      announce itself on the local network, and uses GnuTLS to
 
116
      communicate securely with and to authenticate the clients.
 
117
      Mandos uses IPv6 link-local addresses, since the clients are
 
118
      assumed to not have any other addresses configured yet.  Any
 
119
      authenticated client is then given the pre-encrypted password
 
120
      for that specific client.
 
121
    </para>
 
122
 
 
123
  </refsect1>  
 
124
  
 
125
  <refsect1 id="purpose">
 
126
    <title>PURPOSE</title>
 
127
 
 
128
    <para>
 
129
      The purpose of this is to enable <emphasis>remote and unattended
 
130
      rebooting</emphasis> of any client host computer with an
 
131
      <emphasis>encrypted root file system</emphasis>.  The client
 
132
      host computer should start a Mandos client in the initial RAM
 
133
      disk environment, the Mandos client program communicates with
 
134
      this server program to get an encrypted password, which is then
 
135
      decrypted and used to unlock the encrypted root file system.
 
136
      The client host computer can then continue its boot sequence
 
137
      normally.
 
138
    </para>
 
139
 
 
140
  </refsect1>  
 
141
  
 
142
  <refsect1 id="options">
 
143
    <title>OPTIONS</title>
107
144
 
108
145
    <variablelist>
109
146
      <varlistentry>
110
147
        <term><literal>-h</literal>, <literal>--help</literal></term>
111
148
        <listitem>
112
149
          <para>
113
 
            show a help message and exit
 
150
            Show a help message and exit
114
151
          </para>
115
152
        </listitem>
116
153
      </varlistentry>
120
157
        IF</replaceable></literal></term>
121
158
        <listitem>
122
159
          <para>
123
 
            Bind to interface IF
 
160
            Only announce the server and listen to requests on network
 
161
            interface <replaceable>IF</replaceable>.  Default is to
 
162
            use all available interfaces.
124
163
          </para>
125
164
        </listitem>
126
165
      </varlistentry>      
130
169
        ADDRESS</replaceable></literal></term>
131
170
        <listitem>
132
171
          <para>
133
 
            Address to listen for requests on
 
172
            If this option is used, the server will only listen to a
 
173
            specific address.  This must currently be an IPv6 address;
 
174
            an IPv4 address can be specified using the
 
175
            "<literal>::FFFF:192.0.2.3</literal>" syntax.  Also, if a
 
176
            link-local address is specified, an interface should be
 
177
            set, since a link-local address is only valid on a single
 
178
            interface.  By default, the server will listen to all
 
179
            available addresses.
134
180
          </para>
135
181
        </listitem>
136
182
      </varlistentry>          
140
186
        PORT</replaceable></literal></term>
141
187
        <listitem>
142
188
          <para>
143
 
            Port number to receive requests on
 
189
            If this option is used, the server to bind to that
 
190
            port. By default, the server will listen to an arbitrary
 
191
            port given by the operating system.
144
192
          </para>
145
193
        </listitem>
146
194
      </varlistentry>          
149
197
        <term><literal>--check</literal></term>
150
198
        <listitem>
151
199
          <para>
152
 
            Run self-test on the server
 
200
            Run the server's self-tests.  This includes any unit
 
201
            tests, etc.
153
202
          </para>
154
203
        </listitem>
155
204
      </varlistentry>      
158
207
        <term><literal>--debug</literal></term>
159
208
        <listitem>
160
209
          <para>
161
 
            Debug mode
 
210
            If the server is run in debug mode, it will run in the
 
211
            foreground and print a lot of debugging information.  The
 
212
            default is <emphasis>not</emphasis> to run in debug mode.
162
213
          </para>
163
214
        </listitem>
164
215
      </varlistentry>
168
219
        PRIORITY</replaceable></literal></term>
169
220
        <listitem>
170
221
          <para>
171
 
            GnuTLS priority string. See <citerefentry>
172
 
            <refentrytitle>gnutls_priority_init</refentrytitle>
173
 
            <manvolnum>3</manvolnum></citerefentry>
 
222
            GnuTLS priority string for the TLS handshake with the
 
223
            clients.  See
 
224
            <citerefentry><refentrytitle>gnutls_priority_init
 
225
            </refentrytitle><manvolnum>3</manvolnum></citerefentry>
 
226
            for the syntax.  The default is
 
227
            "<literal>SECURE256:!CTYPE-X.509:+CTYPE-OPENPGP</literal>".
 
228
            <emphasis>Warning</emphasis>: changing this may make the
 
229
            TLS handshake fail, making communication with clients
 
230
            impossible.
174
231
          </para>
175
232
        </listitem>
176
233
      </varlistentry>      
180
237
        </literal></term>
181
238
        <listitem>
182
239
          <para>
183
 
            Zeroconf service name
 
240
            Zeroconf service name.  The default is
 
241
            "<literal>Mandos</literal>".  You only need to change this
 
242
            if you for some reason want to run more than one server on
 
243
            the same <emphasis>host</emphasis>.  If there are name
 
244
            collisions on the same <emphasis>network</emphasis>, the
 
245
            new server will automatically rename itself to "Mandos
 
246
            #2", etc.
184
247
          </para>
185
248
        </listitem>
186
249
      </varlistentry>     
190
253
        </literal></term>
191
254
        <listitem>
192
255
          <para>
193
 
            Directory to search for configuration files
 
256
            Directory to search for configuration files.  Default is
 
257
            "<literal>/etc/mandos</literal>".  See <citerefentry>
 
258
            <refentrytitle>mandos.conf</refentrytitle>
 
259
            <manvolnum>5</manvolnum></citerefentry> and <citerefentry>
 
260
            <refentrytitle>mandos-clients.conf</refentrytitle>
 
261
            <manvolnum>5</manvolnum></citerefentry>.
194
262
          </para>
195
263
        </listitem>
196
264
      </varlistentry>
199
267
        <term><literal>--version</literal></term>
200
268
        <listitem>
201
269
          <para>
202
 
            Prints the program version
 
270
            Prints the program version and exit.
203
271
          </para>
204
272
        </listitem>
205
273
      </varlistentry>      
206
 
      
207
274
    </variablelist>
208
275
  </refsect1>
 
276
 
 
277
  <refsect1 id="protocol">
 
278
    <title>NETWORK PROTOCOL</title>
 
279
    <para>
 
280
      The Mandos server announces itself as a Zeroconf service of type
 
281
      "<literal>_mandos._tcp</literal>".  The Mandos client connects
 
282
      to the announced address and port, and sends a line of text
 
283
      where the first whitespace-separated field is the protocol
 
284
      version, which currently is "<literal>1</literal>".  The client
 
285
      and server then start a TLS protocol handshake with a slight
 
286
      quirk: the Mandos server program acts as a TLS "client" while
 
287
      the connecting Mandos client acts as a TLS "server".  The Mandos
 
288
      client must supply an OpenPGP certificate, and the fingerprint
 
289
      of this certificate is used by the Mandos server to look up (in
 
290
      a list read from a file at start time) which binary blob to give
 
291
      the client.  No other authentication or authorization is done by
 
292
      the server.
 
293
    </para>
 
294
    <informaltable><tgroup cols="3"><thead>
 
295
      <row>
 
296
        <entry>Mandos Client</entry>
 
297
        <entry>Direction</entry>
 
298
        <entry>Mandos Server</entry>
 
299
      </row>
 
300
      </thead><tbody>
 
301
      <row>
 
302
        <entry>Connect</entry>
 
303
        <entry>-><!-- &rarr; --></entry>
 
304
      </row>
 
305
      <row>
 
306
        <entry>"<literal>1\r\en</literal>"</entry>
 
307
        <entry>-><!-- &rarr; --></entry>
 
308
      </row>
 
309
      <row>
 
310
        <entry>TLS handshake</entry>
 
311
        <entry>&lt;-><!-- &xharr; --></entry>
 
312
        <entry>TLS handshake</entry>
 
313
      </row>
 
314
      <row>
 
315
        <entry>OpenPGP public key (part of TLS handshake)</entry>
 
316
        <entry>-><!-- &rarr; --></entry>
 
317
      </row>
 
318
      <row>
 
319
        <entry/>
 
320
        <entry>&lt;-<!-- &larr; --></entry>
 
321
        <entry>Binary blob</entry>
 
322
      </row>
 
323
      <row>
 
324
        <entry/>
 
325
        <entry>&lt;-<!-- &larr; --></entry>
 
326
        <entry>Close</entry>
 
327
      </row>
 
328
    </tbody></tgroup></informaltable>
 
329
  </refsect1>
 
330
 
 
331
  <refsect1 id="logging">
 
332
    <title>LOGGING</title>
 
333
    <para>
 
334
      The server will log a lot of information with various severity
 
335
      levels to
 
336
      <citerefentry><refentrytitle>syslog</refentrytitle>
 
337
      <manvolnum>8</manvolnum></citerefentry>.  With the
 
338
      <option>--debug</option> option, it will log even more messages,
 
339
      and also show them on the console.
 
340
    </para>
 
341
  </refsect1>
 
342
 
 
343
  <refsect1 id="exit_status">
 
344
    <title>EXIT STATUS</title>
 
345
    <para>
 
346
      The server will exit with a non-zero exit status only when a
 
347
      critical error is encountered.
 
348
    </para>
 
349
  </refsect1>
 
350
 
 
351
  <refsect1 id="file">
 
352
    <title>FILES</title>
 
353
    <para>
 
354
      <itemizedlist>
 
355
        <listitem><para>
 
356
          <filename>/etc/mandos/mandos.conf</filename>  See <citerefentry>
 
357
            <refentrytitle>mandos.conf</refentrytitle>
 
358
            <manvolnum>5</manvolnum></citerefentry>.
 
359
        </para></listitem>
 
360
        <listitem><para>
 
361
          <filename>/etc/mandos/clients.conf</filename> See <citerefentry>
 
362
            <refentrytitle>mandos-clients.conf</refentrytitle>
 
363
            <manvolnum>5</manvolnum></citerefentry>.
 
364
        </para></listitem>
 
365
        <listitem><para>
 
366
          <filename>/var/run/mandos/mandos.pid</filename>
 
367
        </para></listitem>
 
368
      </itemizedlist>
 
369
    </para>
 
370
  </refsect1>  
 
371
 
 
372
  <refsect1 id="bugs">
 
373
    <title>BUGS</title>
 
374
    <para>
 
375
    </para>
 
376
  </refsect1>  
 
377
 
 
378
  <refsect1 id="examples">
 
379
    <title>EXAMPLES</title>
 
380
    <para>
 
381
    </para>
 
382
  </refsect1>
 
383
 
 
384
  <refsect1 id="security">
 
385
    <title>SECURITY</title>
 
386
    <para>
 
387
    </para>
 
388
  </refsect1>
 
389
 
 
390
  <refsect1 id="see_also">
 
391
    <title>SEE ALSO</title>
 
392
    <itemizedlist spacing="compact">
 
393
      <listitem><para>
 
394
        <citerefentry><refentrytitle>password-request</refentrytitle>
 
395
        <manvolnum>8mandos</manvolnum></citerefentry>
 
396
      </para></listitem>
 
397
      
 
398
      <listitem><para>
 
399
        <citerefentry><refentrytitle>plugin-runner</refentrytitle>
 
400
        <manvolnum>8mandos</manvolnum></citerefentry>
 
401
      </para></listitem>
 
402
      
 
403
      <listitem><para>
 
404
        <ulink url="http://www.zeroconf.org/">Zeroconf</ulink>
 
405
      </para></listitem>
 
406
      
 
407
      <listitem><para>
 
408
        <ulink url="http://www.avahi.org/">Avahi</ulink>
 
409
      </para></listitem>
 
410
      
 
411
      <listitem><para>
 
412
        <ulink
 
413
            url="http://www.gnu.org/software/gnutls/">GnuTLS</ulink>
 
414
      </para></listitem>
 
415
      
 
416
      <listitem><para>
 
417
        <citation>RFC 4880: <citetitle>OpenPGP Message
 
418
        Format</citetitle></citation>
 
419
      </para></listitem>
 
420
      
 
421
      <listitem><para>
 
422
        <citation>RFC 5081: <citetitle>Using OpenPGP Keys for
 
423
        Transport Layer Security</citetitle></citation>
 
424
      </para></listitem>
 
425
      
 
426
      <listitem><para>
 
427
        <citation>RFC 4291: <citetitle>IP Version 6 Addressing
 
428
        Architecture</citetitle>, section 2.5.6, Link-Local IPv6
 
429
        Unicast Addresses</citation>
 
430
      </para></listitem>
 
431
    </itemizedlist>
 
432
  </refsect1>
209
433
</refentry>