]>
Commit | Line | Data |
---|---|---|
7900ab1b | 1 | .TH IPSEC.CONF 5 "27 Jun 2007" |
496e76cb | 2 | .\" RCSID $Id$ |
fea5e716 MW |
3 | .SH NAME |
4 | ipsec.conf \- IPsec configuration and connections | |
5 | .SH DESCRIPTION | |
6 | The optional | |
7 | .I ipsec.conf | |
8 | file | |
9 | specifies most configuration and control information for the | |
10 | strongSwan IPsec subsystem. | |
11 | (The major exception is secrets for authentication; | |
12 | see | |
13 | .IR ipsec.secrets (5).) | |
532f2347 | 14 | Its contents are not security-sensitive. |
fea5e716 MW |
15 | .PP |
16 | The file is a text file, consisting of one or more | |
17 | .IR sections . | |
18 | White space followed by | |
19 | .B # | |
20 | followed by anything to the end of the line | |
21 | is a comment and is ignored, | |
22 | as are empty lines which are not within a section. | |
23 | .PP | |
24 | A line which contains | |
25 | .B include | |
26 | and a file name, separated by white space, | |
27 | is replaced by the contents of that file, | |
28 | preceded and followed by empty lines. | |
29 | If the file name is not a full pathname, | |
30 | it is considered to be relative to the directory containing the | |
31 | including file. | |
32 | Such inclusions can be nested. | |
33 | Only a single filename may be supplied, and it may not contain white space, | |
34 | but it may include shell wildcards (see | |
35 | .IR sh (1)); | |
36 | for example: | |
37 | .PP | |
38 | .B include | |
39 | .B "ipsec.*.conf" | |
40 | .PP | |
41 | The intention of the include facility is mostly to permit keeping | |
42 | information on connections, or sets of connections, | |
43 | separate from the main configuration file. | |
44 | This permits such connection descriptions to be changed, | |
45 | copied to the other security gateways involved, etc., | |
46 | without having to constantly extract them from the configuration | |
47 | file and then insert them back into it. | |
48 | Note also the | |
49 | .B also | |
50 | parameter (described below) which permits splitting a single logical | |
51 | section (e.g. a connection description) into several actual sections. | |
52 | .PP | |
fea5e716 MW |
53 | A section |
54 | begins with a line of the form: | |
55 | .PP | |
56 | .I type | |
57 | .I name | |
58 | .PP | |
59 | where | |
60 | .I type | |
61 | indicates what type of section follows, and | |
62 | .I name | |
63 | is an arbitrary name which distinguishes the section from others | |
64 | of the same type. | |
65 | (Names must start with a letter and may contain only | |
66 | letters, digits, periods, underscores, and hyphens.) | |
67 | All subsequent non-empty lines | |
68 | which begin with white space are part of the section; | |
69 | comments within a section must begin with white space too. | |
70 | There may be only one section of a given type with a given name. | |
71 | .PP | |
72 | Lines within the section are generally of the form | |
73 | .PP | |
74 | \ \ \ \ \ \fIparameter\fB=\fIvalue\fR | |
75 | .PP | |
76 | (note the mandatory preceding white space). | |
77 | There can be white space on either side of the | |
78 | .BR = . | |
79 | Parameter names follow the same syntax as section names, | |
80 | and are specific to a section type. | |
81 | Unless otherwise explicitly specified, | |
82 | no parameter name may appear more than once in a section. | |
83 | .PP | |
84 | An empty | |
85 | .I value | |
86 | stands for the system default value (if any) of the parameter, | |
87 | i.e. it is roughly equivalent to omitting the parameter line entirely. | |
88 | A | |
89 | .I value | |
90 | may contain white space only if the entire | |
91 | .I value | |
92 | is enclosed in double quotes (\fB"\fR); | |
93 | a | |
94 | .I value | |
95 | cannot itself contain a double quote, | |
96 | nor may it be continued across more than one line. | |
97 | .PP | |
98 | Numeric values are specified to be either an ``integer'' | |
99 | (a sequence of digits) or a ``decimal number'' | |
100 | (sequence of digits optionally followed by `.' and another sequence of digits). | |
101 | .PP | |
102 | There is currently one parameter which is available in any type of | |
103 | section: | |
104 | .TP | |
105 | .B also | |
106 | the value is a section name; | |
107 | the parameters of that section are appended to this section, | |
108 | as if they had been written as part of it. | |
109 | The specified section must exist, must follow the current one, | |
110 | and must have the same section type. | |
111 | (Nesting is permitted, | |
112 | and there may be more than one | |
113 | .B also | |
114 | in a single section, | |
115 | although it is forbidden to append the same section more than once.) | |
fea5e716 MW |
116 | .PP |
117 | A section with name | |
118 | .B %default | |
119 | specifies defaults for sections of the same type. | |
120 | For each parameter in it, | |
121 | any section of that type which does not have a parameter of the same name | |
122 | gets a copy of the one from the | |
123 | .B %default | |
124 | section. | |
125 | There may be multiple | |
126 | .B %default | |
127 | sections of a given type, | |
128 | but only one default may be supplied for any specific parameter name, | |
129 | and all | |
130 | .B %default | |
131 | sections of a given type must precede all non-\c | |
132 | .B %default | |
133 | sections of that type. | |
134 | .B %default | |
135 | sections may not contain the | |
136 | .B also | |
137 | parameter. | |
138 | .PP | |
139 | Currently there are three types of sections: | |
140 | a | |
141 | .B config | |
142 | section specifies general configuration information for IPsec, a | |
143 | .B conn | |
144 | section specifies an IPsec connection, while a | |
145 | .B ca | |
7900ab1b | 146 | section specifies special properties of a certification authority. |
fea5e716 MW |
147 | .SH "CONN SECTIONS" |
148 | A | |
149 | .B conn | |
150 | section contains a | |
151 | .IR "connection specification" , | |
152 | defining a network connection to be made using IPsec. | |
532f2347 | 153 | The name given is arbitrary, and is used to identify the connection. |
fea5e716 MW |
154 | Here's a simple example: |
155 | .PP | |
156 | .ne 10 | |
157 | .nf | |
158 | .ft B | |
159 | .ta 1c | |
160 | conn snt | |
7900ab1b AS |
161 | left=192.168.0.1 |
162 | leftsubnet=10.1.0.0/16 | |
163 | right=192.168.0.2 | |
164 | rightsubnet=10.1.0.0/16 | |
fea5e716 | 165 | keyingtries=%forever |
7900ab1b | 166 | auto=add |
fea5e716 MW |
167 | .ft |
168 | .fi | |
169 | .PP | |
532f2347 | 170 | A note on terminology: There are two kinds of communications going on: |
fea5e716 MW |
171 | transmission of user IP packets, and gateway-to-gateway negotiations for |
172 | keying, rekeying, and general control. | |
532f2347 | 173 | The path to control the connection is called 'ISAKMP SA' in IKEv1 and |
7900ab1b | 174 | 'IKE SA' in the IKEv2 protocol. That what is being negotiated, the kernel |
532f2347 MW |
175 | level data path, is called 'IPsec SA'. |
176 | strongSwan currently uses two separate keying daemons. Pluto handles | |
177 | all IKEv1 connections, Charon is the new daemon supporting the IKEv2 protocol. | |
178 | Charon does not support all keywords yet. | |
fea5e716 MW |
179 | .PP |
180 | To avoid trivial editing of the configuration file to suit it to each system | |
181 | involved in a connection, | |
182 | connection specifications are written in terms of | |
183 | .I left | |
184 | and | |
185 | .I right | |
186 | participants, | |
187 | rather than in terms of local and remote. | |
188 | Which participant is considered | |
189 | .I left | |
190 | or | |
191 | .I right | |
192 | is arbitrary; | |
193 | IPsec figures out which one it is being run on based on internal information. | |
194 | This permits using identical connection specifications on both ends. | |
195 | There are cases where there is no symmetry; a good convention is to | |
196 | use | |
197 | .I left | |
198 | for the local side and | |
199 | .I right | |
200 | for the remote side (the first letters are a good mnemonic). | |
201 | .PP | |
202 | Many of the parameters relate to one participant or the other; | |
203 | only the ones for | |
204 | .I left | |
205 | are listed here, but every parameter whose name begins with | |
206 | .B left | |
207 | has a | |
208 | .B right | |
209 | counterpart, | |
210 | whose description is the same but with | |
211 | .B left | |
212 | and | |
213 | .B right | |
214 | reversed. | |
215 | .PP | |
532f2347 MW |
216 | Parameters are optional unless marked '(required)'. |
217 | .SS "CONN PARAMETERS" | |
218 | Unless otherwise noted, for a connection to work, | |
fea5e716 MW |
219 | in general it is necessary for the two ends to agree exactly |
220 | on the values of these parameters. | |
221 | .TP 14 | |
c2bc2b27 AS |
222 | .B ah |
223 | AH authentication algorithm to be used | |
224 | for the connection, e.g. | |
225 | .B hmac-md5. | |
fea5e716 MW |
226 | .TP |
227 | .B auth | |
228 | whether authentication should be done as part of | |
229 | ESP encryption, or separately using the AH protocol; | |
230 | acceptable values are | |
231 | .B esp | |
232 | (the default) and | |
233 | .BR ah . | |
532f2347 | 234 | The IKEv2 daemon currently supports only ESP. |
fea5e716 MW |
235 | .TP |
236 | .B authby | |
237 | how the two security gateways should authenticate each other; | |
238 | acceptable values are | |
239 | .B secret | |
7900ab1b AS |
240 | or |
241 | .B psk | |
fea5e716 MW |
242 | for shared secrets, |
243 | .B rsasig | |
244 | for RSA digital signatures (the default), | |
245 | .B secret|rsasig | |
246 | for either, and | |
247 | .B never | |
248 | if negotiation is never to be attempted or accepted (useful for shunt-only conns). | |
532f2347 | 249 | Digital signatures are superior in every way to shared secrets. In IKEv2, the |
7900ab1b AS |
250 | two ends must not agree on this parameter, it is relevant for the |
251 | outbound authentication method only. | |
252 | IKEv1 additionally supports the values | |
253 | .B xauthpsk | |
254 | and | |
255 | .B xauthrsasig | |
256 | that will enable eXtended AUTHentication (XAUTH) in addition to IKEv1 main mode | |
257 | based on shared secrets or digital RSA signatures, respectively. | |
258 | IKEv2 additionally supports the value | |
9b45443d MW |
259 | .B eap, |
260 | which indicates an initiator to request EAP authentication. The EAP method to | |
261 | use is selected by the server (see | |
262 | .B eap). | |
fea5e716 | 263 | .TP |
c2bc2b27 AS |
264 | .B auto |
265 | what operation, if any, should be done automatically at IPsec startup; | |
266 | currently-accepted values are | |
267 | .B add | |
268 | , | |
269 | .B route | |
270 | , | |
271 | .B start | |
7900ab1b | 272 | and |
c2bc2b27 AS |
273 | .BR ignore . |
274 | .B add | |
275 | loads a connection without starting it. | |
276 | .B route | |
277 | loads a connection and installs kernel traps. If traffic is detected between | |
278 | .B leftsubnet | |
279 | and | |
280 | .B rightsubnet | |
281 | , a connection is established. | |
282 | .B start | |
283 | loads a connection and brings it up immediatly. | |
284 | .B ignore | |
285 | ignores the connection. This is equal to delete a connection from the config | |
286 | file. | |
287 | Relevant only locally, other end need not agree on it | |
288 | (but in general, for an intended-to-be-permanent connection, | |
289 | both ends should use | |
290 | .B auto=start | |
291 | to ensure that any reboot causes immediate renegotiation). | |
7900ab1b | 292 | .TP |
fea5e716 MW |
293 | .B compress |
294 | whether IPComp compression of content is proposed on the connection | |
295 | (link-level compression does not work on encrypted data, | |
296 | so to be effective, compression must be done \fIbefore\fR encryption); | |
297 | acceptable values are | |
298 | .B yes | |
299 | and | |
300 | .B no | |
532f2347 | 301 | (the default). A value of |
fea5e716 MW |
302 | .B yes |
303 | causes IPsec to propose both compressed and uncompressed, | |
304 | and prefer compressed. | |
305 | A value of | |
306 | .B no | |
307 | prevents IPsec from proposing compression; | |
308 | a proposal to compress will still be accepted. | |
532f2347 | 309 | IKEv2 does not support IP compression yet. |
fea5e716 | 310 | .TP |
fea5e716 MW |
311 | .B dpdaction |
312 | controls the use of the Dead Peer Detection protocol (DPD, RFC 3706) where | |
a655f5c0 MW |
313 | R_U_THERE notification messages (IKEv1) or empty INFORMATIONAL messages (IKEv2) |
314 | are periodically sent in order to check the | |
315 | liveliness of the IPsec peer. The values | |
7900ab1b AS |
316 | .BR clear , |
317 | .BR hold , | |
318 | and | |
319 | .B restart | |
320 | all activate DPD. If no activity is detected, all connections with a dead peer | |
fea5e716 MW |
321 | are stopped and unrouted ( |
322 | .B clear | |
7900ab1b | 323 | ), put in the hold state ( |
fea5e716 | 324 | .B hold |
7900ab1b AS |
325 | ) or restarted ( |
326 | .B restart | |
327 | ). | |
328 | For IKEv1, the default is | |
a655f5c0 MW |
329 | .B none |
330 | which disables the active sending of R_U_THERE notifications. | |
331 | Nevertheless pluto will always send the DPD Vendor ID during connection set up | |
332 | in order to signal the readiness to act passively as a responder if the peer | |
7900ab1b AS |
333 | wants to use DPD. For IKEv2, |
334 | .B none | |
335 | does't make sense, since all messages are used to detect dead peers. If specified, | |
a655f5c0 MW |
336 | it has the same meaning as the default ( |
337 | .B clear | |
fea5e716 MW |
338 | ). |
339 | .TP | |
340 | .B dpddelay | |
a655f5c0 MW |
341 | defines the period time interval with which R_U_THERE messages/INFORMATIONAL |
342 | exchanges are sent to the peer. These are only sent if no other traffic is | |
343 | received. In IKEv2, a value of 0 sends no additional INFORMATIONAL | |
344 | messages and uses only standard messages (such as those to rekey) to detect | |
345 | dead peers. | |
fea5e716 MW |
346 | .TP |
347 | .B dpdtimeout | |
348 | defines the timeout interval, after which all connections to a peer are deleted | |
a655f5c0 MW |
349 | in case of inactivity. This only applies to IKEv1, in IKEv2 the default |
350 | retransmission timeout applies, as every exchange is used to detect dead peers. | |
fea5e716 | 351 | .TP |
eea626ed | 352 | .B eap |
0f806802 | 353 | defines the EAP type to propose as server if the client has |
eea626ed | 354 | .B authby=eap |
0f806802 | 355 | selected. Acceptable values are |
eea626ed | 356 | .B aka |
0f806802 | 357 | for EAP-AKA, |
eea626ed | 358 | .B sim |
0f806802 MW |
359 | for EAP-SIM and |
360 | .B md5 | |
361 | for EAP-MD5. | |
362 | Additionally, IANA assigned EAP method numbers are accepted, or a definition | |
363 | in the form | |
364 | .B eap=type-vendor | |
365 | (e.g. | |
366 | .B eap=7-12345 | |
367 | ) can be used to specify vendor specific EAP types. | |
eea626ed | 368 | .TP |
c2bc2b27 AS |
369 | .B esp |
370 | ESP encryption/authentication algorithm to be used | |
371 | for the connection, e.g. | |
372 | .B 3des-md5 | |
373 | (encryption-integrity-[dh-group]). If dh-group is specified, CHILD_SA setup | |
374 | and rekeying include a separate diffe hellman exchange (IKEv2 only). | |
375 | .TP | |
9dae1bed MW |
376 | .B force_encap |
377 | Force UDP encapsulation for ESP packets even if no NAT situation is detected. | |
378 | This may help to hurdle restrictive firewalls. To enforce the peer to | |
379 | encapsulate packets, NAT detection payloads are faked (IKEv2 only). | |
380 | .TP | |
c2bc2b27 AS |
381 | .B ike |
382 | IKE/ISAKMP SA encryption/authentication algorithm to be used, e.g. | |
383 | .B aes128-sha1-modp2048 | |
384 | (encryption-integrity-dhgroup). In IKEv2, multiple algorithms and proposals | |
385 | may be included, such as | |
386 | .B aes128-aes256-sha1-modp1536-modp2048,3des-sha1-md5-modp1024. | |
387 | .TP | |
fea5e716 | 388 | .B ikelifetime |
532f2347 | 389 | how long the keying channel of a connection ('ISAKMP/IKE SA') |
fea5e716 MW |
390 | should last before being renegotiated. |
391 | .TP | |
392 | .B keyexchange | |
393 | method of key exchange; | |
3572b3b6 | 394 | which protocol should be used to initialize the connection. Connections marked with |
fea5e716 | 395 | .B ikev1 |
3572b3b6 | 396 | are initiated with pluto, those marked with |
fea5e716 | 397 | .B ikev2 |
3572b3b6 MW |
398 | with charon. An incoming request from the remote peer is handled by the correct |
399 | daemon, unaffected from the | |
fea5e716 | 400 | .B keyexchange |
3572b3b6 | 401 | setting. The default value |
fea5e716 MW |
402 | .B ike |
403 | currently behaves exactly as | |
404 | .B ikev1. | |
405 | .TP | |
fea5e716 MW |
406 | .B keyingtries |
407 | how many attempts (a whole number or \fB%forever\fP) should be made to | |
408 | negotiate a connection, or a replacement for one, before giving up | |
409 | (default | |
410 | .BR %forever ). | |
411 | The value \fB%forever\fP | |
532f2347 | 412 | means 'never give up'. |
fea5e716 MW |
413 | Relevant only locally, other end need not agree on it. |
414 | .TP | |
415 | .B keylife | |
416 | how long a particular instance of a connection | |
417 | (a set of encryption/authentication keys for user packets) should last, | |
418 | from successful negotiation to expiry; | |
419 | acceptable values are an integer optionally followed by | |
420 | .BR s | |
421 | (a time in seconds) | |
422 | or a decimal number followed by | |
423 | .BR m , | |
424 | .BR h , | |
425 | or | |
426 | .B d | |
427 | (a time | |
428 | in minutes, hours, or days respectively) | |
429 | (default | |
430 | .BR 1h , | |
431 | maximum | |
432 | .BR 24h ). | |
433 | Normally, the connection is renegotiated (via the keying channel) | |
434 | before it expires. | |
435 | The two ends need not exactly agree on | |
436 | .BR keylife , | |
437 | although if they do not, | |
438 | there will be some clutter of superseded connections on the end | |
439 | which thinks the lifetime is longer. | |
440 | .TP | |
c2bc2b27 AS |
441 | .B left |
442 | (required) | |
443 | the IP address of the left participant's public-network interface, | |
444 | in any form accepted by | |
445 | .IR ttoaddr (3) | |
446 | or one of several magic values. | |
447 | If it is | |
448 | .BR %defaultroute , | |
449 | .B left | |
450 | will be filled in automatically with the local address | |
451 | of the default-route interface (as determined at IPsec startup time). | |
452 | (Either | |
453 | .B left | |
454 | or | |
455 | .B right | |
456 | may be | |
457 | .BR %defaultroute , | |
458 | but not both.) | |
459 | The value | |
460 | .B %any | |
461 | signifies an address to be filled in (by automatic keying) during | |
462 | negotiation. The prefix | |
463 | .B % | |
464 | in front of a fully-qualified domain name or an IP address will implicitly set | |
465 | .B leftallowany=yes. | |
466 | If the domain name cannot be resolved into an IP address at IPsec startup or update time | |
467 | then | |
468 | .B left=%any | |
469 | and | |
470 | .B leftallowany=no | |
471 | will be assumed. | |
472 | .TP | |
473 | .B leftallowany | |
474 | a modifier for | |
475 | .B left | |
476 | , making it behave as | |
477 | .B %any | |
478 | although a concrete IP address has been assigned. | |
479 | Recommended for dynamic IP addresses that can be resolved by DynDNS at IPsec startup or | |
480 | update time. | |
481 | Acceptable values are | |
482 | .B yes | |
483 | and | |
484 | .B no | |
485 | (the default). | |
486 | .TP | |
fea5e716 MW |
487 | .B leftca |
488 | the distinguished name of a certificate authority which is required to | |
489 | lie in the trust path going from the left participant's certificate up | |
490 | to the root certification authority. | |
491 | .TP | |
492 | .B leftcert | |
493 | the path to the left participant's X.509 certificate. The file can be coded either in | |
494 | PEM or DER format. OpenPGP certificates are supported as well. | |
7900ab1b | 495 | Both absolute paths or paths relative to \fI/etc/ipsec.d/certs\fP |
fea5e716 MW |
496 | are accepted. By default |
497 | .B leftcert | |
498 | sets | |
499 | .B leftid | |
500 | to the distinguished name of the certificate's subject and | |
501 | .B leftca | |
502 | to the distinguished name of the certificate's issuer. | |
503 | The left participant's ID can be overriden by specifying a | |
504 | .B leftid | |
505 | value which must be certified by the certificate, though. | |
506 | .TP | |
c2bc2b27 AS |
507 | .B leftfirewall |
508 | whether the left participant is doing forwarding-firewalling | |
509 | (including masquerading) using iptables for traffic from \fIleftsubnet\fR, | |
510 | which should be turned off (for traffic to the other subnet) | |
511 | once the connection is established; | |
512 | acceptable values are | |
513 | .B yes | |
514 | and | |
515 | .B no | |
516 | (the default). | |
517 | May not be used in the same connection description with | |
518 | .BR leftupdown . | |
519 | Implemented as a parameter to the default \fBipsec _updown\fR script. | |
520 | See notes below. | |
521 | Relevant only locally, other end need not agree on it. | |
522 | ||
523 | If one or both security gateways are doing forwarding firewalling | |
524 | (possibly including masquerading), | |
525 | and this is specified using the firewall parameters, | |
526 | tunnels established with IPsec are exempted from it | |
527 | so that packets can flow unchanged through the tunnels. | |
528 | (This means that all subnets connected in this manner must have | |
529 | distinct, non-overlapping subnet address blocks.) | |
530 | This is done by the default \fBipsec _updown\fR script (see | |
531 | .IR pluto (8)). | |
532 | ||
533 | In situations calling for more control, | |
534 | it may be preferable for the user to supply his own | |
535 | .I updown | |
536 | script, | |
537 | which makes the appropriate adjustments for his system. | |
538 | .TP | |
539 | .B leftgroups | |
540 | a comma separated list of group names. If the | |
541 | .B leftgroups | |
542 | parameter is present then the peer must be a member of at least one | |
543 | of the groups defined by the parameter. Group membership must be certified | |
544 | by a valid attribute certificate stored in \fI/etc/ipsec.d/acerts/\fP thas has been | |
545 | issued to the peer by a trusted Authorization Authority stored in | |
546 | \fI/etc/ipsec.d/aacerts/\fP. Attribute certificates are not supported in IKEv2 yet. | |
547 | .TP | |
548 | .B lefthostaccess | |
549 | inserts a pair of INPUT and OUTPUT iptables rules using the default | |
550 | \fBipsec _updown\fR script, thus allowing access to the host itself | |
551 | in the case where the host's internal interface is part of the | |
552 | negotiated client subnet. | |
553 | Acceptable values are | |
554 | .B yes | |
555 | and | |
556 | .B no | |
557 | (the default). | |
558 | .TP | |
559 | .B leftid | |
560 | how | |
561 | the left participant | |
562 | should be identified for authentication; | |
563 | defaults to | |
564 | .BR left . | |
565 | Can be an IP address (in any | |
566 | .IR ttoaddr (3) | |
567 | syntax) | |
568 | or a fully-qualified domain name preceded by | |
569 | .B @ | |
570 | (which is used as a literal string and not resolved). | |
571 | .TP | |
572 | .B leftnexthop | |
573 | this parameter is not needed any more because the NETKEY IPsec stack does | |
574 | not require explicit routing entries for the traffic to be tunneled. | |
575 | .TP | |
576 | .B leftprotoport | |
577 | restrict the traffic selector to a single protocol and/or port. | |
578 | Examples: | |
579 | .B leftprotoport=tcp/http | |
7900ab1b | 580 | or |
c2bc2b27 | 581 | .B leftprotoport=6/80 |
7900ab1b | 582 | or |
c2bc2b27 | 583 | .B leftprotoport=udp |
7900ab1b AS |
584 | .TP |
585 | .B leftrsasigkey | |
586 | the left participant's | |
587 | public key for RSA signature authentication, | |
588 | in RFC 2537 format using | |
589 | .IR ttodata (3) | |
590 | encoding. | |
591 | The magic value | |
592 | .B %none | |
593 | means the same as not specifying a value (useful to override a default). | |
594 | The value | |
595 | .B %cert | |
596 | (the default) | |
597 | means that the key is extracted from a certificate. | |
598 | The identity used for the left participant | |
599 | must be a specific host, not | |
600 | .B %any | |
601 | or another magic value. | |
602 | .B Caution: | |
603 | if two connection descriptions | |
604 | specify different public keys for the same | |
605 | .BR leftid , | |
606 | confusion and madness will ensue. | |
607 | .TP | |
c2bc2b27 AS |
608 | .B leftsendcert |
609 | Accepted values are | |
610 | .B never | |
611 | or | |
612 | .BR no , | |
613 | .B always | |
614 | or | |
615 | .BR yes , | |
616 | and | |
617 | .BR ifasked . | |
fea5e716 | 618 | .TP |
fea5e716 | 619 | .B leftsourceip |
9b45443d MW |
620 | The internal source IP to use in a tunnel, also known as virtual IP. If the |
621 | value is | |
7900ab1b AS |
622 | .BR %modeconfig , |
623 | .BR %modecfg , | |
624 | .BR %config , | |
9b45443d | 625 | or |
7900ab1b | 626 | .B %cfg, |
8e79d8d3 MW |
627 | an address is requested from the peer. In IKEv2, a defined address is requested, |
628 | but the server may change it. If the server does not support it, the address | |
629 | is enforced. | |
630 | .TP | |
532137e7 | 631 | .B rightsourceip |
8e79d8d3 MW |
632 | The internal source IP to use in a tunnel for the remote peer. If the |
633 | value is | |
634 | .B %config | |
635 | on the responder side, the initiator must propose a address which is then echoed | |
636 | back. | |
fea5e716 | 637 | .TP |
c2bc2b27 AS |
638 | .B leftsubnet |
639 | private subnet behind the left participant, expressed as | |
640 | \fInetwork\fB/\fInetmask\fR | |
641 | (actually, any form acceptable to | |
642 | .IR ttosubnet (3)); | |
643 | if omitted, essentially assumed to be \fIleft\fB/32\fR, | |
644 | signifying that the left end of the connection goes to the left participant | |
645 | only. When using IKEv2, the configured subnet of the peers may differ, the | |
646 | protocol narrows it to the greates common subnet. | |
647 | .TP | |
648 | .B leftsubnetwithin | |
649 | the peer can propose any subnet or single IP address that fits within the | |
650 | range defined by | |
651 | .BR leftsubnetwithin. | |
652 | Not relevant for IKEv2, as subnets are narrowed. | |
653 | .TP | |
654 | .B leftupdown | |
655 | what ``updown'' script to run to adjust routing and/or firewalling | |
656 | when the status of the connection | |
657 | changes (default | |
658 | .BR "ipsec _updown" ). | |
659 | May include positional parameters separated by white space | |
660 | (although this requires enclosing the whole string in quotes); | |
661 | including shell metacharacters is unwise. | |
662 | See | |
663 | .IR pluto (8) | |
664 | for details. | |
665 | Relevant only locally, other end need not agree on it. IKEv2 uses the updown | |
666 | script to insert firewall rules only. Routing is not support and will be | |
667 | implemented directly into Charon. | |
668 | .TP | |
8c4339bd AS |
669 | .B mobike |
670 | enables the IKEv2 MOBIKE protocol defined by RFC 4555. Accepted values are | |
671 | .B yes | |
672 | (the default) and | |
673 | .BR no . | |
674 | If set to | |
675 | .BR no , | |
676 | the IKEv2 charon daemon will not actively propose MOBIKE but will still | |
677 | accept and support the protocol as a responder. | |
678 | .TP | |
7900ab1b AS |
679 | .B modeconfig |
680 | defines which mode is used to assign a virtual IP. | |
681 | Accepted values are | |
682 | .B push | |
683 | and | |
684 | .B pull | |
685 | (the default). | |
686 | Currently relevant for IKEv1 only since IKEv2 always uses the configuration | |
687 | payload in pull mode. | |
688 | .TP | |
fea5e716 MW |
689 | .B pfs |
690 | whether Perfect Forward Secrecy of keys is desired on the connection's | |
691 | keying channel | |
692 | (with PFS, penetration of the key-exchange protocol | |
693 | does not compromise keys negotiated earlier); | |
694 | acceptable values are | |
695 | .B yes | |
696 | (the default) | |
697 | and | |
7900ab1b AS |
698 | .BR no. |
699 | IKEv2 always uses PFS for IKE_SA rekeying whereas for CHILD_SA rekeying | |
700 | PFS is enforced by defining a Diffie-Hellman modp group in the | |
701 | .B esp | |
702 | parameter. | |
fea5e716 | 703 | .TP |
c2bc2b27 AS |
704 | .B reauth |
705 | whether rekeying of an IKE_SA should also reauthenticate the peer. In IKEv1, | |
706 | reauthentication is always done. In IKEv2, a value of | |
707 | .B no | |
708 | rekeys without uninstalling the IPsec SAs, a value of | |
709 | .B yes | |
710 | (the default) creates a new IKE_SA from scratch and tries to recreate | |
711 | all IPsec SAs. | |
712 | .TP | |
fea5e716 MW |
713 | .B rekey |
714 | whether a connection should be renegotiated when it is about to expire; | |
715 | acceptable values are | |
716 | .B yes | |
717 | (the default) | |
718 | and | |
719 | .BR no . | |
7900ab1b | 720 | The two ends need not agree, but while a value of |
fea5e716 | 721 | .B no |
6fe03b0a | 722 | prevents Pluto/Charon from requesting renegotiation, |
fea5e716 MW |
723 | it does not prevent responding to renegotiation requested from the other end, |
724 | so | |
725 | .B no | |
726 | will be largely ineffective unless both ends agree on it. | |
727 | .TP | |
728 | .B rekeyfuzz | |
729 | maximum percentage by which | |
730 | .B rekeymargin | |
731 | should be randomly increased to randomize rekeying intervals | |
732 | (important for hosts with many connections); | |
733 | acceptable values are an integer, | |
734 | which may exceed 100, | |
735 | followed by a `%' | |
736 | (default set by | |
7900ab1b | 737 | .IR pluto (8), |
fea5e716 MW |
738 | currently |
739 | .BR 100% ). | |
740 | The value of | |
741 | .BR rekeymargin , | |
742 | after this random increase, | |
743 | must not exceed | |
744 | .BR keylife . | |
745 | The value | |
746 | .B 0% | |
747 | will suppress time randomization. | |
748 | Relevant only locally, other end need not agree on it. | |
749 | .TP | |
750 | .B rekeymargin | |
751 | how long before connection expiry or keying-channel expiry | |
752 | should attempts to | |
753 | negotiate a replacement | |
754 | begin; acceptable values as for | |
755 | .B keylife | |
756 | (default | |
757 | .BR 9m ). | |
758 | Relevant only locally, other end need not agree on it. | |
532f2347 | 759 | .TP |
c2bc2b27 AS |
760 | .B type |
761 | the type of the connection; currently the accepted values | |
762 | are | |
763 | .B tunnel | |
764 | (the default) | |
765 | signifying a host-to-host, host-to-subnet, or subnet-to-subnet tunnel; | |
766 | .BR transport , | |
767 | signifying host-to-host transport mode; | |
768 | .BR passthrough , | |
769 | signifying that no IPsec processing should be done at all; | |
770 | .BR drop , | |
771 | signifying that packets should be discarded; and | |
772 | .BR reject , | |
773 | signifying that packets should be discarded and a diagnostic ICMP returned. | |
774 | Charon currently supports only | |
775 | .BR tunnel | |
776 | and | |
777 | .BR transport | |
778 | connection types. | |
fea5e716 | 779 | .TP |
c2bc2b27 AS |
780 | .B xauth |
781 | specifies the role in the XAUTH protocol if activated by | |
782 | .B authby=xauthpsk | |
783 | or | |
784 | .B authby=xauthrsasig. | |
785 | Accepted values are | |
786 | .B server | |
787 | and | |
788 | .B client | |
789 | (the default). | |
d5cc1758 TB |
790 | |
791 | .SS "CONN PARAMETERS: PEER-TO-PEER" | |
792 | The following parameters are relevant to Peer-to-Peer NAT-T operation | |
793 | only. | |
794 | .TP 14 | |
795 | .B p2p_mediation | |
796 | whether this connection is a P2P mediation connection, ie. whether this | |
797 | connection is used to mediate other connections. Mediation connections | |
798 | create no child SA. Acceptable values are | |
799 | .B no | |
800 | (the default) and | |
801 | .BR yes . | |
802 | .TP | |
803 | .B p2p_mediated_by | |
804 | the name of the connection to mediate this connection through. If given, | |
805 | the connection will be mediated through the named mediation connection. | |
806 | The mediation connection must set | |
807 | .BR p2p_mediation=yes . | |
808 | .TP | |
809 | .B p2p_peerid | |
810 | ID as which the peer is known to the mediation server, ie. which the other | |
811 | end of this connection uses as its | |
812 | .B leftid | |
813 | on its connection to the mediation server. This is the ID we request the | |
814 | mediation server to mediate us with. If | |
815 | .B p2p_peerid | |
816 | is not given, the | |
817 | .B rightid | |
818 | of this connection will be used as peer ID. | |
819 | ||
fea5e716 MW |
820 | .SH "CA SECTIONS" |
821 | This are optional sections that can be used to assign special | |
532f2347 MW |
822 | parameters to a Certification Authority (CA). These parameters are not |
823 | supported in IKEv2 yet. | |
fea5e716 MW |
824 | .TP 10 |
825 | .B auto | |
826 | currently can have either the value | |
827 | .B ignore | |
828 | or | |
829 | .B add | |
830 | . | |
831 | .TP | |
832 | .B cacert | |
833 | defines a path to the CA certificate either relative to | |
834 | \fI/etc/ipsec.d/cacerts\fP or as an absolute path. | |
835 | .TP | |
836 | .B crluri | |
837 | defines a CRL distribution point (ldap, http, or file URI) | |
838 | .TP | |
7900ab1b AS |
839 | .B crluri1 |
840 | synonym for | |
841 | .B crluri. | |
842 | .TP | |
fea5e716 MW |
843 | .B crluri2 |
844 | defines an alternative CRL distribution point (ldap, http, or file URI) | |
845 | .TP | |
846 | .B ldaphost | |
7900ab1b | 847 | defines an ldap host. Currently used by IKEv1 only. |
fea5e716 MW |
848 | .TP |
849 | .B ocspuri | |
850 | defines an OCSP URI. | |
7900ab1b AS |
851 | .TP |
852 | .B ocspuri1 | |
853 | synonym for | |
854 | .B ocspuri. | |
855 | .TP | |
856 | .B ocspuri2 | |
857 | defines an alternative OCSP URI. Currently used by IKEv2 only. | |
fea5e716 MW |
858 | .SH "CONFIG SECTIONS" |
859 | At present, the only | |
860 | .B config | |
861 | section known to the IPsec software is the one named | |
862 | .BR setup , | |
863 | which contains information used when the software is being started | |
864 | (see | |
7900ab1b | 865 | .IR starter (8)). |
fea5e716 MW |
866 | Here's an example: |
867 | .PP | |
868 | .ne 8 | |
869 | .nf | |
870 | .ft B | |
871 | .ta 1c | |
872 | config setup | |
fea5e716 | 873 | plutodebug=all |
7900ab1b AS |
874 | crlcheckinterval=10m |
875 | strictcrlpolicy=yes | |
fea5e716 MW |
876 | .ft |
877 | .fi | |
878 | .PP | |
879 | Parameters are optional unless marked ``(required)''. | |
880 | The currently-accepted | |
881 | .I parameter | |
882 | names in a | |
883 | .B config | |
884 | .B setup | |
885 | section are: | |
886 | .TP 14 | |
e0e7ef07 AS |
887 | .B cachecrls |
888 | certificate revocation lists (CRLs) fetched via http or ldap will be cached in | |
889 | \fI/etc/ipsec.d/crls/\fR under a unique file name derived from the certification | |
890 | authority's public key. | |
891 | Accepted values are | |
892 | .B yes | |
893 | and | |
894 | .B no | |
895 | (the default). | |
7900ab1b AS |
896 | .TP |
897 | .B charonstart | |
e0e7ef07 | 898 | whether to start the IKEv2 Charon daemon or not. |
7900ab1b | 899 | Accepted values are |
fea5e716 | 900 | .B yes |
7900ab1b AS |
901 | (the default) |
902 | or | |
903 | .BR no . | |
904 | .TP | |
e0e7ef07 AS |
905 | .B crlcheckinterval |
906 | interval in seconds. CRL fetching is enabled if the value is greater than zero. | |
907 | Asynchronous, periodic checking for fresh CRLs is currently done by the | |
908 | IKEv1 Pluto daemon only. | |
909 | .TP | |
910 | .B dumpdir | |
911 | in what directory should things started by \fBipsec starter\fR | |
912 | (notably the Pluto and Charon daemons) be allowed to dump core? | |
913 | The empty value (the default) means they are not | |
914 | allowed to. | |
915 | This feature is currently not yet supported by \fBipsec starter\fR. | |
7900ab1b AS |
916 | .TP |
917 | .B plutostart | |
e0e7ef07 | 918 | whether to start the IKEv1 Pluto daemon or not. |
7900ab1b AS |
919 | Accepted values are |
920 | .B yes | |
921 | (the default) | |
922 | or | |
fea5e716 | 923 | .BR no . |
fea5e716 | 924 | .TP |
e0e7ef07 AS |
925 | .B strictcrlpolicy |
926 | defines if a fresh CRL must be available in order for the peer authentication based | |
927 | on RSA signatures to succeed. | |
928 | Accepted values are | |
929 | .B yes | |
930 | and | |
931 | .B no | |
932 | (the default). | |
933 | IKEv2 additionally recognizes | |
934 | .B ifuri | |
935 | which reverts to | |
936 | .B yes | |
937 | if at least one CRL URI is defined and to | |
938 | .B no | |
939 | if no URI is known. | |
940 | .PP | |
941 | The following | |
942 | .B config section | |
943 | parameters are used by the IKEv1 Pluto daemon only: | |
944 | .TP | |
945 | .B keep_alive | |
946 | interval in seconds between NAT keep alive packets, the default being 20 seconds. | |
947 | .TP | |
948 | .B nat_traversal | |
949 | activates NAT traversal by accepting source ISAKMP ports different from udp/500 and | |
950 | being able of floating to udp/4500 if a NAT situation is detected. | |
951 | Accepted values are | |
952 | .B yes | |
953 | and | |
954 | .B no | |
955 | (the default). | |
8c4339bd | 956 | .TP |
e0e7ef07 AS |
957 | .B nocrsend |
958 | no certificate request payloads will be sent. | |
959 | Accepted values are | |
960 | .B yes | |
961 | and | |
962 | .B no | |
963 | (the default). | |
964 | Used by IKEv1 only, NAT traversal always being active in IKEv2. | |
965 | .TP | |
dd0ee786 AS |
966 | .B pkcs11initargs |
967 | non-standard argument string for PKCS#11 C_Initialize() function; | |
968 | required by NSS softoken. | |
969 | .TP | |
e0e7ef07 AS |
970 | .B pkcs11module |
971 | defines the path to a dynamically loadable PKCS #11 library. | |
972 | .TP | |
973 | .B pkcs11keepstate | |
974 | PKCS #11 login sessions will be kept during the whole lifetime of the keying | |
975 | daemon. Useful with pin-pad smart card readers. | |
976 | Accepted values are | |
977 | .B yes | |
978 | and | |
979 | .B no | |
980 | (the default). | |
981 | .TP | |
982 | .B pkcs11proxy | |
983 | Pluto will act as a PKCS #11 proxy accessible via the whack interface. | |
984 | Accepted values are | |
985 | .B yes | |
986 | and | |
987 | .B no | |
988 | (the default). | |
989 | .TP | |
fea5e716 MW |
990 | .B plutodebug |
991 | how much Pluto debugging output should be logged. | |
992 | An empty value, | |
993 | or the magic value | |
994 | .BR none , | |
995 | means no debugging output (the default). | |
996 | The magic value | |
997 | .B all | |
998 | means full output. | |
999 | Otherwise only the specified types of output | |
1000 | (a quoted list, names without the | |
1001 | .B \-\-debug\- | |
1002 | prefix, | |
1003 | separated by white space) are enabled; | |
1004 | for details on available debugging types, see | |
7900ab1b | 1005 | .IR pluto (8). |
fea5e716 | 1006 | .TP |
e0e7ef07 AS |
1007 | .B postpluto |
1008 | shell command to run after starting Pluto | |
1009 | (e.g., to remove a decrypted copy of the | |
fea5e716 MW |
1010 | .I ipsec.secrets |
1011 | file). | |
1012 | It's run in a very simple way; | |
1013 | complexities like I/O redirection are best hidden within a script. | |
1014 | Any output is redirected for logging, | |
1015 | so running interactive commands is difficult unless they use | |
1016 | .I /dev/tty | |
1017 | or equivalent for their interaction. | |
1018 | Default is none. | |
1019 | .TP | |
e0e7ef07 AS |
1020 | .B prepluto |
1021 | shell command to run before starting Pluto | |
1022 | (e.g., to decrypt an encrypted copy of the | |
fea5e716 MW |
1023 | .I ipsec.secrets |
1024 | file). | |
1025 | It's run in a very simple way; | |
1026 | complexities like I/O redirection are best hidden within a script. | |
1027 | Any output is redirected for logging, | |
1028 | so running interactive commands is difficult unless they use | |
1029 | .I /dev/tty | |
1030 | or equivalent for their interaction. | |
1031 | Default is none. | |
1032 | .TP | |
e0e7ef07 AS |
1033 | .B virtual_private |
1034 | defines private networks using a wildcard notation. | |
fea5e716 MW |
1035 | .TP |
1036 | .B uniqueids | |
1037 | whether a particular participant ID should be kept unique, | |
1038 | with any new (automatically keyed) | |
1039 | connection using an ID from a different IP address | |
1040 | deemed to replace all old ones using that ID; | |
1041 | acceptable values are | |
1042 | .B yes | |
1043 | (the default) | |
1044 | and | |
1045 | .BR no . | |
1046 | Participant IDs normally \fIare\fR unique, | |
1047 | so a new (automatically-keyed) connection using the same ID is | |
1048 | almost invariably intended to replace an old one. | |
e0e7ef07 AS |
1049 | .PP |
1050 | The following | |
1051 | .B config section | |
1052 | parameters are used by the IKEv2 Charon daemon only: | |
fea5e716 | 1053 | .TP |
e0e7ef07 AS |
1054 | .B charondebug |
1055 | how much Charon debugging output should be logged. | |
1056 | A comma separated list containing type level/pairs may | |
1057 | be specified, e.g: | |
1058 | .B dmn 3, ike 1, net -1. | |
1059 | Acceptable values for types are | |
1060 | .B dmn, mgr, ike, chd, job, cfg, knl, net, enc, lib | |
1061 | and the level is one of | |
1062 | .B -1, 0, 1, 2, 3, 4 | |
1063 | (for silent, audit, control, controlmore, raw, private). | |
1064 | .PP | |
1065 | The following | |
1066 | .B config section | |
1067 | parameters only make sense if the KLIPS IPsec stack | |
1068 | is used instead of the default NETKEY stack of the Linux 2.6 kernel: | |
fea5e716 | 1069 | .TP |
e0e7ef07 AS |
1070 | .B fragicmp |
1071 | whether a tunnel's need to fragment a packet should be reported | |
1072 | back with an ICMP message, | |
1073 | in an attempt to make the sender lower his PMTU estimate; | |
1074 | acceptable values are | |
7900ab1b | 1075 | .B yes |
e0e7ef07 | 1076 | (the default) |
7900ab1b | 1077 | and |
e0e7ef07 | 1078 | .BR no . |
7900ab1b | 1079 | .TP |
e0e7ef07 AS |
1080 | .B hidetos |
1081 | whether a tunnel packet's TOS field should be set to | |
1082 | .B 0 | |
1083 | rather than copied from the user packet inside; | |
1084 | acceptable values are | |
7900ab1b | 1085 | .B yes |
e0e7ef07 | 1086 | (the default) |
7900ab1b | 1087 | and |
e0e7ef07 | 1088 | .BR no |
fea5e716 | 1089 | .TP |
e0e7ef07 AS |
1090 | .B interfaces |
1091 | virtual and physical interfaces for IPsec to use: | |
1092 | a single | |
1093 | \fIvirtual\fB=\fIphysical\fR pair, a (quoted!) list of pairs separated | |
1094 | by white space, or | |
1095 | .BR %none . | |
1096 | One of the pairs may be written as | |
1097 | .BR %defaultroute , | |
1098 | which means: find the interface \fId\fR that the default route points to, | |
1099 | and then act as if the value was ``\fBipsec0=\fId\fR''. | |
1100 | .B %defaultroute | |
1101 | is the default; | |
1102 | .B %none | |
1103 | must be used to denote no interfaces. | |
7900ab1b | 1104 | .TP |
e0e7ef07 AS |
1105 | .B overridemtu |
1106 | value that the MTU of the ipsec\fIn\fR interface(s) should be set to, | |
1107 | overriding IPsec's (large) default. | |
fea5e716 MW |
1108 | .SH CHOOSING A CONNECTION |
1109 | .PP | |
1110 | When choosing a connection to apply to an outbound packet caught with a | |
1111 | .BR %trap, | |
1112 | the system prefers the one with the most specific eroute that | |
1113 | includes the packet's source and destination IP addresses. | |
1114 | Source subnets are examined before destination subnets. | |
1115 | For initiating, only routed connections are considered. For responding, | |
1116 | unrouted but added connections are considered. | |
1117 | .PP | |
1118 | When choosing a connection to use to respond to a negotiation which | |
1119 | doesn't match an ordinary conn, an opportunistic connection | |
1120 | may be instantiated. Eventually, its instance will be /32 -> /32, but | |
1121 | for earlier stages of the negotiation, there will not be enough | |
1122 | information about the client subnets to complete the instantiation. | |
1123 | .SH FILES | |
1124 | .nf | |
1125 | /etc/ipsec.conf | |
7900ab1b AS |
1126 | /etc/ipsec.d/aacerts |
1127 | /etc/ipsec.d/acerts | |
fea5e716 MW |
1128 | /etc/ipsec.d/cacerts |
1129 | /etc/ipsec.d/certs | |
1130 | /etc/ipsec.d/crls | |
fea5e716 MW |
1131 | |
1132 | .SH SEE ALSO | |
7900ab1b | 1133 | ipsec(8), pluto(8), starter(8), ttoaddr(3), ttodata(3) |
fea5e716 | 1134 | .SH HISTORY |
e0e7ef07 AS |
1135 | Written for the FreeS/WAN project by Henry Spencer. |
1136 | Extended for the strongSwan project | |
fea5e716 | 1137 | <http://www.strongswan.org> |
7900ab1b | 1138 | by Andreas Steffen. IKEv2-specific features by Martin Willi. |
fea5e716 MW |
1139 | .SH BUGS |
1140 | .PP | |
7900ab1b | 1141 | If conns are to be added before DNS is available, \fBleft=\fP\fIFQDN\fP |
fea5e716 | 1142 | will fail. |