/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-02-24">
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>
88
 
      <sbr/>
89
 
      <arg><option>--no-ipv6</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-ipv6</option></term>
237
 
        <listitem>
238
 
          <xi:include href="mandos-options.xml" xpointer="ipv6"/>
239
 
        </listitem>
240
 
      </varlistentry>
241
238
    </variablelist>
242
239
  </refsect1>
243
 
  
 
240
 
244
241
  <refsect1 id="overview">
245
242
    <title>OVERVIEW</title>
246
243
    <xi:include href="overview.xml"/>
247
244
    <para>
248
245
      This program is the server part.  It is a normal server program
249
246
      and will run in a normal system environment, not in an initial
250
 
      <acronym>RAM</acronym> disk environment.
 
247
      RAM disk environment.
251
248
    </para>
252
249
  </refsect1>
253
 
  
 
250
 
254
251
  <refsect1 id="protocol">
255
252
    <title>NETWORK PROTOCOL</title>
256
253
    <para>
308
305
      </row>
309
306
    </tbody></tgroup></table>
310
307
  </refsect1>
311
 
  
 
308
 
312
309
  <refsect1 id="checking">
313
310
    <title>CHECKING</title>
314
311
    <para>
322
319
      <manvolnum>5</manvolnum></citerefentry>.
323
320
    </para>
324
321
  </refsect1>
325
 
  
 
322
 
326
323
  <refsect1 id="logging">
327
324
    <title>LOGGING</title>
328
325
    <para>
332
329
      and also show them on the console.
333
330
    </para>
334
331
  </refsect1>
335
 
  
 
332
 
336
333
  <refsect1 id="exit_status">
337
334
    <title>EXIT STATUS</title>
338
335
    <para>
340
337
      critical error is encountered.
341
338
    </para>
342
339
  </refsect1>
343
 
  
 
340
 
344
341
  <refsect1 id="environment">
345
342
    <title>ENVIRONMENT</title>
346
343
    <variablelist>
360
357
      </varlistentry>
361
358
    </variablelist>
362
359
  </refsect1>
363
 
  
364
 
  <refsect1 id="files">
 
360
 
 
361
  <refsect1 id="file">
365
362
    <title>FILES</title>
366
363
    <para>
367
364
      Use the <option>--configdir</option> option to change where
390
387
        </listitem>
391
388
      </varlistentry>
392
389
      <varlistentry>
393
 
        <term><filename>/var/run/mandos.pid</filename></term>
 
390
        <term><filename>/var/run/mandos/mandos.pid</filename></term>
394
391
        <listitem>
395
392
          <para>
396
393
            The file containing the process id of
431
428
      Currently, if a client is declared <quote>invalid</quote> due to
432
429
      having timed out, the server does not record this fact onto
433
430
      permanent storage.  This has some security implications, see
434
 
      <xref linkend="clients"/>.
 
431
      <xref linkend="CLIENTS"/>.
435
432
    </para>
436
433
    <para>
437
434
      There is currently no way of querying the server of the current
445
442
      Debug mode is conflated with running in the foreground.
446
443
    </para>
447
444
    <para>
448
 
      The console log messages do not show a time stamp.
449
 
    </para>
450
 
    <para>
451
 
      This server does not check the expire time of clients’ OpenPGP
452
 
      keys.
 
445
      The console log messages does not show a timestamp.
453
446
    </para>
454
447
  </refsect1>
455
448
  
490
483
      </para>
491
484
    </informalexample>
492
485
  </refsect1>
493
 
  
 
486
 
494
487
  <refsect1 id="security">
495
488
    <title>SECURITY</title>
496
 
    <refsect2 id="server">
 
489
    <refsect2 id="SERVER">
497
490
      <title>SERVER</title>
498
491
      <para>
499
492
        Running this <command>&COMMANDNAME;</command> server program
500
493
        should not in itself present any security risk to the host
501
 
        computer running it.  The program switches to a non-root user
502
 
        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.
503
496
      </para>
504
497
    </refsect2>
505
 
    <refsect2 id="clients">
 
498
    <refsect2 id="CLIENTS">
506
499
      <title>CLIENTS</title>
507
500
      <para>
508
501
        The server only gives out its stored data to clients which
515
508
        <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
516
509
        <manvolnum>5</manvolnum></citerefentry>)
517
510
        <emphasis>must</emphasis> be made non-readable by anyone
518
 
        except the user starting the server (usually root).
 
511
        except the user running the server.
519
512
      </para>
520
513
      <para>
521
514
        As detailed in <xref linkend="checking"/>, the status of all
532
525
        restarting servers if it is suspected that a client has, in
533
526
        fact, been compromised by parties who may now be running a
534
527
        fake Mandos client with the keys from the non-encrypted
535
 
        initial <acronym>RAM</acronym> image of the client host.  What
536
 
        should be done in that case (if restarting the server program
537
 
        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
538
531
        configuration file to omit any suspect clients, and restart
539
532
        the server program.
540
533
      </para>
541
534
      <para>
542
535
        For more details on client-side security, see
543
 
        <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
536
        <citerefentry><refentrytitle>password-request</refentrytitle>
544
537
        <manvolnum>8mandos</manvolnum></citerefentry>.
545
538
      </para>
546
539
    </refsect2>
547
540
  </refsect1>
548
 
  
 
541
 
549
542
  <refsect1 id="see_also">
550
543
    <title>SEE ALSO</title>
551
544
    <para>
554
547
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
555
548
        <refentrytitle>mandos.conf</refentrytitle>
556
549
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
557
 
        <refentrytitle>mandos-client</refentrytitle>
 
550
        <refentrytitle>password-request</refentrytitle>
558
551
        <manvolnum>8mandos</manvolnum></citerefentry>, <citerefentry>
559
552
        <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
560
553
      </citerefentry>