/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-29 16:53:41 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080829165341-xzrp0xxxfrua5kzq
* mandos.xml (SYNOPSIS): Split <term> tags for the "--help" and
                         "--interface" options.

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-09-17">
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-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>
315
312
      The server will, by default, continually check that the clients
316
313
      are still up.  If a client has not been confirmed as being up
317
314
      for some time, the client is assumed to be compromised and is no
318
 
      longer eligible to receive the encrypted password.  (Manual
319
 
      intervention is required to re-enable a client.)  The timeout,
 
315
      longer eligible to receive the encrypted password.  The timeout,
320
316
      checker program, and interval between checks can be configured
321
317
      both globally and per client; see <citerefentry>
322
318
      <refentrytitle>mandos-clients.conf</refentrytitle>
323
 
      <manvolnum>5</manvolnum></citerefentry>.  A client successfully
324
 
      receiving its password will also be treated as a successful
325
 
      checker run.
 
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
 
  
 
332
 
339
333
  <refsect1 id="exit_status">
340
334
    <title>EXIT STATUS</title>
341
335
    <para>
343
337
      critical error is encountered.
344
338
    </para>
345
339
  </refsect1>
346
 
  
 
340
 
347
341
  <refsect1 id="environment">
348
342
    <title>ENVIRONMENT</title>
349
343
    <variablelist>
350
344
      <varlistentry>
351
 
        <term><envar>PATH</envar></term>
 
345
        <term><varname>PATH</varname></term>
352
346
        <listitem>
353
347
          <para>
354
348
            To start the configured checker (see <xref
363
357
      </varlistentry>
364
358
    </variablelist>
365
359
  </refsect1>
366
 
  
367
 
  <refsect1 id="files">
 
360
 
 
361
  <refsect1 id="file">
368
362
    <title>FILES</title>
369
363
    <para>
370
364
      Use the <option>--configdir</option> option to change where
393
387
        </listitem>
394
388
      </varlistentry>
395
389
      <varlistentry>
396
 
        <term><filename>/var/run/mandos.pid</filename></term>
 
390
        <term><filename>/var/run/mandos/mandos.pid</filename></term>
397
391
        <listitem>
398
392
          <para>
399
393
            The file containing the process id of
434
428
      Currently, if a client is declared <quote>invalid</quote> due to
435
429
      having timed out, the server does not record this fact onto
436
430
      permanent storage.  This has some security implications, see
437
 
      <xref linkend="clients"/>.
 
431
      <xref linkend="CLIENTS"/>.
438
432
    </para>
439
433
    <para>
440
434
      There is currently no way of querying the server of the current
448
442
      Debug mode is conflated with running in the foreground.
449
443
    </para>
450
444
    <para>
451
 
      The console log messages do not show a time stamp.
452
 
    </para>
453
 
    <para>
454
 
      This server does not check the expire time of clients’ OpenPGP
455
 
      keys.
 
445
      The console log messages does not show a timestamp.
456
446
    </para>
457
447
  </refsect1>
458
448
  
493
483
      </para>
494
484
    </informalexample>
495
485
  </refsect1>
496
 
  
 
486
 
497
487
  <refsect1 id="security">
498
488
    <title>SECURITY</title>
499
 
    <refsect2 id="server">
 
489
    <refsect2 id="SERVER">
500
490
      <title>SERVER</title>
501
491
      <para>
502
492
        Running this <command>&COMMANDNAME;</command> server program
503
493
        should not in itself present any security risk to the host
504
 
        computer running it.  The program switches to a non-root user
505
 
        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.
506
496
      </para>
507
497
    </refsect2>
508
 
    <refsect2 id="clients">
 
498
    <refsect2 id="CLIENTS">
509
499
      <title>CLIENTS</title>
510
500
      <para>
511
501
        The server only gives out its stored data to clients which
518
508
        <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
519
509
        <manvolnum>5</manvolnum></citerefentry>)
520
510
        <emphasis>must</emphasis> be made non-readable by anyone
521
 
        except the user starting the server (usually root).
 
511
        except the user running the server.
522
512
      </para>
523
513
      <para>
524
514
        As detailed in <xref linkend="checking"/>, the status of all
535
525
        restarting servers if it is suspected that a client has, in
536
526
        fact, been compromised by parties who may now be running a
537
527
        fake Mandos client with the keys from the non-encrypted
538
 
        initial <acronym>RAM</acronym> image of the client host.  What
539
 
        should be done in that case (if restarting the server program
540
 
        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
541
531
        configuration file to omit any suspect clients, and restart
542
532
        the server program.
543
533
      </para>
544
534
      <para>
545
535
        For more details on client-side security, see
546
 
        <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
536
        <citerefentry><refentrytitle>password-request</refentrytitle>
547
537
        <manvolnum>8mandos</manvolnum></citerefentry>.
548
538
      </para>
549
539
    </refsect2>
550
540
  </refsect1>
551
 
  
 
541
 
552
542
  <refsect1 id="see_also">
553
543
    <title>SEE ALSO</title>
554
544
    <para>
557
547
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
558
548
        <refentrytitle>mandos.conf</refentrytitle>
559
549
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
560
 
        <refentrytitle>mandos-client</refentrytitle>
 
550
        <refentrytitle>password-request</refentrytitle>
561
551
        <manvolnum>8mandos</manvolnum></citerefentry>, <citerefentry>
562
552
        <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
563
553
      </citerefentry>