bionic (5) ipsec.conf.5.gz

Provided by: strongswan-starter_5.6.2-1ubuntu2.9_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
              uniquids 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.

       keylife
              synonym for lifetime.

       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.

       rekeymargin
              synonym for margintime.

       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.