/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

merge

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">
4
5
<!ENTITY COMMANDNAME "mandos">
5
 
<!ENTITY TIMESTAMP "2009-01-04">
6
 
<!ENTITY % common SYSTEM "common.ent">
7
 
%common;
 
6
<!ENTITY TIMESTAMP "2008-08-29">
8
7
]>
9
8
 
10
9
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
11
 
   <refentryinfo>
 
10
  <refentryinfo>
12
11
    <title>Mandos Manual</title>
13
12
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
14
13
    <productname>Mandos</productname>
15
 
    <productnumber>&version;</productnumber>
 
14
    <productnumber>&VERSION;</productnumber>
16
15
    <date>&TIMESTAMP;</date>
17
16
    <authorgroup>
18
17
      <author>
32
31
    </authorgroup>
33
32
    <copyright>
34
33
      <year>2008</year>
35
 
      <year>2009</year>
36
34
      <holder>Teddy Hogeborn</holder>
37
35
      <holder>Björn Påhlsson</holder>
38
36
    </copyright>
39
 
    <xi:include href="legalnotice.xml"/>
 
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>
40
60
  </refentryinfo>
41
 
  
 
61
 
42
62
  <refmeta>
43
63
    <refentrytitle>&COMMANDNAME;</refentrytitle>
44
64
    <manvolnum>8</manvolnum>
47
67
  <refnamediv>
48
68
    <refname><command>&COMMANDNAME;</command></refname>
49
69
    <refpurpose>
50
 
      Gives encrypted passwords to authenticated Mandos clients
 
70
      Sends encrypted passwords to authenticated Mandos clients
51
71
    </refpurpose>
52
72
  </refnamediv>
53
 
  
 
73
 
54
74
  <refsynopsisdiv>
55
75
    <cmdsynopsis>
56
76
      <command>&COMMANDNAME;</command>
57
 
      <group>
58
 
        <arg choice="plain"><option>--interface
59
 
        <replaceable>NAME</replaceable></option></arg>
60
 
        <arg choice="plain"><option>-i
61
 
        <replaceable>NAME</replaceable></option></arg>
62
 
      </group>
63
 
      <sbr/>
64
 
      <group>
65
 
        <arg choice="plain"><option>--address
66
 
        <replaceable>ADDRESS</replaceable></option></arg>
67
 
        <arg choice="plain"><option>-a
68
 
        <replaceable>ADDRESS</replaceable></option></arg>
69
 
      </group>
70
 
      <sbr/>
71
 
      <group>
72
 
        <arg choice="plain"><option>--port
73
 
        <replaceable>PORT</replaceable></option></arg>
74
 
        <arg choice="plain"><option>-p
75
 
        <replaceable>PORT</replaceable></option></arg>
76
 
      </group>
77
 
      <sbr/>
78
 
      <arg><option>--priority
79
 
      <replaceable>PRIORITY</replaceable></option></arg>
80
 
      <sbr/>
81
 
      <arg><option>--servicename
82
 
      <replaceable>NAME</replaceable></option></arg>
83
 
      <sbr/>
84
 
      <arg><option>--configdir
85
 
      <replaceable>DIRECTORY</replaceable></option></arg>
86
 
      <sbr/>
87
 
      <arg><option>--debug</option></arg>
88
 
      <sbr/>
89
 
      <arg><option>--no-dbus</option></arg>
 
77
      <arg>--interface<arg choice="plain">NAME</arg></arg>
 
78
      <arg>--address<arg choice="plain">ADDRESS</arg></arg>
 
79
      <arg>--port<arg choice="plain">PORT</arg></arg>
 
80
      <arg>--priority<arg choice="plain">PRIORITY</arg></arg>
 
81
      <arg>--servicename<arg choice="plain">NAME</arg></arg>
 
82
      <arg>--configdir<arg choice="plain">DIRECTORY</arg></arg>
 
83
      <arg>--debug</arg>
 
84
    </cmdsynopsis>
 
85
    <cmdsynopsis>
 
86
      <command>&COMMANDNAME;</command>
 
87
      <arg>-i<arg choice="plain">NAME</arg></arg>
 
