]>
Commit | Line | Data |
---|---|---|
9f8ceffb | 1 | .TH IPSEC.CONF 5 "2010-10-19" "@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'. | |
175 | strongSwan currently uses two separate keying daemons. \fIpluto\fP handles | |
176 | all IKEv1 connections, \fIcharon\fP is the daemon handling the IKEv2 | |
177 | protocol. | |
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 |
6bcf6016 | 240 | .BR auth " = " esp " | ah" |
fea5e716 MW |
241 | whether authentication should be done as part of |
242 | ESP encryption, or separately using the AH protocol; | |
243 | acceptable values are | |
244 | .B esp | |
245 | (the default) and | |
246 | .BR ah . | |
f115838b TB |
247 | .br |
248 | The IKEv2 daemon currently supports ESP only. | |
fea5e716 | 249 | .TP |
6bcf6016 | 250 | .BR authby " = " pubkey " | rsasig | ecdsasig | psk | eap | never | xauth..." |
fea5e716 MW |
251 | how the two security gateways should authenticate each other; |
252 | acceptable values are | |
7900ab1b | 253 | .B psk |
a5477a6f TB |
254 | or |
255 | .B secret | |
c7f76958 AS |
256 | for pre-shared secrets, |
257 | .B pubkey | |
258 | (the default) for public key signatures as well as the synonyms | |
fea5e716 | 259 | .B rsasig |
c7f76958 AS |
260 | for RSA digital signatures and |
261 | .B ecdsasig | |
262 | for Elliptic Curve DSA signatures. | |
fea5e716 | 263 | .B never |
c7f76958 AS |
264 | can be used if negotiation is never to be attempted or accepted (useful for |
265 | shunt-only conns). | |
8015c91c | 266 | Digital signatures are superior in every way to shared secrets. |
7900ab1b AS |
267 | IKEv1 additionally supports the values |
268 | .B xauthpsk | |
269 | and | |
270 | .B xauthrsasig | |
271 | that will enable eXtended AUTHentication (XAUTH) in addition to IKEv1 main mode | |
272 | based on shared secrets or digital RSA signatures, respectively. | |
f115838b TB |
273 | IKEv2 additionally supports the value |
274 | .BR eap , | |
275 | which indicates an initiator to request EAP authentication. The EAP method | |
276 | to use is selected by the server (see | |
277 | .BR eap ). | |
a44bb934 | 278 | This parameter is deprecated for IKEv2 connections, as two peers do not need |
8015c91c | 279 | to agree on an authentication method. Use the |
a44bb934 MW |
280 | .B leftauth |
281 | parameter instead to define authentication methods in IKEv2. | |
fea5e716 | 282 | .TP |
6bcf6016 | 283 | .BR auto " = " ignore " | add | route | start" |
c2bc2b27 AS |
284 | what operation, if any, should be done automatically at IPsec startup; |
285 | currently-accepted values are | |
f115838b TB |
286 | .BR add , |
287 | .BR route , | |
c2bc2b27 | 288 | .B start |
7900ab1b | 289 | and |
f115838b TB |
290 | .B ignore |
291 | (the default). | |
c2bc2b27 AS |
292 | .B add |
293 | loads a connection without starting it. | |
294 | .B route | |
295 | loads a connection and installs kernel traps. If traffic is detected between | |
296 | .B leftsubnet | |
297 | and | |
298 | .B rightsubnet | |
299 | , a connection is established. | |
300 | .B start | |
f3bb1bd0 | 301 | loads a connection and brings it up immediately. |
c2bc2b27 AS |
302 | .B ignore |
303 | ignores the connection. This is equal to delete a connection from the config | |
8015c91c | 304 | file. |
c2bc2b27 AS |
305 | Relevant only locally, other end need not agree on it |
306 | (but in general, for an intended-to-be-permanent connection, | |
307 | both ends should use | |
308 | .B auto=start | |
309 | to ensure that any reboot causes immediate renegotiation). | |
7900ab1b | 310 | .TP |
6bcf6016 | 311 | .BR compress " = yes | " no |
fea5e716 MW |
312 | whether IPComp compression of content is proposed on the connection |
313 | (link-level compression does not work on encrypted data, | |
314 | so to be effective, compression must be done \fIbefore\fR encryption); | |
315 | acceptable values are | |
316 | .B yes | |
317 | and | |
318 | .B no | |
532f2347 | 319 | (the default). A value of |
fea5e716 MW |
320 | .B yes |
321 | causes IPsec to propose both compressed and uncompressed, | |
322 | and prefer compressed. | |
323 | A value of | |
324 | .B no | |
325 | prevents IPsec from proposing compression; | |
326 | a proposal to compress will still be accepted. | |
327 | .TP | |
6bcf6016 | 328 | .BR dpdaction " = " none " | clear | hold | restart" |
fea5e716 | 329 | controls the use of the Dead Peer Detection protocol (DPD, RFC 3706) where |
a655f5c0 MW |
330 | R_U_THERE notification messages (IKEv1) or empty INFORMATIONAL messages (IKEv2) |
331 | are periodically sent in order to check the | |
332 | liveliness of the IPsec peer. The values | |
7900ab1b AS |
333 | .BR clear , |
334 | .BR hold , | |
8015c91c | 335 | and |
7900ab1b AS |
336 | .B restart |
337 | all activate DPD. If no activity is detected, all connections with a dead peer | |
f115838b TB |
338 | are stopped and unrouted |
339 | .RB ( clear ), | |
340 | put in the hold state | |
341 | .RB ( hold ) | |
342 | or restarted | |
343 | .RB ( restart ). | |
7900ab1b | 344 | For IKEv1, the default is |
a655f5c0 MW |
345 | .B none |
346 | which disables the active sending of R_U_THERE notifications. | |
347 | Nevertheless pluto will always send the DPD Vendor ID during connection set up | |
348 | in order to signal the readiness to act passively as a responder if the peer | |
7900ab1b AS |
349 | wants to use DPD. For IKEv2, |
350 | .B none | |
351 | does't make sense, since all messages are used to detect dead peers. If specified, | |
f115838b TB |
352 | it has the same meaning as the default |
353 | .RB ( clear ). | |
fea5e716 | 354 | .TP |
6bcf6016 | 355 | .BR dpddelay " = " 30s " | <time>" |
a655f5c0 MW |
356 | defines the period time interval with which R_U_THERE messages/INFORMATIONAL |
357 | exchanges are sent to the peer. These are only sent if no other traffic is | |
358 | received. In IKEv2, a value of 0 sends no additional INFORMATIONAL | |
359 | messages and uses only standard messages (such as those to rekey) to detect | |
360 | dead peers. | |
fea5e716 | 361 | .TP |
6bcf6016 | 362 | .BR dpdtimeout " = " 150s " | <time>" |
fea5e716 | 363 | defines the timeout interval, after which all connections to a peer are deleted |
a655f5c0 MW |
364 | in case of inactivity. This only applies to IKEv1, in IKEv2 the default |
365 | retransmission timeout applies, as every exchange is used to detect dead peers. | |
a5477a6f TB |
366 | See |
367 | .IR strongswan.conf (5) | |
368 | for a description of the IKEv2 retransmission timeout. | |
fea5e716 | 369 | .TP |
4876f896 MW |
370 | .BR closeaction " = " none " | clear | hold | restart" |
371 | defines the action to take if the remote peer unexpectedly closes a CHILD_SA | |
372 | (IKEv2 only, see dpdaction for meaning of values). A closeaction should not be | |
373 | used if the peer uses reauthentication or uniquids checking, as these events | |
374 | might trigger a closeaction when not desired. | |
375 | .TP | |
6bcf6016 | 376 | .BR inactivity " = <time>" |
8015c91c MW |
377 | defines the timeout interval, after which a CHILD_SA is closed if it did |
378 | not send or receive any traffic. Currently supported in IKEv2 connections only. | |
379 | .TP | |
6bcf6016 | 380 | .BR eap " = md5 | mschapv2 | radius | ... | <type> | <type>-<vendor> |
a44bb934 | 381 | defines the EAP type to propose as server if the client requests EAP |
f115838b TB |
382 | authentication. Currently supported values are |
383 | .B aka | |
384 | for EAP-AKA, | |
385 | .B gtc | |
386 | for EAP-GTC, | |
387 | .B md5 | |
388 | for EAP-MD5, | |
389 | .B mschapv2 | |
390 | for EAP-MS-CHAPv2, | |
391 | .B radius | |
392 | for the EAP-RADIUS proxy and | |
393 | .B sim | |
394 | for EAP-SIM. Additionally, IANA assigned EAP method numbers are accepted, or a | |
395 | definition in the form | |
396 | .B eap=type-vendor | |
397 | (e.g. eap=7-12345) can be used to specify vendor specific EAP types. | |
398 | This parameter is deprecated in the favour of | |
a44bb934 | 399 | .B leftauth. |
4a6b84a9 MW |
400 | |
401 | To forward EAP authentication to a RADIUS server using the EAP-RADIUS plugin, | |
8015c91c | 402 | set |
f115838b | 403 | .BR eap=radius . |
eea626ed | 404 | .TP |
6bcf6016 | 405 | .BR eap_identity " = <id>" |
82290106 MW |
406 | defines the identity the client uses to reply to a EAP Identity request. |
407 | If defined on the EAP server, the defined identity will be used as peer | |
8015c91c | 408 | identity during EAP authentication. The special value |
82290106 | 409 | .B %identity |
f115838b | 410 | uses the EAP Identity method to ask the client for an EAP identity. If not |
82290106 MW |
411 | defined, the IKEv2 identity will be used as EAP identity. |
412 | .TP | |
6bcf6016 | 413 | .BR esp " = <cipher suites>" |
f115838b | 414 | comma-separated list of ESP encryption/authentication algorithms to be used |
c2bc2b27 | 415 | for the connection, e.g. |
a5477a6f | 416 | .BR aes128-sha256 . |
f115838b | 417 | The notation is |
de13eab0 TB |
418 | .BR encryption-integrity[-dhgroup][-esnmode] . |
419 | .br | |
420 | Defaults to | |
421 | .BR aes128-sha1,3des-sha1 | |
422 | for IKEv1. The IKEv2 daemon adds its extensive default proposal to this default | |
423 | or the configured value. To restrict it to the configured proposal an | |
424 | exclamation mark | |
425 | .RB ( ! ) | |
426 | can be added at the end. | |
427 | .br | |
428 | .BR Note : | |
429 | As a responder both daemons accept the first supported proposal received from | |
430 | the peer. In order to restrict a responder to only accept specific cipher | |
431 | suites, the strict flag | |
432 | .RB ( ! , | |
433 | exclamation mark) can be used, e.g: aes256-sha512-modp4096! | |
f115838b TB |
434 | .br |
435 | If | |
436 | .B dh-group | |
de13eab0 TB |
437 | is specified, CHILD_SA setup and rekeying include a separate Diffie-Hellman |
438 | exchange (IKEv2 only). Valid values for | |
439 | .B esnmode | |
37821954 MW |
440 | (IKEv2 only) are |
441 | .B esn | |
442 | and | |
de13eab0 TB |
443 | .BR noesn . |
444 | Specifying both negotiates Extended Sequence Number support with the peer, | |
445 | the default is | |
37821954 | 446 | .B noesn. |
c2bc2b27 | 447 | .TP |
6bcf6016 | 448 | .BR forceencaps " = yes | " no |
a5477a6f | 449 | force UDP encapsulation for ESP packets even if no NAT situation is detected. |
f115838b | 450 | This may help to surmount restrictive firewalls. In order to force the peer to |
9dae1bed MW |
451 | encapsulate packets, NAT detection payloads are faked (IKEv2 only). |
452 | .TP | |
6bcf6016 | 453 | .BR ike " = <cipher suites>" |
f115838b TB |
454 | comma-separated list of IKE/ISAKMP SA encryption/authentication algorithms |
455 | to be used, e.g. | |
456 | .BR aes128-sha1-modp2048 . | |
457 | The notation is | |
458 | .BR encryption-integrity-dhgroup . | |
459 | In IKEv2, multiple algorithms and proposals may be included, such as | |
de13eab0 TB |
460 | aes128-aes256-sha1-modp1536-modp2048,3des-sha1-md5-modp1024. |
461 | .br | |
462 | Defaults to | |
463 | .B aes128-sha1-modp2048,3des-sha1-modp1536 | |
464 | for IKEv1. The IKEv2 daemon adds its extensive default proposal to this | |
465 | default or the configured value. To restrict it to the configured proposal an | |
466 | exclamation mark | |
467 | .RB ( ! ) | |
468 | can be added at the end. | |
469 | .br | |
470 | .BR Note : | |
471 | As a responder both daemons accept the first supported proposal received from | |
472 | the peer. In order to restrict a responder to only accept specific cipher | |
473 | suites, the strict flag | |
474 | .BR ( ! , | |
475 | exclamation mark) can be used, e.g: aes256-sha512-modp4096! | |
c2bc2b27 | 476 | .TP |
6bcf6016 | 477 | .BR ikelifetime " = " 3h " | <time>" |
f115838b | 478 | how long the keying channel of a connection (ISAKMP or IKE SA) |
9f8ceffb | 479 | should last before being renegotiated. Also see EXPIRY/REKEY below. |
fea5e716 | 480 | .TP |
6bcf6016 | 481 | .BR installpolicy " = " yes " | no" |
84bec926 | 482 | decides whether IPsec policies are installed in the kernel by the IKEv2 |
f115838b | 483 | charon daemon for a given connection. Allows peaceful cooperation e.g. with |
84bec926 AS |
484 | the Mobile IPv6 daemon mip6d who wants to control the kernel policies. |
485 | Acceptable values are | |
486 | .B yes | |
487 | (the default) and | |
488 | .BR no . | |
489 | .TP | |
6bcf6016 | 490 | .BR keyexchange " = " ike " | ikev1 | ikev2" |
fea5e716 | 491 | method of key exchange; |
3572b3b6 | 492 | which protocol should be used to initialize the connection. Connections marked with |
fea5e716 | 493 | .B ikev1 |
3572b3b6 | 494 | are initiated with pluto, those marked with |
fea5e716 | 495 | .B ikev2 |
8015c91c MW |
496 | with charon. An incoming request from the remote peer is handled by the correct |
497 | daemon, unaffected from the | |
fea5e716 | 498 | .B keyexchange |
456a4f39 | 499 | setting. Starting with strongSwan 4.5 the default value |
fea5e716 | 500 | .B ike |
456a4f39 AS |
501 | is a synonym for |
502 | .BR ikev2 , | |
503 | whereas in older strongSwan releases | |
504 | .B ikev1 | |
505 | was assumed. | |
fea5e716 | 506 | .TP |
bf870ffb | 507 | .BR keyingtries " = " 3 " | <number> | %forever" |
fea5e716 MW |
508 | how many attempts (a whole number or \fB%forever\fP) should be made to |
509 | negotiate a connection, or a replacement for one, before giving up | |
510 | (default | |
bf870ffb | 511 | .BR 3 ). |
fea5e716 | 512 | The value \fB%forever\fP |
532f2347 | 513 | means 'never give up'. |
fea5e716 MW |
514 | Relevant only locally, other end need not agree on it. |
515 | .TP | |
516 | .B keylife | |
deddfde9 TB |
517 | synonym for |
518 | .BR lifetime . | |
fea5e716 | 519 | .TP |
6bcf6016 | 520 | .BR left " = <ip address> | <fqdn> | %defaultroute | " %any |
c2bc2b27 | 521 | (required) |
f115838b | 522 | the IP address of the left participant's public-network interface |
c2bc2b27 AS |
523 | or one of several magic values. |
524 | If it is | |
525 | .BR %defaultroute , | |
526 | .B left | |
527 | will be filled in automatically with the local address | |
f115838b TB |
528 | of the default-route interface (as determined at IPsec startup time and |
529 | during configuration update). | |
530 | Either | |
c2bc2b27 AS |
531 | .B left |
532 | or | |
533 | .B right | |
534 | may be | |
535 | .BR %defaultroute , | |
f115838b TB |
536 | but not both. |
537 | The prefix | |
c2bc2b27 AS |
538 | .B % |
539 | in front of a fully-qualified domain name or an IP address will implicitly set | |
540 | .B leftallowany=yes. | |
f115838b TB |
541 | If the domain name cannot be resolved into an IP address at IPsec startup or |
542 | update time then | |
c2bc2b27 AS |
543 | .B left=%any |
544 | and | |
545 | .B leftallowany=no | |
546 | will be assumed. | |
f115838b TB |
547 | |
548 | In case of an IKEv2 connection, the value | |
549 | .B %any | |
550 | for the local endpoint signifies an address to be filled in (by automatic | |
551 | keying) during negotiation. If the local peer initiates the connection setup | |
552 | the routing table will be queried to determine the correct local IP address. | |
553 | In case the local peer is responding to a connection setup then any IP address | |
554 | that is assigned to a local interface will be accepted. | |
555 | .br | |
556 | Note that specifying | |
557 | .B %any | |
558 | for the local endpoint is not supported by the IKEv1 pluto daemon. | |
559 | ||
560 | If | |
561 | .B %any | |
562 | is used for the remote endpoint it literally means any IP address. | |
563 | ||
564 | Please note that with the usage of wildcards multiple connection descriptions | |
565 | might match a given incoming connection attempt. The most specific description | |
566 | is used in that case. | |
c2bc2b27 | 567 | .TP |
6bcf6016 | 568 | .BR leftallowany " = yes | " no |
c2bc2b27 AS |
569 | a modifier for |
570 | .B left | |
571 | , making it behave as | |
572 | .B %any | |
573 | although a concrete IP address has been assigned. | |
f115838b TB |
574 | Recommended for dynamic IP addresses that can be resolved by DynDNS at IPsec |
575 | startup or update time. | |
c2bc2b27 AS |
576 | Acceptable values are |
577 | .B yes | |
578 | and | |
579 | .B no | |
580 | (the default). | |
581 | .TP | |
6bcf6016 | 582 | .BR leftauth " = <auth method>" |
f115838b TB |
583 | Authentication method to use locally (left) or require from the remote (right) |
584 | side. | |
8015c91c | 585 | This parameter is supported in IKEv2 only. Acceptable values are |
a44bb934 | 586 | .B pubkey |
8015c91c | 587 | for public key authentication (RSA/ECDSA), |
a44bb934 MW |
588 | .B psk |
589 | for pre-shared key authentication and | |
590 | .B eap | |
44e513a3 MW |
591 | to (require the) use of the Extensible Authentication Protocol. |
592 | To require a trustchain public key strength for the remote side, specify the | |
593 | key type followed by the strength in bits (for example | |
594 | .BR rsa-2048 | |
595 | or | |
596 | .BR ecdsa-256 ). | |
597 | For | |
a44bb934 MW |
598 | .B eap, |
599 | an optional EAP method can be appended. Currently defined methods are | |
f115838b TB |
600 | .BR eap-aka , |
601 | .BR eap-gtc , | |
602 | .BR eap-md5 , | |
21079538 | 603 | .BR eap-tls , |
f115838b | 604 | .B eap-mschapv2 |
a44bb934 | 605 | and |
f115838b | 606 | .BR eap-sim . |
a44bb934 MW |
607 | Alternatively, IANA assigned EAP method numbers are accepted. Vendor specific |
608 | EAP methods are defined in the form | |
609 | .B eap-type-vendor | |
f115838b | 610 | .RB "(e.g. " eap-7-12345 ). |
a44bb934 | 611 | .TP |
6bcf6016 | 612 | .BR leftauth2 " = <auth method>" |
8015c91c | 613 | Same as |
f115838b | 614 | .BR leftauth , |
a44bb934 MW |
615 | but defines an additional authentication exchange. IKEv2 supports multiple |
616 | authentication rounds using "Multiple Authentication Exchanges" defined | |
617 | in RFC4739. This allows, for example, separated authentication | |
618 | of host and user (IKEv2 only). | |
619 | .TP | |
6bcf6016 | 620 | .BR leftca " = <issuer dn> | %same" |
fea5e716 MW |
621 | the distinguished name of a certificate authority which is required to |
622 | lie in the trust path going from the left participant's certificate up | |
8015c91c | 623 | to the root certification authority. |
fea5e716 | 624 | .TP |
6bcf6016 | 625 | .BR leftca2 " = <issuer dn> | %same" |
a44bb934 | 626 | Same as |
6bcf6016 | 627 | .BR leftca , |
a44bb934 MW |
628 | but for the second authentication round (IKEv2 only). |
629 | .TP | |
6bcf6016 | 630 | .BR leftcert " = <path>" |
f115838b TB |
631 | the path to the left participant's X.509 certificate. The file can be encoded |
632 | either in PEM or DER format. OpenPGP certificates are supported as well. | |
7900ab1b | 633 | Both absolute paths or paths relative to \fI/etc/ipsec.d/certs\fP |
fea5e716 MW |
634 | are accepted. By default |
635 | .B leftcert | |
8015c91c | 636 | sets |
fea5e716 MW |
637 | .B leftid |
638 | to the distinguished name of the certificate's subject and | |
639 | .B leftca | |
640 | to the distinguished name of the certificate's issuer. | |
84545f6e | 641 | The left participant's ID can be overridden by specifying a |
fea5e716 MW |
642 | .B leftid |
643 | value which must be certified by the certificate, though. | |
644 | .TP | |
6bcf6016 | 645 | .BR leftcert2 " = <path>" |
a44bb934 MW |
646 | Same as |
647 | .B leftcert, | |
648 | but for the second authentication round (IKEv2 only). | |
649 | .TP | |
6367de28 MW |
650 | .BR leftcertpolicy " = <OIDs>" |
651 | Comma separated list of certificate policy OIDs the peers certificate must have. | |
652 | OIDs are specified using the numerical dotted representation (IKEv2 only). | |
653 | .TP | |
6bcf6016 | 654 | .BR leftfirewall " = yes | " no |
c2bc2b27 AS |
655 | whether the left participant is doing forwarding-firewalling |
656 | (including masquerading) using iptables for traffic from \fIleftsubnet\fR, | |
657 | which should be turned off (for traffic to the other subnet) | |
658 | once the connection is established; | |
659 | acceptable values are | |
660 | .B yes | |
661 | and | |
662 | .B no | |
663 | (the default). | |
664 | May not be used in the same connection description with | |
665 | .BR leftupdown . | |
666 | Implemented as a parameter to the default \fBipsec _updown\fR script. | |
667 | See notes below. | |
668 | Relevant only locally, other end need not agree on it. | |
669 | ||
670 | If one or both security gateways are doing forwarding firewalling | |
671 | (possibly including masquerading), | |
672 | and this is specified using the firewall parameters, | |
673 | tunnels established with IPsec are exempted from it | |
674 | so that packets can flow unchanged through the tunnels. | |
675 | (This means that all subnets connected in this manner must have | |
676 | distinct, non-overlapping subnet address blocks.) | |
677 | This is done by the default \fBipsec _updown\fR script (see | |
678 | .IR pluto (8)). | |
679 | ||
680 | In situations calling for more control, | |
681 | it may be preferable for the user to supply his own | |
682 | .I updown | |
683 | script, | |
684 | which makes the appropriate adjustments for his system. | |
685 | .TP | |
6bcf6016 | 686 | .BR leftgroups " = <group list>" |
c2bc2b27 AS |
687 | a comma separated list of group names. If the |
688 | .B leftgroups | |
689 | parameter is present then the peer must be a member of at least one | |
690 | of the groups defined by the parameter. Group membership must be certified | |
f115838b TB |
691 | by a valid attribute certificate stored in \fI/etc/ipsec.d/acerts/\fP thas has |
692 | been issued to the peer by a trusted Authorization Authority stored in | |
693 | \fI/etc/ipsec.d/aacerts/\fP. | |
694 | .br | |
695 | Attribute certificates are not supported in IKEv2 yet. | |
c2bc2b27 | 696 | .TP |
6bcf6016 | 697 | .BR lefthostaccess " = yes | " no |
c2bc2b27 AS |
698 | inserts a pair of INPUT and OUTPUT iptables rules using the default |
699 | \fBipsec _updown\fR script, thus allowing access to the host itself | |
700 | in the case where the host's internal interface is part of the | |
701 | negotiated client subnet. | |
702 | Acceptable values are | |
703 | .B yes | |
704 | and | |
705 | .B no | |
706 | (the default). | |
707 | .TP | |
6bcf6016 | 708 | .BR leftid " = <id>" |
f115838b | 709 | how the left participant should be identified for authentication; |
c2bc2b27 AS |
710 | defaults to |
711 | .BR left . | |
f115838b | 712 | Can be an IP address or a fully-qualified domain name preceded by |
c2bc2b27 AS |
713 | .B @ |
714 | (which is used as a literal string and not resolved). | |
715 | .TP | |
6bcf6016 | 716 | .BR leftid2 " = <id>" |
a44bb934 MW |
717 | identity to use for a second authentication for the left participant |
718 | (IKEv2 only); defaults to | |
719 | .BR leftid . | |
720 | .TP | |
6bcf6016 | 721 | .BR leftikeport " = <port>" |
667b7372 | 722 | UDP port the left participant uses for IKE communication. Currently supported in |
f115838b TB |
723 | IKEv2 connections only. If unspecified, port 500 is used with the port floating |
724 | to 4500 if a NAT is detected or MOBIKE is enabled. Specifying a local IKE port | |
667b7372 MW |
725 | different from the default additionally requires a socket implementation that |
726 | listens to this port. | |
727 | .TP | |
6bcf6016 | 728 | .BR leftnexthop " = %direct | %defaultroute | <ip address> | <fqdn>" |
f115838b TB |
729 | this parameter is usually not needed any more because the NETKEY IPsec stack |
730 | does not require explicit routing entries for the traffic to be tunneled. If | |
731 | .B leftsourceip | |
732 | is used with IKEv1 then | |
733 | .B leftnexthop | |
734 | must still be set in order for the source routes to work properly. | |
c2bc2b27 | 735 | .TP |
6bcf6016 | 736 | .BR leftprotoport " = <protocol>/<port>" |
c2bc2b27 AS |
737 | restrict the traffic selector to a single protocol and/or port. |
738 | Examples: | |
739 | .B leftprotoport=tcp/http | |
7900ab1b | 740 | or |
c2bc2b27 | 741 | .B leftprotoport=6/80 |
7900ab1b | 742 | or |
c2bc2b27 | 743 | .B leftprotoport=udp |
7900ab1b | 744 | .TP |
6bcf6016 | 745 | .BR leftrsasigkey " = " %cert " | <raw rsa public key>" |
7900ab1b AS |
746 | the left participant's |
747 | public key for RSA signature authentication, | |
748 | in RFC 2537 format using | |
749 | .IR ttodata (3) | |
750 | encoding. | |
751 | The magic value | |
752 | .B %none | |
753 | means the same as not specifying a value (useful to override a default). | |
754 | The value | |
755 | .B %cert | |
756 | (the default) | |
757 | means that the key is extracted from a certificate. | |
758 | The identity used for the left participant | |
759 | must be a specific host, not | |
760 | .B %any | |
761 | or another magic value. | |
762 | .B Caution: | |
763 | if two connection descriptions | |
764 | specify different public keys for the same | |
765 | .BR leftid , | |
766 | confusion and madness will ensue. | |
767 | .TP | |
6bcf6016 | 768 | .BR leftsendcert " = never | no | " ifasked " | always | yes" |
c2bc2b27 AS |
769 | Accepted values are |
770 | .B never | |
771 | or | |
772 | .BR no , | |
773 | .B always | |
774 | or | |
775 | .BR yes , | |
776 | and | |
a5477a6f | 777 | .BR ifasked " (the default)," |
f115838b TB |
778 | the latter meaning that the peer must send a certificate request payload in |
779 | order to get a certificate in return. | |
fea5e716 | 780 | .TP |
6bcf6016 | 781 | .BR leftsourceip " = %config | %cfg | %modeconfig | %modecfg | <ip address>" |
9b45443d | 782 | The internal source IP to use in a tunnel, also known as virtual IP. If the |
f115838b | 783 | value is one of the synonyms |
7900ab1b | 784 | .BR %config , |
f115838b | 785 | .BR %cfg , |
a5477a6f TB |
786 | .BR %modeconfig , |
787 | or | |
788 | .BR %modecfg , | |
f115838b TB |
789 | an address is requested from the peer. In IKEv2, a statically defined address |
790 | is also requested, since the server may change it. | |
8e79d8d3 | 791 | .TP |
6bcf6016 | 792 | .BR rightsourceip " = %config | <network>/<netmask> | %poolname" |
8e79d8d3 MW |
793 | The internal source IP to use in a tunnel for the remote peer. If the |
794 | value is | |
795 | .B %config | |
f115838b TB |
796 | on the responder side, the initiator must propose an address which is then |
797 | echoed back. Also supported are address pools expressed as | |
b0103105 | 798 | \fInetwork\fB/\fInetmask\fR |
f115838b TB |
799 | or the use of an external IP address pool using %\fIpoolname\fR, |
800 | where \fIpoolname\fR is the name of the IP address pool used for the lookup. | |
fea5e716 | 801 | .TP |
6bcf6016 | 802 | .BR leftsubnet " = <ip subnet>" |
c2bc2b27 | 803 | private subnet behind the left participant, expressed as |
f115838b | 804 | \fInetwork\fB/\fInetmask\fR; |
c2bc2b27 AS |
805 | if omitted, essentially assumed to be \fIleft\fB/32\fR, |
806 | signifying that the left end of the connection goes to the left participant | |
807 | only. When using IKEv2, the configured subnet of the peers may differ, the | |
34443902 MW |
808 | protocol narrows it to the greatest common subnet. Further, IKEv2 supports |
809 | multiple subnets separated by commas. IKEv1 only interprets the first subnet | |
810 | of such a definition. | |
c2bc2b27 | 811 | .TP |
6bcf6016 | 812 | .BR leftsubnetwithin " = <ip subnet>" |
c2bc2b27 AS |
813 | the peer can propose any subnet or single IP address that fits within the |
814 | range defined by | |
815 | .BR leftsubnetwithin. | |
816 | Not relevant for IKEv2, as subnets are narrowed. | |
817 | .TP | |
6bcf6016 | 818 | .BR leftupdown " = <path>" |
c2bc2b27 AS |
819 | what ``updown'' script to run to adjust routing and/or firewalling |
820 | when the status of the connection | |
821 | changes (default | |
822 | .BR "ipsec _updown" ). | |
823 | May include positional parameters separated by white space | |
824 | (although this requires enclosing the whole string in quotes); | |
825 | including shell metacharacters is unwise. | |
826 | See | |
827 | .IR pluto (8) | |
828 | for details. | |
829 | Relevant only locally, other end need not agree on it. IKEv2 uses the updown | |
f115838b TB |
830 | script to insert firewall rules only, since routing has been implemented |
831 | directly into charon. | |
c2bc2b27 | 832 | .TP |
6bcf6016 | 833 | .BR lifebytes " = <number>" |
deddfde9 TB |
834 | the number of bytes transmitted over an IPsec SA before it expires (IKEv2 |
835 | only). | |
836 | .TP | |
6bcf6016 | 837 | .BR lifepackets " = <number>" |
deddfde9 TB |
838 | the number of packets transmitted over an IPsec SA before it expires (IKEv2 |
839 | only). | |
840 | .TP | |
6bcf6016 | 841 | .BR lifetime " = " 1h " | <time>" |
deddfde9 TB |
842 | how long a particular instance of a connection |
843 | (a set of encryption/authentication keys for user packets) should last, | |
844 | from successful negotiation to expiry; | |
845 | acceptable values are an integer optionally followed by | |
846 | .BR s | |
847 | (a time in seconds) | |
848 | or a decimal number followed by | |
849 | .BR m , | |
850 | .BR h , | |
851 | or | |
852 | .B d | |
853 | (a time | |
854 | in minutes, hours, or days respectively) | |
855 | (default | |
856 | .BR 1h , | |
857 | maximum | |
858 | .BR 24h ). | |
859 | Normally, the connection is renegotiated (via the keying channel) | |
860 | before it expires (see | |
861 | .BR margintime ). | |
862 | The two ends need not exactly agree on | |
863 | .BR lifetime , | |
864 | although if they do not, | |
865 | there will be some clutter of superseded connections on the end | |
9f8ceffb | 866 | which thinks the lifetime is longer. Also see EXPIRY/REKEY below. |
deddfde9 | 867 | .TP |
6bcf6016 | 868 | .BR marginbytes " = <number>" |
deddfde9 TB |
869 | how many bytes before IPsec SA expiry (see |
870 | .BR lifebytes ) | |
871 | should attempts to negotiate a replacement begin (IKEv2 only). | |
872 | .TP | |
6bcf6016 | 873 | .BR marginpackets " = <number>" |
deddfde9 TB |
874 | how many packets before IPsec SA expiry (see |
875 | .BR lifepackets ) | |
876 | should attempts to negotiate a replacement begin (IKEv2 only). | |
877 | .TP | |
6bcf6016 | 878 | .BR margintime " = " 9m " | <time>" |
deddfde9 TB |
879 | how long before connection expiry or keying-channel expiry |
880 | should attempts to | |
881 | negotiate a replacement | |
882 | begin; acceptable values as for | |
883 | .B lifetime | |
884 | (default | |
885 | .BR 9m ). | |
9f8ceffb TB |
886 | Relevant only locally, other end need not agree on it. Also see EXPIRY/REKEY |
887 | below. | |
d5f29da3 | 888 | .TP |
6bcf6016 TB |
889 | .BR mark " = <value>[/<mask>]" |
890 | sets an XFRM mark in the inbound and outbound | |
3255e489 | 891 | IPsec SAs and policies. If the mask is missing then a default |
d5f29da3 AS |
892 | mask of |
893 | .B 0xffffffff | |
894 | is assumed. | |
895 | .TP | |
6bcf6016 TB |
896 | .BR mark_in " = <value>[/<mask>]" |
897 | sets an XFRM mark in the inbound IPsec SA and | |
a674c79a | 898 | policy. If the mask is missing then a default mask of |
d5f29da3 AS |
899 | .B 0xffffffff |
900 | is assumed. | |
901 | .TP | |
6bcf6016 TB |
902 | .BR mark_out " = <value>[/<mask>]" |
903 | sets an XFRM mark in the outbound IPsec SA and | |
a674c79a | 904 | policy. If the mask is missing then a default mask of |
d5f29da3 AS |
905 | .B 0xffffffff |
906 | is assumed. | |
deddfde9 | 907 | .TP |
6bcf6016 | 908 | .BR mobike " = " yes " | no" |
8c4339bd AS |
909 | enables the IKEv2 MOBIKE protocol defined by RFC 4555. Accepted values are |
910 | .B yes | |
911 | (the default) and | |
912 | .BR no . | |
913 | If set to | |
914 | .BR no , | |
78279973 MW |
915 | the IKEv2 charon daemon will not actively propose MOBIKE as initiator and |
916 | ignore the MOBIKE_SUPPORTED notify as responder. | |
8c4339bd | 917 | .TP |
6bcf6016 | 918 | .BR modeconfig " = push | " pull |
7900ab1b AS |
919 | defines which mode is used to assign a virtual IP. |
920 | Accepted values are | |
921 | .B push | |
922 | and | |
923 | .B pull | |
924 | (the default). | |
925 | Currently relevant for IKEv1 only since IKEv2 always uses the configuration | |
f115838b TB |
926 | payload in pull mode. Cisco VPN gateways usually operate in |
927 | .B push | |
928 | mode. | |
7900ab1b | 929 | .TP |
6bcf6016 | 930 | .BR pfs " = " yes " | no" |
fea5e716 MW |
931 | whether Perfect Forward Secrecy of keys is desired on the connection's |
932 | keying channel | |
933 | (with PFS, penetration of the key-exchange protocol | |
934 | does not compromise keys negotiated earlier); | |
935 | acceptable values are | |
936 | .B yes | |
937 | (the default) | |
938 | and | |
7900ab1b AS |
939 | .BR no. |
940 | IKEv2 always uses PFS for IKE_SA rekeying whereas for CHILD_SA rekeying | |
941 | PFS is enforced by defining a Diffie-Hellman modp group in the | |
942 | .B esp | |
943 | parameter. | |
0ef961b8 | 944 | .TP |
6bcf6016 | 945 | .BR pfsgroup " = <modp group>" |
0ef961b8 AS |
946 | defines a Diffie-Hellman group for perfect forward secrecy in IKEv1 Quick Mode |
947 | differing from the DH group used for IKEv1 Main Mode (IKEv1 only). | |
fea5e716 | 948 | .TP |
6bcf6016 | 949 | .BR reauth " = " yes " | no" |
c2bc2b27 AS |
950 | whether rekeying of an IKE_SA should also reauthenticate the peer. In IKEv1, |
951 | reauthentication is always done. In IKEv2, a value of | |
952 | .B no | |
953 | rekeys without uninstalling the IPsec SAs, a value of | |
954 | .B yes | |
955 | (the default) creates a new IKE_SA from scratch and tries to recreate | |
956 | all IPsec SAs. | |
957 | .TP | |
6bcf6016 | 958 | .BR rekey " = " yes " | no" |
fea5e716 MW |
959 | whether a connection should be renegotiated when it is about to expire; |
960 | acceptable values are | |
961 | .B yes | |
962 | (the default) | |
963 | and | |
964 | .BR no . | |
7900ab1b | 965 | The two ends need not agree, but while a value of |
fea5e716 | 966 | .B no |
f115838b | 967 | prevents pluto/charon from requesting renegotiation, |
fea5e716 MW |
968 | it does not prevent responding to renegotiation requested from the other end, |
969 | so | |
970 | .B no | |
971 | will be largely ineffective unless both ends agree on it. | |
972 | .TP | |
6bcf6016 | 973 | .BR rekeyfuzz " = " 100% " | <percentage>" |
fea5e716 | 974 | maximum percentage by which |
deddfde9 TB |
975 | .BR marginbytes , |
976 | .B marginpackets | |
977 | and | |
978 | .B margintime | |
fea5e716 MW |
979 | should be randomly increased to randomize rekeying intervals |
980 | (important for hosts with many connections); | |
981 | acceptable values are an integer, | |
982 | which may exceed 100, | |
983 | followed by a `%' | |
deddfde9 | 984 | (defaults to |
fea5e716 MW |
985 | .BR 100% ). |
986 | The value of | |
deddfde9 | 987 | .BR marginTYPE , |
fea5e716 MW |
988 | after this random increase, |
989 | must not exceed | |
deddfde9 TB |
990 | .B lifeTYPE |
991 | (where TYPE is one of | |
992 | .IR bytes , | |
993 | .I packets | |
994 | or | |
995 | .IR time ). | |
fea5e716 MW |
996 | The value |
997 | .B 0% | |
deddfde9 | 998 | will suppress randomization. |
9f8ceffb TB |
999 | Relevant only locally, other end need not agree on it. Also see EXPIRY/REKEY |
1000 | below. | |
fea5e716 MW |
1001 | .TP |
1002 | .B rekeymargin | |
deddfde9 TB |
1003 | synonym for |
1004 | .BR margintime . | |
532f2347 | 1005 | .TP |
6bcf6016 | 1006 | .BR reqid " = <number>" |
b5be105a | 1007 | sets the reqid for a given connection to a pre-configured fixed value. |
a729d17a | 1008 | .TP |
6c302616 MW |
1009 | .BR tfc " = <value>" |
1010 | number of bytes to pad ESP payload data to. Traffic Flow Confidentiality | |
1011 | is currently supported in IKEv2 and applies to outgoing packets only. The | |
1012 | special value | |
1013 | .BR %mtu | |
1014 | fills up ESP packets with padding to have the size of the MTU. | |
1015 | .TP | |
6bcf6016 | 1016 | .BR type " = " tunnel " | transport | transport_proxy | passthrough | drop" |
c2bc2b27 AS |
1017 | the type of the connection; currently the accepted values |
1018 | are | |
1019 | .B tunnel | |
1020 | (the default) | |
1021 | signifying a host-to-host, host-to-subnet, or subnet-to-subnet tunnel; | |
1022 | .BR transport , | |
1023 | signifying host-to-host transport mode; | |
84bec926 AS |
1024 | .BR transport_proxy , |
1025 | signifying the special Mobile IPv6 transport proxy mode; | |
c2bc2b27 AS |
1026 | .BR passthrough , |
1027 | signifying that no IPsec processing should be done at all; | |
1028 | .BR drop , | |
1029 | signifying that packets should be discarded; and | |
1030 | .BR reject , | |
a5477a6f TB |
1031 | signifying that packets should be discarded and a diagnostic ICMP returned |
1032 | .RB ( reject | |
1033 | is currently not supported by the NETKEY stack of the Linux 2.6 kernel). | |
f115838b | 1034 | The IKEv2 daemon charon currently supports |
84bec926 AS |
1035 | .BR tunnel , |
1036 | .BR transport , | |
c2bc2b27 | 1037 | and |
a5477a6f | 1038 | .BR transport_proxy |
f115838b | 1039 | connection types, only. |
fea5e716 | 1040 | .TP |
6bcf6016 | 1041 | .BR xauth " = " client " | server" |
c2bc2b27 AS |
1042 | specifies the role in the XAUTH protocol if activated by |
1043 | .B authby=xauthpsk | |
1044 | or | |
1045 | .B authby=xauthrsasig. | |
1046 | Accepted values are | |
1047 | .B server | |
1048 | and | |
1049 | .B client | |
1050 | (the default). | |
d5cc1758 | 1051 | |
e74bc8e5 | 1052 | .SS "CONN PARAMETERS: IKEv2 MEDIATION EXTENSION" |
8015c91c | 1053 | The following parameters are relevant to IKEv2 Mediation Extension |
e74bc8e5 | 1054 | operation only. |
6bcf6016 TB |
1055 | .TP |
1056 | .BR mediation " = yes | " no | |
e74bc8e5 | 1057 | whether this connection is a mediation connection, ie. whether this |
d5cc1758 TB |
1058 | connection is used to mediate other connections. Mediation connections |
1059 | create no child SA. Acceptable values are | |
1060 | .B no | |
1061 | (the default) and | |
1062 | .BR yes . | |
1063 | .TP | |
6bcf6016 | 1064 | .BR mediated_by " = <name>" |
d5cc1758 TB |
1065 | the name of the connection to mediate this connection through. If given, |
1066 | the connection will be mediated through the named mediation connection. | |
1067 | The mediation connection must set | |
e74bc8e5 | 1068 | .BR mediation=yes . |
d5cc1758 | 1069 | .TP |
6bcf6016 | 1070 | .BR me_peerid " = <id>" |
d5cc1758 TB |
1071 | ID as which the peer is known to the mediation server, ie. which the other |
1072 | end of this connection uses as its | |
1073 | .B leftid | |
1074 | on its connection to the mediation server. This is the ID we request the | |
1075 | mediation server to mediate us with. If | |
e74bc8e5 | 1076 | .B me_peerid |
d5cc1758 TB |
1077 | is not given, the |
1078 | .B rightid | |
1079 | of this connection will be used as peer ID. | |
1080 | ||
fea5e716 | 1081 | .SH "CA SECTIONS" |
bf3c3715 TB |
1082 | These are optional sections that can be used to assign special |
1083 | parameters to a Certification Authority (CA). Because the daemons | |
1084 | automatically import CA certificates from \fI/etc/ipsec.d/cacerts\fP, | |
1085 | there is no need to explicitly add them with a CA section, unless you | |
1086 | want to assign special parameters (like a CRL) to a CA. | |
6bcf6016 | 1087 | .TP |
a5477a6f TB |
1088 | .BR also " = <name>" |
1089 | includes ca section | |
1090 | .BR <name> . | |
1091 | .TP | |
6bcf6016 | 1092 | .BR auto " = " ignore " | add" |
fea5e716 MW |
1093 | currently can have either the value |
1094 | .B ignore | |
6bcf6016 TB |
1095 | (the default) or |
1096 | .BR add . | |
fea5e716 | 1097 | .TP |
6bcf6016 | 1098 | .BR cacert " = <path>" |
8015c91c | 1099 | defines a path to the CA certificate either relative to |
fea5e716 MW |
1100 | \fI/etc/ipsec.d/cacerts\fP or as an absolute path. |
1101 | .TP | |
6bcf6016 | 1102 | .BR crluri " = <uri>" |
fea5e716 MW |
1103 | defines a CRL distribution point (ldap, http, or file URI) |
1104 | .TP | |
7900ab1b AS |
1105 | .B crluri1 |
1106 | synonym for | |
1107 | .B crluri. | |
1108 | .TP | |
6bcf6016 | 1109 | .BR crluri2 " = <uri>" |
fea5e716 MW |
1110 | defines an alternative CRL distribution point (ldap, http, or file URI) |
1111 | .TP | |
6bcf6016 | 1112 | .BR ldaphost " = <hostname>" |
7900ab1b | 1113 | defines an ldap host. Currently used by IKEv1 only. |
fea5e716 | 1114 | .TP |
6bcf6016 | 1115 | .BR ocspuri " = <uri>" |
fea5e716 | 1116 | defines an OCSP URI. |
7900ab1b AS |
1117 | .TP |
1118 | .B ocspuri1 | |
1119 | synonym for | |
1120 | .B ocspuri. | |
1121 | .TP | |
6bcf6016 | 1122 | .BR ocspuri2 " = <uri>" |
7900ab1b | 1123 | defines an alternative OCSP URI. Currently used by IKEv2 only. |
f115838b | 1124 | .TP |
6bcf6016 | 1125 | .BR certuribase " = <uri>" |
6439267a TB |
1126 | defines the base URI for the Hash and URL feature supported by IKEv2. |
1127 | Instead of exchanging complete certificates, IKEv2 allows to send an URI | |
1128 | that resolves to the DER encoded certificate. The certificate URIs are built | |
1129 | by appending the SHA1 hash of the DER encoded certificates to this base URI. | |
fea5e716 MW |
1130 | .SH "CONFIG SECTIONS" |
1131 | At present, the only | |
1132 | .B config | |
1133 | section known to the IPsec software is the one named | |
1134 | .BR setup , | |
f115838b | 1135 | which contains information used when the software is being started. |
fea5e716 MW |
1136 | Here's an example: |
1137 | .PP | |
1138 | .ne 8 | |
1139 | .nf | |
1140 | .ft B | |
1141 | .ta 1c | |
1142 | config setup | |
fea5e716 | 1143 | plutodebug=all |
7900ab1b AS |
1144 | crlcheckinterval=10m |
1145 | strictcrlpolicy=yes | |
fea5e716 MW |
1146 | .ft |
1147 | .fi | |
1148 | .PP | |
1149 | Parameters are optional unless marked ``(required)''. | |
1150 | The currently-accepted | |
1151 | .I parameter | |
1152 | names in a | |
1153 | .B config | |
1154 | .B setup | |
b360e393 | 1155 | section affecting both daemons are: |
6bcf6016 TB |
1156 | .TP |
1157 | .BR cachecrls " = yes | " no | |
e0e7ef07 AS |
1158 | certificate revocation lists (CRLs) fetched via http or ldap will be cached in |
1159 | \fI/etc/ipsec.d/crls/\fR under a unique file name derived from the certification | |
1160 | authority's public key. | |
1161 | Accepted values are | |
1162 | .B yes | |
1163 | and | |
1164 | .B no | |
a5477a6f | 1165 | (the default). Only relevant for IKEv1, as CRLs are always cached in IKEv2. |
7900ab1b | 1166 | .TP |
6bcf6016 TB |
1167 | .BR charonstart " = " yes " | no" |
1168 | whether to start the IKEv2 charon daemon or not. | |
8015c91c | 1169 | The default is |
e4838d02 MW |
1170 | .B yes |
1171 | if starter was compiled with IKEv2 support. | |
7900ab1b | 1172 | .TP |
6bcf6016 TB |
1173 | .BR plutostart " = " yes " | no" |
1174 | whether to start the IKEv1 pluto daemon or not. | |
8015c91c | 1175 | The default is |
e4838d02 MW |
1176 | .B yes |
1177 | if starter was compiled with IKEv1 support. | |
fea5e716 | 1178 | .TP |
6bcf6016 TB |
1179 | .BR strictcrlpolicy " = yes | ifuri | " no |
1180 | defines if a fresh CRL must be available in order for the peer authentication | |
1181 | based on RSA signatures to succeed. | |
e0e7ef07 AS |
1182 | IKEv2 additionally recognizes |
1183 | .B ifuri | |
1184 | which reverts to | |
1185 | .B yes | |
1186 | if at least one CRL URI is defined and to | |
1187 | .B no | |
1188 | if no URI is known. | |
b360e393 | 1189 | .TP |
6bcf6016 | 1190 | .BR uniqueids " = " yes " | no | replace | keep" |
b360e393 MW |
1191 | whether a particular participant ID should be kept unique, |
1192 | with any new (automatically keyed) | |
1193 | connection using an ID from a different IP address | |
1194 | deemed to replace all old ones using that ID; | |
1195 | acceptable values are | |
1196 | .B yes | |
1197 | (the default) | |
1198 | and | |
1199 | .BR no . | |
1200 | Participant IDs normally \fIare\fR unique, | |
1201 | so a new (automatically-keyed) connection using the same ID is | |
1202 | almost invariably intended to replace an old one. | |
1203 | The IKEv2 daemon also accepts the value | |
1204 | .B replace | |
f3bb1bd0 | 1205 | which is identical to |
b360e393 MW |
1206 | .B yes |
1207 | and the value | |
1208 | .B keep | |
1209 | to reject new IKE_SA setups and keep the duplicate established earlier. | |
e0e7ef07 AS |
1210 | .PP |
1211 | The following | |
1212 | .B config section | |
1213 | parameters are used by the IKEv1 Pluto daemon only: | |
1214 | .TP | |
6bcf6016 | 1215 | .BR crlcheckinterval " = " 0s " | <time>" |
b360e393 MW |
1216 | interval in seconds. CRL fetching is enabled if the value is greater than zero. |
1217 | Asynchronous, periodic checking for fresh CRLs is currently done by the | |
1218 | IKEv1 Pluto daemon only. | |
1219 | .TP | |
6bcf6016 | 1220 | .BR keep_alive " = " 20s " | <time>" |
e0e7ef07 AS |
1221 | interval in seconds between NAT keep alive packets, the default being 20 seconds. |
1222 | .TP | |
6bcf6016 | 1223 | .BR nat_traversal " = yes | " no |
e0e7ef07 AS |
1224 | activates NAT traversal by accepting source ISAKMP ports different from udp/500 and |
1225 | being able of floating to udp/4500 if a NAT situation is detected. | |
1226 | Accepted values are | |
1227 | .B yes | |
1228 | and | |
1229 | .B no | |
1230 | (the default). | |
a5477a6f | 1231 | Used by IKEv1 only, NAT traversal is always being active in IKEv2. |
8c4339bd | 1232 | .TP |
6bcf6016 | 1233 | .BR nocrsend " = yes | " no |
e0e7ef07 | 1234 | no certificate request payloads will be sent. |
e0e7ef07 | 1235 | .TP |
6bcf6016 | 1236 | .BR pkcs11initargs " = <args>" |
dd0ee786 AS |
1237 | non-standard argument string for PKCS#11 C_Initialize() function; |
1238 | required by NSS softoken. | |
1239 | .TP | |
6bcf6016 | 1240 | .BR pkcs11module " = <args>" |
e0e7ef07 AS |
1241 | defines the path to a dynamically loadable PKCS #11 library. |
1242 | .TP | |
6bcf6016 | 1243 | .BR pkcs11keepstate " = yes | " no |
e0e7ef07 AS |
1244 | PKCS #11 login sessions will be kept during the whole lifetime of the keying |
1245 | daemon. Useful with pin-pad smart card readers. | |
1246 | Accepted values are | |
1247 | .B yes | |
1248 | and | |
1249 | .B no | |
1250 | (the default). | |
1251 | .TP | |
6bcf6016 | 1252 | .BR pkcs11proxy " = yes | " no |
e0e7ef07 AS |
1253 | Pluto will act as a PKCS #11 proxy accessible via the whack interface. |
1254 | Accepted values are | |
1255 | .B yes | |
1256 | and | |
1257 | .B no | |
1258 | (the default). | |
1259 | .TP | |
6bcf6016 TB |
1260 | .BR plutodebug " = " none " | <debug list> | all" |
1261 | how much pluto debugging output should be logged. | |
fea5e716 MW |
1262 | An empty value, |
1263 | or the magic value | |
1264 | .BR none , | |
1265 | means no debugging output (the default). | |
1266 | The magic value | |
1267 | .B all | |
1268 | means full output. | |
1269 | Otherwise only the specified types of output | |
1270 | (a quoted list, names without the | |
1271 | .B \-\-debug\- | |
1272 | prefix, | |
1273 | separated by white space) are enabled; | |
1274 | for details on available debugging types, see | |
7900ab1b | 1275 | .IR pluto (8). |
fea5e716 | 1276 | .TP |
6bcf6016 | 1277 | .BR plutostderrlog " = <file>" |
0fc1fc0e | 1278 | Pluto will not use syslog, but rather log to stderr, and redirect stderr |
6bcf6016 | 1279 | to <file>. |
0fc1fc0e | 1280 | .TP |
6bcf6016 TB |
1281 | .BR postpluto " = <command>" |
1282 | shell command to run after starting pluto | |
e0e7ef07 | 1283 | (e.g., to remove a decrypted copy of the |
fea5e716 MW |
1284 | .I ipsec.secrets |
1285 | file). | |
1286 | It's run in a very simple way; | |
1287 | complexities like I/O redirection are best hidden within a script. | |
1288 | Any output is redirected for logging, | |
1289 | so running interactive commands is difficult unless they use | |
1290 | .I /dev/tty | |
1291 | or equivalent for their interaction. | |
1292 | Default is none. | |
1293 | .TP | |
6bcf6016 TB |
1294 | .BR prepluto " = <command>" |
1295 | shell command to run before starting pluto | |
e0e7ef07 | 1296 | (e.g., to decrypt an encrypted copy of the |
fea5e716 MW |
1297 | .I ipsec.secrets |
1298 | file). | |
1299 | It's run in a very simple way; | |
1300 | complexities like I/O redirection are best hidden within a script. | |
1301 | Any output is redirected for logging, | |
1302 | so running interactive commands is difficult unless they use | |
1303 | .I /dev/tty | |
1304 | or equivalent for their interaction. | |
1305 | Default is none. | |
1306 | .TP | |
6bcf6016 | 1307 | .BR virtual_private " = <networks>" |
e0e7ef07 | 1308 | defines private networks using a wildcard notation. |
e0e7ef07 AS |
1309 | .PP |
1310 | The following | |
1311 | .B config section | |
6bcf6016 | 1312 | parameters are used by the IKEv2 charon daemon only: |
fea5e716 | 1313 | .TP |
6bcf6016 TB |
1314 | .BR charondebug " = <debug list>" |
1315 | how much charon debugging output should be logged. | |
5b217e49 | 1316 | A comma separated list containing type/level-pairs may |
e0e7ef07 AS |
1317 | be specified, e.g: |
1318 | .B dmn 3, ike 1, net -1. | |
1319 | Acceptable values for types are | |
7213abcb | 1320 | .B dmn, mgr, ike, chd, job, cfg, knl, net, enc, lib, tls, tnc, imc, imv, pts |
e0e7ef07 AS |
1321 | and the level is one of |
1322 | .B -1, 0, 1, 2, 3, 4 | |
5b217e49 TB |
1323 | (for silent, audit, control, controlmore, raw, private). By default, the level |
1324 | is set to | |
1325 | .B 1 | |
1326 | for all types. For more flexibility see LOGGER CONFIGURATION in | |
a5477a6f TB |
1327 | .IR strongswan.conf (5). |
1328 | ||
9f8ceffb TB |
1329 | .SH IKEv2 EXPIRY/REKEY |
1330 | The IKE SAs and IPsec SAs negotiated by the daemon can be configured to expire | |
1331 | after a specific amount of time. For IPsec SAs this can also happen after a | |
1332 | specified number of transmitted packets or transmitted bytes. The following | |
1333 | settings can be used to configure this: | |
1334 | .TS | |
1335 | l r l r,- - - -,lB s lB s,a r a r. | |
1336 | Setting Default Setting Default | |
1337 | IKE SA IPsec SA | |
1338 | ikelifetime 3h lifebytes - | |
1339 | lifepackets - | |
1340 | lifetime 1h | |
1341 | .TE | |
1342 | .SS Rekeying | |
1343 | IKE SAs as well as IPsec SAs can be rekeyed before they expire. This can be | |
1344 | configured using the following settings: | |
1345 | .TS | |
1346 | l r l r,- - - -,lB s lB s,a r a r. | |
1347 | Setting Default Setting Default | |
1348 | IKE and IPsec SA IPsec SA | |
1349 | margintime 9m marginbytes - | |
1350 | marginpackets - | |
1351 | .TE | |
1352 | .SS Randomization | |
1353 | To avoid collisions the specified margins are increased randomly before | |
1354 | subtracting them from the expiration limits (see formula below). This is | |
1355 | controlled by the | |
1356 | .B rekeyfuzz | |
1357 | setting: | |
1358 | .TS | |
1359 | l r,- -,lB s,a r. | |
1360 | Setting Default | |
1361 | IKE and IPsec SA | |
1362 | rekeyfuzz 100% | |
1363 | .TE | |
1364 | .PP | |
1365 | Randomization can be disabled by setting | |
1366 | .BR rekeyfuzz " to " 0% . | |
1367 | .SS Formula | |
1368 | The following formula is used to calculate the rekey time of IPsec SAs: | |
1369 | .PP | |
1370 | .EX | |
1371 | rekeytime = lifetime - (margintime + random(0, margintime * rekeyfuzz)) | |
1372 | .EE | |
1373 | .PP | |
1374 | It applies equally to IKE SAs and byte and packet limits for IPsec SAs. | |
1375 | .SS Example | |
1376 | Let's consider the default configuration: | |
1377 | .PP | |
1378 | .EX | |
1379 | lifetime = 1h | |
1380 | margintime = 9m | |
1381 | rekeyfuzz = 100% | |
1382 | .EE | |
1383 | .PP | |
1384 | From the formula above follows that the rekey time lies between: | |
1385 | .PP | |
1386 | .EX | |
1387 | rekeytime_min = 1h - (9m + 9m) = 42m | |
1388 | rekeytime_max = 1h - (9m + 0m) = 51m | |
1389 | .EE | |
1390 | .PP | |
1391 | Thus, the daemon will attempt to rekey the IPsec SA at a random time | |
1392 | between 42 and 51 minutes after establishing the SA. Or, in other words, | |
1393 | between 9 and 18 minutes before the SA expires. | |
1394 | .SS Notes | |
1395 | .IP \[bu] | |
1396 | Since the rekeying of an SA needs some time, the margin values must not be | |
1397 | too low. | |
1398 | .IP \[bu] | |
1399 | The value | |
1400 | .B margin... + margin... * rekeyfuzz | |
1401 | must not exceed the original limit. For example, specifying | |
1402 | .B margintime = 30m | |
1403 | in the default configuration is a bad idea as there is a chance that the rekey | |
1404 | time equals zero and, thus, rekeying gets disabled. | |
fea5e716 MW |
1405 | .SH FILES |
1406 | .nf | |
1407 | /etc/ipsec.conf | |
7900ab1b AS |
1408 | /etc/ipsec.d/aacerts |
1409 | /etc/ipsec.d/acerts | |
fea5e716 MW |
1410 | /etc/ipsec.d/cacerts |
1411 | /etc/ipsec.d/certs | |
1412 | /etc/ipsec.d/crls | |
fea5e716 MW |
1413 | |
1414 | .SH SEE ALSO | |
8207a742 | 1415 | strongswan.conf(5), ipsec.secrets(5), ipsec(8), pluto(8) |
fea5e716 | 1416 | .SH HISTORY |
f115838b TB |
1417 | Originally written for the FreeS/WAN project by Henry Spencer. |
1418 | Updated and extended for the strongSwan project <http://www.strongswan.org> by | |
1419 | Tobias Brunner, Andreas Steffen and Martin Willi. | |
fea5e716 MW |
1420 | .SH BUGS |
1421 | .PP | |
7900ab1b | 1422 | If conns are to be added before DNS is available, \fBleft=\fP\fIFQDN\fP |
fea5e716 | 1423 | will fail. |