1IPSEC.CONF(5)                     strongSwan                     IPSEC.CONF(5)
2
3
4

NAME

6       ipsec.conf - IPsec configuration and connections
7

DESCRIPTION

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
14       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
19       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
26       include ipsec.*.conf
27
28       The intention of the include facility is mostly to permit  keeping  in‐
29       formation  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
37       A section begins with a line of the form:
38
39       type name
40
41       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
47       Lines within the section are generally of the form
48
49            parameter=value
50
51       (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
55       An  empty value stands for the system default value (if any) of the pa‐
56       rameter, i.e. it is roughly equivalent to omitting the  parameter  line
57       entirely.  This  may be useful to clear a setting inherited from a %de‐
58       fault section or via also parameter (see below).  A value  may  contain
59       single  spaces  (additional  white  space is reduced to one space).  To
60       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
68       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
72       There is currently one parameter which is available in any type of sec‐
73       tion:
74
75       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 af‐
80              ter the current section.  Nesting is permitted, and there may be
81              more  than  one also in a single section (parameters from refer‐
82              enced sections are inherited and  overridden  in  the  order  of
83              these also parameters).
84
85       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
89       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

CONN SECTIONS

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
99       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
107       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
117       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
132       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
137       Parameters are optional unless marked '(required)'.
138
139   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
144       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
150       aggressive = yes | no
151              whether to use IKEv1 Aggressive or Main Mode (the default).
152
153       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   integ‐
156              rity[-dhgroup].  For IKEv2, multiple algorithms (separated by -)
157              of the same type can be included in  a  single  proposal.  IKEv1
158              only  includes  the  first algorithm in a proposal.  Only either
159              the ah or esp keyword may be used, AH+ESP bundles are  not  sup‐
160              ported.
161
162              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
167              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
171       also = <name>
172              includes conn section <name>.
173
174       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
181       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
197       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 ig‐
200              nore (the default).  add loads a connection without starting it.
201              route loads a connection and installs kernel traps.  If  traffic
202              is  detected between leftsubnet and rightsubnet, a connection is
203              established.  start loads a connection and brings it up  immedi‐
204              ately.  ignore ignores the connection. This is equal to deleting
205              a connection from the config file.  Relevant only locally, other
206              end need not agree on it.
207
208       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 uniqueids checking, as these events might trigger the defined
213              action when not desired.
214
215       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
224       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 IN‐
227              FORMATIONAL  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
237       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
244       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
250       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
257       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
265       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 in‐
270              cluded in a single proposal. IKEv1 only includes the first algo‐
271              rithm in a proposal.  Only either the ah or esp keyword  may  be
272              used, AH+ESP bundles are not supported.
273
274              Defaults  to  aes128-sha256.   The daemon adds its extensive de‐
275              fault proposal to this default or the configured value.  To  re‐
276              strict  it  to  the  configured proposal an exclamation mark (!)
277              can be added at the end.
278
279              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
286              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  de‐
290              rived  from the IKE_SA's key material. So any DH group specified
291              here will only apply when the CHILD_SA is later  rekeyed  or  is
292              created  with a separate CREATE_CHILD_SA exchange.  Therefore, a
293              proposal mismatch might not immediately be noticed when  the  SA
294              is established, but may later cause rekeying to fail.
295
296              Valid values for esnmode are esn and noesn.  Specifying both ne‐
297              gotiates Extended Sequence Number support with the peer, the de‐
298              fault is noesn.
299
300       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
306       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. Fi‐
315              nally, setting the option to no will disable announcing  support
316              for this feature.
317
318              Note  that fragmented IKE messages sent by a peer are always ac‐
319              cepted irrespective of the value of this option (even  when  set
320              to no).
321
322       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
333              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
338              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 (!, ex‐
341              clamation mark) can be used, e.g: aes256-sha512-modp4096!
342
343       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 bi‐
346              nary encoded string defining the Codepoint to set, as defined in
347              RFC 2474.
348
349       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 be‐
352              low.
353
354       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  de‐
359              fault) and no.
360
361       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
366       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
372       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 de‐
375              fault) for the local endpoint signifies an address to be  filled
376              in  (by  automatic keying) during negotiation. If the local peer
377              initiates the connection setup the routing table will be queried
378              to  determine  the  correct local IP address.  In case the local
379              peer is responding to a connection setup  then  any  IP  address
380              that is assigned to a local interface will be accepted.
381
382              The  prefix % in front of a fully-qualified domain name or an IP
383              address will implicitly set leftallowany=yes.
384
385              If %any is used for the remote endpoint it literally  means  any
386              IP address.
387
388              If an FQDN is assigned it is resolved every time a configuration
389              lookup is done. If DNS resolution times out, the lookup  is  de‐
390              layed for that time.
391
392              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 re‐
397              quired.
398
399              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
403       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
407       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
415              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 ac‐
418              ceptable  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
428              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  al‐
436              gorithm  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
442              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
447              For eap, an optional EAP method can be appended.  Currently  de‐
448              fined  methods are eap-aka, eap-gtc, eap-md5, eap-mschapv2, eap-
449              peap, eap-sim, eap-tls, eap-ttls, eap-dynamic,  and  eap-radius.
450              Alternatively,  IANA  assigned  EAP method numbers are accepted.
451              Vendor specific EAP methods are defined in  the  form  eap-type-
452              vendor (e.g. eap-7-12345).  To specify signature and trust chain
453              constraints for EAP-(T)TLS, append a colon to  the  EAP  method,
454              followed  by  the  key type/size and hash algorithm as discussed
455              above. For xauth, an XAuth authentication backend can be  speci‐
456              fied,  such  as xauth-generic or xauth-eap.  If XAuth is used in
457              leftauth, Hybrid authentication is used. For  traditional  XAuth
458              authentication, define XAuth in lefauth2.
459
460       leftauth2 = <auth method>
461              Same  as  leftauth, but defines an additional authentication ex‐
462              change. In IKEv1, only XAuth can be used in the second authenti‐
463              cation  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
468       leftca = <issuer dn> | %same
469              the distinguished name of a certificate authority which  is  re‐
470              quired  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
475       leftca2 = <issuer dn> | %same
476              Same as leftca, but for the second authentication  round  (IKEv2
477              only).
478
479       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> de‐
488              fines a specific certificate to load from a PKCS#11 backend  for
489              this  connection.  See ipsec.secrets(5) for details about smart‐
490              card definitions.  leftcert is required only  if  selecting  the
491              certificate with leftid is not sufficient, for example if multi‐
492              ple 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
498       leftcert2 = <path>
499              Same as leftcert, but for the second authentication round (IKEv2
500              only).
501
502       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
507       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 ad‐
512              dresses are allowed and  define  DNS  servers  assigned  to  the
513              client.
514
515       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
525              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
533              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
537       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
542       leftgroups2 = <group list>
543              Same as leftgroups, but for the second authentication round  de‐
544              fined with leftauth2.
545
546       lefthostaccess = yes | no
547              inserts  a pair of INPUT and OUTPUT iptables rules using the de‐
548              fault ipsec _updown script, thus allowing access to the host it‐
549              self  in the case where the host's internal interface is part of
550              the negotiated client subnet.  Acceptable values are yes and  no
551              (the default).
552
553       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
559              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
565              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
585              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
594       leftid2 = <id>
595              identity to use for a second authentication for the left partic‐
596              ipant (IKEv2 only); defaults to leftid.
597
598       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
605       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
610       leftsigkey = <raw public key> | <path to public key>
611              the left participant's public key for public key  signature  au‐
612              thentication,  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 ac‐
619              cepted.
620
621       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
626       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  re‐
632              quested  explicitly.  If an IP address is configured, it will be
633              requested from the responder, which is free to  respond  with  a
634              different address.
635
636       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
645       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
660              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
664              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  ei‐
666              ther  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
669              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
674              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  in‐
678              stead.
679
680              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
686
687       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
697       lifebytes = <number>
698              the number of bytes transmitted over an IPsec SA before  it  ex‐
699              pires.
700
701       lifepackets = <number>
702              the number of packets transmitted over an IPsec SA before it ex‐
703              pires.
704
705       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 su‐
715              perseded  connections  on  the  end which thinks the lifetime is
716              longer. Also see EXPIRY/REKEY below.
717
718       marginbytes = <number>
719              how many bytes before IPsec SA expiry (see lifebytes) should at‐
720              tempts to negotiate a replacement begin.
721
722       marginpackets = <number>
723              how many packets before IPsec SA expiry (see lifepackets) should
724              attempts to negotiate a replacement begin.
725
726       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
732       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
740       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
744       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
748       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
754       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
760       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
767       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
776       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
787       replay_window = -1 | <number>
788              The IPsec replay window size for this connection. With  the  de‐
789              fault  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 re‐
792              play protection.
793
794       reqid = <number>
795              sets the reqid for a given connection to a pre-configured  fixed
796              value.
797
798       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
806       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
812       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
821       xauth = client | server
822              specifies  the  role  in  the XAuth protocol if activated by au‐
823              thby=xauthpsk or authby=xauthrsasig.  Accepted values are server
824              and client (the default).
825
826       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
831
832   CONN PARAMETERS: IKEv2 MEDIATION EXTENSION
833       The  following parameters are relevant to IKEv2 Mediation Extension op‐
834       eration only.
835
836       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
842       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  me‐
845              diation  connection.   The  mediation connection must set media‐
846              tion=yes.
847
848       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
855

