/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.conf.xml

  • Committer: Teddy Hogeborn
  • Date: 2019-07-29 16:35:53 UTC
  • Revision ID: teddy@recompile.se-20190729163553-1i442i2cbx64c537
Make tests and man page examples match

Make the tests test_manual_page_example[1-5] match exactly what is
written in the manual page, and add comments to manual page as
reminders to keep tests and manual page examples in sync.

* mandos-ctl (Test_commands_from_options.test_manual_page_example_1):
  Remove "--verbose" option, since the manual does not have it as the
  first example, and change assertion to match.
* mandos-ctl.xml (EXAMPLE): Add comments to all examples documenting
  which test function they correspond to.  Also remove unnecessary
  quotes from option arguments in fourth example, and clarify language
  slightly in fifth example.

Show diffs side-by-side

added added

removed removed

Lines of Context:
mandos.conf.xml
1
 
<?xml version='1.0' encoding='UTF-8'?>
 
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 CONFNAME "mandos.conf">
6
5
<!ENTITY CONFPATH "<filename>/etc/mandos/mandos.conf</filename>">
7
 
<!ENTITY OVERVIEW SYSTEM "overview.xml">
 
6
<!ENTITY TIMESTAMP "2019-06-20">
 
7
<!ENTITY % common SYSTEM "common.ent">
 
8
%common;
8
9
]>
9
10
 
10
11
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
11
12
  <refentryinfo>
12
 
    <title>&CONFNAME;</title>
 
13
    <title>Mandos Manual</title>
13
14
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
14
 
    <productname>&CONFNAME;</productname>
15
 
    <productnumber>&VERSION;</productnumber>
 
15
    <productname>Mandos</productname>
 
16
    <productnumber>&version;</productnumber>
 
17
    <date>&TIMESTAMP;</date>
16
18
    <authorgroup>
17
19
      <author>
18
20
        <firstname>Björn</firstname>
19
21
        <surname>Påhlsson</surname>
20
22
        <address>
21
 
          <email>belorn@fukt.bsnet.se</email>
 
23
          <email>belorn@recompile.se</email>
22
24
        </address>
23
25
      </author>
24
26
      <author>
25
27
        <firstname>Teddy</firstname>
26
28
        <surname>Hogeborn</surname>
27
29
        <address>
28
 
          <email>teddy@fukt.bsnet.se</email>
 
30
          <email>teddy@recompile.se</email>
29
31
        </address>
30
32
      </author>
31
33
    </authorgroup>
32
34
    <copyright>
33
35
      <year>2008</year>
 
36
      <year>2009</year>
 
37
      <year>2010</year>
 
38
      <year>2011</year>
 
39
      <year>2012</year>
 
40
      <year>2013</year>
 
41
      <year>2014</year>
 
42
      <year>2015</year>
 
43
      <year>2016</year>
 
44
      <year>2017</year>
 
45
      <year>2018</year>
 
46
      <year>2019</year>
34
47
      <holder>Teddy Hogeborn</holder>
35
48
      <holder>Björn Påhlsson</holder>
36
49
    </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>
 
50
    <xi:include href="legalnotice.xml"/>
60
51
  </refentryinfo>
61
 
 
 
52
  
62
53
  <refmeta>
63
54
    <refentrytitle>&CONFNAME;</refentrytitle>
64
55
    <manvolnum>5</manvolnum>
70
61
      Configuration file for the Mandos server
71
62
    </refpurpose>
72
63
  </refnamediv>
73
 
 
 
64
  
74
65
  <refsynopsisdiv>
75
 
    <synopsis>
76
 
      &CONFPATH;
77
 
    </synopsis>
 
66
    <synopsis>&CONFPATH;</synopsis>
78
67
  </refsynopsisdiv>
79
 
 
 
68
  
80
69
  <refsect1 id="description">
81
70
    <title>DESCRIPTION</title>
82
71
    <para>
83
72
      The file &CONFPATH; is a simple configuration file for
84
73
      <citerefentry><refentrytitle>mandos</refentrytitle>
85
74
      <manvolnum>8</manvolnum></citerefentry>, and is read by it at
86
 
      startup.  The configuration file starts with
