IPSEC.CONF(5)

💖 IPSEC.CONF(5) 💖

okay bestie, buckle up — this is ipsec.conf, from section 5 of the manual (File formats and conventions), and it's literally the main character of Libreswan config files. 🎀

✨ NAME ✨

ipsec.conf — IPsec configuration and connections. that's it, that's the vibe. 🦋

🌸 DESCRIPTION 🌸

💅 Overview

So. The ipsec.conf file specifies most of the configuration and control information for the Libreswan IPsec subsystem. The big exception? Secrets for authentication — those live elsewhere, see ipsec.secrets(5). 🔐

Libreswan reads this file during start up. Technically — and I'm being so serious right now — if Libreswan's daemon ipsec-pluto(8) is invoked directly, then the file ipsec.conf is not needed. However, that is not recommended. 🙈

Configurations can be added using either this configuration file or by using ipsec whack directly.

ipsec.conf is a text file, consisting of one or more sections. simple as that. ✨

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. 🗒️

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:

include /etc/ipsec.d/*.conf

The intention of the include facility is mostly to permit keeping information on connections, or sets of connections, separate from the main configuration file. This permits such connection descriptions to be changed, copied to the other security gateways involved, etc., without having to constantly extract them from the configuration file and then insert them back into it. Also note the also parameters (described below) which permit splitting a single logical section (e.g. a connection description) into several distinct sections. 🧚

The first significant line of the file may specify a version of this specification for backwards compatibility with freeswan and openswan. It is ignored and unused. For compatibility with openswan, specify:

version 2

A section begins with a line of the form:

type name

where type indicates what type of section follows, and name is an arbitrary name that distinguishes the section from others of the same type. Names must start with a letter and may contain only letters, digits, periods, underscores, and hyphens. All subsequent non-empty lines that begin with white space are part of the section; comments within a section must begin with white space too. There may be only one section of a given type with a given name. 👑

There are two types of section: a config section specifies general configuration information for Libreswan, and a conn section specifies an IPsec connection.

Lines within the section are generally of the form

parameter=value

(note the mandatory preceding white space). There can be white space on either side of the =. Parameter names follow the same syntax as section names, and are specific to a section type. Unless otherwise explicitly specified, no parameter name may appear more than once in a section.

An empty value stands for the 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.

Numeric values are specified to be either an integer (a sequence of digits) or a decimal number (sequence of digits optionally followed by . and another sequence of digits).

There is currently one parameter that is available in any type of section:

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. iykyk 🫶

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

🦋 Values

🍓 Byte Counts And Binary Data

Options, such as ipsec-max-bytes, that expect a numeric byte count, also accept decimal fractions, and the following multipliers as a suffix:

KiB — kilobytes (1024 bytes)
MiB — megabytes (1024*1024 bytes)
GiB — gigabytes (1024*1024*1024 bytes)
TiB — terabytes (1024*1024*1024*1024 bytes)
PiB — petabytes (1024*1024*1024*1024*1024 bytes)
EiB — exabytes (1024*1024*1024*1024*1024*1024 bytes)

⏱️ Duration

Options, such as retransmit-timeout, that expect a numeric duration, also accept decimal fractions, and the following multipliers as a suffix:

us — microseconds (1/1_000_000 seconds)
ms — milliseconds (1/1_000 seconds)
s — seconds
m — minutes (60 seconds)
h — hours (60*60 seconds)
d — days (24*60*60 seconds)
w — weeks (7*24*60*60 seconds)

For instance, the following are each equivalent: 1ms and 1000us; 0.5s and 500ms; 1.5h and 90m. math is mathing 💜

🔥 Proposals

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

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

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.

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

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.

Enabled cryptographic algorithms and default proposals are logged by pluto during startup (see ipsec-pluto(8)). 🎀

Note 📌 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).

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

Limitations: Libreswan 5.4 does not support the IKE_FOLLOWUP_KE exchange. 😭

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"). 💀

👑 Config Setup Section

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

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

The currently-accepted configuration parameters are:

audit-log={yes|no} — should pluto be out here producing Linux Auditing System log messages or not? 👀 If you enable it, pluto logs start, stop and fail for the negotiation of IKE and IPsec SAs. The kernel also logs success and failures for actually adding and removing IPsec SAs from the kernel's SADB, bestie. On non-Linux systems this option is literally ignored 🙈. If it's enabled but the kernel is lacking audit support, audit messages just don't get sent. But — and this is the scary part — if the kernel has audit support and using it fails, pluto will abort 💀. Also 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.

crl-strict={yes|no} — if this is 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, and active connections will be terminated at rekey time 😭. This setup is more secure, but vulnerable to downtime if the CRL expires. Trade-offs, babes.

The default is no.

Prior to Libreswan version 3.16, this option was called strictcrlpolicy.

crl-timeout=seconds[us|ms|s|m|h|d|w] — the timeout used when fetching CRLs ⏳.

The default is 5 seconds (5s).

crlcheckinterval=seconds[us|ms|s|m|h|d|w] — interval expressed in second units (like, crlcheckinterval=8h for 8 hours ✨), after which pluto will fetch new Certificate Revocation List (CRL) from crl distribution points. The list of used CRL distribution points is 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).

curl-iface= — the name of the interface that is used for CURL lookups 🌐. This is needed in rare situations where the interface needs to be forced to be different from the default interface used based on the routing table. iykyk.
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.

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.

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.

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.

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.

dnssec-rootkey-file=file — the file that contains the DNSSEC root zone public key 🔑.

The default is /var/lib/unbound/root.key.

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. So like, heads up.

The default is /run/pluto.

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.

rundir=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.

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, fr fr. One use case of shortening these is if opportunistic 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.

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 Opportunistic 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 referred to as bare.

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

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.

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.

ikev1-policy={drop,accept,reject} — what to do with received IKEv1 packets 🤔.

Valid options are:

drop — silently drop any received IKEv1 packet
accept — accept IKEv1 connections
reject — reply with an error.

If this option is set to drop or reject, an attempt to load an IKEv1 connection will fail, as these connections would never be able to receive a packet for processing. Makes sense, bestie 💅.

The default is drop.

ipsec-interface-managed={yes|no} — specify whether the IPsec Interface specified by ipsec-interface is managed by Libreswan 🛠️.

Possible values are:

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.

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.

The default is yes.

ipsecdir=directory — specifies a directory for administrator-controlled configuration files and directories 🗂️. It may contain the following files and directories:
- passwd — (optional) for IKEv1 XAUTH support if not using PAM (this file should not be world-readable 🙈). See README.XAUTH for more information.
nsspassword — this optional file holds the passwords needed to unlock the NSS database in /var/lib/ipsec/nss. Bestie, this file should not be world-readable 💅. See README.nss for more information.
policies/ — a directory containing policy group configuration information. See POLICY GROUP FILES in this document for more information. 👑

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.

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

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.

listen=address — IP address to listen on. Currently only accepts one IP address. By default all addresses are listened to. 🎧
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.

logfile=file — instead of logging using syslog(2), log to the specified file. 🗂️
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.

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.

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.

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.

myvendorid=string — the string to use as our vendor id (VID) when send-vendorid=yes. 🏷️

The default is OE-Libreswan-VERSION.

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

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 many helpers as the number of CPUs, minus 1 to dedicate to the main thread. For machines with less than 4 CPUs, an equal number of helpers to CPUs are started.

nssdir=directory — specifies a directory for NSS database files. It may contain the following files: 🗃️
- pkcs11.txt — detailed info about NSS database creation parameters.
- cert9.db — NSS Certificate database.
- key4.db — NSS Key database.

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.

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

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

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.

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.

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.

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.

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

ocsp-trustname= — the nickname of the certificate that has been imported into the NSS database of the server handling the OCSP requests. This requires the ocsp-uri option to be set as well. This option and the previous options sets the OCSP default responder. 🪪
ocsp-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. 🌐
plutodebug=option — a comma separated list of options that globally enable internal debug logs. For debug logs of a single connection, see debug=. 🐛

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.

Below is a select list of debug options (for a complete list ipsec whack --debug help):

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.
base — in addition to routing, include general debug messages.
cpu-usage — dump the CPU time consumed as an event is processed. Only recommended when diagnosing performance problems.
refcnt — dump all changes to all reference counters. Only recommended when tracking down a memory leak.
all — equivalent to routing/, base, cpu-usage, and refcnt. Recommend using either routing, or base instead.
updown — run the ipsec-updown(8) script with set -x. Only recommended when debugging the ipsec-updown(8) script.
crypt — dump calls into the NSS library. Only recommended when debugging NSS dependent code.
private — dump the cryptographic material used by the IKE and Child SAs. The format is similar to that expected by tcpdump and wireshark.
tmi — it stands for Too Much Information. It is not recommended. Need we say more? 💀

All lines of debugging output are prefixed with "|" to distinguish them from normal diagnostic messages (the command grep -v -e '|' pluto.log can be used to filter out the debug logs). 🎀

protostack= — okay so this one decides which protocol stack is gonna be used. Valid values are xfrm and bsd. Bestie, this option should no longer be set, because 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). 💅
seccomp={enabled,tolerant,disabled} — Set the seccomp kernel syscall whitelisting feature. Here’s the vibe check:
- 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.

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. 🔐
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. 🌱
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 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). ⏱️
statsbin= — This option specifies an optional external program to report tunnel state changes to. 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. 📊
syslog — The syslog(2) facility name and priority to use for startup/shutdown log messages. The default is daemon.error. 📝
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. 🪪

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

Conn Section 🎀

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

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”. 🫶

To avoid trivial editing of the configuration file to suit it to each system involved in a connection, connection specifications are written in terms of left and right participants, rather than in terms of local and remote. Which participant is considered left or right is arbitrary; IPsec figures out which one it is being run on based on internal information. This permits using identical connection specifications on both ends. There are cases where there is no symmetry; a good convention is to use left for the local side and right for the remote side (the first letters are a good mnemonic). ✨

Many of the parameters relate to one participant or the other; only the ones for left are listed here, but every parameter whose name begins with left has a right counterpart, whose description is the same but with left and right reversed.

Parameters are optional unless marked “(required)”:

CONN PARAMETERS: GENERAL 🌈

The following parameters are relevant to IKE automatic keying. Unless otherwise noted, for a connection to work, in general it is necessary for the two ends to agree exactly on the values of these parameters.

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

ikev2={yes|no} —

Note: ikev2= has been deprecated since Libreswan 5.0; use keyexchange=ikev1 or keyexchange=ikev2.

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.

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 of using the new hostaddrfamily and clientaddrfamily.

clientaddrfamily={ipv4,ipv6} — This option was removed in Libreswan version 5.3.

Since Libreswan version 5.0, subnet= and subnets= have allowed a mixture of IKEv1 and IKEv2 addresses, making clientaddrfamily= redundant. 💀

type={tunnel|transport|passthrough|drop} — bestie, this is the connection's whole personality 💫. tunnel means a host-to-host, host-to-subnet, or subnet-to-subnet tunnel; transport means host-to-host transport mode; passthrough means no IPsec processing should be done at all; drop means packets should be discarded. The default is tunnel, periodt. Historic Note: KLIPS supported the option reject, meaning packets should be discarded and a diagnostic ICMP returned. Support for KLIPS, and this option, have been removed. 💅
iptfs={yes|no} — turns on “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 lets the kernel 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. 🦋
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. 🌸
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. 🎀
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). 🍓
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). 🧚
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. ⭐
left={hostname|address}, right={hostname|address} — (required) the IP address or DNS hostname of the left participant's public-network interface (right= is the same kind of deal for the right side) 💖. 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, iykyk:

%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.)
%any — signifies an address to be filled in (by automatic keying) during negotiation.
%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.
%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.
NAT heads-up: if using IP addresses in combination with NAT, always use the actual local machine's (NATed) IP address, and if the remote (eg right=) is NATed as well, the remote's public (not NATed) IP address. Note that this makes the configuration no longer symmetrical on both sides, so you cannot use an identical configuration file on both hosts. 🙈

leftsubnet=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 is 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.
- IKEv1: only a single selector is allowed, and it is limited to specifying a subnet as in: network / netmask.
- IKEv1 magic shorthands: 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.
- 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.
- History: support for specifying multiple selectors, the protocol, and the port was added in Libreswan 5.0. 🫶
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, the entire option value needs to be in double quotes. 🌈
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. 💜
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 IPv4 and one IPv6 pool may be specified. The leftaddresspool= option cannot be combined 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 for combined IPv4 and IPv6 address pools was added in Libreswan 5.0; support for IPv6 addresspool subnets was added in Libreswan 5.4.
- Limitations: Libreswan 5.4 does not support an address pool (addresspool=) combined with additional fixed selectors (subnet=); patches would be welcome. 💖
leftprotoport=protocol[/port], rightprotoport=protocol[/port] — these set the allowed protocols and ports over the connection, aka Port Selectors 💅. The argument is in the form protocol, which can be a number or a name that gets looked up in /etc/protocols (like leftprotoport=icmp), or in the form protocol/port (like tcp/smtp). Ports can be a number (eg. 25) or a name (eg smtp) that gets 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.

🧚 Use with leftsubnet=. With IKEv2, the leftsubnet= specification can include the protocol and port. Combining that syntax with protoport= is not supported.

leftnexthop={hostname|address}, rightnexthop={hostname|address} — the next-hop gateway IP address for the left participant's connection to the public network; it defaults to %direct (meaning right). If the value is to be overridden by the left=%defaultroute method (see above), an explicit value must not be given. If that method is not being used, but leftnexthop is %defaultroute, the next-hop gateway address of the default-route interface will be used. The magic value %direct signifies a value to be filled in (by automatic keying) with the peer's address. Relevant only locally, other end need not agree on it.
leftsourceip=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.
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:

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.

leftupdown-config={async|exec}, rightupdown-config={async|exec} — modify how the updown command is run.
- exec — invoke the updown command directly using execvpe(3). By default, the updown command is invoked using /bin/sh -c (see sh(1)).
- 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).

⚠️ Caution. This option is experimental.

History: updown-config= was added in Libreswan 5.4.

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.

leftfirewall=, rightirewall= — this option is obsolete and should not used anymore 🙈.

If one or both security gateways are doing forwarding firewalling (possibly including masquerading), and this is specified using the firewall parameters, tunnels established with IPsec are exempted from it so that packets can flow unchanged through the tunnels. (This means that all subnets connected in this manner must have distinct, non-overlapping subnet address blocks.) This is done by the default updown script (see ipsec-pluto(8)).

The implementation of this makes certain assumptions about firewall setup, and the availability of the Linux Advanced Routing tools. In situations calling for more control, it may be preferable for the user to supply their own updown script, which makes the appropriate adjustments for their system.

⚡ CONN PARAMETERS: AUTOMATIC KEYING ⚡

The following parameters are relevant to automatic keying via IKE. Unless otherwise noted, for a connection to work, in general it is necessary for the two ends to agree exactly on the values of these parameters 👑.

auto= — what operation, if any, should be done automatically at IPsec startup; currently-accepted values are:
- auto=add — equivalent to:

ipsec add connection

auto=ondemand — equivalent to:

ipsec add connection
ipsec route connection

(auto=route is an alias)

auto=up, auto=start — equivalent to:

ipsec add connection
ipsec up connection

auto=ignore — signifying no automatic operation when Libreswan is starting (also the default).
auto=keep — signifying an add plus an attempt to keep the connection up once the remote peer brought it up.

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.

authby= — how the two security gateways should authenticate each other. A comma separated list of one or more of the following:
- ecdsa, ecdsa-sha2 — ECDSA digital signature based authentication with any of the hash algorithms SHA2_256, SHA2_384, or SHA2_512.
- 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.
- eddsa — EDDSA digital signature based authentication on curve 25519.
- 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.
- rsa-sha1 — RSA-PKCSv1.5 digital signature based authentication with SHA1.
- rsa-sha2 — RSASSA-PSS digital signature based authentication with any of the hash algorithms SHA2_256, SHA2_384, or SHA2_512.
- 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.
- secret — Shared secrets (PSK) authentication; cannot be combined with other authentication methods.
- never — Negotiation is never to be attempted or accepted; cannot be combined with other authentication methods.
null — NULL-authentication. Cannot be combined with other authentication methods. Periodt.

For IKEv1, SHA2-based signatures are literally not defined and ECDSA isn't implemented, so the default authby value is rsa-sha1 🎀. Using authby=rsasig also gets you only rsa-sha1. No upgrades, bestie.

For IKEv2 you get 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 only be used if RFC 7427 isn't supported by the peer. Rude of them tbh.

Heads up: 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 — so like, watch this space. 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. One vibe, one signature system, iykyk 💖.

Digital signatures are superior in every way to shared secrets — no cap 🔥. 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 🙈.

✨ `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 the IKE_SA_INIT response and IKE_AUTH request, allowing the peer to pick a compatible method before sending its AUTH payload. It's giving considerate queen energy 👑.

The default is no.

Caution ⚠️ This option is experimental and implements the SUPPORTED_AUTH_METHODS notification defined in RFC 9593.

✨ `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:

ike=aes
ike=aes_ctr
ike=aes_gcm256;sha2_256
ike=aes128-sha1;modp2048
ike=aes256-sha2;dh19
ike=aes128-sha1;dh22
ike=3des-md5;modp1024,aes-sha1;modp1536

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)). Slay, logs.

✨ `sha2-truncbug={yes|no}` ✨

Enable the use of the draft 96-bit truncated hash (instead of the 128-bit truncated hash 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?). Ancient behaviour, honestly.

Another workaround is to switch from sha2_256 to sha2_512 🦋.

The default is no.

✨ `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. Not me defending Windows — I'm not.

The accepted values are no, (the default) or yes.

✨ `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. Main character protection, fr.

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. Obsessed with knowing both.

The default is no.

✨ `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. Boundaries, bestie 💅.

✨ `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 use of 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.

✨ `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.

✨ `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. Can't vibe-check a problem you can't see, smh.

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.

✨ `share-lease={yes|no}` ✨

Whether multiple outgoing 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. Sharing is caring, apparently.

✨ `esp=esp-proposal,...` ✨

A list of proposals specifying the cryptographic algorithms to negotiate when establishing an ESP Child SA (Phase 2 IPsec SA) 🌸. (The original line kicks off here mid-thought with DH). — that's the leftover fragment, not a typo of mine, bestie 😭.) For instance:

esp=aes_gcm;aes128+aes256-sha2_512+sha2_256
esp=aes128-sha2_512;dh19

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)). Iconic logging behaviour, honestly.

✨ `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:

ah=sha2_256,sha2_512
ah=sha2_256+sha2_512-dh14+dh19

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

Note 💜 AH is not recommended. A deployment using tunnel mode can be protected using ESP with esp=null (null encryption). Consider this your gentle intervention.

✨ `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. Pick one route, bestie — you don't need both 🎀.

Historic note, bestie: 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. Also 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. iykyk 💅

Another 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. the more u know ✨

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.

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

fragmentation={yes|no} — whether or not to allow IKE fragmentation. In addition IKEv1 allows force. <butterfly>ok flexible king</butterfly>

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.

ikepad={yes|no} — work around IKEv1 padding issues when inter-operating with other IKE daemons. the diplomacy option 🫶

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

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. wifi-to-cellular glow-up, no reconnect era ✨

The default is no.

heads up: VTI and MOBIKE might not work well when used together.

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.

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. 10Gbps girlies stay winning 🔥

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.

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.

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.

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.

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.

ok real talk, 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. fr fr just be specific bestie 💅

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. letting the hardware do the cardio 🏃‍♀️

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 not to 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. like why offload a flip phone khi

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. the @ is literally "don't talk to me, I said what I said" 💅

Okay so for opaque identifiers — usually of type ID_KEY_ID, literally the thing Cisco uses to specify Group Name — you wrap it in square brackets, like rightid=@[GroupName]. 🫶

The magic value %fromcert makes the ID get set to a DN taken from a certificate that's loaded. And a lil history moment for you: prior to 2.5.16, that was the default if a certificate was specified. 👑

The magic value %none sets the ID to no ID. It's in here for completeness, 'cause the ID might have been set back in the default conn and you just want it to default instead of being explicitly set, yk?

When you're using certificate-based IDs, you need to specify the full RDN — and you can optionally use wildcard matching (like CN='*'). If the RDN contains a comma, mask it with a backslash, e.g. OU='Foo\, Bar and associates'. ✨

leftpubkey=, rightpubkey= — the left participant's public key for signature (either RSA, ECDSA or EdDSA) authentication. leftpubkey is the generic option, bestie. The key should be in base-64 encoded RFC 2537 format (with 0s prepended), or one of these:
- %none — same as not specifying a value at all (useful for overriding a default)
- %dnsondemand — (the default) the key gets fetched from DNS at the time it's needed
- %dns — treated as %dnsondemand. The identity used for the left participant has to be a specific host — not %any or another magic value
- %cert — the info required comes from a certificate defined in %leftcert, and it automatically defines leftid for you

Additionally, you can provide a DER-encoded public key, or a raw public key generated using the ipsec {rsasig,ecdsa,eddsa}key command.

Caution ⚠️ if two connection descriptions specify different public keys for the same leftid, confusion and madness will ensue. Like, actual chaos. Do not.

leftrsasigkey=, rightrsasigkey= — the left/right participant's public key for RSA signature authentication. The argument can be any of the generic arguments listed in the leftpubkey/rightpubkey option. The generic DNS-related arguments can use the mechanism described in either RFC 3110 (previously RFC 2537) or RFC 4025.

Additionally, you can provide a raw public key generated using the ipsec rsasigkey command.

Caution ⚠️ if two connection descriptions specify different public keys for the same leftid, confusion and madness will ensue. 💀

leftecdsakey=, rightecdsakey= — the left/right participant's public key for ECDSA signature authentication. The argument can be any of the generic arguments listed in the leftpubkey/rightpubkey option. The generic DNS-related arguments can use the mechanism described in RFC 8005.

Additionally, you can provide a raw public key generated using the ipsec ecdsakey command.

Caution ⚠️ if two connection descriptions specify different public keys for the same leftid, confusion and madness will ensue. Same rule, different algorithm, same drama.

lefteddsakey=, righteddsakey= — the left/right participant's public key for EdDSA signature authentication. The argument can be any of the generic arguments listed in the leftpubkey/rightpubkey option. The generic DNS-related arguments can use the mechanism described in RFC 9373.

Additionally, you can provide a raw public key generated using the ipsec eddsakey command.

Caution ⚠️ if two connection descriptions specify different public keys for the same leftid, confusion and madness will ensue. Every single time. 🙈

leftcert=, rightcert= — if you're 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. It can live on a software or hardware security device, so like, your choice bestie. 🎀
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. 🔑

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
- null — for null-authentication

There is no default value — if it's unset, the symmetrical authby= keyword is used to determine the authentication policy of the connection.

Asymmetric authentication is only supported with IKEv2, sorry IKEv1 girlies. 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. No halfsies. 🚫

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"). Yes, the "by" is doing so much heavy lifting. Mind it. 💅

leftautheap={none|tls}, rightautheap={none|tls} — whether the security gateways will authenticate using 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. 🦋

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 it means 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 you're using a single CA, it can be safely omitted for both left and right — no stress. 🌸

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=. 👀
leftsendcert=, rightsendcert= — this option configures when Libreswan will send X.509 certificates to the remote host. Acceptable values are:
- yes, always — always send a certificate
- sendifasked — send a certificate when the peer asks for it (for instance by sending a CERTREQ payload)
- no, never — never send a certificate

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're 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. Glow-up arc fr. ✨

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.

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

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.

leftmodecfgserver={yes|no}, rightmodecfgserver={yes|no} — the end is a Mode Config server. It can push network configuration to the client. Iconic behavior honestly. 👑

The default is no.

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.

xauthby={file|pam|alwaysok} — so when IKEv1 XAUTH support is available, this picks the method XAUTH uses to authenticate the user with IKEv1. Currently supported values are file, pam, and alwaysok.

The default is file.

The password file lives at /etc/ipsec.d/passwd, and its syntax is similar to an Apache htpasswd file, except there's an extra connection name argument (plus an optional static IP address) hanging out in there too:

username:password:conname:ipaddress

For the supported password hashing methods, go peek at crypt(3). Heads up: if pluto is running in FIPS mode, some hash methods — MD5, for example — might not be available. Threads are used to launch an xauth authentication helper for the file method as well as the pam method.

alwaysok should only be used if the XAUTH user authentication isn't really being used but is required for interoperability, because it literally defeats the whole entire point of XAUTH, which is to rely on a secret only a human knows. Also see pam-authorize=yes.

xauthfail={hard|soft} — when XAUTH support is available, this sets the failure method you want when authentication fails. A soft failure means the IPsec SA is allowed to be established, as if authentication had passed successfully 😬 — but the XAUTH_FAILED environment variable gets set to 1 for the updown script, which you can then use to redirect the user into a walled garden, like a payment portal, for example.

The default is hard.

pam-authorize={yes|no} — IKEv2 does not support receiving a plaintext username and password (nope, not a thing). The pam-authorize=yes option performs an authorization call via PAM, but it only includes the remote ID — not the username, not the password. This lets backends disallow an ID based on non-password situations, like "user disabled" or "user over quota" ✨

Also see the IKEv1 option xauthby=pam.

modecfgpull={yes|no} — pulls the Mode Config network information from the server. Both server and client must use the same setting, bestie, like matching outfits.

The default is no.

remote-peer-type= — sets 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 — and yes, that includes automatically updating (and restoring) /etc/resolv.conf. These options require that XAUTH is also enabled on this connection.

History lesson 🎀: the parameter was originally called remote_peer_type=; it got renamed to remote-peer-type= in Libreswan 3.9.

nm-configured={yes|no} — marks 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.

encapsulation={yes|no|auto} — okay so in some cases, like when ESP packets are filtered or when a broken IPsec peer doesn't 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. rip 🫡

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 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. And if you do use fallback mode, it's recommended to reduce the retransmit-timeout from the default 60s to a much shorter value such as 10s, so you don't have to sit there for a whole minute waiting 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.

tcp-remoteport= — which remote TCP port to use when IKE over TCP is attempted. The default value is to use the NAT-T IKE port (4500). This value is not negotiated and should be configured properly on all endpoints. When opening a TCP socket to the remote host in this port, a regular ephemeral source port is obtained from the OS. For changing the UDP ports, see leftikeport.
nat-keepalive={yes|no} — whether to send any NAT-T keep-alives. These one byte packets prevent the NAT router from closing its port when there isn't enough traffic on the IPsec connection.

The default is yes.

initial-contact={yes|no} — whether to send an INITIAL_CONTACT payload to the peer we're initiating to, if we currently have no IPsec SAs up with that peer. It's 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.

cisco-unity={yes|no} — whether to send a CISCO_UNITY payload to the peer.

The default is no.

It's 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.

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. periodt 💅

The default is no.

History: cisco-split was added in Libreswan 5.3.

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 actually changes 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.

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, signifies 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.

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.
redirect-to={hostname|address},... — where to send remote peers to via the send-redirect option. This can be an IP address or hostname (FQDN).
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 the 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.

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.

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. so like… trade-off, bestie 🧚

The prefix OE stands for **"Opportunistic Encryption"</strong> 💫 ngl this prefix has lore — it 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. ok history lesson over bestie 📚

overlapip={yes|no} — a boolean (yes/no, the classic) that decides, when (left|right)subnet=vhost: is being used, whether the virtual IP claimed by the states created from this connection can overlap with states created from other connections. 🫂

Quick note: connection instances created by the Opportunistic Encryption or PKIX (x.509) instantiation system are distinct internally, and they will inherit this policy bit. so like, they're separate but they still get the vibe handed down 💅

The default is no.

Heads up 🚨 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. so, yeah, klips or nothing.

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. fr fr, don't do this to yourself 😭

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 it 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. 🔗

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 way these two are a package deal 🎀

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). the name change saga, we've all been there 🌀

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. PFS ate, lowkey iconic.
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. 🚩 bestie that's a red flag the size of a billboard

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 — which 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 ✨ growth mindset

History: the parameter was originally called aggrmode=; it was renamed to aggressive= in Libreswan 3.23.

The default is aggressive=no.

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=. no need to be in sync, it's giving independent queens ✨

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

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 original initiator's soft limit to 25% of ipsec-max-bytes (with 12% fuzz) and 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 🎯 clever tbh

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.

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 — so Ki, Mi, Gi, Ti, Pi, Ei, not the byte-flavoured ones. iykyk 👑

When using Linux with nic-offload=packet set, Linux 6.7 or later is required.

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. confusing? yes. iconic? also yes 💅

Technically, at least the Linux kernel can install IPsec SA's with an IPsec SA Sequence Number, but this is currently not supported by libreswan.

rekey={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. 😬 cooperation is key bestie

The default is yes.

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

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. sprinkle a lil chaos on the timing, it's good for you ✨

The default is 100%.

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. glow-up 💖

retransmit-timeout=seconds[us|ms|s|m|h|d|w] — okay bestie, this is the patience timer for one single packet, including all its retransmits, before the whole IKE attempt gets aborted. If rekeying is enabled, a fresh IKE attempt starts. The default set by ipsec-pluto(8) is currently 60s ✨

See also: retransmit-interval and rekey.

retransmit-interval=milliseconds[us|ms|s|m|h|d|w] — this is the initial interval, specified in msecs, that pluto waits before retransmitting an IKE packet. It gets doubled for each attempt — exponential back-off, slay 💅 The default set by ipsec-pluto(8) is currently 500.

See also: retransmit-timeout and rekey.

compress={yes|no} — whether IPComp compression of content is proposed on the connection. Important vibe check: 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 a connection without compression.

When set to yes, compression is negotiated for the DEFLATE compression algorithm.

metric=number — sets 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.

mtu= — sets 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 to become too big for a router on the path. Since IPsec cannot trust any unauthenticated ICMP messages, PATH MTU discovery does not work 😭 This can also be needed when using "6to4" IPV6 deployments, which adds another header on the packet size.

Acceptable values are positive numbers. There is no default.

tfc= — enables 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, because 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.

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 this end does not support Traffic Flow Confidentiality ("TFC") (RFC-4303). Possible values are no (do not send notification), which allows the peer to use TFC, and yes (send notification), which prevents the 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 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. 💀

nflog-group= — if set, this is 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.

mark= — if set, this is the MARK to set for the IPsec SA of this connection. The format of a CONNMARK is mark/mask. If the mask is left out, a default mask of 0xffffffff is used. A mark value of -1 means to assign a new global unique mark number for each instance of the connection. Global marks start at 1001 🌈 This option is only available on linux XFRM kernels. It can be used with iptables to create custom iptables rules using CONNMARK. It can also be used with Virtual Tunnel Interfaces ("VTI") to direct marked traffic to specific vtiXX devices.
mark-in= — the same as mark, but mark-in only applies to the inbound half of the IPsec SA. It overrides any mark= setting.
mark-out= — the same as mark, but mark-out only applies to the outbound half of the IPsec SA. It overrides any mark= setting.
vti-interface= — > 🚨 deprecated, bestie. 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.

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.

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.

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:

no — do not use "Routing based IPsec VPN".
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.
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.

The default is no.

Kernel Support:

Linux (since 4.19) — okay so 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.
NetBSD (since 8.0) 🦋
OpenBSD (since 7.4) 🦋
FreeBSD (since 11.0) — supported since Libreswan 5.2.
leftinterface-ip=address[/prefix] and rightinterface-ip=address[/prefix] — these set 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.

priority= — the priority in the kernel SPD/SAD database, when matching up packets. Each kernel (XFRM, OSX, etc) has its own mechanism for setting the priority. Setting this option to non-zero passes the priority to the kernel stack unmodified. The maximum value depends on the stack. It is recommended not to exceed 65536.

XFRM use a priority system based on "most specific match first". It uses an internal algorithm to calculate these based on network prefix length, protocol and port selectors. A lower value means a higher priority.

Typical values are about the 2000 range. These can be seen on the XFRM stack using ip xfrm policy when the connection is up. For "anonymous IPsec" or Opportunistic Encryption based connections, a much lower priority (65535) is used to ensure administrator configured IPsec always takes precedence over opportunistic IPsec.

sendca={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.

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.

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.

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.

debug=option — a comma separated list of options that enable internal debug logs of the connection. For more information see the global plutodebug= option.

Note — this feature is used by Libreswan developers. The default logs should provide sufficient information to diagnose configuration and connection problems.

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.

🌸 CONN PARAMETERS: DNS 🌸

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.

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.
modecfgdomains= — the modecfgdomains= option takes a comma or space separated list of internal domain names that are reachable via the supplied modecfgdns DNS servers.
modecfgbanner= — banner to display when peer connects using IKEv1.

🦋 OPPORTUNISTIC CONNS 🦋

For Opportunistic connections, the system requires creating special named conns that are used to implement the default policy groups. Currently, these names cannot be changed.

conn clear
      type=passthrough
      authby=never
      left=%defaultroute
      right=%group
      auto=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

🎀 POLICY GROUP FILES 🎀

The optional files under /etc/ipsec.d/policies, including

/etc/ipsec.d/policies/clear
/etc/ipsec.d/policies/clear-or-private
/etc/ipsec.d/policies/private-or-clear
/etc/ipsec.d/policies/private
/etc/ipsec.d/policies/block

may contain policy group configuration information to supplement ipsec.conf. Their contents are not security-sensitive.

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.

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.

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.

💜 DEFAULT POLICY GROUPS 💜

The standard Libreswan install includes several policy groups which provide a way of classifying possible peers into IPsec security classes: private (talk encrypted only), private-or-clear (prefer encryption), clear-or-private (respond to requests for encryption), clear and block.

💀 CHOOSING A CONNECTION [THIS SECTION IS EXTREMELY OUT OF DATE 💀

When choosing a connection to apply to an outbound packet caught with a %trap, the system prefers the one with the most specific eroute that includes the packet's source and destination IP addresses. Source subnets are examined before destination subnets. For initiating, only routed connections are considered. For responding, unrouted but added connections are considered.

When choosing a connection to use to respond to a negotiation that doesn't match an ordinary conn, an opportunistic connection may be instantiated. Eventually, its instance will be /32 -> /32, but for earlier stages of the negotiation, there will not be enough information about the client subnets to complete the instantiation.

🌈 FILES 🌈

/etc/ipsec.conf
/etc/ipsec.d/
/etc/ipsec.d/policies/clear
/etc/ipsec.d/policies/clear-or-private
/etc/ipsec.d/policies/private-or-clear
/etc/ipsec.d/policies/private
/etc/ipsec.d/policies/block

⭐ SEE ALSO ⭐

ipsec(8), ipsec-rsasigkey(8)

🌸 HISTORY 🌸

Designed for the FreeS/WAN project (https://www.freeswan.org) by Henry Spencer.

👑 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

Catch u later, bestie — this whole manual-page moment is from Libreswan 5.4.1, dated 10/23/2026, and yes it's IPSEC.CONF(5) 💖✨ periodt.

📦 where this page comes from

fedora 43: libreswan 5.4.1-1.fc43 · GPL-2.0-or-later AND MPL-2.0
fedora 44: libreswan 5.4.1-1.fc44 · GPL-2.0-or-later AND MPL-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms

IPSEC.CONF(5)

💖 IPSEC.CONF(5) 💖

✨ NAME ✨

🌸 DESCRIPTION 🌸

💅 Overview

🦋 Values

🍓 Byte Counts And Binary Data

⏱️ Duration

🔥 Proposals

👑 Config Setup Section

Conn Section 🎀

CONN PARAMETERS: GENERAL 🌈

⚡ CONN PARAMETERS: AUTOMATIC KEYING ⚡

✨ send-supported-auth-methods={yes|no} ✨

✨ ike=ike-proposal,... ✨

✨ sha2-truncbug={yes|no} ✨

✨ ms-dh-downgrade={yes|no} ✨

✨ dns-match-id={yes|no} ✨

✨ require-id-on-certificate={yes|no} ✨

✨ ppk={no|propose|yes|insist|never} ✨

✨ ppk-ids= ✨

✨ nat-ikev1-method={drafts|rfc|both|none} ✨

✨ share-lease={yes|no} ✨

✨ esp=esp-proposal,... ✨

✨ ah=ah-proposal,... ✨

✨ phase2={esp|ah} ✨

🌸 CONN PARAMETERS: DNS 🌸

🦋 OPPORTUNISTIC CONNS 🦋

🎀 POLICY GROUP FILES 🎀

💜 DEFAULT POLICY GROUPS 💜

💀 CHOOSING A CONNECTION [THIS SECTION IS EXTREMELY OUT OF DATE 💀

🌈 FILES 🌈

⭐ SEE ALSO ⭐

🌸 HISTORY 🌸

👑 AUTHOR 👑

✨ `send-supported-auth-methods={yes|no}` ✨

✨ `ike=ike-proposal,...` ✨

✨ `sha2-truncbug={yes|no}` ✨

✨ `ms-dh-downgrade={yes|no}` ✨

✨ `dns-match-id={yes|no}` ✨

✨ `require-id-on-certificate={yes|no}` ✨

✨ `ppk={no|propose|yes|insist|never}` ✨

✨ `ppk-ids=` ✨

✨ `nat-ikev1-method={drafts|rfc|both|none}` ✨

✨ `share-lease={yes|no}` ✨

✨ `esp=esp-proposal,...` ✨

✨ `ah=ah-proposal,...` ✨

✨ `phase2={esp|ah}` ✨