/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: 2009-01-04 22:15:01 UTC
  • Revision ID: teddy@fukt.bsnet.se-20090104221501-23vutw4cnmb575rq
* debian/mandos.README.Debian: Updated to reflect code changes.

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-30">
 
5
<!ENTITY TIMESTAMP "2009-01-04">
 
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>
31
32
    </authorgroup>
32
33
    <copyright>
33
34
      <year>2008</year>
 
35
      <year>2009</year>
34
36
      <holder>Teddy Hogeborn</holder>
35
37
      <holder>Björn Påhlsson</holder>
36
38
    </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>
 
39
    <xi:include href="legalnotice.xml"/>
60
40
  </refentryinfo>
61
 
 
 
41
  
62
42
  <refmeta>
63
43
    <refentrytitle>&COMMANDNAME;</refentrytitle>
64
44
    <manvolnum>8</manvolnum>
70
50
      Gives encrypted passwords to authenticated Mandos clients
71
51
    </refpurpose>
72
52
  </refnamediv>
73
 
 
 
53
  
74
54
  <refsynopsisdiv>
75
55
    <cmdsynopsis>
76
56
      <command>&COMMANDNAME;</command>
105
85
      <replaceable>DIRECTORY</replaceable></option></arg>
106
86
      <sbr/>
107
87
      <arg><option>--debug</option></arg>
 
88
      <sbr/>
 
89
      <arg><option>--no-dbus</option></arg>
108
90
    </cmdsynopsis>
109
91
    <cmdsynopsis>
110
92
      <command>&COMMANDNAME;</command>
111
93
      <group choice="req">
 
94
        <arg choice="plain"><option>--help</option></arg>
112
95
        <arg choice="plain"><option>-h</option></arg>
113
 
        <arg choice="plain"><option>--help</option></arg>
114
96
      </group>
115
97
    </cmdsynopsis>
116
98
    <cmdsynopsis>
122
104
      <arg choice="plain"><option>--check</option></arg>
123
105
    </cmdsynopsis>
124
106
  </refsynopsisdiv>
125
 
 
 
107
  
126
108
  <refsect1 id="description">
127
109
    <title>DESCRIPTION</title>
128
110
    <para>
137
119
      Any authenticated client is then given the stored pre-encrypted
138
120
      password for that specific client.
139
121
    </para>
140
 
 
141
122
  </refsect1>
142
123
  
143
124
  <refsect1 id="purpose">
144
125
    <title>PURPOSE</title>
145
 
 
146
126
    <para>
147
127
      The purpose of this is to enable <emphasis>remote and unattended
148
128
      rebooting</emphasis> of client host computer with an
149
129
      <emphasis>encrypted root file system</emphasis>.  See <xref
150
130
      linkend="overview"/> for details.
151
131
    </para>
152
 
 
153
132
  </refsect1>
154
133
  
155
134
  <refsect1 id="options">
156
135
    <title>OPTIONS</title>
157
 
 
158
136
    <variablelist>
159
137
      <varlistentry>
 
138
        <term><option>--help</option></term>
160
139
        <term><option>-h</option></term>
161
 
        <term><option>--help</option></term>
162
140
        <listitem>
163
141
          <para>
164
142
            Show a help message and exit
165
143
          </para>
166
144
        </listitem>
167
145
      </varlistentry>
168
 
 
 
146
      
169
147
      <varlistentry>
 
148
        <term><option>--interface</option>
 
149
        <replaceable>NAME</replaceable></term>
170
150
        <term><option>-i</option>
171
151
        <replaceable>NAME</replaceable></term>
172
 
        <term><option>--interface</option>
173
 
        <replaceable>NAME</replaceable></term>
174
152
        <listitem>
175
153
          <xi:include href="mandos-options.xml" xpointer="interface"/>
176
154
        </listitem>
177
155
      </varlistentry>
178
 
 
 
156
      
179
157
      <varlistentry>
180
 
        <term><literal>-a</literal>, <literal>--address <replaceable>
181
 
        ADDRESS</replaceable></literal></term>
 
158
        <term><option>--address
 
159
        <replaceable>ADDRESS</replaceable></option></term>
 
160
        <term><option>-a
 
161
        <replaceable>ADDRESS</replaceable></option></term>
182
162
        <listitem>
183
163
          <xi:include href="mandos-options.xml" xpointer="address"/>
184
164
        </listitem>
185
165
      </varlistentry>
186
 
 
 
166
      
187
167
      <varlistentry>
188
 
        <term><literal>-p</literal>, <literal>--port <replaceable>
