/mandos/release

To get this branch, use:
bzr branch http://bzr.recompile.se/loggerhead/mandos/release

« back to all changes in this revision

Viewing changes to mandos.xml

  • Committer: Teddy Hogeborn
  • Date: 2008-08-30 18:45:41 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080830184541-j8zru4q0rlz5a0hw
* mandos-clients.conf.xml (SYNOPSIS): Remove line breaks.
  (OPTIONS): Add <option> tags.  Moved option name to outside
             <literal>.  Moved synopsis to inside <term> tags.
             Removed <synopsis> tags.  Improve wording of "secfile"
             option.
  (EXPANSION): Improved wording slightly.

* mandos-options.xml (interface): Improve wording.

* mandos.conf.xml (SYNOPSIS): Remove line breaks.
  (OPTIONS): Add <option> tags.  Moved option name to outside
             <literal>.  Moved synopsis to inside <term> tags.
             Removed <synopsis> tags.

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