/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 from trunk: remove last traces of debconf stuff.

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-29">
 
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
 
    <title>&COMMANDNAME;</title>
 
11
   <refentryinfo>
 
12
    <title>Mandos Manual</title>
12
13
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
13
 
    <productname>&COMMANDNAME;</productname>
14
 
    <productnumber>&VERSION;</productnumber>
 
14
    <productname>Mandos</productname>
 
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>
67
47
  <refnamediv>
68
48
    <refname><command>&COMMANDNAME;</command></refname>
69
49
    <refpurpose>
70
 
      Sends encrypted passwords to authenticated Mandos clients
 
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>
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>
 
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>
94
88
    </cmdsynopsis>
95
89
    <cmdsynopsis>
96
90
      <command>&COMMANDNAME;</command>
97
91
      <group choice="req">
98
 
        <arg choice="plain">-h</arg>
99
 
        <arg choice="plain">--help</arg>
 
92
        <arg choice="plain"><option>--help</option></arg>
 
93
        <arg choice="plain"><option>-h</option></arg>
100
94
      </group>
101
95
    </cmdsynopsis>
102
96
    <cmdsynopsis>
103
97
      <command>&COMMANDNAME;</command>
104
 
      <arg choice="plain">--version</arg>
 
98
      <arg choice="plain"><option>--version</option></arg>
105
99
    </cmdsynopsis>
106
100
    <cmdsynopsis>
107
101
      <command>&COMMANDNAME;</command>
108
 
      <arg choice="plain">--check</arg>
 
102
      <arg choice="plain"><option>--check</option></arg>
109
103
    </cmdsynopsis>
110
104
  </refsynopsisdiv>
111
 
 
 
105
  
112
106
  <refsect1 id="description">
113
107
    <title>DESCRIPTION</title>
114
108
    <para>
123
117
      Any authenticated client is then given the stored pre-encrypted
124
118
      password for that specific client.
125
119
    </para>
126
 
 
127
120
  </refsect1>
128
121
  
129
122
  <refsect1 id="purpose">
130
123
    <title>PURPOSE</title>
131
 
 
132
124
    <para>
133
125
      The purpose of this is to enable <emphasis>remote and unattended
134
126
      rebooting</emphasis> of client host computer with an
135
127
      <emphasis>encrypted root file system</emphasis>.  See <xref
136
128
      linkend="overview"/> for details.
137
129
    </para>
138
 
 
139
130
  </refsect1>
140
131
  
141
132
  <refsect1 id="options">
142
133
    <title>OPTIONS</title>
143
 
 
144
134
    <variablelist>
145
135
      <varlistentry>
146
 
        <term><literal>-h</literal>, <literal>--help</literal></term>
 
136
        <term><option>--help</option></term>
 
137
        <term><option>-h</option></term>
147
138
        <listitem>
148
139
          <para>
149
140
            Show a help message and exit
150
141
          </para>
151
142
        </listitem>
152
143
      </varlistentry>
153
 
 
 
144
      
154
145
      <varlistentry>
155
 
        <term><literal>-i</literal>, <literal>--interface <replaceable
156
 
        >NAME</replaceable></literal></term>
 
146
        <term><option>--interface</option>
 
147
        <replaceable>NAME</replaceable></term>
 
148
        <term><option>-i</option>
 
149
        <replaceable>NAME</replaceable></term>
157
150
        <listitem>
158
151
          <xi:include href="mandos-options.xml" xpointer="interface"/>
159
152
        </listitem>
160
153
      </varlistentry>
161
 
 
 
154
      
162
155
      <varlistentry>
163
 
        <term><literal>-a</literal>, <literal>--address <replaceable>
164
 
        ADDRESS</replaceable></literal></term>
 
156
        <term><option>--address
 
157
        <replaceable>ADDRESS</replaceable></option></term>
 
158
        <term><option>-a
 
159
        <replaceable>ADDRESS</replaceable></option></term>
165
160
        <listitem>
166
161
          <xi:include href="mandos-options.xml" xpointer="address"/>
167
162
        </listitem>
168
163
      </varlistentry>
169
 
 
 
164
      
170
165
      <varlistentry>
171
 
        <term><literal>-p</literal>, <literal>--port <replaceable>
172
 
        PORT</replaceable></literal></term>
 
166
        <term><option>--port
 
167
        <replaceable>PORT</replaceable></option></term>
 
168
        <term><option>-p
 
169
        <replaceable>PORT</replaceable></option></term>