87
 
      <quote><literal>[DEFAULT]</literal></quote> on a line by itself,
88
 
      followed by any number of
89
 
      <quote><varname><replaceable>option</replaceable></varname>=<replaceable>value</replaceable></quote>
90
 
      entries, with continuations in the style of RFC 822.
91
 
      <quote><varname><replaceable>option</replaceable></varname>:
92
 
      <replaceable>value</replaceable></quote> is also accepted.  Note
93
 
      that leading whitespace is removed from values.  Lines beginning
94
 
      with <quote>#</quote> or <quote>;</quote> are ignored and may be
95
 
      used to provide comments.
 
75
      startup.  The configuration file starts with <quote><literal
 
76
      >[DEFAULT]</literal></quote> on a line by itself, followed by
 
77
      any number of <quote><varname><replaceable>option</replaceable
 
78
      ></varname>=<replaceable>value</replaceable></quote> entries,
 
79
      with continuations in the style of RFC 822.  <quote><varname
 
80
      ><replaceable>option</replaceable></varname>: <replaceable
 
81
      >value</replaceable></quote> is also accepted.  Note that
 
82
      leading whitespace is removed from values.  Lines beginning with
 
83
      <quote>#</quote> or <quote>;</quote> are ignored and may be used
 
84
      to provide comments.
96
85
    </para>
97
 
 
 
86
    
98
87
  </refsect1>
99
88
  <refsect1>
100
89
    <title>OPTIONS</title>
101
90
    
102
91
    <variablelist>
103
92
      <varlistentry>
104
 
        <term><varname>interface</varname></term>
 
93
        <term><option>interface<literal> = </literal><replaceable
 
94
        >NAME</replaceable></option></term>
105
95
        <listitem>
106
 
          <synopsis><literal>interface = </literal><arg
107
 
          choice="plain"><replaceable>IF</replaceable></arg>
108
 
          </synopsis>
109
96
          <xi:include href="mandos-options.xml" xpointer="interface"/>
110
97
        </listitem>
111
98
      </varlistentry>
112
 
 
 
99
      
113
100
      <varlistentry>
114
 
        <term><varname>address</varname></term>
 
101
        <term><option>address<literal> = </literal><replaceable
 
102
          >ADDRESS</replaceable></option></term>
115
103
        <listitem>
116
 
          <synopsis><literal>address = </literal><arg
117
 
          choice="plain"><replaceable>ADDRESS</replaceable></arg>
118
 
          </synopsis>
119
104
          <xi:include href="mandos-options.xml" xpointer="address"/>
120
105
        </listitem>
121
106
      </varlistentry>
122
 
 
 
107
      
123
108
      <varlistentry>
124
 
        <term><varname>port</varname></term>
 
109
        <term><option>port<literal> = </literal><replaceable
 
110
        >NUMBER</replaceable></option></term>
125
111
        <listitem>
126
 
          <synopsis><literal>port = </literal><arg
127
 
          choice="plain"><replaceable>PORT</replaceable></arg>
128
 
          </synopsis>
129
112
          <xi:include href="mandos-options.xml" xpointer="port"/>
130
113
        </listitem>
131
114
      </varlistentry>
132
 
 
 
115
      
133
116
      <varlistentry>
134
 
        <term><varname>debug</varname></term>
 
117
        <term><option>debug<literal> = </literal>{ <literal
 
118
          >1</literal> | <literal>yes</literal> | <literal
 
119
          >true</literal> | <literal>on</literal> | <literal
 
120
          >0</literal> | <literal>no</literal> | <literal
 
121
          >false</literal> | <literal>off</literal> }</option></term>
135
122
        <listitem>
136
 
          <synopsis><literal>debug =</literal><group choice="req">
137
 
            <arg choice="plain">1</arg>
138
 
            <arg choice="plain">yes</arg>
139
 
            <arg choice="plain">true</arg>
140
 
            <arg choice="plain">on</arg>
141
 
            <arg choice="plain">0</arg>
142
 
            <arg choice="plain">no</arg>
143
 
            <arg choice="plain">false</arg>
144
 
            <arg choice="plain">off</arg>
145
 
          </group>
146
 
          </synopsis>