CA SECTIONS

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 as‐
861       sign special parameters (like a CRL) to a CA.
862
863       also = <name>
864              includes ca section <name>.
865
866       auto = ignore | add
867              currently can have either the value ignore (the default) or add.
868
869       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> de‐
873              fines 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
877       crluri = <uri>
878              defines a CRL distribution point (ldap, http, or file URI)
879
880       crluri1
881              synonym for crluri.
882
883       crluri2 = <uri>
884              defines an alternative CRL distribution point  (ldap,  http,  or
885              file URI)
886
887
888       ocspuri = <uri>
889              defines an OCSP URI.
890
891       ocspuri1
892              synonym for ocspuri.
893
894       ocspuri2 = <uri>
895              defines an alternative OCSP URI.
896
897       certuribase = <uri>
898              defines  the  base URI for the Hash and URL feature supported by
899              IKEv2.  Instead of exchanging complete certificates,  IKEv2  al‐
900              lows  one  to  send an URI that resolves to the DER encoded cer‐
901              tificate. The certificate URIs are built by appending  the  SHA1
902              hash of the DER encoded certificates to this base URI.
903

CONFIG SECTIONS

905       At  present, the only config section known to the IPsec software is the
906       one named setup, which contains information used when the  software  is
907       being  started.   The  currently-accepted  parameter  names in a config
908       setup section are:
909
910       cachecrls = yes | no
911              if enabled, certificate revocation lists (CRLs) fetched via HTTP
912              or LDAP will be cached in /etc/ipsec.d/crls/ under a unique file
913              name derived from the certification authority's public key.
914
915       charondebug = <debug list>
916              how much charon debugging output should be logged.  A comma sep‐
917              arated  list  containing type/level-pairs may be specified, e.g:
918              dmn 3, ike 1, net -1.  Acceptable values for types are dmn, mgr,
919              ike, chd, job, cfg, knl, net, asn, enc, lib, esp, tls, tnc, imc,
920              imv, pts and the level is one of -1, 0, 1, 2, 3, 4 (for  silent,
921              audit,  control,  controlmore,  raw,  private).  By default, the
922              level is set to 1 for all types.  For more flexibility see  LOG‐
923              GER CONFIGURATION in strongswan.conf(5).
924
925       strictcrlpolicy = yes | ifuri | no
926              defines  if  a fresh CRL must be available in order for the peer
927              authentication based on RSA signatures to succeed.  IKEv2  addi‐
928              tionally  recognizes  ifuri which reverts to yes if at least one
929              CRL URI is defined and to no if no URI is known.
930
931       uniqueids = yes | no | never | replace | keep
932              whether a particular participant ID should be kept unique,  with
933              any  new IKE_SA using an ID deemed to replace all old ones using
934              that ID; acceptable values are yes (the default), no and  never.
935              Participant  IDs  normally are unique, so a new IKE_SA using the
936              same ID is almost invariably intended to replace an old one. The
937              difference  between no and never is that the daemon will replace
938              old IKE_SAs when receiving an INITIAL_CONTACT notify if the  op‐
939              tion  is  no  but will ignore these notifies if never is config‐
940              ured.  The daemon also accepts the value replace which is  iden‐
941              tical  to yes and the value keep to reject new IKE_SA setups and
942              keep the duplicate established earlier.
943
944