88
      <arg>-a<arg choice="plain">ADDRESS</arg></arg>
 
89
      <arg>-p<arg choice="plain">PORT</arg></arg>
 
90
      <arg>--priority<arg choice="plain">PRIORITY</arg></arg>
 
91
      <arg>--servicename<arg choice="plain">NAME</arg></arg>
 
92
      <arg>--configdir<arg choice="plain">DIRECTORY</arg></arg>
 
93
      <arg>--debug</arg>
90
94
    </cmdsynopsis>
91
95
    <cmdsynopsis>
92
96
      <command>&COMMANDNAME;</command>
93
97
      <group choice="req">
94
 
        <arg choice="plain"><option>--help</option></arg>
95
 
        <arg choice="plain"><option>-h</option></arg>
 
98
        <arg choice="plain">-h</arg>
 
99
        <arg choice="plain">--help</arg>
96
100
      </group>
97
101
    </cmdsynopsis>
98
102
    <cmdsynopsis>
99
103
      <command>&COMMANDNAME;</command>
100
 
      <arg choice="plain"><option>--version</option></arg>
 
104
      <arg choice="plain">--version</arg>
101
105
    </cmdsynopsis>
102
106
    <cmdsynopsis>
103
107
      <command>&COMMANDNAME;</command>
104
 
      <arg choice="plain"><option>--check</option></arg>
 
108
      <arg choice="plain">--check</arg>
105
109
    </cmdsynopsis>
106
110
  </refsynopsisdiv>
107
 
  
 
111
 
108
112
  <refsect1 id="description">
109
113
    <title>DESCRIPTION</title>
110
114
    <para>
119
123
      Any authenticated client is then given the stored pre-encrypted
120
124
      password for that specific client.
121
125
    </para>
 
126
 
122
127
  </refsect1>
123
128
  
124
129
  <refsect1 id="purpose">
125
130
    <title>PURPOSE</title>
 
131
 
126
132
    <para>
127
133
      The purpose of this is to enable <emphasis>remote and unattended
128
134
      rebooting</emphasis> of client host computer with an
129
135
      <emphasis>encrypted root file system</emphasis>.  See <xref
130
136
      linkend="overview"/> for details.
131
137
    </para>
 
138
 
132
139
  </refsect1>
133
140
  
134
141
  <refsect1 id="options">
135
142
    <title>OPTIONS</title>
 
143
 
136
144
    <variablelist>
137
145
      <varlistentry>
 
146
        <term><option>-h</option></term>
138
147
        <term><option>--help</option></term>
139
 
        <term><option>-h</option></term>
140
148
        <listitem>
141
149
          <para>
142
150
            Show a help message and exit
143
151
          </para>
144
152
        </listitem>
145
153
      </varlistentry>
146
 
      
 
154
 
147
155
      <varlistentry>
 
156
        <term><option>-i</option>
 
157
        <replaceable>NAME</replaceable></term>
148
158
        <term><option>--interface</option>
149
159
        <replaceable>NAME</replaceable></term>
150
 
        <term><option>-i</option>
151
 
        <replaceable>NAME</replaceable></term>
152
160
        <listitem>
153
161
          <xi:include href="mandos-options.xml" xpointer="interface"/>
154
162
        </listitem>
155
163
      </varlistentry>
156
 
      
 
164
 
157
165
      <varlistentry>
158
 
        <term><option>--address
159
 
        <replaceable>ADDRESS</replaceable></option></term>
160
 
        <term><option>-a
161
 
        <replaceable>ADDRESS</replaceable></option></term>
 
166
        <term><literal>-a</literal>, <literal>--address <replaceable>
 
167
        ADDRESS</replaceable></literal></term>
162
168
        <listitem>
163
169
          <xi:include href="mandos-options.xml" xpointer="address"/>
164
170
        </listitem>
165
171
      </varlistentry>
166
 
      
 
172
 
167
173
      <varlistentry>
168
 
        <term><option>--port
169
 
        <replaceable>PORT</replaceable></option></term>
170
 
        <term><option>-p
171
 
        <replaceable>PORT</replaceable></option></term>
 
174
        <term><literal>-p</literal>, <literal>--port <replaceable>
 