147
123
          <xi:include href="mandos-options.xml" xpointer="debug"/>
148
124
        </listitem>
149
125
      </varlistentry>
150
 
 
 
126
      
151
127
      <varlistentry>
152
 
        <term><varname>priority</varname></term>
 
128
        <term><option>priority<literal> = </literal><replaceable
 
129
        >STRING</replaceable></option></term>
153
130
        <listitem>
154
 
          <synopsis><literal>priority = </literal><arg
155
 
          choice="plain"><replaceable>PRIORITY</replaceable></arg>
156
 
          </synopsis>
157
131
          <xi:include href="mandos-options.xml" xpointer="priority"/>
158
132
        </listitem>
159
133
      </varlistentry>
160
 
 
 
134
      
161
135
      <varlistentry>
162
 
        <term><varname>servicename</varname></term>
163
 
          <synopsis><literal>servicename = </literal><arg
164
 
          choice="plain"><replaceable>NAME</replaceable></arg>
165
 
          </synopsis>
 
136
        <term><option>servicename<literal> = </literal
 
137
        ><replaceable>NAME</replaceable></option></term>
166
138
        <listitem>
167
139
          <xi:include href="mandos-options.xml"
168
140
                      xpointer="servicename"/>
169
141
        </listitem>
170
142
      </varlistentry>
171
143
      
 
144
      <varlistentry>
 
145
        <term><option>use_dbus<literal> = </literal>{ <literal
 
146
          >1</literal> | <literal>yes</literal> | <literal
 
147
          >true</literal> | <literal>on</literal> | <literal
 
148
          >0</literal> | <literal>no</literal> | <literal
 
149
          >false</literal> | <literal>off</literal> }</option></term>
 
150
        <listitem>
 
151
          <xi:include href="mandos-options.xml" xpointer="dbus"/>
 
152
        </listitem>
 
153
      </varlistentry>
 
154
      
 
155
      <varlistentry>
 
156
        <term><option>use_ipv6<literal> = </literal>{ <literal
 
157
          >1</literal> | <literal>yes</literal> | <literal
 
158
          >true</literal> | <literal>on</literal> | <literal
 
159
          >0</literal> | <literal>no</literal> | <literal
 
160
          >false</literal> | <literal>off</literal> }</option></term>
 
161
        <listitem>
 
162
          <xi:include href="mandos-options.xml" xpointer="ipv6"/>
 
163
        </listitem>
 
164
      </varlistentry>
 
165
      
 
166
      <varlistentry>
 
167
        <term><option>restore<literal> = </literal>{ <literal
 
168
          >1</literal> | <literal>yes</literal> | <literal
 
169
          >true</literal> | <literal>on</literal> | <literal
 
170
          >0</literal> | <literal>no</literal> | <literal
 
171
          >false</literal> | <literal>off</literal> }</option></term>
 
172
        <listitem>
 
173
          <xi:include href="mandos-options.xml" xpointer="restore"/>
 
174
        </listitem>
 
175
      </varlistentry>
 
176
      
 
177
      <varlistentry>
 
178
        <term><option>statedir<literal> = </literal><replaceable
 
179
        >DIRECTORY</replaceable></option></term>
 
180
        <listitem>
 
181
          <xi:include href="mandos-options.xml" xpointer="statedir"/>
 
182
        </listitem>
 
183
      </varlistentry>
 
184
      
 
185
      <varlistentry>
 
186
        <term><option>socket<literal> = </literal><replaceable
 
187
        >NUMBER</replaceable></option></term>
 
188
        <listitem>
 
189
          <xi:include href="mandos-options.xml" xpointer="socket"/>
 
190
        </listitem>
 
191
      </varlistentry>
 
192
      
172
193
    </variablelist>
173
194
  </refsect1>
174
195
  
183
204
    <title>BUGS</title>
184
205
    <para>
185
206
      The <literal>[DEFAULT]</literal> is necessary because the Python
186
 
      module <systemitem class="library">ConfigParser</systemitem>
187
 
      requres it.
 
207
      built-in module <systemitem class="library">ConfigParser</systemitem>
 
208
      requires it.
188
209
    </para>
 
210
    <xi:include href="bugs.xml"/>
