/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
 
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
 
107
140
  </refsect1>  
108
141
  
109
142
  <refsect1 id="options">
114
147
        <term><literal>-h</literal>, <literal>--help</literal></term>
115
148
        <listitem>
116
149
          <para>
117
 
            show a help message and exit
 
150
            Show a help message and exit
118
151
          </para>
119
152
        </listitem>
120
153
      </varlistentry>
124
157
        IF</replaceable></literal></term>
125
158
        <listitem>
126
159
          <para>
127
 
            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.
128
163
          </para>
129
164
        </listitem>
130
165
      </varlistentry>      
134
169
        ADDRESS</replaceable></literal></term>
135
170
        <listitem>
136
171
          <para>
137
 
            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.
138
180
          </para>
139
181
        </listitem>
140
182
      </varlistentry>          
144
186
        PORT</replaceable></literal></term>
145
187
        <listitem>
146
188
          <para>
147
 
            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.
148
192
          </para>
149
193
        </listitem>
150
194
      </varlistentry>          
153
197
        <term><literal>--check</literal></term>
154
198
        <listitem>
155
199
          <para>
156
 
            Run self-test on the server
 
200
            Run the server's self-tests.  This includes any unit
 
201
            tests, etc.
157
202
          </para>
158
203
        </listitem>
159
204
      </varlistentry>      
162
207
        <term><literal>--debug</literal></term>
163
208
        <listitem>
164
209
          <para>
165
 
            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.
166
213
          </para>
167
214
        </listitem>
168
215
      </varlistentry>
172
219
        PRIORITY</replaceable></literal></term>
173
220
        <listitem>
174
221
          <para>
175
 
            GnuTLS priority string. See <citerefentry>
176
 
            <refentrytitle>gnutls_priority_init</refentrytitle>
177
 
            <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.
178
231
          </para>
179
232
        </listitem>
180
233
      </varlistentry>      
184
237
        </literal></term>
185
238
        <listitem>
186
239
          <para>
187
 
            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.
188
247
          </para>
189
248
        </listitem>
190
249
      </varlistentry>     
194
253
        </literal></term>
195
254
        <listitem>
196
255
          <para>
197
 
            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>.
198
262
          </para>
199
263
        </listitem>
200
264
      </varlistentry>
203
267
        <term><literal>--version</literal></term>
204
268
        <listitem>
205
269
          <para>
206
 
            Prints the program version
 
270
            Prints the program version and exit.
207
271
          </para>
208
272
        </listitem>
209
273
      </varlistentry>      
210
274
    </variablelist>
211
275
  </refsect1>
212
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
 
213
343
  <refsect1 id="exit_status">
214
344
    <title>EXIT STATUS</title>
215
345
    <para>
 
346
      The server will exit with a non-zero exit status only when a
 
347
      critical error is encountered.
216
348
    </para>
217
349
  </refsect1>
218
350
 
219
351
  <refsect1 id="file">
220
352
    <title>FILES</title>
221
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>
222
369
    </para>
223
370
  </refsect1>  
224
371
 
225
 
  <refsect1 id="notes">
226
 
    <title>NOTES</title>
227
 
    <para>
228
 
    </para>
229
 
  </refsect1>
230
 
  
231
372
  <refsect1 id="bugs">
232
373
    <title>BUGS</title>
233
374
    <para>
248
389
 
249
390
  <refsect1 id="see_also">
250
391
    <title>SEE ALSO</title>
251
 
    <para>
252
 
      <citerefentry><refentrytitle>plugin-runner</refentrytitle>
253
 
      <manvolnum>8mandos</manvolnum></citerefentry>, <citerefentry>
254
 
      <refentrytitle>password-request</refentrytitle>
255
 
      <manvolnum>8mandos</manvolnum></citerefentry> and <citerefentry>
256
 
      <refentrytitle>password-prompt</refentrytitle>
257
 
      <manvolnum>8mandos</manvolnum></citerefentry>
258
 
    </para>
 
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>
259
432
  </refsect1>
260
 
  
261
433
</refentry>