Provided by: strongswan-starter_5.8.2-1ubuntu3.6_amd64 bug

NAME

       ipsec.conf - IPsec configuration and connections

DESCRIPTION

       The  optional ipsec.conf file specifies most configuration and control information for the
       strongSwan IPsec subsystem.  The  major  exception  is  secrets  for  authentication;  see
       ipsec.secrets(5).  Its contents are not security-sensitive.

       The  file  is  a text file, consisting of one or more sections.  White space followed by #
       followed by anything to the end of the line is a comment and  is  ignored,  as  are  empty
       lines which are not within a section.

       A  line  which  contains include and a file name, separated by white space, is replaced by
       the contents of that file.  If the file name is not a full pathname, it is  considered  to
       be  relative  to  the  directory  containing  the  including file.  Such inclusions can be
       nested.  Only a single filename may be supplied, and it may not contain white  space,  but
       it may include shell wildcards (see sh(1)); for example:

       include ipsec.*.conf

       The  intention  of  the  include  facility  is  mostly  to  permit  keeping information on
       connections, or sets of connections, separate from  the  main  configuration  file.   This
       permits  such connection descriptions to be changed, copied to the other security gateways
       involved, etc., without having to constantly extract them from the configuration file  and
       then  insert  them  back  into  it.   Note also the also parameter (described below) which
       permits splitting a single logical section (e.g. a connection  description)  into  several
       actual sections.

       A section begins with a line of the form:

       type name

       where  type  indicates  what  type of section follows, and name is an arbitrary name which
       distinguishes the section from others of the same type.  All  subsequent  non-empty  lines
       which  begin  with  white  space  are part of the section.  Sections of the same type that
       share the same name are merged.

       Lines within the section are generally of the form

            parameter=value

       (note the mandatory preceding white space).  There can be white space on  either  side  of
       the =.  Parameter names are specific to a section type.

       An  empty  value stands for the system default value (if any) of the parameter, i.e. it is
       roughly equivalent to omitting the parameter line entirely. This may be useful to clear  a
       setting  inherited from a %default section or via also parameter (see below).  A value may
       contain single spaces (additional white space is reduced to one space).  To preserve white
       space  as  written  enclose  the  entire value in double quotes ("); in such values double
       quotes themselves may be escaped by prefixing them  with  \  characters.  A  double-quoted
       string  may  span  multiple  lines by ending them with \ characters (following lines don't
       have to begin with white space, as that will be preserved).  Additionally,  the  following
       control characters may be encoded in double-quoted strings: \n, \r, \t, \b, \f.

       Numeric  values  are  specified  to  be  either an ``integer'' (a sequence of digits) or a
       ``decimal number'' (sequence of digits optionally followed by `.' and another sequence  of
       digits).

       There is currently one parameter which is available in any type of section:

       also   the  value  is  a section name; the parameters of that section are inherited by the
              current section. Parameters  in  the  current  section  always  override  inherited
              parameters,  even  if an also follows after them.  The specified section must exist
              and must have the same section type; it doesn't if it is defined  before  or  after
              the  current section.  Nesting is permitted, and there may be more than one also in
              a single section (parameters from referenced sections are inherited and  overridden
              in the order of these also parameters).

       A  section  with  name  %default  specifies  defaults  for  sections of the same type. All
       parameters in it, are inherited by all other sections of that type.

       Currently  there  are  three  types  of  sections:  a  config  section  specifies  general
       configuration information for IPsec, a conn section specifies an IPsec connection, while a
       ca section specifies special properties of a certification authority.

CONN SECTIONS

       A conn section contains a connection specification, defining a network  connection  to  be
       made  using  IPsec.   The name given is arbitrary, and is used to identify the connection.
       Here's a simple example:

       conn snt
           left=192.168.0.1
           leftsubnet=10.1.0.0/16
           right=192.168.0.2
           rightsubnet=10.1.0.0/16
           keyingtries=%forever
           auto=add

       A note on terminology: There are two kinds of communications  going  on:  transmission  of
       user  IP  packets,  and  gateway-to-gateway negotiations for keying, rekeying, and general
       control.  The path to control the connection is called 'ISAKMP SA' in IKEv1 and  'IKE  SA'
       in  the  IKEv2  protocol.  That  what  is being negotiated, the kernel level data path, is
       called 'IPsec SA' or 'Child SA'.  strongSwan previously used two separate keying  daemons,
       pluto and charon. This manual does not discuss pluto options anymore, but only charon that
       since strongSwan 5.0 supports both IKEv1 and IKEv2.

       To avoid trivial editing of the configuration file to suit it to each system involved in a
       connection, connection specifications are written in terms of left and right participants,
       rather than in terms of local and remote.  Which participant is considered left  or  right
       is  arbitrary;  for  every connection description an attempt is made to figure out whether
       the local endpoint should act as the left or right endpoint. This is done by matching  the
       IP  addresses  defined  for both endpoints with the IP addresses assigned to local network
       interfaces. If a match is found then the role (left or right) that matches is going to  be
       considered  local.   If  no match is found during startup, left is considered local.  This
       permits using identical connection specifications on both ends.   There  are  cases  where
       there  is  no  symmetry; a good convention is to use left for the local side and right for
       the remote side (the first letters are a good mnemonic).

       Many of the parameters relate to one participant or the other; only the ones for left  are
       listed  here,  but  every  parameter  whose name begins with left has a right counterpart,
       whose description is the same but with left and right reversed.

       Parameters are optional unless marked '(required)'.

   CONN PARAMETERS
       Unless otherwise noted, for a connection to work, in general it is necessary for  the  two
       ends to agree exactly on the values of these parameters.

       aaa_identity = <id>
              defines the identity of the AAA backend used during IKEv2 EAP authentication.  This
              is required if the EAP client uses a method that verifies the server identity (such
              as EAP-TLS), but it does not match the IKEv2 gateway identity.

       aggressive = yes | no
              whether to use IKEv1 Aggressive or Main Mode (the default).

       ah = <cipher suites>
              comma-separated  list  of  AH  algorithms  to  be  used  for  the  connection, e.g.
              sha1-sha256-modp1024.  The notation is integrity[-dhgroup].   For  IKEv2,  multiple
              algorithms  (separated by -) of the same type can be included in a single proposal.
              IKEv1 only includes the first algorithm in a proposal.  Only either the ah  or  esp
              keyword may be used, AH+ESP bundles are not supported.

              There  is no default AH cipher suite since by default ESP is used.  The daemon adds
              its extensive default proposal to the configured  value.  To  restrict  it  to  the
              configured proposal an exclamation mark (!)  can be added at the end.

              If dh-group is specified, CHILD_SA/Quick Mode setup and rekeying include a separate
              Diffie-Hellman exchange (refer to the esp keyword for details).

       also = <name>
              includes conn section <name>.

       auth = <value>
              was used by the pluto IKEv1 daemon to use AH integrity protection for ESP encrypted
              packets, but is not supported in charon. The ah keyword specifies algorithms to use
              for integrity protection with AH, but without encryption. AH+ESP  bundles  are  not
              supported.

       authby = pubkey | rsasig | ecdsasig | psk | secret | never | xauthpsk | xauthrsasig
              how the two security gateways should authenticate each other; acceptable values are
              psk or  secret  for  pre-shared  secrets,  pubkey  (the  default)  for  public  key
              signatures  as  well as the synonyms rsasig for RSA digital signatures and ecdsasig
              for Elliptic Curve DSA signatures.  never can be used if negotiation is never to be
              attempted  or  accepted  (useful  for  shunt-only  conns).   Digital signatures are
              superior in every way to shared secrets.  IKEv1 additionally  supports  the  values
              xauthpsk  and  xauthrsasig  that  will  enable  eXtended  AUTHentication (XAUTH) in
              addition to IKEv1 main mode based on shared  secrets  or  digital  RSA  signatures,
              respectively.   This  parameter is deprecated, as two peers do not need to agree on
              an authentication method in IKEv2. Use the leftauth  parameter  instead  to  define
              authentication methods.

       auto = ignore | add | route | start
              what  operation,  if any, should be done automatically at IPsec startup; currently-
              accepted values are add, route, start  and  ignore  (the  default).   add  loads  a
              connection  without  starting  it.   route  loads  a connection and installs kernel
              traps. If traffic is detected between leftsubnet and rightsubnet, a  connection  is
              established.   start  loads  a  connection  and  brings  it up immediately.  ignore
              ignores the connection. This is equal to deleting  a  connection  from  the  config
              file.  Relevant only locally, other end need not agree on it.

       closeaction = none | clear | hold | restart
              defines  the  action to take if the remote peer unexpectedly closes a CHILD_SA (see
              dpdaction for meaning of values).  A closeaction should not be  used  if  the  peer
              uses  reauthentication  or  uniqueids  checking,  as these events might trigger the
              defined action when not desired.

       compress = yes | no
              whether IPComp compression of content is proposed  on  the  connection  (link-level
              compression  does  not work on encrypted data, so to be effective, compression must
              be done before encryption); acceptable values are yes and no (the default). A value
              of  yes  causes  the daemon to propose both compressed and uncompressed, and prefer
              compressed.  A value  of  no  prevents  the  daemon  from  proposing  or  accepting
              compression.

       dpdaction = none | clear | hold | restart
              controls  the  use  of  the  Dead  Peer  Detection  protocol  (DPD, RFC 3706) where
              R_U_THERE notification messages (IKEv1) or empty INFORMATIONAL messages (IKEv2) are
              periodically  sent  in  order to check the liveliness of the IPsec peer. The values
              clear, hold, and restart all activate DPD and determine the action to perform on  a
              timeout.  With  clear the connection is closed with no further actions taken.  hold
              installs a trap policy, which will catch matching traffic and tries to re-negotiate
              the  connection  on  demand.   restart  will  immediately trigger an attempt to re-
              negotiation the connection.  The default is none which disables the active  sending
              of DPD messages.

       dpddelay = 30s | <time>
              defines  the  period  time  interval  with  which  R_U_THERE messages/INFORMATIONAL
              exchanges are sent to the peer.  These  are  only  sent  if  no  other  traffic  is
              received.  In  IKEv2,  a  value of 0 sends no additional INFORMATIONAL messages and
              uses only standard messages (such as those to rekey) to detect dead peers.

       dpdtimeout = 150s | <time>
              defines the timeout interval, after which all connections to a peer are deleted  in
              case of inactivity. This only applies to IKEv1, in IKEv2 the default retransmission
              timeout applies, as every exchange is used to detect dead peers.

       inactivity = <time>
              defines the timeout interval, after which a CHILD_SA is closed if it did  not  send
              or  receive  any traffic. The inactivity counter is reset during CHILD_SA rekeying.
              This means that the inactivity timeout must be smaller than the  rekeying  interval
              to have any effect.

       eap_identity = <id>
              defines  the  identity  the  client  uses  to reply to an EAP Identity request.  If
              defined on the EAP server, the defined identity  will  be  used  as  peer  identity
              during EAP authentication. The special value %identity uses the EAP Identity method
              to ask the client for an EAP identity. If not defined, the IKEv2 identity  will  be
              used as EAP identity.

       esp = <cipher suites>
              comma-separated list of ESP encryption/authentication algorithms to be used for the
              connection,    e.g.     aes128-sha256.      The     notation     is     encryption-
              integrity[-dhgroup][-esnmode].   For IKEv2, multiple algorithms (separated by -) of
              the same type can be included in a single proposal. IKEv1 only includes  the  first
              algorithm  in  a  proposal.   Only either the ah or esp keyword may be used, AH+ESP
              bundles are not supported.

              Defaults to aes128-sha256.  The daemon adds its extensive default proposal to  this
              default  or  the  configured  value.   To restrict it to the configured proposal an
              exclamation mark (!)  can be added at the end.

              Note: As a responder,  the  daemon  defaults  to  selecting  the  first  configured
              proposal   that's   also   supported   by   the  peer.  This  may  be  changed  via
              strongswan.conf(5) to selecting the first acceptable  proposal  sent  by  the  peer
              instead.  In  order  to restrict a responder to only accept specific cipher suites,
              the strict flag (!, exclamation mark) can be used, e.g: aes256-sha512-modp4096!

              If dh-group is specified, CHILD_SA/Quick Mode rekeying and initial negotiation  use
              a  separate  Diffie-Hellman exchange using the specified group. However, for IKEv2,
              the keys of the CHILD_SA created implicitly with the IKE_SA will always be  derived
              from the IKE_SA's key material. So any DH group specified here will only apply when
              the CHILD_SA is later  rekeyed  or  is  created  with  a  separate  CREATE_CHILD_SA
              exchange.  Therefore, a proposal mismatch might not immediately be noticed when the
              SA is established, but may later cause rekeying to fail.

              Valid values for esnmode are esn and noesn.  Specifying  both  negotiates  Extended
              Sequence Number support with the peer, the default is noesn.

       forceencaps = yes | no
              force UDP encapsulation for ESP packets even if no NAT situation is detected.  This
              may help to  surmount  restrictive  firewalls.  In  order  to  force  the  peer  to
              encapsulate packets, NAT detection payloads are faked.

       fragmentation = yes  | accept | force | no
              whether   to   use   IKE   fragmentation  (proprietary  IKEv1  extension  or  IKEv2
              fragmentation as per RFC 7383).  Acceptable values are yes (the  default),  accept,
              force and no.  If set to yes, and the peer supports it, oversized IKE messages will
              be sent in fragments. If set to accept, support for fragmentation is  announced  to
              the  peer  but  the  daemon  does not send its own messages in fragments. If set to
              force (only supported for IKEv1) the initial IKE message will already be fragmented
              if  required. Finally, setting the option to no will disable announcing support for
              this feature.

              Note that fragmented IKE messages sent by a peer are always  accepted  irrespective
              of the value of this option (even when set to no).

       ike = <cipher suites>
              comma-separated  list  of  IKE/ISAKMP SA encryption/authentication algorithms to be
              used,    e.g.     aes128-sha256-modp3072.     The    notation    is     encryption-
              integrity[-prf]-dhgroup.   If no PRF is given, the algorithms defined for integrity
              are used for the PRF.  The prf keywords are the same as the  integrity  algorithms,
              but have a prf prefix (such as prfsha1, prfsha256 or prfaesxcbc).
              In   IKEv2,   multiple   algorithms   and   proposals  may  be  included,  such  as
              aes128-aes256-sha1-modp3072-modp2048,3des-sha1-md5-modp1024.

              Defaults to aes128-sha256-modp3072.  The daemon adds its extensive default proposal
              to this default or the configured value.  To restrict it to the configured proposal
              an exclamation mark (!)  can be added at the end.

              Note: As a responder the daemon accepts the first supported proposal received  from
              the  peer.  In order to restrict a responder to only accept specific cipher suites,
              the strict flag (!, exclamation mark) can be used, e.g: aes256-sha512-modp4096!

       ikedscp = 000000 | <DSCP field>
              Differentiated Services Field Codepoint to set on outgoing IKE  packets  sent  from
              this  connection.  The  value  is  a  six  digit binary encoded string defining the
              Codepoint to set, as defined in RFC 2474.

       ikelifetime = 3h | <time>
              how long the keying channel of a connection (ISAKMP or IKE SA) should  last  before
              being renegotiated. Also see EXPIRY/REKEY below.

       installpolicy = yes | no
              decides whether IPsec policies are installed in the kernel by the charon daemon for
              a given connection. Allows peaceful cooperation e.g. with the  Mobile  IPv6  daemon
              mip6d  who  wants  to  control the kernel policies.  Acceptable values are yes (the
              default) and no.

       keyexchange = ike | ikev1 | ikev2
              which key exchange protocol should be used to initiate the connection.  Connections
              marked  with  ike  use  IKEv2 when initiating, but accept any protocol version when
              responding.

       keyingtries = 3 | <number> | %forever
              how many attempts (a whole number or  %forever)  should  be  made  to  negotiate  a
              connection,  or  a  replacement  for  one, before giving up (default 3).  The value
              %forever means 'never give up'.  Relevant only locally, other end need not agree on
              it.

       left = <ip address> | <fqdn> | %any | <range> | <subnet>
              The IP address of the left participant's public-network interface or one of several
              magic values.  The value %any (the default) for the  local  endpoint  signifies  an
              address to be filled in (by automatic keying) during negotiation. If the local peer
              initiates the connection setup the routing table will be queried to  determine  the
              correct  local  IP  address.   In case the local peer is responding to a connection
              setup then any IP address that is assigned to a local interface will be accepted.

              The prefix % in front of a fully-qualified  domain  name  or  an  IP  address  will
              implicitly set leftallowany=yes.

              If %any is used for the remote endpoint it literally means any IP address.

              If an FQDN is assigned it is resolved every time a configuration lookup is done. If
              DNS resolution times out, the lookup is delayed for that time.

              To  limit  the  connection  to  a    specific   range   of   hosts,   a   range   (
              10.1.0.0-10.2.255.255  ) or a subnet ( 10.1.0.0/16 ) can be specified, and multiple
              addresses, ranges and subnets can be separated by  commas.  While  one  can  freely
              combine  these  items,  to initiate the connection at least one non-range/subnet is
              required.

              Please note that with the usage of wildcards multiple connection descriptions might
              match a given incoming connection attempt. The most specific description is used in
              that case.

       leftallowany = yes | no
              a modifier for left, making it behave as %any although a  concrete  IP  address  or
              domain name has been assigned.

       leftauth = <auth method>
              Authentication  method  to  use  locally  (left) or require from the remote (right)
              side.  Acceptable values are pubkey for public key authentication (RSA/ECDSA),  psk
              for  pre-shared  key  authentication,  eap  to  (require the) use of the Extensible
              Authentication Protocol in IKEv2, and xauth for IKEv1 eXtended Authentication.

              To require a trustchain public key strength for the remote side,  specify  the  key
              type   followed  by  the  minimum  strength  in  bits  (for  example  ecdsa-384  or
              rsa-2048-ecdsa-256).  To  limit  the  acceptable  set  of  hashing  algorithms  for
              trustchain  validation,  append  hash  algorithms  to  pubkey  or  a  key  strength
              definition (for  example  pubkey-sha256-sha512,  rsa-2048-sha256-sha384-sha512,  or
              rsa-2048-sha256-ecdsa-256-sha256-sha384).   Unless  disabled in strongswan.conf(5),
              or explicit IKEv2 signature constraints are configured (see below), such key  types
              and  hash  algorithms  are  also  applied  as  constraints  against IKEv2 signature
              authentication schemes used by the remote side.

              If both peers support RFC 7427 ("Signature Authentication in IKEv2") specific  hash
              algorithms to be used during IKEv2 authentication may be configured.  The syntax is
              the same as above, but with ike: prefix. For example, with ike:pubkey-sha384-sha256
              a  public  key  signature  scheme with either SHA-384 or SHA-256 would get used for
              authentication, in that order and depending on the hash algorithms supported by the
              peer.   If  no specific hash algorithms are configured, the default is to prefer an
              algorithm that matches or exceeds  the  strength  of  the  signature  key.   If  no
              constraints  with  ike:  prefix  are  configured  any  signature  scheme constraint
              (without ike: prefix) will also apply  to  IKEv2  authentication,  unless  this  is
              disabled in strongswan.conf(5).

              To  use  or  require  RSASSA-PSS  signatures  use rsa/pss instead of rsa as in e.g.
              ike:rsa/pss-sha256.   If  pubkey  or  rsa  constraints  are  configured  RSASSA-PSS
              signatures will only be used/accepted if enabled in strongswan.conf(5).

              For eap, an optional EAP method can be appended. Currently defined methods are eap-
              aka, eap-gtc, eap-md5, eap-mschapv2, eap-peap,  eap-sim,  eap-tls,  eap-ttls,  eap-
              dynamic,  and  eap-radius.   Alternatively,  IANA  assigned  EAP method numbers are
              accepted. Vendor specific EAP methods are defined in the form eap-type-vendor (e.g.
              eap-7-12345).   To  specify  signature  and trust chain constraints for EAP-(T)TLS,
              append a colon to the EAP method, followed by the key type/size and hash  algorithm
              as  discussed  above.  For xauth, an XAuth authentication backend can be specified,
              such as  xauth-generic  or  xauth-eap.   If  XAuth  is  used  in  leftauth,  Hybrid
              authentication  is  used.  For  traditional  XAuth  authentication, define XAuth in
              lefauth2.

       leftauth2 = <auth method>
              Same as leftauth, but defines an additional authentication exchange. In IKEv1, only
              XAuth  can  be  used  in  the  second authentication round. IKEv2 supports multiple
              complete authentication rounds using "Multiple Authentication Exchanges" defined in
              RFC 4739. This allows, for example, separated authentication of host and user.

       leftca = <issuer dn> | %same
              the  distinguished  name of a certificate authority which is required to lie in the
              trust  path  going  from  the  left  participant's  certificate  up  to  the   root
              certification  authority.   %same  means  that  the  value configured for the right
              participant should be reused.

       leftca2 = <issuer dn> | %same
              Same as leftca, but for the second authentication round (IKEv2 only).

       leftcert = <path>
              the path to the left participant's X.509  certificate.  The  file  can  be  encoded
              either  in  PEM  or  DER  format. OpenPGP certificates are supported as well.  Both
              absolute paths or paths relative to /etc/ipsec.d/certs  are  accepted.  By  default
              leftcert  sets  leftid to the distinguished name of the certificate's subject.  The
              left participant's ID can be overridden by specifying a leftid value which must  be
              certified by the certificate, though.
              A  value  in  the  form %smartcard[<slot nr>[@<module>]]:<keyid> defines a specific
              certificate  to  load  from  a   PKCS#11   backend   for   this   connection.   See
              ipsec.secrets(5)  for  details  about  smartcard definitions.  leftcert is required
              only if selecting the certificate with leftid is not  sufficient,  for  example  if
              multiple certificates use the same subject.
              Multiple  certificate  paths  or  PKCS#11  backends  can  be  specified  in a comma
              separated  list.  The  daemon  chooses  the  certificate  based  on  the   received
              certificate requests if possible before enforcing the first.

       leftcert2 = <path>
              Same as leftcert, but for the second authentication round (IKEv2 only).

       leftcertpolicy = <OIDs>
              Comma  separated  list of certificate policy OIDs the peer's certificate must have.
              OIDs are specified using the numerical dotted representation.

       leftdns = <servers>
              Comma  separated  list  of  DNS  server  addresses  to  exchange  as  configuration
              attributes.   On  the  initiator,  a  server  is  a  fixed  IPv4/IPv6  address,  or
              %config4/%config6 to request attributes without an address. On the responder,  only
              fixed  IPv4/IPv6  addresses  are  allowed  and  define  DNS servers assigned to the
              client.

       leftfirewall = yes | no
              whether  the  left   participant   is   doing   forwarding-firewalling   (including
              masquerading)  using  iptables  for traffic from leftsubnet, which should be turned
              off (for  traffic  to  the  other  subnet)  once  the  connection  is  established;
              acceptable  values  are  yes  and  no  (the  default).  May not be used in the same
              connection description with leftupdown.  Implemented as a parameter to the  default
              ipsec  _updown script.  See notes below.  Relevant only locally, other end need not
              agree on it.

              If one or  both  security  gateways  are  doing  forwarding  firewalling  (possibly
              including  masquerading),  and  this  is  specified  using the firewall parameters,
              tunnels established with IPsec are exempted  from  it  so  that  packets  can  flow
              unchanged  through  the  tunnels.   (This  means that all subnets connected in this
              manner must have distinct, non-overlapping subnet address blocks.)  This is done by
              the default ipsec _updown script.

              In situations calling for more control, it may be preferable for the user to supply
              his own updown script, which makes the appropriate adjustments for his system.

       leftgroups = <group list>
              a comma separated list of group names. If the leftgroups parameter is present  then
              the peer must be a member of at least one of the groups defined by the parameter.

       leftgroups2 = <group list>
              Same as leftgroups, but for the second authentication round defined with leftauth2.

       lefthostaccess = yes | no
              inserts  a  pair of INPUT and OUTPUT iptables rules using the default ipsec _updown
              script, thus allowing access to the host  itself  in  the  case  where  the  host's
              internal  interface is part of the negotiated client subnet.  Acceptable values are
              yes and no (the default).

       leftid = <id>
              how the left participant should be identified for authentication; defaults to  left
              or  the  subject  of  the  certificate  configured  with  leftcert.  If leftcert is
              configured the identity has to be confirmed by the certificate.

              Can be an IP address,  a  fully-qualified  domain  name,  an  email  address  or  a
              Distinguished Name for which the ID type is determined automatically and the string
              is converted to the  appropriate  encoding.  The  rules  for  this  conversion  are
              described in IDENTITY PARSING below.

              In  certain  special  situations  the identity parsing above might be inadequate or
              produce the wrong result. Examples are the need to encode a FQDN as KEY_ID  or  the
              string  parser  being  unable  to  produce  the  correct binary ASN.1 encoding of a
              certificate's DN.  For these situations  it  is  possible  to  enforce  a  specific
              identity  type  and  to  provide  the binary encoding of the identity. To do this a
              prefix may be used, followed by a colon (:). If the number  sign  (#)  follows  the
              colon,  the  remaining data is interpreted as hex encoding, otherwise the string is
              used as is as the identification data.  Note: The latter implies that no conversion
              is performed for non-string identities.  For example, ipv4:10.0.0.1 does not create
              a valid ID_IPV4_ADDR  IKE  identity,  as  it  does  not  get  converted  to  binary
              0x0a000001. Instead, one could use ipv4:#0a000001 to get a valid identity, but just
              using the implicit type with automatic conversion  is  usually  simpler.  The  same
              applies  to  the ASN.1 encoded types. The following prefixes are known: ipv4, ipv6,
              rfc822, email, userfqdn, fqdn, dns, asn1dn, asn1gn and keyid.  Custom type prefixes
              may be specified by surrounding the numerical type value by curly brackets.

              For  IKEv2  and  rightid  the prefix % in front of the identity prevents the daemon
              from sending IDr in its IKE_AUTH request and will allow it to verify the configured
              identity  against  the  subject  and  subjectAltNames  contained in the responder's
              certificate (otherwise it is only compared with the IDr returned by the responder).
              The  IDr sent by the initiator might otherwise prevent the responder from finding a
              config if it has configured a different value for leftid.

       leftid2 = <id>
              identity to use for a second authentication for the left participant (IKEv2  only);
              defaults to leftid.

       leftikeport = <port>
              UDP port the left participant uses for IKE communication.  If unspecified, port 500
              is used with the port floating to 4500 if a NAT is detected or MOBIKE  is  enabled.
              Specifying  a  local  IKE  port  different from the default additionally requires a
              socket implementation that listens on this port.

       leftprotoport = <protocol>/<port>
              restrict the traffic selector to a single protocol and/or port. This option is  now
              deprecated,  protocol/port  information  can be defined for each subnet directly in
              leftsubnet.

       leftsigkey = <raw public key> | <path to public key>
              the left participant's public key  for  public  key  signature  authentication,  in
              PKCS#1  format  using  hex  (0x  prefix)  or  base64 (0s prefix) encoding. With the
              optional dns: or ssh: prefix in front of 0x or 0s, the public key is expected to be
              in  either the RFC 3110 (not the full RR, only RSA key part) or RFC 4253 public key
              format, respectively.  Also accepted is the path to a file  containing  the  public
              key  in  PEM,  DER  or  SSH  encoding.  Both  absolute  paths  or paths relative to
              /etc/ipsec.d/certs are accepted.

       leftsendcert = never | no | ifasked | always | yes
              Accepted values are never or no, always or yes,  and  ifasked  (the  default),  the
              latter  meaning  that  the peer must send a certificate request payload in order to
              get a certificate in return.

       leftsourceip = %config4 | %config6 | <ip address>
              Comma separated list of internal source IPs to use  in  a  tunnel,  also  known  as
              virtual  IP.  If  the  value  is one of the synonyms %config, %cfg, %modeconfig, or
              %modecfg, an address (from the tunnel address family) is requested from  the  peer.
              With %config4 and %config6 an address of the given address family will be requested
              explicitly.  If an IP  address  is  configured,  it  will  be  requested  from  the
              responder, which is free to respond with a different address.

       rightsourceip = %config | <network>/<netmask> | <from>-<to> | %poolname
              Comma separated list of internal source IPs to use in a tunnel for the remote peer.
              If the value is %config on the  responder  side,  the  initiator  must  propose  an
              address  which  is  then echoed back. Also supported are address pools expressed as
              network/netmask and from-to or the  use  of  an  external  IP  address  pool  using
              %poolname, where poolname is the name of the IP address pool used for the lookup.

       leftsubnet = <ip subnet>[[<proto/port>]][,...]
              private  subnet  behind  the  left  participant,  expressed  as network/netmask; if
              omitted, essentially assumed to be left/32, signifying that the  left  end  of  the
              connection  goes  to the left participant only. Configured subnets of the peers may
              differ, the protocol narrows it to the greatest common subnet. In IKEv1,  this  may
              lead  to  problems  with  other  implementations,  make sure to configure identical
              subnets in such  configurations.  IKEv2  supports  multiple  subnets  separated  by
              commas.  IKEv1  only  interprets  the first subnet of such a definition, unless the
              Cisco Unity extension plugin is enabled. This is due to a limitation of  the  IKEv1
              protocol,  which  only  allows  a single pair of subnets per CHILD_SA. So to tunnel
              several subnets a conn entry has to be defined and brought  up  for  each  pair  of
              subnets.

              The  optional  part  after  each  subnet  enclosed  in  square brackets specifies a
              protocol/port to restrict the selector for that subnet.

              Examples:              leftsubnet=10.0.0.1[tcp/http],10.0.0.2[6/80]              or
              leftsubnet=fec1::1[udp],10.0.0.0/16[/53].   Instead  of  omitting either value %any
              can       be       used        to        the        same        effect,        e.g.
              leftsubnet=fec1::1[udp/%any],10.0.0.0/16[%any/53].

              If  the  protocol is icmp or ipv6-icmp the port is interpreted as ICMP message type
              if it is less than 256 or as type and code if it is greater or equal to  256,  with
              the  type  in  the  most significant 8 bits and the code in the least significant 8
              bits.

              The port value can alternatively  take  the  value  %opaque  for  RFC  4301  OPAQUE
              selectors,  or  a  numerical  range  in  the  form  1024-65535.  None of the kernel
              backends currently supports  opaque  or  port  ranges  and  uses  %any  for  policy
              installation instead.

              Instead  of  specifying  a  subnet, %dynamic can be used to replace it with the IKE
              address, having the same effect as omitting leftsubnet completely.  Using  %dynamic
              can  be  used  to  define  multiple  dynamic  selectors,  each having a potentially
              different protocol/port definition.

       leftupdown = <path>
              what ``updown'' script to run to adjust routing and/or firewalling when the  status
              of  the  connection  changes  (default  ipsec  _updown).   May  include  positional
              parameters separated by white space (although this  requires  enclosing  the  whole
              string  in  quotes);  including  shell  metacharacters  is  unwise.   Relevant only
              locally, other end need not agree on it. Charon uses the updown  script  to  insert
              firewall rules only, since routing has been implemented directly into the daemon.

       lifebytes = <number>
              the number of bytes transmitted over an IPsec SA before it expires.

       lifepackets = <number>
              the number of packets transmitted over an IPsec SA before it expires.

       lifetime = 1h | <time>
              how  long a particular instance of a connection (a set of encryption/authentication
              keys for  user  packets)  should  last,  from  successful  negotiation  to  expiry;
              acceptable  values are an integer optionally followed by s (a time in seconds) or a
              decimal number followed by  m,  h,  or  d  (a  time  in  minutes,  hours,  or  days
              respectively)  (default 1h, maximum 24h).  Normally, the connection is renegotiated
              (via the keying channel) before it expires (see margintime).  The two ends need not
              exactly  agree  on lifetime, although if they do not, there will be some clutter of
              superseded connections on the end which thinks the lifetime  is  longer.  Also  see
              EXPIRY/REKEY below.

       marginbytes = <number>
              how  many bytes before IPsec SA expiry (see lifebytes) should attempts to negotiate
              a replacement begin.

       marginpackets = <number>
              how many packets before IPsec  SA  expiry  (see  lifepackets)  should  attempts  to
              negotiate a replacement begin.

       margintime = 9m | <time>
              how  long  before  connection  expiry  or  keying-channel expiry should attempts to
              negotiate a replacement begin; acceptable values  as  for  lifetime  (default  9m).
              Relevant only locally, other end need not agree on it. Also see EXPIRY/REKEY below.

       mark = <value>[/<mask>]
              sets  an  XFRM  mark on the inbound policy and outbound IPsec SA and policy. If the
              mask is missing then a default mask of 0xffffffff is  assumed.  The  special  value
              %unique assigns a unique value to each newly created IPsec SA. To additionally make
              the mark unique for each IPsec SA direction (in/out) the special value  %unique-dir
              may be used.

       mark_in = <value>[/<mask>]
              sets  an  XFRM  mark  on the inbound policy (not on the SA). If the mask is missing
              then a default mask of 0xffffffff is assumed.

       mark_out = <value>[/<mask>]
              sets an XFRM mark on the outbound IPsec SA and policy. If the mask is missing  then
              a default mask of 0xffffffff is assumed.

       mobike = yes | no
              enables the IKEv2 MOBIKE protocol defined by RFC 4555. Accepted values are yes (the
              default) and no.  If set to no, the charon daemon will not actively propose  MOBIKE
              as initiator and ignore the MOBIKE_SUPPORTED notify as responder.

       modeconfig = push | pull
              defines  which  mode  is used to assign a virtual IP.  Accepted values are push and
              pull (the default).  Push mode is currently not supported with IKEv2.  The  setting
              must be the same on both sides.

       reauth = yes | no
              whether  rekeying  of  an  IKE_SA  should  also  reauthenticate the peer. In IKEv1,
              reauthentication  is  always  done.  In  IKEv2,  a  value  of  no  rekeys   without
              uninstalling  the IPsec SAs, a value of yes (the default) creates a new IKE_SA from
              scratch and tries to recreate all IPsec SAs.

       rekey = yes | no
              whether a connection should be renegotiated when it is about to expire;  acceptable
              values  are  yes  (the  default)  and no.  The two ends need not agree, but while a
              value of no prevents charon from requesting  renegotiation,  it  does  not  prevent
              responding  to  renegotiation  requested  from the other end, so no will be largely
              ineffective unless both ends agree on it. Also see reauth.

       rekeyfuzz = 100% | <percentage>
              maximum percentage by which marginbytes, marginpackets  and  margintime  should  be
              randomly  increased  to randomize rekeying intervals (important for hosts with many
              connections); acceptable values are an integer, which may exceed 100, followed by a
              `%'  (defaults to 100%).  The value of marginTYPE, after this random increase, must
              not exceed lifeTYPE (where TYPE is one of bytes, packets or time).   The  value  0%
              will  suppress  randomization.   Relevant only locally, other end need not agree on
              it. Also see EXPIRY/REKEY below.

       replay_window = -1 | <number>
              The IPsec replay window size for this connection. With the default of -1 the  value
              configured  with  charon.replay_window in strongswan.conf(5) is used. Larger values
              than 32 are supported using the Netlink backend only, a value of 0  disables  IPsec
              replay protection.

       reqid = <number>
              sets the reqid for a given connection to a pre-configured fixed value.

       sha256_96 = no | yes
              HMAC-SHA-256  is  used  with  128-bit truncation with IPsec. For compatibility with
              implementations that incorrectly use 96-bit truncation this option may  be  enabled
              to  configure the shorter truncation length in the kernel.  This is not negotiated,
              so this only works with peers that use the incorrect  truncation  length  (or  have
              this option enabled).

       tfc = <value>
              number  of  bytes  to  pad  ESP  payload  data  to. Traffic Flow Confidentiality is
              currently supported in IKEv2 and applies to  outgoing  packets  only.  The  special
              value %mtu fills up ESP packets with padding to have the size of the MTU.

       type = tunnel | transport | transport_proxy | passthrough | drop
              the  type of the connection; currently the accepted values are tunnel (the default)
              signifying a host-to-host, host-to-subnet, or subnet-to-subnet  tunnel;  transport,
              signifying  host-to-host  transport  mode;  transport_proxy, signifying the special
              Mobile IPv6 transport proxy mode; passthrough, signifying that no IPsec  processing
              should be done at all; drop, signifying that packets should be discarded.

       xauth = client | server
              specifies  the  role  in  the  XAuth  protocol  if  activated by authby=xauthpsk or
              authby=xauthrsasig.  Accepted values are server and client (the default).

       xauth_identity = <id>
              defines the identity/username the client uses to reply to an XAuth request.  If not
              defined, the IKEv1 identity will be used as XAuth identity.

   CONN PARAMETERS: IKEv2 MEDIATION EXTENSION
       The following parameters are relevant to IKEv2 Mediation Extension operation only.

       mediation = yes | no
              whether  this  connection is a mediation connection, ie. whether this connection is
              used to mediate other connections.   Mediation  connections  create  no  child  SA.
              Acceptable values are no (the default) and yes.

       mediated_by = <name>
              the  name  of  the  connection  to  mediate this connection through.  If given, the
              connection will be mediated through the named mediation connection.  The  mediation
              connection must set mediation=yes.

       me_peerid = <id>
              ID  as  which the peer is known to the mediation server, ie. which the other end of
              this connection uses as its leftid on its connection to the mediation server.  This
              is  the ID we request the mediation server to mediate us with.  If me_peerid is not
              given, the rightid of this connection will be used as peer ID.

CA SECTIONS

       These are  optional  sections  that  can  be  used  to  assign  special  parameters  to  a
       Certification  Authority  (CA).  Because  the daemons automatically import CA certificates
       from /etc/ipsec.d/cacerts, there is no need to explicitly add  them  with  a  CA  section,
       unless you want to assign special parameters (like a CRL) to a CA.

       also = <name>
              includes ca section <name>.

       auto = ignore | add
              currently can have either the value ignore (the default) or add.

       cacert = <path>
              defines  a path to the CA certificate either relative to /etc/ipsec.d/cacerts or as
              an absolute path.
              A value in the form %smartcard[<slot nr>[@<module>]]:<keyid> defines a specific  CA
              certificate  to  load from a PKCS#11 backend for this CA.  See ipsec.secrets(5) for
              details about smartcard definitions.

       crluri = <uri>
              defines a CRL distribution point (ldap, http, or file URI)

       crluri1
              synonym for crluri.

       crluri2 = <uri>
              defines an alternative CRL distribution point (ldap, http, or file URI)

       ocspuri = <uri>
              defines an OCSP URI.

       ocspuri1
              synonym for ocspuri.

       ocspuri2 = <uri>
              defines an alternative OCSP URI.

       certuribase = <uri>
              defines the base URI for the Hash and URL feature supported by IKEv2.   Instead  of
              exchanging  complete certificates, IKEv2 allows one to send an URI that resolves to
              the DER encoded certificate. The certificate URIs are built by appending  the  SHA1
              hash of the DER encoded certificates to this base URI.

CONFIG SECTIONS

       At  present,  the  only config section known to the IPsec software is the one named setup,
       which contains information used when  the  software  is  being  started.   The  currently-
       accepted parameter names in a config setup section are:

       cachecrls = yes | no
              if  enabled,  certificate  revocation lists (CRLs) fetched via HTTP or LDAP will be
              cached  in  /etc/ipsec.d/crls/  under  a  unique  file  name   derived   from   the
              certification authority's public key.

       charondebug = <debug list>
              how  much  charon  debugging  output  should  be  logged.   A  comma separated list
              containing  type/level-pairs  may  be  specified,  e.g:  dmn  3,  ike  1,  net  -1.
              Acceptable  values  for types are dmn, mgr, ike, chd, job, cfg, knl, net, asn, enc,
              lib, esp, tls, tnc, imc, imv, pts and the level is one of -1, 0, 1, 2,  3,  4  (for
              silent,  audit,  control, controlmore, raw, private).  By default, the level is set
              to  1  for  all  types.   For  more  flexibility  see   LOGGER   CONFIGURATION   in
              strongswan.conf(5).

       strictcrlpolicy = yes | ifuri | no
              defines if a fresh CRL must be available in order for the peer authentication based
              on RSA signatures to succeed.  IKEv2 additionally recognizes ifuri which reverts to
              yes if at least one CRL URI is defined and to no if no URI is known.

       uniqueids = yes | no | never | replace | keep
              whether  a  particular  participant  ID  should be kept unique, with any new IKE_SA
              using an ID deemed to replace all old ones using that ID; acceptable values are yes
              (the  default), no and never.  Participant IDs normally are unique, so a new IKE_SA
              using the same ID is  almost  invariably  intended  to  replace  an  old  one.  The
              difference  between  no  and never is that the daemon will replace old IKE_SAs when
              receiving an INITIAL_CONTACT notify if the option  is  no  but  will  ignore  these
              notifies  if  never is configured.  The daemon also accepts the value replace which
              is identical to yes and the value keep to reject new IKE_SA  setups  and  keep  the
              duplicate established earlier.

IDENTITY PARSING

       The  type  and  binary  encoding  of  identity strings specified in leftid are detected as
       follows:

       •      If the string value contains an equal sign (=) it is assumed to be a  Distinguished
              Name,  with RDNs separated by commas (,) or slashes (/ - the string must start with
              a slash to use this syntax). An attempt is made to create a binary  ASN.1  encoding
              from  this  string. If that fails the type is set to KEY_ID with the literal string
              value adopted as encoding.

       •      If the string value contains an  @  the  type  depends  on  the  position  of  that
              character:

              •      If  the  string  begins  with  @#  the  type is set to KEY_ID and the string
                     following that prefix is assumed to be the hex-encoded binary value  of  the
                     identity.

              •      If  the  string begins with @@ the type is set to USER_FQDN and the encoding
                     is the literal string after that prefix.

              •      If the string begins with @ the type is set to FQDN and the encoding is  the
                     literal string after that prefix.

              •      All   remaining   strings  containing  an  @  are  assumed  to  be  of  type
                     USER_FQDN/RFC822 with the literal string value as encoding.

       •      If the value does not contain any @ or = characters it is parsed as follows:

              •      If the value is an empty string, or equals %any[6], 0.0.0.0, ::,  or  *  the
                     type is set to ID_ANY, which matches any other identity.

              •      If  the  value contains a colon (:) it is assumed to be an IPv6 address. But
                     if parsing the address and converting it to its binary  encoding  fails  the
                     type is set to KEY_ID and the encoding is the literal value.

              •      For  all other strings an attempt at parsing them as IPv4 addresses is made.
                     If that fails the type is set to FQDN and the literal value  is  adopted  as
                     encoding (this is where domain names and simple names end up).

SA EXPIRY/REKEY

       The  IKE  SAs  and  IPsec SAs negotiated by the daemon can be configured to expire after a
       specific amount of time. For IPsec SAs this can also happen after a  specified  number  of
       transmitted  packets or transmitted bytes. The following settings can be used to configure
       this:

       Setting         Default   Setting         Default
       ──────────────────────────────────────────────────
       IKE SA                    IPsec SA
        ikelifetime         3h    lifebytes            -
                                  lifepackets          -
                                  lifetime            1h

   Rekeying
       IKE SAs as well as IPsec SAs can be rekeyed before they expire.  This  can  be  configured
       using the following settings:

       Setting        Default   Setting           Default
       ───────────────────────────────────────────────────
       IKE and IPsec SA         IPsec SA
        margintime         9m    marginbytes            -
                                 marginpackets          -

   Randomization
       To  avoid  collisions the specified margins are increased randomly before subtracting them
       from the expiration limits (see formula  below).  This  is  controlled  by  the  rekeyfuzz
       setting:

       Setting       Default
       ──────────────────────
       IKE and IPsec SA
        rekeyfuzz       100%

       Randomization can be disabled by setting rekeyfuzz to 0%.

   Formula
       The following formula is used to calculate the rekey time of IPsec SAs:

        rekeytime = lifetime - (margintime + random(0, margintime * rekeyfuzz))

       It applies equally to IKE SAs and byte and packet limits for IPsec SAs.

   Example
       Let's consider the default configuration:

                  lifetime = 1h
                  margintime = 9m
                  rekeyfuzz = 100%

       From the formula above follows that the rekey time lies between:

                  rekeytime_min = 1h - (9m + 9m) = 42m
                  rekeytime_max = 1h - (9m + 0m) = 51m

       Thus,  the  daemon  will  attempt to rekey the IPsec SA at a random time between 42 and 51
       minutes after establishing the SA. Or, in other words, between 9 and 18 minutes before the
       SA expires.

   Notes
       •      Since the rekeying of an SA needs some time, the margin values must not be too low.

       •      The value margin... + margin... * rekeyfuzz must not exceed the original limit. For
              example, specifying margintime = 30m in the default configuration is a bad idea  as
              there  is  a  chance  that  the  rekey  time  equals  zero and, thus, rekeying gets
              disabled.

FILES

       /etc/ipsec.conf
       /etc/ipsec.d/aacerts
       /etc/ipsec.d/acerts
       /etc/ipsec.d/cacerts
       /etc/ipsec.d/certs
       /etc/ipsec.d/crls

SEE ALSO

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

HISTORY

       Originally written for the FreeS/WAN project by Henry Spencer.  Updated and  extended  for
       the  strongSwan project <http://www.strongswan.org> by Tobias Brunner, Andreas Steffen and
       Martin Willi.