/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

* mandos (Client.timeout, Client.interval): Changed from being a
                                            property to be a normal
                                            attribute.
  (Client._timeout, Client._interval): Removed.
  (Client._timeout_milliseconds): Changed from being an attribute to
                                  be a method "timeout_milliseconds".
                                  All users changed.
  (Client._interval_milliseconds): Changed from being an attribute to
                                   be method "interval_milliseconds".
                                   All users changed.
  (Client.__init__): Take additional "use_dbus" keyword argument.
                     Only provide D-Bus interface if "use_dbus" is
                     True.
  (Client.use_dbus): New attribute.
  (Client.dbus_object_path): Changed to only be set if "self.use_dbus"
                             is True.
  (Client.enable, Client.disable, Client.checker_callback,
  Client.bump_timeout, Client.start_checker, Client.stop_checker):
  Only emit D-Bus signals if "self.use_dbus".
  (Client.SetChecker, Client.SetHost, Client.Enable): Bug fix: Emit
                                                      D-Bus signals.
  (Client.SetInterval, Client.SetTimeout): Changed to emit D-Bus
                                           signals.

  (main): Remove deprecated "default" keyword argument to "--check"
          option.  Added new "--no-dbus" option.  Added corresponding
          "use_dbus" server configuration option.  Only provide D-Bus
          interface and emit D-Bus signals if "use_dbus".  Pass
          "use_dbus" on to Client constructor.

* mandos-options.xml ([@id="dbus"]): New option.

* mandos.conf (use_dbus): New option.

* mandos.conf.xml (OPTIONS): New option "use_dbus".
  (EXAMPLE): - '' -

* mandos.xml (SYNOPSIS): New option "--no-dbus".
  (D-BUS INTERFACE): New section.

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">
5
4
<!ENTITY COMMANDNAME "mandos">
6
 
<!ENTITY TIMESTAMP "2008-08-30">
 
5
<!ENTITY TIMESTAMP "2008-12-28">
 
6
<!ENTITY % common SYSTEM "common.ent">
 
7
%common;
7
8
]>
8
9
 
9
10
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
10
 
  <refentryinfo>
 
11
   <refentryinfo>
11
12
    <title>Mandos Manual</title>
12
13
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
13
14
    <productname>Mandos</productname>
14
 
    <productnumber>&VERSION;</productnumber>
 
15
    <productnumber>&version;</productnumber>
15
16
    <date>&TIMESTAMP;</date>
16
17
    <authorgroup>
17
18
      <author>
34
35
      <holder>Teddy Hogeborn</holder>
35
36
      <holder>Björn Påhlsson</holder>
36
37
    </copyright>
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>
 
38
    <xi:include href="legalnotice.xml"/>
60
39
  </refentryinfo>
61
 
 
 
40
  
62
41
  <refmeta>
63
42
    <refentrytitle>&COMMANDNAME;</refentrytitle>
64
43
    <manvolnum>8</manvolnum>
70
49
      Gives encrypted passwords to authenticated Mandos clients
71
50
    </refpurpose>
72
51
  </refnamediv>
73
 
 
 
52
  
74
53
  <refsynopsisdiv>
75
54
    <cmdsynopsis>
76
55
      <command>&COMMANDNAME;</command>
105
84
      <replaceable>DIRECTORY</replaceable></option></arg>
106
85
      <sbr/>
107
86
      <arg><option>--debug</option></arg>
 
87
      <sbr/>
 
88
      <arg><option>--no-dbus</option></arg>
108
89
    </cmdsynopsis>
109
90
    <cmdsynopsis>
110
91
      <command>&COMMANDNAME;</command>
111
92
      <group choice="req">
 
93
        <arg choice="plain"><option>--help</option></arg>
112
94
        <arg choice="plain"><option>-h</option></arg>
113
 
        <arg choice="plain"><option>--help</option></arg>
114
95
      </group>
115
96
    </cmdsynopsis>
116
97
    <cmdsynopsis>
