/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-12-28 10:20:47 UTC
  • Revision ID: teddy@fukt.bsnet.se-20081228102047-1fhyj7oqxfdo44d2
* Makefile: Bug fix for Debian bug #509398; make sure "-z relro" is
            passed to linker, not C compiler.

Show diffs side-by-side

added added

removed removed

Lines of Context:
mandos.xml
1
1
<?xml version="1.0" encoding="UTF-8"?>
2
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3
3
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4
 
<!ENTITY VERSION "1.0">
5
4
<!ENTITY COMMANDNAME "mandos">
6
 
<!ENTITY TIMESTAMP "2008-08-31">
 
5
<!ENTITY TIMESTAMP "2008-10-03">
 
6
<!ENTITY % common SYSTEM "common.ent">
 
7
%common;
7
8
]>
8
9
 
9
10
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
10
 
  <refentryinfo>
 
11
   <refentryinfo>
11
12
    <title>Mandos Manual</title>
12
13
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
13
14
    <productname>Mandos</productname>
14
 
    <productnumber>&VERSION;</productnumber>
 
15
    <productnumber>&version;</productnumber>
15
16
    <date>&TIMESTAMP;</date>
16
17
    <authorgroup>
17
18
      <author>
34
35
      <holder>Teddy Hogeborn</holder>
35
36
      <holder>Björn Påhlsson</holder>
36
37
    </copyright>
37
 
    <legalnotice>
38
 
      <para>
39
 
        This manual page is free software: you can redistribute it
40
 
        and/or modify it under the terms of the GNU General Public
41
 
        License as published by the Free Software Foundation,
42
 
        either version 3 of the License, or (at your option) any
43
 
        later version.
44
 
      </para>
45
 
 
46
 
      <para>
47
 
        This manual page is distributed in the hope that it will
48
 
        be useful, but WITHOUT ANY WARRANTY; without even the
49
 
        implied warranty of MERCHANTABILITY or FITNESS FOR A
50
 
        PARTICULAR PURPOSE.  See the GNU General Public License
51
 
        for more details.
52
 
      </para>
53
 
 
54
 
      <para>
55
 
        You should have received a copy of the GNU General Public
56
 
        License along with this program; If not, see
57
 
        <ulink url="http://www.gnu.org/licenses/"/>.
58
 
      </para>
59
 
    </legalnotice>
 
38
    <xi:include href="legalnotice.xml"/>
60
39
  </refentryinfo>
61
 
 
 
40
  
62
41
  <refmeta>
63
42
    <refentrytitle>&COMMANDNAME;</refentrytitle>
64
43
    <manvolnum>8</manvolnum>
70
49
      Gives encrypted passwords to authenticated Mandos clients
71
50
    </refpurpose>
72
51
  </refnamediv>
73
 
 
 
52
  
74
53
  <refsynopsisdiv>
75
54
    <cmdsynopsis>
76
55
      <command>&COMMANDNAME;</command>
122
101
      <arg choice="plain"><option>--check</option></arg>
123
102
    </cmdsynopsis>
124
103
  </refsynopsisdiv>
125
 
 
 
104
  
126
105
  <refsect1 id="description">
127
106
    <title>DESCRIPTION</title>
128
107
    <para>
137
116
      Any authenticated client is then given the stored pre-encrypted
138
117
      password for that specific client.
139
118
    </para>
140
 
 
141
119
  </refsect1>
142
120
  
143
121
  <refsect1 id="purpose">
144
122
    <title>PURPOSE</title>
145
 
 
146
123
    <para>
147
124
      The purpose of this is to enable <emphasis>remote and unattended
148
125
      rebooting</emphasis> of client host computer with an
149
126
      <emphasis>encrypted root file system</emphasis>.  See <xref
150
127
      linkend="overview"/> for details.
151
128
    </para>
152
 
 
153
129
  </refsect1>
154
130
  
155
131
  <refsect1 id="options">
156
132
    <title>OPTIONS</title>
157
 
 
158
133
    <variablelist>
159
134
      <varlistentry>
 
135
        <term><option>--help</option></term>
160
136
        <term><option>-h</option></term>
161
 
        <term><option>--help</option></term>
162
137
        <listitem>
163
138
          <para>
164
139
            Show a help message and exit
165
140
          </para>
166
141
        </listitem>
167
142
      </varlistentry>
168
 
 
 
143
      
169
144
      <varlistentry>
 
145
        <term><option>--interface</option>
 
146
        <replaceable>NAME</replaceable></term>
170
147
        <term><option>-i</option>
171
148
        <replaceable>NAME</replaceable></term>
172
 
        <term><option>--interface</option>
173
 
        <replaceable>NAME</replaceable></term>
174
149
        <listitem>
