Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
IPSEC.CONF(5)			  strongSwan			 IPSEC.CONF(5)

       ipsec.conf - IPsec configuration	and connections

       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

       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  sec-

       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  in-
       formation  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., with-
       out 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 connec-
       tion 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 arbi-
       trary 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


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

       An  empty value stands for the system default value (if any) of the pa-
       rameter,	i.e. it	is roughly equivalent to omitting the  parameter  line
       entirely.  This	may be useful to clear a setting inherited from	a %de-
       fault 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  mul-
       tiple  lines  by	 ending	 them with \ characters	(following lines don't
       have to begin with white	space, as that will be	preserved).  Addition-
       ally,  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 sec-

       also   the  value is a section name; the	parameters of that section are
	      inherited	by the current section.	Parameters in the current sec-
	      tion  always override inherited parameters, even if an also fol-
	      lows after them.	The specified section must exist and must have
	      the same section type; it	doesn't	if it is defined before	or af-
	      ter the current section.	Nesting	is permitted, and there	may be
	      more  than  one also in a	single section (parameters from	refer-
	      enced 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.

       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

       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 sepa-
       rate keying daemons, pluto and charon. This  manual  does  not  discuss
       pluto  options  anymore,	but only charon	that since strongSwan 5.0 sup-
       ports 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 arbi-
       trary; for every	connection description an attempt is  made  to	figure
       out  whether  the  local	 endpoint should act as	the left or right end-
       point. This is done by matching the IP addresses	defined	for both  end-
       points 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 con-
       sidered local.  This permits using identical connection	specifications
       on  both	ends.  There are cases where there is no symmetry; a good con-
       vention 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)'.

       Unless otherwise	noted, for a connection	to work, in general it is nec-
       essary for the two ends to agree	exactly	on the values of these parame-

       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 connec-
	      tion,  e.g.   sha1-sha256-modp1024.   The	 notation  is	integ-
	      rity[-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  sup-

	      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  protec-
	      tion  for	ESP encrypted packets, but is not supported in charon.
	      The ah keyword specifies algorithms to use for integrity protec-
	      tion  with  AH,  but  without encryption.	AH+ESP bundles are not

       authby =	pubkey | rsasig	| ecdsasig | psk | secret | never | xauthpsk |
	      how  the	two  security gateways should authenticate each	other;
	      acceptable values	are psk	or secret for pre-shared secrets, pub-
	      key  (the	default) for public key	signatures as well as the syn-
	      onyms rsasig for RSA digital signatures and ecdsasig for	Ellip-
	      tic  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	signa-
	      tures, 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 ig-
	      nore (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  immedi-
	      ately.  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 connec-
	      tion (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 IN-
	      FORMATIONAL  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  fur-
	      ther  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 mes-
	      sages/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 stan-
	      dard 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	 nota-
	      tion  is	encryption-integrity[-dhgroup][-esnmode].   For	IKEv2,
	      multiple algorithms (separated by	-) of the same type can	be in-
	      cluded in	a single proposal. IKEv1 only includes the first algo-
	      rithm 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 de-
	      fault proposal to	this default or	the configured value.  To  re-
	      strict  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 accept-
	      able  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 ini-
	      tial 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  de-
	      rived  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 ne-
	      gotiates Extended	Sequence Number	support	with the peer, the de-
	      fault 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 frag-
	      ments. 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  ini-
	      tial  IKE	 message  will	already	be fragmented if required. Fi-
	      nally, setting the option	to no will disable announcing  support
	      for this feature.

	      Note  that fragmented IKE	messages sent by a peer	are always ac-
	      cepted 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	 nota-
	      tion 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-

	      Defaults to aes128-sha256-modp3072.  The daemon adds its	exten-
	      sive  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 pro-
	      posal received from the peer.  In	order to restrict a  responder
	      to  only	accept specific	cipher suites, the strict flag (!, ex-
	      clamation	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 bi-
	      nary 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 be-

       installpolicy = yes | no
	      decides  whether	IPsec  policies	are installed in the kernel by
	      the charon daemon	for a given connection.	Allows peaceful	 coop-
	      eration e.g. with	the Mobile IPv6	daemon mip6d who wants to con-
	      trol the kernel policies.	 Acceptable values are	yes  (the  de-
	      fault) and no.

       keyexchange = ike | ikev1 | ikev2
	      which  key exchange protocol should be used to initiate the con-
	      nection.	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'.  Rel-
	      evant 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	inter-
	      face  or	one  of	several	magic values.  The value %any (the de-
	      fault) 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  de-
	      layed for	that time.

	      To limit the connection to a  specific range of hosts, a range ( ) or a subnet (	) can be spec-
	      ified,  and  multiple addresses, ranges and subnets can be sepa-
	      rated by commas. While one can freely combine  these  items,  to
	      initiate	the  connection	 at  least one non-range/subnet	is re-

	      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  con-
	      crete 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 authenti-
	      cation, eap to (require the) use of the  Extensible  Authentica-
	      tion Protocol in IKEv2, and xauth	for IKEv1 eXtended Authentica-

	      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 ac-
	      ceptable	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  authentica-
	      tion schemes used	by the remote side.

	      If  both	peers  support	RFC 7427 ("Signature Authentication in
	      IKEv2") specific hash algorithms to be used during IKEv2 authen-
	      tication	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  al-
	      gorithm  that  matches  or exceeds the strength of the signature
	      key.  If no constraints with ike:	prefix are configured any sig-
	      nature  scheme  constraint (without ike: prefix) will also apply
	      to  IKEv2	  authentication,   unless   this   is	 disabled   in

	      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  con-
	      straints	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  de-
	      fined  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	speci-
	      fied,  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 ex-
	      change. In IKEv1,	only XAuth can be used in the second authenti-
	      cation  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  re-
	      quired  to  lie  in  the trust path going	from the left partici-
	      pant'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

       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> de-
	      fines a specific certificate to load from	a PKCS#11 backend  for
	      this  connection.	 See ipsec.secrets(5) for details about	smart-
	      card definitions.	 leftcert is required only  if	selecting  the
	      certificate with leftid is not sufficient, for example if	multi-
	      ple 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

       leftcertpolicy =	<OIDs>
	      Comma separated list of certificate policy OIDs the peer's  cer-
	      tificate must have.  OIDs	are specified using the	numerical dot-
	      ted representation.

       leftdns = <servers>
	      Comma separated list of DNS server addresses to exchange as con-
	      figuration  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 ad-
	      dresses are allowed and  define  DNS  servers  assigned  to  the

       leftfirewall = yes | no
	      whether  the  left  participant  is doing	forwarding-firewalling
	      (including masquerading) using iptables for traffic  from	 left-
	      subnet,  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 con-
	      nection 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	 fire-
	      walling (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	appro-
	      priate adjustments for his system.

       leftgroups = <group list>
	      a	comma separated	list of	group names. If	the leftgroups parame-
	      ter 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  de-
	      fined with leftauth2.

       lefthostaccess =	yes | no
	      inserts  a pair of INPUT and OUTPUT iptables rules using the de-
	      fault ipsec _updown script, thus allowing	access to the host it-
	      self  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 authentica-
	      tion; defaults to	left or	the subject of the certificate config-
	      ured  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	deter-
	      mined automatically and the string is converted to the appropri-
	      ate  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	 iden-
	      tity 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	inter-
	      preted as	hex encoding, otherwise	the string is used  as	is  as
	      the  identification data.	 Note: The latter implies that no con-
	      version is performed for non-string  identities.	 For  example,
	      ipv4: 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 pre-
	      fixes 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 pre-
	      vents  the  daemon  from sending IDr in its IKE_AUTH request and
	      will allow it to verify the configured identity against the sub-
	      ject  and	 subjectAltNames contained in the responder's certifi-
	      cate (otherwise it is only compared with the IDr returned	by the
	      responder).   The	IDr sent by the	initiator might	otherwise pre-
	      vent 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 partic-
	      ipant (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  au-
	      thentication,  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 ac-

       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 certifi-
	      cate 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  re-
	      quested  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/net-
	      mask 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 net-
	      work/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	inter-
	      prets  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 sub-
	      nets 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 sub-

	      Examples:	 leftsubnet=[tcp/http],[6/80] or left-
	      subnet=fec1::1[udp],[/53].  Instead of	 omitting  ei-
	      ther  value  %any	can be used to the same	effect,	e.g.  leftsub-

	      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 signif-
	      icant 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  in-

	      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 mul-
	      tiple dynamic selectors, each  having  a	potentially  different
	      protocol/port definition.

       leftupdown = <path>
	      what  ``updown''	script	to  run	to adjust routing and/or fire-
	      walling 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  ex-

       lifepackets = <number>
	      the number of packets transmitted	over an	IPsec SA before	it ex-

       lifetime	= 1h | <time>
	      how long a particular instance of	a connection (a	set of encryp-
	      tion/authentication  keys	 for  user  packets) should last, from
	      successful negotiation to	expiry;	acceptable values are an inte-
	      ger  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 connec-
	      tion is renegotiated (via	the keying channel) before it  expires
	      (see  margintime).  The two ends need not	exactly	agree on life-
	      time, although if	they do	not, there will	be some	clutter	of su-
	      perseded	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 at-
	      tempts 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

       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

       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);  accept-
	      able  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  randomiza-
	      tion.   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  de-
	      fault  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 re-
	      play protection.

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

       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	Confi-
	      dentiality is currently supported	in IKEv2 and applies to	outgo-
	      ing 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 au-
	      thby=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.

       The  following parameters are relevant to IKEv2 Mediation Extension op-
       eration 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  me-
	      diation  connection.   The  mediation connection must set	media-

       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 con-
	      nection 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.

       These are optional sections that	can be used to assign special  parame-
       ters  to	 a Certification Authority (CA). Because the daemons automati-
       cally import CA certificates from  /etc/ipsec.d/cacerts,	 there	is  no
       need  to	 explicitly add	them with a CA section,	unless you want	to as-
       sign 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> de-
	      fines a specific CA certificate to load from a  PKCS#11  backend
	      for  this	 CA.  See ipsec.secrets(5) for details about smartcard

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

	      synonym for crluri.

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

       ocspuri = <uri>
	      defines an OCSP URI.

	      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  al-
	      lows  one	 to  send an URI that resolves to the DER encoded cer-
	      tificate.	The certificate	URIs are built by appending  the  SHA1
	      hash of the DER encoded certificates to this base	URI.

       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 sep-
	      arated  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  LOG-
	      GER 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	 addi-
	      tionally	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  op-
	      tion  is	no  but	will ignore these notifies if never is config-
	      ured.  The daemon	also accepts the value replace which is	 iden-
	      tical  to	yes and	the value keep to reject new IKE_SA setups and
	      keep the duplicate established earlier.

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

       o      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 syn-
	      tax). 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.

       o      If the string value contains an @	the type depends on the	 posi-
	      tion of that character:

	      o	     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.

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

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

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

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

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

	      o	     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.

	      o	     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).

       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

       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		-

       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%.

       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.

       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.

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

       o      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.


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

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

5.9.1				  2012-06-26			 IPSEC.CONF(5)


Want to link to this manual page? Use this URL:

home | help