189
211
  </refsect1>
190
212
  
191
213
  <refsect1 id="example">
192
214
    <title>EXAMPLE</title>
193
215
    <informalexample>
 
216
      <para>
 
217
        No options are actually required:
 
218
      </para>
 
219
      <programlisting>
 
220
[DEFAULT]
 
221
      </programlisting>
 
222
    </informalexample>
 
223
    <informalexample>
 
224
      <para>
 
225
        An example using all the options:
 
226
      </para>
194
227
      <programlisting>
195
228
[DEFAULT]
196
229
# A configuration example
197
 
interface = eth0
198
 
address = 2001:db8:f983:bd0b:30de:ae4a:71f2:f672
 
230
interface = enp1s0
 
231
address = fe80::aede:48ff:fe71:f6f2
199
232
port = 1025
200
 
debug = true
201
 
priority = SECURE256:!CTYPE-X.509:+CTYPE-OPENPGP
202
 
servicename = Mandos
 
233
debug = True
 
234
priority = SECURE128:!CTYPE-X.509:+CTYPE-RAWPK:!RSA:!VERS-ALL:+VERS-TLS1.3:%PROFILE_ULTRA
 
235
servicename = Daena
 
236
use_dbus = False
 
237
use_ipv6 = True
 
238
restore = True
 
239
statedir = /var/lib/mandos
203
240
      </programlisting>
204
241
    </informalexample>
205
242
  </refsect1>
 
243
  
 
244
  <refsect1 id="see_also">
 
245
    <title>SEE ALSO</title>
 
246
    <para>
 
247
      <citerefentry><refentrytitle>intro</refentrytitle>
 
248
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
249
      <citerefentry><refentrytitle>gnutls_priority_init</refentrytitle
 
250
      ><manvolnum>3</manvolnum></citerefentry>,
 
251
      <citerefentry><refentrytitle>mandos</refentrytitle>
 
252
      <manvolnum>8</manvolnum></citerefentry>,
 
253
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
 
254
      <manvolnum>5</manvolnum></citerefentry>
 
255
    </para>
 
256
    
 
257
    <variablelist>
 
258
      <varlistentry>
 
259
        <term>
 
260
          RFC 4291: <citetitle>IP Version 6 Addressing
 
261
          Architecture</citetitle>
 
262
        </term>
 
263
        <listitem>
 
264
          <variablelist>
 
265
            <varlistentry>
 
266
              <term>Section 2.2: <citetitle>Text Representation of
 
267
              Addresses</citetitle></term>
 
268
              <listitem><para/></listitem>
 
269
            </varlistentry>
 
270
            <varlistentry>
 
271
              <term>Section 2.5.5.2: <citetitle>IPv4-Mapped IPv6
 
272
              Address</citetitle></term>
 
273
              <listitem><para/></listitem>
 
274
            </varlistentry>
 
275
            <varlistentry>
 
276
            <term>Section 2.5.6, <citetitle>Link-Local IPv6 Unicast
 
277
            Addresses</citetitle></term>
 
278
            <listitem>
 
279
              <para>
 
280
                The clients use IPv6 link-local addresses, which are
 
281
                immediately usable since a link-local addresses is
 
282
                automatically assigned to a network interface when it
 
283
                is brought up.
 
284
              </para>
 
285
            </listitem>
 
286
            </varlistentry>
 
287
          </variablelist>
 
288
        </listitem>
 
289
      </varlistentry>
 
290
      <varlistentry>
 
291
        <term>
 
292
          <ulink url="http://www.zeroconf.org/">Zeroconf</ulink>
 
293
        </term>
 
294
        <listitem>
 
295
          <para>
 
296
            Zeroconf is the network protocol standard used by clients
 
297
            for finding the Mandos server on the local network.
 
298
          </para>
 
299
        </listitem>
 
300
      </varlistentry>
 
301
    </variablelist>
 
302
  </refsect1>
206
303
</refentry>
 
304
<!-- Local Variables: -->
 
305
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
 
306
<!-- time-stamp-end: "[\"']>" -->
 
307
<!-- time-stamp-format: "%:y-%02m-%02d" -->
 
308
<!-- End: -->