/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-30 11:31:37 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080830113137-v0inyj0limprzfwn
* mandos-options.xml (priority): Added <acronym> tags.

* mandos.xml (NAME): Improved wording.

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