122
103
      <arg choice="plain"><option>--check</option></arg>
123
104
    </cmdsynopsis>
124
105
  </refsynopsisdiv>
125
 
 
 
106
  
126
107
  <refsect1 id="description">
127
108
    <title>DESCRIPTION</title>
128
109
    <para>
137
118
      Any authenticated client is then given the stored pre-encrypted
138
119
      password for that specific client.
139
120
    </para>
140
 
 
141
121
  </refsect1>
142
122
  
143
123
  <refsect1 id="purpose">
144
124
    <title>PURPOSE</title>
145
 
 
146
125
    <para>
147
126
      The purpose of this is to enable <emphasis>remote and unattended
148
127
      rebooting</emphasis> of client host computer with an
149
128
      <emphasis>encrypted root file system</emphasis>.  See <xref
150
129
      linkend="overview"/> for details.
151
130
    </para>
152
 
 
153
131
  </refsect1>
154
132
  
155
133
  <refsect1 id="options">
156
134
    <title>OPTIONS</title>
157
 
 
158
135
    <variablelist>
159
136
      <varlistentry>
 
137
        <term><option>--help</option></term>
160
138
        <term><option>-h</option></term>
161
 
        <term><option>--help</option></term>
162
139
        <listitem>
163
140
          <para>
164
141
            Show a help message and exit
165
142
          </para>
166
143
        </listitem>
167
144
      </varlistentry>
168
 
 
 
145
      
169
146
      <varlistentry>
 
147
        <term><option>--interface</option>
 
148
        <replaceable>NAME</replaceable></term>
170
149
        <term><option>-i</option>
171
150
        <replaceable>NAME</replaceable></term>
172
 
        <term><option>--interface</option>
173
 
        <replaceable>NAME</replaceable></term>
174
151
        <listitem>
175
152
          <xi:include href="mandos-options.xml" xpointer="interface"/>
176
153
        </listitem>
177
154
      </varlistentry>
178
 
 
 
155
      
179
156
      <varlistentry>
180
 
        <term><literal>-a</literal>, <literal>--address <replaceable>
181
 
        ADDRESS</replaceable></literal></term>
 
157
        <term><option>--address
 
158
        <replaceable>ADDRESS</replaceable></option></term>
 
159
        <term><option>-a
 
160
        <replaceable>ADDRESS</replaceable></option></term>
182
161
        <listitem>
183
162
          <xi:include href="mandos-options.xml" xpointer="address"/>
184
163
        </listitem>
185
164
      </varlistentry>
186
 
 
 
165
      
187
166
      <varlistentry>
188
 
        <term><literal>-p</literal>, <literal>--port <replaceable>
189
 
        PORT</replaceable></literal></term>
 
167
        <term><option>--port
 
168
        <replaceable>PORT</replaceable></option></term>
 
169
        <term><option>-p
 
170
        <replaceable>PORT</replaceable></option></term>
190
171
        <listitem>
191
172
          <xi:include href="mandos-options.xml" xpointer="port"/>
192
173
        </listitem>
193
174
      </varlistentry>
194
 
 
 
175
      
195
176
      <varlistentry>
196
 
        <term><literal>--check</literal></term>
 
177
        <term><option>--check</option></term>
197
178
        <listitem>
198
179
          <para>
199
180
            Run the server’s self-tests.  This includes any unit
201
182
          </para>
202
183
        </listitem>
203
184
      </varlistentry>
204
 
 
 
185
      
205
186
      <varlistentry>
206
 
        <term><literal>--debug</literal></term>
 
187
        <term><option>--debug</option></term>
207
188
        <listitem>
208
189
          <xi:include href="mandos-options.xml" xpointer="debug"/>
209
190
        </listitem>
210
191
      </varlistentry>
211
 
 
 
192
      
212
193
      <varlistentry>
213
 
        <term><literal>--priority <replaceable>
214
 
        PRIORITY</replaceable></literal></term>
 