189
 
        PORT</replaceable></literal></term>
 
168
        <term><option>--port
 
169
        <replaceable>PORT</replaceable></option></term>
 
170
        <term><option>-p
 
171
        <replaceable>PORT</replaceable></option></term>
190
172
        <listitem>
191
173
          <xi:include href="mandos-options.xml" xpointer="port"/>
192
174
        </listitem>
193
175
      </varlistentry>
194
 
 
 
176
      
195
177
      <varlistentry>
196
 
        <term><literal>--check</literal></term>
 
178
        <term><option>--check</option></term>
197
179
        <listitem>
198
180
          <para>
199
181
            Run the server’s self-tests.  This includes any unit
201
183
          </para>
202
184
        </listitem>
203
185
      </varlistentry>
204
 
 
 
186
      
205
187
      <varlistentry>
206
 
        <term><literal>--debug</literal></term>
 
188
        <term><option>--debug</option></term>
207
189
        <listitem>
208
190
          <xi:include href="mandos-options.xml" xpointer="debug"/>
209
191
        </listitem>
210
192
      </varlistentry>
211
 
 
 
193
      
212
194
      <varlistentry>
213
 
        <term><literal>--priority <replaceable>
214
 
        PRIORITY</replaceable></literal></term>
 
195
        <term><option>--priority <replaceable>
 
196
        PRIORITY</replaceable></option></term>
215
197
        <listitem>
216
198
          <xi:include href="mandos-options.xml" xpointer="priority"/>
217
199
        </listitem>
218
200
      </varlistentry>
219
 
 
 
201
      
220
202
      <varlistentry>
221
 
        <term><literal>--servicename <replaceable>NAME</replaceable>
222
 
        </literal></term>
 
203
        <term><option>--servicename
 
204
        <replaceable>NAME</replaceable></option></term>
223
205
        <listitem>
224
206
          <xi:include href="mandos-options.xml"
225
207
                      xpointer="servicename"/>
226
208
        </listitem>
227
209
      </varlistentry>
228
 
 
 
210
      
229
211
      <varlistentry>
230
 
        <term><literal>--configdir <replaceable>DIR</replaceable>
231
 
        </literal></term>
 
212
        <term><option>--configdir
 
213
        <replaceable>DIRECTORY</replaceable></option></term>
232
214
        <listitem>
233
215
          <para>
234
216
            Directory to search for configuration files.  Default is
240
222
          </para>
241
223
        </listitem>
242
224
      </varlistentry>
243
 
 
 
225
      
244
226
      <varlistentry>
245
 
        <term><literal>--version</literal></term>
 
227
        <term><option>--version</option></term>
246
228
        <listitem>
247
229
          <para>
248
230
            Prints the program version and exit.
249
231
          </para>
250
232
        </listitem>
251
233
      </varlistentry>
 
234
      
 
235
      <varlistentry>
 
236
        <term><option>--no-dbus</option></term>
 
237
        <listitem>
 
238
          <xi:include href="mandos-options.xml" xpointer="dbus"/>
 
239
          <para>
 
240
            See also <xref linkend="dbus_interface"/>.
 
241
          </para>
 
242
        </listitem>
 
243
      </varlistentry>
252
244
    </variablelist>
253
245
  </refsect1>
254
 
 
 
246
  
255
247
  <refsect1 id="overview">
256
248
    <title>OVERVIEW</title>
257
249
    <xi:include href="overview.xml"/>
258
250
    <para>
259
251
      This program is the server part.  It is a normal server program
260
252
      and will run in a normal system environment, not in an initial
261
 
      RAM disk environment.
 
253
      <acronym>RAM</acronym> disk environment.
262
254
    </para>
263
255
  </refsect1>
264
 
 
 
256
  
265
257
  <refsect1 id="protocol">
266
258
    <title>NETWORK PROTOCOL</title>
267
259
    <para>
319
311
      </row>
320
312
    </tbody></tgroup></table>
321
313
  </refsect1>
322
 
 
 
314
  
323
315
  <refsect1 id="checking">
324
316
    <title>CHECKING</title>
325
317
    <para>
333
325
      <manvolnum>5</manvolnum></citerefentry>.
334
326
    </para>
335
327
  </refsect1>
336
 
 
 
328
  
337
329
  <refsect1 id="logging">
338
330
    <title>LOGGING</title>
339
331
    <para>
343
335
      and also show them on the console.
344
336
    </para>
345
337
  </refsect1>
 
338
  
 
339
  <refsect1 id="dbus_interface">
 
340
    <title>D-BUS INTERFACE</title>
 
