/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 19:05:15 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080830190515-l7e6vu81yyw5kcku
* mandos.xml (SYNOPSIS): Use <option> and <replaceable> tags.  Unify
                         short and long 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-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>
89
109
    <cmdsynopsis>
90
110
      <command>&COMMANDNAME;</command>
91
111
      <group choice="req">
 
112
        <arg choice="plain"><option>-h</option></arg>
92
113
        <arg choice="plain"><option>--help</option></arg>
93
 
        <arg choice="plain"><option>-h</option></arg>
94
114
      </group>
95
115
    </cmdsynopsis>
96
116
    <cmdsynopsis>
102
122
      <arg choice="plain"><option>--check</option></arg>
103
123
    </cmdsynopsis>
104
124
  </refsynopsisdiv>
105
 
  
 
125
 
106
126
  <refsect1 id="description">
107
127
    <title>DESCRIPTION</title>
108
128
    <para>
117
137
      Any authenticated client is then given the stored pre-encrypted
118
138
      password for that specific client.
119
139
    </para>
 
140
 
120
141
  </refsect1>
121
142
  
122
143
  <refsect1 id="purpose">
123
144
    <title>PURPOSE</title>
 
145
 
124
146
    <para>
125
147
      The purpose of this is to enable <emphasis>remote and unattended
126
148
      rebooting</emphasis> of client host computer with an
127
149
      <emphasis>encrypted root file system</emphasis>.  See <xref
128
150
      linkend="overview"/> for details.
129
151
    </para>
 
152
 
130
153
  </refsect1>
131
154
  
132
155
  <refsect1 id="options">
133
156
    <title>OPTIONS</title>
 
157
 
134
158
    <variablelist>
135
159
      <varlistentry>
 
160
        <term><option>-h</option></term>
136
161
        <term><option>--help</option></term>
137
 
        <term><option>-h</option></term>
138
162
        <listitem>
139
163
          <para>
140
164
            Show a help message and exit
141
165
          </para>
142
166
        </listitem>
143
167
      </varlistentry>
144
 
      
 
168
 
145
169
      <varlistentry>
 
170
        <term><option>-i</option>
 
171
        <replaceable>NAME</replaceable></term>
146
172
        <term><option>--interface</option>
147
173
        <replaceable>NAME</replaceable></term>
148
 
        <term><option>-i</option>
149
 
        <replaceable>NAME</replaceable></term>
150
174
        <listitem>
151
175
          <xi:include href="mandos-options.xml" xpointer="interface"/>
152
176
        </listitem>
153
177
      </varlistentry>
154
 
      
 
178
 
155
179
      <varlistentry>
156
 
        <term><option>--address
157
 
        <replaceable>ADDRESS</replaceable></option></term>
158
 
        <term><option>-a
159
 
        <replaceable>ADDRESS</replaceable></option></term>
 
180
        <term><literal>-a</literal>, <literal>--address <replaceable>
 
181
        ADDRESS</replaceable></literal></term>
160
182
        <listitem>
161
183
          <xi:include href="mandos-options.xml" xpointer="address"/>
162
184
        </listitem>
163
185
      </varlistentry>
164
 
      
 
186
 
165
187
      <varlistentry>
166
 
        <term><option>--port
167
 
        <replaceable>PORT</replaceable></option></term>
168
 
        <term><option>-p
169
 
        <replaceable>PORT</replaceable></option></term>
 
188
        <term><literal>-p</literal>, <literal>--port <replaceable>
 
189
        PORT</replaceable></literal></term>
170
190
        <listitem>
171
191
          <xi:include href="mandos-options.xml" xpointer="port"/>
172
192
        </listitem>
173
193
      </varlistentry>
174
 
      
 
194
 
175
195
      <varlistentry>
176
 
        <term><option>--check</option></term>
 
196
        <term><literal>--check</literal></term>
177
197
        <listitem>
178
198
          <para>
179
199
            Run the server’s self-tests.  This includes any unit
181
201
          </para>
182
202
        </listitem>
183
203
      </varlistentry>
184
 
      
 
204
 
185
205
      <varlistentry>
186
 
        <term><option>--debug</option></term>
 
206
        <term><literal>--debug</literal></term>
187
207
        <listitem>
188
208
          <xi:include href="mandos-options.xml" xpointer="debug"/>
189
209
        </listitem>
190
210
      </varlistentry>
191
 
      
 
211
 
192
212
      <varlistentry>
193
 
        <term><option>--priority <replaceable>
194
 
        PRIORITY</replaceable></option></term>
 
213
        <term><literal>--priority <replaceable>
 
214
        PRIORITY</replaceable></literal></term>
195
215
        <listitem>
196
216
          <xi:include href="mandos-options.xml" xpointer="priority"/>
197
217
        </listitem>
198
218
      </varlistentry>
199
 
      
 
219
 
200
220
      <varlistentry>
201
 
        <term><option>--servicename
202
 
        <replaceable>NAME</replaceable></option></term>
 
221
        <term><literal>--servicename <replaceable>NAME</replaceable>
 
222
        </literal></term>
203
223
        <listitem>
204
224
          <xi:include href="mandos-options.xml"
205
225
                      xpointer="servicename"/>
206
226
        </listitem>
207
227
      </varlistentry>
208
 
      
 
228
 
209
229
      <varlistentry>
210
 
        <term><option>--configdir
211
 
        <replaceable>DIRECTORY</replaceable></option></term>
 
230
        <term><literal>--configdir <replaceable>DIR</replaceable>
 
231
        </literal></term>
212
232
        <listitem>
213
233
          <para>
214
234
            Directory to search for configuration files.  Default is
220
240
          </para>