194
        <term><option>--priority <replaceable>
 
195
        PRIORITY</replaceable></option></term>
215
196
        <listitem>
216
197
          <xi:include href="mandos-options.xml" xpointer="priority"/>
217
198
        </listitem>
218
199
      </varlistentry>
219
 
 
 
200
      
220
201
      <varlistentry>
221
 
        <term><literal>--servicename <replaceable>NAME</replaceable>
222
 
        </literal></term>
 
202
        <term><option>--servicename
 
203
        <replaceable>NAME</replaceable></option></term>
223
204
        <listitem>
224
205
          <xi:include href="mandos-options.xml"
225
206
                      xpointer="servicename"/>
226
207
        </listitem>
227
208
      </varlistentry>
228
 
 
 
209
      
229
210
      <varlistentry>
230
 
        <term><literal>--configdir <replaceable>DIR</replaceable>
231
 
        </literal></term>
 
211
        <term><option>--configdir
 
212
        <replaceable>DIRECTORY</replaceable></option></term>
232
213
        <listitem>
233
214
          <para>
234
215
            Directory to search for configuration files.  Default is
240
221
          </para>
241
222
        </listitem>
242
223
      </varlistentry>
243
 
 
 
224
      
244
225
      <varlistentry>
245
 
        <term><literal>--version</literal></term>
 
226
        <term><option>--version</option></term>
246
227
        <listitem>
247
228
          <para>
248
229
            Prints the program version and exit.
249
230
          </para>
250
231
        </listitem>
251
232
      </varlistentry>
 
233
      
 
234
      <varlistentry>
 
235
        <term><option>--no-dbus</option></term>
 
236
        <listitem>
 
237
          <xi:include href="mandos-options.xml" xpointer="dbus"/>
 
238
          <para>
 
239
            See also <xref linkend="dbus"/>.
 
240
        </listitem>
 
241
      </varlistentry>
252
242
    </variablelist>
253
243
  </refsect1>
254
 
 
 
244
  
255
245
  <refsect1 id="overview">
256
246
    <title>OVERVIEW</title>
257
247
    <xi:include href="overview.xml"/>
258
248
    <para>
259
249
      This program is the server part.  It is a normal server program
260
250
      and will run in a normal system environment, not in an initial
261
 
      RAM disk environment.
 
251
      <acronym>RAM</acronym> disk environment.
262
252
    </para>
263
253
  </refsect1>
264
 
 
 
254
  
265
255
  <refsect1 id="protocol">
266
256
    <title>NETWORK PROTOCOL</title>
267
257
    <para>
319
309
      </row>
320
310
    </tbody></tgroup></table>
321
311
  </refsect1>
322
 
 
 
312
  
323
313
  <refsect1 id="checking">
324
314
    <title>CHECKING</title>
325
315
    <para>
333
323
      <manvolnum>5</manvolnum></citerefentry>.
334
324
    </para>
335
325
  </refsect1>
336
 
 
 
326
  
337
327
  <refsect1 id="logging">
338
328
    <title>LOGGING</title>
339
329
    <para>
343
333
      and also show them on the console.
344
334
    </para>
345
335
  </refsect1>
 
336
  
 
337
  <refsect1 id="dbus">
 
338
    <title>D-BUS INTERFACE</title>
 
339
    <para>
 
340
      The server will by default provide a D-Bus system bus interface.
 
341
      This interface will only be accessible by the root user or a
 
342
      Mandos-specific user, if such a user exists.
 
343
      <!-- XXX -->
 
344
    </para>
 
345
  </refsect1>
346
346
 
347
347
  <refsect1 id="exit_status">
348
348
    <title>EXIT STATUS</title>
351
351
      critical error is encountered.
352
352
    </para>
353
353
  </refsect1>
354
 
 
 
354
  
355
355
  <refsect1 id="environment">
356
356
    <title>ENVIRONMENT</title>
357
357
    <variablelist>
371
371
      </varlistentry>
372
372
    </variablelist>
