| IPSEC.CONF(5) | File formats and conventions | IPSEC.CONF(5) |
.SH "NAME" ipsec.conf - IPsec configuration and connections
.SH "DESCRIPTION"
.SS "Overview"
.PP 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)). Libreswan reads this file
during start up (technically, if Libreswan's daemon ipsec-pluto(8) is
invoked directly then the file ipsec.conf is not needed; however, this is
not recommended). Configurations can be added using eithe this configuration
file or by using ipsec whack directly.
.PP ipsec.conf is a text file, consisting of one or more sections.
.PP Within the file, 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.
.PP A line that contains include and a file name, separated by white
space, is replaced by the contents of that file. If the file name is not a
full pathname, it is considered to be relative to the directory 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 glob(3)); for example:
.PP include /etc/ipsec.d/*.conf
.PP 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 parameters (described below) which
permit splitting a single logical section (e.g. a connection description)
into several distinct sections.
.PP 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:
.PP version 2
.PP A section begins with a line of the form:
.PP type name
.PP 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.
.PP There are two types of section: a config section specifies general
configuration information for Libreswan, and a conn section specifies
an IPsec connection.
.PP Lines within the section are generally of the form
.PP parameter=value
.PP (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.
.PP An empty value stands for the empty string. A non-empty
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.
.PP 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).
.PP There is currently one parameter that is available in any type of
section:
.PP also=value
The value is a section name. The parameters of that section are inserted, in place, into this section (i.e., as if they had been written as part of and at that point in the section's definition). The specified section must exist, and must have the same section type. Multiple and nested also are permitted (duplicate insertions of the same section are ignored). When the same parameter appears in multiple sections, the first definition encountered is used. 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.
Putting also at the end of the section after any parameter definitions is recommended. This way, the section's parameter value overrides also sections.
.RE
.PP 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 and multiple default values for a given parameter (the last
value is used). %default sections may not contain any
also parameters.
.SS "Values"
.sp
Byte Counts And Binary Data
.PP Options, such as ipsec-max-bytes, that expect a numeric byte
count, also accept decimal fractions, and the following multipliers as a
suffix:
.PP KiB
kilobytes (1024 bytes)
.RE .PP MiB
megabytes (1024*1024 bytes)
.RE .PP GiB
gigabytes (1024*1024*1024 bytes)
.RE .PP TiB
terabytes (1024*1024*1024*1024 bytes)
.RE .PP PiB
petabytes (1024*1024*1024*1024*1024 bytes)
.RE .PP EiB
exabytes (1024*1024*1024*1024*1024*1024 bytes)
.RE
.RE
.sp
Duration
.PP Options, such as retransmit-timeout, that expect a numeric
duration, also accept decimal fractions, and the following multipliers as a
suffix:
.PP us
microseconds (1/1_000_000 seconds)
.RE .PP ms
milliseconds (1/1_000 seconds)
.RE .PP s
seconds
.RE .PP m
minutes (60 seconds)
.RE .PP h
hours (60*60 seconds)
.RE .PP d
days (24*60*60 seconds)
.RE .PP w
weeks (7*24*60*60 seconds)
.RE
For instance, the following are each equivalent: 1ms and 1000us; 0.5s and
500ms; 1.5h and 90m.
.RE
.sp
Proposals
.PP The options ike=, esp=, and ah= expect algorithm
proposals that follow the following syntax:
PROPOSALS = PROPOSAL { "," PROPOSAL }
(* IKEv1 *)
PROPOSAL = ALGORITHM
{ "-" ALGORITHM }
[ ";" KE_ALGORITHM ]
ALGORITHM = ENCRYPTION_ALGORITHM |
PRF_ALGORITHM (*aka-KDF*) |
INTEGRITY_ALGORITHM |
KE_ALGORITHM (*aka-DH*)
(* IKEv2 *)
PROPOSAL = [ ALGORITHMS
{ "-" ALGORITHMS }
[ ";" KE_ALGORITHM (*aka-DH*) ] ]
{ ";" TYPE_ALGORITHMS }
ALGORITHMS = ENCRYPTION_ALGORITHMS |
PRF_ALGORITHMS (*aka-KDF*) |
INTEGRITY_ALGORITHMS |
KE_ALGORITHMS (*aka-DH*)
TYPE_ALGORITHMS = "encrypt=" ENCRYPTION_ALGORITHMS |
"prf=" PRF_ALGORITHMS (*aka-KDF*) |
"integ=" INTEGRITY_ALGORITHMS |
"ke=" KE_ALGORITHMS (*aka-DH*) |
"sn=" SN_ALGORITHMS (*aka-ESN*) |
"addke1=" KE_ALGORITHMS |
"addke2=" KE_ALGORITHMS |
...
ENCRYPTION_ALGORITHMS = ENCRYPTION_ALGORITHM { "+" ENCRYPTION_ALGORITHM }
PRF_ALGORITHMS = PRF_ALGORITHM { "+" PRF_ALGORITHM }
INTEGRITY_ALGORITHMS = INTEGRITY_ALGORITHM { "+" INTEGRITY_ALGORITHM }
KE_ALGORITHMS = KE_ALGORITHM { "+" KE_ALGORITHM }
SN_ALGORITHMS = SN_ALGORITHM { "+" SN_ALGORITHM }
ENCRYPTION_ALGORITHM = "aes" | "aes_gcm" | ...
PRF_ALGORITHM = "sha1" | "sha2_256" | ...
INTEGRITY_ALGORITHM = "sha1_96" | "sha2_256_128" | ...
KE_ALGORITHM = "modp2048" | "dh19" | "ml_kem_768" | ...
SN_ALGORITHM = "yes" | "no" | "32-bit-sequential" | ...
.PP Proposals are not required. When omitted, Libreswan will provide suitable
defaults (see ipsec-algparse(8)). Similarly, when an algorithm is
omitted from a proposal, Libreswan will, again, provide suitable
defaults.
.PP Specifying the IKE INTEGRITY (hash) algorithms is not recommended;
Libreswan will automatically generate the prefered INTEGRITY algorithms
based on the specified, or default, PRF (KDF) algorithms. Specifying
different IKE INTEGRITY and PRF (KDF) is not recommended.
.PP Specifying an additional key-exchange (for instance,
ike=aes;addke1=ml_kem_768) in an IKE proposal implicitly enables the
IKE_INTERMEDIATE exchange it depends on.
.PP Specifying Key Exchange Methods in either an ESP or AH proposal is not
recommended. When a proposal requires Key Exchange Methods (for instance
when PFS is enabled) the proposal will automatically include the Key
Exchange Method negotiated during the IKE exchange.
.PP Enabled cryptographic algorithms and default proposals are logged by
pluto during startup (see ipsec-pluto(8)).
.if n .sp
Note
.PP Some distributions, such as Fedora and RHEL/CentOS, use a System Wide
Crypto Policy to specify the default ike= and esp= proposals.
Specifying your own proposals using either ike= or esp= will
override these system or software recommended defaults (but can be necessary
at times).
.sp .5v
.PP History: the ";TYPE=ALGORITHMS" syntax was added in Libreswan
5.4; the "ENCRYPTION-INTEGRITY-PRF" syntax for IKE proposals was
deprecated in Libreswan 5.4; the "ENCRYPTION-PRF-INTEGRITY" syntax
for IKE proposals was added in Libreswan 5.4.
.PP Limitations: Libreswan 5.4 does not support the IKE_FOLLOWUP_KE
exchange.
.PP Note: The abbreviation "KE" can refer to either Key Exchange
Method (e.g. "modp2048" or "dh19") or Key Encapsulation
Method (e.g. "ml_kem_768").
.RE
.SS "Config Setup Section"
.PP The config setup section overrides preset configuration
parameters. For instance, to change the location of pluto's log file,
include a config setup section containing:
config setup
logfile=/var/log/pluto.log
.PP To display a configuration parameter's preset, the command ipsec
addconn --configsetup parameter can be used. This is
especially useful for obtaining the location of directories, such as the NSS
Database directory, that vary across systems.
.PP The currently-accepted configuration parameters are:
.PP audit-log={yes|no}
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. 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 when
logip=no.
The default is yes.
Prior to Libreswan version 5.3, when pluto was invoked directly and
without a configuration file, this option was set to no.
.PP crl-strict={yes|no}
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.
The default is no.
Prior to Libreswan version 3.16, this option was called
strictcrlpolicy.
.PP
crl-timeout=seconds[us|ms|s|m|h|d|w]
The timeout for used when fetching CRLs.
The default is 5 seconds (5s).
.PP
crlcheckinterval=seconds[us|ms|s|m|h|d|w]
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 CRL updating is disabled.
By default CRL updating is disabled (0).
.PP 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.
.PP 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. See also ddos-mode and ipsec whack --ddos-XXX.
The default is 25000.
.PP
ddos-mode={busy|unlimited|auto}
The startup mode of the DDoS defense mechanism. 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.
The default is auto.
.PP dns-resolver={file,systemd}
The DNS resolver to be configured by ipsec-updown(8). Both file
(/etc/resolve.conf) and systemd (systemd-resolved are recognized. The
configured value is passed to ipsec-updown(8) in the environment
variable PLUTO_DNS_RESOLVER.
The default is file.
.PP dnssec-anchors=file
The 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.
.PP dnssec-enable={yes|no}
Whether pluto should perform DNSSEC validation using
libunbound(3) (assuming Libreswan was built with
USE_DNSSEC=true which is enabled in the default build). Note that
pluto reads the file /etc/resolv.conf to determine which nameservers
to use.
The default is yes.
.PP dnssec-rootkey-file=file
The file that contains the DNSSEC root zone public key.
The default is not-applicable.
.PP dumpdir=directory
in what directory should things started by setup (notably the Pluto
daemon) be allowed to dump core? When SELinux runs in enforced mode,
changing this requires a similar change in the SELinux policy for the pluto
daemon.
The default is /run/pluto.
.PP exampledir=directory
Specifies the directory where Libreswan's sample configuration files are
installed. This includes files such as ipsec.conf-sample and
ipsec.secrets-sample. Packaging systems can use ipsec-addconn(8) to
query the parameter's value.
The default is /usr/share/doc/libreswan.
History: the read-only exampledir= parameter was added in Libreswan
5.4.
.PP rundir=directory
Directory directory where pluto will create the process ID file
pluto.pid and the control socket pluto.ctl. Utilities can use
ipsec-addconn(8) to query the parameter's value.
The default is /run/pluto.
History: the read-only rundir= parameter was added in Libreswan
5.4.
.PP
expire-lifetime=seconds[us|ms|s|m|h|d|w]
The time until the acquire kernel state times out.
On-demand connections (such as Opportunistic, auto=ondemand, or
ipsec route) have an IPsec trap policy installed in the kernel. If an
outgoing (or inbound) packet matches this policy, a state is created in the
kernel and then 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.
See also failureshunt and negotiationshunt
The default, on Linux, as determined by /proc/sys/net/core/xfrm_acq_expires,
is 30 seconds (30s). On BSD, this option is ignored.
Prior to Libreswan version 5.3 this option was called
xfrmlifetime.
.PP
expire-shunt-interval=seconds[us|ms|s|m|h|d|w]
How often to scan for Opportunistic Encryption failure shunts (kernel
policies) that have expired and should be removed.
When an Opportuistic Encryption negotiation fails, a failure shunt is
installed to either block (drop) or allows(pass) traffic to
the peer. These shunts are given a lifetime of 15 minutes (see
shuntlifetime) after which time they expire and should be removed.
The option expire-shunt-interval determines how frequently these
shunts are checked.
The default is 20 seconds (20s).
Note: because these shunts (kernel policies) are not bound to a connection
instance they are refered to as bare.
.PP
global-redirect-to={hostname|address},...
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.
.PP
global-redirect={yes|no|auto}
Whether to send requests for the remote peer to redirect IKE/IPsec SA's
during IKE_SA_INIT. 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.
The default is no.
.PP
ike-socket-bufsize=count[Ki|Mi|Gi|Ti|Pi|Ei]
Set the IKE socket buffer size. 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.
The default is determined by the OS (as of writing, this seems to be 212992).
On Linux this is visible via /proc/sys/net/core/rmem_default and
/proc/sys/net/core/wmem_default.
.PP ike-socket-errqueue={yes|no}
Whether to enable or disable receiving socket errors via IP_RECVERR. 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.
The default is yes.
.PP ikev1-policy={drop,accept,reject}
What to do with received IKEv1 packets.
Valid options are:
.PP drop
silently drop any received IKEv1 packet
.RE .PP accept
accept IKEv1 connections
.RE .PP reject
reply with an error.
.RE
.sp 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.
The default is drop.
.PP ipsec-interface-managed={yes|no}
Specify whether the IPsec Interface specified by ipsec-interface is
managed by Libreswan.
Possible values are:
.PP yes
Libreswan is responsible for managing the IPsec Interface. For instance, creating it when needed, adding the address specified by interface-ip, installing any kernel policy or state, and marking it up and down.
In this mode ipsec-interface identifies the IPsec interface network device. For instance, ipsec-interface=1 specifies the network device ipsec1.
.RE
.PP no
Libreswan assumes that the IPsec interface specified by ipsec-interface exists and Libreswan is only responsible for managing kernel policy and state.
In this mode ipsec-interface identifies the low level kernel ID. For instance, on Linux, ipsec-interface=1 identifies the device with the XFRM if_id 1.
.RE
.sp
The default is yes.
.PP ipsecdir=directory
Specifies a directory for administrator-controlled configuration files and
directories. It may contain the following files and directories:
.PP passwd
(optional) for IKEv1 XAUTH support if not using PAM (this file should not be world-readable). See README.XAUTH for more information.
.RE .PP 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.
.RE .PP policies/
a directory containing policy group configuration information. See POLICY GROUP FILES in this document for more information.
.RE
.sp
The default is /etc/ipsec.d.
When SELinux runs in enforced mode, changing this requires a similar change
in the SELinux policy for the pluto daemon.
.PP
keep-alive=seconds[us|ms|s|m|h|d|w]
The delay (in seconds) for NAT-T keep-alive packets, if these are enabled
using nat-keepalive This parameter may eventually become
per-connection.
.PP listen-tcp={yes|no}
Whether the pluto IKE daemon should listen on the standard TCP port
4500. The TCP usage complies to RFC 9329 for IKE and ESP over TCP
support. Connections can specify their own non-standard TCP port using
leftikeport= and tcp-remoteport= for a non-standard peer TCP
port.
The default is no.
.PP listen-udp={yes|no}
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. 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=.
The default is yes.
.PP listen=address
IP address to listen on. Currently only accepts one IP address.
By default all addresses are listend to.
.PP logappend={yes|no}
When pluto is logging to a file, as specified by logfile=, open the
log file in append mode or truncate mode. Since, on modern systems,
pluto is restarted by other daemons, such as systemd(8), this
option should be left as its default, yes, to preserve the log entries of
previous runs of pluto.
This option is mainly intended for developers when running the test suite,
which needs to create new log files from scratch.
The default is yes.
Prior to Libreswan version 5.3 pluto, when invoked without a config
file, would set this option to no.
.PP logfile=file
Instead of logging using syslog(2) log to the specified
file.
.PP logip={yes|no}
If pluto is instructed to log the IP address of incoming connections. 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.
The default is no.
.PP loglimit={yes|no}
Whether pluto's internal log rate limiting is enabled. When enabled, pluto
limits the number of repetitive log messages (such as malformed packets or
bad certificates) to prevent excessive logging under heavy load. Setting
this to no disables all rate limiters, allowing every log message to
be emitted. This is useful for debugging or when full log visibility is
required.
The rate limit counters are reset once every hour.
The default is yes.
History: loglimit= was added in Libreswan 5.4.
.PP logtime={yes|no}
When pluto is directed to log to a file using logfile=, this option
determines whether or not to log the current timestamp as prefix. The no
value can be used to create logs without ephemeral timestamps, such as those
created when running the test suite.
The default is yes.
Prior to Libreswan version 3.14, this option was called
plutostderrlogtime
.PP
max-halfopen-ike=count[Ki|Mi|Gi|Ti|Pi|Ei]
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 is 50000.
.PP myvendorid=string
The string to use as our vendor id (VID) when
send-vendorid=yes.
The default is OE-Libreswan-VERSION.
.PP nflog-all=
If set, the NFLOG group number to log all pre-crypt and post-decrypt traffic
to. The value 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.
The default is 0 (no logging at all).
.PP nhelpers=count
How many pluto helpers are started to help with cryptographic
operations. 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.
By default, pluto will start as 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.
.PP nssdir=directory
Specifies a directory for NSS database files. It may contain the following
files:
.PP pkcs11.txt
Detailed info about NSS database creation parameters.
.RE .PP cert9.db
NSS Certificate database.
.RE .PP key4.db
NSS Key database.
.RE
.sp
The default is /var/lib/ipsec/nss.
When SELinux runs in enforced mode, changing this requires a similar change
in the SELinux policy for the pluto daemon.
.PP
ocsp-cache-max-age=seconds[us|ms|s|m|h|d|w]
The maximum age before a new fetch will be attempted.
The default is 1 day (1d).
.PP
ocsp-cache-min-age=seconds[us|ms|s|m|h|d|w]
The minimum age before a new fetch will be attempted.
The default is 1 hour (1h).
.PP
ocsp-cache-size=count[Ki|Mi|Gi|Ti|Pi|Ei]
The maximum size (in number of certificates) of OCSP responses that will be
kept in the cache. Setting this value to 0 means the cache is disabled.
The default is 1000.
.PP ocsp-enable={yes|no}
Whether to perform Online Certificate Store Protocol ("OCSP")
checks on those certificates that have an OCSP URI defined.
The default is no.
.PP ocsp-method={get|post}
The HTTP methods used for fetching OCSP data. 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.
The default is get.
.PP ocsp-strict={yes|no}
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.
The strict mode refers to the NSS ocspMode_FailureIsVerificationFailure mode,
while non-strict mode refers to the NSS
ocspMode_FailureIsNotAVerificationFailure mode.
The default is no.
.PP
ocsp-timeout=seconds[us|ms|s|m|h|d|w]
The time until an OCSP request is aborted and considered failed.
The default is 2 seconds (2s).
.PP 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.
.PP ocsp-uri=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.
.PP plutodebug=option
A comma separated list of options that globally enable internal debug logs.
For debug logs of a single connection, see debug=.
.if n .sp
Note
This feature is used by Libreswan developers when debugging libreswan
internals. The default logs should provide sufficient information to
diagnose most configuration and connection problems.
.sp .5v
Below is a select list of debug options (for a complete list ipsec whack --debug help):
.PP routing
Dump connection changes (for instance, routed, up, negotiating, ...) and how they interact with the kernel. Helpful when debugging connection transitions, and corresponding updates to kernel state/policy.
.RE
.PP base
In addition to routing, include general debug messages.
.RE
.PP cpu-usage
Dump the CPU time consumed as an event is processed. Only recommended when diagnosing performance problems.
.RE
.PP refcnt
Dump all changes to all reference counters. Only recommended when tracking down a memory leak.
.RE
.PP all
Equivalent to routing/, base, cpu-usage, and refcnt. Recommend using either routing, or base instead.
.RE
.PP updown
Run the ipsec-updown(8) script with set -x. Only recommended when debugging the ipsec-updown(8) script.
.RE
.PP crypt
Dump calls into the NSS library. Only recommended when debugging NSS dependent code.
.RE
.PP private
Dump the cryptographic material used by the IKE and Child SAs. The format is similar to that expected by tcpdump and wireshark.
.RE
.PP tmi
It stands for Too Much Information. It is not recommended. Need we say more?
.RE
.sp All lines of debugging output are prefixed with "|" to
distinguish them from normal diagnostic messages (the the command grep -v
-e '|' pluto.log can be used to filter out the debug logs).
.PP protostack=
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).
.PP seccomp={enabled,tolerant,disabled}
Set the seccomp kernel syscall whitelisting feature. When set to
enabled and 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. When 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.
By default, seccomp is disabled, as there is a significant performance
penalty, custom updown scripts could trigger false positives, and system
library updates could also trigger false positives. A false positive (or
real malicious remote code execution of a bad syscall) will cause the
pluto daemon to crash or hang.
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.
To see if a seccomp rule got triggered, you must run with
seccomp=enabled, and keep an eye on type=SECCOMP messages in
the audit log (usually /var/log/audit/audit.log. Note that logging
can be delayed by many seconds.
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.
.PP secretsfile=file
The file that stores the secret credentials such as preshared keys (PSKs).
See ipsec.secrets(5) for the file syntax.
The default is /etc/ipsec.secrets.
.PP 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. If specifying a value, it is recommended to
specify at least 460 bits (for FIPS) or 440 bits (for BSI).
The default is to not perform this redundant seeding.
.PP
shuntlifetime=seconds[us|ms|s|m|h|d|w]
The time until bare shunts (kernel policies not associated with connections)
are deleted from the kernel. 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
The default is 15 minutes (15m).
.PP statsbin=
This option specifies an optional external program to report tunnel state
changes too. This program can be used to notify the user's desktop (dbus,
NetworkManager) or to report tunnel changes to a central logging server.
The default is to not report tunnel state changes.
.PP syslog
The syslog(2) facility name and priority to use for
startup/shutdown log messages.
The default is daemon.error.
.PP uniqueids={yes|no}
Whether IDs should be considered identifying remote parties uniquely.
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.
The default is yes.
Prior to Libreswan version 5.3, when pluto was started directly and
without a configuration file, this option was set to no.
.PP
virtual-private=address[/prefix],...
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.
.SS "Conn Section"
.PP 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(8)
sub-commands. 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
.PP A note on terminology... In automatic keying, there are two kinds of
communications going on: transmission of user IP packets, and
gateway-to-gateway negotiations for keying, rekeying, and general control.
The data path (a set of “Child SAs”) used for user packets is
herein referred to as the “connection”; the path used for
negotiations (built with “IKE SAs”) is referred to as the
“keying channel”.
.PP To avoid trivial editing of the configuration file to suit it to each
system involved in a connection, connection specifications are written in
terms of left and right participants, rather than in terms of
local and remote. Which participant is considered left or
right is arbitrary; IPsec figures out which one it is being run on
based on internal information. This permits using identical connection
specifications on both ends. There are cases where there is no symmetry; a
good convention is to use left for the local side and right
for the remote side (the first letters are a good mnemonic).
.PP Many of the parameters relate to one participant or the other; only the
ones for left are listed here, but every parameter whose name begins
with left has a right counterpart, whose description is the
same but with left and right reversed.
.PP Parameters are optional unless marked “(required)”:
.sp
CONN PARAMETERS: GENERAL
.PP 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.
.PP keyexchange={ikev1|ikev2}
Whether to use IKEv2 (RFC 7296) or IKEv1 (RFC 4301). Currently the accepted
values are ikev1 and ikev2.
This option replaces ikev2=yes|no. Old values yes, propose and instist all
map to keyexchange=ikev2. Values no and permit are map to
keyexchange=ikev1.
The default is ikev2.
.PP ikev2={yes|no}
.if n .sp
Note
ikev2= has been deprecated since Libreswan 5.0; use
keyexchange=ikev1 or keyexchange=ikev2.
.sp .5v
Whether to use IKEv2 (RFC 7296) or IKEv1 (RFC 4301). The accepted values are yes, signifying only IKEv2 is accepted, and no, signifying only IKEv1 is accepted.
History: the original ikev2= parameter allowed the values yes, no,
propose, permit, and insist; support for propose, permit, and insist was
removed in Libreswan 3.28; the parameter ikev2= was deprecated in
Libreswan 5.0.
.PP hostaddrfamily={ipv4,ipv6}
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.
.PP clientaddrfamily={ipv4,ipv6}
This option was removed in Libreswan version 5.3.
Since Libreswan version 5.0, subnet= subnets= have allowed a
mixture of IKEv1 and IKEv2 addresses, making clientaddrfamily=
redundant.
.PP
type={tunnel|transport|passthrough|drop}
the type of the connection; currently the accepted values are tunnel,
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.
The default is tunnel.
Historic Note: KLIPS supported the option reject signifying that
packets should be discarded and a diagnostic ICMP returned. Support for
KLIPS, and this option, have been removed.
.PP iptfs={yes|no}
Enable "Aggregation and Fragmentation Mode for Encapsulating Security
Payload (ESP) and its use for IP Traffic Flow Security (IP-TFS) as defined
in RFC 9347. Currently, this is only supported for the Linux XFRM stack and
will likely be merged into Linux 6.7 or 6.8. IP-TFS allow the kernel to
combine multiple small packets into one ESP packet, which should cause a
performance gain when many small packets (eg iperf packets) are sent. It
also allows the kernel to fragment the outgoing packet stream so that the
ESP packets have a fixed size that can be set manually or fit the path MTU.
This should avoid common MTU issues with IPsec. IP-TFS can only be used with
tunnel mode and ESP. It cannot be combined with type=transport,
phase2=ah, compress=yes or tfc=yes. A number of
IP-TFS options can be tuned.
The default is no.
.PP iptfs-fragmentation={yes|no}
Whether or not to fragment IP-TFS.
On Linux and iptfs-fragmentation=no, this passes
XFRMA_IPTFS_DONT_FRAG to the kernel. (Unclear to at least one author
if this means regular ICMP Dont Fragment sending, or whether it stops IP-TFS
from fragmenting).
The default is yes.
.PP iptfs-max-queue-size=
The default IP-TFS max output queue size in octets. The output queue is where
received packets destined for output over an IP-TFS tunnel are stored prior
to being output in aggregated/fragmented form over the IP-TFS tunnel.
The default is 1000000.
.PP
iptfs-drop-time=seconds[us|ms|s|m|h|d|w]
The amount of time before a missing out-of-order IP-TFS tunnel packet is
considered lost. See also iptfs-reorder-window.
The default is 1 second (1s.
.PP
iptfs-init-delay=seconds[us|ms|s|m|h|d|w]
The amount of time prior to servicing the output queue after queueing the
first packet on said queue.
The default is 0 seconds (0s).
.PP
iptfs-reorder-window=count[Ki|Mi|Gi|Ti|Pi|Ei]
The default IP-TFS reorder window size. The reorder window size dictates the
maximum number of IP-TFS tunnel packets in a sequence that may arrive out of
order.
The default is 3.
.PP left={hostname|address}
right={hostname|address}
(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.
.PP
leftsubnet=address[/prefix[/protocol][/port],...
rightsubnet=address[/prefix[/protocol][/port],...
A comma separated list of traffic selectors behind the left or
right participant.
Each traffic selector expressed as: network-prefix / netmask/
protocol/ port where trailing elements may be omitted. For
instance: leftsubnet=1.2.3.0/24,1:2::/64,
leftsubnet=1.2.3.4/32/tcp,1:2::/128/tcp,
leftsubnet=1.2.3.4/31/tcp/22,1:2::/128/tcp/22.
If both leftsubnet= and rightsubnet= are specified, all combinations will be
established as a single IPsec tunnel.
When omitted, essentially assumed to be left, signifying that the left end of
the connection goes to the left participant only.
.if n .sp
IKEv1
In IKEv1 only a single selector is allowed and it is limited to specifying a
subnet as in: network / netmask
.sp .5v
.if n .sp
IKEv1
IKEv1 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.
.sp .5v
.if n .sp
Use with leftprotport and leftsubnets
Compatible with libreswan version 4, a simple leftsubnet (specifying a single
network prefix and netmask) may be combined with leftprotoport and
leftsubnets. Anything more complicated should be converted to use the
selector syntax.
.sp .5v
History: support for specifying multiple selectors, the protocol, and the
port was added in Libreswan 5.0.
.PP
leftsubnets=address[/prefix],...
rightsubnets=address[/prefix],...
Specify multiple private subnets behind the participant, expressed as
networkA/netmaskA,networkB/netmaskB,....
If both a leftsubnets= and rightsubnets= are defined, all
combinations of subnet tunnels will be established as separate 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.
.PP leftvti=
rightvti=
the address/mask to configure on the VTI interface when vti-interface
is set. It takes the form of network/netmask Currently,
IPv4 and IPv6 addresses with cidr netmask are supported. This option is
often used in combination with routed based VPNs.
.PP
leftaddresspool=address[/prefix[/subnet-mask]|address-address,...
rightaddresspool=address[/prefix[/subnet-mask]|address-address,...
Comma separated list of address pools from where the IKEv1 (IPv4 Mode Config
server) and IKEv2 (IPv4 and IPv6 configuration payload server) can assign IP
addresses to clients. At most one one IPv4 and one IPv6 pool may be
specified. The leftaddresspool= option can not be combined with with
either the leftsubnet or leftsubnets options.
A pool is specified using either an address range (for instance,
leftaddresspool=192.168.1.100-192.168.1.200 or CIDR (for instance,
leftaddresspool=2001:db8:0:3:1::/97) syntax. For IPv6, the CIDR
syntax has been extended to also allow the specification of a subnet, for
instance leftaddresspool=2001:db8:0:3:1::/60/64 will allocate
/64 leases. While address pools are grown as required and leases are
reclaimed, the size of an address pool should be reasonable. For instance,
the pool leftaddresspool=10.0.0.0-11.0.0.0 will eventually result in
an in-memory structure containing 16 million leases.
Address pools specifying the exact same range are shared between connections.
Different addresspools cannot partially overlap.
For IKEv1, when right is configured as a server using
rightxauthserver=yes, this option specifies the address pool from
which IP addresses are taken to assign the left clients during the
Mode Config exchange. Generally, the leftaddresspool= option will be
accompanied by leftxauthclient=yes, rightxauthserver=yes and
rightsubnet=0.0.0.0/0 option.
History: support for IPv6 addresses was added in Libreswan 3.30; support
combined IPv4 and IPv6 address pools was added in Libreswan 5.0 support for
IPv6 addresspool subnets was added in Libreswan 5.4.
.if n .sp
Limitations
Libreswan 5.4 does not support an address pool (addresspool=) combined
with with additional fixed selectors (subnet=); patches would be
welcome.
.sp .5v
.PP
leftprotoport=protocol[/port]
rightprotoport=protocol[/port]
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 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 environment variables
PLUTO_MY_PROTOCOL, PLUTO_PEER_PROTOCOL, PLUTO_MY_PORT,
and PLUTO_PEER_PORT are available for use in ipsec _updown
scripts (see ipsec-updown(8)). 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.
.if n .sp
Use with leftsubnet=.
With IKEv2, the leftsubnet= specification can include the protocol and
port. Combining that syntax with protoport= is not supported.
.sp .5v
.PP
leftnexthop={hostname|address}
rightnexthop={hostname|address}
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.
.PP leftsourceip=address
rightsourceip=address
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.
.PP leftupdown=[command]
rightupdown=[command]
The command to run to adjust routing and/or firewalling when the
status of the connection changes. By default, command is passed to
/bin/sh -c (see sh(1)) and run synchronously. See
updown-config= for how this can be changed.
command may include positional parameters separated by white space
(this requires enclosing the whole string in quotes). When invoked using
sh(1), command may include metacharacters (although is is
considered unwise).
An example to enable routing when using the XFRM stack, one can use:
.RS 4 leftupdown="ipsec _updown --route yes"
To disable calling an updown script, set it to the empty string, eg
leftupdown=.
Connections with type= set to passthrough, reject or
drop never run ipsec _updown.
For more information, see the command ipsec-updown(8) and the option
updown-config=.
The default is ipsec _updown.
Relevant only locally, other end need not agree on it.
.PP leftupdown-config={async|exec}
rightupdown-config={async|exec}
Modify how the updown command is run.
.PP exec
Invoke the updown command directly using execvpe(3). By default, the updown command is invoked using /bin/sh -c (see sh(1)).
.RE
.PP async
On the IKE SA responder (server), when establishing an IKEv2 Child SA, invoke the updown command once and asynchronously. Normally there is one invocation of the updown command for each combinations of the PLUTO_VERB (prepare, route, up) combined with each combinations of the Child SA's selectors.
For more information see ipsec-updown(8)
.if n .sp
Caution
This option is experimental.
.sp .5v
.RE
.sp
History: updown-config= was added in Libreswan 5.4.
.PP leftcat={yes|no}
rightcat={yes|no}
Whether to perform Client Address Translation ("CAT") when using
Opportunistic IPsec behind NAT. 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 nftables or 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.
The default is no.
.PP leftfirewall=
rightirewall=
This option is obsolete and should not used anymore.
.PP 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)).
.PP 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.
.RE
.sp
CONN PARAMETERS: AUTOMATIC KEYING
.PP 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.
.PP auto=
what operation, if any, should be done automatically at IPsec startup;
currently-accepted values are:
.PP auto=add
equivalent to:
ipsec add connection
.RE
.PP auto=ondemand
equivalent to:
ipsec add connection
ipsec route connection
.RE
.PP auto=up
auto=start
equivalent to:
ipsec add connection
ipsec up connection
.RE
.PP auto=ignore
signifying no automatic operation when Libreswan is starting (also the default)
.RE
.PP auto=keep
signifying an add plus an attempt to keep the connection up once the remote peer brought it up
.RE
.sp
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=up to
ensure that any reboot causes immediate renegotiation).
See the config setup discussion below.
.PP authby=
How the two security gateways should authenticate each other. A comma
separated list of one or more of the following:
.PP ecdsa
ecdsa-sha2
ECDSA digital signature based authentication with any of the hash algorithms SHA2_256, SHA2_384, or SHA2_512.
.RE
.PP ecdsa-sha2_256
ecdsa-sha2_384
ecdsa-sha2_512
ECDSA digital signature based authentication with the specified SHA2_256, SHA2_384, or SHA2_512 hash algorithm.
.RE
.PP eddsa
EDDSA digital signature based authentication on curve on curve 25519.
.RE
.PP rsa
rsasig
RSA-PKCSv1.5 digital signature based authentication with SHA1; and, when IKEv2, RSASSA-PSS digital signature authentication with either SHA2_256, SHA2_384, or SHA2_512.
.RE
.PP rsa-sha1
RSA-PKCSv1.5 digital signature based authentication with SHA1
.RE
.PP rsa-sha2
RSASSA-PSS digital signature based authentication with any of the hash algorithms SHA2_256, SHA2_384, or SHA2_512.
.RE
.PP rsa-sha2_256
rsa-sha2_384
rsa-sha2_512
RSASSA-PSS digital signature based authentication with the specified SHA2_256, SHA2_384, or SHA2_512 hash algorithm.
.RE
.PP secret
Shared secrets (PSK) authentication; cannot be combined with other authentication methods.
.RE
.PP never
Negotiation is never to be attempted or accepted; cannot be combined with other authentication methods.
.RE
.PP null
NULL-authentication; cannot be combined with other authentication methods.
.RE
.sp
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, rsasig,ecdsa which allows ECDSA with SHA-2 and RSA with
SHA2 or SHA1. 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.
Note that authby cannot be used for asymmetric authentication.
Instead, IKEv2 must be enabled and the options leftauth and
rightauth used.
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 when 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.
.PP
send-supported-auth-methods={yes|no}
Whether to send the SUPPORTED_AUTH_METHODS notification to the remote peer.
When enabled, the locally supported authentication methods are announced in
IKE_SA_INIT response and IKE_AUTH request, allowing the peer to pick a
compatible method before sending its AUTH payload.
The default is no.
.if n .sp
Caution
This option is experimental and implements the SUPPORTED_AUTH_METHODS
notification defined in RFC 9593.
.sp .5v
.PP ike=ike-proposal,...
A list of proposals specifying the cryptographic algorithms to negotiate when
establishing an IKE SA (ISAKMP SA, or Phase 1). For instance:
The basic syntax is:
ENCRYPTION_ALGORITHMS["-"PRF_ALGORITHMS]["-"INTEGRITY_ALGORITHMS]["-"KE_ALGORITHMS]
For the full syntax, see the Proposals section. Specifying both a PRF and INTEGRITY algorithm is not recommended.
Enabled cryptographic algorithms and default proposals are logged by
pluto during startup (see ipsec-pluto(8)).
.PP sha2-truncbug={yes|no}
Enable the use of the draft 96-bit trunacted hash (instead of the 128-bit
truncated has specified in the final RFC) when negotiating ESP with
esp=sha2_256.
This option is required when interoperating with Linux, before 2.6.33, and
some Cisco routers (2811?).
Another workaround is to switch from sha2_256 to sha2_512.
The default is no.
.PP ms-dh-downgrade={yes|no}
Whether to allow a downgrade of Diffie-Hellman 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
ms-dh-downgrade=yes (and adding modp1024 proposals to the ike
line) will allow this downgrade attack to happen. This should only be used
to support Windows that feature this bug.
The accepted values are no, (the default) or yes.
.PP dns-match-id={yes|no}
Whether to perform an additional DNS lookup and confirm the remote ID payload
with the DNS name in the reverse DNS PTR record. 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.
The default is no.
.PP require-id-on-certificate={yes|no}
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.
.PP
ppk={no|propose|yes|insist|never}
Post-quantum preshared keys (PPKs) to be used. Currently the accepted values
are: propose, permit, or yes, signifying we allow the of 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. This
feature is based on RFC 8784.
The default is propose.
.PP ppk-ids=
EXPERIMENTAL: Specify which PPK_ID's to look for in .secrets file. The value
must be a string (enclosed in quotes) containing a comma-separated list with
PPK_ID's. Whitespaces cannot be a part of PPK_ID, i.e., they will be seen as
a delimiter. If some PPK_ID's are specified and PPK feature is enabled
(ppk=), one of the PPK secrets must have an ID matching one of the
specified PPK_ID's. If this option is not set and the PPK feature is
enabled, any matching PPK secret will be used.
.PP
nat-ikev1-method={drafts|rfc|both|none}
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. 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.
The default is both.
.PP share-lease={yes|no}
Whether multiple outoging IKEv1 connections that are not specifying a local
subnet should use the lease IP given by the server of the first connection.
The default and expected behaviour (of emulating a Cisco client) is yes. It
can be disabled by setting it to no.
.PP esp=esp-proposal,...
A list of proposals specifying the cryptographic algorithms to negotiate when
establishing an ESP Child SA (Phase 2 IPsec SA). DH). For instance:
The basic syntax is:
ENCRYPTION_ALGORITHMS["-"INTEGRITY_ALGORITHMS]["-"KE_ALGORITHMS]
For the full syntax, see the Proposals section.
Enabled cryptographic algorithms and default proposals are logged by
pluto during startup (see ipsec-pluto(8)).
.PP ah=ah-proposal,...
A comma separated list of proposals specifying the cryptographic algorithms
to negotiate when establishing an AH Child SA (Phase 2, IPsec SA). For
instance:
The basic syntax is:
INTEGRITY_ALGORITHMS["-"KE_ALGORITHMS]
For the full syntax, see the Proposals section.
Enabled cryptographic algorithms and default proposals are logged by
pluto during startup (see ipsec-pluto(8)).
.if n .sp
Note
AH is not recommended. A deployment using tunnel mode can be protected using
ESP with esp=null (null encryption).
.sp .5v
.PP phase2={esp|ah}
Sets the type of SA that will be produced. Valid options are: esp for
encryption and integrity protection, ah for integrity protection only.
Instead of specifying both phase2= and phase2alg=, the
parameters ah= and esp= can be used to directly specify the
Child (IPsec) SA's protocol and cryptographic algorithms.
Historic note: 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.
Historic note: the term Phase 2 dates back to the original IKEv1
specificiation where the Child (IPsec) SA was established using a second
(Phase 2) exchange; since IKEv2 can establish a Child SA during the initial
exchange the term no longer applies.
History: ah= and esp= were made fully functional in Libreswan
5.3, prior to this they were aliases for phase2alg=.
The default is phase2=esp.
.PP phase2alg=proposal,...
Specify the cryptographic algorithms to be negotiated as part of establishing
phase2= Child (IPsec) SA. For a detailed description of the proposal
syntax see the Proposals section.
Instead of specifying both phase2= and phase2alg=, the
parameters ah= and esp= can be used to directly specify the
Child (IPsec) SA's protocol and cryptographic algorithms.
Historic note: the term Phase 2 dates back to the original IKEv1
specificiation where the Child (IPsec) SA was established using a second
(Phase 2) exchange; since IKEv2 can establish a Child SA during the initial
exchange the term no longer applies.
History: ah= and esp= were made fully functional in Libreswan
5.3, prior to this they were aliases for phase2alg=.
.PP fragmentation={yes|no}
Whether or not to allow IKE fragmentation. In addition IKEv1 allows
force.
The default is yes.
IKEv2 fragmentation support is implemented using RFC 7383.
IKEv1 fragmentation capabilities are negotiated via a well-known private
vendor id. 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.
.PP ikepad={yes|no}
Work around IKEv1 padding issues when inter-operating with other IKE
daemons.
By default, Libreswan pads messages to a minimum of 4-bytes. While this is
allowed it may cause interoperability issues. To remove this padding,
specify ikepad=no (note that this does not affect messages
encrypted using a block-mode cipher where padding is always added).
Prior to Libreswan version 5.2, some MODECFG payloads were incorrectly padded
to 4-bytes which caused interoperability issues. To restore this behaviour,
specify ikepad=yes.
The default is no.
In IKEv2, this option is ignored.
Background
It was thought that padding messages by 4-bytes was causing interoperability
issues with Checkpoint (ikepad=no was added as a workaround).
However, it's since been determined that Racoon also had interoperability
issues and the cause was the padding of some XAUTH and MODECFG payloads.
Setting ikepad=no fixed interoperability because it was also
disabling that padding. The padding of XAUTH and MODECFG was removed in
Libreswan version 5.2.
Further details can be found in the RFCs, see: RFC-2409 section 5.3, Phase 1
Authenticated With a Revised Mode of Public Key Encryption, “the last
byte of the padding contains the number of padding bytes” and
“there will always be padding”; RFC-2408 section 3.5, Proposal
Payload, “there is no padding applied to the payload, however, it can
be applied at the end of the message”; RFC-2408 section 3.6,
Transform Payload, “then subsequent payloads will not be aligned and
any padding will be added at the end of the message to make the message
4-octet aligned”.
.PP mobike={yes|no}
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. Only connection acting as modecfgclient will allow the
initiator to migrate using mobike. Only connections acting as modecfgserver
will allow clients to migrate.
The default is no.
VTI and MOBIKE might not work well when used together.
.PP intermediate={yes|no}
Whether to enable the INTERMEDIATE exchange in IKEv2 (RFC 9242). Currently
the accepted values are: yes, signifying we propose to use the INTERMEDIATE
exchange for this connection; and no, signifying we will not use the
INTERMEDIATE exchange for this connection.
The default is no.
.PP esn={yes|no|either}
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. If either is specified as an initiator, the responder will make the
choice. As a responder, if either is received, yes is picked.
The default is either.
If replay-window is set to 0, ESN is disabled as some (most?) IPsec stacks
won't support ESN in such a configuration.
.PP decap-dscp={yes|no}
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.
Currently this feature is only implemented for the Linux XFRM stack.
The default is no.
.PP encap-dscp={yes|no}
Enable encapsulating the Differentiated Services Code Point (DSCP, formerly
known as Terms Of Service (TOS)) bits. The extra xfrm flag
"dont-encap-dscp" prevents these bits from being copied from the
unencrypted IP packets to the encrypted IP packets.
The default is yes.
Currently this feature is only implemented for the Linux XFRM stack.
.PP nopmtudisc={yes|no}
Disable Path MTU discovery for the IPsec SA. Currently this feature is only
implemented for the Linux XFRM stack.
The default is no.
.PP narrowing={yes|no}
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.
.PP
nic-offload={no|crypto|packet}
Set the method of Network Interface Controller (NIC) hardware offload for
ESP/AH packet processing. The value yes is a backwards compatible value for
crypto. The nic-offload option is separate from any CPU hardware
offload available. When set to crypto, only cryptographic operations are
offloaded to the NIC card. When set to packet, the entire packet processing
including the encryption/decryption is offloaded to the NIC card.
The default is no.
Crypto NIC-offload is available starting Linux 4.13 using the XFRM IPsec
stack. Packet NIC-offload is available starting Linux 6.3. Both require that
the Linux kernel is compiled with the options CONFIG_XFRM_OFFLOAD,
CONFIG_INET_ESP_OFFLOAD and CONFIG_INET6_ESP_OFFLOAD. Network card support
can be seen by the presence of the esp-hw-offload capability using
the ethtool -S command. The Linux kernel attempts to fall back from
crypto hardware offload to software, but only for some algorithms (AEADs
only?). There is no fallback from packet offload to crypto offload. At the
time of libreswan 5.0, we are only aware of the Nvidia/Mellanox ConnectX-7
(and to some extend ConnectX-6) cards supporting packet offload.
In general, it makes no sense to try to offload older (non-AEAD)
cryptographic algorithms such as AES-CBC or 3DES, as these algorithms are so
much slower than AEAD algorithms (such as AES-GCM) that one would gain more
performance by switching the algorithm to AEAD than by offloading. As such,
AES-CBC tends to not be implemented in offload hardware. This option has
also no effect on IKE packets, which are never offloaded, although IKE
encryption does use supported CPU hardware instructions, such as AESNI.
.PP leftid=
rightid=
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.
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 backslash (eg OU='Foo\, Bar and associates')
.PP leftpubkey=
rightpubkey=
The left participant's public key for signature (either RSA, ECDSA or EdDSA)
authentication. The leftpubkey is the generic option. The key should
be in base-64 encoded RFC 2537 format (with 0s prepended), or one of the
following:
.PP %none
the same as not specifying a value (useful to override a default)
.RE .PP %dnsondemand
(the default) the key is to be fetched from DNS at the time it is needed.
.RE .PP %dns
Treated as %dnsondemand. The identity used for the left participant must be a specific host, not %any or another magic value.
.RE .PP %cert
the information required from a certificate defined in %leftcert and automatically define leftid for you
.RE
.sp
Additionally, one can provide: a DER-encoded public key, or a raw public key
generated using ipsec {rsasig,ecdsa,eddsa}key command.
.if n .sp
Caution
If two connection descriptions specify different public keys for the same
leftid, confusion and madness will ensue.
.sp .5v
.PP leftrsasigkey=
rightrsasigkey=
The left/right participant's public key for RSA signature authentication. The
argument can be one of the generic arguments listed in
leftpubkey/rightpubkey option. The generic DNS-related
arguments can use the mechanism described in either RFC 3110 (previously RFC
2537) or RFC 4025.
Additionally, one can provide a raw public key generated using ipsec
rsasigkey command.
.if n .sp
Caution
If two connection descriptions specify different public keys for the same
leftid, confusion and madness will ensue.
.sp .5v
.PP leftecdsakey=
rightecdsakey=
The left/right participant's public key for ECDSA signature authentication.
The argument can be one of the generic arguments listed in
leftpubkey/rightpubkey option. The generic DNS-related
arguments can use the mechanism described in RFC 8005.
Additionally, one can provide a raw public key generated using ipsec
ecdsakey command.
.if n .sp
Caution
If two connection descriptions specify different public keys for the same
leftid, confusion and madness will ensue.
.sp .5v
.PP lefteddsakey=
righteddsakey=
The left/right participant's public key for EdDSA signature authentication.
The argument can be one of the generic arguments listed in
leftpubkey/rightpubkey option. The generic DNS-related
arguments can use the mechanism described in RFC 9373.
Additionally, one can provide a raw public key generated using ipsec
eddsakey command.
.if n .sp
Caution
If two connection descriptions specify different public keys for the same
leftid, confusion and madness will ensue.
.sp .5v
.PP leftcert=
rightcert=
If you are using left{pub,rsasig,ecdsa,eddsa}key=%cert/
right{pub,rsasig,ecdsa,eddsa}key=%cert, this defines the certificate
nickname of your certificate in the NSS database. This can be on software or
hardware security device.
.PP leftckaid=
rightckaid=
The CKAID of the X.509 certificate or host key.
For X.509 certificates, the CKAID is either the certificate's
SubjectKeyIdentifier or the public key's SHA1 fingerprint (when the
SubjectKeyIdentifier isn't specified). For host keys the CKAID is the SHA1
fingerprint of the public key.
.PP leftauth=
rightauth=
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").
.PP leftautheap={none|tls}
rightautheap={none|tls}
Whether the security gateways will authenticate uing an EAP method.
Acceptable values are none and tls for EAPTLS. If EAP is the only
authentication method, set leftauth=none in addition to
leftautheap=tls.
The default is none.
The EAP authentication mechanisms are only available for IKEv2 based
connections.
.PP leftca=
rightca=
Specifies the Distinguished Name of the authorized Certificate Authority (CA)
that signed the certificate of the peer. When unspecified, 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.
.PP leftikeport=port
rightikeport=port
The UDP IKE port to listen on or send data to. This port cannot be 0 or 500.
For TCP, see tcp-remoteport=
.PP leftsendcert=
rightsendcert=
This option configures when Libreswan will send X.509 certificates to the
remote host. Acceptable values are:
.PP yes
always
always send a certificate
.RE
.PP sendifasked
send a certificate when the peer asks for it (for instance by sending a CERTREQ payload)
.RE
.PP no
never
never send a certificate
.RE
.sp The default for this option is always. Note that while
always is suboptimal, setting this to sendifasked may break
compatibility with other vendor's IPsec implementations, such as Cisco. If
you find that you are getting errors about no ID/Key found, you likely need
to revert this option to always.
History: sendcert= was added in Libreswan 2.5.14 with the default
sendifasked; in Libreswan 2.28, the default was changed to
always; in Libreswan 3.0, the related and obsolete global parameter
nocrsend= was removed.
.PP leftxauthserver={yes|no}
rightxauthserver={yes|no}
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.
The default is no.
.PP leftxauthclient=
rightxauthclient=
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 up
connection. 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).
.PP leftusername=
rightusername=
The username associated with this connection. The username can be the IKEv1
XAUTH username, a GSSAPI username or IKEv2 CP username. For the XAUTH
username, the XAUTH password can be configured in the file
ipsec.secrets(5).
History: the parameter was originally called xauthusername=; it was
renamed to username= in Libreswan 3.17.
.PP leftmodecfgserver={yes|no}
rightmodecfgserver={yes|no}
The end is a Mode Config server. It can push network configuration to the
client.
The default is no.
.PP leftmodecfgclient={yes|no}
rightmodecfgclient={yes|no}
Specify that the end is a Mode Config client (it can receive network
configuration from the server).
The default is no.
.PP
xauthby={file|pam|alwaysok}
When IKEv1 XAUTH support is available, set the method used by XAUTH to
authenticate the user with IKEv1. The currently supported values are file,
pam, and alwaysok.
The default is file.
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
.PP xauthfail={hard|soft}
When XAUTH support is available, set the failure method desired when
authentication has failed. 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.
The default is hard.
.PP pam-authorize={yes|no}
IKEv2 does not support receiving a plaintext username and password. 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 the IKEv1 option xauthby=pam
.PP modecfgpull={yes|no}
Pull the Mode Config network information from the server. Both server and
client must use same setting.
The default is no,
.PP remote-peer-type=
Set the remote peer type. This can enable additional processing during the
IKEv1 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.
History: the parameter was originally called remote_peer_type=; it was
renamed to remote-peer-type= in Libreswan 3.9.
.PP nm-configured={yes|no}
Mark this connection as controlled by Network Manager. Currently, setting
this to yes will cause libreswan to skip reconfiguring resolv.conf when used
with XAUTH and ModeConfig.
The default is no.
.PP
encapsulation={yes|no|auto}
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.
History: encapsulation= was added in Libreswan 3.19, and
forceencaps= was made obsolete; forceencaps= was removed in
Libreswan 5.0.
.PP
enable-tcp={no|fallback|yes}
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, 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. To receive incoming TCP connections, the config
setup option listen-tcp needs to be enabled.
The default is no.
.PP 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.
.PP nat-keepalive={yes|no}
whether to send any NAT-T keep-alives. These one byte packets prevent the NAT
router from closing its port when there is not enough traffic on the IPsec
connection.
The default is yes.
.PP initial-contact={yes|no}
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. 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.
The default is yes.
.PP cisco-unity={yes|no}
whether to send a CISCO_UNITY payload to the peer.
The default is no.
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.
.PP cisco-split={yes|no}
Use the IKEv1 MODE_CFG CISCO_SPLIT_INCLUDE payload to transfer the server's
subnet= list to the client. During the Quick Mode exchange, the
client and server will then install kernel policy that includes all the
subnets.
The default is no.
History: cisco-split was added in Libreswan 5.3.
.PP ignore-peer-dns={yes|no}
whether to ignore received DNS configuration. 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.
The default is no.
.PP accept-redirect-to=address,...
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 ignored when
accept-redirect=no.
.PP accept-redirect={yes|no}
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.
.PP
redirect-to={hostname|address},...
Where to send remote peers to via the send-redirect option. This can
be an IP address or hostname (FQDN).
.PP send-redirect={yes|no}
Whether to send requests for the remote peer to redirect IKE/IPsec SA's
during IKE_AUTH. 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 redirect
command.
The default is no.
.PP fake-strongswan={yes|no}
Whether to send a fake strongSwan Vendor ID payload to the peer.
strongSwan enables some non-standard features and private algorithms only
when it detects the strongSwan Vendor ID. The exact capabilities depend on
the strongSwan version. At the time of writing this entry this option can
enable negotiation of BEET mode (until the IETF assigns a code point),
enable some private algorithms (eg some experimental post-quantum
algorithms) and enables forwarding RADIUS attributes (which should not have
any affects with the current EAP support in libreswan). Note that
experimental algorithms on strongSwan can also be enabled using
charon.accept_private_algs and then this option is not needed.
The default is no.
.PP send-vendorid={yes|no}
whether to send our Vendor ID during IKE. The vendor id sent can be
configured using the "config setup" option myvendorid=. It
defaults to OE-Libreswan-VERSION.
The default is no.
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.
.PP overlapip={yes|no}
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.
.PP 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.
.PP
dpddelay=seconds[us|ms|s|m|h|d|w]
Set the delay (in time units, defaults to seconds) between IKEv1's Dead Peer
Detection or IKEv2's Liveness keepalives that are sent for this connection.
Set to enable checking.
The default is 0 meaning disabled.
If dpddelay is set, you might need to adjust retransmit-timeout
for IKEv2 and you must set dpdtimeout for IKEv1.
.PP
dpdtimeout=seconds[us|ms|s|m|h|d|w]
Set the length of time that pluto will idle without hearing back from the
peer. After this period has elapsed with no response and no traffic, pluto
will declare the peer dead, and remove the SA. Set value bigger than
dpddelay to enable. If dpdtimeout is set, dpddelay also
needs to be set.
The default is dpdtimeout=0, meaning disabled.
This option is only valid for IKEv1. IKEv2 uses the retransmit-timeout
(any retransmit timeout implies that the IKE SA is dead).
History: the original parameter was called dpdtimeout=; it was renamed
to ikev1-dpdtimeout= Libreswan 5.0 (with dpdtimeout= as an
alias); it was renamed back in Libreswan 5.4 (ikev1-dpdtimeout= made
the alias).
.PP pfs={yes|no}
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.
.PP aggressive={yes|no}
For IKEv1 connections, use Aggressive Mode instead of Main Mode. When this
option is enabled, IKEv1 Main Mode will no longer be allowed for this
connection.
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 esp= 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.
History: the parameter was originally called aggrmode=; it was was
renamed to aggressive= in Libreswan 3.23.
The default is aggressive=no.
.PP
ipsec-lifetime=seconds[us|ms|s|m|h|d|w]
How long a particular instance of a connection's IPsec SA (a set of
encryption/authentication keys for user packets) should last up to a maximum
of 24 hours (1d or 24h); from successful negotiation to
expiry.
Normally, the connection is renegotiated (via the keying channel) before it
expires. The two ends need not exactly agree on ipsec-lifetime=.
History: the original parameter was called keylife=, lifetime=,
and salifetime=; these were replaced by ipsec-lifetime= in
Libreswan 4.8.
The default is ipsec-lifetime=8h (eight hours).
.PP
ipsec-max-bytes=bytes[KiB|MiB|GiB|TiB|PiB|EiB]
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 renegotiation (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.).
When using Linux with nic-offload=packet set, Linux 6.7 or later is
required.
.PP
ipsec-max-packets=count[Ki|Mi|Gi|Ti|Pi|Ei]
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.
When using Linux with nic-offload=packet set, Linux 6.7 or later is
required.
.PP 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.
.PP rekey={yes|no}
whether a connection should be renegotiated when it is about to expire. The
two ends need not agree. 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.
The default is yes.
.PP
rekeymargin=seconds[us|ms|s|m|h|d|w]
how long before connection expiry or keying-channel expiry should attempts to
negotiate a replacement begin; acceptable values as for salifetime.
Relevant only locally, other end need not agree on it.
The default is 9 minutes (9m).
.PP rekeyfuzz=percent;%
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 `%'.
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.
The default is 100%.
.PP
ikelifetime=seconds[us|ms|s|m|h|d|w]
How long the connection's IKEv2 IKE SA (or IKEv1 ISAKMP SA) should last
before being replaced.
The default is 8 hours (8h>.
Prior to Libreswan version 4.2, the value was 1h.
.PP
retransmit-timeout=seconds[us|ms|s|m|h|d|w]
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 and rekey.
.PP
retransmit-interval=milliseconds[us|ms|s|m|h|d|w]
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 and rekey
.PP compress={yes|no}
whether IPComp compression of content is proposed on the connection
(link-level compression does not work on encrypted data, so to be effective,
compression must be done before encryption).
The default is no.
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.
.PP metric=number
Set the metric for added routes. This value is passed to the ipsec
_updown scripts as PLUTO_METRIC (see ipsec-updown(8)).
Acceptable values are positive numbers.
The default is 1.
.PP 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.
.PP 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 no.
.PP
send-esp-tfc-padding-not-supported={yes|no}
Whether or not to send the ESP_TFC_PADDING_NOT_SUPPORTED notification
to the peer informing it that that this end does not support Traffic Flow
Confidentiality ("TFC") (RFC-4303). Possible values are no (do not
send notifification), which allows the peer to use TFC, and yes (send
notification) which prevents to peer from using TFC when sending ESP
packets.
This does not affect whether this endpoint uses TFC when sending ESP packets
- it depends on the tfc= parameter and the peer sending sending an
ESP_TFC_PADDING_NOT_SUPPORTED notification).
History: the parameter, added in Libreswan 3.18, was originally called
send-no-esp-tfc=; it was renamed to
send-esp-tfc-padding-not-supported= in Libreswan 5.3.
The default is send-esp-padding-not-supported=no. This option
is only valid for IKEv2.
.PP nflog-group=
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.
History: the original parameter was called nflog=; it was renamed to
nflog-group= in Libreswan version 5.3.
.PP 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.
.PP mark-in=
The same as mark, but mark-in only applies to the inbound half of the
IPsec SA. It overrides any mark= setting.
.PP mark-out=
The same as mark, but mark-out only applies to the outbound half of
the IPsec SA. It overrides any mark= setting.
.PP vti-interface=
This option is deprecated. See ipsec-interface instead.
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.
.PP vti-routing={yes|no}
Whether or not to add network rules or routes for IPsec SA's to the
respective VTI devices. 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
The default is yes.
.PP vti-shared={yes|no}
Whether or not the VTI device is shared amongst connections. 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.
The default is no.
.PP ipsec-interface=device-number
Specify the IPsec Interface for "Routing based IPsec VPNs" (as
opposed to "Policy based VPNs"). 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 managed by an external routing
daemon or manually by the administrator.
By default, Libreswan is configured in managed mode. In managed mode,
Libreswan will create, configure up, down, and delete the
IPsec Interface device (on Linux, FreeBSD, and NetBSD that device is named
ipsec; OpenBSD it is named sec). To specify the IP address to
configure when creating the device also specify interface-ip=.
Alternatively, Libreswan can be configured in unmanaged mode. In unmanaged
mode, Libreswan does not manipulate the IPsec Interface Device directly.
Instead Libreswan will assume the IPsec Interface device already exists,
manipulating it directly using the low-level kernel ID (on Linux that is the
XFRMi if_id). A typical use is with namespaces where the IPsec Interface
Device and Libreswan are in separate namespace.
Possible values are:
.PP no
Do not use "Routing based IPsec VPN".
.RE .PP yes
Enable "Routing based IPsec VPNs". In managed mode, use IPsec Interface device 1 (for instance, ipsec1). In unmanaged mode, use the kernel device 1.
.RE .PP number
Enable "Routing based IPsec VPNs" using the device number. For instance, ipsec-interface=5 will use ipsec5 in managed mode, and kernel xfrm interface with if_id 5 in unmanaged mode.
.RE
.sp
The default is no.
Kernel Support:
.PP Linux (since 4.19)
This option is currently only supported on Linux kernels 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.
.RE
.PP NetBSD (since 8.0)
OpenBSD (since 7.4)
FreeBSD (since 11.0)
Supported since Libreswan 5.2.
.RE
.sp
.PP
leftinterface-ip=address[/prefix]
rightinterface-ip=address[/prefix]
The IP address and netmask to configure on a virtual device (eg
ipsecN). 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 configuring IP addresses when using deprecated
VTI.
.PP 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.
.PP
sendca={none|issuer|all}
How many of the available X.509 intermediate CA certificates to send with the
End certificate (root CA's are never sent). Specifying none sends no
intermediate certificates, issuer sends the End certificate's issuing
intermediate CA, and all sends all intermediate CAs.
The default is all.
Prior to Libreswan version 5.3, the default was none (that is, no
intermediate CAs were sent). Libreswan never sends intermediate certificates
when establishing a connection using IKEv1's Agressive Mode.
.PP sec-label=
The string representation of an access control security label that is
interpreted by the Linux Security Module (e.g. SELinux) for use with Labeled
IPsec.
For example,
policy-label=system_u:object_r:ipsec_spd_t:s0-s15:c0.c1023
Labeled IPsec support is IKEv2 only.
History: the parameter was originally called policy-label=; it was
renamed to sec-label= in Libreswan 4.2; IKEv1 support for Labeled
IPsec was removed in Libreswan 5.0.
.PP
failureshunt={none|pass|drop|reject}
What to do with packets when negotiation fails. none means install no shunt;
pass, drop, and reject have the obvious meanings.
The default is none.
.PP negotiationshunt={drop|pass}
What to do with packets during the IKE negotiation. This should almost always
be left to the default drop value to avoid cleartext packet leaking. The
only reason to set this to pass is if plaintext service availability is more
important than service security or privacy, a scenario that also implies
failureshunt=pass and most likely authby=%null using
Opportunistic Encryption.
The default is drop.
.PP debug=option
A comma separated list of options that enable internal debug logs of the
connection. For more information see the global plutodebug=
option.
.if n .sp
Note
This feature is used by Libreswan developers. The default logs should provide
sufficient information to diagnose configuration and connection
problems.
.sp .5v
.PP
reject-simultaneous-ike-auth={yes|no}
When libreswan receives IKE_AUTH request from the peer while having an
outstanding IKE_AUTH request for the same connection, reject with
AUTHENTICATION_FAILED to avoid potential SA mismatch issues. This only
applies to permanent IKEv2 connections so that the revival mechanism ensures
connection retry.
The default is no.
.RE
.sp
CONN PARAMETERS: DNS
.PP 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.
.PP modecfgdns=
The modecfgdns= option takes a comma or space separated list of IP
addresses that can be used for DNS resolution. When the connection is
brought down, the previous DNS resolving state is restored.
.PP modecfgdomains=
The modecfgdomains= option takes a comma or space separated list of
internal domain names that are reachable via the supplied modecfgdns DNS
servers.
.PP modecfgbanner=
Banner to display when peer connects using IKEv1.
.RE
.SS "OPPORTUNISTIC CONNS"
.PP 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=ondemand conn clear-or-private
type=tunnel
left=%defaultroute
authby=null
leftid=%null
rightid=%null
right=%opportunisticgroup
failureshunt=passthrough
negotiationshunt=passthrough
auto=add conn private-or-clear
type=tunnel
left=%defaultroute
authby=null
leftid=%null
rightid=%null
right=%opportunisticgroup
failureshunt=passthrough
negotiationshunt=passthrough
auto=ondemand conn private
type=tunnel
left=%defaultroute
leftid=%null
rightid=%null
right=%opportunisticgroup
negotiationshunt=drop
failureshunt=drop
auto=ondemand conn block
type=drop
authby=never
left=%defaultroute
right=%group
auto=ondemand
.SS "POLICY GROUP FILES"
.PP The optional files under /etc/ipsec.d/policies, including
.PP /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
.PP may contain policy group configuration information to supplement
ipsec.conf. Their contents are not security-sensitive.
.PP These files are text files. Each consists of a list of CIDR blocks, one
per line. White space followed by # followed by anything to the end of the
line is a comment and is ignored, as are empty lines.
.PP A connection in ipsec.conf that has right=%group or
right=%opportunisticgroup is a policy group connection. When a policy
group file of the same name is loaded at system start, the connection is
instantiated such that each CIDR block serves as an instance's right
value. The system treats the resulting instances as normal connections.
.PP For example, given a suitable connection definition private, and
the file /etc/ipsec.d/policies/private with an entry 192.0.2.3, the system
creates a connection instance private#192.0.2.3. This connection
inherits all details from private, except that its right client is
192.0.2.3.
.SS "DEFAULT POLICY GROUPS"
.PP 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.
.SS "CHOOSING A CONNECTION [THIS SECTION IS EXTREMELY OUT OF
DATE"
.PP 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.
.PP 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.
.SH "FILES"
.RS 4 /etc/ipsec.conf
.SH "SEE ALSO"
.PP ipsec(8), ipsec-rsasigkey(8)
.SH "HISTORY"
.PP Designed for the FreeS/WAN project
<https://www.freeswan.org> by Henry Spencer.
.SH "AUTHOR"
Amrinder Singh, Andrew Cagney, Antony Antony, Brady Johnson, Daiki Ueno,
Daniel Kahn Gillmor, David McCullough, D. Hugh Redelmeier, Harald Jenny,
Jose Quaresma, Kim B. Heino, Michael Richardson, Ondrej Moris, Paul Wouters,
Philippe Vouters, Pietro Monteiro, Rishabh, Sahana Prasad, Shubham Kumar,
Simon Deziel, Tuomo Soini, Vukasin Karadzic, Wolfgang Nothdurft
| 10/06/2026 | Libreswan v5.4.1-HEAD |