175
        PORT</replaceable></literal></term>
172
176
        <listitem>
173
177
          <xi:include href="mandos-options.xml" xpointer="port"/>
174
178
        </listitem>
175
179
      </varlistentry>
176
 
      
 
180
 
177
181
      <varlistentry>
178
 
        <term><option>--check</option></term>
 
182
        <term><literal>--check</literal></term>
179
183
        <listitem>
180
184
          <para>
181
185
            Run the server’s self-tests.  This includes any unit
183
187
          </para>
184
188
        </listitem>
185
189
      </varlistentry>
186
 
      
 
190
 
187
191
      <varlistentry>
188
 
        <term><option>--debug</option></term>
 
192
        <term><literal>--debug</literal></term>
189
193
        <listitem>
190
194
          <xi:include href="mandos-options.xml" xpointer="debug"/>
191
195
        </listitem>
192
196
      </varlistentry>
193
 
      
 
197
 
194
198
      <varlistentry>
195
 
        <term><option>--priority <replaceable>
196
 
        PRIORITY</replaceable></option></term>
 
199
        <term><literal>--priority <replaceable>
 
200
        PRIORITY</replaceable></literal></term>
197
201
        <listitem>
198
202
          <xi:include href="mandos-options.xml" xpointer="priority"/>
199
203
        </listitem>
200
204
      </varlistentry>
201
 
      
 
205
 
202
206
      <varlistentry>
203
 
        <term><option>--servicename
204
 
        <replaceable>NAME</replaceable></option></term>
 
207
        <term><literal>--servicename <replaceable>NAME</replaceable>
 
208
        </literal></term>
205
209
        <listitem>
206
210
          <xi:include href="mandos-options.xml"
207
211
                      xpointer="servicename"/>
208
212
        </listitem>
209
213
      </varlistentry>
210
 
      
 
214
 
211
215
      <varlistentry>
212
 
        <term><option>--configdir
213
 
        <replaceable>DIRECTORY</replaceable></option></term>
 
216
        <term><literal>--configdir <replaceable>DIR</replaceable>
 
217
        </literal></term>
214
218
        <listitem>
215
219
          <para>
216
220
            Directory to search for configuration files.  Default is
222
226
          </para>
223
227
        </listitem>
224
228
      </varlistentry>
225
 
      
 
229
 
226
230
      <varlistentry>
227
 
        <term><option>--version</option></term>
 
231
        <term><literal>--version</literal></term>
228
232
        <listitem>
229
233
          <para>
230
234
            Prints the program version and exit.
231
235
          </para>
232
236
        </listitem>
233
237
      </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>
244
238
    </variablelist>
245
239
  </refsect1>
246
 
  
 
240
 
247
241
  <refsect1 id="overview">
248
242
    <title>OVERVIEW</title>
249
243
    <xi:include href="overview.xml"/>
250
244
    <para>
251
245
      This program is the server part.  It is a normal server program
252
246
      and will run in a normal system environment, not in an initial
253
 
      <acronym>RAM</acronym> disk environment.
 
247
      RAM disk environment.
254
248
    </para>
255
249
  </refsect1>
256
 
  
 
250
 
257
251
  <refsect1 id="protocol">
258
252
    <title>NETWORK PROTOCOL</title>
259
253
    <para>
311
305
      </row>
312
306
    </tbody></tgroup></table>
313
307
  </refsect1>
314
 
  
 
308
 
315
309
  <refsect1 id="checking">
316
310
    <title>CHECKING</title>
317
311
    <para>
325
319
      <manvolnum>5</manvolnum></citerefentry>.
326
320
    </para>
327
321
  </refsect1>
328
 
  
 
322
 
329
323
  <refsect1 id="logging">
330
324
    <title>LOGGING</title>
331
325
    <para>
335
329
      and also show them on the console.
336
330
    </para>
337
331
  </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>
348
332
 
349
333
  <refsect1 id="exit_status">
350
334
    <title>EXIT STATUS</title>
353
337
      critical error is encountered.
354
338
    </para>
355
339
  </refsect1>
356
 
  
 
340
 
357
341
  <refsect1 id="environment">