173
170
        <listitem>
174
171
          <xi:include href="mandos-options.xml" xpointer="port"/>
175
172
        </listitem>
176
173
      </varlistentry>
177
 
 
 
174
      
178
175
      <varlistentry>
179
 
        <term><literal>--check</literal></term>
 
176
        <term><option>--check</option></term>
180
177
        <listitem>
181
178
          <para>
182
179
            Run the server’s self-tests.  This includes any unit
184
181
          </para>
185
182
        </listitem>
186
183
      </varlistentry>
187
 
 
 
184
      
188
185
      <varlistentry>
189
 
        <term><literal>--debug</literal></term>
 
186
        <term><option>--debug</option></term>
190
187
        <listitem>
191
188
          <xi:include href="mandos-options.xml" xpointer="debug"/>
192
189
        </listitem>
193
190
      </varlistentry>
194
 
 
 
191
      
195
192
      <varlistentry>
196
 
        <term><literal>--priority <replaceable>
197
 
        PRIORITY</replaceable></literal></term>
 
193
        <term><option>--priority <replaceable>
 
194
        PRIORITY</replaceable></option></term>
198
195
        <listitem>
199
196
          <xi:include href="mandos-options.xml" xpointer="priority"/>
200
197
        </listitem>
201
198
      </varlistentry>
202
 
 
 
199
      
203
200
      <varlistentry>
204
 
        <term><literal>--servicename <replaceable>NAME</replaceable>
205
 
        </literal></term>
 
201
        <term><option>--servicename
 
202
        <replaceable>NAME</replaceable></option></term>
206
203
        <listitem>
207
204
          <xi:include href="mandos-options.xml"
208
205
                      xpointer="servicename"/>
209
206
        </listitem>
210
207
      </varlistentry>
211
 
 
 
208
      
212
209
      <varlistentry>
213
 
        <term><literal>--configdir <replaceable>DIR</replaceable>
214
 
        </literal></term>
 
210
        <term><option>--configdir
 
211
        <replaceable>DIRECTORY</replaceable></option></term>
215
212
        <listitem>
216
213
          <para>
217
214
            Directory to search for configuration files.  Default is
223
220
          </para>
224
221
        </listitem>
225
222
      </varlistentry>
226
 
 
 
223
      
227
224
      <varlistentry>
228
 
        <term><literal>--version</literal></term>
 
225
        <term><option>--version</option></term>
229
226
        <listitem>
230
227
          <para>
231
228
            Prints the program version and exit.
234
231
      </varlistentry>
235
232
    </variablelist>
236
233
  </refsect1>
237
 
 
 
234
  
238
235
  <refsect1 id="overview">
239
236
    <title>OVERVIEW</title>
240
237
    <xi:include href="overview.xml"/>
241
238
    <para>
242
239
      This program is the server part.  It is a normal server program
243
240
      and will run in a normal system environment, not in an initial
244
 
      RAM disk environment.
 
241
      <acronym>RAM</acronym> disk environment.
245
242
    </para>
246
243
  </refsect1>
247
 
 
 
244
  
248
245
  <refsect1 id="protocol">
249
246
    <title>NETWORK PROTOCOL</title>
250
247
    <para>
302
299
      </row>
303
300
    </tbody></tgroup></table>
304
301
  </refsect1>
305
 
 
 
302
  
306
303
  <refsect1 id="checking">
307
304
    <title>CHECKING</title>
308
305
    <para>
316
313
      <manvolnum>5</manvolnum></citerefentry>.
317
314
    </para>
318
315
  </refsect1>
319
 
 
 
316
  
320
317
  <refsect1 id="logging">
321
318
    <title>LOGGING</title>
322
319
    <para>
326
323
      and also show them on the console.
327
324
    </para>
328
325
  </refsect1>
329
 
 
 
326
  
330
327
  <refsect1 id="exit_status">
331
328
    <title>EXIT STATUS</title>
332
329
    <para>
334
331
      critical error is encountered.
335
332
    </para>
336
333
  </refsect1>
337
 
 
 
334
  
338
335
  <refsect1 id="environment">
339
336
    <title>ENVIRONMENT</title>
340
337
    <variablelist>
341
338
      <varlistentry>
342
 
        <term><varname>PATH</varname></term>
 
339
        <term><envar>PATH</envar></term>
343
340
        <listitem>
344
341
          <para>
