]>
Commit | Line | Data |
---|---|---|
c4bb26b8 TB |
1 | .TH STRONGSWAN.CONF 5 "" "@PACKAGE_VERSION@" "strongSwan" |
2 | .SH NAME | |
3 | strongswan.conf \- strongSwan configuration file | |
4 | .SH DESCRIPTION | |
5 | While the | |
6 | .IR ipsec.conf (5) | |
7 | configuration file is well suited to define IPsec related configuration | |
8 | parameters, it is not useful for other strongSwan applications to read options | |
9 | from this file. | |
10 | The file is hard to parse and only | |
11 | .I ipsec starter | |
12 | is capable of doing so. As the number of components of the strongSwan project | |
13 | is continually growing, a more flexible configuration file was needed, one that | |
14 | is easy to extend and can be used by all components. With strongSwan 4.2.1 | |
15 | .IR strongswan.conf (5) | |
16 | was introduced which meets these requirements. | |
17 | ||
18 | .SH SYNTAX | |
19 | The format of the strongswan.conf file consists of hierarchical | |
20 | .B sections | |
21 | and a list of | |
22 | .B key/value pairs | |
23 | in each section. Each section has a name, followed by C-Style curly brackets | |
24 | defining the section body. Each section body contains a set of subsections | |
25 | and key/value pairs: | |
26 | .PP | |
27 | .EX | |
28 | settings := (section|keyvalue)* | |
29 | section := name { settings } | |
30 | keyvalue := key = value\\n | |
31 | .EE | |
32 | .PP | |
33 | Values must be terminated by a newline. | |
34 | .PP | |
61c3870b | 35 | Comments are possible using the \fB#\fP-character. |
c4bb26b8 TB |
36 | .PP |
37 | Section names and keys may contain any printable character except: | |
38 | .PP | |
39 | .EX | |
61c3870b | 40 | . , : { } = " # \\n \\t space |
c4bb26b8 TB |
41 | .EE |
42 | .PP | |
43 | An example file in this format might look like this: | |
44 | .PP | |
45 | .EX | |
46 | a = b | |
47 | section-one { | |
48 | somevalue = asdf | |
49 | subsection { | |
50 | othervalue = xxx | |
51 | } | |
52 | # yei, a comment | |
53 | yetanother = zz | |
54 | } | |
55 | section-two { | |
56 | x = 12 | |
57 | } | |
58 | .EE | |
59 | .PP | |
60 | Indentation is optional, you may use tabs or spaces. | |
61 | ||
64b10dfb TB |
62 | .SH NUMBER FORMATS |
63 | Options that define an integer value can be specified as decimal (the default) | |
64 | or hexadecimal ("0x" prefix, upper- or lowercase letters are accepted). | |
65 | Locale-dependent strings (e.g. the thousands separator of the current locale) | |
66 | may also be accepted in locales other than "C". | |
67 | .PP | |
68 | Options that define a floating-point value can be specified as decimal (the | |
69 | default) or hexadecimal ("0x" prefix, upper- or lowercase letters are accepted). | |
70 | The radix character (decimal separator) in either case is locale-dependent, | |
71 | usually ".". | |
72 | ||
73 | .SH TIME FORMATS | |
74 | Unless stated otherwise, options that define a time are specified in seconds. | |
75 | The "s", "m", "h" and "d" suffixes may be used to automatically convert values | |
76 | given in seconds, minutes, hours or days (for instance, instead of configuring | |
77 | a rekey time of 4 hours as "14400" seconds, "4h" may be used). | |
78 | .PP | |
79 | There are some global options that don't accept these suffixes as they are | |
80 | configured as integer values in seconds or milliseconds, or even as | |
81 | floating-point numbers (e.g. the retransmission timeout). Options that accept | |
82 | the suffixes have a corresponding default value. | |
61c3870b TB |
83 | |
84 | .SH REFERENCING OTHER SECTIONS | |
85 | It is possible to inherit settings and sections from another section. This | |
86 | feature is mainly useful in swanctl.conf (which uses the same file format). | |
87 | The syntax is as follows: | |
88 | .PP | |
89 | .EX | |
90 | section := name : references { settings } | |
91 | references := absname[, absname]* | |
92 | absname := name[.name]* | |
93 | .EE | |
94 | .PP | |
95 | All key/value pairs and all subsections of the referenced sections will be | |
96 | inherited by the section that references them via their absolute name. Values | |
97 | may be overridden in the section or any of its sub-sections (use an empty | |
98 | assignment to clear a value so its default value, if any, will apply). It is | |
99 | currently not possible to limit the inclusion level or clear/remove inherited | |
100 | sub-sections. | |
101 | ||
102 | If the order is important (e.g. for auth rounds in a connection, if \fIround\fR | |
103 | is not used), it should be noted that inherited settings/sections will follow | |
104 | those defined in the current section (if multiple sections are referenced, their | |
105 | settings are enumerated left to right). | |
106 | ||
107 | References are evaluated dynamically at runtime, so referring to sections later | |
108 | in the config file or included via other files is no problem. | |
109 | ||
110 | Here is an example of how this might look like: | |
111 | .PP | |
112 | .EX | |
113 | conn-defaults { | |
114 | # default settings for all conns (e.g. a cert, or IP pools) | |
115 | } | |
116 | eap-defaults { | |
117 | # defaults if eap is used (e.g. a remote auth round) | |
118 | } | |
119 | child-defaults { | |
120 | # defaults for child configs (e.g. traffic selectors) | |
121 | } | |
122 | connections { | |
123 | conn-a : conn-defaults, eap-defaults { | |
124 | # set/override stuff specific to this connection | |
125 | children { | |
126 | child-a : child-defaults { | |
127 | # set/override stuff specific to this child | |
128 | } | |
129 | } | |
130 | } | |
131 | conn-b : conn-defaults { | |
132 | # set/override stuff specific to this connection | |
133 | children { | |
134 | child-b : child-defaults { | |
135 | # set/override stuff specific to this child | |
136 | } | |
137 | } | |
138 | } | |
139 | conn-c : connections.conn-a { | |
140 | # everything is inherited, including everything conn-a | |
141 | # already inherits from the sections it and its | |
142 | # sub-section reference | |
143 | } | |
144 | } | |
145 | .EE | |
146 | .PP | |
147 | ||
c4bb26b8 TB |
148 | .SH INCLUDING FILES |
149 | Using the | |
150 | .B include | |
151 | statement it is possible to include other files into strongswan.conf, e.g. | |
152 | .PP | |
153 | .EX | |
154 | include /some/path/*.conf | |
155 | .EE | |
156 | .PP | |
157 | If the file name is not an absolute path, it is considered to be relative | |
158 | to the directory of the file containing the include statement. The file name | |
159 | may include shell wildcards (see | |
160 | .IR sh (1)). | |
161 | Also, such inclusions can be nested. | |
162 | .PP | |
163 | Sections loaded from included files | |
164 | .I extend | |
165 | previously loaded sections; already existing values are | |
166 | .IR replaced . | |
167 | It is important to note that settings are added relative to the section the | |
168 | include statement is in. | |
169 | .PP | |
170 | As an example, the following three files result in the same final | |
171 | config as the one given above: | |
172 | .PP | |
173 | .EX | |
174 | a = b | |
175 | section-one { | |
176 | somevalue = before include | |
177 | include include.conf | |
178 | } | |
179 | include other.conf | |
180 | ||
181 | include.conf: | |
182 | # settings loaded from this file are added to section-one | |
183 | # the following replaces the previous value | |
184 | somevalue = asdf | |
185 | subsection { | |
186 | othervalue = yyy | |
187 | } | |
188 | yetanother = zz | |
189 | ||
190 | other.conf: | |
191 | # this extends section-one and subsection | |
192 | section-one { | |
193 | subsection { | |
194 | # this replaces the previous value | |
195 | othervalue = xxx | |
196 | } | |
197 | } | |
198 | section-two { | |
199 | x = 12 | |
200 | } | |
201 | .EE | |
202 | ||
203 | .SH READING VALUES | |
204 | Values are accessed using a dot-separated section list and a key. | |
205 | With reference to the example above, accessing | |
206 | .B section-one.subsection.othervalue | |
207 | will return | |
208 | .BR xxx . | |
209 | ||
210 | .SH DEFINED KEYS | |
211 | The following keys are currently defined (using dot notation). The default | |
212 | value (if any) is listed in brackets after the key. |