221
241
        </listitem>
222
242
      </varlistentry>
223
 
      
 
243
 
224
244
      <varlistentry>
225
 
        <term><option>--version</option></term>
 
245
        <term><literal>--version</literal></term>
226
246
        <listitem>
227
247
          <para>
228
248
            Prints the program version and exit.
231
251
      </varlistentry>
232
252
    </variablelist>
233
253
  </refsect1>
234
 
  
 
254
 
235
255
  <refsect1 id="overview">
236
256
    <title>OVERVIEW</title>
237
257
    <xi:include href="overview.xml"/>
238
258
    <para>
239
259
      This program is the server part.  It is a normal server program
240
260
      and will run in a normal system environment, not in an initial
241
 
      <acronym>RAM</acronym> disk environment.
 
261
      RAM disk environment.
242
262
    </para>
243
263
  </refsect1>
244
 
  
 
264
 
245
265
  <refsect1 id="protocol">
246
266
    <title>NETWORK PROTOCOL</title>
247
267
    <para>
299
319
      </row>
300
320
    </tbody></tgroup></table>
301
321
  </refsect1>
302
 
  
 
322
 
303
323
  <refsect1 id="checking">
304
324
    <title>CHECKING</title>
305
325
    <para>
313
333
      <manvolnum>5</manvolnum></citerefentry>.
314
334
    </para>
315
335
  </refsect1>
316
 
  
 
336
 
317
337
  <refsect1 id="logging">
318
338
    <title>LOGGING</title>
319
339
    <para>
323
343
      and also show them on the console.
324
344
    </para>
325
345
  </refsect1>
326
 
  
 
346
 
327
347
  <refsect1 id="exit_status">
328
348
    <title>EXIT STATUS</title>
329
349
    <para>
331
351
      critical error is encountered.
332
352
    </para>
333
353
  </refsect1>
334
 
  
 
354
 
335
355
  <refsect1 id="environment">
336
356
    <title>ENVIRONMENT</title>
337
357
    <variablelist>
351
371
      </varlistentry>
352
372
    </variablelist>
353
373
  </refsect1>
354
 
  
355
 
  <refsect1 id="files">
 
374
 
 
375
  <refsect1 id="file">
356
376
    <title>FILES</title>
357
377
    <para>
358
378
      Use the <option>--configdir</option> option to change where
381
401
        </listitem>
382
402
      </varlistentry>
383
403
      <varlistentry>
384
 
        <term><filename>/var/run/mandos.pid</filename></term>
 
404
        <term><filename>/var/run/mandos/mandos.pid</filename></term>
385
405
        <listitem>
386
406
          <para>
387
407
            The file containing the process id of
422
442
      Currently, if a client is declared <quote>invalid</quote> due to
423
443
      having timed out, the server does not record this fact onto
424
444
      permanent storage.  This has some security implications, see
425
 
      <xref linkend="clients"/>.
 
445
      <xref linkend="CLIENTS"/>.
426
446
    </para>
427
447
    <para>
428
448
      There is currently no way of querying the server of the current
436
456
      Debug mode is conflated with running in the foreground.
437
457
    </para>
438
458
    <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.
 
459
      The console log messages does not show a timestamp.
444
460
    </para>
445
461
  </refsect1>
446
462
  
481
497
      </para>
482
498
    </informalexample>
483
499
  </refsect1>
484
 
  
 
500
 
485
501
  <refsect1 id="security">
486
502
    <title>SECURITY</title>
487
 
    <refsect2 id="server">
 
503
    <refsect2 id="SERVER">
488
504
      <title>SERVER</title>
489
505
      <para>
490
506
        Running this <command>&COMMANDNAME;</command> server program
491
507
        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.
 
508
        computer running it.  The program does not need any special
 
509
        privileges to run, and is designed to run as a non-root user.
494
510
      </para>
495
511
    </refsect2>
496
 
    <refsect2 id="clients">
 
512
    <refsect2 id="CLIENTS">
497
513
      <title>CLIENTS</title>
498
514
      <para>
499
515
        The server only gives out its stored data to clients which
506
522
        <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
507
523
        <manvolnum>5</manvolnum></citerefentry>)
508
524
        <emphasis>must</emphasis> be made non-readable by anyone
509
 
        except the user starting the server (usually root).
 
525
        except the user running the server.
510
526
      </para>
511
527
      <para>
512
528
        As detailed in <xref linkend="checking"/>, the status of all
523
539
        restarting servers if it is suspected that a client has, in
524
540
        fact, been compromised by parties who may now be running a
525
541
        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
 
542
        initial RAM image of the client host.  What should be done in
 
543
        that case (if restarting the server program really is
 
544
        necessary) is to stop the server program, edit the
529
545
        configuration file to omit any suspect clients, and restart
530
546
        the server program.
531
547
      </para>
532
548
      <para>
533
549
        For more details on client-side security, see
534
 
        <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
550
        <citerefentry><refentrytitle>password-request</refentrytitle>
535
551
        <manvolnum>8mandos</manvolnum></citerefentry>.
536
552
      </para>
537
553
    </refsect2>
538
554
  </refsect1>
539
 
  
 
555
 
540
556
  <refsect1 id="see_also">
541
557
    <title>SEE ALSO</title>
542
558
    <para>
545
561
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
546
562
        <refentrytitle>mandos.conf</refentrytitle>
547
563
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
548
 
        <refentrytitle>mandos-client</refentrytitle>
 
564
        <refentrytitle>password-request</refentrytitle>
549
565
        <manvolnum>8mandos</manvolnum></citerefentry>, <citerefentry>
550
566
        <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
551
567
      </citerefentry>