341
    <para>
 
342
      The server will by default provide a D-Bus system bus interface.
 
343
      This interface will only be accessible by the root user or a
 
344
      Mandos-specific user, if such a user exists.
 
345
      <!-- XXX -->
 
346
    </para>
 
347
  </refsect1>
346
348
 
347
349
  <refsect1 id="exit_status">
348
350
    <title>EXIT STATUS</title>
351
353
      critical error is encountered.
352
354
    </para>
353
355
  </refsect1>
354
 
 
 
356
  
355
357
  <refsect1 id="environment">
356
358
    <title>ENVIRONMENT</title>
357
359
    <variablelist>
371
373
      </varlistentry>
372
374
    </variablelist>
373
375
  </refsect1>
374
 
 
375
 
  <refsect1 id="file">
 
376
  
 
377
  <refsect1 id="files">
376
378
    <title>FILES</title>
377
379
    <para>
378
380
      Use the <option>--configdir</option> option to change where
401
403
        </listitem>
402
404
      </varlistentry>
403
405
      <varlistentry>
404
 
        <term><filename>/var/run/mandos/mandos.pid</filename></term>
 
406
        <term><filename>/var/run/mandos.pid</filename></term>
405
407
        <listitem>
406
408
          <para>
407
409
            The file containing the process id of
442
444
      Currently, if a client is declared <quote>invalid</quote> due to
443
445
      having timed out, the server does not record this fact onto
444
446
      permanent storage.  This has some security implications, see
445
 
      <xref linkend="CLIENTS"/>.
 
447
      <xref linkend="clients"/>.
446
448
    </para>
447
449
    <para>
448
450
      There is currently no way of querying the server of the current
456
458
      Debug mode is conflated with running in the foreground.
457
459
    </para>
458
460
    <para>
459
 
      The console log messages does not show a timestamp.
 
461
      The console log messages does not show a time stamp.
 
462
    </para>
 
463
    <para>
 
464
      This server does not check the expire time of clients’ OpenPGP
 
465
      keys.
460
466
    </para>
461
467
  </refsect1>
462
468
  
497
503
      </para>
498
504
    </informalexample>
499
505
  </refsect1>
500
 
 
 
506
  
501
507
  <refsect1 id="security">
502
508
    <title>SECURITY</title>
503
 
    <refsect2 id="SERVER">
 
509
    <refsect2 id="server">
504
510
      <title>SERVER</title>
505
511
      <para>
506
512
        Running this <command>&COMMANDNAME;</command> server program
507
513
        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.
 
514
        computer running it.  The program switches to a non-root user
 
515
        soon after startup.
510
516
      </para>
511
517
    </refsect2>
512
 
    <refsect2 id="CLIENTS">
 
518
    <refsect2 id="clients">
513
519
      <title>CLIENTS</title>
514
520
      <para>
515
521
        The server only gives out its stored data to clients which
522
528
        <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
523
529
        <manvolnum>5</manvolnum></citerefentry>)
524
530
        <emphasis>must</emphasis> be made non-readable by anyone
525
 
        except the user running the server.
 
531
        except the user starting the server (usually root).
526
532
      </para>
527
533
      <para>
528
534
        As detailed in <xref linkend="checking"/>, the status of all
539
545
        restarting servers if it is suspected that a client has, in
540
546
        fact, been compromised by parties who may now be running a
541
547
        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
 
548
        initial <acronym>RAM</acronym> image of the client host.  What
 
549
        should be done in that case (if restarting the server program
 
550
        really is necessary) is to stop the server program, edit the
545
551
        configuration file to omit any suspect clients, and restart
546
552
        the server program.
547
553
      </para>
548
554
      <para>
549
555
        For more details on client-side security, see
550
 
        <citerefentry><refentrytitle>password-request</refentrytitle>
 
556
        <citerefentry><refentrytitle>mandos-client</refentrytitle>
551
557
        <manvolnum>8mandos</manvolnum></citerefentry>.
552
558
      </para>
553
559
    </refsect2>
554
560
  </refsect1>
555
 
 
 
561
  
556
562
  <refsect1 id="see_also">
557
563
    <title>SEE ALSO</title>
558
564
    <para>
561
567
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
562
568
        <refentrytitle>mandos.conf</refentrytitle>
563
569
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
564
 
        <refentrytitle>password-request</refentrytitle>
 
570
        <refentrytitle>mandos-client</refentrytitle>
565
571
        <manvolnum>8mandos</manvolnum></citerefentry>, <citerefentry>
566
572
        <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
567
573
      </citerefentry>