NAME
ipsec.conf - IPsec configuration and connectionsDESCRIPTION
The ipsec.conf file specifies most configuration and control information for the Libreswan IPsec subsystem. (The major exception is secrets for authentication; see ipsec.secrets(5).) Its contents are not security-sensitive. Configurations can be added using this configuration file or by using ipsec whack directly. This means that technically, the ipsec.conf file is optional, but a few warnings might show up when this file is missing. ipsec.conf 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 that are not within a section. A line that 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 that contains 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 /etc/ipsec.d/*.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 and alsoflip parameters (described below) which permit splitting a single logical section (e.g. a connection description) into several distinct sections. The first significant line of the file may specify a version of this specification for backwards compatibility with freeswan and openswan. It is ignored and unused. For compatibility with openswan, specify: version 2 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 that 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 that 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 parameter=value (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 section. 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 that is available in any type of section: alsothe 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.) This allows, for example, keeping the encryption
keys for a connection in a separate file from the rest of the description, by
using both an also parameter and an include line. (Caution, see
BUGS below for some restrictions.)
alsoflip
can be used in a conn section. It acts
like an also that flips the referenced section's entries
left-for-right.
Parameter names beginning with x- (or X-, or x_, or
X_) are reserved for user extensions and will never be assigned
meanings by IPsec. Parameters with such names must still observe the syntax
rules (limits on characters used in the name; no white space in a non-quoted
value; no newlines or double quotes within the value). All other as-yet-unused
parameter names are reserved for future IPsec improvements.
A section with name %default specifies defaults for sections of the same
type. For each parameter in it, any section of that type that 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.
%default sections may not contain also or alsoflip
parameters.
Currently there are two types of section: a config section specifies
general configuration information for IPsec, while a conn section
specifies an IPsec connection.
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 to ipsec_auto(8) Here's a simple example:conn snt left=10.11.11.1 leftsubnet=10.0.1.0/24 leftnexthop=172.16.55.66 leftsourceip=10.0.1.1 right=192.168.22.1 rightsubnet=10.0.2.0/24 rightnexthop=172.16.88.99 rightsourceip=10.0.2.1 keyingtries=%forever
CONN PARAMETERS: GENERAL
The following parameters are relevant to IKE automatic keying. 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. keyexchangemethod of key exchange; the default and
currently the only accepted value is ike
hostaddrfamily
the address family of the hosts; currently the
accepted values are ipv4 and ipv6. The default is to detect this
based on the IP addresses specified or the IP addresses resolved, so this
option is not needed, unless you specify hostnames that resolve to both IPv4
and IPv6. This option used to be named connaddrfamily but its use was broken
so it was obsoleted in favour or using the new hostaddrfamily and
clientaddrfamily.
clientaddrfamily
the address family of the clients (subnets);
currently the accepted values are ipv4 and ipv6. The default is
to detect this based on the network IP addresses specified or the network IP
addresses resolved, so this option is not needed, unless you specify names
that resolve to both IPv4 and IPv6.
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.
left
(required) the IP address or DNS hostname of
the left participant's public-network interface, Currently, IPv4 and IPv6 IP
addresses are supported. If a DNS hostname is used, it will be resolved to an
IP address on load time, and whenever a connection is rekeying or restarting
(such as when restarted via a DPD failure detection). This allows one to use a
DNS hostname when the endpoint is on a dynamic IP address.
There are 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); this also overrides any value
supplied for leftnexthop. (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 value
%opportunistic signifies that both left and leftnexthop
are to be filled in (by automatic keying) from DNS data for left's
client. The value can also contain the interface name, which will then later
be used to obtain the IP address from to fill in. For example %ppp0.
The values %group and %opportunisticgroup makes this a policy
group conn: one that will be instantiated into a regular or opportunistic conn
for each CIDR block listed in the policy group file with the same name as the
conn.
If using IP addresses in combination with NAT, always use the actual local
machine's (NATed) IP address, and if the remote (eg right=) is NATed as well,
the remote's public ( not NATed) IP address. Note that this makes the
configuration no longer symmetrical on both sides, so you cannot use an
identical configuration file on both hosts.
leftsubnet
private subnet behind the left participant,
expressed as network/netmask (actually, any form
acceptable to ipsec_ttosubnet(3)); Currently, IPv4 and IPv6 ranges are
supported. if omitted, essentially assumed to be left/32, signifying
that the left end of the connection goes to the left participant only
It supports two magic shorthands vhost: and vnet:, which can list
subnets in the same syntax as virtual-private. The value %priv
expands to the networks specified in virtual-private. The value
%no means no subnet. A common use for allowing roadwarriors to come in
on public IPs or via accepted NATed networks from RFC1918 is to use
leftsubnet=vhost:%no,%priv. The vnet: option can be used to
allow RFC1918 subnets without hardcoding them. When using vnet the connection
will instantiate, allowing for multiple tunnels with different subnets.
leftsubnets
specify multiple private subnets behind the
left participant, expressed as { networkA/netmaskA,
networkB /netmaskB [...] } If both a leftsubnets=
and rightsubnets= are defined, all combinations of subnet tunnels will be
established as IPsec tunnels. You cannot use leftsubnet= and leftsubnets=
together. For examples see testing/pluto/multinet-*. Be aware that when
using spaces as separator, that the entire option value needs to be in double
quotes.
leftvti
the address/mask to configure on the VTI
interface when vti-interface is set. It takes the form of
network /netmask (actually, any form acceptable to
ipsec_ttosubnet(3)); Currently, IPv4 and IPv6 ranges are supported.
This option is often used in combination with routed based VPNs.
leftaddresspool
address pool from where the IKEv1 ModeCFG or
IKEv2 server can assign IP addresses to clients. When configured as a server,
using leftxauthserver=yes this option specifies the address pool from
which IP addresses are taken to assign the clients. The syntax of the address
pool specifies a range (not a CIDR) for IPv4 and CIDR for IPv6, in the
following syntax: rightaddresspool=192.168.1.100-192.168.1.200 or
rightaddresspool=2001:db8:0:3:1::/97 Generally, the
rightaddresspool= option will be accompanied by
rightxauthclient=yes, leftxauthserver=yes and
leftsubnet=0.0.0.0/0 option.
When leftaddresspool= is specified, the connection may not specify either
leftsubnet= or leftsubnets=. Address pools are fully allocated
when the connection is loaded, so the ranges should be sane. For example,
specifying a range rightaddresspool=10.0.0.0-11.0.0.0 will lead to
massive memory allocation. Address pools specifying the exact same range are
shared between different connections. Different addresspools should not be
defined to partially overlap.
leftprotoport
allowed protocols and ports over connection,
also called Port Selectors. The argument is in the form protocol, which
can be a number or a name that will be looked up in /etc/protocols,
such as leftprotoport=icmp, or in the form of protocol/port,
such as tcp/smtp. Ports can be defined as a number (eg. 25) or as a
name (eg smtp) which will be looked up in /etc/services. A special
keyword %any can be used to allow all ports of a certain protocol. The
most common use of this option is for L2TP connections to only allow l2tp
packets (UDP port 1701), eg: leftprotoport=17/1701.
To filter on specific icmp type and code, use the higher 8 bits for type and the
lower 8 bits for port. For example, to allow icmp echo packets (type 8, code
0) the 'port' would be 0x0800, or 2048 in decimal, so you configure
leftprotoport=icmp/2048. Similarly, to allow ipv6-icmp Neighbour
Discovery which has type 136 (0x88) and code 0(0x00) this becomes 0x8800 or in
decimal 34816 resulting in leftprotoport=ipv6-icmp/34816 .
Some clients, notably older Windows XP and some Mac OSX clients, use a random
high port as source port. In those cases rightprotoport=17/%any can be
used to allow all UDP traffic on the connection. Note that this option is part
of the proposal, so it cannot be arbitrarily left out if one end does not care
about the traffic selection over this connection - both peers have to agree.
The Port Selectors show up in the output of ipsec eroute and ipsec
auto --status eg: "l2tp":
193.110.157.131[@aivd.libreswan.org]:7/1701...%any:17/1701 This option
only filters outbound traffic. Inbound traffic selection must still be based
on firewall rules activated by an updown script. The variables
$PLUTO_MY_PROTOCOL, $PLUTO_PEER_PROTOCOL, $PLUTO_MY_PORT, and $PLUTO_PEER_PORT
are available for use in updown scripts. Older workarounds for bugs
involved a setting of 17/0 to denote any single UDP port (not
UDP port 0). Some clients, most notably OSX, uses a random high port, instead
of port 1701 for L2TP.
leftnexthop
next-hop gateway IP address for the left
participant's connection to the public network; defaults to %direct
(meaning right). If the value is to be overridden by the
left=%defaultroute method (see above), an explicit value must
not be given. If that method is not being used, but leftnexthop
is %defaultroute, the next-hop gateway address of the default-route
interface will be used. The magic value %direct signifies a value to be
filled in (by automatic keying) with the peer's address. Relevant only
locally, other end need not agree on it.
leftsourceip
the IP address for this host to use when
transmitting a packet to the other side of this link. Relevant only locally,
the other end need not agree. This option is used to make the gateway itself
use its internal IP, which is part of the leftsubnet, to communicate to the
rightsubnet or right. Otherwise, it will use its nearest IP address,
which is its public IP address. This option is mostly used when defining
subnet-subnet connections, so that the gateways can talk to each other and the
subnet at the other end, without the need to build additional host-subnet,
subnet-host and host-host tunnels. Both IPv4 and IPv6 addresses are
supported.
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. An example to enable routing when
using the XFRM stack, one can use:
leftupdown="ipsec _updown --route yes"
To disable calling an updown script, set it to the empty string, eg
leftupdown="" or leftupdown="%disabled".
See ipsec_pluto(8) for details. Relevant only locally, other end need not
agree on it.
leftcat
Whether to perform Client Address Translation
("CAT") when using Opportunistic IPsec behind NAT. Accepted values
are no (the default) and yes. This option should only be enabled
on the special Opportunistic IPsec connections, usually called
"private" and "private-or-clear". When set, this option
causes the given addresspool IP from the remote peer to be NATed with
iptables. It will also install an additional IPsec SA policy to cover the
pre-NAT IP. See the Opportunistic IPsec information on the libreswan website
for more information and examples.
leftfirewall
This option is obsolete and should not used
anymore.
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 updown script (see ipsec_pluto(8)).
The implementation of this makes certain assumptions about firewall setup, and
the availability of the Linux Advanced Routing tools. 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.
CONN PARAMETERS: AUTOMATIC KEYING
The following parameters are relevant to automatic keying via IKE. 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. autowhat operation, if any, should be done
automatically at IPsec startup; currently-accepted values are add
(signifying an ipsec auto --add), ondemand (signifying
that plus an ipsec auto --ondemand), start (signifying
that plus an ipsec auto --up), and ignore (also the
default) (signifying no automatic startup operation), and keep
(signifying an add plus an attempt to keep the connection up once the remote
peer brought it up). See the config setup discussion below. 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 renegotiation).
The option ondemand used to be called route
authby
how the two security gateways should
authenticate each other; the default value is rsasig,ecdsa which allows
ECDSA with SHA-2 and RSA with SHA2 or SHA1. To limit this further, there are
the options of ecdsa for ECDSA digital signatures using SHA-2,
rsa-sha2 for RSASSA-PSS digital signatures based authentication with
SHA2-256, rsa-sha2_384 for RSASSA-PSS digital signatures based
authentication with SHA2-384, rsa-sha2_512 for RSASSA-PSS digital
signatures based authentication with SHA2-512, rsa-sha1 for
RSA-PKCSv1.5 digital signatures based authentication with SHA1, secret
for shared secrets (PSK) authentication, secret|rsasig for either,
never if negotiation is never to be attempted or accepted (useful for
shunt-only conns), and null for null-authentication.
If asymmetric authentication is requested, IKEv2 must be enabled, and the
options leftauth= and rightauth= should be used instead of
authby.
For IKEv1, SHA2 based signatures are not defined and ECDSA is not implemented,
so the default authby= value is rsa-sha1. Using authby=rsasig results in only
rsa-sha1 as well. For IKEv2, using authby=rsasig means using rsa-sha2_512,
rsa-sha2_384, rsa-sha2_256 and rsa-sha1, where rsa-sha1 will used only if RFC
7427 is not supported by the peer.
As per RFC 8221, authby=rsa-sha1 is only supported in the old style, meaning
RSA-PKCSv1.5. The SHA2 variants are only supported for the new style of RFC
7427, so authby=rsa-sha2 will use the new style. The default authby= will
remove rsa-sha1 in the near future. It is strongly recommended that if
certificates are used, the certificates and the authby= signature methods used
are the same, as it increases interoperability and keeps the authentication of
everything within one digital signature system.
Digital signatures are superior in every way to shared secrets. Especially IKEv1
in Aggressive Mode is vulnerable to offline dictionary attacks and is
performed routinely by at least the NSA on monitored internet traffic
globally. The never option is only used for connections that do not actually
start an IKE negotiation, such as type=passthrough connections. The auth
method null is used for "anonymous opportunistic IPsec" and should
not be used for regular pre-configured IPsec VPNs.
ike
IKE encryption/authentication algorithm to be
used for the connection (phase 1 aka ISAKMP SA or IKE SA). If this option is
not set, the builtin defaults will be used. This is the preferred method, and
allows for gradual automatic updates using the same configuration. Some
distributions, such as Fedora and RHEL/CentOS, use a System Wide Crypto Policy
that sets the default ike= (and esp=) lines. Specifying your own ike= line
means overriding all these system or software recommended defaults, but can be
necessary at times. Note that libreswan does not support using a PRF algorithm
that is different from the INTEGRITY (hash) algorithm by design.
The format is "cipher-hash;modpgroup, cipher-hash;modpgroup,
..." Any omitited option will be filled in with all allowed
default values. Multiple proposals are separated by a comma. If an ike=
line is specified, no other received proposals will be accepted than those
specified on the IKE line. Some examples are ike=3des-sha1,aes-sha1,
ike=aes, ike=aes_ctr, ike=aes_gcm256-sha2,
ike=aes128-md5;modp2048, ike=aes256-sha2;dh19,
ike=aes128-sha1;dh22, ike=3des-md5;modp1024,aes-sha1;modp1536.
IKEv2 allows combining elements into a single proposal. These can be specified
by using the + symbol. An example is:
ike=aes_gcm+chacha20_poly1305;dh14+dh19,aes+3des-sha2+sha1;dh14. Note
that AEAD algorithms (aes_gcm, aes_ccm, chacha20_poly1305) and non-AEAD
algorithms (aes, 3des) cannot be combined into a single proposal. To support
aes and aes_gcm, two proposals separated by a comma must be used.
The default IKE proposal depends on the version of libreswan used. It follow the
recommendations of RFC4306, RFC7321 and as of this writing their successor
draft documents RFC4306bis and RFC7321bis. As for libreswan 3.32, SHA1 and
MODP1536(dh5) are still allowed per default for backwards compatibility, but
3DES and MODP1024(dh2) are not allowed per default. As of libreswan 4.x,
modp1024(dh2) support is no longer compiled in at all. For IKEv2, the defaults
include AES, AES-GCM, DH14 and stronger, and SHA2. The default key size is 256
bits. The default AES_GCM ICV is 16 bytes.
Note that AES-GCM is an AEAD algorithm, meaning that it performs
encryption+authentication in one step. This means that AES-GCM must not
specify an authentication algorithm. However, for IKE it does require a PRF
function, so the second argument to an AEAD algorithm denotes the PRF. So
ike=aes_gcm-sha2 means propose AES_GCM with SHA2 as the prf. Note that for
phase2alg, there is no prf, so AES-GCM is specified for ESP as
esp=aes_gcm-null. The AES-GCM and AES-CCM algorithms support 8,12 and 16 byte
ICV's. These can be specified using a postfix, for example aes_gcm_a (for 8),
aes_gcm_b (for 12) and aes_gcm_c (for 16). The default (aes_gcm without
postfix) refers to the 16 byte ICV version. It is strongly recommended to NOT
use the 8 or 12 byte versions of GCM or CCM. These versions are NOT included
in the default and will be removed in a future version, following the
recommendation of RFC 8247 or it successor.
Weak algorithms are regularly removed from libreswan. Currently, 1DES and
modp768(DH1) have been removed and modp1024(DH2) has been disabled at compile
time. Additionally, MD5 and SHA1 will be removed within the next few years.
Null encryption is available, and should only be used for testing or
benchmarking purposes. Please do not request for insecure algorithms to be
re-added to libreswan. IKEv1 has been disabled per default, and will soon no
longer be compiled in by default.
For all Diffie-Hellman groups, the "dh" keyword can be used instead of
the "modp" keyword. For example ike=3des-sha1;dh19.
Diffie-Hellman groups 19,20 and 21 from RFC-5903 are supported. Curve25519
from RFC-8031 is supported as "dh31". Curve448 and GOST DH groups
are not yet supported in libreswan because these are not supported yet in the
NSS crypto library.
Diffie-Hellman groups 22, 23 and 24 from RFC-5114 are implemented but not
compiled in by default. These DH groups are extremely controversial and MUST
NOT be used unless forced (administratively) by the other party. This is
further documented in RFC 8247, but the summary is that it cannot be proven
that these DH groups do not contain a cryptographic trapdoor (a backdoor by
the USG who provided these primes without revealing the seeds and generation
process used).
The modp syntax will be removed in favour of the dh syntax in the future
phase2
Sets the type of SA that will be produced.
Valid options are: esp for encryption (the default), ah for
authentication only.
The very first IPsec designs called for use of AH plus ESP to offer
authentication, integrity and confidentiality. That dual protocol use was a
significant burden, so ESP was extended to offer all three services, and AH
remained as an auth/integ. The old mode of ah+esp is no longer
supported in compliance with RFC 8221 Section 4. Additionally, AH does not
play well with NATs, so it is strongly recommended to use ESP with the null
cipher if you require unencrypted authenticated transport.
phase2alg
This option is alias to esp.
sha2-truncbug
The default ESP hash truncation for sha2_256
is 128 bits. Some IPsec implementations (Linux before 2.6.33, some Cisco
(2811?) routers) implement the draft version which stated 96 bits. If a draft
implementation communicates with an RFC implementation, both ends will reject
encrypted packets from each other.
This option enables using the draft 96 bits version to interop with those
implementations. Currently the accepted values are no, (the default)
signifying default RFC truncation of 128 bits, or yes, signifying the
draft 96 bits truncation.
Another workaround is to switch from sha2_256 to sha2_128 or sha2_512.
ms-dh-downgrade
Whether to allow a downgrade of DiffieHellman
group during rekey (using CREATE_CHILD_SA). Microsoft Windows (at the time of
writing, Feb 2018) defaults to using the very weak modp1024 (DH2). This can be
changed using a Windows registry setting to use modp2048 (DH14). However, at
rekey times, it will shamelessly use modp1024 again and the connection might
fail. Setting this option to yes (and adding modp1024 proposals to the ike
line) this will allow this downgrade attack to happen. This should only be
used to support Windows that feature this bug. Currently the accepted values
are no, (the default) or yes.
dns-match-id
Whether to perform an additional DNS lookup
and confirm the remote ID payload with the DNS name in the reverse DNS PTR
record. Accepted values are no (the default) or yes. This check
should be enabled when Opportunistic IPsec is enabled in a mode that is based
on packet triggers (on-demand) using IPSECKEY records in DNS. Since in that
case the IKE daemon pluto does not know the remote ID, it only knows the
remote IP address, this option forces it to confirm the peer's proposed ID
(and thus its public/private key) with its actual IP address as listed in the
DNS. This prevents attacks where mail.example.com's IP address is taken over
by a neighbour machine with a valid web.example.com setup. This check is not
needed for certificate based Opportunistic IPsec, as
"mail.example.com"s certificate does not have an entry for
"web.example.com". It is also not needed for DNS server triggered
Opportunistic IPsec, as in that case the IKE daemon pluto is informed of both
the IP address, and the hostname/public key.
require-id-on-certificate
When using certificates, check whether the IKE
peer ID is present as a subjectAltName (SAN) on the peer certificate. Accepted
values are yes (the default) or no. This check should only be
disabled when intentionally using certificates that do not have their peer ID
specified as a SAN on the certificate. These certificates violate RFC 4945
Section 3.1 and are normally rejected to prevent a compromised host from
assuming the IKE identity of another host. The SAN limits the IDs that the
peer is able to assume.
ppk
EXPERIMENTAL: Post-quantum preshared keys
(PPKs) to be used. Currently the accepted values are propose or
yes (the default), signifying we propose to use PPK for this
connection; insist, signifying we allow communication only if PPK is
used for key derivation; never or no, signifying that PPK should
not be used for key derivation. PPKs can be used in connections that allow
only IKEv2. In libreswan that would mean that ikev2 option must have value
insist. (currently based on draft-fluhrer-qr-ikev2, not
raft-ietf-ipsecme-qr-ikev2-00)
nat-ikev1-method
NAT Traversal in IKEv1 is negotiated via
Vendor ID options as specified in RFC 3947. However, many implementations only
support the draft version of the RFC. Libreswan sends both the RFC and the
most common draft versions (02, 02_n and 03) to maximize interoperability.
Unfortunately, there are known broken implementations of RFC 3947, notably
Cisco routers that have not been updated to the latest firmware. As the NAT-T
payload is sent in the very first packet of the initiator, there is no method
to auto-detect this problem and initiate a workaround.
This option allows fine tuning which of the NAT-T payloads to consider for
sending and processing. Currently the accepted values are drafts,
rfc, both (the default) and none. To interoperate with
known broken devices, use nat-ikev1-method=drafts. To prevent the other end
from triggering IKEv1 NAT-T encapsulation, set this to none. This will omit
the NAT-T payloads used to determine NAT, forcing the other end not to use
encapsulation.
esp
Specifies the algorithms that will be
offered/accepted when negotiating a a Child SA. The general syntax is:
During startup, ipsec_pluto(8) will log all supported ESP algorithms.
Specifying the DH algorithms explicitly is not recommended. When PFS is
enabled, and the DH algorithms are omitted, each PROPOSAL will automatically
include the DH algorithm negotiated during the IKE exchange.
AEAD algorithms such as AES_GCM and AES_CCM no not require a separate integrity
algorithm. For example esp=aes_gcm256 or esp=aes_ccm.
For instance:
If not specified, a secure set of defaults will be used. The program:
can be used to query these defaults.
ah
ESP = PROPOSAL[,PROPOSAL...]
PROPOSAL = ENCRYPT_ALGS[-INTEG_ALGS[-DH_ALGS]]
ENCRYPT_ALGS = ENCRYPT_ALG[+ENCRYPT_ALG...]
INTEG_ALGS = INTEG_ALG[+INTEG_ALG...]
DH_ALGS = DH_ALG[+DH_ALG...]
esp=aes_gcm,aes128+aes256-sha2_512+sha2_256-dh14+dh19
esp=aes128-sha2_512-dh14+dh19
ipsec algparse esp=...
A comma separated list of AH algorithms that
will be offered/accepted when negotiating the Child SA. The general syntax is:
During startup, ipsec_pluto(8) will log all supported AH algorithms.
Specifying the DH algorithms explicitly is not recommended. When PFS is
enabled, and the DH algorithms are omitted, each PROPOSAL will automatically
include the DH algorithm negotiated during the IKE exchange.
The default is not to use AH. If for some (invalid) reason you still think you
need AH, please use esp with the null encryption cipher instead.
For instance:
If not specified, a secure set of defaults will be used. The program:
can be used to query these defaults.
fragmentation
AH = PROPOSAL[,PROPOSAL...]
PROPOSAL = INTEG_ALGS[-DH_ALGS]
INTEG_ALGS = INTEG_ALG[+INTEG_ALG...]
DH_ALGS = DH_ALG[+DH_ALG...]
ah=sha2_256+sha2_512
ah=sha2_256+sha2_512-dh14+dh19
ipsec algparse ah=...
Whether or not to allow IKE fragmentation.
Valid values are yes, (the default), no or force.
IKEv1 fragmentation capabilities are negotiated via a well-known private
vendor id. IKEv2 fragmentation support is implemented using RFC 7383.
If pluto does not receive the fragmentation payload, no IKE fragments will be
sent, regardless of the fragmentation= setting. When set to yes, IKE
fragmentation will be attempted on the first re-transmit of an IKE packet of a
size larger then 576 bytes for IPv4 and 1280 bytes for IPv6. If fragmentation
is set to force, IKE fragmentation is used on initial transmits of such sized
packets as well. When we have received IKE fragments for a connection, pluto
behaves as if in force mode.
ikepad
Whether or not to pad IKEv1 messages to a
multiple of 4 bytes. Valid values are yes, (the default) and no.
IKE padding is allowed in IKEv1 but has been known to cause interoperability
issues. The ikepad= option can be used to disable IKEv1 padding. This used to
be required for some devices (such as Checkpoint in Aggressive Mode) that
reject padded IKEv1 packets. A bug was fixed in libreswan 3.25 that applied
wrong IKE padding in XAUTH, so it is suspected that Checkpoint padding issue
bas been resolved. And this option should not be needed by anyone. In IKEv2,
no padding is allowed, and this option has no effect. If you find a device
that seems to require IKE padding, please contact the libreswan developers.
This option should almost never be enabled and might be removed in a future
version.
ikev2
Whether to use IKEv2 (RFC 7296) or IKEv1 (RFC
4301). Currently the accepted values are yes (the default), signifying
only IKEv2 is accepted, or no, signifying only IKEv1 is accepted.
Previous versions allowed the keywords propose or permit that
would allow either IKEv1 or IKEv2, but this is no longer supported. The permit
option is interpreted as no and the propose option is interpreted as yes.
Older versions also supported keyword insist which is now interpreted
as yes.
mobike
Whether to allow MOBIKE (RFC 4555) to enable a
connection to migrate its endpoint without needing to restart the connection
from scratch. This is used on mobile devices that switch between wired,
wireless or mobile data connections. Current values are no (the
default) or yes, Only connection acting as modecfgclient will allow the
initiator to migrate using mobike. Only connections acting as modecfgserver
will allow clients to migrate.
VTI and MOBIKE might not work well when used together.
esn
Whether or not to enable Extended Sequence
Number (ESN) for the IPsec SA. This option is only implemented for IKEv2. ESN
is typically used for very high-speed links (10Gbps or faster) where the
standard 32 bit sequence number is exhausted too quickly, causing IPsec SA's
rekeys to happen too often. Accepted values are either (the default),
yes and no. If either is specified as an initiator, the
responder will make the choice. As a responder, if either is received,
yes is picked.
If replay-window is set to 0, ESN is disabled as some (most?) IPsec stacks won't
support ESN in such a configuration.
decap-dscp
Enable decapsulating the Differentiated
Services Code Point (DSCP, formerly known as Terms Of Service (TOS)) bits. If
these bits are set on the inner (encrypted) IP packets, these bits are set on
the decrypted IP packets. Acceptable values are no (the default) or
yes. Currently this feature is only implemented for the Linux XFRM
stack.
nopmtudisc
Disable Path MTU discovery for the IPsec SA.
Acceptable values are no (the default) or yes. Currently this
feature is only implemented for the Linux XFRM stack.
narrowing
IKEv2 (RFC5996) Section 2.9 Traffic Selector
narrowing options. Currently the accepted values are no, (the default)
signifying no narrowing will be proposed or accepted, or yes,
signifying IKEv2 negotiation may allow establishing an IPsec connection with
narrowed down traffic selectors. This option is ignored for IKEv1.
There are security implications in allowing narrowing down the proposal. For
one, what should be done with packets that we hoped to tunnel, but cannot.
Should these be dropped or send in the clear? Second, this could cause
thousands of narrowed down Child SAs to be created if the conn has a broad
policy (eg 0/0 to 0/0). One possible good use case scenario is that a remote
end (that you fully trust) allows you to define a 0/0 to them, while adjusting
what traffic you route via them, and what traffic remains outside the tunnel.
However, it is always preferred to setup the exact tunnel policy you want, as
this will be much clearer to the user.
sareftrack
Set the method of tracking reply packets with
SArefs when using an SAref compatible stack. Currently only the mast
stack supports this. Acceptable values are yes (the default), no
or conntrack. This option is ignored when SArefs are not supported.
This option is passed as PLUTO_SAREF_TRACKING to the updown script
which makes the actual decisions whether to perform any iptables/ip_conntrack
manipulation. A value of yes means that an IPSEC mangle table will be created.
This table will be used to match reply packets. A value of conntrack means
that additionally, subsequent packets using this connection will be marked as
well, reducing the lookups needed to find the proper SAref by using the
ip_conntrack state. A value of no means no IPSEC mangle table is created, and
SAref tracking is left to a third-party (kernel) module. In case of a third
party module, the SArefs can be relayed using the statsbin=
notification helper.
nic-offload
Set the method of Network Interface Controller
(NIC) hardware offload for ESP/AH packet processing. Acceptable values are
auto (the default), yes or no. This option is separate
from any CPU hardware offload available and is currently only available on
Linux 4.13+ using the XFRM IPsec stack, when compiled with the options
CONFIG_XFRM_OFFLOAD, CONFIG_INET_ESP_OFFLOAD and CONFIG_INET6_ESP_OFFLOAD. The
auto option will attempt to auto-detect the presence of kernel and hardware
support, and then automatically mark the IPsec SA for hardware offloading. One
vendor supporting this offload method is Mellanox.
leftid
how the left participant should be identified
for authentication; defaults to left. Can be an IP address or a
fully-qualified domain name which will be resolved. If preceded by @,
the value is used as a literal string and will not be resolved. To support
opaque identifiers (usually of type ID_KEY_ID, such as used by Cisco to
specify Group Name, use square brackets, eg rightid=@[GroupName]. The
magic value %fromcert causes the ID to be set to a DN taken from a
certificate that is loaded. Prior to 2.5.16, this was the default if a
certificate was specified. The magic value %none sets the ID to no ID.
This is included for completeness, as the ID may have been set in the default
conn, and one wishes for it to default instead of being explicitly set. The
magic value %myid stands for the current setting of myid. This
is set in config setup or by ipsec_whack(8)), or, if not set, it
is the IP address in %defaultroute (if that is supported by a TXT
record in its reverse domain), or otherwise it is the system's hostname (if
that is supported by a TXT record in its forward domain), or otherwise it is
undefined.
When using certificate based ID's, one need to specify the full RDN, optionally
using wildcard matching (eg CN='*'). If the RDN contains a comma, this can be
masked using a comma (eg OU='Foo,, Bar and associates')
leftrsasigkey
the left participant's public key for RSA
signature authentication, in RFC 2537 format using ipsec_ttodata(3)
encoding. The magic value %none means the same as not specifying a
value (useful to override a default). The value %dnsondemand (the
default) means the key is to be fetched from DNS at the time it is needed. The
value %dnsonload means the key is to be fetched from DNS at the time
the connection description is read from ipsec.conf; currently this will
be treated as %none if right=%any or
right=%opportunistic. The value %dns is currently treated as
%dnsonload but will change to %dnsondemand in the future. The
identity used for the left participant must be a specific host, not
%any or another magic value. The value %cert will load the
information required from a certificate defined in %leftcert and
automatically define leftid for you. Caution: if two connection
descriptions specify different public keys for the same leftid,
confusion and madness will ensue.
leftcert
If you are using leftrsasigkey=%cert
this defines the certificate nickname of your certificate in the NSS database.
This can be on software or hardware security device.
leftckaid
The hex CKAID of the X.509 certificate.
Certificates are stored in the NSS database.
leftauth
How the security gateways will authenticate to
the other side in the case of asymmetric authentication; acceptable values are
rsasig or rsa for RSA Authentication with SHA-1, rsa-sha2
for RSA-PSS digital signatures based authentication with SHA2-256,
rsa-sha2_384 for RSA-PSS digital signatures based authentication with
SHA2-384, rsa-sha2_512 for RSA-PSS digital signatures based
authentication with SHA2-512, ecdsa for ECDSA digital signatures based
authentication, secret for shared secrets (PSK) authentication and
null for null-authentication. There is no default value - if unset, the
symmetrical authby= keyword is used to determine the authentication
policy of the connection.
Asymmetric authentication is only supported with IKEv2. If symmetric
authentication is required, use authby= instead of leftauth and
rightauth. If leftauth is set, rightauth must also be set and authby= must not
be set. Asymmetric authentication cannot use secret (psk) on one side and null
on the other side - use psk on both ends instead.
When using EAPONLY authentication, which omits the regular IKEv2 AUTH payload,
leftauth= (or rightauth=) should be set to eaponly.
Be aware that the symmetric keyword is authby= but the asymmetric keyword
is leftauth and rightauth (without the "by").
leftautheap
Whether the security gateways will
authenticate uing an EAP method. Acceptable values are none (the
default) and tls for EAPTLS. If EAP is the only authentication method,
set leftauth=none in addition to leftautheap=tls=.
The EAP authentication mechanisms are only available for IKEv2 based
connections.
leftca
specifies the authorized Certificate Authority
(CA) that signed the certificate of the peer. If undefined, it defaults to the
CA that signed the certificate specified in leftcert. The special
rightca=%same is implied when not specifying a rightca and means
that only peers with certificates signed by the same CA as the leftca will be
allowed. This option is only useful in complex multi CA certificate
situations. When using a single CA, it can be safely omitted for both left and
right.
leftikeport
The UDP IKE port to listen on or send data to.
This port cannot be 0 or 500. For TCP, see tcp-remoteport=
leftsendcert
This option configures when Libreswan will
send X.509 certificates to the remote host. Acceptable values are
yes|always (signifying that we should always send a certificate),
sendifasked (signifying that we should send a certificate if the remote
end asks for it), and no|never (signifying that we will never send a
X.509 certificate). The default for this option is sendifasked which
may break compatibility with other vendor's IPsec implementations, such as
Cisco and SafeNet. If you find that you are getting errors about no ID/Key
found, you likely need to set this to always. This per-conn option
replaces the obsolete global nocrsend option.
leftxauthserver
Left is an XAUTH server. This can use PAM for
authentication or md5 passwords in /etc/ipsec.d/passwd. These are
additional credentials to verify the user identity, and should not be confused
with the XAUTH group secret, which is just a regular PSK defined in
ipsec.secrets. The other side of the connection should be configured as
rightxauthclient. XAUTH connections cannot rekey, so rekey=no
should be specified in this conn. For further details on how to compile and
use XAUTH, see README.XAUTH. Acceptable values are yes or no
(the default).
leftxauthclient
Left is an XAUTH client. The xauth connection
will have to be started interactively and cannot be configured using
auto=start. Instead, it has to be started from the commandline using
ipsec auto --up connname. You will then be prompted for the username
and password. To setup an XAUTH connection non-interactively, which defeats
the whole purpose of XAUTH, but is regularly requested by users, it is
possible to use a whack command - ipsec whack --name baduser
--ipsecgroup-xauth --xauthname badusername --xauthpass password --initiate
The other side of the connection should be configured as
rightxauthserver. Acceptable values are yes or no (the
default).
leftusername
The username associated with this connection.
The username can be the IKEv2 XAUTH username, a GSSAPI username or IKEv2 CP
username. For the XAUTH username, the XAUTH password can be configured in the
ipsec.secrets file. This option was previously called
leftxauthusername.
leftmodecfgserver
Left is a Mode Config server. It can push
network configuration to the client. Acceptable values are yes or
no (the default).
leftmodecfgclient
Left is a Mode Config client. It can receive
network configuration from the server. Acceptable values are yes or
no (the default).
xauthby
When IKEv1 XAUTH support is available, set the
method used by XAUTH to authenticate the user with IKEv1. The currently
supported values are file (the default), pam or alwaysok.
The password file is located at /etc/ipsec.d/passwd, and follows a
syntax similar to the Apache htpasswd file, except an additional connection
name argument (and optional static IP address) are also present:
username:password:conname:ipaddress
For supported password hashing methods, see crypt(3). If pluto is running
in FIPS mode, some hash methods, such as MD5, might not be available. Threads
are used to launch an xauth authentication helper for file as well as PAM
methods.
The alwaysok should only be used if the XAUTH user authentication is not
really used, but is required for interoperability, as it defeats the whole
point of XAUTH which is to rely on a secret only known by a human. See also
pam-authorize=yes
xauthfail
When XAUTH support is available, set the
failure method desired when authentication has failed. The currently supported
values are hard (the default) and soft. A soft failure means the
IPsec SA is allowed to be established, as if authentication had passed
successfully, but the XAUTH_FAILED environment variable will be set to 1 for
the updown script, which can then be used to redirect the user into a walled
garden, for example a payment portal.
pam-authorize
IKEv1 supports PAM authorization via XAUTH
using xauthby=pam. IKEv2 does not support receiving a plaintext
username and password. Libreswan does not yet support EAP authentication
methods for IKE. The pam-authorize=yes option performs an authorization call
via PAM, but only includes the remote ID (not username or password). This
allows for backends to disallow an ID based on non-password situations, such
as "user disabled" or "user over quota". See also
xauthby=pam
modecfgpull
Pull the Mode Config network information from
the server. Acceptable values are yes or no (the default).
modecfgdns, modecfgdomains, modecfgbanner
When configured as IKEv1 ModeCFG or IKEv2
server, specifying any of these options will cause those options and values to
be sent to the connecting client. Libreswan as a client will use these
received options to either update /etc/resolv.conf or the running unbound DNS
server. When the connection is brought down, the previous DNS resolving state
is restored.
The modecfgdns option takes a comma or space separated list of IP addresses that
can be used for DNS resolution. The modecfgdomains option takes a comma or
space separated list of internal domain names that are reachable via the
supplied modecfgdns DNS servers.
The IKEv1 split tunnel directive will be sent automatically if the xauth server
side has configured a network other than 0.0.0.0/0. For IKEv2, this is
automated via narrowing.
remote-peer-type
Set the remote peer type. This can enable
additional processing during the IKE negotiation. Acceptable values are
cisco or ietf (the default). When set to cisco, support for
Cisco IPsec gateway redirection and Cisco obtained DNS and domainname are
enabled. This includes automatically updating (and restoring)
/etc/resolv.conf. These options require that XAUTH is also enabled on this
connection.
nm-configured
Mark this connection as controlled by Network
Manager. Acceptable values are yes or no (the default).
Currently, setting this to yes will cause libreswan to skip reconfiguring
resolv.conf when used with XAUTH and ModeConfig.
encapsulation
In some cases, for example when ESP packets
are filtered or when a broken IPsec peer does not properly recognise NAT, it
can be useful to force RFC-3948 encapsulation. In other cases, where IKE is
NAT'ed but ESP packets can or should flow without encapsulation, it can be
useful to ignore the NAT-Traversal auto-detection. encapsulation=yes
forces the NAT detection code to lie and tell the remote peer that RFC-3948
encapsulation (ESP in port 4500 packets) is required. encapsulation=no
ignores the NAT detection causing ESP packets to send send without
encapsulation. The default value of encapsulation=auto follows the
regular outcome of the NAT auto-detection code performed in IKE. This option
replaced the obsoleted forceencaps option.
enable-tcp
Normally, IKE negotiation and ESP
encapsulation happens over UDP. This option enables support for IKE and ESP
over TCP as per RFC 8229. Acceptable values are no(the default),
yes meaning only TCP will be used, or fallback meaning that TCP
will be attempted only after negotiation over UDP failed. Since performance
over TCP is much less, and TCP sessions are vulnerable to simply RST resets
and MITM attacks causing the TCP connection to close, this option should
really only be used in fallback mode. If used in fallback mode, it is
recommend to reduce the retransmit-timeout from the default 60s to a
much shorter value such as 10s, so that one does not have to wait a minute for
the TCP fallback to be attempted.
tcp-remoteport
Which remote TCP port to use when IKE over TCP
is attempted. The default value is to use the NAT-T IKE port (4500). This
value is not negotiated and should be configured properly on all endpoints.
When opening a TCP socket to the remote host in this port, a regular ephemeral
source port is obtained from the OS. For changing the UDP ports, see
leftikeport=
nat-keepalive
whether to send any NAT-T keep-alives. These
one byte packets are send to prevent the NAT router from closing its port when
there is not enough traffic on the IPsec connection. Acceptable values are:
yes (the default) and no.
initial-contact
whether to send an INITIAL_CONTACT payload to
the peer we are initiating to, if we currently have no IPsec SAs up with that
peer. Acceptable values are: yes (the default) and no. It is
recommended to leave this option set, unless multiple clients with the same
identity are expected to connect using the same subnets and should operate at
the same time. Or if a reconnecting client should not delete its old instance
(eg perhaps it is still running). This is unlikely to be true.
cisco-unity
whether to send a CISCO_UNITY payload to the
peer. Acceptable values are: no (the default) and yes. It is
recommended to leave this option unset, unless the remote peer (Cisco client
or server) requires it. This option does not modify local behaviour. It can be
needed to connect as a client to a Cisco server. It can also be needed to act
as a server for a Cisco client, which otherwise might send back an error
DEL_REASON_NON_UNITY_PEER.
ignore-peer-dns
whether to ignore received DNS configuration.
Acceptable values are: no (the default) and yes. Normally, when
a roadwarrior connects to a remote VPN, the remote VPN server sends a list of
DNS domains and DNS nameserver IP addresses that the roadwarrior can use to
reach internal only resources through the VPN. This option allows the
roadwarrior to ignore the server's suggestion. The roadwarrior will normally
use this information to update the DNS resolving process. What is changed
depends on the detected DNS configuration. It can modify /etc/resolv.conf
directly, or reconfigure a locally running DNS server (unbound, knot, stubby
or systemd-resolved) or inform NetworkManager.
accept-redirect
Whether requests of the remote peer to
redirect IKE/IPsec SA's are accepted. Valid options are no (the
default) and yes. See also accept-redirect-to.
accept-redirect-to
Specify the comma separated list of addresses
we accept being redirected to. Both IPv4 and IPv6 addresses are supported as
well the FQDNs. The value %any, as well as not specifying any address,
signifes that we will redirect to any address gateway sends us in REDIRECT
notify payload.
The value of this option is not considered at all if accept-redirect is set to
no.
send-redirect
Whether to send requests for the remote peer
to redirect IKE/IPsec SA's during IKE_AUTH. Valid options are no (the
default) and yes. If set, the option redirect-to= must also be
set to indicate where to redirect peers to. For redirection during IKE_SA_INIT
exchange, see the global-redirect= and global-redirect-to=
options. Runtime redirects can be triggered via the ipsec whack
--redirect command.
redirect-to
Where to send remote peers to via the
send-redirect option. This can be an IP address or hostname
(FQDN).
fake-strongswan
whether to send a STRONGSWAN Vendor ID payload
to the peer. Acceptable values are: no (the default) and yes.
This used to be required because strongswan rejects certain proposals with
private use numbers such as esp=twofish or esp=serpent unless it receives a
strongswan vendorid by the peer. This option sends such an (unversioned)
vendor id. Note that libreswan and strongswan no longer support twofish or
serpent, so enabling this option likely will no longer do anything.
send-vendorid
whether to send our Vendor ID during IKE.
Acceptable values are: no (the default) and yes. The vendor id
sent can be configured using the "config setup" option
myvendorid=. It defaults to OE-Libreswan-VERSION.
Vendor ID's can be useful in tracking interoperability problems. However,
specific vendor identification and software versions can be useful to an
attacker when there are known vulnerabilities to a specific vendor/version.
The prefix OE stands for "Opportunistic Encryption". This prefix was
historically used by The FreeS/WAN Project and The Openswan Project (openswan
up to version 2.6.38) and in one Xeleranized openswan versions (2.6.39).
Further Xeleranized openswan's use the prefix OSW.
overlapip
a boolean (yes/no) that determines, when
(left|right)subnet=vhost: is used, if the virtual IP claimed by this states
created from this connection can with states created from other connections.
Note that connection instances created by the Opportunistic Encryption or PKIX
(x.509) instantiation system are distinct internally. They will inherit this
policy bit.
The default is no.
This feature is only available with kernel drivers that support SAs to
overlapping conns. At present only the (klips) mast protocol stack supports
this feature.
reqid
a unique identifier used to match IPsec SAs
using iptables with XFRM. This identifier is normally automatically allocated
in groups of 4. It is exported to the _updown script as REQID. On Linux,
reqids are supported with IP Connection Tracking and NAT (iptables).
Automatically generated values use the range 16380 and higher. Manually
specified reqid values therefore must be between 1 and 16379.
Automatically generated reqids use a range of 0-3 (eg 16380-16383 for the first
reqid). These are used depending on the exact policy (AH, AH+ESP, IPCOMP,
etc).
WARNING: Manually assigned reqids are all identical. Instantiations of
connections (those using %any wildcards) will all use the same reqid. If you
use manual assigning you should make sure your connections only match single
road warrior only or you break multiple road warriors behind same NAT router
because this feature requires unique reqids to work.
dpddelay
Set the delay (in time units, defaults to
seconds) between Dead Peer Detection (IKEv1 RFC 3706) or IKEv2 Liveness
keepalives that are sent for this connection (default 0 seconds). Set to
enable checking. If dpddelay is set, dpdtimeout also needs to be set.
dpdtimeout
Set the length of time (in time units,
defaults to seconds) that we will idle without hearing back from our peer.
After this period has elapsed with no response and no traffic, we will declare
the peer dead, and remove the SA (default 0 seconds). Set value bigger than
dpddelay to enable. If dpdtimeout is set, dpddelay also needs to be set.
dpdaction
When a DPD enabled peer is declared dead, what
action should be taken. hold (default) means the eroute will be put
into %hold status, while clear means the eroute and SA with both be
cleared. restart means that ALL SAs to the dead peer will
renegotiated.
dpdaction=clear is really only useful on the server of a Road Warrior
config.
The value restart_by_peer has been obsoleted and its functionality moved
into the regular restart action.
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.
pfsgroup
This option is obsoleted, please use phase2alg
if you need the PFS to be different from phase1 (the default) using:
phase2alg=aes128-md5;modp1024
aggressive
Use IKEv1 Aggressive Mode instead of IKEv1
Main Mode. This option has no effect when IKEv2 is used. Acceptable values are
no (the default) or yes. When this option is enabled, IKEv1 Main
Mode will no longer be allowed for this connection. The old name of this
option was aggrmode.
Aggressive Mode is less secure, and more vulnerable to Denial Of Service
attacks. It is also vulnerable to brute force attacks with software such as
ikecrack. It should not be used, and it should especially not be used
with XAUTH and group secrets (PSK). If the remote system administrator insists
on staying irresponsible, enable this option.
Aggressive Mode is further limited to only proposals with one DH group as there
is no room to negotiate the DH group. Therefore it is mandatory for Aggressive
Mode connections that both ike= and phase2alg= options are
specified with only one fully specified proposal using one DH group.
The KE payload is created in the first exchange packet when using aggressive
mode. The KE payload depends on the DH group used. This is why there cannot be
multiple DH groups in IKEv1 aggressive mode. In IKEv2, which uses a similar
method to IKEv1 Aggressive Mode, there is an INVALID_KE response payload that
can inform the initiator of the responder's desired DH group and so an IKEv2
connection can actually recover from picking the wrong DH group by restarting
its negotiation.
salifetime
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 8h, maximum 24h). Normally, the
connection is renegotiated (via the keying channel) before it expires. The two
ends need not exactly agree on salifetime, although if they do not,
there will be some clutter of superseded connections on the end which thinks
the lifetime is longer.
The keywords "keylife" and "lifetime" are obsoleted aliases
for "salifetime." Change your configs to use "salifetime"
instead.
ipsec-max-bytes
how many bytes can be sent, or how many bytes
can be received on an IPsec SA instance for a connection; acceptable values
are an integer optionally followed by KiB, MiB, GiB,
TiB, PiB or EiB to signify kilobytes, megabytes,
gigabytes, terabytes, petabytes or exabytes.
An IPsec SA contains two keys, one for inbound and one for outbound traffic. The
ipsec-max-bytes sets two limits on each of these keys: the hard limit
which is the total number of bytes that a given key can encrypt, and the soft
limit which is the number of bytes that can be encrypted before a
renegotiation of the IPsec SA is initiated. Normally the renegotation (via the
IKE SA) is completed before the ipsec-max-bytes value is reached.
Pluto sets the the original initiator's soft limit to 25% of
ipsec-max-bytes (with 12% fuzz) and on the original responder's soft
limit to 50% of ipsec-max-bytes (with 12% fuzz). This way the original
initiator hopefully is the one initiating the renegotiation of the IPsec SA.
This option is not negotiated between IKE peers. Each end of the IPsec SA sets
their own limits independently.
The default (hard limit) is 2^63 bytes. The original initiator's soft limit is
2^61 bytes (approx.) and the original responder's soft limit is 2^62 bytes
(approx.).
ipsec-max-packets
how many packets can be sent/received on a
particular instance of a connection (a set of encryption/authentication keys
for user packets) , from successful negotiation to expiry.
Default values and caveats are the same as for ipsec-max-bytes. This
option uses a prefix without "B" for bytes.
replay-window
The size of the IPsec SA replay window
protection in packets. Kernels (Linux, and most BSDs) support a window size of
at least 2040 packets. The default replay window size is 128 packets.
A value of 0 disables replay protection. Disabling of replay protection is
sometimes used on a pair of IPsec servers in a High Availability setup, or on
servers with very unpredictable latency, such as mobile networks, which can
cause an excessive amount of out of order packets.
Disabling replay protection will also disable Extended Sequence Numbers
(esn=no), as advise from RFC 4303 caused some stacks to not support ESN
without a replay-window.
Note: on Linux, sequence errors can be seen in /proc/net/xfrm_stat.
Note: the BSD setkey utility displays the replay window size in bytes (8
packets per byte) and not packets.
Technically, at least the Linux kernel can install IPsec SA's with an IPsec SA
Sequence Number, but this is currently not supported by libreswan.
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 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.
rekeymargin
how long before connection expiry or
keying-channel expiry should attempts to negotiate a replacement begin;
acceptable values as for salifetime (default 9m). Relevant only
locally, other end need not 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 ipsec_pluto(8), currently
100%). The value of rekeymargin, after this random increase,
must not exceed salifetime. The value 0% will suppress time
randomization. Relevant only locally, other end need not agree on it.
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
or 0 means to keep trying forever. For Opportunistic Encryption connections, a
keyingtries value of %forever or 0 is set to 1 and a warning message
will be logged. This is because an expired failureshunt triggers new
keyingtries on-demand later, when there is traffic. This prevents accumulating
an infinite amount of attempts to peers that do not support Opportunistic
Encryption. For Opportunistic, a keyingtries value of > 1 is allowed but
currently not recommended. The meaning of failureshunt= is unclear when there
is continued (failed) keying happening with a negotiationshunt installed.
Relevant only locally, other end need not agree on it.
ikelifetime
how long the keying channel of a connection
(buzzphrase: “IKE SA” or “Parent SA”) should last
before being renegotiated; acceptable values as for salifetime. The
default as of version 4.2 is 8h, before that it was 1h. The maximum is
24h. The two-ends-disagree case is similar to that of
salifetime.
retransmit-timeout
how long a single packet, including
retransmits of that packet, may take before the IKE attempt is aborted. If
rekeying is enabled, a new IKE attempt is started. The default set by
ipsec_pluto(8), currently is 60s. See also:
retransmit-interval, rekey and keyingtries.
retransmit-interval
the initial interval time period, specified in
msecs, that pluto waits before retransmitting an IKE packet. This interval is
doubled for each attempt (exponential back-off). The default set by
ipsec_pluto(8), currently is 500. See also:
retransmit-timeout, rekey and keyingtries.
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).
For IKEv1, compress settings on both peers must match. For IKEv2, compression
can only be suggested and a mismatched compress setting results in connection
without compression.
When set to yes, compression is negotiated for the DEFLATE compression
algorithm.
metric
Set the metric for added routes. This value is
passed to the _updown scripts as PLUTO_METRIC. Acceptable values are positive
numbers, with the default being 1.
mtu
Set the MTU for the route(s) to the remote
endpoint and/or subnets. This is sometimes required when the overhead of the
IPsec encapsulation would cause the packet the become too big for a router on
the path. Since IPsec cannot trust any unauthenticated ICMP messages, PATH MTU
discovery does not work. This can also be needed when using "6to4"
IPV6 deployments, which adds another header on the packet size. Acceptable
values are positive numbers. There is no default.
tfc
Enable Traffic Flow Confidentiality
("TFC") (RFC-4303) for outgoing ESP packets in Tunnel Mode. When
enabled, ESP packets are padded to the specified size (up to the PMTU size) to
prevent leaking information based on ESP packet size. This option is ignored
for AH and for ESP in Transport Mode as those always leak traffic
characteristics and applying TFC will not do anything. Acceptable values are
positive numbers. The value 0 means TFC padding is not performed. Currently
this feature is only implemented for the Linux XFRM stack. In IKEv2, when the
notify payload ESP_TFC_PADDING_NOT_SUPPORTED is received, TFC padding is
disabled. The default is not to do any TFC padding, but this might change in
the near future.
send-no-esp-tfc
Whether or not to tell the remote peer that we
do not support Traffic Flow Confidentiality ("TFC") (RFC-4303).
Possible values are no (the default) which allows the peer to use TFC
or yes which prevents to peer from using TFC. This does not affect
whether this endpoint uses TFC, which only depends on the local tfc
setting. This option is only valid for IKEv2.
nflog
If set, the NFLOG group number to log this
connection's pre-crypt and post-decrypt traffic to. The default value of
0 means no logging at all. This option is only available on linux
kernel 2.6.14 and later. It allows common network utilities such as tcpdump,
wireshark and dumpcap, to use nflog:XXX pseudo interfaces where XXX is the
nflog group number. During the updown phase of a connection, iptables will be
used to add and remove the source/destination pair to the nflog group
specified. The rules are setup with the nflog-prefix matching the connection
name. See also the global nflog-all option.
mark
If set, the MARK to set for the IPsec SA of
this connection. The format of a CONNMARK is mark/mask. If the mask is
left out, a default mask of 0xffffffff is used. A mark value of -1 means to
assign a new global unique mark number for each instance of the connection.
Global marks start at 1001. This option is only available on linux XFRM
kernels. It can be used with iptables to create custom iptables rules using
CONNMARK. It can also be used with Virtual Tunnel Interfaces ("VTI")
to direct marked traffic to specific vtiXX devices.
mark-in
The same as mark, but mark-in only
applies to the inbound half of the IPsec SA. It overrides any mark=
setting.
mark-out
The same as mark, but mark-out only
applies to the outbound half of the IPsec SA. It overrides any mark=
setting.
vti-interface
This option is used to create "Routing
based VPNs" (as opposed to "Policy based VPNs"). It will create
a new interface that can be used to route traffic in for
encryption/decryption. The Virtual Tunnel Interface ("VTI")
interface name is used to for all IPsec SA's created by this connection. This
requires that the connection also enables either the mark= or
mark-in= / mark-out- option(s). All traffic marked with the proper
MARKs will be automatically encrypted if there is an IPsec SA policy covering
the source/destination traffic. Tools such as tcpdump and iptables can be used
on all cleartext pre-encrypt and post-decrypt traffic on the device. See the
libreswan wiki for example configurations that use VTI.
VTI interfaces are currently only supported on Linux with XFRM. The _updown
script handles certain Linux specific interfaces settings required for proper
functioning (disable_policy, rp_filter, forwarding, etc). Interface names are
limited to 16 characters and may not allow all characters to be used. If
marking and vti-routing=yes is used, no manual iptables should be
required. However, administrators can use the iptables mangle table to mark
traffic manually if desired.
vti-routing
Whether or not to add network rules or routes
for IPsec SA's to the respective VTI devices. Valid values are yes (the
default) or no. When using "routing based VPNs" with a
subnets policy of 0.0.0.0/0, this setting needs to set to no to prevent
imploding the tunnel, and the administrator is expected to manually add ip
rules and ip routes to configure what traffic must be encrypted. When set to
yes, the _updown script will automatically route the
leftsubnet/rightsubnet traffic into the VTI device specified with
vti-interface
vti-shared
Whether or not the VTI device is shared
amongst connections. Valid values are no (the default) or yes.
When set to no, the VTI device is automatically deleted if the connection is a
single non-instantiated connection. If a connection instantiates (eg
right=%any) then this option has no effect, as the VTI device is not removed
as it is shared with multiple roadwarriors.
ipsec-interface
Create or use an existing virtual interface
ipsecXXX for "Routing based VPNs" (as opposed to "Policy
based VPNs"). Valid options are yes, no or a number. When
using a number, the IPsec interface created and/or used will use that number
as part of the interface name. For example setting ipsec-interface=5
will create and/or use the ipsec5 interface. The value 0 cannot
be used and is interpreted as no. The value yes is interpreted
as the number 1, and thus will use the interface named ipsec1. An IP
address can be configured for this interface via the interface-ip=
option.
The ipsec-interface is used to route outbound traffic that needs to be
encrypted, and will decrypt inbound traffic that arrives on this interface.
All traffic that is routed to this interface will be automatically encrypted
providing the IPsec SA policy covers this traffic. Traffic not matching the
IPsec SA will be dropped. Tools such as tcpdump, iptables, ifconfig and tools
that need traffic counters can be used on all cleartext pre-encrypt and
post-decrypt traffic on the device. When leftsubnet= is equal to
rightsubnet=, the routing needs to be manged by an external routing
daemon or manually by the administrator.
This option is currently only supported on Linux kernels 4.19 or later when
compiled with XFRMi support ( CONFIG_XFRM_INTERFACE). The number of the
ipsecX device corresponds with the XFRM IF_ID policy option of the
IPsec SA in the Linux kernel. On Linux, XFRMi interfaces can be managed by
libreswan automatically or can be preconfigured on the system using the
existing init system or via networking tools such as systemd-networkd and
NetworkManager. The _updown script handles certain Linux specific interfaces
settings required for proper functioning, such as forwarding and routing rules
for IPsec traffic.
The ipsec-interface=0 will create an interface with the same name as the old
KLIPS interface, ipsec0. This interface name should only be used when required
for migration from KLIPS to XFRM interfaces. Since XFRM IF_ID and marking
cannot use 0, this is mapped to 16384. This means that the devices ipsec0 and
ipsec16384 cannot both be in use.
interface-ip=
NOTE: This option is currently not implemented
pending pluto IP address reference counting. The IP address and netmask to
configure on a virtual device (eg ipsecXXX). This is often used when building
Routing based IPsec tunnels using transport mode and GRE, but can also be
useful in other scenarios. Currently requires ipsec-interface=. See
also leftvti= for cnofiguring IP addresses when using VTI.
priority
The priority in the kernel SPD/SAD database,
when matching up packets. Each kernel (XFRM, OSX, etc) has its own mechanism
for setting the priority. Setting this option to non-zero passes the priority
to the kernel stack unmodified. The maximum value depends on the stack. It is
recommended not to exceed 65536
XFRM use a priority system based on "most specific match first". It
uses an internal algorithm to calculate these based on network prefix length,
protocol and port selectors. A lower value means a higher priority.
Typical values are about the 2000 range. These can be seen on the XFRM stack
using ip xfrm policy when the connection is up. For "anonymous
IPsec" or Opportunistic Encryption based connections, a much lower
priority (65535) is used to ensure administrator configured IPsec always takes
precedence over opportunistic IPsec.
sendca
How much of our available X.509 trust chain to
send with the End certificate, excluding any root CA's. Specifying
issuer sends just the issuing intermediate CA, while all will
send the entire chain of intermediate CA's. none (the default) will not
send any CA certs.
labeled-ipsec
This option is obsolete. To enable labeled
IPsec, setting the policy-label= is enough. See also policy-label= and
secctx-attr-type=
policy-label
The string representation of an access control
security label that is interpreted by the LSM (e.g. SELinux) for use with
Labeled IPsec. See also labeled-ipsec= and secctx-attr-type=. For example,
policy-label=system_u:object_r:ipsec_spd_t:s0-s15:c0.c1023
failureshunt
what to do with packets when negotiation
fails. The default is none: no shunt; passthrough, drop,
and reject have the obvious meanings.
negotiationshunt
What to do with packets during the IKE
negotiation. Valid options are hold (the default) or
passthrough. This should almost always be left to the default hold
value to avoid cleartext packet leaking. The only reason to set this to
passthrough is if plaintext service availability is more important than
service security or privacy, a scenario that also implies
failureshunt=passthrough and most likely authby=%null using Opportunistic
Encryption.
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 (see ipsec_setup(8)). Here's an example:config setup logfile=/var/log/pluto.log plutodebug=all
decide which protocol stack is going to be
used. Valid values are "xfrm" and "bsd". This option
should no longer be set, as the stack is currently auto-detected. The values
"klips, "mast", "netkey", "native",
"kame" and "auto" are obsolete. The option is kept only
because it is suspected that Linux and BSD will get userspace stacks with
IPsec support soon (such as dpdk).
listen
IP address to listen on, defaults to ANY.
Currently only accepts one IP address.
ike-socket-bufsize
Set the IKE socket buffer size. Default size
is determined by the OS (as of writing, this seems to be set to 212992. On
Linux this is visible via /proc/sys/net/core/rmem_default and
/proc/sys/net/core/wmem_default. On Linux, this option uses SO_RCVBUFFORCE and
SO_SNDBUFFORCE so that it can override rmem_max/wmem_max values of the OS.
This requires CAP_NET_ADMIN (which is also required for other tasks). This
option can also be toggled on a running system using ipsec whack
--ike-socket-bufsize bufsize.
ike-socket-errqueue
Whether to enable or disable receiving socket
errors via IP_RECVERR. The default is enabled. This will cause the socket to
receive, process and log socket errors, such as ICMP unreachable messages or
Connection Refused messages. Disabling this only makes sense on very busy
servers, and even then it might not make much of a difference. This option can
also be toggled on a running system using ipsec whack
--ike-socket-errqueue-toggle.
listen-udp
Whether the pluto IKE daemon should listen on
the standard UDP ports of 500 and 4500. The value
"yes" means to listen on these ports, and is the default. This
should almost never be disabled. In the rare case where it is known that only
ever TCP or non-standard UDP ports will be used, this option can disable the
standard UDP ports. Connections can specify their own non-standard port using
leftikeport=.
listen-tcp
Whether the pluto IKE daemon should listen on
the (pseudo) standard TCP port 4500. The value "no" is the
current default, but this will be changed in the future to "yes".
The TCP usage complies to RFC 8229 for IKE and ESP over TCP support.
Connections can specify their own non-standard port using leftikeport=.
nflog-all
If set, the NFLOG group number to log
all pre-crypt and post-decrypt traffic to. The default value of
0 means no logging at all. This option is only available on linux
kernel 2.6.14 and later. It allows common network utilities such as tcpdump,
wireshark and dumpcap, to use nflog:XXX pseudo interfaces where XXX is the
nflog group number. During startup and shutdown of the IPsec service, iptables
commands will be used to add or remove the global NFLOG table rules. The rules
are setup with the nflog-prefix all-ipsec. See also the per-connection
nflog option.
keep-alive
The delay (in seconds) for NAT-T keep-alive
packets, if these are enabled using nat-keepalive This parameter may
eventually become per-connection.
virtual-private
contains the networks that are allowed as
(left|right)subnet= for the remote clients when using the vhost: or
vnet: keywords in the (left|right)subnet= parameters. In other
words, the address ranges that may live behind a NAT router through which a
client connects. This value is usually set to all the RFC-1918 address space,
excluding the space used in the local subnet behind the NAT (An IP address
cannot live at two places at once). IPv4 address ranges are denoted as
%v4:a.b.c.d/mm and IPv6 is denoted as
%v6:aaaa::bbbb:cccc:dddd:eeee/mm. One can exclude subnets by using the
!. For example, if the VPN server is giving access to 192.168.1.0/24,
this option should be set to:
virtual-private=%v4:10.0.0.0/8,%v4:192.168.0.0/16,%v4:172.16.0.0/12,%v4:!192.168.1.0/24.
This parameter is only needed on the server side and not on the client side
that resides behind the NAT router, as the client will just use its IP address
for the inner IP setting. This parameter may eventually become per-connection.
See also leftsubnet=
Note: It seems that T-Mobile in the US and Rogers/Fido in Canada have started
using 25.0.0.0/8 as their pre-NAT range. This range technically belongs to the
Defence Interoperable Network Services Authority (DINSA), an agency of the
Ministry of Defence of the United Kingdom. The network range seems to not have
been announced for decades, which is probably why these organisations
"borrowed" this range. To support roadwarriors on these 3G networks,
you might have to add it to the virtual-private= line.
myvendorid
The string to use as our vendor id (VID) when
send-vendorid=yes. The default is OE-Libreswan-VERSION.
nhelpers
how many pluto helpers are started to
help with cryptographic operations. Pluto will start as many helpers as the
number of CPU's, minus 1 to dedicate to the main thread. For machines with
less than 4 CPU's, an equal number of helpers to CPU's are started. A value of
0 forces pluto to do all operations inline using the main process. A value of
-1 tells pluto to perform the above calculation. Any other value forces the
number to that amount.
seedbits
Pluto uses the NSS crypto library as its
random source. Some government Three Letter Agencies require that pluto reads
additional bits from /dev/random and feed these into the NSS RNG before
drawing random from the NSS library, despite the NSS library itself already
seeding its internal state. This process can block pluto for an extended time
during startup, depending on the entropy of the system. Therefore, the default
is to not perform this redundant seeding. If specifying a value, it is
recommended to specify at least 460 bits (for FIPS) or 440 bits (for
BSI).
ikev1-secctx-attr-type
The value for the IKEv1 IPsec SA security
context attribute identifier that is used for Labeled IPsec. Defaults to the
private use IANA value 32001 from the IPsec SA attributes registry. Old
openswan versions might still be using the (stolen) value 10, which has since
been assigned by IANA for something else. Other values are not recommended
unless IANA assigns an actual value for this option. Labeled IPsec using IKEv2
does not use this option, it only uses an IANA allocated Notify number. See
also policy-label.
ikev1-policy
What to do with received IKEv1 packets. Valid
options are drop (default) which will silently drop any received IKEv1
packet, accept, and reject which will reply with an error. If
this option is set to drop or reject, an attempt to load an IKEv1 connection
will fail, as these connections would never be able to receive a packet for
processing.
crlcheckinterval
interval expressed in second units, for
example crlcheckinterval=8h for 8 hours, after which pluto will fetch new
Certificate Revocation List (CRL) from crl distribution points. List of used
CRL distribution points are collected from CA certificates and end
certificates. Loaded X.509 CRL's are verified to be valid and updates are
imported to NSS database. If set to 0, which is also the default value
if this option is not specified, CRL updating is disabled.
crl-strict
if not set, pluto is tolerant about missing or
expired X.509 Certificate Revocation Lists (CRL's), and will allow peer
certificates as long as they do not appear on an expired CRL. When this option
is enabled, all connections with an expired or missing CRL will be denied.
Active connections will be terminated at rekey time. This setup is more
secure, but vulnerable to downtime if the CRL expires. Acceptable values are
yes or no (the default). This option used to be called
strictcrlpolicy.
curl-iface
The name of the interface that is used for
CURL lookups. This is needed on rare situations where the interface needs to
be forced to be different from the default interface used based on the routing
table.
curl-timeout
The timeout for the curl library calls used to
fetch CRL and OCSP requests. The default is 5s.
ocsp-enable
Whether to perform Online Certificate Store
Protocol ("OCSP") checks on those certificates that have an OCSP URI
defined. Acceptable values are yes or no (the default).
ocsp-strict
if set to no, pluto is tolerant about failing
to obtain an OCSP responses and a certificate is not rejected when the OCSP
request fails, only when the OCSP request succeeds and lists the certificate
as revoked. If set to yes, any failure on obtaining an OCSP status for a
certificate will be fatal and the certificate will be rejected. Acceptable
values are yes or no (the default).
The strict mode refers to the NSS ocspMode_FailureIsVerificationFailure mode,
while non-strict mode refers to the NSS
ocspMode_FailureIsNotAVerificationFailure mode.
ocsp-method
The HTTP methods used for fetching OCSP data.
Valid options are get (the default) and post. Note that this
behaviour depends on the NSS crypto library that is actually performing the
fetching. When set to the get method, post is attempted only as fallback in
case of failure. When set to post, only the post method is ever used.
ocsp-timeout
The time until an OCSP request is aborted and
considered failed. The default value is 2 seconds.
ocsp-uri
The URI to use for OCSP requests instead of
the default OCSP URI listed in the CA certificate. This requires the
ocsp-trustname option to be set to the nick (friendly name) of the OCSP server
certificate, which needs to be present in the NSS database. These option
combined with the next option sets the OCSP default responder.
ocsp-trustname
The nickname of the certificate that has been
imported into the NSS database of the server handling the OCSP requests. This
requires the ocsp-uri option to be set as well. This option and the previous
options sets the OCSP default responder.
ocsp-cache-size
The maximum size (in number of certificates)
of OCSP responses that will be kept in the cache. The default is 1000. Setting
this value to 0 means the cache is disabled.
ocsp-cache-min-age
The minimum age (in seconds) before a new
fetch will be attempted. The default is 1 hour.
ocsp-cache-max-age
The maximum age (in seconds) before a new
fetch will be attempted. The default is 1 day.
syslog
the syslog(2) “facility”
name and priority to use for startup/shutdown log messages, default
daemon.error.
plutodebug
how much Pluto debugging output should be
logged. An empty value, or the magic value none, means no debug output
(the default). Otherwise only the specified types of output (a quoted list,
names without the --debug- prefix, separated by white space) are
enabled;
The current option values are base that represents moderate amounts of
information, cpu-usage for getting timing/load based information (best
used without any other debugging options), crypt for all crypto related
operations and tmi (Too Much Information) for excessive logging. To log
any sensitive private key or password material, use the special private
value.
The old plutodebug options (control, controlmore, x509, kernel, etc) are mapped
to either base or tmi. Note that all maps to base and not
tmi.
uniqueids
Whether IDs should be considered identifying
remote parties uniquely. Acceptable values are yes (the default) and
no. Participant IDs normally are unique, so a new connection instance
using the same remote ID is almost invariably intended to replace an old
existing connection.
When the connection is defined to be a server (using xauthserver=) and the
connection policy is authby=secret, this option is ignored (as of 3.20) and
old connections will never be replaced. This situation is commonly known as
clients using a "Group ID".
This option may disappear in the near future. People using identical X.509
certificates on multiple devices are urged to upgrade to use separate
certificates per client and device.
logfile
do not use syslog, but rather log to stderr,
and direct stderr to the argument file. This option used to be called
plutostderrlog=
logappend
If pluto is instructed to log to a file using
logfile=, this option determines whether the log file should be
appended to or overwritten. Valid options are yes (the default) to
append and no to overwrite. Since on modern systems, pluto is restarted
by other daemons, such as systemd, this option should be left at its default
yes value to preserve the log entries of previous runs of pluto. The option is
mainly of use for running the test suite, which needs to create new log files
from scratch.
logip
If pluto is instructed to log the IP address
of incoming connections. Valid options are yes (the default) and
no. Note that this only affects regular logging. Any enabled debugging
via plutodebug= will still contain IP addresses of peers. This option
is mostly meant for servers that want to avoid logging IP addresses of
incoming clients. Other identifiable information might still be logged, such
as ID payloads and X.509 certificate details. When using ID of type IP
address, this option will not hide the actual IP address as part of the ID.
Most deployments will not want to change this from the default. If logging of
IP addresses is unwanted, audit-log=no should also be set.
audit-log
Whether pluto should produce Linux Auditing
System log messages. If enabled, pluto will log start, stop and
fail for the negotiation of IKE and IPsec SA's. The kernel will also
log success and failures for actually adding and removing IPsec SA's from the
kernel's SADB. Valid options are yes(the default) and no. On
non-Linux systems, this option is ignored. If enabled but the kernel is
lacking audit support, audit messages are not sent. If the kernel has audit
support and using it fails, pluto will abort. Note that for compliance
reasons, audit log messages contain the relevant IP addresses, even if
logip=no.
logtime
When pluto is directed to log to a file using
logfile=, this option determines whether or not to log the current
timestamp as prefix. Values are yes (the default) or no. The no
value can be used to create logs without ephemeral timestamps, such as those
created when running the test suite. This option used to be called
plutostderrlogtime=
ddos-mode
The startup mode of the DDoS defense
mechanism. Acceptable values are busy, unlimited or auto
(the default). This option can also be given to the IKE daemon while running,
for example by issuing ipsec whack --ddos--busy. When in busy mode,
pluto activates anti-DDoS counter measures. Currently, counter measures
consist of requiring IKEv2 anti-DDoS cookies on new incoming IKE requests, and
a more aggressive cleanup of partially established or AUTH_NULL
connections.
ddos-ike-threshold
The number of half-open IKE SAs before the
pluto IKE daemon will be placed in busy mode. When in busy mode, pluto
activates anti-DDoS counter measures. The default is 25000. See also
ddos-mode and ipsec whack --ddos-XXX.
global-redirect
Whether to send requests for the remote peer
to redirect IKE/IPsec SA's during IKE_SA_INIT. Valid options are no
(the default), yes and auto, where auto means that the requests
will be sent if DDoS mode is active (see ddos-mode). If set, the option
global-redirect-to= must also be set to indicate where to redirect
peers to. For specific connection redirection after IKE SA authentication, see
the send-redirect= and redirect-to= options. This configuration
can be changed at runtime via the ipsec whack --global-redirect
command.
global-redirect-to
Where to send remote peers to via the
global-redirect option. This can be a list, or a single entry, of IP
addresses or hostnames (FQDNs). If there is a list of entries, they must be
separated with comma's. One specified entry means all peers will be redirected
to it, while multiple specified entries means peers will be evenly distributed
across the specified servers. This configuration can be changed at runtime via
the ipsec whack --global-redirect-to command.
max-halfopen-ike
The number of half-open IKE SAs before the IKE
daemon starts refusing all new IKE attempts. Established IKE peers are not
affected. The default value is 50000.
shuntlifetime
The time until bare shunts (kernel policies
not associated with connections) are deleted from the kernel. The default
value is 15m. When using Opportunistic Encryption to a specific host fails,
the system will either install a %pass or %hold shunt to let the traffic out
clear text or block it. During the the shuntlifetime, no new Opportunistic
Encryption attempt will be started, although the system will still respond to
incoming OE requests from the remote IP. See also failureshunt and
negotiationshunt
xfrmlifetime
The time in seconds until the XFRM acquire
state times out. The default value is 30 seconds. For auto=ondemand
connections and Opportunistic connections an IPsec policy is installed in the
kernel. If an incoming or outgoing packet matches this policy, a state is
created in the kernel and the kernel sends an ACQUIRE message to the IKE
daemon pluto. While this state is in place, no new acquires will come in for
this connection. The default should be fine for most people. One use case of
shortening these is if opportunistc encryption is used towards cloud instances
that can quickly re-use IP addresses. This value is only used during the
libreswan startup process by the ipsec _stackmanager helper. See also
failureshunt and negotiationshunt
dumpdir
in what directory should things started by
setup (notably the Pluto daemon) be allowed to dump core? The default
value is /var/run/pluto. When SELinux runs in enforced mode, changing
this requires a similar change in the SELinux policy for the pluto
daemon.
statsbin
This option specifies an optional external
program to report tunnel state changes too. The default is not to report
tunnel state changes. This program can be used to notify the user's desktop
(dbus, NetworkManager) or to report tunnel changes to a central logging
server.
ipsecdir
Specifies a directory for
administrator-controlled configuration files and directories. The default
value is /etc/ipsec.d. It may contain the following files and
directories:
passwd
When SELinux runs in enforced mode, changing this requires a similar change in
the SELinux policy for the pluto daemon.
nssdir
(optional) for XAUTH support if not using PAM
(this file should not be world-readable). See README.XAUTH for more
information.
nsspassword
(optional) passwords needed to unlock the NSS
database in /var/lib/ipsec/nss (this file should not be world-readable). See
README.nss for more information.
policies/
a directory containing policy group
configuration information. See POLICY GROUP FILES in this document for
more information.
cacerts/
DEPRECATED: a directory to store trust anchors
(root certificate authority certificates). The preferred (and default)
approach is to store CA certs in the NSS database instead. See README.nss for
more information.
crls/
DEPRECATED: a directory to store certificate
revocation lists. The preferred (and default) approach is to store CRLs in the
NSS database instead. See README.nss for more information.
Specifies a directory for NSS database files.
The default value is /var/lib/ipsec/nss. It may contain the following
files:
pkcs11.txt
When SELinux runs in enforced mode, changing this requires a similar change in
the SELinux policy for the pluto daemon.
secretsfile
Detailed info about NSS database creation
parameteres.
cert9.db
NSS Certificate database.
key4.db
NSS Key database.
pathname of the file that stores the secret
credentials such as preshared keys (PSKs). See man ipsec.secrets for
the syntax. The default value is /etc/ipsec.secrets.
seccomp
Set the seccomp kernel syscall whitelisting
feature. When set to enabled, if pluto calls a syscall that is not on
the compiled-in whitelist, the kernel will assume an exploit is attempting to
use pluto for malicious access to the system and terminate the pluto daemon.
When set to tolerant, the kernel will only block the rogue syscall and
pluto will attempt to continue. If set to disabled, pluto is allowed to
call any syscall offered by the kernel, although it might be restricted via
other security mechanisms, such as capabilities, SElinux, AppArmor or other OS
security features.
The current default is disabled, but it is expected that in the future this
feature will be enabled on all supported operating systems. Similarly, it is
expected that further privilege separation will reduce the allowed syscalls -
for example for the crypto helpers or DNS helpers.
Warning: The restrictions of pluto are inherited by the updown scripts,
so these scripts are also not allowed to use syscalls that are forbidden for
pluto.
This feature can be tested using ipsec whack --seccomp-crashtest.
Warning: With seccomp=enabled, pluto will be terminated by the kernel.
With seccomp=tolerant or seccomp=disabled, pluto will report the results of
the seccomp test. SECCOMP will log the forbidden syscall numbers to the audit
log, but only with seccomp=enabled. The tool scmp_sys_resolver from the
libseccomp development package can be used to translate the syscall number
into a name. See programs/pluto/pluto_seccomp.c for the list of allowed
syscalls.
dnssec-enable
Whether pluto should perform dnssec validation
using libunbound, provided libreswan was compiled with USE_DNSSEC. A value of
yes (the default) means pluto should perform DNSSEC validation. Note
that pluto reads the file /etc/resolv.conf to determine which
nameservers to use.
dnssec-rootkey-file
The location of the DNSSEC root zone public
key file. The default is /var/lib/unbound/root.key but this can be
changed at compile time.
dnssec-anchors
The location of a file containing additional
DNSSEC Trust Anchors. This can be used when a network is using split-DNS and
the internal hierarchy is using DNSSEC trust anchors. There is no default
value.
OPPORTUNISTIC CONNS
For Opportunistic connections, the system requires creating special named conns that are used to implement the default policy groups. Currently, these names cannot be changed.conn clear type=passthrough authby=never left=%defaultroute right=%group auto=route conn clear-or-private type=passthrough left=%defaultroute leftid=%myid right=%opportunisticgroup failureshunt=passthrough keyingtries=3 ikelifetime=1h salifetime=1h rekey=no auto=route conn private-or-clear type=tunnel left=%defaultroute leftid=%myid right=%opportunisticgroup failureshunt=passthrough keyingtries=3 ikelifetime=1h salifetime=1h rekey=no auto=route conn private type=tunnel left=%defaultroute leftid=%myid right=%opportunisticgroup failureshunt=drop keyingtries=3 ikelifetime=1h salifetime=1h rekey=no auto=route conn block type=reject authby=never left=%defaultroute right=%group auto=route
POLICY GROUP FILES
The optional files under /etc/ipsec.d/policies, including/etc/ipsec.d/policies/clear /etc/ipsec.d/policies/clear-or-private /etc/ipsec.d/policies/private-or-clear /etc/ipsec.d/policies/private /etc/ipsec.d/policies/block
DEFAULT POLICY GROUPS
The standard Libreswan install includes several policy groups which provide a way of classifying possible peers into IPsec security classes: private (talk encrypted only), private-or-clear (prefer encryption), clear-or-private (respond to requests for encryption), clear and block.CHOOSING A CONNECTION [THIS SECTION IS EXTREMELY OUT OF DATE
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 that 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.FILES
/etc/ipsec.conf /etc/ipsec.d/policies/clear /etc/ipsec.d/policies/clear-or-private /etc/ipsec.d/policies/private-or-clear /etc/ipsec.d/policies/private /etc/ipsec.d/policies/block
SEE ALSO
ipsec(8), ipsec_auto(8), ipsec_rsasigkey(8)HISTORY
Designed for the FreeS/WAN project < https://www.freeswan.org> by Henry Spencer.BUGS
Before reporting new bugs, please ensure you are using the latest version of Libreswan. When type or failureshunt is set to drop or reject, Libreswan blocks outbound packets using eroutes, but assumes inbound blocking is handled by the firewall. Libreswan offers firewall hooks via an “updown” script. However, the default ipsec _updown provides no help in controlling a modern firewall. Including attributes of the keying channel (authentication methods, ikelifetime, etc.) as an attribute of a connection, rather than of a participant pair, is dubious and incurs limitations. The use of %any with the protoport= option is ambiguous. Should the SA permits any port through or should the SA negotiate any single port through? The first is a basic conn with a wildcard. The second is a template. The second is the current behaviour, and it's wrong for quite a number of uses involving TCP. The keyword %one may be introduced in the future to separate these two cases. It would be good to have a line-continuation syntax, especially for the very long lines involved in RSA signature keys. The ability to specify different identities, authby, and public keys for different automatic-keyed connections between the same participants is misleading; this doesn't work dependably because the identity of the participants is not known early enough. This is especially awkward for the “Road Warrior” case, where the remote IP address is specified as 0.0.0.0, and that is considered to be the “participant” for such connections. If conns are to be added before DNS is available, left=FQDN, leftnextop= FQDN, and leftrsasigkey=%dnsonload will fail. ipsec_pluto(8) does not actually use the public key for our side of a conn but it isn't generally known at a add-time which side is ours (Road Warrior and Opportunistic conns are currently exceptions). The myid option does not affect explicit ipsec auto --add or ipsec auto --replace commands for implicit conns.AUTHOR
Paul Woutersdocumenter
| 06/02/2023 | libreswan |