358
342
    <title>ENVIRONMENT</title>
359
343
    <variablelist>
360
344
      <varlistentry>
361
 
        <term><envar>PATH</envar></term>
 
345
        <term><varname>PATH</varname></term>
362
346
        <listitem>
363
347
          <para>
364
348
            To start the configured checker (see <xref
373
357
      </varlistentry>
374
358
    </variablelist>
375
359
  </refsect1>
376
 
  
377
 
  <refsect1 id="files">
 
360
 
 
361
  <refsect1 id="file">
378
362
    <title>FILES</title>
379
363
    <para>
380
364
      Use the <option>--configdir</option> option to change where
403
387
        </listitem>
404
388
      </varlistentry>
405
389
      <varlistentry>
406
 
        <term><filename>/var/run/mandos.pid</filename></term>
 
390
        <term><filename>/var/run/mandos/mandos.pid</filename></term>
407
391
        <listitem>
408
392
          <para>
409
393
            The file containing the process id of
444
428
      Currently, if a client is declared <quote>invalid</quote> due to
445
429
      having timed out, the server does not record this fact onto
446
430
      permanent storage.  This has some security implications, see
447
 
      <xref linkend="clients"/>.
 
431
      <xref linkend="CLIENTS"/>.
448
432
    </para>
449
433
    <para>
450
434
      There is currently no way of querying the server of the current
458
442
      Debug mode is conflated with running in the foreground.
459
443
    </para>
460
444
    <para>
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.
 
445
      The console log messages does not show a timestamp.
466
446
    </para>
467
447
  </refsect1>
468
448
  
503
483
      </para>
504
484
    </informalexample>
505
485
  </refsect1>
506
 
  
 
486
 
507
487
  <refsect1 id="security">
508
488
    <title>SECURITY</title>
509
 
    <refsect2 id="server">
 
489
    <refsect2 id="SERVER">
510
490
      <title>SERVER</title>
511
491
      <para>
512
492
        Running this <command>&COMMANDNAME;</command> server program
513
493
        should not in itself present any security risk to the host
514
 
        computer running it.  The program switches to a non-root user
515
 
        soon after startup.
 
494
        computer running it.  The program does not need any special
 
495
        privileges to run, and is designed to run as a non-root user.
516
496
      </para>
517
497
    </refsect2>
518
 
    <refsect2 id="clients">
 
498
    <refsect2 id="CLIENTS">
519
499
      <title>CLIENTS</title>
520
500
      <para>
521
501
        The server only gives out its stored data to clients which
528
508
        <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
529
509
        <manvolnum>5</manvolnum></citerefentry>)
530
510
        <emphasis>must</emphasis> be made non-readable by anyone
531
 
        except the user starting the server (usually root).
 
511
        except the user running the server.
532
512
      </para>
533
513
      <para>
534
514
        As detailed in <xref linkend="checking"/>, the status of all
545
525
        restarting servers if it is suspected that a client has, in
546
526
        fact, been compromised by parties who may now be running a
547
527
        fake Mandos client with the keys from the non-encrypted
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
 
528
        initial RAM image of the client host.  What should be done in
 
529
        that case (if restarting the server program really is
 
530
        necessary) is to stop the server program, edit the
551
531
        configuration file to omit any suspect clients, and restart
552
532
        the server program.
553
533
      </para>
554
534
      <para>
555
535
        For more details on client-side security, see
556
 
        <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
536
        <citerefentry><refentrytitle>password-request</refentrytitle>
557
537
        <manvolnum>8mandos</manvolnum></citerefentry>.
558
538
      </para>
559
539
    </refsect2>
560
540
  </refsect1>
561
 
  
 
541
 
562
542
  <refsect1 id="see_also">
563
543
    <title>SEE ALSO</title>
564
544
    <para>
567
547
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
568
548
        <refentrytitle>mandos.conf</refentrytitle>
569
549
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
570
 
        <refentrytitle>mandos-client</refentrytitle>
 
550
        <refentrytitle>password-request</refentrytitle>
571
551
        <manvolnum>8mandos</manvolnum></citerefentry>, <citerefentry>
572
552
        <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
573
553
      </citerefentry>