]>
Commit | Line | Data |
---|---|---|
b768d6a4 | 1 | .TH IPSEC.CONF 5 "2011-12-14" "@IPSEC_VERSION@" "strongSwan" |
fea5e716 MW |
2 | .SH NAME |
3 | ipsec.conf \- IPsec configuration and connections | |
4 | .SH DESCRIPTION | |
5 | The optional | |
6 | .I ipsec.conf | |
7 | file | |
8 | specifies most configuration and control information for the | |
9 | strongSwan IPsec subsystem. | |
f115838b | 10 | The major exception is secrets for authentication; |
fea5e716 | 11 | see |
f115838b | 12 | .IR ipsec.secrets (5). |
532f2347 | 13 | Its contents are not security-sensitive. |
fea5e716 MW |
14 | .PP |
15 | The file is a text file, consisting of one or more | |
16 | .IR sections . | |
17 | White space followed by | |
18 | .B # | |
19 | followed by anything to the end of the line | |
20 | is a comment and is ignored, | |
21 | as are empty lines which are not within a section. | |
22 | .PP | |
23 | A line which contains | |
24 | .B include | |
25 | and a file name, separated by white space, | |
26 | is replaced by the contents of that file, | |
27 | preceded and followed by empty lines. | |
28 | If the file name is not a full pathname, | |
29 | it is considered to be relative to the directory containing the | |
30 | including file. | |
31 | Such inclusions can be nested. | |
32 | Only a single filename may be supplied, and it may not contain white space, | |
33 | but it may include shell wildcards (see | |
34 | .IR sh (1)); | |
35 | for example: | |
36 | .PP | |
37 | .B include | |
38 | .B "ipsec.*.conf" | |
39 | .PP | |
40 | The intention of the include facility is mostly to permit keeping | |
41 | information on connections, or sets of connections, | |
42 | separate from the main configuration file. | |
43 | This permits such connection descriptions to be changed, | |
44 | copied to the other security gateways involved, etc., | |
45 | without having to constantly extract them from the configuration | |
46 | file and then insert them back into it. | |
47 | Note also the | |
48 | .B also | |
49 | parameter (described below) which permits splitting a single logical | |
50 | section (e.g. a connection description) into several actual sections. | |
51 | .PP | |
fea5e716 MW |
52 | A section |
53 | begins with a line of the form: | |
54 | .PP | |
55 | .I type | |
56 | .I name | |
57 | .PP | |
58 | where | |
59 | .I type | |
60 | indicates what type of section follows, and | |
61 | .I name | |
62 | is an arbitrary name which distinguishes the section from others | |
63 | of the same type. | |
f115838b TB |
64 | Names must start with a letter and may contain only |
65 | letters, digits, periods, underscores, and hyphens. | |
fea5e716 MW |
66 | All subsequent non-empty lines |
67 | which begin with white space are part of the section; | |
68 | comments within a section must begin with white space too. | |
69 | There may be only one section of a given type with a given name. | |
70 | .PP | |
71 | Lines within the section are generally of the form | |
72 | .PP | |
73 | \ \ \ \ \ \fIparameter\fB=\fIvalue\fR | |
74 | .PP | |
75 | (note the mandatory preceding white space). | |
76 | There can be white space on either side of the | |
77 | .BR = . | |
78 | Parameter names follow the same syntax as section names, | |
79 | and are specific to a section type. | |
80 | Unless otherwise explicitly specified, | |
81 | no parameter name may appear more than once in a section. | |
82 | .PP | |
83 | An empty | |
84 | .I value | |
85 | stands for the system default value (if any) of the parameter, | |
86 | i.e. it is roughly equivalent to omitting the parameter line entirely. | |
87 | A | |
88 | .I value | |
89 | may contain white space only if the entire | |
90 | .I value | |
91 | is enclosed in double quotes (\fB"\fR); | |
92 | a | |
93 | .I value | |
94 | cannot itself contain a double quote, | |
95 | nor may it be continued across more than one line. | |
96 | .PP | |
97 | Numeric values are specified to be either an ``integer'' | |
98 | (a sequence of digits) or a ``decimal number'' | |
99 | (sequence of digits optionally followed by `.' and another sequence of digits). | |
100 | .PP | |
101 | There is currently one parameter which is available in any type of | |
102 | section: | |
103 | .TP | |
104 | .B also | |
105 | the value is a section name; | |
106 | the parameters of that section are appended to this section, | |
107 | as if they had been written as part of it. | |
108 | The specified section must exist, must follow the current one, | |
109 | and must have the same section type. | |
110 | (Nesting is permitted, | |
111 | and there may be more than one | |
112 | .B also | |
113 | in a single section, | |
114 | although it is forbidden to append the same section more than once.) | |
fea5e716 MW |
115 | .PP |
116 | A section with name | |
117 | .B %default | |
118 | specifies defaults for sections of the same type. | |
119 | For each parameter in it, | |
120 | any section of that type which does not have a parameter of the same name | |
121 | gets a copy of the one from the | |
122 | .B %default | |
123 | section. | |
124 | There may be multiple | |
125 | .B %default | |
126 | sections of a given type, | |
127 | but only one default may be supplied for any specific parameter name, | |
128 | and all | |
129 | .B %default | |
130 | sections of a given type must precede all non-\c | |
131 | .B %default | |
132 | sections of that type. | |
133 | .B %default | |
134 | sections may not contain the | |
135 | .B also | |
136 | parameter. | |
137 | .PP | |
138 | Currently there are three types of sections: | |
139 | a | |
140 | .B config | |
141 | section specifies general configuration information for IPsec, a | |
142 | .B conn | |
143 | section specifies an IPsec connection, while a | |
144 | .B ca | |
7900ab1b | 145 | section specifies special properties of a certification authority. |
fea5e716 MW |
146 | .SH "CONN SECTIONS" |
147 | A | |
148 | .B conn | |
149 | section contains a | |
150 | .IR "connection specification" , | |
151 | defining a network connection to be made using IPsec. | |
532f2347 | 152 | The name given is arbitrary, and is used to identify the connection. |
fea5e716 MW |
153 | Here's a simple example: |
154 | .PP | |
155 | .ne 10 | |
156 | .nf | |
157 | .ft B | |
158 | .ta 1c | |
159 | conn snt | |
7900ab1b AS |
160 | left=192.168.0.1 |
161 | leftsubnet=10.1.0.0/16 | |
162 | right=192.168.0.2 | |
163 | rightsubnet=10.1.0.0/16 | |
fea5e716 | 164 | keyingtries=%forever |
7900ab1b | 165 | auto=add |
fea5e716 MW |
166 | .ft |
167 | .fi | |
168 | .PP | |
532f2347 | 169 | A note on terminology: There are two kinds of communications going on: |
fea5e716 MW |
170 | transmission of user IP packets, and gateway-to-gateway negotiations for |
171 | keying, rekeying, and general control. | |
f115838b TB |
172 | The path to control the connection is called 'ISAKMP SA' in IKEv1 |
173 | and 'IKE SA' in the IKEv2 protocol. That what is being negotiated, the kernel | |
174 | level data path, is called 'IPsec SA' or 'Child SA'. | |
75e3d90d MW |
175 | strongSwan previously used two separate keying daemons, \fIpluto\fP and |
176 | \fIcharon\fP. This manual does not discuss \fIpluto\fP options anymore, but | |
177 | only \fIcharon\fP that since strongSwan 5.0 supports both IKEv1 and IKEv2. | |
fea5e716 MW |
178 | .PP |
179 | To avoid trivial editing of the configuration file to suit it to each system | |
180 | involved in a connection, | |
181 | connection specifications are written in terms of | |
182 | .I left | |
183 | and | |
184 | .I right | |
185 | participants, | |
186 | rather than in terms of local and remote. | |
187 | Which participant is considered | |
188 | .I left | |
189 | or | |
190 | .I right | |
191 | is arbitrary; | |
f115838b TB |
192 | for every connection description an attempt is made to figure out whether |
193 | the local endpoint should act as the | |
194 | .I left | |
195 | or | |
196 | .I right | |
197 | endpoint. This is done by matching the IP addresses defined for both endpoints | |
198 | with the IP addresses assigned to local network interfaces. If a match is found | |
199 | then the role (left or right) that matches is going to be considered local. | |
200 | If no match is found during startup, | |
201 | .I left | |
202 | is considered local. | |
fea5e716 MW |
203 | This permits using identical connection specifications on both ends. |
204 | There are cases where there is no symmetry; a good convention is to | |
205 | use | |
206 | .I left | |
207 | for the local side and | |
208 | .I right | |
209 | for the remote side (the first letters are a good mnemonic). | |
210 | .PP | |
211 | Many of the parameters relate to one participant or the other; | |
212 | only the ones for | |
213 | .I left | |
214 | are listed here, but every parameter whose name begins with | |
215 | .B left | |
216 | has a | |
217 | .B right | |
218 | counterpart, | |
219 | whose description is the same but with | |
220 | .B left | |
221 | and | |
222 | .B right | |
223 | reversed. | |
224 | .PP | |
532f2347 MW |
225 | Parameters are optional unless marked '(required)'. |
226 | .SS "CONN PARAMETERS" | |
227 | Unless otherwise noted, for a connection to work, | |
fea5e716 MW |
228 | in general it is necessary for the two ends to agree exactly |
229 | on the values of these parameters. | |
6bcf6016 TB |
230 | .TP |
231 | .BR aaa_identity " = <id>" | |
64d7b073 MW |
232 | defines the identity of the AAA backend used during IKEv2 EAP authentication. |
233 | This is required if the EAP client uses a method that verifies the server | |
234 | identity (such as EAP-TLS), but it does not match the IKEv2 gateway identity. | |
235 | .TP | |
a5477a6f TB |
236 | .BR also " = <name>" |
237 | includes conn section | |
238 | .BR <name> . | |
fea5e716 | 239 | .TP |
c8d46f29 | 240 | .BR authby " = " pubkey " | rsasig | ecdsasig | psk | never | xauthpsk | xauthrsasig" |
fea5e716 MW |
241 | how the two security gateways should authenticate each other; |
242 | acceptable values are | |
7900ab1b | 243 | .B psk |
a5477a6f TB |
244 | or |
245 | .B secret | |
c7f76958 AS |
246 | for pre-shared secrets, |
247 | .B pubkey | |
248 | (the default) for public key signatures as well as the synonyms | |
fea5e716 | 249 | .B rsasig |
c7f76958 AS |
250 | for RSA digital signatures and |
251 | .B ecdsasig | |
252 | for Elliptic Curve DSA signatures. | |
fea5e716 | 253 | .B never |
c7f76958 AS |
254 | can be used if negotiation is never to be attempted or accepted (useful for |
255 | shunt-only conns). | |
8015c91c | 256 | Digital signatures are superior in every way to shared secrets. |
7900ab1b AS |
257 | IKEv1 additionally supports the values |
258 | .B xauthpsk | |
259 | and | |
260 | .B xauthrsasig | |
261 | that will enable eXtended AUTHentication (XAUTH) in addition to IKEv1 main mode | |
c8d46f29 | 262 | based on shared secrets or digital RSA signatures, respectively. |
75e3d90d MW |
263 | This parameter is deprecated, as two peers do not need to agree on an |
264 | authentication method in IKEv2. Use the | |
a44bb934 | 265 | .B leftauth |
75e3d90d | 266 | parameter instead to define authentication methods. |
fea5e716 | 267 | .TP |
6bcf6016 | 268 | .BR auto " = " ignore " | add | route | start" |
c2bc2b27 AS |
269 | what operation, if any, should be done automatically at IPsec startup; |
270 | currently-accepted values are | |
f115838b TB |
271 | .BR add , |
272 | .BR route , | |
c2bc2b27 | 273 | .B start |
7900ab1b | 274 | and |
f115838b TB |
275 | .B ignore |
276 | (the default). | |
c2bc2b27 AS |
277 | .B add |
278 | loads a connection without starting it. | |
279 | .B route | |
280 | loads a connection and installs kernel traps. If traffic is detected between | |
281 | .B leftsubnet | |
282 | and | |
283 | .B rightsubnet | |
284 | , a connection is established. | |
285 | .B start | |
f3bb1bd0 | 286 | loads a connection and brings it up immediately. |
c2bc2b27 AS |
287 | .B ignore |
288 | ignores the connection. This is equal to delete a connection from the config | |
8015c91c | 289 | file. |
c2bc2b27 AS |
290 | Relevant only locally, other end need not agree on it |
291 | (but in general, for an intended-to-be-permanent connection, | |
292 | both ends should use | |
293 | .B auto=start | |
294 | to ensure that any reboot causes immediate renegotiation). | |
7900ab1b | 295 | .TP |
6bcf6016 | 296 | .BR compress " = yes | " no |
fea5e716 MW |
297 | whether IPComp compression of content is proposed on the connection |
298 | (link-level compression does not work on encrypted data, | |
299 | so to be effective, compression must be done \fIbefore\fR encryption); | |
300 | acceptable values are | |
301 | .B yes | |
302 | and | |
303 | .B no | |
532f2347 | 304 | (the default). A value of |
fea5e716 | 305 | .B yes |
18dac73f | 306 | causes the daemon to propose both compressed and uncompressed, |
fea5e716 MW |
307 | and prefer compressed. |
308 | A value of | |
309 | .B no | |
18dac73f | 310 | prevents the daemon from proposing or accepting compression. |
fea5e716 | 311 | .TP |
6bcf6016 | 312 | .BR dpdaction " = " none " | clear | hold | restart" |
fea5e716 | 313 | controls the use of the Dead Peer Detection protocol (DPD, RFC 3706) where |
a655f5c0 MW |
314 | R_U_THERE notification messages (IKEv1) or empty INFORMATIONAL messages (IKEv2) |
315 | are periodically sent in order to check the | |
316 | liveliness of the IPsec peer. The values | |
7900ab1b AS |
317 | .BR clear , |
318 | .BR hold , | |
8015c91c | 319 | and |
7900ab1b AS |
320 | .B restart |
321 | all activate DPD. If no activity is detected, all connections with a dead peer | |
f115838b TB |
322 | are stopped and unrouted |
323 | .RB ( clear ), | |
324 | put in the hold state | |
325 | .RB ( hold ) | |
326 | or restarted | |
327 | .RB ( restart ). | |
75e3d90d | 328 | The default is |
7900ab1b | 329 | .B none |
75e3d90d | 330 | which disables the active sending of DPD messages. |
fea5e716 | 331 | .TP |
6bcf6016 | 332 | .BR dpddelay " = " 30s " | <time>" |
a655f5c0 MW |
333 | defines the period time interval with which R_U_THERE messages/INFORMATIONAL |
334 | exchanges are sent to the peer. These are only sent if no other traffic is | |
335 | received. In IKEv2, a value of 0 sends no additional INFORMATIONAL | |
336 | messages and uses only standard messages (such as those to rekey) to detect | |
337 | dead peers. | |
fea5e716 | 338 | .TP |
4876f896 | 339 | .BR closeaction " = " none " | clear | hold | restart" |
75e3d90d MW |
340 | defines the action to take if the remote peer unexpectedly closes a CHILD_SA. |
341 | A closeaction should not be | |
4876f896 | 342 | used if the peer uses reauthentication or uniquids checking, as these events |
75e3d90d MW |
343 | might trigger a closeaction when not desired. Closeactions are currently |
344 | not supported with IKEv1. | |
4876f896 | 345 | .TP |
6bcf6016 | 346 | .BR inactivity " = <time>" |
8015c91c | 347 | defines the timeout interval, after which a CHILD_SA is closed if it did |
75e3d90d | 348 | not send or receive any traffic. |
eea626ed | 349 | .TP |
6bcf6016 | 350 | .BR eap_identity " = <id>" |
82290106 MW |
351 | defines the identity the client uses to reply to a EAP Identity request. |
352 | If defined on the EAP server, the defined identity will be used as peer | |
8015c91c | 353 | identity during EAP authentication. The special value |
82290106 | 354 | .B %identity |
f115838b | 355 | uses the EAP Identity method to ask the client for an EAP identity. If not |
82290106 MW |
356 | defined, the IKEv2 identity will be used as EAP identity. |
357 | .TP | |
6bcf6016 | 358 | .BR esp " = <cipher suites>" |
f115838b | 359 | comma-separated list of ESP encryption/authentication algorithms to be used |
c2bc2b27 | 360 | for the connection, e.g. |
a5477a6f | 361 | .BR aes128-sha256 . |
f115838b | 362 | The notation is |
de13eab0 TB |
363 | .BR encryption-integrity[-dhgroup][-esnmode] . |
364 | .br | |
365 | Defaults to | |
75e3d90d MW |
366 | .BR aes128-sha1,3des-sha1 . |
367 | The daemon adds its extensive default proposal to this default | |
de13eab0 TB |
368 | or the configured value. To restrict it to the configured proposal an |
369 | exclamation mark | |
370 | .RB ( ! ) | |
371 | can be added at the end. | |
372 | .br | |
373 | .BR Note : | |
75e3d90d | 374 | As a responder the daemon accepts the first supported proposal received from |
de13eab0 TB |
375 | the peer. In order to restrict a responder to only accept specific cipher |
376 | suites, the strict flag | |
377 | .RB ( ! , | |
378 | exclamation mark) can be used, e.g: aes256-sha512-modp4096! | |
f115838b TB |
379 | .br |
380 | If | |
381 | .B dh-group | |
75e3d90d MW |
382 | is specified, CHILD_SA/Quick Mode setup and rekeying include a separate |
383 | Diffie-Hellman exchange. Valid values for | |
de13eab0 | 384 | .B esnmode |
37821954 MW |
385 | (IKEv2 only) are |
386 | .B esn | |
387 | and | |
de13eab0 TB |
388 | .BR noesn . |
389 | Specifying both negotiates Extended Sequence Number support with the peer, | |
390 | the default is | |
37821954 | 391 | .B noesn. |
c2bc2b27 | 392 | .TP |
6bcf6016 | 393 | .BR forceencaps " = yes | " no |
a5477a6f | 394 | force UDP encapsulation for ESP packets even if no NAT situation is detected. |
f115838b | 395 | This may help to surmount restrictive firewalls. In order to force the peer to |
75e3d90d | 396 | encapsulate packets, NAT detection payloads are faked. |
9dae1bed | 397 | .TP |
6bcf6016 | 398 | .BR ike " = <cipher suites>" |
f115838b TB |
399 | comma-separated list of IKE/ISAKMP SA encryption/authentication algorithms |
400 | to be used, e.g. | |
401 | .BR aes128-sha1-modp2048 . | |
402 | The notation is | |
403 | .BR encryption-integrity-dhgroup . | |
404 | In IKEv2, multiple algorithms and proposals may be included, such as | |
de13eab0 TB |
405 | aes128-aes256-sha1-modp1536-modp2048,3des-sha1-md5-modp1024. |
406 | .br | |
407 | Defaults to | |
75e3d90d MW |
408 | .B aes128-sha1-modp2048,3des-sha1-modp1536 . |
409 | The daemon adds its extensive default proposal to this | |
de13eab0 TB |
410 | default or the configured value. To restrict it to the configured proposal an |
411 | exclamation mark | |
412 | .RB ( ! ) | |
413 | can be added at the end. | |
414 | .br | |
415 | .BR Note : | |
75e3d90d | 416 | As a responder the daemon accepts the first supported proposal received from |
de13eab0 TB |
417 | the peer. In order to restrict a responder to only accept specific cipher |
418 | suites, the strict flag | |
419 | .BR ( ! , | |
420 | exclamation mark) can be used, e.g: aes256-sha512-modp4096! | |
c2bc2b27 | 421 | .TP |
6bcf6016 | 422 | .BR ikelifetime " = " 3h " | <time>" |
f115838b | 423 | how long the keying channel of a connection (ISAKMP or IKE SA) |
9f8ceffb | 424 | should last before being renegotiated. Also see EXPIRY/REKEY below. |
fea5e716 | 425 | .TP |
6bcf6016 | 426 | .BR installpolicy " = " yes " | no" |
75e3d90d MW |
427 | decides whether IPsec policies are installed in the kernel by the charon daemon |
428 | for a given connection. Allows peaceful cooperation e.g. with | |
84bec926 AS |
429 | the Mobile IPv6 daemon mip6d who wants to control the kernel policies. |
430 | Acceptable values are | |
431 | .B yes | |
432 | (the default) and | |
433 | .BR no . | |
434 | .TP | |
6bcf6016 | 435 | .BR keyexchange " = " ike " | ikev1 | ikev2" |
fea5e716 | 436 | method of key exchange; |
3572b3b6 | 437 | which protocol should be used to initialize the connection. Connections marked with |
fea5e716 | 438 | .B ike |
75e3d90d | 439 | use IKEv2 when initiating, but accept any protocol version when responding. |
fea5e716 | 440 | .TP |
bf870ffb | 441 | .BR keyingtries " = " 3 " | <number> | %forever" |
fea5e716 MW |
442 | how many attempts (a whole number or \fB%forever\fP) should be made to |
443 | negotiate a connection, or a replacement for one, before giving up | |
444 | (default | |
bf870ffb | 445 | .BR 3 ). |
fea5e716 | 446 | The value \fB%forever\fP |
532f2347 | 447 | means 'never give up'. |
fea5e716 MW |
448 | Relevant only locally, other end need not agree on it. |
449 | .TP | |
450 | .B keylife | |
deddfde9 TB |
451 | synonym for |
452 | .BR lifetime . | |
fea5e716 | 453 | .TP |
95e41fb8 | 454 | .BR left " = <ip address> | <fqdn> | " %any |
c2bc2b27 | 455 | (required) |
f115838b | 456 | the IP address of the left participant's public-network interface |
c2bc2b27 | 457 | or one of several magic values. |
75e3d90d | 458 | The value |
f115838b TB |
459 | .B %any |
460 | for the local endpoint signifies an address to be filled in (by automatic | |
461 | keying) during negotiation. If the local peer initiates the connection setup | |
462 | the routing table will be queried to determine the correct local IP address. | |
463 | In case the local peer is responding to a connection setup then any IP address | |
464 | that is assigned to a local interface will be accepted. | |
465 | .br | |
f115838b TB |
466 | |
467 | If | |
468 | .B %any | |
469 | is used for the remote endpoint it literally means any IP address. | |
470 | ||
471 | Please note that with the usage of wildcards multiple connection descriptions | |
472 | might match a given incoming connection attempt. The most specific description | |
473 | is used in that case. | |
c2bc2b27 | 474 | .TP |
6bcf6016 | 475 | .BR leftauth " = <auth method>" |
f115838b TB |
476 | Authentication method to use locally (left) or require from the remote (right) |
477 | side. | |
75e3d90d | 478 | Acceptable values are |
a44bb934 | 479 | .B pubkey |
8015c91c | 480 | for public key authentication (RSA/ECDSA), |
a44bb934 | 481 | .B psk |
75e3d90d | 482 | for pre-shared key authentication, |
a44bb934 | 483 | .B eap |
75e3d90d MW |
484 | to (require the) use of the Extensible Authentication Protocol in IKEv2, and |
485 | .B xauth | |
486 | for IKEv1 eXtended Authentication. | |
44e513a3 | 487 | To require a trustchain public key strength for the remote side, specify the |
7c4214bd MW |
488 | key type followed by the minimum strength in bits (for example |
489 | .BR ecdsa-384 | |
44e513a3 | 490 | or |
7c4214bd MW |
491 | .BR rsa-2048-ecdsa-256 ). |
492 | To limit the acceptable set of hashing algorithms for trustchain validation, | |
493 | append hash algorithms to | |
494 | .BR pubkey | |
495 | or a key strength definition (for example | |
496 | .BR pubkey-sha1-sha256 | |
497 | or | |
498 | .BR rsa-2048-ecdsa-256-sha256-sha384-sha512 ). | |
44e513a3 | 499 | For |
7c4214bd | 500 | .B eap , |
a44bb934 | 501 | an optional EAP method can be appended. Currently defined methods are |
f115838b | 502 | .BR eap-aka , |
c8d46f29 | 503 | .BR eap-sim , |
f115838b TB |
504 | .BR eap-gtc , |
505 | .BR eap-md5 , | |
0293f095 AS |
506 | .BR eap-mschapv2 , |
507 | .BR eap-peap , | |
508 | .BR eap-sim , | |
21079538 | 509 | .BR eap-tls , |
b24be296 | 510 | .BR eap-ttls , |
a44bb934 | 511 | and |
c8d46f29 | 512 | .BR eap-radius . |
a44bb934 MW |
513 | Alternatively, IANA assigned EAP method numbers are accepted. Vendor specific |
514 | EAP methods are defined in the form | |
515 | .B eap-type-vendor | |
f115838b | 516 | .RB "(e.g. " eap-7-12345 ). |
75e3d90d MW |
517 | For |
518 | .B xauth, | |
519 | a XAuth authentication backend can be specified, such as | |
520 | .B xauth-generic | |
521 | or | |
522 | .B xauth-eap . | |
523 | If XAuth is used in | |
524 | .BR leftauth , | |
525 | Hybrid authentication is used. For traditional XAuth authentication, define | |
526 | XAuth in | |
527 | .BR lefauth2 . | |
a44bb934 | 528 | .TP |
6bcf6016 | 529 | .BR leftauth2 " = <auth method>" |
8015c91c | 530 | Same as |
f115838b | 531 | .BR leftauth , |
75e3d90d MW |
532 | but defines an additional authentication exchange. In IKEv1, only XAuth can be |
533 | used in the second authentication round. IKEv2 supports multiple complete | |
a44bb934 MW |
534 | authentication rounds using "Multiple Authentication Exchanges" defined |
535 | in RFC4739. This allows, for example, separated authentication | |
75e3d90d | 536 | of host and user. |
a44bb934 | 537 | .TP |
6bcf6016 | 538 | .BR leftca " = <issuer dn> | %same" |
fea5e716 MW |
539 | the distinguished name of a certificate authority which is required to |
540 | lie in the trust path going from the left participant's certificate up | |
8015c91c | 541 | to the root certification authority. |
fea5e716 | 542 | .TP |
6bcf6016 | 543 | .BR leftca2 " = <issuer dn> | %same" |
a44bb934 | 544 | Same as |
6bcf6016 | 545 | .BR leftca , |
a44bb934 MW |
546 | but for the second authentication round (IKEv2 only). |
547 | .TP | |
6bcf6016 | 548 | .BR leftcert " = <path>" |
f115838b TB |
549 | the path to the left participant's X.509 certificate. The file can be encoded |
550 | either in PEM or DER format. OpenPGP certificates are supported as well. | |
7900ab1b | 551 | Both absolute paths or paths relative to \fI/etc/ipsec.d/certs\fP |
fea5e716 MW |
552 | are accepted. By default |
553 | .B leftcert | |
8015c91c | 554 | sets |
fea5e716 MW |
555 | .B leftid |
556 | to the distinguished name of the certificate's subject and | |
557 | .B leftca | |
558 | to the distinguished name of the certificate's issuer. | |
84545f6e | 559 | The left participant's ID can be overridden by specifying a |
fea5e716 MW |
560 | .B leftid |
561 | value which must be certified by the certificate, though. | |
562 | .TP | |
6bcf6016 | 563 | .BR leftcert2 " = <path>" |
a44bb934 MW |
564 | Same as |
565 | .B leftcert, | |
566 | but for the second authentication round (IKEv2 only). | |
567 | .TP | |
6367de28 MW |
568 | .BR leftcertpolicy " = <OIDs>" |
569 | Comma separated list of certificate policy OIDs the peers certificate must have. | |
570 | OIDs are specified using the numerical dotted representation (IKEv2 only). | |
571 | .TP | |
6bcf6016 | 572 | .BR leftfirewall " = yes | " no |
c2bc2b27 AS |
573 | whether the left participant is doing forwarding-firewalling |
574 | (including masquerading) using iptables for traffic from \fIleftsubnet\fR, | |
575 | which should be turned off (for traffic to the other subnet) | |
576 | once the connection is established; | |
577 | acceptable values are | |
578 | .B yes | |
579 | and | |
580 | .B no | |
581 | (the default). | |
582 | May not be used in the same connection description with | |
583 | .BR leftupdown . | |
584 | Implemented as a parameter to the default \fBipsec _updown\fR script. | |
585 | See notes below. | |
586 | Relevant only locally, other end need not agree on it. | |
587 | ||
588 | If one or both security gateways are doing forwarding firewalling | |
589 | (possibly including masquerading), | |
590 | and this is specified using the firewall parameters, | |
591 | tunnels established with IPsec are exempted from it | |
592 | so that packets can flow unchanged through the tunnels. | |
593 | (This means that all subnets connected in this manner must have | |
594 | distinct, non-overlapping subnet address blocks.) | |
75e3d90d | 595 | This is done by the default \fBipsec _updown\fR script. |
c2bc2b27 AS |
596 | |
597 | In situations calling for more control, | |
598 | it may be preferable for the user to supply his own | |
599 | .I updown | |
600 | script, | |
601 | which makes the appropriate adjustments for his system. | |
602 | .TP | |
6bcf6016 | 603 | .BR leftgroups " = <group list>" |
c2bc2b27 AS |
604 | a comma separated list of group names. If the |
605 | .B leftgroups | |
606 | parameter is present then the peer must be a member of at least one | |
75e3d90d | 607 | of the groups defined by the parameter. |
c2bc2b27 | 608 | .TP |
6bcf6016 | 609 | .BR lefthostaccess " = yes | " no |
c2bc2b27 AS |
610 | inserts a pair of INPUT and OUTPUT iptables rules using the default |
611 | \fBipsec _updown\fR script, thus allowing access to the host itself | |
612 | in the case where the host's internal interface is part of the | |
613 | negotiated client subnet. | |
614 | Acceptable values are | |
615 | .B yes | |
616 | and | |
617 | .B no | |
618 | (the default). | |
619 | .TP | |
6bcf6016 | 620 | .BR leftid " = <id>" |
f115838b | 621 | how the left participant should be identified for authentication; |
c2bc2b27 AS |
622 | defaults to |
623 | .BR left . | |
f115838b | 624 | Can be an IP address or a fully-qualified domain name preceded by |
c2bc2b27 AS |
625 | .B @ |
626 | (which is used as a literal string and not resolved). | |
627 | .TP | |
6bcf6016 | 628 | .BR leftid2 " = <id>" |
a44bb934 MW |
629 | identity to use for a second authentication for the left participant |
630 | (IKEv2 only); defaults to | |
631 | .BR leftid . | |
632 | .TP | |
6bcf6016 | 633 | .BR leftikeport " = <port>" |
75e3d90d MW |
634 | UDP port the left participant uses for IKE communication. |
635 | If unspecified, port 500 is used with the port floating | |
f115838b | 636 | to 4500 if a NAT is detected or MOBIKE is enabled. Specifying a local IKE port |
667b7372 MW |
637 | different from the default additionally requires a socket implementation that |
638 | listens to this port. | |
639 | .TP | |
95e41fb8 | 640 | .BR leftnexthop " = %direct | <ip address> | <fqdn>" |
f115838b TB |
641 | this parameter is usually not needed any more because the NETKEY IPsec stack |
642 | does not require explicit routing entries for the traffic to be tunneled. If | |
643 | .B leftsourceip | |
644 | is used with IKEv1 then | |
645 | .B leftnexthop | |
646 | must still be set in order for the source routes to work properly. | |
c2bc2b27 | 647 | .TP |
6bcf6016 | 648 | .BR leftprotoport " = <protocol>/<port>" |
c2bc2b27 AS |
649 | restrict the traffic selector to a single protocol and/or port. |
650 | Examples: | |
651 | .B leftprotoport=tcp/http | |
7900ab1b | 652 | or |
c2bc2b27 | 653 | .B leftprotoport=6/80 |
7900ab1b | 654 | or |
c2bc2b27 | 655 | .B leftprotoport=udp |
7900ab1b | 656 | .TP |
6bcf6016 | 657 | .BR leftsendcert " = never | no | " ifasked " | always | yes" |
c2bc2b27 AS |
658 | Accepted values are |
659 | .B never | |
660 | or | |
661 | .BR no , | |
662 | .B always | |
663 | or | |
664 | .BR yes , | |
665 | and | |
a5477a6f | 666 | .BR ifasked " (the default)," |
f115838b TB |
667 | the latter meaning that the peer must send a certificate request payload in |
668 | order to get a certificate in return. | |
fea5e716 | 669 | .TP |
6bcf6016 | 670 | .BR leftsourceip " = %config | %cfg | %modeconfig | %modecfg | <ip address>" |
9b45443d | 671 | The internal source IP to use in a tunnel, also known as virtual IP. If the |
f115838b | 672 | value is one of the synonyms |
7900ab1b | 673 | .BR %config , |
f115838b | 674 | .BR %cfg , |
a5477a6f TB |
675 | .BR %modeconfig , |
676 | or | |
677 | .BR %modecfg , | |
75e3d90d | 678 | an address is requested from the peer. |
8e79d8d3 | 679 | .TP |
6bcf6016 | 680 | .BR rightsourceip " = %config | <network>/<netmask> | %poolname" |
8e79d8d3 MW |
681 | The internal source IP to use in a tunnel for the remote peer. If the |
682 | value is | |
683 | .B %config | |
f115838b TB |
684 | on the responder side, the initiator must propose an address which is then |
685 | echoed back. Also supported are address pools expressed as | |
b0103105 | 686 | \fInetwork\fB/\fInetmask\fR |
f115838b TB |
687 | or the use of an external IP address pool using %\fIpoolname\fR, |
688 | where \fIpoolname\fR is the name of the IP address pool used for the lookup. | |
fea5e716 | 689 | .TP |
6bcf6016 | 690 | .BR leftsubnet " = <ip subnet>" |
c2bc2b27 | 691 | private subnet behind the left participant, expressed as |
f115838b | 692 | \fInetwork\fB/\fInetmask\fR; |
c2bc2b27 AS |
693 | if omitted, essentially assumed to be \fIleft\fB/32\fR, |
694 | signifying that the left end of the connection goes to the left participant | |
75e3d90d MW |
695 | only. Configured subnet of the peers may differ, the protocol narrows it to |
696 | the greatest common subnet. In IKEv1, this may lead to problems with other | |
697 | implementations, make sure to configure identical subnets in such | |
698 | configurations. IKEv2 supports multiple subnets separated by commas, IKEv1 only | |
699 | interprets the first subnet of such a definition. | |
c2bc2b27 | 700 | .TP |
6bcf6016 | 701 | .BR leftupdown " = <path>" |
c2bc2b27 AS |
702 | what ``updown'' script to run to adjust routing and/or firewalling |
703 | when the status of the connection | |
704 | changes (default | |
705 | .BR "ipsec _updown" ). | |
706 | May include positional parameters separated by white space | |
707 | (although this requires enclosing the whole string in quotes); | |
708 | including shell metacharacters is unwise. | |
75e3d90d | 709 | Relevant only locally, other end need not agree on it. Charon uses the updown |
f115838b | 710 | script to insert firewall rules only, since routing has been implemented |
75e3d90d | 711 | directly into the daemon. |
c2bc2b27 | 712 | .TP |
6bcf6016 | 713 | .BR lifebytes " = <number>" |
75e3d90d | 714 | the number of bytes transmitted over an IPsec SA before it expires. |
deddfde9 | 715 | .TP |
6bcf6016 | 716 | .BR lifepackets " = <number>" |
75e3d90d | 717 | the number of packets transmitted over an IPsec SA before it expires. |
deddfde9 | 718 | .TP |
6bcf6016 | 719 | .BR lifetime " = " 1h " | <time>" |
deddfde9 TB |
720 | how long a particular instance of a connection |
721 | (a set of encryption/authentication keys for user packets) should last, | |
722 | from successful negotiation to expiry; | |
723 | acceptable values are an integer optionally followed by | |
724 | .BR s | |
725 | (a time in seconds) | |
726 | or a decimal number followed by | |
727 | .BR m , | |
728 | .BR h , | |
729 | or | |
730 | .B d | |
731 | (a time | |
732 | in minutes, hours, or days respectively) | |
733 | (default | |
734 | .BR 1h , | |
735 | maximum | |
736 | .BR 24h ). | |
737 | Normally, the connection is renegotiated (via the keying channel) | |
738 | before it expires (see | |
739 | .BR margintime ). | |
740 | The two ends need not exactly agree on | |
741 | .BR lifetime , | |
742 | although if they do not, | |
743 | there will be some clutter of superseded connections on the end | |
9f8ceffb | 744 | which thinks the lifetime is longer. Also see EXPIRY/REKEY below. |
deddfde9 | 745 | .TP |
6bcf6016 | 746 | .BR marginbytes " = <number>" |
deddfde9 TB |
747 | how many bytes before IPsec SA expiry (see |
748 | .BR lifebytes ) | |
75e3d90d | 749 | should attempts to negotiate a replacement begin. |
deddfde9 | 750 | .TP |
6bcf6016 | 751 | .BR marginpackets " = <number>" |
deddfde9 TB |
752 | how many packets before IPsec SA expiry (see |
753 | .BR lifepackets ) | |
75e3d90d | 754 | should attempts to negotiate a replacement begin. |
deddfde9 | 755 | .TP |
6bcf6016 | 756 | .BR margintime " = " 9m " | <time>" |
deddfde9 TB |
757 | how long before connection expiry or keying-channel expiry |
758 | should attempts to | |
759 | negotiate a replacement | |
760 | begin; acceptable values as for | |
761 | .B lifetime | |
762 | (default | |
763 | .BR 9m ). | |
9f8ceffb TB |
764 | Relevant only locally, other end need not agree on it. Also see EXPIRY/REKEY |
765 | below. | |
d5f29da3 | 766 | .TP |
6bcf6016 TB |
767 | .BR mark " = <value>[/<mask>]" |
768 | sets an XFRM mark in the inbound and outbound | |
3255e489 | 769 | IPsec SAs and policies. If the mask is missing then a default |
d5f29da3 AS |
770 | mask of |
771 | .B 0xffffffff | |
772 | is assumed. | |
773 | .TP | |
6bcf6016 TB |
774 | .BR mark_in " = <value>[/<mask>]" |
775 | sets an XFRM mark in the inbound IPsec SA and | |
a674c79a | 776 | policy. If the mask is missing then a default mask of |
d5f29da3 AS |
777 | .B 0xffffffff |
778 | is assumed. | |
779 | .TP | |
6bcf6016 TB |
780 | .BR mark_out " = <value>[/<mask>]" |
781 | sets an XFRM mark in the outbound IPsec SA and | |
a674c79a | 782 | policy. If the mask is missing then a default mask of |
d5f29da3 AS |
783 | .B 0xffffffff |
784 | is assumed. | |
deddfde9 | 785 | .TP |
6bcf6016 | 786 | .BR mobike " = " yes " | no" |
8c4339bd AS |
787 | enables the IKEv2 MOBIKE protocol defined by RFC 4555. Accepted values are |
788 | .B yes | |
789 | (the default) and | |
790 | .BR no . | |
791 | If set to | |
792 | .BR no , | |
75e3d90d | 793 | the charon daemon will not actively propose MOBIKE as initiator and |
78279973 | 794 | ignore the MOBIKE_SUPPORTED notify as responder. |
8c4339bd | 795 | .TP |
6bcf6016 | 796 | .BR modeconfig " = push | " pull |
7900ab1b AS |
797 | defines which mode is used to assign a virtual IP. |
798 | Accepted values are | |
799 | .B push | |
800 | and | |
801 | .B pull | |
802 | (the default). | |
75e3d90d MW |
803 | Push mode is currently not supported in charon, hence this parameter has no |
804 | effect. | |
fea5e716 | 805 | .TP |
6bcf6016 | 806 | .BR reauth " = " yes " | no" |
c2bc2b27 AS |
807 | whether rekeying of an IKE_SA should also reauthenticate the peer. In IKEv1, |
808 | reauthentication is always done. In IKEv2, a value of | |
809 | .B no | |
810 | rekeys without uninstalling the IPsec SAs, a value of | |
811 | .B yes | |
812 | (the default) creates a new IKE_SA from scratch and tries to recreate | |
813 | all IPsec SAs. | |
814 | .TP | |
6bcf6016 | 815 | .BR rekey " = " yes " | no" |
fea5e716 MW |
816 | whether a connection should be renegotiated when it is about to expire; |
817 | acceptable values are | |
818 | .B yes | |
819 | (the default) | |
820 | and | |
821 | .BR no . | |
7900ab1b | 822 | The two ends need not agree, but while a value of |
fea5e716 | 823 | .B no |
75e3d90d | 824 | prevents charon from requesting renegotiation, |
fea5e716 MW |
825 | it does not prevent responding to renegotiation requested from the other end, |
826 | so | |
827 | .B no | |
828 | will be largely ineffective unless both ends agree on it. | |
829 | .TP | |
6bcf6016 | 830 | .BR rekeyfuzz " = " 100% " | <percentage>" |
fea5e716 | 831 | maximum percentage by which |
deddfde9 TB |
832 | .BR marginbytes , |
833 | .B marginpackets | |
834 | and | |
835 | .B margintime | |
fea5e716 MW |
836 | should be randomly increased to randomize rekeying intervals |
837 | (important for hosts with many connections); | |
838 | acceptable values are an integer, | |
839 | which may exceed 100, | |
840 | followed by a `%' | |
deddfde9 | 841 | (defaults to |
fea5e716 MW |
842 | .BR 100% ). |
843 | The value of | |
deddfde9 | 844 | .BR marginTYPE , |
fea5e716 MW |
845 | after this random increase, |
846 | must not exceed | |
deddfde9 TB |
847 | .B lifeTYPE |
848 | (where TYPE is one of | |
849 | .IR bytes , | |
850 | .I packets | |
851 | or | |
852 | .IR time ). | |
fea5e716 MW |
853 | The value |
854 | .B 0% | |
deddfde9 | 855 | will suppress randomization. |
9f8ceffb TB |
856 | Relevant only locally, other end need not agree on it. Also see EXPIRY/REKEY |
857 | below. | |
fea5e716 MW |
858 | .TP |
859 | .B rekeymargin | |
deddfde9 TB |
860 | synonym for |
861 | .BR margintime . | |
532f2347 | 862 | .TP |
6bcf6016 | 863 | .BR reqid " = <number>" |
b5be105a | 864 | sets the reqid for a given connection to a pre-configured fixed value. |
a729d17a | 865 | .TP |
6c302616 MW |
866 | .BR tfc " = <value>" |
867 | number of bytes to pad ESP payload data to. Traffic Flow Confidentiality | |
868 | is currently supported in IKEv2 and applies to outgoing packets only. The | |
869 | special value | |
870 | .BR %mtu | |
871 | fills up ESP packets with padding to have the size of the MTU. | |
872 | .TP | |
6bcf6016 | 873 | .BR type " = " tunnel " | transport | transport_proxy | passthrough | drop" |
c2bc2b27 AS |
874 | the type of the connection; currently the accepted values |
875 | are | |
876 | .B tunnel | |
877 | (the default) | |
878 | signifying a host-to-host, host-to-subnet, or subnet-to-subnet tunnel; | |
879 | .BR transport , | |
880 | signifying host-to-host transport mode; | |
84bec926 AS |
881 | .BR transport_proxy , |
882 | signifying the special Mobile IPv6 transport proxy mode; | |
c2bc2b27 AS |
883 | .BR passthrough , |
884 | signifying that no IPsec processing should be done at all; | |
885 | .BR drop , | |
75e3d90d | 886 | signifying that packets should be discarded. |
fea5e716 | 887 | .TP |
6bcf6016 | 888 | .BR xauth " = " client " | server" |
b768d6a4 | 889 | specifies the role in the XAuth protocol if activated by |
c2bc2b27 AS |
890 | .B authby=xauthpsk |
891 | or | |
892 | .B authby=xauthrsasig. | |
893 | Accepted values are | |
894 | .B server | |
895 | and | |
896 | .B client | |
897 | (the default). | |
b768d6a4 TB |
898 | .TP |
899 | .BR xauth_identity " = <id>" | |
900 | defines the identity/username the client uses to reply to an XAuth request. | |
901 | If not defined, the IKEv1 identity will be used as XAuth identity. | |
d5cc1758 | 902 | |
e74bc8e5 | 903 | .SS "CONN PARAMETERS: IKEv2 MEDIATION EXTENSION" |
8015c91c | 904 | The following parameters are relevant to IKEv2 Mediation Extension |
e74bc8e5 | 905 | operation only. |
6bcf6016 TB |
906 | .TP |
907 | .BR mediation " = yes | " no | |
e74bc8e5 | 908 | whether this connection is a mediation connection, ie. whether this |
d5cc1758 TB |
909 | connection is used to mediate other connections. Mediation connections |
910 | create no child SA. Acceptable values are | |
911 | .B no | |
912 | (the default) and | |
913 | .BR yes . | |
914 | .TP | |
6bcf6016 | 915 | .BR mediated_by " = <name>" |
d5cc1758 TB |
916 | the name of the connection to mediate this connection through. If given, |
917 | the connection will be mediated through the named mediation connection. | |
918 | The mediation connection must set | |
e74bc8e5 | 919 | .BR mediation=yes . |
d5cc1758 | 920 | .TP |
6bcf6016 | 921 | .BR me_peerid " = <id>" |
d5cc1758 TB |
922 | ID as which the peer is known to the mediation server, ie. which the other |
923 | end of this connection uses as its | |
924 | .B leftid | |
925 | on its connection to the mediation server. This is the ID we request the | |
926 | mediation server to mediate us with. If | |
e74bc8e5 | 927 | .B me_peerid |
d5cc1758 TB |
928 | is not given, the |
929 | .B rightid | |
930 | of this connection will be used as peer ID. | |
931 | ||
fea5e716 | 932 | .SH "CA SECTIONS" |
bf3c3715 TB |
933 | These are optional sections that can be used to assign special |
934 | parameters to a Certification Authority (CA). Because the daemons | |
935 | automatically import CA certificates from \fI/etc/ipsec.d/cacerts\fP, | |
936 | there is no need to explicitly add them with a CA section, unless you | |
937 | want to assign special parameters (like a CRL) to a CA. | |
6bcf6016 | 938 | .TP |
a5477a6f TB |
939 | .BR also " = <name>" |
940 | includes ca section | |
941 | .BR <name> . | |
942 | .TP | |
6bcf6016 | 943 | .BR auto " = " ignore " | add" |
fea5e716 MW |
944 | currently can have either the value |
945 | .B ignore | |
6bcf6016 TB |
946 | (the default) or |
947 | .BR add . | |
fea5e716 | 948 | .TP |
6bcf6016 | 949 | .BR cacert " = <path>" |
8015c91c | 950 | defines a path to the CA certificate either relative to |
fea5e716 MW |
951 | \fI/etc/ipsec.d/cacerts\fP or as an absolute path. |
952 | .TP | |
6bcf6016 | 953 | .BR crluri " = <uri>" |
fea5e716 MW |
954 | defines a CRL distribution point (ldap, http, or file URI) |
955 | .TP | |
7900ab1b AS |
956 | .B crluri1 |
957 | synonym for | |
958 | .B crluri. | |
959 | .TP | |
6bcf6016 | 960 | .BR crluri2 " = <uri>" |
fea5e716 MW |
961 | defines an alternative CRL distribution point (ldap, http, or file URI) |
962 | .TP | |
fea5e716 | 963 | .TP |
6bcf6016 | 964 | .BR ocspuri " = <uri>" |
fea5e716 | 965 | defines an OCSP URI. |
7900ab1b AS |
966 | .TP |
967 | .B ocspuri1 | |
968 | synonym for | |
969 | .B ocspuri. | |
970 | .TP | |
6bcf6016 | 971 | .BR ocspuri2 " = <uri>" |
75e3d90d | 972 | defines an alternative OCSP URI. |
f115838b | 973 | .TP |
6bcf6016 | 974 | .BR certuribase " = <uri>" |
6439267a TB |
975 | defines the base URI for the Hash and URL feature supported by IKEv2. |
976 | Instead of exchanging complete certificates, IKEv2 allows to send an URI | |
977 | that resolves to the DER encoded certificate. The certificate URIs are built | |
978 | by appending the SHA1 hash of the DER encoded certificates to this base URI. | |
fea5e716 MW |
979 | .SH "CONFIG SECTIONS" |
980 | At present, the only | |
981 | .B config | |
982 | section known to the IPsec software is the one named | |
983 | .BR setup , | |
f115838b | 984 | which contains information used when the software is being started. |
fea5e716 MW |
985 | The currently-accepted |
986 | .I parameter | |
987 | names in a | |
988 | .B config | |
989 | .B setup | |
75e3d90d | 990 | section are: |
fea5e716 | 991 | .TP |
6bcf6016 TB |
992 | .BR strictcrlpolicy " = yes | ifuri | " no |
993 | defines if a fresh CRL must be available in order for the peer authentication | |
994 | based on RSA signatures to succeed. | |
e0e7ef07 AS |
995 | IKEv2 additionally recognizes |
996 | .B ifuri | |
997 | which reverts to | |
998 | .B yes | |
999 | if at least one CRL URI is defined and to | |
1000 | .B no | |
1001 | if no URI is known. | |
b360e393 | 1002 | .TP |
6bcf6016 | 1003 | .BR uniqueids " = " yes " | no | replace | keep" |
b360e393 MW |
1004 | whether a particular participant ID should be kept unique, |
1005 | with any new (automatically keyed) | |
1006 | connection using an ID from a different IP address | |
1007 | deemed to replace all old ones using that ID; | |
1008 | acceptable values are | |
1009 | .B yes | |
1010 | (the default) | |
1011 | and | |
1012 | .BR no . | |
1013 | Participant IDs normally \fIare\fR unique, | |
1014 | so a new (automatically-keyed) connection using the same ID is | |
1015 | almost invariably intended to replace an old one. | |
75e3d90d | 1016 | The daemon also accepts the value |
b360e393 | 1017 | .B replace |
f3bb1bd0 | 1018 | which is identical to |
b360e393 MW |
1019 | .B yes |
1020 | and the value | |
1021 | .B keep | |
1022 | to reject new IKE_SA setups and keep the duplicate established earlier. | |
fea5e716 | 1023 | .TP |
6bcf6016 TB |
1024 | .BR charondebug " = <debug list>" |
1025 | how much charon debugging output should be logged. | |
5b217e49 | 1026 | A comma separated list containing type/level-pairs may |
e0e7ef07 AS |
1027 | be specified, e.g: |
1028 | .B dmn 3, ike 1, net -1. | |
1029 | Acceptable values for types are | |
54d096a7 | 1030 | .B dmn, mgr, ike, chd, job, cfg, knl, net, asn, enc, lib, tls, tnc, imc, imv, pts |
e0e7ef07 AS |
1031 | and the level is one of |
1032 | .B -1, 0, 1, 2, 3, 4 | |
5b217e49 TB |
1033 | (for silent, audit, control, controlmore, raw, private). By default, the level |
1034 | is set to | |
1035 | .B 1 | |
1036 | for all types. For more flexibility see LOGGER CONFIGURATION in | |
a5477a6f TB |
1037 | .IR strongswan.conf (5). |
1038 | ||
75e3d90d | 1039 | .SH SA EXPIRY/REKEY |
9f8ceffb TB |
1040 | The IKE SAs and IPsec SAs negotiated by the daemon can be configured to expire |
1041 | after a specific amount of time. For IPsec SAs this can also happen after a | |
1042 | specified number of transmitted packets or transmitted bytes. The following | |
1043 | settings can be used to configure this: | |
1044 | .TS | |
1045 | l r l r,- - - -,lB s lB s,a r a r. | |
1046 | Setting Default Setting Default | |
1047 | IKE SA IPsec SA | |
1048 | ikelifetime 3h lifebytes - | |
1049 | lifepackets - | |
1050 | lifetime 1h | |
1051 | .TE | |
1052 | .SS Rekeying | |
1053 | IKE SAs as well as IPsec SAs can be rekeyed before they expire. This can be | |
1054 | configured using the following settings: | |
1055 | .TS | |
1056 | l r l r,- - - -,lB s lB s,a r a r. | |
1057 | Setting Default Setting Default | |
1058 | IKE and IPsec SA IPsec SA | |
1059 | margintime 9m marginbytes - | |
1060 | marginpackets - | |
1061 | .TE | |
1062 | .SS Randomization | |
1063 | To avoid collisions the specified margins are increased randomly before | |
1064 | subtracting them from the expiration limits (see formula below). This is | |
1065 | controlled by the | |
1066 | .B rekeyfuzz | |
1067 | setting: | |
1068 | .TS | |
1069 | l r,- -,lB s,a r. | |
1070 | Setting Default | |
1071 | IKE and IPsec SA | |
1072 | rekeyfuzz 100% | |
1073 | .TE | |
1074 | .PP | |
1075 | Randomization can be disabled by setting | |
1076 | .BR rekeyfuzz " to " 0% . | |
1077 | .SS Formula | |
1078 | The following formula is used to calculate the rekey time of IPsec SAs: | |
1079 | .PP | |
1080 | .EX | |
1081 | rekeytime = lifetime - (margintime + random(0, margintime * rekeyfuzz)) | |
1082 | .EE | |
1083 | .PP | |
1084 | It applies equally to IKE SAs and byte and packet limits for IPsec SAs. | |
1085 | .SS Example | |
1086 | Let's consider the default configuration: | |
1087 | .PP | |
1088 | .EX | |
1089 | lifetime = 1h | |
1090 | margintime = 9m | |
1091 | rekeyfuzz = 100% | |
1092 | .EE | |
1093 | .PP | |
1094 | From the formula above follows that the rekey time lies between: | |
1095 | .PP | |
1096 | .EX | |
1097 | rekeytime_min = 1h - (9m + 9m) = 42m | |
1098 | rekeytime_max = 1h - (9m + 0m) = 51m | |
1099 | .EE | |
1100 | .PP | |
1101 | Thus, the daemon will attempt to rekey the IPsec SA at a random time | |
1102 | between 42 and 51 minutes after establishing the SA. Or, in other words, | |
1103 | between 9 and 18 minutes before the SA expires. | |
1104 | .SS Notes | |
1105 | .IP \[bu] | |
1106 | Since the rekeying of an SA needs some time, the margin values must not be | |
1107 | too low. | |
1108 | .IP \[bu] | |
1109 | The value | |
1110 | .B margin... + margin... * rekeyfuzz | |
1111 | must not exceed the original limit. For example, specifying | |
1112 | .B margintime = 30m | |
1113 | in the default configuration is a bad idea as there is a chance that the rekey | |
1114 | time equals zero and, thus, rekeying gets disabled. | |
fea5e716 MW |
1115 | .SH FILES |
1116 | .nf | |
1117 | /etc/ipsec.conf | |
7900ab1b AS |
1118 | /etc/ipsec.d/aacerts |
1119 | /etc/ipsec.d/acerts | |
fea5e716 MW |
1120 | /etc/ipsec.d/cacerts |
1121 | /etc/ipsec.d/certs | |
1122 | /etc/ipsec.d/crls | |
fea5e716 MW |
1123 | |
1124 | .SH SEE ALSO | |
75e3d90d | 1125 | strongswan.conf(5), ipsec.secrets(5), ipsec(8) |
fea5e716 | 1126 | .SH HISTORY |
f115838b TB |
1127 | Originally written for the FreeS/WAN project by Henry Spencer. |
1128 | Updated and extended for the strongSwan project <http://www.strongswan.org> by | |
1129 | Tobias Brunner, Andreas Steffen and Martin Willi. | |
fea5e716 MW |
1130 | .SH BUGS |
1131 | .PP | |
7900ab1b | 1132 | If conns are to be added before DNS is available, \fBleft=\fP\fIFQDN\fP |
fea5e716 | 1133 | will fail. |