175
150
          <xi:include href="mandos-options.xml" xpointer="interface"/>
176
151
        </listitem>
177
152
      </varlistentry>
178
 
 
 
153
      
179
154
      <varlistentry>
180
 
        <term><literal>-a</literal>, <literal>--address <replaceable>
181
 
        ADDRESS</replaceable></literal></term>
 
155
        <term><option>--address
 
156
        <replaceable>ADDRESS</replaceable></option></term>
 
157
        <term><option>-a
 
158
        <replaceable>ADDRESS</replaceable></option></term>
182
159
        <listitem>
183
160
          <xi:include href="mandos-options.xml" xpointer="address"/>
184
161
        </listitem>
185
162
      </varlistentry>
186
 
 
 
163
      
187
164
      <varlistentry>
188
 
        <term><literal>-p</literal>, <literal>--port <replaceable>
189
 
        PORT</replaceable></literal></term>
 
165
        <term><option>--port
 
166
        <replaceable>PORT</replaceable></option></term>
 
167
        <term><option>-p
 
168
        <replaceable>PORT</replaceable></option></term>
190
169
        <listitem>
191
170
          <xi:include href="mandos-options.xml" xpointer="port"/>
192
171
        </listitem>
193
172
      </varlistentry>
194
 
 
 
173
      
195
174
      <varlistentry>
196
 
        <term><literal>--check</literal></term>
 
175
        <term><option>--check</option></term>
197
176
        <listitem>
198
177
          <para>
199
178
            Run the server’s self-tests.  This includes any unit
201
180
          </para>
202
181
        </listitem>
203
182
      </varlistentry>
204
 
 
 
183
      
205
184
      <varlistentry>
206
 
        <term><literal>--debug</literal></term>
 
185
        <term><option>--debug</option></term>
207
186
        <listitem>
208
187
          <xi:include href="mandos-options.xml" xpointer="debug"/>
209
188
        </listitem>
210
189
      </varlistentry>
211
 
 
 
190
      
212
191
      <varlistentry>
213
 
        <term><literal>--priority <replaceable>
214
 
        PRIORITY</replaceable></literal></term>
 
192
        <term><option>--priority <replaceable>
 
193
        PRIORITY</replaceable></option></term>
215
194
        <listitem>
216
195
          <xi:include href="mandos-options.xml" xpointer="priority"/>
217
196
        </listitem>
218
197
      </varlistentry>
219
 
 
 
198
      
220
199
      <varlistentry>
221
 
        <term><literal>--servicename <replaceable>NAME</replaceable>
222
 
        </literal></term>
 
200
        <term><option>--servicename
 
201
        <replaceable>NAME</replaceable></option></term>
223
202
        <listitem>
224
203
          <xi:include href="mandos-options.xml"
225
204
                      xpointer="servicename"/>
226
205
        </listitem>
227
206
      </varlistentry>
228
 
 
 
207
      
229
208
      <varlistentry>
230
 
        <term><literal>--configdir <replaceable>DIR</replaceable>
231
 
        </literal></term>
 
209
        <term><option>--configdir
 
210
        <replaceable>DIRECTORY</replaceable></option></term>
232
211
        <listitem>
233
212
          <para>
234
213
            Directory to search for configuration files.  Default is
240
219
          </para>
241
220
        </listitem>
242
221
      </varlistentry>
243
 
 
 
222
      
244
223
      <varlistentry>
245
 
        <term><literal>--version</literal></term>
 
224
        <term><option>--version</option></term>
246
225
        <listitem>
247
226
          <para>
248
227
            Prints the program version and exit.
251
230
      </varlistentry>
252
231
    </variablelist>
253
232
  </refsect1>
254
 
 
 
233
  
255
234
  <refsect1 id="overview">
256
235
    <title>OVERVIEW</title>
257
236
    <xi:include href="overview.xml"/>
258
237
    <para>
259
238
      This program is the server part.  It is a normal server program
260
239
      and will run in a normal system environment, not in an initial
261
 
      RAM disk environment.
 
240
      <acronym>RAM</acronym> disk environment.
262
241
    </para>
263
242
  </refsect1>
264
 
 
 
243
  
265
244
  <refsect1 id="protocol">
266
245
    <title>NETWORK PROTOCOL</title>
267
246
    <para>
319
298
      </row>
320
299
    </tbody></tgroup></table>
321
300
  </refsect1>
322
 
 
 
301
  
323
302
  <refsect1 id="checking">
324
303
    <title>CHECKING</title>
325
304
    <para>
333
312
      <manvolnum>5</manvolnum></citerefentry>.
334
313
    </para>
335
314
  </refsect1>
336
 
 
 
315
  
337
316
  <refsect1 id="logging">
338
317
    <title>LOGGING</title>
339
318
    <para>