IDENTITY PARSING

946       The type and binary encoding of identity strings  specified  in  leftid
947       are detected as follows:
948
949       •      If  the string value contains an equal sign (=) it is assumed to
950              be a Distinguished Name, with RDNs separated by  commas  (,)  or
951              slashes (/ - the string must start with a slash to use this syn‐
952              tax). An attempt is made to create a binary ASN.1 encoding  from
953              this  string.  If  that fails the type is set to KEY_ID with the
954              literal string value adopted as encoding.
955
956       •      If the string value contains an @ the type depends on the  posi‐
957              tion of that character:
958
959              •      If  the  string  begins with @# the type is set to KEY_ID
960                     and the string following that prefix is assumed to be the
961                     hex-encoded binary value of the identity.
962
963              •      If the string begins with @@ the type is set to USER_FQDN
964                     and the encoding is the literal string after that prefix.
965
966              •      If the string begins with @ the type is set to  FQDN  and
967                     the encoding is the literal string after that prefix.
968
969              •      All  remaining  strings containing an @ are assumed to be
970                     of type USER_FQDN/RFC822 with the literal string value as
971                     encoding.
972
973       •      If the value does not contain any @ or = characters it is parsed
974              as follows:
975
976              •      If the value is  an  empty  string,  or  equals  %any[6],
977                     0.0.0.0,  ::,  or  *  the  type  is  set to ID_ANY, which
978                     matches any other identity.
979
980              •      If the value contains a colon (:) it is assumed to be  an
981                     IPv6  address.  But if parsing the address and converting
982                     it to its binary encoding fails the type is set to KEY_ID
983                     and the encoding is the literal value.
984
985              •      For  all other strings an attempt at parsing them as IPv4
986                     addresses is made. If that fails the type is set to  FQDN
987                     and  the  literal  value  is adopted as encoding (this is
988                     where domain names and simple names end up).
989
990

