/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 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
 
73
74
  <refsynopsisdiv>
74
75
    <cmdsynopsis>
75
76
      <command>&COMMANDNAME;</command>
76
 
      <arg choice='opt' rep='repeat'>OPTION</arg>
77
 
    </cmdsynopsis>
 
77
      <arg choice='opt'>--interface<arg choice='plain'>IF</arg></arg>
 
78
      <arg choice='opt'>--address<arg choice='plain'>ADDRESS</arg></arg>
 
79
      <arg choice='opt'>--port<arg choice='plain'>PORT</arg></arg>
 
80
      <arg choice='opt'>--priority<arg choice='plain'>PRIORITY</arg></arg>
 
81
      <arg choice='opt'>--servicename<arg choice='plain'>NAME</arg></arg>
 
82
      <arg choice='opt'>--configdir<arg choice='plain'>DIRECTORY</arg></arg>
 
83
      <arg choice='opt'>--debug</arg>
 
84
    </cmdsynopsis>
 
85
    <cmdsynopsis>
 
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>
 
97
      <arg choice='plain'>--help</arg>
 
98
    </cmdsynopsis>
 
99
    <cmdsynopsis>
 
100
      <command>&COMMANDNAME;</command>
 
101
      <arg choice='plain'>--version</arg>
 
102
    </cmdsynopsis>
 
103
    <cmdsynopsis>
 
104
      <command>&COMMANDNAME;</command>
 
105
      <arg choice='plain'>--check</arg>
 
106
    </cmdsynopsis>    
78
107
  </refsynopsisdiv>
79
108
 
80
109
  <refsect1 id="description">
81
110
    <title>DESCRIPTION</title>
82
111
    <para>
83
 
      <command>&COMMANDNAME;</command> is a server daemon that handels
84
 
      incomming passwords request for passwords. Mandos use avahi to
85
 
      announce the service, and through gnutls authenticates
86
 
      clients. Any authenticated client is then given its encrypted
87
 
      password.
88
 
    </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>
89
144
 
90
145
    <variablelist>
91
146
      <varlistentry>
92
147
        <term><literal>-h</literal>, <literal>--help</literal></term>
93
148
        <listitem>
94
149
          <para>
95
 
            show a help message and exit
 
150
            Show a help message and exit
96
151
          </para>
97
152
        </listitem>
98
153
      </varlistentry>
102
157
        IF</replaceable></literal></term>
103
158
        <listitem>
104
159
          <para>
105
 
            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.
106
163
          </para>
107
164
        </listitem>
108
165
      </varlistentry>      
112
169
        ADDRESS</replaceable></literal></term>
113
170
        <listitem>
114
171
          <para>
115
 
            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.
116
180
          </para>
117
181
        </listitem>
118
182
      </varlistentry>          
122
186
        PORT</replaceable></literal></term>
123
187
        <listitem>
124
188
          <para>
125
 
            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.
126
192
          </para>
127
193
        </listitem>
128
194
      </varlistentry>          
131
197
        <term><literal>--check</literal></term>
132
198
        <listitem>
133
199
          <para>
134
 
            Run self-test on the server
 
200
            Run the server's self-tests.  This includes any unit
 
201
            tests, etc.
135
202
          </para>
136
203
        </listitem>
137
204
      </varlistentry>      
140
207
        <term><literal>--debug</literal></term>
141
208
        <listitem>
142
209
          <para>
143
 
            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.
144
213
          </para>
145
214
        </listitem>
146
215
      </varlistentry>
150
219
        PRIORITY</replaceable></literal></term>
151
220
        <listitem>
152
221
          <para>
153
 
            GnuTLS priority string. See <citerefentry>
154
 
            <refentrytitle>gnutls_priority_init</refentrytitle>
155
 
            <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.
156
231
          </para>
157
232
        </listitem>
158
233
      </varlistentry>      
162
237
        </literal></term>
163
238
        <listitem>
164
239
          <para>
165
 
            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.
166
247
          </para>
167
248
        </listitem>
168
249
      </varlistentry>     
172
253
        </literal></term>
173
254
        <listitem>
174
255
          <para>
175
 
            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>.
176
262
          </para>
177
263
        </listitem>
178
264
      </varlistentry>
179
 
      
 
265
 
 
266
      <varlistentry>
 
267
        <term><literal>--version</literal></term>
 
268
        <listitem>
 
269
          <para>
 
270
            Prints the program version and exit.
 
271
          </para>
 
272
        </listitem>
 
273
      </varlistentry>      
180
274
    </variablelist>
181
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>
182
433
</refentry>