345
342
            To start the configured checker (see <xref
354
351
      </varlistentry>
355
352
    </variablelist>
356
353
  </refsect1>
357
 
 
358
 
  <refsect1 id="file">
 
354
  
 
355
  <refsect1 id="files">
359
356
    <title>FILES</title>
360
357
    <para>
361
358
      Use the <option>--configdir</option> option to change where
384
381
        </listitem>
385
382
      </varlistentry>
386
383
      <varlistentry>
387
 
        <term><filename>/var/run/mandos/mandos.pid</filename></term>
 
384
        <term><filename>/var/run/mandos.pid</filename></term>
388
385
        <listitem>
389
386
          <para>
390
387
            The file containing the process id of
425
422
      Currently, if a client is declared <quote>invalid</quote> due to
426
423
      having timed out, the server does not record this fact onto
427
424
      permanent storage.  This has some security implications, see
428
 
      <xref linkend="CLIENTS"/>.
 
425
      <xref linkend="clients"/>.
429
426
    </para>
430
427
    <para>
431
428
      There is currently no way of querying the server of the current
439
436
      Debug mode is conflated with running in the foreground.
440
437
    </para>
441
438
    <para>
442
 
      The console log messages does not show a timestamp.
 
439
      The console log messages does not show a time stamp.
 
440
    </para>
 
441
    <para>
 
442
      This server does not check the expire time of clients’ OpenPGP
 
443
      keys.
443
444
    </para>
444
445
  </refsect1>
445
446
  
480
481
      </para>
481
482
    </informalexample>
482
483
  </refsect1>
483
 
 
 
484
  
484
485
  <refsect1 id="security">
485
486
    <title>SECURITY</title>
486
 
    <refsect2 id="SERVER">
 
487
    <refsect2 id="server">
487
488
      <title>SERVER</title>
488
489
      <para>
489
490
        Running this <command>&COMMANDNAME;</command> server program
490
491
        should not in itself present any security risk to the host
491
 
        computer running it.  The program does not need any special
492
 
        privileges to run, and is designed to run as a non-root user.
 
492
        computer running it.  The program switches to a non-root user
 
493
        soon after startup.
493
494
      </para>
494
495
    </refsect2>
495
 
    <refsect2 id="CLIENTS">
 
496
    <refsect2 id="clients">
496
497
      <title>CLIENTS</title>
497
498
      <para>
498
499
        The server only gives out its stored data to clients which
505
506
        <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
506
507
        <manvolnum>5</manvolnum></citerefentry>)
507
508
        <emphasis>must</emphasis> be made non-readable by anyone
508
 
        except the user running the server.
 
509
        except the user starting the server (usually root).
509
510
      </para>
510
511
      <para>
511
512
        As detailed in <xref linkend="checking"/>, the status of all
522
523
        restarting servers if it is suspected that a client has, in
523
524
        fact, been compromised by parties who may now be running a
524
525
        fake Mandos client with the keys from the non-encrypted
525
 
        initial RAM image of the client host.  What should be done in
526
 
        that case (if restarting the server program really is
527
 
        necessary) is to stop the server program, edit the
 
526
        initial <acronym>RAM</acronym> image of the client host.  What
 
527
        should be done in that case (if restarting the server program
 
528
        really is necessary) is to stop the server program, edit the
528
529
        configuration file to omit any suspect clients, and restart
529
530
        the server program.
530
531
      </para>
531
532
      <para>
532
533
        For more details on client-side security, see
533
 
        <citerefentry><refentrytitle>password-request</refentrytitle>
 
534
        <citerefentry><refentrytitle>mandos-client</refentrytitle>
534
535
        <manvolnum>8mandos</manvolnum></citerefentry>.
535
536
      </para>
536
537
    </refsect2>
537
538
  </refsect1>
538
 
 
 
539
  
539
540
  <refsect1 id="see_also">
540
541
    <title>SEE ALSO</title>
541
542
    <para>
542
543
      <citerefentry>
 
544
        <refentrytitle>mandos-clients.conf</refentrytitle>
 
545
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
543
546
        <refentrytitle>mandos.conf</refentrytitle>
544
547
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
545
 
        <refentrytitle>mandos-clients.conf</refentrytitle>
546
 
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
547
 
        <refentrytitle>password-request</refentrytitle>
 
548
        <refentrytitle>mandos-client</refentrytitle>
548
549
        <manvolnum>8mandos</manvolnum></citerefentry>, <citerefentry>
549
550
        <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
550
551
      </citerefentry>