SA EXPIRY/REKEY

992       The IKE SAs and IPsec SAs negotiated by the daemon can be configured to
993       expire  after  a  specific  amount of time. For IPsec SAs this can also
994       happen after a specified number of transmitted packets  or  transmitted
995       bytes. The following settings can be used to configure this:
996
997       Setting         Default   Setting         Default
998       ──────────────────────────────────────────────────
999       IKE SA                    IPsec SA
1000        ikelifetime         3h    lifebytes            -
1001                                  lifepackets          -
1002                                  lifetime            1h
1003
1004   Rekeying
1005       IKE  SAs  as  well as IPsec SAs can be rekeyed before they expire. This
1006       can be configured using the following settings:
1007
1008       Setting        Default   Setting           Default
1009       ───────────────────────────────────────────────────
1010       IKE and IPsec SA         IPsec SA
1011        margintime         9m    marginbytes            -
1012                                 marginpackets          -
1013
1014   Randomization
1015       To avoid collisions the specified margins are increased randomly before
1016       subtracting  them  from the expiration limits (see formula below). This
1017       is controlled by the rekeyfuzz setting:
1018
1019       Setting       Default
1020       ──────────────────────
1021       IKE and IPsec SA
1022        rekeyfuzz       100%
1023
1024       Randomization can be disabled by setting rekeyfuzz to 0%.
1025
1026   Formula
1027       The following formula is used to calculate the rekey time of IPsec SAs:
1028
1029        rekeytime = lifetime - (margintime + random(0, margintime * rekeyfuzz))
1030
1031       It applies equally to IKE SAs and byte and packet limits for IPsec SAs.
1032
1033   Example
1034       Let's consider the default configuration:
1035
1036                  lifetime = 1h
1037                  margintime = 9m
1038                  rekeyfuzz = 100%
1039
1040       From the formula above follows that the rekey time lies between:
1041
1042                  rekeytime_min = 1h - (9m + 9m) = 42m
1043                  rekeytime_max = 1h - (9m + 0m) = 51m
1044
1045       Thus, the daemon will attempt to rekey the IPsec SA at  a  random  time
1046       between  42  and  51  minutes  after  establishing the SA. Or, in other
1047       words, between 9 and 18 minutes before the SA expires.
1048
1049   Notes
1050       •      Since the rekeying of an SA needs some time, the  margin  values
1051              must not be too low.
1052
1053       •      The  value margin... + margin... * rekeyfuzz must not exceed the
1054              original limit. For example, specifying margintime = 30m in  the
1055              default  configuration  is  a bad idea as there is a chance that
1056              the rekey time equals zero and, thus, rekeying gets disabled.
1057
1058

FILES

1060       /etc/ipsec.conf
1061       /etc/ipsec.d/aacerts
1062       /etc/ipsec.d/acerts
1063       /etc/ipsec.d/cacerts
1064       /etc/ipsec.d/certs
1065       /etc/ipsec.d/crls
1066
1067

SEE ALSO

1069       strongswan.conf(5), ipsec.secrets(5), ipsec(8)
1070

HISTORY

1072       Originally written for the FreeS/WAN project by Henry Spencer.  Updated
1073       and  extended for the strongSwan project <http://www.strongswan.org> by
1074       Tobias Brunner, Andreas Steffen and Martin Willi.
1075
1076
1077
10785.9.4                             2012-06-26                     IPSEC.CONF(5)
Impressum