1IPSEC.CONF(5) strongSwan IPSEC.CONF(5)
2
6 ipsec.conf - IPsec configuration and connections
7
9 The optional ipsec.conf file specifies most configuration and control
10 information for the strongSwan IPsec subsystem. The major exception is
11 secrets for authentication; see ipsec.secrets(5). Its contents are not
12 security-sensitive.
13 The file is a text file, consisting of one or more sections. White
15 space followed by # followed by anything to the end of the line is a
16 comment and is ignored, as are empty lines which are not within a sec‐
17 tion.
18 A line which contains include and a file name, separated by white
20 space, is replaced by the contents of that file. If the file name is
21 not a full pathname, it is considered to be relative to the directory
22 containing the including file. Such inclusions can be nested. Only a
23 single filename may be supplied, and it may not contain white space,
24 but it may include shell wildcards (see sh(1)); for example:
25 include ipsec.*.conf
27 The intention of the include facility is mostly to permit keeping
29 information on connections, or sets of connections, separate from the
30 main configuration file. This permits such connection descriptions to
31 be changed, copied to the other security gateways involved, etc., with‐
32 out having to constantly extract them from the configuration file and
33 then insert them back into it. Note also the also parameter (described
34 below) which permits splitting a single logical section (e.g. a connec‐
35 tion description) into several actual sections.
36 A section begins with a line of the form:
38 type name
40 where type indicates what type of section follows, and name is an arbi‐
42 trary name which distinguishes the section from others of the same
43 type. All subsequent non-empty lines which begin with white space are
44 part of the section. Sections of the same type that share the same
45 name are merged.
46 Lines within the section are generally of the form
48 parameter=value
50 (note the mandatory preceding white space). There can be white space
52 on either side of the =. Parameter names are specific to a section
53 type.
54 An empty value stands for the system default value (if any) of the
56 parameter, i.e. it is roughly equivalent to omitting the parameter line
57 entirely. This may be useful to clear a setting inherited from a
58 %default section or via also parameter (see below). A value may con‐
59 tain single spaces (additional white space is reduced to one space).
60 To preserve white space as written enclose the entire value in double
61 quotes ("); in such values double quotes themselves may be escaped by
62 prefixing them with \ characters. A double-quoted string may span mul‐
63 tiple lines by ending them with \ characters (following lines don't
64 have to begin with white space, as that will be preserved). Addition‐
65 ally, the following control characters may be encoded in double-quoted
66 strings: \n, \r, \t, \b, \f.
67 Numeric values are specified to be either an ``integer'' (a sequence of
69 digits) or a ``decimal number'' (sequence of digits optionally followed
70 by `.' and another sequence of digits).
71 There is currently one parameter which is available in any type of sec‐
73 tion:
74 also the value is a section name; the parameters of that section are
76 inherited by the current section. Parameters in the current sec‐
77 tion always override inherited parameters, even if an also fol‐
78 lows after them. The specified section must exist and must have
79 the same section type; it doesn't if it is defined before or
80 after the current section. Nesting is permitted, and there may
81 be more than one also in a single section (parameters from ref‐
82 erenced sections are inherited and overridden in the order of
83 these also parameters).
84 A section with name %default specifies defaults for sections of the
86 same type. All parameters in it, are inherited by all other sections of
87 that type.
88 Currently there are three types of sections: a config section specifies
90 general configuration information for IPsec, a conn section specifies
91 an IPsec connection, while a ca section specifies special properties of
92 a certification authority.
93
95 A conn section contains a connection specification, defining a network
96 connection to be made using IPsec. The name given is arbitrary, and is
97 used to identify the connection. Here's a simple example:
98 conn snt
100 left=192.168.0.1
101 leftsubnet=10.1.0.0/16
102 right=192.168.0.2
103 rightsubnet=10.1.0.0/16
104 keyingtries=%forever
105 auto=add
106 A note on terminology: There are two kinds of communications going on:
108 transmission of user IP packets, and gateway-to-gateway negotiations
109 for keying, rekeying, and general control. The path to control the
110 connection is called 'ISAKMP SA' in IKEv1 and 'IKE SA' in the IKEv2
111 protocol. That what is being negotiated, the kernel level data path, is
112 called 'IPsec SA' or 'Child SA'. strongSwan previously used two sepa‐
113 rate keying daemons, pluto and charon. This manual does not discuss
114 pluto options anymore, but only charon that since strongSwan 5.0 sup‐
115 ports both IKEv1 and IKEv2.
116 To avoid trivial editing of the configuration file to suit it to each
118 system involved in a connection, connection specifications are written
119 in terms of left and right participants, rather than in terms of local
120 and remote. Which participant is considered left or right is arbi‐
121 trary; for every connection description an attempt is made to figure
122 out whether the local endpoint should act as the left or right end‐
123 point. This is done by matching the IP addresses defined for both end‐
124 points with the IP addresses assigned to local network interfaces. If a
125 match is found then the role (left or right) that matches is going to
126 be considered local. If no match is found during startup, left is con‐
127 sidered local. This permits using identical connection specifications
128 on both ends. There are cases where there is no symmetry; a good con‐
129 vention is to use left for the local side and right for the remote side
130 (the first letters are a good mnemonic).
131 Many of the parameters relate to one participant or the other; only the
133 ones for left are listed here, but every parameter whose name begins
134 with left has a right counterpart, whose description is the same but
135 with left and right reversed.
136 Parameters are optional unless marked '(required)'.
138 CONN PARAMETERS
140 Unless otherwise noted, for a connection to work, in general it is nec‐
141 essary for the two ends to agree exactly on the values of these parame‐
142 ters.
143 aaa_identity = <id>
145 defines the identity of the AAA backend used during IKEv2 EAP
146 authentication. This is required if the EAP client uses a
147 method that verifies the server identity (such as EAP-TLS), but
148 it does not match the IKEv2 gateway identity.
149 aggressive = yes | no
151 whether to use IKEv1 Aggressive or Main Mode (the default).
152 ah = <cipher suites>
154 comma-separated list of AH algorithms to be used for the connec‐
155 tion, e.g. sha1-sha256-modp1024. The notation is
156 integrity[-dhgroup]. For IKEv2, multiple algorithms (separated
157 by -) of the same type can be included in a single proposal.
158 IKEv1 only includes the first algorithm in a proposal. Only
159 either the ah or esp keyword may be used, AH+ESP bundles are not
160 supported.
161 There is no default AH cipher suite since by default ESP is
163 used. The daemon adds its extensive default proposal to the
164 configured value. To restrict it to the configured proposal an
165 exclamation mark (!) can be added at the end.
166 If dh-group is specified, CHILD_SA/Quick Mode setup and rekeying
168 include a separate Diffie-Hellman exchange (refer to the esp
169 keyword for details).
170 also = <name>
172 includes conn section <name>.
173 auth = <value>
175 was used by the pluto IKEv1 daemon to use AH integrity protec‐
176 tion for ESP encrypted packets, but is not supported in charon.
177 The ah keyword specifies algorithms to use for integrity protec‐
178 tion with AH, but without encryption. AH+ESP bundles are not
179 supported.
180 authby = pubkey | rsasig | ecdsasig | psk | secret | never | xauthpsk |
182 xauthrsasig
183 how the two security gateways should authenticate each other;
184 acceptable values are psk or secret for pre-shared secrets, pub‐
185 key (the default) for public key signatures as well as the syn‐
186 onyms rsasig for RSA digital signatures and ecdsasig for Ellip‐
187 tic Curve DSA signatures. never can be used if negotiation is
188 never to be attempted or accepted (useful for shunt-only conns).
189 Digital signatures are superior in every way to shared secrets.
190 IKEv1 additionally supports the values xauthpsk and xauthrsasig
191 that will enable eXtended AUTHentication (XAUTH) in addition to
192 IKEv1 main mode based on shared secrets or digital RSA signa‐
193 tures, respectively. This parameter is deprecated, as two peers
194 do not need to agree on an authentication method in IKEv2. Use
195 the leftauth parameter instead to define authentication methods.
196 auto = ignore | add | route | start
198 what operation, if any, should be done automatically at IPsec
199 startup; currently-accepted values are add, route, start and
200 ignore (the default). add loads a connection without starting
201 it. route loads a connection and installs kernel traps. If
202 traffic is detected between leftsubnet and rightsubnet, a con‐
203 nection is established. start loads a connection and brings it
204 up immediately. ignore ignores the connection. This is equal to
205 deleting a connection from the config file. Relevant only
206 locally, other end need not agree on it.
207 closeaction = none | clear | hold | restart
209 defines the action to take if the remote peer unexpectedly
210 closes a CHILD_SA (see dpdaction for meaning of values). A
211 closeaction should not be used if the peer uses reauthentication
212 or uniquids checking, as these events might trigger the defined
213 action when not desired.
214 compress = yes | no
216 whether IPComp compression of content is proposed on the connec‐
217 tion (link-level compression does not work on encrypted data, so
218 to be effective, compression must be done before encryption);
219 acceptable values are yes and no (the default). A value of yes
220 causes the daemon to propose both compressed and uncompressed,
221 and prefer compressed. A value of no prevents the daemon from
222 proposing or accepting compression.
223 dpdaction = none | clear | hold | restart
225 controls the use of the Dead Peer Detection protocol (DPD, RFC
226 3706) where R_U_THERE notification messages (IKEv1) or empty
227 INFORMATIONAL messages (IKEv2) are periodically sent in order to
228 check the liveliness of the IPsec peer. The values clear, hold,
229 and restart all activate DPD and determine the action to perform
230 on a timeout. With clear the connection is closed with no fur‐
231 ther actions taken. hold installs a trap policy, which will
232 catch matching traffic and tries to re-negotiate the connection
233 on demand. restart will immediately trigger an attempt to re-
234 negotiation the connection. The default is none which disables
235 the active sending of DPD messages.
236 dpddelay = 30s | <time>
238 defines the period time interval with which R_U_THERE mes‐
239 sages/INFORMATIONAL exchanges are sent to the peer. These are
240 only sent if no other traffic is received. In IKEv2, a value of
241 0 sends no additional INFORMATIONAL messages and uses only stan‐
242 dard messages (such as those to rekey) to detect dead peers.
243 dpdtimeout = 150s | <time>
245 defines the timeout interval, after which all connections to a
246 peer are deleted in case of inactivity. This only applies to
247 IKEv1, in IKEv2 the default retransmission timeout applies, as
248 every exchange is used to detect dead peers.
249 inactivity = <time>
251 defines the timeout interval, after which a CHILD_SA is closed
252 if it did not send or receive any traffic. The inactivity
253 counter is reset during CHILD_SA rekeying. This means that the
254 inactivity timeout must be smaller than the rekeying interval to
255 have any effect.
256 eap_identity = <id>
258 defines the identity the client uses to reply to an EAP Identity
259 request. If defined on the EAP server, the defined identity
260 will be used as peer identity during EAP authentication. The
261 special value %identity uses the EAP Identity method to ask the
262 client for an EAP identity. If not defined, the IKEv2 identity
263 will be used as EAP identity.
264 esp = <cipher suites>
266 comma-separated list of ESP encryption/authentication algorithms
267 to be used for the connection, e.g. aes128-sha256. The nota‐
268 tion is encryption-integrity[-dhgroup][-esnmode]. For IKEv2,
269 multiple algorithms (separated by -) of the same type can be
270 included in a single proposal. IKEv1 only includes the first
271 algorithm in a proposal. Only either the ah or esp keyword may
272 be used, AH+ESP bundles are not supported.
273 Defaults to aes128-sha256. The daemon adds its extensive
275 default proposal to this default or the configured value. To
276 restrict it to the configured proposal an exclamation mark (!)
277 can be added at the end.
278 Note: As a responder, the daemon defaults to selecting the first
280 configured proposal that's also supported by the peer. This may
281 be changed via strongswan.conf(5) to selecting the first accept‐
282 able proposal sent by the peer instead. In order to restrict a
283 responder to only accept specific cipher suites, the strict flag
284 (!, exclamation mark) can be used, e.g: aes256-sha512-modp4096!
285 If dh-group is specified, CHILD_SA/Quick Mode rekeying and ini‐
287 tial negotiation use a separate Diffie-Hellman exchange using
288 the specified group. However, for IKEv2, the keys of the
289 CHILD_SA created implicitly with the IKE_SA will always be
290 derived from the IKE_SA's key material. So any DH group speci‐
291 fied here will only apply when the CHILD_SA is later rekeyed or
292 is created with a separate CREATE_CHILD_SA exchange. Therefore,
293 a proposal mismatch might not immediately be noticed when the SA
294 is established, but may later cause rekeying to fail.
295 Valid values for esnmode are esn and noesn. Specifying both
297 negotiates Extended Sequence Number support with the peer, the
298 default is noesn.
299 forceencaps = yes | no
301 force UDP encapsulation for ESP packets even if no NAT situation
302 is detected. This may help to surmount restrictive firewalls.
303 In order to force the peer to encapsulate packets, NAT detection
304 payloads are faked.
305 fragmentation = yes | accept | force | no
307 whether to use IKE fragmentation (proprietary IKEv1 extension or
308 IKEv2 fragmentation as per RFC 7383). Acceptable values are yes
309 (the default), accept, force and no. If set to yes, and the
310 peer supports it, oversized IKE messages will be sent in frag‐
311 ments. If set to accept, support for fragmentation is announced
312 to the peer but the daemon does not send its own messages in
313 fragments. If set to force (only supported for IKEv1) the ini‐
314 tial IKE message will already be fragmented if required.
315 Finally, setting the option to no will disable announcing sup‐
316 port for this feature.
317 Note that fragmented IKE messages sent by a peer are always
319 accepted irrespective of the value of this option (even when set
320 to no).
321 ike = <cipher suites>
323 comma-separated list of IKE/ISAKMP SA encryption/authentication
324 algorithms to be used, e.g. aes128-sha256-modp3072. The nota‐
325 tion is encryption-integrity[-prf]-dhgroup. If no PRF is given,
326 the algorithms defined for integrity are used for the PRF. The
327 prf keywords are the same as the integrity algorithms, but have
328 a prf prefix (such as prfsha1, prfsha256 or prfaesxcbc).
329 In IKEv2, multiple algorithms and proposals may be included,
330 such as aes128-aes256-sha1-modp3072-modp2048,3des-
331 sha1-md5-modp1024.
332 Defaults to aes128-sha256-modp3072. The daemon adds its exten‐
334 sive default proposal to this default or the configured value.
335 To restrict it to the configured proposal an exclamation mark
336 (!) can be added at the end.
337 Note: As a responder the daemon accepts the first supported pro‐
339 posal received from the peer. In order to restrict a responder
340 to only accept specific cipher suites, the strict flag (!,
341 exclamation mark) can be used, e.g: aes256-sha512-modp4096!
342 ikedscp = 000000 | <DSCP field>
344 Differentiated Services Field Codepoint to set on outgoing IKE
345 packets sent from this connection. The value is a six digit
346 binary encoded string defining the Codepoint to set, as defined
347 in RFC 2474.
348 ikelifetime = 3h | <time>
350 how long the keying channel of a connection (ISAKMP or IKE SA)
351 should last before being renegotiated. Also see EXPIRY/REKEY
352 below.
353 installpolicy = yes | no
355 decides whether IPsec policies are installed in the kernel by
356 the charon daemon for a given connection. Allows peaceful coop‐
357 eration e.g. with the Mobile IPv6 daemon mip6d who wants to con‐
358 trol the kernel policies. Acceptable values are yes (the
359 default) and no.
360 keyexchange = ike | ikev1 | ikev2
362 which key exchange protocol should be used to initiate the con‐
363 nection. Connections marked with ike use IKEv2 when initiating,
364 but accept any protocol version when responding.
365 keyingtries = 3 | <number> | %forever
367 how many attempts (a whole number or %forever) should be made to
368 negotiate a connection, or a replacement for one, before giving
369 up (default 3). The value %forever means 'never give up'. Rel‐
370 evant only locally, other end need not agree on it.
371 left = <ip address> | <fqdn> | %any | <range> | <subnet>
373 The IP address of the left participant's public-network inter‐
374 face or one of several magic values. The value %any (the
375 default) for the local endpoint signifies an address to be
376 filled in (by automatic keying) during negotiation. If the local
377 peer initiates the connection setup the routing table will be
378 queried to determine the correct local IP address. In case the
379 local peer is responding to a connection setup then any IP
380 address that is assigned to a local interface will be accepted.
381 The prefix % in front of a fully-qualified domain name or an IP
383 address will implicitly set leftallowany=yes.
384 If %any is used for the remote endpoint it literally means any
386 IP address.
387 If an FQDN is assigned it is resolved every time a configuration
389 lookup is done. If DNS resolution times out, the lookup is
390 delayed for that time.
391 To limit the connection to a specific range of hosts, a range (
393 10.1.0.0-10.2.255.255 ) or a subnet ( 10.1.0.0/16 ) can be spec‐
394 ified, and multiple addresses, ranges and subnets can be sepa‐
395 rated by commas. While one can freely combine these items, to
396 initiate the connection at least one non-range/subnet is
397 required.
398 Please note that with the usage of wildcards multiple connection
400 descriptions might match a given incoming connection attempt.
401 The most specific description is used in that case.
402 leftallowany = yes | no
404 a modifier for left, making it behave as %any although a con‐
405 crete IP address or domain name has been assigned.
406 leftauth = <auth method>
408 Authentication method to use locally (left) or require from the
409 remote (right) side. Acceptable values are pubkey for public
410 key authentication (RSA/ECDSA), psk for pre-shared key authenti‐
411 cation, eap to (require the) use of the Extensible Authentica‐
412 tion Protocol in IKEv2, and xauth for IKEv1 eXtended Authentica‐
413 tion.
414 To require a trustchain public key strength for the remote side,
416 specify the key type followed by the minimum strength in bits
417 (for example ecdsa-384 or rsa-2048-ecdsa-256). To limit the
418 acceptable set of hashing algorithms for trustchain validation,
419 append hash algorithms to pubkey or a key strength definition
420 (for example pubkey-sha256-sha512,
421 rsa-2048-sha256-sha384-sha512, or
422 rsa-2048-sha256-ecdsa-256-sha256-sha384). Unless disabled in
423 strongswan.conf(5), or explicit IKEv2 signature constraints are
424 configured (see below), such key types and hash algorithms are
425 also applied as constraints against IKEv2 signature authentica‐
426 tion schemes used by the remote side.
427 If both peers support RFC 7427 ("Signature Authentication in
429 IKEv2") specific hash algorithms to be used during IKEv2 authen‐
430 tication may be configured. The syntax is the same as above,
431 but with ike: prefix. For example, with ike:pubkey-sha384-sha256
432 a public key signature scheme with either SHA-384 or SHA-256
433 would get used for authentication, in that order and depending
434 on the hash algorithms supported by the peer. If no specific
435 hash algorithms are configured, the default is to prefer an
436 algorithm that matches or exceeds the strength of the signature
437 key. If no constraints with ike: prefix are configured any sig‐
438 nature scheme constraint (without ike: prefix) will also apply
439 to IKEv2 authentication, unless this is disabled in
440 strongswan.conf(5).
441 To use or require RSASSA-PSS signatures use rsa/pss instead of
443 rsa as in e.g. ike:rsa/pss-sha256. If pubkey or rsa con‐
444 straints are configured RSASSA-PSS signatures will only be
445 used/accepted if enabled in strongswan.conf(5).
446 For eap, an optional EAP method can be appended. Currently
448 defined methods are eap-aka, eap-gtc, eap-md5, eap-mschapv2,
449 eap-peap, eap-sim, eap-tls, eap-ttls, eap-dynamic, and eap-
450 radius. Alternatively, IANA assigned EAP method numbers are
451 accepted. Vendor specific EAP methods are defined in the form
452 eap-type-vendor (e.g. eap-7-12345). To specify signature and
453 trust chain constraints for EAP-(T)TLS, append a colon to the
454 EAP method, followed by the key type/size and hash algorithm as
455 discussed above. For xauth, an XAuth authentication backend can
456 be specified, such as xauth-generic or xauth-eap. If XAuth is
457 used in leftauth, Hybrid authentication is used. For traditional
458 XAuth authentication, define XAuth in lefauth2.
459 leftauth2 = <auth method>
461 Same as leftauth, but defines an additional authentication
462 exchange. In IKEv1, only XAuth can be used in the second authen‐
463 tication round. IKEv2 supports multiple complete authentication
464 rounds using "Multiple Authentication Exchanges" defined in RFC
465 4739. This allows, for example, separated authentication of host
466 and user.
467 leftca = <issuer dn> | %same
469 the distinguished name of a certificate authority which is
470 required to lie in the trust path going from the left partici‐
471 pant's certificate up to the root certification authority.
472 %same means that the value configured for the right participant
473 should be reused.
474 leftca2 = <issuer dn> | %same
476 Same as leftca, but for the second authentication round (IKEv2
477 only).
478 leftcert = <path>
480 the path to the left participant's X.509 certificate. The file
481 can be encoded either in PEM or DER format. OpenPGP certificates
482 are supported as well. Both absolute paths or paths relative to
483 /etc/ipsec.d/certs are accepted. By default leftcert sets leftid
484 to the distinguished name of the certificate's subject. The
485 left participant's ID can be overridden by specifying a leftid
486 value which must be certified by the certificate, though.
487 A value in the form %smartcard[<slot nr>[@<module>]]:<keyid>
488 defines a specific certificate to load from a PKCS#11 backend
489 for this connection. See ipsec.secrets(5) for details about
490 smartcard definitions. leftcert is required only if selecting
491 the certificate with leftid is not sufficient, for example if
492 multiple certificates use the same subject.
493 Multiple certificate paths or PKCS#11 backends can be specified
494 in a comma separated list. The daemon chooses the certificate
495 based on the received certificate requests if possible before
496 enforcing the first.
497 leftcert2 = <path>
499 Same as leftcert, but for the second authentication round (IKEv2
500 only).
501 leftcertpolicy = <OIDs>
503 Comma separated list of certificate policy OIDs the peer's cer‐
504 tificate must have. OIDs are specified using the numerical dot‐
505 ted representation.
506 leftdns = <servers>
508 Comma separated list of DNS server addresses to exchange as con‐
509 figuration attributes. On the initiator, a server is a fixed
510 IPv4/IPv6 address, or %config4/%config6 to request attributes
511 without an address. On the responder, only fixed IPv4/IPv6
512 addresses are allowed and define DNS servers assigned to the
513 client.
514 leftfirewall = yes | no
516 whether the left participant is doing forwarding-firewalling
517 (including masquerading) using iptables for traffic from left‐
518 subnet, which should be turned off (for traffic to the other
519 subnet) once the connection is established; acceptable values
520 are yes and no (the default). May not be used in the same con‐
521 nection description with leftupdown. Implemented as a parameter
522 to the default ipsec _updown script. See notes below. Relevant
523 only locally, other end need not agree on it.
524 If one or both security gateways are doing forwarding fire‐
526 walling (possibly including masquerading), and this is specified
527 using the firewall parameters, tunnels established with IPsec
528 are exempted from it so that packets can flow unchanged through
529 the tunnels. (This means that all subnets connected in this
530 manner must have distinct, non-overlapping subnet address
531 blocks.) This is done by the default ipsec _updown script.
532 In situations calling for more control, it may be preferable for
534 the user to supply his own updown script, which makes the appro‐
535 priate adjustments for his system.
536 leftgroups = <group list>
538 a comma separated list of group names. If the leftgroups parame‐
539 ter is present then the peer must be a member of at least one of
540 the groups defined by the parameter.
541 leftgroups2 = <group list>
543 Same as leftgroups, but for the second authentication round
544 defined with leftauth2.
545 lefthostaccess = yes | no
547 inserts a pair of INPUT and OUTPUT iptables rules using the
548 default ipsec _updown script, thus allowing access to the host
549 itself in the case where the host's internal interface is part
550 of the negotiated client subnet. Acceptable values are yes and
551 no (the default).
552 leftid = <id>
554 how the left participant should be identified for authentica‐
555 tion; defaults to left or the subject of the certificate config‐
556 ured with leftcert. If leftcert is configured the identity has
557 to be confirmed by the certificate.
558 Can be an IP address, a fully-qualified domain name, an email
560 address or a Distinguished Name for which the ID type is deter‐
561 mined automatically and the string is converted to the appropri‐
562 ate encoding. The rules for this conversion are described in
563 IDENTITY PARSING below.
564 In certain special situations the identity parsing above might
566 be inadequate or produce the wrong result. Examples are the need
567 to encode a FQDN as KEY_ID or the string parser being unable to
568 produce the correct binary ASN.1 encoding of a certificate's DN.
569 For these situations it is possible to enforce a specific iden‐
570 tity type and to provide the binary encoding of the identity. To
571 do this a prefix may be used, followed by a colon (:). If the
572 number sign (#) follows the colon, the remaining data is inter‐
573 preted as hex encoding, otherwise the string is used as is as
574 the identification data. Note: The latter implies that no con‐
575 version is performed for non-string identities. For example,
576 ipv4:10.0.0.1 does not create a valid ID_IPV4_ADDR IKE identity,
577 as it does not get converted to binary 0x0a000001. Instead, one
578 could use ipv4:#0a000001 to get a valid identity, but just using
579 the implicit type with automatic conversion is usually simpler.
580 The same applies to the ASN.1 encoded types. The following pre‐
581 fixes are known: ipv4, ipv6, rfc822, email, userfqdn, fqdn, dns,
582 asn1dn, asn1gn and keyid. Custom type prefixes may be specified
583 by surrounding the numerical type value by curly brackets.
584 For IKEv2 and rightid the prefix % in front of the identity pre‐
586 vents the daemon from sending IDr in its IKE_AUTH request and
587 will allow it to verify the configured identity against the sub‐
588 ject and subjectAltNames contained in the responder's certifi‐
589 cate (otherwise it is only compared with the IDr returned by the
590 responder). The IDr sent by the initiator might otherwise pre‐
591 vent the responder from finding a config if it has configured a
592 different value for leftid.
593 leftid2 = <id>
595 identity to use for a second authentication for the left partic‐
596 ipant (IKEv2 only); defaults to leftid.
597 leftikeport = <port>
599 UDP port the left participant uses for IKE communication. If
600 unspecified, port 500 is used with the port floating to 4500 if
601 a NAT is detected or MOBIKE is enabled. Specifying a local IKE
602 port different from the default additionally requires a socket
603 implementation that listens on this port.
604 leftprotoport = <protocol>/<port>
606 restrict the traffic selector to a single protocol and/or port.
607 This option is now deprecated, protocol/port information can be
608 defined for each subnet directly in leftsubnet.
609 leftsigkey = <raw public key> | <path to public key>
611 the left participant's public key for public key signature
612 authentication, in PKCS#1 format using hex (0x prefix) or base64
613 (0s prefix) encoding. With the optional dns: or ssh: prefix in
614 front of 0x or 0s, the public key is expected to be in either
615 the RFC 3110 (not the full RR, only RSA key part) or RFC 4253
616 public key format, respectively. Also accepted is the path to a
617 file containing the public key in PEM, DER or SSH encoding. Both
618 absolute paths or paths relative to /etc/ipsec.d/certs are
619 accepted.
620 leftsendcert = never | no | ifasked | always | yes
622 Accepted values are never or no, always or yes, and ifasked (the
623 default), the latter meaning that the peer must send a certifi‐
624 cate request payload in order to get a certificate in return.
625 leftsourceip = %config4 | %config6 | <ip address>
627 Comma separated list of internal source IPs to use in a tunnel,
628 also known as virtual IP. If the value is one of the synonyms
629 %config, %cfg, %modeconfig, or %modecfg, an address (from the
630 tunnel address family) is requested from the peer. With %config4
631 and %config6 an address of the given address family will be
632 requested explicitly. If an IP address is configured, it will
633 be requested from the responder, which is free to respond with a
634 different address.
635 rightsourceip = %config | <network>/<netmask> | <from>-<to> | %poolname
637 Comma separated list of internal source IPs to use in a tunnel
638 for the remote peer. If the value is %config on the responder
639 side, the initiator must propose an address which is then echoed
640 back. Also supported are address pools expressed as network/net‐
641 mask and from-to or the use of an external IP address pool using
642 %poolname, where poolname is the name of the IP address pool
643 used for the lookup.
644 leftsubnet = <ip subnet>[[<proto/port>]][,...]
646 private subnet behind the left participant, expressed as net‐
647 work/netmask; if omitted, essentially assumed to be left/32,
648 signifying that the left end of the connection goes to the left
649 participant only. Configured subnets of the peers may differ,
650 the protocol narrows it to the greatest common subnet. In IKEv1,
651 this may lead to problems with other implementations, make sure
652 to configure identical subnets in such configurations. IKEv2
653 supports multiple subnets separated by commas. IKEv1 only inter‐
654 prets the first subnet of such a definition, unless the Cisco
655 Unity extension plugin is enabled. This is due to a limitation
656 of the IKEv1 protocol, which only allows a single pair of sub‐
657 nets per CHILD_SA. So to tunnel several subnets a conn entry has
658 to be defined and brought up for each pair of subnets.
659 The optional part after each subnet enclosed in square brackets
661 specifies a protocol/port to restrict the selector for that sub‐
662 net.
663 Examples: leftsubnet=10.0.0.1[tcp/http],10.0.0.2[6/80] or left‐
665 subnet=fec1::1[udp],10.0.0.0/16[/53]. Instead of omitting
666 either value %any can be used to the same effect, e.g. leftsub‐
667 net=fec1::1[udp/%any],10.0.0.0/16[%any/53].
668 If the protocol is icmp or ipv6-icmp the port is interpreted as
670 ICMP message type if it is less than 256 or as type and code if
671 it is greater or equal to 256, with the type in the most signif‐
672 icant 8 bits and the code in the least significant 8 bits.
673 The port value can alternatively take the value %opaque for RFC
675 4301 OPAQUE selectors, or a numerical range in the form
676 1024-65535. None of the kernel backends currently supports
677 opaque or port ranges and uses %any for policy installation
678 instead.
679 Instead of specifying a subnet, %dynamic can be used to replace
681 it with the IKE address, having the same effect as omitting
682 leftsubnet completely. Using %dynamic can be used to define mul‐
683 tiple dynamic selectors, each having a potentially different
684 protocol/port definition.
685 leftupdown = <path>
688 what ``updown'' script to run to adjust routing and/or fire‐
689 walling when the status of the connection changes (default ipsec
690 _updown). May include positional parameters separated by white
691 space (although this requires enclosing the whole string in
692 quotes); including shell metacharacters is unwise. Relevant
693 only locally, other end need not agree on it. Charon uses the
694 updown script to insert firewall rules only, since routing has
695 been implemented directly into the daemon.
696 lifebytes = <number>
698 the number of bytes transmitted over an IPsec SA before it
699 expires.
700 lifepackets = <number>
702 the number of packets transmitted over an IPsec SA before it
703 expires.
704 lifetime = 1h | <time>
706 how long a particular instance of a connection (a set of encryp‐
707 tion/authentication keys for user packets) should last, from
708 successful negotiation to expiry; acceptable values are an inte‐
709 ger optionally followed by s (a time in seconds) or a decimal
710 number followed by m, h, or d (a time in minutes, hours, or days
711 respectively) (default 1h, maximum 24h). Normally, the connec‐
712 tion is renegotiated (via the keying channel) before it expires
713 (see margintime). The two ends need not exactly agree on life‐
714 time, although if they do not, there will be some clutter of
715 superseded connections on the end which thinks the lifetime is
716 longer. Also see EXPIRY/REKEY below.
717 marginbytes = <number>
719 how many bytes before IPsec SA expiry (see lifebytes) should
720 attempts to negotiate a replacement begin.
721 marginpackets = <number>
723 how many packets before IPsec SA expiry (see lifepackets) should
724 attempts to negotiate a replacement begin.
725 margintime = 9m | <time>
727 how long before connection expiry or keying-channel expiry
728 should attempts to negotiate a replacement begin; acceptable
729 values as for lifetime (default 9m). Relevant only locally,
730 other end need not agree on it. Also see EXPIRY/REKEY below.
731 mark = <value>[/<mask>]
733 sets an XFRM mark on the inbound policy and outbound IPsec SA
734 and policy. If the mask is missing then a default mask of
735 0xffffffff is assumed. The special value %unique assigns a
736 unique value to each newly created IPsec SA. To additionally
737 make the mark unique for each IPsec SA direction (in/out) the
738 special value %unique-dir may be used.
739 mark_in = <value>[/<mask>]
741 sets an XFRM mark on the inbound policy (not on the SA). If the
742 mask is missing then a default mask of 0xffffffff is assumed.
743 mark_out = <value>[/<mask>]
745 sets an XFRM mark on the outbound IPsec SA and policy. If the
746 mask is missing then a default mask of 0xffffffff is assumed.
747 mobike = yes | no
749 enables the IKEv2 MOBIKE protocol defined by RFC 4555. Accepted
750 values are yes (the default) and no. If set to no, the charon
751 daemon will not actively propose MOBIKE as initiator and ignore
752 the MOBIKE_SUPPORTED notify as responder.
753 modeconfig = push | pull
755 defines which mode is used to assign a virtual IP. Accepted
756 values are push and pull (the default). Push mode is currently
757 not supported with IKEv2. The setting must be the same on both
758 sides.
759 reauth = yes | no
761 whether rekeying of an IKE_SA should also reauthenticate the
762 peer. In IKEv1, reauthentication is always done. In IKEv2, a
763 value of no rekeys without uninstalling the IPsec SAs, a value
764 of yes (the default) creates a new IKE_SA from scratch and tries
765 to recreate all IPsec SAs.
766 rekey = yes | no
768 whether a connection should be renegotiated when it is about to
769 expire; acceptable values are yes (the default) and no. The two
770 ends need not agree, but while a value of no prevents charon
771 from requesting renegotiation, it does not prevent responding to
772 renegotiation requested from the other end, so no will be
773 largely ineffective unless both ends agree on it. Also see
774 reauth.
775 rekeyfuzz = 100% | <percentage>
777 maximum percentage by which marginbytes, marginpackets and
778 margintime should be randomly increased to randomize rekeying
779 intervals (important for hosts with many connections); accept‐
780 able values are an integer, which may exceed 100, followed by a
781 `%' (defaults to 100%). The value of marginTYPE, after this
782 random increase, must not exceed lifeTYPE (where TYPE is one of
783 bytes, packets or time). The value 0% will suppress randomiza‐
784 tion. Relevant only locally, other end need not agree on it.
785 Also see EXPIRY/REKEY below.
786 replay_window = -1 | <number>
788 The IPsec replay window size for this connection. With the
789 default of -1 the value configured with charon.replay_window in
790 strongswan.conf(5) is used. Larger values than 32 are supported
791 using the Netlink backend only, a value of 0 disables IPsec
792 replay protection.
793 reqid = <number>
795 sets the reqid for a given connection to a pre-configured fixed
796 value.
797 sha256_96 = no | yes
799 HMAC-SHA-256 is used with 128-bit truncation with IPsec. For
800 compatibility with implementations that incorrectly use 96-bit
801 truncation this option may be enabled to configure the shorter
802 truncation length in the kernel. This is not negotiated, so
803 this only works with peers that use the incorrect truncation
804 length (or have this option enabled).
805 tfc = <value>
807 number of bytes to pad ESP payload data to. Traffic Flow Confi‐
808 dentiality is currently supported in IKEv2 and applies to outgo‐
809 ing packets only. The special value %mtu fills up ESP packets
810 with padding to have the size of the MTU.
811 type = tunnel | transport | transport_proxy | passthrough | drop
813 the type of the connection; currently the accepted values are
814 tunnel (the default) signifying a host-to-host, host-to-subnet,
815 or subnet-to-subnet tunnel; transport, signifying host-to-host
816 transport mode; transport_proxy, signifying the special Mobile
817 IPv6 transport proxy mode; passthrough, signifying that no IPsec
818 processing should be done at all; drop, signifying that packets
819 should be discarded.
820 xauth = client | server
822 specifies the role in the XAuth protocol if activated by
823 authby=xauthpsk or authby=xauthrsasig. Accepted values are
824 server and client (the default).
825 xauth_identity = <id>
827 defines the identity/username the client uses to reply to an
828 XAuth request. If not defined, the IKEv1 identity will be used
829 as XAuth identity.
830 CONN PARAMETERS: IKEv2 MEDIATION EXTENSION
833 The following parameters are relevant to IKEv2 Mediation Extension
834 operation only.
835 mediation = yes | no
837 whether this connection is a mediation connection, ie. whether
838 this connection is used to mediate other connections. Mediation
839 connections create no child SA. Acceptable values are no (the
840 default) and yes.
841 mediated_by = <name>
843 the name of the connection to mediate this connection through.
844 If given, the connection will be mediated through the named
845 mediation connection. The mediation connection must set media‐
846 tion=yes.
847 me_peerid = <id>
849 ID as which the peer is known to the mediation server, ie. which
850 the other end of this connection uses as its leftid on its con‐
851 nection to the mediation server. This is the ID we request the
852 mediation server to mediate us with. If me_peerid is not given,
853 the rightid of this connection will be used as peer ID.
854
857 These are optional sections that can be used to assign special parame‐
858 ters to a Certification Authority (CA). Because the daemons automati‐
859 cally import CA certificates from /etc/ipsec.d/cacerts, there is no
860 need to explicitly add them with a CA section, unless you want to
861 assign special parameters (like a CRL) to a CA.
862 also = <name>
864 includes ca section <name>.
865 auto = ignore | add
867 currently can have either the value ignore (the default) or add.
868 cacert = <path>
870 defines a path to the CA certificate either relative to
871 /etc/ipsec.d/cacerts or as an absolute path.
872 A value in the form %smartcard[<slot nr>[@<module>]]:<keyid>
873 defines a specific CA certificate to load from a PKCS#11 backend
874 for this CA. See ipsec.secrets(5) for details about smartcard
875 definitions.
876 crluri = <uri>
878 defines a CRL distribution point (ldap, http, or file URI)
879 crluri1
881 synonym for crluri.
882 crluri2 = <uri>
884 defines an alternative CRL distribution point (ldap, http, or
885 file URI)
886 ocspuri = <uri>
889 defines an OCSP URI.
890 ocspuri1
892 synonym for ocspuri.
893 ocspuri2 = <uri>
895 defines an alternative OCSP URI.
896 certuribase = <uri>
898 defines the base URI for the Hash and URL feature sup‐
899 ported by IKEv2. Instead of exchanging complete certifi‐
900 cates, IKEv2 allows one to send an URI that resolves to
901 the DER encoded certificate. The certificate URIs are
902 built by appending the SHA1 hash of the DER encoded cer‐
903 tificates to this base URI.
904
906 At present, the only config section known to the IPsec software
907 is the one named setup, which contains information used when the
908 software is being started. The currently-accepted parameter
909 names in a config setup section are:
910 cachecrls = yes | no
912 if enabled, certificate revocation lists (CRLs) fetched
913 via HTTP or LDAP will be cached in /etc/ipsec.d/crls/
914 under a unique file name derived from the certification
915 authority's public key.
916 charondebug = <debug list>
918 how much charon debugging output should be logged. A
919 comma separated list containing type/level-pairs may be
920 specified, e.g: dmn 3, ike 1, net -1. Acceptable values
921 for types are dmn, mgr, ike, chd, job, cfg, knl, net,
922 asn, enc, lib, esp, tls, tnc, imc, imv, pts and the level
923 is one of -1, 0, 1, 2, 3, 4 (for silent, audit, control,
924 controlmore, raw, private). By default, the level is set
925 to 1 for all types. For more flexibility see LOGGER CON‐
926 FIGURATION in strongswan.conf(5).
927 strictcrlpolicy = yes | ifuri | no
929 defines if a fresh CRL must be available in order for the
930 peer authentication based on RSA signatures to succeed.
931 IKEv2 additionally recognizes ifuri which reverts to yes
932 if at least one CRL URI is defined and to no if no URI is
933 known.
934 uniqueids = yes | no | never | replace | keep
936 whether a particular participant ID should be kept
937 unique, with any new IKE_SA using an ID deemed to replace
938 all old ones using that ID; acceptable values are yes
939 (the default), no and never. Participant IDs normally
940 are unique, so a new IKE_SA using the same ID is almost
941 invariably intended to replace an old one. The difference
942 between no and never is that the daemon will replace old
943 IKE_SAs when receiving an INITIAL_CONTACT notify if the
944 option is no but will ignore these notifies if never is
945 configured. The daemon also accepts the value replace
946 which is identical to yes and the value keep to reject
947 new IKE_SA setups and keep the duplicate established ear‐
948 lier.
949
952 The type and binary encoding of identity strings specified in
953 leftid are detected as follows:
954 · If the string value contains an equal sign (=) it is
956 assumed to be a Distinguished Name, with RDNs separated
957 by commas (,) or slashes (/ - the string must start with
958 a slash to use this syntax). An attempt is made to create
959 a binary ASN.1 encoding from this string. If that fails
960 the type is set to KEY_ID with the literal string value
961 adopted as encoding.
962 · If the string value contains an @ the type depends on the
964 position of that character:
965 · If the string begins with @# the type is set to
967 KEY_ID and the string following that prefix is
968 assumed to be the hex-encoded binary value of the
969 identity.
970 · If the string begins with @@ the type is set to
972 USER_FQDN and the encoding is the literal string
973 after that prefix.
974 · If the string begins with @ the type is set to
976 FQDN and the encoding is the literal string after
977 that prefix.
978 · All remaining strings containing an @ are assumed
980 to be of type USER_FQDN/RFC822 with the literal
981 string value as encoding.
982 · If the value does not contain any @ or = characters it is
984 parsed as follows:
985 · If the value is an empty string, or equals
987 %any[6], 0.0.0.0, ::, or * the type is set to
988 ID_ANY, which matches any other identity.
989 · If the value contains a colon (:) it is assumed to
991 be an IPv6 address. But if parsing the address and
992 converting it to its binary encoding fails the
993 type is set to KEY_ID and the encoding is the lit‐
994 eral value.
995 · For all other strings an attempt at parsing them
997 as IPv4 addresses is made. If that fails the type
998 is set to FQDN and the literal value is adopted as
999 encoding (this is where domain names and simple
1000 names end up).
1001
1004 The IKE SAs and IPsec SAs negotiated by the daemon can be con‐
1005 figured to expire after a specific amount of time. For IPsec SAs
1006 this can also happen after a specified number of transmitted
1007 packets or transmitted bytes. The following settings can be used
1008 to configure this:
1009 Setting Default Setting Default
1011 ──────────────────────────────────────────────────
1012 IKE SA IPsec SA
1013 ikelifetime 3h lifebytes -
1014 lifepackets -
1015 lifetime 1h
1016 Rekeying
1018 IKE SAs as well as IPsec SAs can be rekeyed before they expire.
1019 This can be configured using the following settings:
1020 Setting Default Setting Default
1022 ───────────────────────────────────────────────────
1023 IKE and IPsec SA IPsec SA
1024 margintime 9m marginbytes -
1025 marginpackets -
1026 Randomization
1028 To avoid collisions the specified margins are increased randomly
1029 before subtracting them from the expiration limits (see formula
1030 below). This is controlled by the rekeyfuzz setting:
1031 Setting Default
1033 ──────────────────────
1034 IKE and IPsec SA
1035 rekeyfuzz 100%
1036 Randomization can be disabled by setting rekeyfuzz to 0%.
1038 Formula
1040 The following formula is used to calculate the rekey time of
1041 IPsec SAs:
1042 rekeytime = lifetime - (margintime + random(0, margintime * rekeyfuzz))
1044 It applies equally to IKE SAs and byte and packet limits for
1046 IPsec SAs.
1047 Example
1049 Let's consider the default configuration:
1050 lifetime = 1h
1052 margintime = 9m
1053 rekeyfuzz = 100%
1054 From the formula above follows that the rekey time lies between:
1056 rekeytime_min = 1h - (9m + 9m) = 42m
1058 rekeytime_max = 1h - (9m + 0m) = 51m
1059 Thus, the daemon will attempt to rekey the IPsec SA at a random
1061 time between 42 and 51 minutes after establishing the SA. Or, in
1062 other words, between 9 and 18 minutes before the SA expires.
1063 Notes
1065 · Since the rekeying of an SA needs some time, the margin
1066 values must not be too low.
1067 · The value margin... + margin... * rekeyfuzz must not
1069 exceed the original limit. For example, specifying
1070 margintime = 30m in the default configuration is a bad
1071 idea as there is a chance that the rekey time equals zero
1072 and, thus, rekeying gets disabled.
1073
1076 /etc/ipsec.conf
1077 /etc/ipsec.d/aacerts
1078 /etc/ipsec.d/acerts
1079 /etc/ipsec.d/cacerts
1080 /etc/ipsec.d/certs
1081 /etc/ipsec.d/crls
1082
1085 strongswan.conf(5), ipsec.secrets(5), ipsec(8)
1086
1088 Originally written for the FreeS/WAN project by Henry Spencer.
1089 Updated and extended for the strongSwan project
1090 <http://www.strongswan.org> by Tobias Brunner, Andreas Steffen
1091 and Martin Willi.
10925.7.2 2012-06-26 IPSEC.CONF(5)