373
373
  </refsect1>
374
 
 
375
 
  <refsect1 id="file">
 
374
  
 
375
  <refsect1 id="files">
376
376
    <title>FILES</title>
377
377
    <para>
378
378
      Use the <option>--configdir</option> option to change where
401
401
        </listitem>
402
402
      </varlistentry>
403
403
      <varlistentry>
404
 
        <term><filename>/var/run/mandos/mandos.pid</filename></term>
 
404
        <term><filename>/var/run/mandos.pid</filename></term>
405
405
        <listitem>
406
406
          <para>
407
407
            The file containing the process id of
442
442
      Currently, if a client is declared <quote>invalid</quote> due to
443
443
      having timed out, the server does not record this fact onto
444
444
      permanent storage.  This has some security implications, see
445
 
      <xref linkend="CLIENTS"/>.
 
445
      <xref linkend="clients"/>.
446
446
    </para>
447
447
    <para>
448
448
      There is currently no way of querying the server of the current
456
456
      Debug mode is conflated with running in the foreground.
457
457
    </para>
458
458
    <para>
459
 
      The console log messages does not show a timestamp.
 
459
      The console log messages does not show a time stamp.
 
460
    </para>
 
461
    <para>
 
462
      This server does not check the expire time of clients’ OpenPGP
 
463
      keys.
460
464
    </para>
461
465
  </refsect1>
462
466
  
497
501
      </para>
498
502
    </informalexample>
499
503
  </refsect1>
500
 
 
 
504
  
501
505
  <refsect1 id="security">
502
506
    <title>SECURITY</title>
503
 
    <refsect2 id="SERVER">
 
507
    <refsect2 id="server">
504
508
      <title>SERVER</title>
505
509
      <para>
506
510
        Running this <command>&COMMANDNAME;</command> server program
507
511
        should not in itself present any security risk to the host
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.
 
512
        computer running it.  The program switches to a non-root user
 
513
        soon after startup.
510
514
      </para>
511
515
    </refsect2>
512
 
    <refsect2 id="CLIENTS">
 
516
    <refsect2 id="clients">
513
517
      <title>CLIENTS</title>
514
518
      <para>
515
519
        The server only gives out its stored data to clients which
522
526
        <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
523
527
        <manvolnum>5</manvolnum></citerefentry>)
524
528
        <emphasis>must</emphasis> be made non-readable by anyone
525
 
        except the user running the server.
 
529
        except the user starting the server (usually root).
526
530
      </para>
527
531
      <para>
528
532
        As detailed in <xref linkend="checking"/>, the status of all
539
543
        restarting servers if it is suspected that a client has, in
540
544
        fact, been compromised by parties who may now be running a
541
545
        fake Mandos client with the keys from the non-encrypted
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
 
546
        initial <acronym>RAM</acronym> image of the client host.  What
 
547
        should be done in that case (if restarting the server program
 
548
        really is necessary) is to stop the server program, edit the
545
549
        configuration file to omit any suspect clients, and restart
546
550
        the server program.
547
551
      </para>
548
552
      <para>
549
553
        For more details on client-side security, see
550
 
        <citerefentry><refentrytitle>password-request</refentrytitle>
 
554
        <citerefentry><refentrytitle>mandos-client</refentrytitle>
551
555
        <manvolnum>8mandos</manvolnum></citerefentry>.
552
556
      </para>
553
557
    </refsect2>
554
558
  </refsect1>
555
 
 
 
559
  
556
560
  <refsect1 id="see_also">
557
561
    <title>SEE ALSO</title>
558
562
    <para>
561
565
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
562
566
        <refentrytitle>mandos.conf</refentrytitle>
563
567
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
564
 
        <refentrytitle>password-request</refentrytitle>
 
568
        <refentrytitle>mandos-client</refentrytitle>
565
569
        <manvolnum>8mandos</manvolnum></citerefentry>, <citerefentry>
566
570
        <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
567
571
      </citerefentry>