343
322
      and also show them on the console.
344
323
    </para>
345
324
  </refsect1>
346
 
 
 
325
  
347
326
  <refsect1 id="exit_status">
348
327
    <title>EXIT STATUS</title>
349
328
    <para>
351
330
      critical error is encountered.
352
331
    </para>
353
332
  </refsect1>
354
 
 
 
333
  
355
334
  <refsect1 id="environment">
356
335
    <title>ENVIRONMENT</title>
357
336
    <variablelist>
371
350
      </varlistentry>
372
351
    </variablelist>
373
352
  </refsect1>
374
 
 
375
 
  <refsect1 id="file">
 
353
  
 
354
  <refsect1 id="files">
376
355
    <title>FILES</title>
377
356
    <para>
378
357
      Use the <option>--configdir</option> option to change where
401
380
        </listitem>
402
381
      </varlistentry>
403
382
      <varlistentry>
404
 
        <term><filename>/var/run/mandos/mandos.pid</filename></term>
 
383
        <term><filename>/var/run/mandos.pid</filename></term>
405
384
        <listitem>
406
385
          <para>
407
386
            The file containing the process id of
442
421
      Currently, if a client is declared <quote>invalid</quote> due to
443
422
      having timed out, the server does not record this fact onto
444
423
      permanent storage.  This has some security implications, see
445
 
      <xref linkend="CLIENTS"/>.
 
424
      <xref linkend="clients"/>.
446
425
    </para>
447
426
    <para>
448
427
      There is currently no way of querying the server of the current
456
435
      Debug mode is conflated with running in the foreground.
457
436
    </para>
458
437
    <para>
459
 
      The console log messages does not show a timestamp.
 
438
      The console log messages does not show a time stamp.
 
439
    </para>
 
440
    <para>
 
441
      This server does not check the expire time of clients’ OpenPGP
 
442
      keys.
460
443
    </para>
461
444
  </refsect1>
462
445
  
497
480
      </para>
498
481
    </informalexample>
499
482
  </refsect1>
500
 
 
 
483
  
501
484
  <refsect1 id="security">
502
485
    <title>SECURITY</title>
503
 
    <refsect2 id="SERVER">
 
486
    <refsect2 id="server">
504
487
      <title>SERVER</title>
505
488
      <para>
506
489
        Running this <command>&COMMANDNAME;</command> server program
507
490
        should not in itself present any security risk to the host
508
 
        computer running it.  The program does not need any special
509
 
        privileges to run, and is designed to run as a non-root user.
 
491
        computer running it.  The program switches to a non-root user
 
492
        soon after startup.
510
493
      </para>
511
494
    </refsect2>
512
 
    <refsect2 id="CLIENTS">
 
495
    <refsect2 id="clients">
513
496
      <title>CLIENTS</title>
514
497
      <para>
515
498
        The server only gives out its stored data to clients which
522
505
        <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
523
506
        <manvolnum>5</manvolnum></citerefentry>)
524
507
        <emphasis>must</emphasis> be made non-readable by anyone
525
 
        except the user running the server.
 
508
        except the user starting the server (usually root).
526
509
      </para>
527
510
      <para>
528
511
        As detailed in <xref linkend="checking"/>, the status of all
539
522
        restarting servers if it is suspected that a client has, in
540
523
        fact, been compromised by parties who may now be running a
541
524
        fake Mandos client with the keys from the non-encrypted
542
 
        initial RAM image of the client host.  What should be done in
543
 
        that case (if restarting the server program really is
544
 
        necessary) is to stop the server program, edit the
 
525
        initial <acronym>RAM</acronym> image of the client host.  What
 
526
        should be done in that case (if restarting the server program
 
527
        really is necessary) is to stop the server program, edit the
545
528
        configuration file to omit any suspect clients, and restart
546
529
        the server program.
547
530
      </para>
548
531
      <para>
549
532
        For more details on client-side security, see
550
 
        <citerefentry><refentrytitle>password-request</refentrytitle>
 
533
        <citerefentry><refentrytitle>mandos-client</refentrytitle>
551
534
        <manvolnum>8mandos</manvolnum></citerefentry>.
552
535
      </para>
553
536
    </refsect2>
554
537
  </refsect1>
555
 
 
 
538
  
556
539
  <refsect1 id="see_also">
557
540
    <title>SEE ALSO</title>
558
541
    <para>
561
544
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
562
545
        <refentrytitle>mandos.conf</refentrytitle>
563
546
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
564
 
        <refentrytitle>password-request</refentrytitle>
 
547
        <refentrytitle>mandos-client</refentrytitle>
565
548
        <manvolnum>8mandos</manvolnum></citerefentry>, <citerefentry>
566
549
        <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
567
550
      </citerefentry>