]>
Commit | Line | Data |
---|---|---|
7900ab1b | 1 | .TH IPSEC.CONF 5 "27 Jun 2007" |
fea5e716 MW |
2 | .\" RCSID $Id: ipsec.conf.5,v 1.2 2006/01/22 15:33:46 as Exp $ |
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 | |
222 | .B type | |
223 | the type of the connection; currently the accepted values | |
224 | are | |
225 | .B tunnel | |
226 | (the default) | |
227 | signifying a host-to-host, host-to-subnet, or subnet-to-subnet tunnel; | |
228 | .BR transport , | |
229 | signifying host-to-host transport mode; | |
230 | .BR passthrough , | |
231 | signifying that no IPsec processing should be done at all; | |
232 | .BR drop , | |
233 | signifying that packets should be discarded; and | |
234 | .BR reject , | |
235 | signifying that packets should be discarded and a diagnostic ICMP returned. | |
7652be89 | 236 | Charon currently supports only |
532f2347 | 237 | .BR tunnel |
7652be89 MW |
238 | and |
239 | .BR transport | |
240 | connection types. | |
fea5e716 MW |
241 | .TP |
242 | .B left | |
243 | (required) | |
244 | the IP address of the left participant's public-network interface, | |
245 | in any form accepted by | |
7900ab1b | 246 | .IR ttoaddr (3) |
fea5e716 MW |
247 | or one of several magic values. |
248 | If it is | |
249 | .BR %defaultroute , | |
fea5e716 MW |
250 | .B left |
251 | will be filled in automatically with the local address | |
7900ab1b | 252 | of the default-route interface (as determined at IPsec startup time). |
fea5e716 MW |
253 | (Either |
254 | .B left | |
255 | or | |
256 | .B right | |
257 | may be | |
258 | .BR %defaultroute , | |
259 | but not both.) | |
260 | The value | |
261 | .B %any | |
262 | signifies an address to be filled in (by automatic keying) during | |
7900ab1b AS |
263 | negotiation. The prefix |
264 | .B % | |
265 | in front of a fully-qualified domain name or an IP address will implicitly set | |
266 | .B leftallowany=yes. | |
267 | If the domain name cannot be resolved into an IP address at IPsec startup or update time | |
268 | then | |
269 | .B left=%any | |
270 | and | |
271 | .B leftallowany=no | |
272 | will be assumed. | |
273 | .TP | |
274 | .B leftallowany | |
275 | a modifier for | |
276 | .B left | |
277 | , making it behave as | |
278 | .B %any | |
279 | although a concrete IP address has been assigned. | |
280 | Recommended for dynamic IP addresses that can be resolved by DynDNS at IPsec startup or | |
281 | update time. | |
282 | Acceptable values are | |
283 | .B yes | |
284 | and | |
285 | .B no | |
286 | (the default). | |
fea5e716 MW |
287 | .TP |
288 | .B leftsubnet | |
289 | private subnet behind the left participant, expressed as | |
290 | \fInetwork\fB/\fInetmask\fR | |
291 | (actually, any form acceptable to | |
7900ab1b | 292 | .IR ttosubnet (3)); |
fea5e716 | 293 | if omitted, essentially assumed to be \fIleft\fB/32\fR, |
532f2347 MW |
294 | signifying that the left end of the connection goes to the left participant |
295 | only. When using IKEv2, the configured subnet of the peers may differ, the | |
296 | protocol narrows it to the greates common subnet. | |
fea5e716 | 297 | .TP |
487fe29e AS |
298 | .B leftsubnetwithin |
299 | the peer can propose any subnet or single IP address that fits within the | |
300 | range defined by | |
301 | .BR leftsubnetwithin. | |
302 | Not relevant for IKEv2, as subnets are narrowed. | |
303 | .TP | |
304 | .B leftprotoport | |
305 | restrict the traffic selector to a single protocol and/or port. | |
306 | Examples: | |
307 | .B leftprotoport=tcp/http | |
308 | or | |
309 | .B leftprotoport=6/80 | |
310 | or | |
311 | .B leftprotoport=udp | |
312 | .TP | |
fea5e716 | 313 | .B leftnexthop |
7900ab1b AS |
314 | this parameter is not needed any more because the NETKEY IPsec stack does |
315 | not require explicit routing entries for the traffic to be tunneled. | |
fea5e716 | 316 | .TP |
fea5e716 MW |
317 | .B leftfirewall |
318 | whether the left participant is doing forwarding-firewalling | |
7900ab1b | 319 | (including masquerading) using iptables for traffic from \fIleftsubnet\fR, |
fea5e716 MW |
320 | which should be turned off (for traffic to the other subnet) |
321 | once the connection is established; | |
322 | acceptable values are | |
323 | .B yes | |
7900ab1b AS |
324 | and |
325 | .B no | |
326 | (the default). | |
fea5e716 MW |
327 | May not be used in the same connection description with |
328 | .BR leftupdown . | |
487fe29e | 329 | Implemented as a parameter to the default \fBipsec _updown\fR script. |
fea5e716 MW |
330 | See notes below. |
331 | Relevant only locally, other end need not agree on it. | |
532f2347 | 332 | |
fea5e716 MW |
333 | If one or both security gateways are doing forwarding firewalling |
334 | (possibly including masquerading), | |
335 | and this is specified using the firewall parameters, | |
336 | tunnels established with IPsec are exempted from it | |
337 | so that packets can flow unchanged through the tunnels. | |
338 | (This means that all subnets connected in this manner must have | |
339 | distinct, non-overlapping subnet address blocks.) | |
487fe29e | 340 | This is done by the default \fBipsec _updown\fR script (see |
7900ab1b | 341 | .IR pluto (8)). |
532f2347 | 342 | |
fea5e716 MW |
343 | In situations calling for more control, |
344 | it may be preferable for the user to supply his own | |
345 | .I updown | |
346 | script, | |
347 | which makes the appropriate adjustments for his system. | |
532f2347 | 348 | .TP |
487fe29e AS |
349 | .B lefthostaccess |
350 | inserts a pair of INPUT and OUTPUT iptables rules using the default | |
351 | \fBipsec _updown\fR script, thus allowing access to the host itself | |
352 | in the case where the host's internal interface is part of the | |
353 | negotiated client subnet. | |
354 | Acceptable values are | |
355 | .B yes | |
356 | and | |
357 | .B no | |
358 | (the default). | |
359 | .TP | |
360 | .B leftupdown | |
361 | what ``updown'' script to run to adjust routing and/or firewalling | |
362 | when the status of the connection | |
363 | changes (default | |
364 | .BR "ipsec _updown" ). | |
365 | May include positional parameters separated by white space | |
366 | (although this requires enclosing the whole string in quotes); | |
367 | including shell metacharacters is unwise. | |
368 | See | |
369 | .IR pluto (8) | |
370 | for details. | |
371 | Relevant only locally, other end need not agree on it. IKEv2 uses the updown | |
372 | script to insert firewall rules only. Routing is not support and will be | |
373 | implemented directly into Charon. | |
374 | .TP | |
fea5e716 MW |
375 | .B auto |
376 | what operation, if any, should be done automatically at IPsec startup; | |
377 | currently-accepted values are | |
378 | .B add | |
532f2347 | 379 | , |
fea5e716 | 380 | .B route |
532f2347 | 381 | , |
fea5e716 | 382 | .B start |
fea5e716 MW |
383 | and |
384 | .B ignore | |
532f2347 MW |
385 | . |
386 | .B add | |
387 | loads a connection without starting it. | |
388 | .B route | |
389 | loads a connection and installs kernel traps. If traffic is detected between | |
390 | .B leftsubnet | |
391 | and | |
392 | .B rightsubnet | |
393 | , a connection is established. | |
394 | .B start | |
395 | loads a connection and brings it up immediatly. | |
396 | .B ignore | |
397 | ignores the connection. This is equal to delete a connection from the config | |
398 | file. | |
fea5e716 MW |
399 | Relevant only locally, other end need not agree on it |
400 | (but in general, for an intended-to-be-permanent connection, | |
401 | both ends should use | |
402 | .B auto=start | |
403 | to ensure that any reboot causes immediate renegotiation). | |
404 | .TP | |
405 | .B auth | |
406 | whether authentication should be done as part of | |
407 | ESP encryption, or separately using the AH protocol; | |
408 | acceptable values are | |
409 | .B esp | |
410 | (the default) and | |
411 | .BR ah . | |
532f2347 | 412 | The IKEv2 daemon currently supports only ESP. |
fea5e716 MW |
413 | .TP |
414 | .B authby | |
415 | how the two security gateways should authenticate each other; | |
416 | acceptable values are | |
417 | .B secret | |
7900ab1b AS |
418 | or |
419 | .B psk | |
fea5e716 MW |
420 | for shared secrets, |
421 | .B rsasig | |
422 | for RSA digital signatures (the default), | |
423 | .B secret|rsasig | |
424 | for either, and | |
425 | .B never | |
426 | if negotiation is never to be attempted or accepted (useful for shunt-only conns). | |
532f2347 | 427 | Digital signatures are superior in every way to shared secrets. In IKEv2, the |
7900ab1b AS |
428 | two ends must not agree on this parameter, it is relevant for the |
429 | outbound authentication method only. | |
430 | IKEv1 additionally supports the values | |
431 | .B xauthpsk | |
432 | and | |
433 | .B xauthrsasig | |
434 | that will enable eXtended AUTHentication (XAUTH) in addition to IKEv1 main mode | |
435 | based on shared secrets or digital RSA signatures, respectively. | |
436 | IKEv2 additionally supports the value | |
9b45443d MW |
437 | .B eap, |
438 | which indicates an initiator to request EAP authentication. The EAP method to | |
439 | use is selected by the server (see | |
440 | .B eap). | |
fea5e716 | 441 | .TP |
7900ab1b AS |
442 | .B xauth |
443 | specifies the role in the XAUTH protocol if activated by | |
444 | .B authby=xauthpsk | |
445 | or | |
446 | .B authby=xauthrsasig. | |
447 | Accepted values are | |
448 | .B server | |
449 | and | |
450 | .B client | |
451 | (the default). | |
452 | .TP | |
fea5e716 MW |
453 | .B compress |
454 | whether IPComp compression of content is proposed on the connection | |
455 | (link-level compression does not work on encrypted data, | |
456 | so to be effective, compression must be done \fIbefore\fR encryption); | |
457 | acceptable values are | |
458 | .B yes | |
459 | and | |
460 | .B no | |
532f2347 | 461 | (the default). A value of |
fea5e716 MW |
462 | .B yes |
463 | causes IPsec to propose both compressed and uncompressed, | |
464 | and prefer compressed. | |
465 | A value of | |
466 | .B no | |
467 | prevents IPsec from proposing compression; | |
468 | a proposal to compress will still be accepted. | |
532f2347 | 469 | IKEv2 does not support IP compression yet. |
fea5e716 | 470 | .TP |
fea5e716 MW |
471 | .B dpdaction |
472 | controls the use of the Dead Peer Detection protocol (DPD, RFC 3706) where | |
a655f5c0 MW |
473 | R_U_THERE notification messages (IKEv1) or empty INFORMATIONAL messages (IKEv2) |
474 | are periodically sent in order to check the | |
475 | liveliness of the IPsec peer. The values | |
7900ab1b AS |
476 | .BR clear , |
477 | .BR hold , | |
478 | and | |
479 | .B restart | |
480 | all activate DPD. If no activity is detected, all connections with a dead peer | |
fea5e716 MW |
481 | are stopped and unrouted ( |
482 | .B clear | |
7900ab1b | 483 | ), put in the hold state ( |
fea5e716 | 484 | .B hold |
7900ab1b AS |
485 | ) or restarted ( |
486 | .B restart | |
487 | ). | |
488 | For IKEv1, the default is | |
a655f5c0 MW |
489 | .B none |
490 | which disables the active sending of R_U_THERE notifications. | |
491 | Nevertheless pluto will always send the DPD Vendor ID during connection set up | |
492 | in order to signal the readiness to act passively as a responder if the peer | |
7900ab1b AS |
493 | wants to use DPD. For IKEv2, |
494 | .B none | |
495 | does't make sense, since all messages are used to detect dead peers. If specified, | |
a655f5c0 MW |
496 | it has the same meaning as the default ( |
497 | .B clear | |
fea5e716 MW |
498 | ). |
499 | .TP | |
500 | .B dpddelay | |
a655f5c0 MW |
501 | defines the period time interval with which R_U_THERE messages/INFORMATIONAL |
502 | exchanges are sent to the peer. These are only sent if no other traffic is | |
503 | received. In IKEv2, a value of 0 sends no additional INFORMATIONAL | |
504 | messages and uses only standard messages (such as those to rekey) to detect | |
505 | dead peers. | |
fea5e716 MW |
506 | .TP |
507 | .B dpdtimeout | |
508 | defines the timeout interval, after which all connections to a peer are deleted | |
a655f5c0 MW |
509 | in case of inactivity. This only applies to IKEv1, in IKEv2 the default |
510 | retransmission timeout applies, as every exchange is used to detect dead peers. | |
fea5e716 | 511 | .TP |
fea5e716 | 512 | .B ikelifetime |
532f2347 | 513 | how long the keying channel of a connection ('ISAKMP/IKE SA') |
fea5e716 MW |
514 | should last before being renegotiated. |
515 | .TP | |
516 | .B keyexchange | |
517 | method of key exchange; | |
3572b3b6 | 518 | which protocol should be used to initialize the connection. Connections marked with |
fea5e716 | 519 | .B ikev1 |
3572b3b6 | 520 | are initiated with pluto, those marked with |
fea5e716 | 521 | .B ikev2 |
3572b3b6 MW |
522 | with charon. An incoming request from the remote peer is handled by the correct |
523 | daemon, unaffected from the | |
fea5e716 | 524 | .B keyexchange |
3572b3b6 | 525 | setting. The default value |
fea5e716 MW |
526 | .B ike |
527 | currently behaves exactly as | |
528 | .B ikev1. | |
529 | .TP | |
fea5e716 MW |
530 | .B keyingtries |
531 | how many attempts (a whole number or \fB%forever\fP) should be made to | |
532 | negotiate a connection, or a replacement for one, before giving up | |
533 | (default | |
534 | .BR %forever ). | |
535 | The value \fB%forever\fP | |
532f2347 | 536 | means 'never give up'. |
fea5e716 MW |
537 | Relevant only locally, other end need not agree on it. |
538 | .TP | |
539 | .B keylife | |
540 | how long a particular instance of a connection | |
541 | (a set of encryption/authentication keys for user packets) should last, | |
542 | from successful negotiation to expiry; | |
543 | acceptable values are an integer optionally followed by | |
544 | .BR s | |
545 | (a time in seconds) | |
546 | or a decimal number followed by | |
547 | .BR m , | |
548 | .BR h , | |
549 | or | |
550 | .B d | |
551 | (a time | |
552 | in minutes, hours, or days respectively) | |
553 | (default | |
554 | .BR 1h , | |
555 | maximum | |
556 | .BR 24h ). | |
557 | Normally, the connection is renegotiated (via the keying channel) | |
558 | before it expires. | |
559 | The two ends need not exactly agree on | |
560 | .BR keylife , | |
561 | although if they do not, | |
562 | there will be some clutter of superseded connections on the end | |
563 | which thinks the lifetime is longer. | |
564 | .TP | |
565 | .B leftca | |
566 | the distinguished name of a certificate authority which is required to | |
567 | lie in the trust path going from the left participant's certificate up | |
568 | to the root certification authority. | |
569 | .TP | |
570 | .B leftcert | |
571 | the path to the left participant's X.509 certificate. The file can be coded either in | |
572 | PEM or DER format. OpenPGP certificates are supported as well. | |
7900ab1b | 573 | Both absolute paths or paths relative to \fI/etc/ipsec.d/certs\fP |
fea5e716 MW |
574 | are accepted. By default |
575 | .B leftcert | |
576 | sets | |
577 | .B leftid | |
578 | to the distinguished name of the certificate's subject and | |
579 | .B leftca | |
580 | to the distinguished name of the certificate's issuer. | |
581 | The left participant's ID can be overriden by specifying a | |
582 | .B leftid | |
583 | value which must be certified by the certificate, though. | |
584 | .TP | |
7900ab1b AS |
585 | .B leftsendcert |
586 | Accepted values are | |
587 | .B never | |
588 | or | |
589 | .BR no , | |
590 | .B always | |
591 | or | |
592 | .BR yes , | |
593 | and | |
594 | .BR ifasked . | |
595 | .TP | |
596 | .B leftrsasigkey | |
597 | the left participant's | |
598 | public key for RSA signature authentication, | |
599 | in RFC 2537 format using | |
600 | .IR ttodata (3) | |
601 | encoding. | |
602 | The magic value | |
603 | .B %none | |
604 | means the same as not specifying a value (useful to override a default). | |
605 | The value | |
606 | .B %cert | |
607 | (the default) | |
608 | means that the key is extracted from a certificate. | |
609 | The identity used for the left participant | |
610 | must be a specific host, not | |
611 | .B %any | |
612 | or another magic value. | |
613 | .B Caution: | |
614 | if two connection descriptions | |
615 | specify different public keys for the same | |
616 | .BR leftid , | |
617 | confusion and madness will ensue. | |
618 | .TP | |
fea5e716 MW |
619 | .B leftgroups |
620 | a comma separated list of group names. If the | |
621 | .B leftgroups | |
622 | parameter is present then the peer must be a member of at least one | |
623 | of the groups defined by the parameter. Group membership must be certified | |
624 | by a valid attribute certificate stored in \fI/etc/ipsec.d/acerts\fP thas has been | |
625 | issued to the peer by a trusted Authorization Authority stored in | |
532f2347 | 626 | \fI/etc/ipsec.d/aacerts\fP. Attribute certificates are not supported in IKEv2 yet. |
fea5e716 MW |
627 | .TP |
628 | .B leftid | |
629 | how | |
630 | the left participant | |
631 | should be identified for authentication; | |
632 | defaults to | |
633 | .BR left . | |
634 | Can be an IP address (in any | |
7900ab1b | 635 | .IR ttoaddr (3) |
fea5e716 MW |
636 | syntax) |
637 | or a fully-qualified domain name preceded by | |
638 | .B @ | |
639 | (which is used as a literal string and not resolved). | |
fea5e716 | 640 | .TP |
fea5e716 | 641 | .B leftsourceip |
9b45443d MW |
642 | The internal source IP to use in a tunnel, also known as virtual IP. If the |
643 | value is | |
7900ab1b AS |
644 | .BR %modeconfig , |
645 | .BR %modecfg , | |
646 | .BR %config , | |
9b45443d | 647 | or |
7900ab1b | 648 | .B %cfg, |
8e79d8d3 MW |
649 | an address is requested from the peer. In IKEv2, a defined address is requested, |
650 | but the server may change it. If the server does not support it, the address | |
651 | is enforced. | |
652 | .TP | |
532137e7 | 653 | .B rightsourceip |
8e79d8d3 MW |
654 | The internal source IP to use in a tunnel for the remote peer. If the |
655 | value is | |
656 | .B %config | |
657 | on the responder side, the initiator must propose a address which is then echoed | |
658 | back. | |
fea5e716 | 659 | .TP |
7900ab1b AS |
660 | .B modeconfig |
661 | defines which mode is used to assign a virtual IP. | |
662 | Accepted values are | |
663 | .B push | |
664 | and | |
665 | .B pull | |
666 | (the default). | |
667 | Currently relevant for IKEv1 only since IKEv2 always uses the configuration | |
668 | payload in pull mode. | |
669 | .TP | |
fea5e716 MW |
670 | .B pfs |
671 | whether Perfect Forward Secrecy of keys is desired on the connection's | |
672 | keying channel | |
673 | (with PFS, penetration of the key-exchange protocol | |
674 | does not compromise keys negotiated earlier); | |
675 | acceptable values are | |
676 | .B yes | |
677 | (the default) | |
678 | and | |
7900ab1b AS |
679 | .BR no. |
680 | IKEv2 always uses PFS for IKE_SA rekeying whereas for CHILD_SA rekeying | |
681 | PFS is enforced by defining a Diffie-Hellman modp group in the | |
682 | .B esp | |
683 | parameter. | |
fea5e716 MW |
684 | .TP |
685 | .B rekey | |
686 | whether a connection should be renegotiated when it is about to expire; | |
687 | acceptable values are | |
688 | .B yes | |
689 | (the default) | |
690 | and | |
691 | .BR no . | |
7900ab1b | 692 | The two ends need not agree, but while a value of |
fea5e716 | 693 | .B no |
6fe03b0a | 694 | prevents Pluto/Charon from requesting renegotiation, |
fea5e716 MW |
695 | it does not prevent responding to renegotiation requested from the other end, |
696 | so | |
697 | .B no | |
698 | will be largely ineffective unless both ends agree on it. | |
699 | .TP | |
6fe03b0a MW |
700 | .B reauth |
701 | whether rekeying of an IKE_SA should also reauthenticate the peer. In IKEv1, | |
702 | reauthentication is always done. In IKEv2, a value of | |
703 | .B no | |
704 | rekeys without uninstalling the IPsec SAs, a value of | |
705 | .B yes | |
706 | (the default) creates a new IKE_SA from scratch and tries to recreate | |
707 | all IPsec SAs. | |
708 | .TP | |
fea5e716 MW |
709 | .B rekeyfuzz |
710 | maximum percentage by which | |
711 | .B rekeymargin | |
712 | should be randomly increased to randomize rekeying intervals | |
713 | (important for hosts with many connections); | |
714 | acceptable values are an integer, | |
715 | which may exceed 100, | |
716 | followed by a `%' | |
717 | (default set by | |
7900ab1b | 718 | .IR pluto (8), |
fea5e716 MW |
719 | currently |
720 | .BR 100% ). | |
721 | The value of | |
722 | .BR rekeymargin , | |
723 | after this random increase, | |
724 | must not exceed | |
725 | .BR keylife . | |
726 | The value | |
727 | .B 0% | |
728 | will suppress time randomization. | |
729 | Relevant only locally, other end need not agree on it. | |
730 | .TP | |
731 | .B rekeymargin | |
732 | how long before connection expiry or keying-channel expiry | |
733 | should attempts to | |
734 | negotiate a replacement | |
735 | begin; acceptable values as for | |
736 | .B keylife | |
737 | (default | |
738 | .BR 9m ). | |
739 | Relevant only locally, other end need not agree on it. | |
532f2347 MW |
740 | .TP |
741 | .B ike | |
742 | IKE/ISAKMP SA encryption/authentication algorithm to be used, e.g. | |
743 | .B aes128-sha1-modp2048 | |
b7ade11b MW |
744 | (encryption-integrity-dhgroup). In IKEv2, multiple algorithms and proposals |
745 | may be included, such as | |
746 | .B aes128-aes256-sha1-modp1536-modp2048,3des-sha1-md5-modp1024. | |
fea5e716 MW |
747 | .TP |
748 | .B esp | |
749 | ESP encryption/authentication algorithm to be used | |
750 | for the connection, e.g. | |
532f2347 | 751 | .B 3des-md5 |
b7ade11b MW |
752 | (encryption-integrity-[dh-group]). If dh-group is specified, CHILD_SA setup |
753 | and rekeying include a separate diffe hellman exchange (IKEv2 only). | |
fea5e716 MW |
754 | .TP |
755 | .B ah | |
756 | AH authentication algorithm to be used | |
757 | for the connection, e.g. | |
532f2347 | 758 | .B hmac-md5. |
fea5e716 MW |
759 | .SH "CA SECTIONS" |
760 | This are optional sections that can be used to assign special | |
532f2347 MW |
761 | parameters to a Certification Authority (CA). These parameters are not |
762 | supported in IKEv2 yet. | |
fea5e716 MW |
763 | .TP 10 |
764 | .B auto | |
765 | currently can have either the value | |
766 | .B ignore | |
767 | or | |
768 | .B add | |
769 | . | |
770 | .TP | |
771 | .B cacert | |
772 | defines a path to the CA certificate either relative to | |
773 | \fI/etc/ipsec.d/cacerts\fP or as an absolute path. | |
774 | .TP | |
775 | .B crluri | |
776 | defines a CRL distribution point (ldap, http, or file URI) | |
777 | .TP | |
7900ab1b AS |
778 | .B crluri1 |
779 | synonym for | |
780 | .B crluri. | |
781 | .TP | |
fea5e716 MW |
782 | .B crluri2 |
783 | defines an alternative CRL distribution point (ldap, http, or file URI) | |
784 | .TP | |
785 | .B ldaphost | |
7900ab1b | 786 | defines an ldap host. Currently used by IKEv1 only. |
fea5e716 MW |
787 | .TP |
788 | .B ocspuri | |
789 | defines an OCSP URI. | |
7900ab1b AS |
790 | .TP |
791 | .B ocspuri1 | |
792 | synonym for | |
793 | .B ocspuri. | |
794 | .TP | |
795 | .B ocspuri2 | |
796 | defines an alternative OCSP URI. Currently used by IKEv2 only. | |
fea5e716 MW |
797 | .SH "CONFIG SECTIONS" |
798 | At present, the only | |
799 | .B config | |
800 | section known to the IPsec software is the one named | |
801 | .BR setup , | |
802 | which contains information used when the software is being started | |
803 | (see | |
7900ab1b | 804 | .IR starter (8)). |
fea5e716 MW |
805 | Here's an example: |
806 | .PP | |
807 | .ne 8 | |
808 | .nf | |
809 | .ft B | |
810 | .ta 1c | |
811 | config setup | |
fea5e716 | 812 | plutodebug=all |
7900ab1b AS |
813 | crlcheckinterval=10m |
814 | strictcrlpolicy=yes | |
fea5e716 MW |
815 | .ft |
816 | .fi | |
817 | .PP | |
818 | Parameters are optional unless marked ``(required)''. | |
819 | The currently-accepted | |
820 | .I parameter | |
821 | names in a | |
822 | .B config | |
823 | .B setup | |
824 | section are: | |
825 | .TP 14 | |
e0e7ef07 AS |
826 | .B cachecrls |
827 | certificate revocation lists (CRLs) fetched via http or ldap will be cached in | |
828 | \fI/etc/ipsec.d/crls/\fR under a unique file name derived from the certification | |
829 | authority's public key. | |
830 | Accepted values are | |
831 | .B yes | |
832 | and | |
833 | .B no | |
834 | (the default). | |
7900ab1b AS |
835 | .TP |
836 | .B charonstart | |
e0e7ef07 | 837 | whether to start the IKEv2 Charon daemon or not. |
7900ab1b | 838 | Accepted values are |
fea5e716 | 839 | .B yes |
7900ab1b AS |
840 | (the default) |
841 | or | |
842 | .BR no . | |
843 | .TP | |
e0e7ef07 AS |
844 | .B crlcheckinterval |
845 | interval in seconds. CRL fetching is enabled if the value is greater than zero. | |
846 | Asynchronous, periodic checking for fresh CRLs is currently done by the | |
847 | IKEv1 Pluto daemon only. | |
848 | .TP | |
849 | .B dumpdir | |
850 | in what directory should things started by \fBipsec starter\fR | |
851 | (notably the Pluto and Charon daemons) be allowed to dump core? | |
852 | The empty value (the default) means they are not | |
853 | allowed to. | |
854 | This feature is currently not yet supported by \fBipsec starter\fR. | |
7900ab1b AS |
855 | .TP |
856 | .B plutostart | |
e0e7ef07 | 857 | whether to start the IKEv1 Pluto daemon or not. |
7900ab1b AS |
858 | Accepted values are |
859 | .B yes | |
860 | (the default) | |
861 | or | |
fea5e716 | 862 | .BR no . |
fea5e716 | 863 | .TP |
e0e7ef07 AS |
864 | .B strictcrlpolicy |
865 | defines if a fresh CRL must be available in order for the peer authentication based | |
866 | on RSA signatures to succeed. | |
867 | Accepted values are | |
868 | .B yes | |
869 | and | |
870 | .B no | |
871 | (the default). | |
872 | IKEv2 additionally recognizes | |
873 | .B ifuri | |
874 | which reverts to | |
875 | .B yes | |
876 | if at least one CRL URI is defined and to | |
877 | .B no | |
878 | if no URI is known. | |
879 | .PP | |
880 | The following | |
881 | .B config section | |
882 | parameters are used by the IKEv1 Pluto daemon only: | |
883 | .TP | |
884 | .B keep_alive | |
885 | interval in seconds between NAT keep alive packets, the default being 20 seconds. | |
886 | .TP | |
887 | .B nat_traversal | |
888 | activates NAT traversal by accepting source ISAKMP ports different from udp/500 and | |
889 | being able of floating to udp/4500 if a NAT situation is detected. | |
890 | Accepted values are | |
891 | .B yes | |
892 | and | |
893 | .B no | |
894 | (the default). | |
895 | .B nocrsend | |
896 | no certificate request payloads will be sent. | |
897 | Accepted values are | |
898 | .B yes | |
899 | and | |
900 | .B no | |
901 | (the default). | |
902 | Used by IKEv1 only, NAT traversal always being active in IKEv2. | |
903 | .TP | |
904 | .B pkcs11module | |
905 | defines the path to a dynamically loadable PKCS #11 library. | |
906 | .TP | |
907 | .B pkcs11keepstate | |
908 | PKCS #11 login sessions will be kept during the whole lifetime of the keying | |
909 | daemon. Useful with pin-pad smart card readers. | |
910 | Accepted values are | |
911 | .B yes | |
912 | and | |
913 | .B no | |
914 | (the default). | |
915 | .TP | |
916 | .B pkcs11proxy | |
917 | Pluto will act as a PKCS #11 proxy accessible via the whack interface. | |
918 | Accepted values are | |
919 | .B yes | |
920 | and | |
921 | .B no | |
922 | (the default). | |
923 | .TP | |
fea5e716 MW |
924 | .B plutodebug |
925 | how much Pluto debugging output should be logged. | |
926 | An empty value, | |
927 | or the magic value | |
928 | .BR none , | |
929 | means no debugging output (the default). | |
930 | The magic value | |
931 | .B all | |
932 | means full output. | |
933 | Otherwise only the specified types of output | |
934 | (a quoted list, names without the | |
935 | .B \-\-debug\- | |
936 | prefix, | |
937 | separated by white space) are enabled; | |
938 | for details on available debugging types, see | |
7900ab1b | 939 | .IR pluto (8). |
fea5e716 | 940 | .TP |
e0e7ef07 AS |
941 | .B postpluto |
942 | shell command to run after starting Pluto | |
943 | (e.g., to remove a decrypted copy of the | |
fea5e716 MW |
944 | .I ipsec.secrets |
945 | file). | |
946 | It's run in a very simple way; | |
947 | complexities like I/O redirection are best hidden within a script. | |
948 | Any output is redirected for logging, | |
949 | so running interactive commands is difficult unless they use | |
950 | .I /dev/tty | |
951 | or equivalent for their interaction. | |
952 | Default is none. | |
953 | .TP | |
e0e7ef07 AS |
954 | .B prepluto |
955 | shell command to run before starting Pluto | |
956 | (e.g., to decrypt an encrypted copy of the | |
fea5e716 MW |
957 | .I ipsec.secrets |
958 | file). | |
959 | It's run in a very simple way; | |
960 | complexities like I/O redirection are best hidden within a script. | |
961 | Any output is redirected for logging, | |
962 | so running interactive commands is difficult unless they use | |
963 | .I /dev/tty | |
964 | or equivalent for their interaction. | |
965 | Default is none. | |
966 | .TP | |
e0e7ef07 AS |
967 | .B virtual_private |
968 | defines private networks using a wildcard notation. | |
fea5e716 MW |
969 | .TP |
970 | .B uniqueids | |
971 | whether a particular participant ID should be kept unique, | |
972 | with any new (automatically keyed) | |
973 | connection using an ID from a different IP address | |
974 | deemed to replace all old ones using that ID; | |
975 | acceptable values are | |
976 | .B yes | |
977 | (the default) | |
978 | and | |
979 | .BR no . | |
980 | Participant IDs normally \fIare\fR unique, | |
981 | so a new (automatically-keyed) connection using the same ID is | |
982 | almost invariably intended to replace an old one. | |
e0e7ef07 AS |
983 | .PP |
984 | The following | |
985 | .B config section | |
986 | parameters are used by the IKEv2 Charon daemon only: | |
fea5e716 | 987 | .TP |
e0e7ef07 AS |
988 | .B charondebug |
989 | how much Charon debugging output should be logged. | |
990 | A comma separated list containing type level/pairs may | |
991 | be specified, e.g: | |
992 | .B dmn 3, ike 1, net -1. | |
993 | Acceptable values for types are | |
994 | .B dmn, mgr, ike, chd, job, cfg, knl, net, enc, lib | |
995 | and the level is one of | |
996 | .B -1, 0, 1, 2, 3, 4 | |
997 | (for silent, audit, control, controlmore, raw, private). | |
998 | .PP | |
999 | The following | |
1000 | .B config section | |
1001 | parameters only make sense if the KLIPS IPsec stack | |
1002 | is used instead of the default NETKEY stack of the Linux 2.6 kernel: | |
fea5e716 | 1003 | .TP |
e0e7ef07 AS |
1004 | .B fragicmp |
1005 | whether a tunnel's need to fragment a packet should be reported | |
1006 | back with an ICMP message, | |
1007 | in an attempt to make the sender lower his PMTU estimate; | |
1008 | acceptable values are | |
7900ab1b | 1009 | .B yes |
e0e7ef07 | 1010 | (the default) |
7900ab1b | 1011 | and |
e0e7ef07 | 1012 | .BR no . |
7900ab1b | 1013 | .TP |
e0e7ef07 AS |
1014 | .B hidetos |
1015 | whether a tunnel packet's TOS field should be set to | |
1016 | .B 0 | |
1017 | rather than copied from the user packet inside; | |
1018 | acceptable values are | |
7900ab1b | 1019 | .B yes |
e0e7ef07 | 1020 | (the default) |
7900ab1b | 1021 | and |
e0e7ef07 | 1022 | .BR no |
fea5e716 | 1023 | .TP |
e0e7ef07 AS |
1024 | .B interfaces |
1025 | virtual and physical interfaces for IPsec to use: | |
1026 | a single | |
1027 | \fIvirtual\fB=\fIphysical\fR pair, a (quoted!) list of pairs separated | |
1028 | by white space, or | |
1029 | .BR %none . | |
1030 | One of the pairs may be written as | |
1031 | .BR %defaultroute , | |
1032 | which means: find the interface \fId\fR that the default route points to, | |
1033 | and then act as if the value was ``\fBipsec0=\fId\fR''. | |
1034 | .B %defaultroute | |
1035 | is the default; | |
1036 | .B %none | |
1037 | must be used to denote no interfaces. | |
7900ab1b | 1038 | .TP |
e0e7ef07 AS |
1039 | .B overridemtu |
1040 | value that the MTU of the ipsec\fIn\fR interface(s) should be set to, | |
1041 | overriding IPsec's (large) default. | |
fea5e716 MW |
1042 | .SH CHOOSING A CONNECTION |
1043 | .PP | |
1044 | When choosing a connection to apply to an outbound packet caught with a | |
1045 | .BR %trap, | |
1046 | the system prefers the one with the most specific eroute that | |
1047 | includes the packet's source and destination IP addresses. | |
1048 | Source subnets are examined before destination subnets. | |
1049 | For initiating, only routed connections are considered. For responding, | |
1050 | unrouted but added connections are considered. | |
1051 | .PP | |
1052 | When choosing a connection to use to respond to a negotiation which | |
1053 | doesn't match an ordinary conn, an opportunistic connection | |
1054 | may be instantiated. Eventually, its instance will be /32 -> /32, but | |
1055 | for earlier stages of the negotiation, there will not be enough | |
1056 | information about the client subnets to complete the instantiation. | |
1057 | .SH FILES | |
1058 | .nf | |
1059 | /etc/ipsec.conf | |
7900ab1b AS |
1060 | /etc/ipsec.d/aacerts |
1061 | /etc/ipsec.d/acerts | |
fea5e716 MW |
1062 | /etc/ipsec.d/cacerts |
1063 | /etc/ipsec.d/certs | |
1064 | /etc/ipsec.d/crls | |
fea5e716 MW |
1065 | |
1066 | .SH SEE ALSO | |
7900ab1b | 1067 | ipsec(8), pluto(8), starter(8), ttoaddr(3), ttodata(3) |
fea5e716 | 1068 | .SH HISTORY |
e0e7ef07 AS |
1069 | Written for the FreeS/WAN project by Henry Spencer. |
1070 | Extended for the strongSwan project | |
fea5e716 | 1071 | <http://www.strongswan.org> |
7900ab1b | 1072 | by Andreas Steffen. IKEv2-specific features by Martin Willi. |
fea5e716 MW |
1073 | .SH BUGS |
1074 | .PP | |
7900ab1b | 1075 | If conns are to be added before DNS is available, \fBleft=\fP\fIFQDN\fP |
fea5e716 | 1076 | will fail. |