Provided by: strongswan_4.2.4-5ubuntu1_i386
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
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
A line which contains include and a file name, separated by white
space, is replaced by the contents of that file, preceded and followed
by empty lines. 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:
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:
where type indicates what type of section follows, and name is an
arbitrary name which distinguishes the section from others of the same
type. (Names must start with a letter and may contain only letters,
digits, periods, underscores, and hyphens.) All subsequent non-empty
lines which begin with white space are part of the section; comments
within a section must begin with white space too. There may be only
one section of a given type with a given name.
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 follow the same syntax as
section names, and are specific to a section type. Unless otherwise
explicitly specified, no parameter name may appear more than once in a
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. A value may contain white space only if the entire value is
enclosed in double quotes ("); a value cannot itself contain a double
quote, nor may it be continued across more than one line.
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
also the value is a section name; the parameters of that section are
appended to this section, as if they had been written as part of
it. The specified section must exist, must follow the current
one, and must have the same section type. (Nesting is
permitted, and there may be more than one also in a single
section, although it is forbidden to append the same section
more than once.)
A section with name %default specifies defaults for sections of the
same type. For each parameter in it, any section of that type which
does not have a parameter of the same name gets a copy of the one from
the %default section. There may be multiple %default sections of a
given type, but only one default may be supplied for any specific
parameter name, and all %default sections of a given type must precede
all non-%default sections of that type. %default sections may not
contain the also parameter.
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:
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 level data path, is
called ’IPsec SA’. strongSwan currently uses two separate keying
daemons. Pluto handles all IKEv1 connections, Charon is the new daemon
supporting the IKEv2 protocol. Charon does not support all keywords
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; IPsec figures out which one it is being run on based on
internal information. 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)’.
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
ah AH authentication algorithm to be used for the
connection, e.g. hmac-md5.
auth whether authentication should be done as part of ESP
encryption, or separately using the AH protocol;
acceptable values are esp (the default) and ah. The
IKEv2 daemon currently supports only ESP.
authby how the two security gateways should authenticate each
other; acceptable values are secret or psk for shared
secrets, rsasig for RSA digital signatures (the default),
secret|rsasig for either, and never if negotiation is
never to be attempted or accepted (useful for shunt-only
conns). Digital signatures are superior in every way to
shared secrets. In IKEv2, the two ends must not agree on
this parameter, it is relevant for the outbound
authentication method only. 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. IKEv2 additionally supports the value eap,
which indicates an initiator to request EAP
authentication. The EAP method to use is selected by the
server (see eap).
auto what operation, if any, should be done automatically at
IPsec startup; currently-accepted values are add , route
, start and ignore. 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 immediatly. ignore
ignores the connection. This is equal to delete a
connection from the config file. Relevant only locally,
other end need not agree on it (but in general, for an
intended-to-be-permanent connection, both ends should use
auto=start to ensure that any reboot causes immediate
compress 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 IPsec to propose
both compressed and uncompressed, and prefer compressed.
A value of no prevents IPsec from proposing compression;
a proposal to compress will still be accepted. IKEv2
does not support IP compression yet.
dpdaction 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. If no activity is detected, all connections
with a dead peer are stopped and unrouted ( clear ), put
in the hold state ( hold ) or restarted ( restart ). For
IKEv1, the default is none which disables the active
sending of R_U_THERE notifications. Nevertheless pluto
will always send the DPD Vendor ID during connection set
up in order to signal the readiness to act passively as a
responder if the peer wants to use DPD. For IKEv2, none
does’t make sense, since all messages are used to detect
dead peers. If specified, it has the same meaning as the
default ( clear ).
dpddelay 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 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
eap defines the EAP type to propose as server if the client
has authby=eap selected. Acceptable values are aka for
EAP-AKA, sim for EAP-SIM and md5 for EAP-MD5.
Additionally, IANA assigned EAP method numbers are
accepted, or a definition in the form eap=type-vendor
(e.g. eap=7-12345 ) can be used to specify vendor
specific EAP types.
esp ESP encryption/authentication algorithm to be used for
the connection, e.g. 3des-md5 (encryption-integrity-[dh-
group]). If dh-group is specified, CHILD_SA setup and
rekeying include a separate diffe hellman exchange (IKEv2
forceencaps Force UDP encapsulation for ESP packets even if no NAT
situation is detected. This may help to hurdle
restrictive firewalls. To enforce the peer to encapsulate
packets, NAT detection payloads are faked (IKEv2 only).
ike IKE/ISAKMP SA encryption/authentication algorithm to be
used, e.g. aes128-sha1-modp2048 (encryption-integrity-
dhgroup). In IKEv2, multiple algorithms and proposals may
be included, such as
ikelifetime how long the keying channel of a connection (’ISAKMP/IKE
SA’) should last before being renegotiated.
keyexchange method of key exchange; which protocol should be used to
initialize the connection. Connections marked with ikev1
are initiated with pluto, those marked with ikev2 with
charon. An incoming request from the remote peer is
handled by the correct daemon, unaffected from the
keyexchange setting. The default value ike currently
behaves exactly as ikev1.
keyingtries how many attempts (a whole number or %forever) should be
made to negotiate a connection, or a replacement for one,
before giving up (default %forever). The value %forever
means ’never give up’. Relevant only locally, other end
need not agree on it.
keylife 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.
The two ends need not exactly agree on keylife, although
if they do not, there will be some clutter of superseded
connections on the end which thinks the lifetime is
left (required) the IP address of the left participant’s
public-network interface, in any form accepted by
ttoaddr(3) or one of several magic values. If it is
%defaultroute, left will be filled in automatically with
the local address of the default-route interface (as
determined at IPsec startup time). (Either left or right
may be %defaultroute, but not both.) The value %any
signifies an address to be filled in (by automatic
keying) during negotiation. The prefix % in front of a
fully-qualified domain name or an IP address will
implicitly set leftallowany=yes. If the domain name
cannot be resolved into an IP address at IPsec startup or
update time then left=%any and leftallowany=no will be
leftallowany a modifier for left , making it behave as %any although a
concrete IP address has been assigned. Recommended for
dynamic IP addresses that can be resolved by DynDNS at
IPsec startup or update time. Acceptable values are yes
and no (the default).
leftca 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
leftcert the path to the left participant’s X.509 certificate. The
file can be coded 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 and leftca to the distinguished
name of the certificate’s issuer. The left participant’s
ID can be overriden by specifying a leftid value which
must be certified by the certificate, though.
leftfirewall 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 (see
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 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. Group
membership must be certified by a valid attribute
certificate stored in /etc/ipsec.d/acerts/ thas has been
issued to the peer by a trusted Authorization Authority
stored in /etc/ipsec.d/aacerts/. Attribute certificates
are not supported in IKEv2 yet.
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 how the left participant should be identified for
authentication; defaults to left. Can be an IP address
(in any ttoaddr(3) syntax) or a fully-qualified domain
name preceded by @ (which is used as a literal string and
leftnexthop this parameter is not needed any more because the NETKEY
IPsec stack does not require explicit routing entries for
the traffic to be tunneled.
leftprotoport restrict the traffic selector to a single protocol and/or
port. Examples: leftprotoport=tcp/http or
leftprotoport=6/80 or leftprotoport=udp
leftrsasigkey the left participant’s public key for RSA signature
authentication, in RFC 2537 format using ttodata(3)
encoding. The magic value %none means the same as not
specifying a value (useful to override a default). The
value %cert (the default) means that the key is extracted
from a certificate. The identity used for the left
participant must be a specific host, not %any or another
magic value. Caution: if two connection descriptions
specify different public keys for the same leftid,
confusion and madness will ensue.
leftsendcert Accepted values are never or no, always or yes, and
leftsourceip The internal source IP to use in a tunnel, also known as
virtual IP. If the value is %modeconfig, %modecfg,
%config, or %cfg, an address is requested from the peer.
In IKEv2, a defined address is requested, but the server
may change it. If the server does not support it, the
address is enforced.
rightsourceip The internal source IP to use in a tunnel for the remote
peer. If the value is %config on the responder side, the
initiator must propose a address which is then echoed
back. The IKEv2 daemon also supports address pools
expressed as network/netmask 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 private subnet behind the left participant, expressed as
network/netmask (actually, any form acceptable to
ttosubnet(3)); if omitted, essentially assumed to be
left/32, signifying that the left end of the connection
goes to the left participant only. When using IKEv2, the
configured subnet of the peers may differ, the protocol
narrows it to the greatest common subnet. Further, IKEv2
supports multiple subnets separated by commas. IKEv1 only
interprets the first subnet of such a definition.
the peer can propose any subnet or single IP address that
fits within the range defined by leftsubnetwithin. Not
relevant for IKEv2, as subnets are narrowed.
leftupdown 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. See pluto(8) for
details. Relevant only locally, other end need not agree
on it. IKEv2 uses the updown script to insert firewall
rules only. Routing is not support and will be
implemented directly into Charon.
mobike enables the IKEv2 MOBIKE protocol defined by RFC 4555.
Accepted values are yes (the default) and no. If set to
no, the IKEv2 charon daemon will not actively propose
MOBIKE but will still accept and support the protocol as
modeconfig defines which mode is used to assign a virtual IP.
Accepted values are push and pull (the default).
Currently relevant for IKEv1 only since IKEv2 always uses
the configuration payload in pull mode.
pfs whether Perfect Forward Secrecy of keys is desired on the
connection’s keying channel (with PFS, penetration of the
key-exchange protocol does not compromise keys negotiated
earlier); acceptable values are yes (the default) and no.
IKEv2 always uses PFS for IKE_SA rekeying whereas for
CHILD_SA rekeying PFS is enforced by defining a Diffie-
Hellman modp group in the esp parameter.
reauth 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 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 Pluto/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.
rekeyfuzz maximum percentage by which rekeymargin 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 ‘%’ (default set by pluto(8), currently 100%). The
value of rekeymargin, after this random increase, must
not exceed keylife. The value 0% will suppress time
randomization. Relevant only locally, other end need not
agree on it.
rekeymargin how long before connection expiry or keying-channel
expiry should attempts to negotiate a replacement begin;
acceptable values as for keylife (default 9m). Relevant
only locally, other end need not agree on it.
type 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; passthrough,
signifying that no IPsec processing should be done at
all; drop, signifying that packets should be discarded;
and reject, signifying that packets should be discarded
and a diagnostic ICMP returned. Charon currently
supports only tunnel and transport connection types.
xauth specifies the role in the XAUTH protocol if activated by
authby=xauthpsk or authby=xauthrsasig. Accepted values
are server and client (the default).
CONN PARAMETERS: IKEv2 MEDIATION EXTENSION
The following parameters are relevant to IKEv2 Mediation Extension
mediation 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 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 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.
This are optional sections that can be used to assign special
parameters to a Certification Authority (CA). These parameters are not
supported in IKEv2 yet.
auto currently can have either the value ignore or add
cacert defines a path to the CA certificate either relative to
/etc/ipsec.d/cacerts or as an absolute path.
crluri defines a CRL distribution point (ldap, http, or file URI)
crluri1 synonym for crluri.
crluri2 defines an alternative CRL distribution point (ldap, http, or
ldaphost defines an ldap host. Currently used by IKEv1 only.
ocspuri defines an OCSP URI.
ocspuri1 synonym for ocspuri.
ocspuri2 defines an alternative OCSP URI. Currently used by IKEv2
only. certuribase defines the base URI for the Hash and URL
feature supported by IKEv2. Instead of exchanging complete
certificates, IKEv2 allows 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.
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 (see starter(8)). Here’s an example:
Parameters are optional unless marked ‘‘(required)’’. The currently-
accepted parameter names in a config setup section affecting both
cachecrls 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. Accepted values are yes and no (the
charonstart whether to start the IKEv2 Charon daemon or not.
Accepted values are yes (the default) or no.
dumpdir in what directory should things started by ipsec starter
(notably the Pluto and Charon daemons) be allowed to dump
core? The empty value (the default) means they are not
allowed to. This feature is currently not yet supported
by ipsec starter.
plutostart whether to start the IKEv1 Pluto daemon or not. Accepted
values are yes (the default) or no.
defines if a fresh CRL must be available in order for the
peer authentication based on RSA signatures to succeed.
Accepted values are yes and no (the default). IKEv2
additionally recognizes ifuri which reverts to yes if at
least one CRL URI is defined and to no if no URI is
uniqueids whether a particular participant ID should be kept
unique, with any new (automatically keyed) connection
using an ID from a different IP address deemed to replace
all old ones using that ID; acceptable values are yes
(the default) and no. Participant IDs normally are
unique, so a new (automatically-keyed) connection using
the same ID is almost invariably intended to replace an
old one. The IKEv2 daemon also accepts the value replace
wich is identical to yes and the value keep to reject new
IKE_SA setups and keep the duplicate established earlier.
The following config section parameters are used by the IKEv1 Pluto
interval in seconds. CRL fetching is enabled if the value is
greater than zero. Asynchronous, periodic checking for fresh
CRLs is currently done by the IKEv1 Pluto daemon only.
interval in seconds between NAT keep alive packets, the default
being 20 seconds.
activates NAT traversal by accepting source ISAKMP ports
different from udp/500 and being able of floating to udp/4500 if
a NAT situation is detected. Accepted values are yes and no
no certificate request payloads will be sent. Accepted values
are yes and no (the default). Used by IKEv1 only, NAT traversal
always being active in IKEv2.
non-standard argument string for PKCS#11 C_Initialize()
function; required by NSS softoken.
defines the path to a dynamically loadable PKCS #11 library.
PKCS #11 login sessions will be kept during the whole lifetime
of the keying daemon. Useful with pin-pad smart card readers.
Accepted values are yes and no (the default).
Pluto will act as a PKCS #11 proxy accessible via the whack
interface. Accepted values are yes and no (the default).
how much Pluto debugging output should be logged. An empty
value, or the magic value none, means no debugging output (the
default). The magic value all means full output. Otherwise
only the specified types of output (a quoted list, names without
the --debug- prefix, separated by white space) are enabled; for
details on available debugging types, see pluto(8).
Pluto will not use syslog, but rather log to stderr, and
redirect stderr to the argument file.
shell command to run after starting Pluto (e.g., to remove a
decrypted copy of the ipsec.secrets file). It’s run in a very
simple way; complexities like I/O redirection are best hidden
within a script. Any output is redirected for logging, so
running interactive commands is difficult unless they use
/dev/tty or equivalent for their interaction. Default is none.
shell command to run before starting Pluto (e.g., to decrypt an
encrypted copy of the ipsec.secrets file). It’s run in a very
simple way; complexities like I/O redirection are best hidden
within a script. Any output is redirected for logging, so
running interactive commands is difficult unless they use
/dev/tty or equivalent for their interaction. Default is none.
defines private networks using a wildcard notation.
The following config section parameters are used by the IKEv2 Charon
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, enc, lib and the level is one
of -1, 0, 1, 2, 3, 4 (for silent, audit, control, controlmore,
The following config section parameters only make sense if the KLIPS
IPsec stack is used instead of the default NETKEY stack of the Linux
whether a tunnel’s need to fragment a packet should be reported
back with an ICMP message, in an attempt to make the sender
lower his PMTU estimate; acceptable values are yes (the default)
whether a tunnel packet’s TOS field should be set to 0 rather
than copied from the user packet inside; acceptable values are
yes (the default) and no
virtual and physical interfaces for IPsec to use: a single
virtual=physical pair, a (quoted!) list of pairs separated by
white space, or %none. One of the pairs may be written as
%defaultroute, which means: find the interface d that the
default route points to, and then act as if the value was
‘‘ipsec0=d’’. %defaultroute is the default; %none must be used
to denote no interfaces.
value that the MTU of the ipsecn interface(s) should be set to,
overriding IPsec’s (large) default.
CHOOSING A CONNECTION
When choosing a connection to apply to an outbound packet caught with a
%trap, the system prefers the one with the most specific eroute that
includes the packet’s source and destination IP addresses. Source
subnets are examined before destination subnets. For initiating, only
routed connections are considered. For responding, unrouted but added
connections are considered.
When choosing a connection to use to respond to a negotiation which
doesn’t match an ordinary conn, an opportunistic connection may be
instantiated. Eventually, its instance will be /32 -> /32, but for
earlier stages of the negotiation, there will not be enough information
about the client subnets to complete the instantiation.
ipsec(8), pluto(8), starter(8), ttoaddr(3), ttodata(3)
Written for the FreeS/WAN project by Henry Spencer. Extended for
the strongSwan project <http://www.strongswan.org> by Andreas Steffen.
IKEv2-specific features by Martin Willi.
If conns are to be added before DNS is available, left=FQDN will fail.
27 Jun 2007 IPSEC.CONF(5)