IPSEC_PLUTO(8)

📦
version 4.15 · 4 versions
, in centos-stream 9

💖 IPSEC_PLUTO(8) — ipsec_pluto, ipsec_whack, pluto 💖

okay bestie, this is the manual page for ipsec_pluto, ipsec_whack, and pluto, and it lives in the Executable programs section. we're doing the whole thing, no skips, no cap. 💅

🌸 NAME 🌸

ipsec_pluto, ipsec_whack, pluto - ipsec whack : IPsec IKE keying daemon and control interface. periodt. 🎀

✨ SYNOPSIS ✨

okay so here's the entire summoning circle, bestie. every bracket, every flag, every | — all of it. do not lose your place. 🌀

ipsec pluto [--help] [--version] [--leak-detective] [--efence-protect]
      [--config filename] [--vendorid VID] [--nofork] [--stderrlog]
      [--logfile filename] [--log-no-time] [--log-no-append]
      [--log-no-ip] [--log-no-audit] [--use-netkey] [--use-bsdkame]
      [--uniqueids] [--virtual-private network_list]
      [--keep-alive delay_sec] [--force-busy] [--crl-strict]
      [--crlcheckinterval] [--interface interfacename] [--listen ipaddr]
      [--ikeport portnumber] [--natikeport portnumber] [--rundir path]
      [--secretsfile secrets-file] [--nhelpers number]
      [--seedbits numbits] [--ipsecdir dirname] [--nssdir dirname]
      [--coredir dirname] [--statsbin filename]
      [--secctx-attr-type number]

ipsec whack [--help] [--version]

ipsec whack --name connection-name [[--ipv4] | [--ipv6]] [[--tunnelipv4]
      | [--tunnelipv6]]
      [--id identity] [--host ip-address] [--cert friendly_name]
      [--ckaid CKAID] [--ca distinguished name]
      [--groups access control groups]
      [--sendcert yes | forced | always | ifasked | no | never]
      [--sendca none | issuer | all] [--certtype number]
      [--ikeport portnumber] [--nexthop ip-address] [[--client subnet]]
      [--clientprotoport protocol/port] [--srcip ip-address]
      [--xauthserver] [--xauthclient] [--modecfgserver]
      [--modecfgclient] [--modecfgdns ip-address, ip-address, ...]
      [--modecfgdomains DNS-domain, DNS-domain, ...]
      [--modecfgbanner login-banner] [--dnskeyondemand]
      [--updown updown]
      --to
      [--id identity] [--host ip-address] [--cert friendly_name]
      [--ckaid CKAID] [--ca distinguished name]
      [--groups access control groups]
      [--sendcert yes | always | ifasked | no | never]
      [--certtype number] [--ikeport port-number] [--nexthop ip-address]
      [--client subnet] [--clientprotoport protocol/port]
      [--srcip ip-address] [--xauthserver] [--xauthclient]
      [--modecfgserver] [--modecfgclient]
      [--modecfgdns ip-address, ip-address, ...]
      [--modecfgdomains DNS-domain, DNS-domain, ...] [--dnskeyondemand]
      [--updown updown]

      [--tunnel] [--psk] [--rsasig] [--encrypt] [--authenticate]
      [--compress] [--pfs]
      [--pfsgroup [modp1024] | [modp1536] | [modp2048] | [modp3072] | [modp4096] | [modp6144] | [modp8192] | [dh22] | [dh23] | [dh24]]
      [--ikelifetime seconds] [--ipseclifetime seconds]
      [--rekeymargin seconds] [--rekeyfuzz percentage]
      [--keyingtries count] [--esp esp-algos] [--dontrekey] [--aggrmode]
      [--modecfgpull] [--metric metric] [--nflog-group nflognum]
      [--conn-mark mark/mask] [[--dpddelay seconds] |
      [--dpdtimeout seconds]] [--dpdaction [clear] | [hold] | [restart]]
      [--forceencaps] [--no-keep-alive]
      [[--initiateontraffic] | [--pass] | [--drop] | [--reject]]
      [[--failnone] | [--failpass] | [--faildrop] | [--failreject]]
      [--rundir path] [--ctlsocket path/file] [--label string]

ipsec whack --keyid id [--addkey] [--pubkeyrsa key] [--rundir path]
      [--ctlsocket path/file] [--label string]

ipsec whack --listen | --unlisten  [--rundir path]
      [--ctlsocket path/file] [--label string]

ipsec whack --ddos-auto | --ddos-busy | --ddos-unlimited
      [--rundir path] [--ctlsocket path/file]

ipsec whack --route | --unroute  --name connection-name [--rundir path]
      [--ctlsocket path/file] [--label string]

ipsec whack --initiate | [--remote-host ip-address] | --terminate |
      --rekey-ike | --rekey-ipsec  --name connection-name
      [--xauthuser user] [--xauthpass pass] [--asynchronous]
      [--rundir path] [--ctlsocket path/file] [--label string]

ipsec whack --global-redirect yes|no|auto

ipsec whack --global-redirect-to ip-address(es)

ipsec whack [--name connection-name] --redirect-to ip-address(es)

ipsec whack [[--tunnelipv4] | [--tunnelipv6]] --oppohere ip-address
      --oppothere ip-address --opposport port --oppodport port
      --oppoproto protocol

ipsec whack --crash [ipaddress]

ipsec whack --name connection-name --delete [--ctlbase path]
      [--label string]

ipsec whack --deletestate state-number [--rundir path]
      [--ctlsocket path/file] [--label string]

ipsec whack --deleteuser --name username [--rundir path]
      [--ctlsocket path/file] [--label string]

ipsec whack [--name connection-name]
      {--debug help | none | base | cpu-usage | class} |
      {--no-debug class} | {--impair help | none | behaviour} |
      {--no-impair behaviour}

ipsec whack [--utc] [--listall] [--listpubkeys] [--listcerts]
      [--listcacerts] [--listcrls]

ipsec whack [--utc] [--rereadsecrets] [--fetchcrls] [--rereadall]

ipsec whack --ddns

ipsec whack --listevents

ipsec whack --purgeocsp

ipsec whack --status --trafficstatus --shuntstatus --addresspoolstatus
      --processstatus [--rundir path] [--ctlsocket path/file]
      [--label string]

ipsec whack --globalstats --clearstats [--rundir path]
      [--ctlsocket path/file] [--label string]

ipsec whack [--ike-socket-bufsize bufsize]
      [--ike-socket-errqueue-toggle] [--rundir path]
      [--ctlsocket path/file] [--label string]

ipsec whack --shutdown [--rundir path] [--ctlsocket path/file]
      [--label string] [--leave-state]

that's the whole synopsis vibe. now we get into the lore. 📖

💅 DESCRIPTION 💅

pluto is an IKE ("IPsec Key Exchange") daemon. whack is an auxiliary program that lets requests be made to a running pluto. like, whack is the bestie who knocks on the door and asks nicely. 🫶

pluto is used to automatically build shared "security associations" on a system that has IPsec, the secure IP protocol. in other words, pluto can eliminate much of the work of manual keying. the actual secure transmission of packets is the responsibility of other parts of the system - the kernel. pluto can talk to various kernel implementations, such as the Linux XFRM and BSD KAME IPsec stacks. ipsec_auto(8) provides a more convenient interface to pluto and whack. ✨

🦋 IKE's Job 🦋

A Security Association (SA) is an agreement between two network nodes on how to process certain traffic between them. this processing involves encapsulation, authentication, encryption, or compression. literally the whole glow-up of packet handling. 💫

IKE can be deployed on a network node to negotiate Security Associations for that node. these IKE implementations can only negotiate with other IKE implementations, so IKE must be on each node that is to be an endpoint of an IKE-negotiated Security Association. no other nodes need to be running IKE. lowkey efficient. 🦋

An IKE instance (i.e. an IKE implementation on a particular network node) communicates with another IKE instance using UDP IP packets, so there must be a route between the nodes in each direction. both ways, bestie. no one-way streets. 🛣️

The negotiation of Security Associations requires a number of choices that involve tradeoffs between security, convenience, trust, and efficiency. these are policy issues and are normally specified to the IKE instance by the system administrator. so your sysadmin is the main character here, fr fr. 👑

IKE deals with two kinds of Security Associations. the first part of a negotiation between IKE instances is to build an ISAKMP SA. an ISAKMP SA is used to protect communication between the two IKEs. IPsec SAs can then be built by the IKEs - these are used to carry protected IP traffic between the systems. two-step slay. 💅

The negotiation of the ISAKMP SA is known as Phase 1. in theory, Phase 1 can be accomplished by a couple of different exchange types. currently, Main Mode and Aggressive Mode are implemented. both iconic in their own way. ⭐

Any negotiation under the protection of an ISAKMP SA, including the negotiation of IPsec SAs, is part of Phase 2. the exchange type that we use to negotiate an IPsec SA is called Quick Mode. quick mode said "i'm fast and i'm protected." 🚀

IKE instances must be able to authenticate each other as part of their negotiation of an ISAKMP SA. this can be done by several mechanisms described in the draft standards. no sketchy strangers allowed. 🙈

IKE negotiation can be initiated by any instance with any other. if both can find an agreeable set of characteristics for a Security Association, and both recognize each others authenticity, they can set up a Security Association. the standards do not specify what causes an IKE instance to initiate a negotiation. it's giving mysterious. 🌫️

In summary, an IKE instance is prepared to automate the management of Security Associations in an IPsec environment, but a number of issues are considered policy and are left in the system administrator's hands. so like, automation with a side of admin judgment. 🫶

🌈 Pluto 🌈

pluto is an implementation of IKE. it runs as a daemon on a network node. currently, this network node must be a Linux system running the XFRM IPsec stack, or a FreeBSD/NetBSD/Mac OSX system running the KAME IPsec stack. platform check: slay or slay. 🐧🦋

pluto implements a large subset of IKEv1 and IKEv2. not all of it, but a large subset. still ate. 💅

The policy for acceptable characteristics for Security Associations is mostly hardwired into the code of pluto (spdb.c). eventually this will be moved into a security policy database with reasonable expressive power and more convenience. future glow-up pending. ✨

pluto uses shared secrets or RSA signatures to authenticate peers with whom it is negotiating. these RSA signatures can come from DNS(SEC), a configuration file, or from X.509 and CA certificates. several sources, one vibe. 🔐

pluto initiates negotiation of a Security Association when it is manually prodded: the program whack is run to trigger this. it will also initiate a negotiation when IPsec traps an outbound packet for Opportunistic Encryption. so either you poke it or the packet pokes it. 🫵

pluto implements ISAKMP SAs itself. after it has negotiated the characteristics of an IPsec SA, it directs the kernel to implement it. if necessary, it also invokes a script to adjust any firewall and issue route(8) commands to direct IP packets. kernel does the actual carrying; pluto does the matchmaking. 💌

When pluto shuts down, it closes all Security Associations. clean exit, no leftover drama. 🧹

🎀 Before Running Pluto 🎀

pluto runs as a daemon with userid root. before running it, a few things must be set up. yes, root. yes, setup first. 👑

pluto requires a working IPsec stack. non-negotiable. 🛠️

pluto supports multiple public networks (that is, networks that are considered insecure and thus need to have their traffic encrypted or authenticated). it discovers the public interfaces to use by looking at all interfaces that are configured (the --interface option can be used to limit the interfaces considered). it does this only when whack tells it to --listen, so the interfaces must be configured by then. the --listen can be used to limit listening on only 1 IP address of a certain interface. ifconfig(8) or ip(8) with the -a flag will show the name and status of each network interface. so like, check your interfaces before you come crying. 🕵️‍♀️

pluto requires a database of preshared secrets and RSA private keys. this is described in the ipsec.secrets(5). pluto is told of RSA public keys via whack commands. if the connection is Opportunistic, and no RSA public key is known, pluto will attempt to fetch RSA keys using the Domain Name System. secrets secured, keys fetched when needed. 🗝️

🦋 Setting up XFRM for pluto

Okay so real talk — there are literally no special requirements for using XFRM. It ships with all modern versions of Linux 2.4 and later. That's it. That's the whole vibe. No cap. ✨

💖 ipsec.secrets file

So here's the thing bestie: a pluto daemon and another IKE daemon (like, say, another instance of pluto) have to convince each other that they are who they are supposed to be before any negotiation can succeed. Mutual vibe check, basically. 🫶

This authentication gets done by using either:

  • secrets that have been shared beforehand (manually), or
  • RSA signatures.

There are other techniques out there, but ngl they have not been implemented in pluto. Periodt.

The file /etc/ipsec.secrets is where preshared secret keys and XAUTH passwords live. Meanwhile RSA private keys, X.509 certificates, CRLs, OCSP and smartcards are all handled via NSS. For debugging, there's an argument to the pluto command to use a different file. This whole file is described in ipsec.secrets(5) — go read it, iykyk.

🔥 Running Pluto

To fire up the daemon, just type pluto (and be sure you're running as the superuser, obviously 👑).

The default IKE port number is 500, the UDP port assigned by IANA for IKE Daemons. pluto must be run by the superuser to be able to use the UDP 500 port. And if pluto is told to enable NAT-Traversal, then UDP port 4500 is also taken by pluto to listen on. Two ports, one daemon, main character energy. 💅

the whole IPstack situation

Pluto supports different IPstacks on different operating systems. Configure it with one of these:

  • --use-netkey — (Linux)
  • --use-bsdkame — (BSD)

On startup, pluto might also read the protostack= option to select the IPsec stack to use — but only if --config /etc/ipsec.conf is given as an argument to pluto. And if both --use-XXX and --config /etc/ipsec.conf are specified, the last command line argument specified takes precedence. Last one wins, always. 🏁

NAT-Traversal stuff 🌈

Pluto supports RFC 3947 NAT-Traversal. The allowed range behind the NAT routers is submitted using the --virtual-private option — see ipsec.conf(5) for the syntax.

  • --force-keepalive — forces the sending of the keep-alive packets. These get sent to prevent the NAT router from closing its port when there's not enough traffic on the IPsec connection.
  • --keep-alive — sets the delay (in seconds) of these keep-alive packets.

The newer NAT-T standards support port floating, and Libreswan enables this per default. Slay. ✨

certificates, bestie 🎀

Pluto supports the use of X.509 certificates and sends certificates when needed. Pluto uses NSS for all X.509 related data, including CAcerts, certs, CRLs and private keys. The Certificate Revocation Lists can also be retrieved from an URL.

  • --crlcheckinterval — sets the time between checking for CRL expiration and issuing new fetch commands.
  • The first attempt to update a CRL is started at 2*crlcheckinterval before the next update time.
  • Pluto logs a warning if no valid CRL was loaded or obtained for a connection.
  • --crl-strict — if given, the connection will be rejected until a valid CRL has been loaded. Like, straight-up no entry. 🚫

helper children 👑

Pluto can also use helper children to off-load cryptographic operations. Fine-tune this behavior using --nhelpers. Here's the math, stay with me:

  • Pluto will start (n-1) of them, where n is the number of CPU's you have (including hyperthreaded CPU's).
  • A value of 0 forces pluto to do all operations in the main process.
  • A value of -1 tells pluto to perform the above calculation.
  • Any other value forces the number to that amount.

the random seeding lore 🍓

Pluto uses the NSS crypto library as its random source. Some government Three Letter Agency requires that pluto reads 440 bits from /dev/random and feed this into the NSS RNG before drawing random from the NSS library — even though the NSS library itself already seeds its internal state. 💀

As this process can block pluto for an extended time, the default is to not perform this redundant seeding. The --seedbits option can be used to specify the number of bits that will be pulled from /dev/random and seeded into the NSS RNG. This can also be accomplished by specifying seedbits in the "config setup" section of ipsec.conf.

This option should not be used by most people. Like, genuinely. Leave it alone unless you know exactly why you're here. 🙈

lockfile time

pluto attempts to create a lockfile with the name /var/run/pluto/pluto.pid. If the lockfile cannot be created, pluto exits — this prevents multiple plutos from competing. Any "leftover" lockfile must be removed before pluto will run. pluto writes its PID into this file so that scripts can find it. 🫡

This lock will not function properly if it is on an NFS volume (but sharing locks on multiple machines doesn't make sense anyway).

forking & logging 🌸

pluto then forks and the parent exits. This is the conventional "daemon fork". It can make debugging awkward, so there's an option to suppress this fork. In certain configurations, pluto might also launch helper programs to assist with DNS queries or to offload cryptographic operations.

All logging, including diagnostics, is sent to syslog(3) with facility=authpriv; it decides where to put these messages (possibly in /var/log/secure or /var/log/auth.log). Since this too can make debugging awkward, the option --stderrlog is used to steer logging to stderr.

Alternatively, --logfile can be used to send all logging information to a specific file.

Once pluto is started, it waits for requests from whack. And that's the tea. ☕

💜 Pluto's Internal State

To understand how to use pluto, it's genuinely helpful to understand a little about its internal state. Plus, the terminology is needed to decipher some of the diagnostic messages. So let's get into it, bestie. 🧚

food groups & certs

Pluto supports food groups for Opportunistic IPsec. The policies for these are located in /etc/ipsec.d/policies, or another directory as specified by --ipsecdir.

Pluto supports X.509 Certificates. All certificate handling is done using the NSS library and all certificate material is stored in an NSS database in /var/lib/ipsec/nss or another directory as specified by --nssdir.

when things go wrong 😭

Pluto may core dump. It will normally do so into the current working directory. You can specify the --coredir option for pluto, or specify the dumpdir= option in ipsec.conf.

If you're investigating a potential memory leak in pluto, start pluto with the --leak-detective option. Before the leak causes the system or pluto to die, shut down pluto in the regular way. pluto will display a list of leaks it has detected. Detective work, iconic. 🔍

If you're investigating a potential use-after-free or double-free in pluto, first build pluto with USE_EFENCE=true and then start pluto with --efence-protect. See efence(2) and EF_PROTECT_BELOW and EF_PROTECT_FREE.

connections & state objects ⭐

The (potential) connection database describes attributes of a connection. These include the IP addresses of the hosts and client subnets and the security characteristics desired. pluto requires this information (simply called a connection) before it can respond to a request to build an SA. Each connection is given a name when it's created, and all references are made using this name.

During the IKE exchange to build an SA, the information about the negotiation is represented in a state object. Each state object reflects how far the negotiation has reached. Once the negotiation is complete and the SA established, the state object remains to represent the SA. When the SA is terminated, the state object is discarded. Each State object is given a serial number and this is used to refer to the state objects in logged messages.

Each state object corresponds to a connection and can be thought of as an instantiation of that connection. At any particular time, there may be any number of state objects corresponding to a particular connection. Often there's one representing an ISAKMP SA and another representing an IPsec SA. Two icons doing two different jobs. 💅

routing tea ☕

XFRM requires no special routing. Clean. Simple. Love that for us.

Each connection may be routed, and must be while it has an IPsec SA. The connection specifies the characteristics of the route:

  • the interface on this machine
  • the "gateway" (the nexthop)
  • the peer's client subnet

Two connections may not be simultaneously routed if they're for the same peer's client subnet but use different interfaces or gateways (pluto's logic does not reflect any advanced routing capabilities).

When pluto needs to install a route for a connection, it must make sure that no conflicting route is in use. If another connection has a conflicting route, that route will be taken down, as long as there is no IPsec SA instantiating that connection. If there is such an IPsec SA, the attempt to install a route will fail.

There is an exception. 👀 If pluto, as Responder, needs to install a route to a fixed client subnet for a connection, and there's already a conflicting route, then the SAs using the route are deleted to make room for the new SAs. The rationale is that the new connection is probably more current. The need for this usually is a product of Road Warrior connections (these are explained later; they cannot be used to initiate).

eroutes 🦋

When pluto needs to install an eroute for an IPsec SA (for a state object), first the state object's connection must be routed (if this cannot be done, the eroute and SA will not be installed). If a conflicting eroute is already in place for another connection, the eroute and SA will not be installed (but note that the routing exception mentioned above may have already deleted potentially conflicting SAs).

If another IPsec SA for the same connection already has an eroute, all its outgoing traffic is taken over by the new eroute. The incoming traffic will still be processed. This characteristic is exploited during rekeying. 🔁

🌟 Using whack

whack is used to command a running pluto. whack uses a UNIX domain socket to speak to pluto (by default, /var/pluto.ctl).

whack has an intricate argument syntax. This syntax allows many different functions to be specified. Let me break down the forms for you:

  • help — shows the usage or version information.
  • connection — gives pluto a description of a potential connection.
  • public key — informs pluto of the RSA public key for a potential peer.
  • delete — deletes a connection description and all SAs corresponding to it.
  • listen — tells pluto to start or stop listening on the public interfaces for IKE requests from peers.
  • route — tells pluto to set up routing for a connection.
  • unroute — undoes the route form. 🙃
  • initiate — tells pluto to negotiate an SA corresponding to a connection.
  • terminate — tells pluto to remove all SAs corresponding to a connection, including those being negotiated.
  • status — displays pluto's internal state.
  • debug — tells pluto to change the selection of debugging output "on the fly".
  • shutdown — tells pluto to shut down, deleting all SAs. Bye bestie 👋

The crash option asks pluto to consider a particularly target IP to have crashed, and to attempt to restart all connections with that IP address as a gateway. In general, you should use Dead Peer Detection to detect this kind of situation automatically, but this is not always possible. Sometimes you gotta tell it by hand. 🤷

Most options are specific to one of the forms, and will be described with that form. There are three options that apply to all forms —

  • --ctlsocket path/file — tells whack to use file as the UNIX domain socket for chatting with pluto 🫶. Use either this or --rundir, bestie — not both.
  • --rundir path — path is where you'll find the UNIX domain socket for talking to pluto, plus the pluto.pid file and the pluto.lock files 💅. Again: this or --ctlsocket, never both.
  • --label string — sticks string onto every single error message whack generates 🏷️ so you can tell your chaos apart from everyone else's.

🎀 the help form

The help form of whack is self-explanatory, iykyk ✨.

  • --help — shows the usage message. That's it, that's the whole vibe 💖
  • --version — shows the version of whack 👑

🦋 the connection form

So the connection form describes a potential connection to pluto. Pluto needs to know which connections can and should be negotiated 👀. When pluto is the initiator, it needs to know what to propose. When pluto is the responder, it needs to know enough to decide whether it's willing to set up what's being proposed.

The description of a potential connection can specify a large number of details. Every connection has a unique name 🌸 — and that name shows up in an updown shell command, so fr fr don't put punctuation in it that would make the command ill-formed. Not the moment for emoji in your conn name, bestie 😭

  • --name connection-name — sets the name of the connection. Main character identifier, lowkey essential 💫

The topology of a connection is symmetric, so to save space here's literally half a picture:

   client_subnet<-->host:ikeport<-->nexthop<---

A similar trick is used for the flags 🎀. The same flag names are used for both ends — the ones before the --to flag describe the left side, and the ones after it describe the right side. When pluto attempts to use the connection, it decides whether it's the left side or the right side based on the IP numbers of its interfaces. Iconic, honestly.

  • --id id — the identity of the end 👑. Currently this can be an IP address (dotted quad, or a Fully Qualified Domain Name which gets resolved immediately), or a Fully Qualified Domain Name itself (prefixed with @ to signify it should not be resolved), or user@FQDN, or an X.509 DN. Pluto only authenticates the identity — it does not use it for addressing, so for example an IP address need not be the one packets are actually sent to 🙈. If this option is absent, the identity defaults to the IP address given by --host.
  • --host ip-address, --host %any, --host %opportunistic — the IP address of the end (generally the public interface) 🌐. If pluto is acting as a responder for IKE negotiations initiated from unknown IP addresses (the "Road Warrior" case), specify the IP as %any — and note that the obsolete notation 0.0.0.0 is currently still accepted for this. If pluto is to opportunistically initiate the connection, use %opportunistic ⭐
  • --cert friendly_name — the friendly_name (aka the nickname) of the X.509 certificate that was used when importing the certificate into the NSS database 🎀. See ipsec.conf(5) for how to extract this from the PKCS#12 file.
  • --ckaid CKAID — the hex CKAID of the X.509 certificate. Certificates live in the NSS database, no cap 💅
  • --ca distinguished name — the X.509 Certificate Authority's Distinguished Name (DN) used as the trust anchor for this connection 🫶. This is the CA certificate that signed the host certificate, as well as the certificate of the incoming client.
  • --groups access control groups — the access control groups used.
  • --sendcert yes|forced|always|ifasked|no|never — whether or not to send our X.509 certificate credentials 📜. Fair warning: this could potentially give an attacker too much information about which identities are allowed to connect to this host 😬. The default is ifasked when we're a Responder, and yes (which is the same as forced and always) when we're an Initiator. The values no and never are equivalent.
⚠️ NOTE: "forced" does not seem to be actually implemented — do not use it. Not me warning you about a flag that's giving unfinished business 💀
  • --sendca none|issuer|all — how much of our available X.509 trust chain to send along with the end certificate, excluding any root CAs 🌈. issuer sends just the issuing intermediate CA, all sends the entire chain of intermediate CAs, and none sends no CA certs at all. The default is none, which maintains the current libreswan behavior.
  • --certtype number — the X.509 certificate type number.
  • --ikeport port-number — the UDP port that IKE listens to on that host 👀. The default is 500. (Pluto on this machine uses the port specified by its own command line argument, so this only affects where pluto sends messages.)
  • --nexthop ip-address — where to route packets for the peer's client (presumably for the peer too, but it won't be used for that) 🛣️. When pluto installs an IPsec SA, it issues a route command and uses the nexthop as the gateway. The default is the peer's IP address — which you can also explicitly write as %direct, and the obsolete notation 0.0.0.0 is accepted too. This option is necessary if pluto's host's interface used for sending packets to the peer is neither point-to-point nor directly connected to the peer. Important stuff, bestie 💜
  • --client subnet — the subnet for which the IPsec traffic will be destined 🎯. If you don't specify it, the host is the client. The subnet can be given in any of the forms supported by ipsec_atosubnet(3). The general form is address/mask. The address can be either a domain name or four decimal numbers (octets) separated by dots. The most convenient form of the mask is a decimal integer specifying the number of leading one bits in the mask — so for example 10.0.0.0/8 specifies the class A network "Net 10". Slay 🌟
  • --clientprotoport protocol/port — specifies the Port Selectors (filters) to be used on this connection 🌸. General form: protocol/port. Most commonly used to limit the connection to L2TP traffic only by specifying 17/1701 for UDP (protocol 17) and port 1701. The notation 17/%any can be used to allow all UDP traffic, and it's needed for L2TP connections with Windows XP machines before Service Pack 2. Vintage tech moment 😭
  • --srcip ip-address — the IP address for this host to use when transmitting a packet to the remote IPsec gateway itself 👑. This option makes the gateway itself use its internal IP, which is part of the --client subnet. Otherwise it'll use its nearest IP address, which is its public IP address — which is not part of the subnet-to-subnet IPsec tunnel, and therefore would not get encrypted 🙈. Use it.
  • --xauthserver — this end is an xauthserver. It looks up the xauth user name and password and verifies them before allowing the connection to get established 💅
  • --xauthclient — this end is an xauthclient. To bring this connection up with --initiate you also need the client to specify --xauthuser username and --xauthpass password 🫶
  • --xauthuser — the username for the xauth authentication. This option is normally passed along by ipsec_auto(8) when an xauth connection is started using ipsec auto --up conn ✨
  • --xauthpass — the password for the xauth authentication. Also normally passed along by ipsec_auto(8) when an xauth connection is started using ipsec auto --up conn 🔐
  • --modecfgserver — this end is a Mode Config server 👑
  • --modecfgclient — this end is a Mode Config client 🦋
  • --modecfgdns — a comma separated list of DNS server IPs to pass along to connecting clients 📋
  • --modecfgdomains — a comma separated list of internal DNS domains to pass along to connecting clients 🌐
  • --dnskeyondemand — specifies that when an RSA public key is needed to authenticate this host, and it isn't already known, fetch it from DNS 🎀
  • --updown updown — specifies an external shell command to be run whenever pluto brings up or down a connection 🔥. The script is used to build a shell command, so it may contain positional parameters — but it ought not to have punctuation that would cause the resulting command to be ill-formed (same energy as the connection name rule, bestie). The default is ipsec _updown. Pluto passes a dozen environment variables to the script about the connection involved 💖
  • --to — separates the specification of the left and right ends of the connection 🎯. Pluto tries to decide whether it's left or right based on the information provided on both sides of this option.

The potential connection description also specifies characteristics of rekeying and security 🔐.

  • --psk — propose and allow preshared secret authentication for IKE peers 🤝. This authentication requires that each side use the same secret. May be combined with --rsasig; at least one must be specified.
  • --rsasig — propose and allow RSA signatures for authentication of IKE peers 🖊️. This authentication requires that each side have a private key of its own and know the public key of its peer. May be combined with --psk; at least one must be specified.
  • --encrypt — all proposed or accepted IPsec SAs will include non-null ESP 💫. The actual choices of transforms are wired into pluto.
  • --authenticate — all proposed IPsec SAs will include AH. All accepted IPsec SAs will include AH or ESP with authentication 🔏. The actual choices of transforms are wired into pluto. Note that this has nothing to do with IKE authentication — don't get it twisted 😌
  • --compress — all proposed IPsec SAs will include IPCOMP (compression) 🗜️
  • --tunnel — the IPsec SA should use tunneling 🚇. Implicit if the SA is for clients. Must only be used with --authenticate or --encrypt.
  • --ipv4 — the host addresses will be interpreted as IPv4 addresses. This is the default 👑. Note that for a connection, all host addresses must be of the same Address Family — IPv4 and IPv6 use different Address Families, so no mixing and matching, bestie 🚫
  • --ipv6 — the host addresses (including nexthop) will be interpreted as IPv6 addresses 🌈. Note that for a connection, all host addresses must be of the same Address Family (IPv4 and IPv6 use different Address Families).
  • --tunnelipv4 — the client addresses will be interpreted as IPv4 addresses. The default is to match whatever the host will be 🎀. This does not imply --tunnel, so the flag can be safely used when no tunnel is actually specified. Note that for a connection, all tunnel addresses must be of the same Address Family.
  • --tunnelipv6 — the client addresses will be interpreted as IPv6 addresses 💜. The default is to match whatever the host will be. This does not imply --tunnel, so the flag can be safely used when no tunnel is actually specified. Note that for a connection, all tunnel addresses must be of the same Address Family.
  • --pfs — bestie we're doing Perfect Forward Secrecy 💪 brand-new keying material gets generated for every single IPsec SA when you're running Quick Mode in IKEv1 or Create Child in IKEv2. Without this flag, the SAKMP SA keying material gets reused instead (mid, honestly). With it, pluto will propose the same group that was used with the original IKE SA.
  • --pfsgroup modp-group — sets which Diffie-Hellman group we're using ✨ Currently supported values are: modp1024 (DHgroup 2), modp1536 (DHgroup 5), modp2048 (DHgroup 14), modp3072 (DHgroup 15), modp4096 (DHgroup 16), modp6144 (DHgroup 17), and modp8192 (DHgroup 18). You can technically support the weak and broken modp768 (DHgroup 1), but that requires a manual recompile and is strongly discouraged 🚩 like, don't.
  • --esp esp-algos — the ESP encryption/authentication algorithm used for the connection (phase2 aka IPsec SA, iykyk). The options have to be suitable as a value of ipsec_spi(8). For the full detailed description of the algorithm format, go check ipsec.conf(5) 📖
  • --aggrmode — this tunnel is using aggressive mode ISAKMP negotiation. Default is main mode. Heads up: aggressive mode is less secure than main mode because it literally reveals your identity to an eavesdropper 🙈 but it's needed to support road warriors using PSK keys, or to interoperate with other buggy implementations that insist on using aggressive mode. slay for compat, cringe for privacy, balance.
  • --modecfgpull — pull the Mode Config network information from the peer 🫶
  • --dpddelay seconds — sets the delay, in seconds, between Dead Peer Detection (RFC 3706) keepalives (R_U_THERE, R_U_THERE_ACK) that get sent for this connection. Default is 30 seconds ⏱️
  • --timeout seconds — sets how long, in seconds, we'll idle without hearing either an R_U_THERE poll from our peer or an R_U_THERE_ACK reply. Once that period elapses with no response and no traffic, we declare the peer dead and remove the SA. Default is 120 seconds 💀
  • --dpdaction action — when a DPD-enabled peer gets declared dead, what do we do about it? hold (default) means the eroute gets put into %hold status, while clear means the eroute and SA both get cleared. clear is really only useful on the server of a Road Warrior config. The action restart is used on tunnels that need to be permanently up and have static IP addresses. The action restart_by_peer has been obsoleted and its functionality has been moved into the restart action 🎀
  • --forceencaps — in some cases, like when ESP packets get filtered or when a broken IPsec peer doesn't properly recognise NAT, it can be useful to force RFC-3948 encapsulation with this option. It makes pluto lie and tell the remote peer that RFC-3948 encapsulation (ESP in UDP port 4500 packets) is required 👀 no cap, sometimes you gotta lie.

If none of the --encrypt, --authenticate, --compress, or --pfs flags is given, then initiating the connection will only build an ISAKMP SA. For a connection like that, client subnets have no meaning and must not be specified ⚠️

Apart from initiating directly using the --initiate option, a tunnel can be loaded with a different policy 🌸

  • --initiateontraffic — only initiate the connection when we actually have traffic to send over the connection. lazy girlie behaviour, but make it networking 💅
  • --pass — allow unencrypted traffic to flow until the tunnel is initiated 🚗
  • --drop — drop unencrypted traffic silently 🤫
  • --reject — drop unencrypted traffic silently, but send an ICMP message notifying the other end 📢

These options need to be documented 😭 (not me doing the homework that the man page didn't):

  • --failnone — to be documented
  • --failpass — to be documented
  • --faildrop — to be documented
  • --failreject — to be documented

pluto supports various X.509 Certificate related options 🎀

  • --utc — display all times in UTC 🕐
  • --listall — lists all of the X.509 information known to pluto
  • --listpubkeys — list all the public keys that have been successfully loaded 🔑
  • --listcerts — list all the X.509 certificates that are currently loaded
  • --checkpubkeys — list all the loaded X.509 certificates that are about to expire or have expired ⏳
  • --listcacerts — list all the Certificate Authority X.509 certificates that are currently loaded 👑
  • --listcrls — list all the loaded Certificate Revocation Lists (CRLs) 📋

The corresponding --rereadsecrets, --rereadall, and --rereadcrls options reread this information from their respective sources, and purge all the online obtained information. The option --listevents lists all pending events, and --ddns triggers the Dynamic DNS update event that's normally scheduled to run once every minute ⏰

  • --ikelifetime seconds — how long pluto will propose that an ISAKMP SA be allowed to live. Default is 3600 (one hour) and the maximum is 86400 (1 day). This option will not affect what is accepted — pluto will reject proposals that exceed the maximum 🚫
  • --ipseclifetime seconds — how long pluto will propose that an IPsec SA be allowed to live. Default is 28800 (eight hours) and the maximum is 86400 (one day). Same deal: this option will not affect what is accepted, and pluto will reject proposals that exceed the maximum 🚫
  • --rekeymargin seconds — how long before an SA's expiration pluto should try to negotiate a replacement SA. This only happens if pluto was the initiator. Default is 540 (nine minutes) ⏳
  • --rekeyfuzz percentage — maximum size of the random component added to rekeymargin, expressed as a percentage of rekeymargin. pluto will select a delay uniformly distributed within this range. By default the percentage is 100. If you want greater determinism, specify 0. It may be appropriate for the percentage to be much larger than 100 🎲
  • --keyingtries count — how many times pluto should try to negotiate an SA, either for the first time or for rekeying. The default value of 0 means keep trying forever 🔥
  • --dontrekey — okay so this name is a misnomer 💀 it only rekeys a connection if we were the Initiator and there was recent traffic on the existing connection. This applies to Phase 1 and Phase 2. It's currently the only automatic way for a connection to terminate. It may be useful with Road Warrior or Opportunistic connections. Since SA lifetime negotiation is take-it-or-leave-it, a Responder normally uses the shorter of the negotiated or the configured lifetime. This only works because if the lifetime is shorter than negotiated, the Responder will rekey in time so everything works. But it interacts badly with --dontrekey — in this case the Responder ends up rekeying to rectify a shortfall in an IPsec SA lifetime; for an ISAKMP SA, the Responder will accept the negotiated lifetime 😬
  • --delete — when used in the connection form, it causes any previous connection with this name to be deleted before this one is added. Unlike a normal delete, no diagnostic is produced if there was no previous connection to delete. Any routing in place for the connection is undone 🗑️
  • --delete, --name connection-name — the delete form deletes a named connection description and any SAs established or negotiations initiated using this connection. Any routing in place for the connection is undone ✂️
  • --deletestate state-number — the deletestate form deletes the state object with the specified serial number. Useful for selectively deleting instances of connections 🎯

The route form of the whack command tells pluto to set up routing for a connection. Even though it's like a traditional route, it uses an ipsec device as a virtual interface 🛣️ Once routing is set up, no packets will be sent "in the clear" to the peer's client specified in the connection. A TRAP shunt eroute gets installed; if outbound traffic gets caught, pluto will initiate the connection. An explicit whack route isn't always needed — if it hasn't been done when an IPsec SA is being installed, one will be automatically attempted ✨

  • --route, --name connection-name — when a routing is attempted for a connection, there must not already be a routing for a different connection with the same subnet but different interface or destination — or if there is, it must not be being used by an IPsec SA. Otherwise the attempt will fail 😭
  • --unroute, --name connection-name — the unroute form of the whack command tells pluto to undo a routing. pluto will refuse if an IPsec SA is using the connection. If another connection is sharing the same routing, it will be left in place. Without a routing, packets get sent without encryption or authentication 🙈

The initiate form tells pluto to initiate a negotiation with another pluto (or other IKE daemon) according to the named connection. Initiation requires a route that --route would provide; if none is in place at the time an IPsec SA is being installed, pluto attempts to set one up 🫶

  • --initiate, --name connection-name, --asynchronous — the initiate form of the whack command will relay back from pluto status information via the UNIX domain socket (unless --asynchronous is specified). The status information is meant to look a bit like that from FTP 📠 Currently whack just copies this to stderr. When the request is finished (eg. the SAs are established or pluto gives up), pluto closes the channel, causing whack to terminate.

The opportunistic initiate form is mainly used for debugging 🐛

  • --tunnelipv4, --tunnelipv6, --oppohere ip-address, --oppothere ip-address, --opposport port, --oppodport port, --oppoproto protocol — this causes pluto to attempt to opportunistically initiate a connection from here to the there, even if a previous attempt had been made. The whack log will show the progress of this attempt 👀

🦋 Rekeying a connection 🦋

  • --rekey-ipsec, --name connection-name — the rekey-ipsec form tells pluto to rekey the IPsec SA (child SA) of the specified connection. It does not affect the IKE SA (parent SA) 💅
  • --rekey-ike, --name connection-name — the rekey-ike form tells pluto to rekey the IKE SA (parent SA) of the specified connection. It does not affect the IPsec SAs (child SAs) ✨

🌸 Ending a connection 🌸

  • --terminate, --name connection-name — the terminate form tells pluto to delete any SAs that use the specified connection and to stop any negotiations in process. It does not prevent new negotiations from starting (the delete form has that effect) 🎀
  • --crash ip-address — okay so picture this: the remote peer has straight-up crashed 💀 and therefore never notified us. So we just keep yeeting encrypted traffic into the void and rejecting all the plaintext (non-IKE) traffic from that peer. --crash brings our end down too, for every single known connection to that ip-address. Iconic cleanup behavior, honestly.
  • ip-address — yeah this is the exact same thing as above, restated: if the remote peer crashed and never told us, we keep sending encrypted traffic and rejecting all plaintext (non-IKE) traffic from it, and --crash brings our end down as well for all known connections to that ip-address. 🫶

Redirecting clients can be done using the IKEv2 redirect mechanism. Slay.

  • --global-redirect yes|no|auto — controls whether pluto will instruct remote peers to redirect IKE/IPsec SA's during IKE_SA_INIT. The valid options are no, yes and auto, where auto means remote peers get redirected if DDoS mode is active. Lowkey clever.
  • --global-redirect-to ip-address(es) — the destination, or a whole list of destinations, where the peers will be redirected. ✨
  • --name connection_name, --redirect-to ip-address(es) — the destination, or a list of destinations, where the peers will be redirected. Specifying the connection name is optional — if you don't specify it, the mechanism redirects all currently active peers. If you do specify it, only the peers from connection connection_name get redirected. iykyk.

The public key form informs pluto of the RSA public key for a potential peer. Private keys must be kept secret, so they're kept in ipsec.secrets(5). 🔐

  • --keyid id — specifies the identity of the peer for which a public key should be used. Its form is identical to the identity in the connection. If no public key is specified, pluto attempts to find KEY records from DNS for the id (if it's a FQDN) or through reverse lookup (if it's an IP address). Heads up bestie: there are several interesting ways in which this is not secure. 🙈
  • --addkey — specifies that the new key is added to the collection; otherwise the new key replaces any old ones. Bye old keys 👋
  • --pubkeyrsa key — specifies the value of the RSA public key. It's a sequence of bytes as described in RFC 2537 "RSA/MD5 KEYs and SIGs in the Domain Name System (DNS)". It's denoted in a way suitable for ipsec_ttodata(3). For example, a base 64 numeral starts with 0s.

The listen form tells pluto to start listening for IKE requests on its public interfaces. To avoid race conditions, it's normal to load the appropriate connections into pluto before letting it listen. And if pluto isn't listening, it's pointless to initiate negotiations, so it will refuse requests to do so. Whenever the listen form is used, pluto looks for public interfaces and will notice when new ones have been added and when old ones have been removed. This is also the trigger for pluto to read the ipsec.secrets file. So --listen may useful more than once. 🎀

  • --listen — start listening for IKE traffic on public interfaces.
  • --unlisten — stop listening for IKE traffic on public interfaces.

The --ddos-auto, --ddos-busy and --ddos-unlimited options tell pluto to update the DDoS protection state. Normally these measures are automatically activated or deactivated based on the number of states inside pluto. The busy and unlimited options tell pluto to activate or deactivate the DDoS protection mode manually. One of these DDoS protection methods is to activate IKEv2 DCOOKIEs to defend against spoofed IKE packets. 🍪

  • --ddos-busy — place pluto into busy mode and activate anti-DDoS measures.
  • --ddos-unlimited — pull pluto out of busy mode and deactivate anti-DDoS measures.
  • --ddos-auto — activate the built-in detection mechanism for the anti-DDoS measures.

The status form will display info about the internal state of pluto: info about each potential connection, about each state object, and about each shunt that pluto is managing without an associated connection. Full tour of pluto's brain 🧠

Statistics can be seen using ipsec whack --globalstats and reset using ipsec whack --clearstats. This can be used with the munin software to monitor VPN services. Obsessed with a monitoring setup, ngl.

  • --status

The trafficstatus form will display the xauth username, add_time and the total in and out bytes of the IPsec SA's. 💅

  • --trafficstatus

The shutdown form is the proper way to shut down pluto. It will tear down the SAs on this machine that pluto has negotiated. If the --leave-state option is given, it does not delete any connections, and leaves the kernel state in the kernel. But note that the init system used might clean up the kernel state regardless. 😭

  • --shutdown

✨ Examples ✨

It would be normal to start pluto in one of the system initialization scripts. It needs to be run by the superuser. Generally, no arguments are needed. To run it manually, the superuser can simply type:

ipsec pluto

The command will immediately return, but a pluto process will be left running, waiting for requests from whack or a peer. Main character energy: peaces out but is definitely still there. 👑

Using whack, several potential connections would be described:

ipsec whack --name silly --host 127.0.0.1 --to --host 127.0.0.2 --ikelifetime 900 --ipseclifetime 800 --keyingtries 3

Since this silly connection description specifies neither encryption, authentication, nor tunneling, it could only be used to establish an ISAKMP SA.

ipsec whack --name conn_name --host 10.0.0.1 --client 10.0.1.0/24 --to --host 10.0.0.2 --client 10.0.2.0/24 --encrypt

This is something that must be done on both sides. If the other side is pluto, the same whack command could be used on it (the command syntax is designed to not distinguish which end is ours). Symmetry, we love to see it. 🦋

Now that the connections are specified, pluto is ready to handle requests and replies via the public interfaces. We must tell it to discover those interfaces and start accepting messages from peers:

ipsec whack --listen

If we don't immediately wish to bring up a secure connection between the two clients, we might wish to prevent insecure traffic. The routing form asks pluto to cause the packets sent from our client to the peer's client to be routed through the ipsec0 device; if there is no SA, they will be discarded:

ipsec whack --route conn_name

Finally, we are ready to get pluto to initiate negotiation for an IPsec SA (and implicitly, an ISAKMP SA):

ipsec whack --initiate --name conn_name

A small log of interesting events will appear on standard output (other logging is sent to syslog).

whack can also be used to terminate pluto cleanly, tearing down all SAs that it has negotiated.

ipsec whack --shutdown

Notification of any IPSEC SA deletion, but not ISAKMP SA deletion, is sent to the peer. Unfortunately, such Notification is not reliable. Furthermore, pluto itself ignores Notifications. 💀 So like... don't count on it.

🌸 XAUTH 🌸

If pluto needs additional authentication, such as defined by the XAUTH specifications, then it may ask whack to prompt the operator for username or passwords. Typically, these will be entered interactively. A GUI that wraps around whack may look for the 041 (username) or 040 (password) prompts, and display them to the user. 🧚

For testing purposes, the options --xauthuser user --xauthpass pass may be be given prior to the --initiate to provide responses to the username and password prompts.

🫶 The updown command 🫶

Whenever pluto brings a connection up or down, it invokes the updown command. This command is specified using the --updown option. This allows for customized control over routing and firewall manipulation. Basically your little helper script that does the manual labor 💅

The updown is invoked for five different operations. Each of these operations can be for our client subnet or for our host itself.

  • prepare-host or prepare-client — is run before bringing up a new connection if no other connection with the same clients is up. Generally, this is useful for deleting a route that might have been set up before pluto was run or perhaps by some agent not known to pluto.
  • route-host or route-client — is run when bringing up a connection for a new peer client subnet (even if prepare-host or prepare-client was run). The command should install a suitable route. Routing decisions are based only on the destination (peer's client) subnet address, unlike eroutes which discriminate based on source too.
  • unroute-host or unroute-client — is run when bringing down the last connection for a particular peer client subnet. It should undo what the route-host or route-client did.
  • up-host or up-client — is run when bringing up a tunnel eroute with a pair of client subnets that does not already have a tunnel eroute. This command should install firewall rules as appropriate. It is generally a good idea to allow IKE messages (UDP port 500) travel between the hosts.
  • down-host or down-client — is run when bringing down the eroute for a pair of client subnets. This command should delete firewall rules as appropriate. Note that there may remain some inbound IPsec SAs with these client subnets.

The script is passed a large number of environment variables to specify what needs to be done. Get comfy, there's a bunch 🍓

  • PLUTO_VERB — specifies the name of the operation to be performed (prepare-host,r prepare-client, up-host, up-client, down-host, or down-client). If the address family for security gateway to security gateway communications is IPv6, then a suffix of -v6 is added to the verb.
  • PLUTO_CONNECTION — is the name of the connection for which we are routing.
  • PLUTO_NEXT_HOP — is the next hop to which packets bound for the peer must be sent.
  • PLUTO_INTERFACE — is the name of the ipsec interface to be used.
  • PLUTO_ME — is the IP address of our host.
  • PLUTO_MY_CLIENT — is the IP address / count of our client subnet. If the client is just the host, this will be the host's own IP address / max (where max is 32 for IPv4 and 128 for IPv6).
  • PLUTO_MY_CLIENT_NET — is the IP address of our client net. If the client is just the host, this will be the host's own IP address.
  • PLUTO_MY_CLIENT_MASK — is the mask for our client net. If the client is just the host, this will be 255.255.255.255.
  • PLUTO_PEER — is the IP address of our peer.
  • PLUTO_PEER_CLIENT — is the IP address / count of the peer's client subnet. If the client is just the peer, this will be the peer's own IP address / max (where max is 32 for IPv4 and 128 for IPv6).
  • PLUTO_PEER_CLIENT_NET — is the IP address of the peer's client net. If the client is just the peer, this will be the peer's own IP address.
  • PLUTO_PEER_CLIENT_MASK — the mask for the peer's client net. If the client is literally just the peer itself, this baby is 255.255.255.255. 🎀
  • PLUTO_MY_PROTOCOL — lists the protocols allowed over this IPsec SA.
  • PLUTO_PEER_PROTOCOL — lists the protocols the peer allows over this IPsec SA.
  • PLUTO_MY_PORT — lists the ports allowed over this IPsec SA.
  • PLUTO_PEER_PORT — lists the ports the peer allows over this IPsec SA.
  • PLUTO_MY_ID — lists our id.
  • PLUTO_PEER_ID — lists our peer's id.
  • PLUTO_PEER_CA — lists the peer's CA.

Okay so every single thing your script throws at stderr or stdout gets logged, bestie. The script should return an exit status of 0 if and only if it succeeds — no cap. 💯

And here's the part where you gotta be chill: Pluto waits for the script to finish and will not do any other processing while it's waiting 😭. So your script gets to assume pluto won't change anything while it runs. But please — avoid doing anything that takes much time, and do not issue any command that requires processing by pluto. Both of those activities can totally be done by a background subprocess of the script instead. Slay responsibly. 🦋

💫 Rekeying 💫

So when an SA that was initiated by pluto has only a bit of lifetime left, pluto will initiate the creation of a new SA. This applies to ISAKMP and IPsec SAs. The rekeying gets kicked off when the SA's remaining lifetime is less than the rekeymargin plus a random percentage — between 0 and rekeyfuzz — of the rekeymargin. Periodt. ✨

Same vibe for an SA that was initiated by the peer: when it's got a bit of lifetime left, pluto will try to initiate the creation of a replacement. But to give preference to the initiator, this rekeying only starts when the SA's remaining lifetime is half of rekeymargin. And if rekeying is done by the responder, the roles get reversed: the responder for the old SA becomes the initiator for the replacement 😳. The former initiator might also initiate rekeying, so there may be redundant SAs created. To avoid these complications, make sure your rekeymargin is generous. 🙏

One risk of having the former responder initiate is that maybe none of its proposals is acceptable to the former initiator (they have not been used in a successful negotiation). To reduce the chances of this happening, and to prevent loss of security, the policy settings are taken from the old SA — and this is the case even if the former initiator is the one initiating. Note that these may be stricter than those of the connection. ⚠️

pluto will not rekey an SA if that SA is not the most recent of its type (IPsec or ISAKMP) for its potential connection. That's how we avoid creating redundant SAs, icon behaviour honestly. 👑

The random component in the rekeying time (rekeyfuzz) is intended to make certain pathological patterns of rekeying unstable. Because listen: if both sides decide to rekey at the same time, twice as many SAs as necessary get created 😭. That could become a stable pattern without the randomness.

And there's an even more important case — when a security gateway has SAs with many other security gateways. Each of these connections might need to be rekeyed at the same time, which would cause a high peek requirement for resources (network bandwidth, CPU time, entropy for random numbers). rekeyfuzz can be used to stagger the rekeying times. Staggered rekeys are the main character energy we deserve. 🌈

Once a new set of SAs has been negotiated, pluto will never send traffic on a superseded one. Traffic will still be accepted on an old SA until it expires.

🌸 Selecting a Connection When Responding: Road Warrior Support 🌸

When pluto receives an initial Main Mode message, it needs to decide which connection this message is for. It picks based solely on the source and destination IP addresses of the message. There might be several connections with suitable IP addresses, in which case one of them is arbitrarily chosen (the ISAKMP SA proposal contained in the message could be taken into account, but it is not — ngl, it just isn't).

The ISAKMP SA is negotiated before the parties pass further identifying information, so all ISAKMP SA characteristics specified in the connection description should be the same for every connection with the same two host IP addresses. At the moment, the only characteristic that might differ is authentication method.

Up to this point, all configuring has presumed that the IP addresses are known to all parties ahead of time. That does not work when either end is mobile (or assigned a dynamic IP address for other reasons). We call this situation "Road Warrior". It's fairly tricky and has some important limitations — most of which are features of the IKE protocol, iykyk.

Only the initiator may be mobile: the initiator may have an IP number unknown to the responder. When the responder doesn't recognize the IP address on the first Main Mode packet, it looks for a connection with itself as one end and %any as the other. If it cannot find one, it refuses to negotiate 💀. If it does find one, it creates a temporary connection that is a duplicate except with the %any replaced by the source IP address from the packet; and if there was no identity specified for the peer, the new IP address will be used.

When pluto is using one of these temporary connections and needs to find the preshared secret or RSA private key in ipsec.secrets, and the connection specified no identity for the peer, %any is used as its identity. Honestly? Iconic reasoning: the real IP address was apparently unknown to the configuration, so it's unreasonable to require that it be used in this table. 🫶

Part way into the Phase 1 (Main Mode) negotiation using one of these temporary connection descriptions, pluto will receive an Identity Payload. At this point pluto checks for a more appropriate connection — one with an identity for the peer that matches the payload and would use the same keys as so far used for authentication. If it finds one, it will switch to using this better connection (or a temporary one derived from this, if it has %any for the peer's IP address). It may even turn out that no connection matches the newly discovered identity, including the current connection; if so, pluto terminates negotiation. Sorry bestie, that's the rule. 😭

Unfortunately, if preshared secret authentication is being used, the Identity Payload is encrypted using this secret, so the secret must be selected by the responder without knowing this payload. That limits there to being at most one preshared secret for all Road Warrior systems connecting to a host. RSA Signature authentication does not require that the responder knows how to select the initiator's public key until after the initiator's Identity Payload is decoded (using the responder's private key, so that must be preselected).

When pluto is responding to a Quick Mode negotiation via one of these temporary connection descriptions, it may well find that the subnets specified by the initiator don't match those in the temporary connection description. If so, it will look for a connection with matching subnets, its own host address, a peer address of %any and matching identities. If it finds one, a new temporary connection is derived from this one and used for the Quick Mode negotiation of IPsec SAs. If it does not find one, pluto terminates negotiation. 💅

Be sure to specify an appropriate nexthop for the responder to send a message to the initiator: pluto has no way of guessing it. If forwarding isn't required, use an explicit %direct as the nexthop and the IP address of the initiator will be filled in — and yes, the obsolete notation 0.0.0.0 is still accepted. 🎀

pluto has no special provision for the initiator side. The current (possibly dynamic) IP address and nexthop must be used in defining connections. These must be properly configured each time the initiator's IP address changes. pluto has no mechanism to do this automatically. You're on your own for that one, bestie. 🙈

Although we call this Road Warrior Support, it could also be used to support encrypted connections with anonymous initiators. The responder's organization could announce the preshared secret that would be used with unrecognized initiators and let anyone connect. Of course the initiator's identity would not be authenticated. 🚨

If any Road Warrior connections are supported, pluto cannot reject an exchange initiated by an unknown host until it has determined that the secret is not shared or the signature is invalid. This must await the third Main Mode message from the initiator. If no Road Warrior connection is supported, the first message from an unknown source would be rejected. This has implications for ease of debugging configurations and for denial of service attacks. 😬

Although a Road Warrior connection must be initiated by the mobile side, the other side can and will rekey using the temporary connection it has created. If the Road Warrior wishes to be able to disconnect, it is probably wise to set --keyingtries to 1 in the connection on the non-mobile side to prevent it trying to rekey the connection. Unfortunately, there is no mechanism to unroute the connection automatically. 💀

🔍 Debugging 🔍

pluto accepts several optional arguments, useful mostly for debugging. Except for --interface, each should appear at most once.

  • --interface interfacename — specifies that the named real public network interface should be considered. The interface name specified should not be ipsecN. If the option doesn't appear, all interfaces are considered. To specify several interfaces, use the option once for each. One use of this option is to specify which interface should be used when two or more share the same IP address. 🦋
  • --ikeport port-number — changes the UDP port that pluto will use (default, specified by IANA: 500).
  • --ctlbase path — basename for control files. path.ctl is the socket through which whack communicates with pluto. path.pid is the lockfile to prevent multiple pluto instances. The default is /var/run/pluto/pluto.
  • --secretsfile file — specifies the file for authentication secrets (default: /etc/ipsec.secrets). This name is subject to "globbing" as in sh(1), so every file with a matching name is processed. Quoting is generally needed to prevent the shell from doing the globbing. ⭐
  • --nofork — disable "daemon fork" (default is to fork). In addition, after the lock file and control socket are created, print the line Pluto initialized to standard out. ✨
  • --uniqueids — if this option has been selected, whenever a new ISAKMP SA is established, any connection with the same Peer ID but a different Peer IP address is unoriented (causing all its SAs to be deleted). This helps clean up dangling SAs when a connection is lost and then regained at another IP address. 🧚
  • --force-busy — ok so if you pick this one, pluto gets forced into being "busy" 🫶. That "busy" state is literally what happens during a Denial of Service attack, and in it pluto is made to use cookies before it'll accept any new incoming IKE packets. Cookies get sent and required in ikev1 Aggressive Mode and in ikev2. It's mostly a testing thing, but paranoid admins are absolutely allowed to pick it too. No cap. 💅
  • --stderrlog — log goes to standard out. (the default is to use syslogd(8)) 👀

pluto is willing to produce a prodigious amount of debugging information, like it's showing off 💀. There are several classes of debugging output, and pluto may be directed to produce a selection of them. All lines of debugging output are prefixed with "| " so you can tell them apart from normal diagnostic messages. iykyk.

When pluto is invoked, it may be given arguments to specify which debug classes to output. The current options are:

  • --debug help (whack only) — list the debugging classes recognised by pluto ✨
  • --debug none — disable logging for all debugging classes 🙈
  • --debug base — enable debug-logging
  • --debug cpu-usage — enable cpu-usage logging 🔥
  • --debug class, --no-debug class, --debug no-class — enable (disable) logging of the specified debugging class (--debug help lists debugging classes supported by this version of pluto)

The debug form of the whack command will change the selection in a running pluto. If a connection name is specified, the flags are added whenever pluto has identified that it is dealing with that connection. Unfortunately — and this is the annoying part 😭 — this is often part way into the operation being observed.

For example, to start pluto with both base and cpu-usage debug-logging enabled:

         pluto --debug base --debug cpu-usage

To later change this pluto to disable base debug-logging use either:

         whack --no-debug base

or:

         whack --debug none --debug cpu-usage

🧪 Impairing

pluto and whack accept several optional arguments that alter (impair) correct behaviour. Yes bestie, "impair" literally means breaking it on purpose 🫠

These options are solely intended for use by developers when testing pluto.
  • --impair help (whack only) — list all the behaviours that can be altered (impaired)
  • --impair list (whack only) — list all the behaviours that are currently altered (impaired)
  • --impair none — disable all altered (impaired) behaviours
  • --impair behaviour, --impair behaviour:how, --no-impair behaviour — alter (impair) pluto inducing the (possibly erroneous) behaviour 💀

🚨 Pluto's Behaviour When Things Go Wrong

When pluto doesn't understand or accept a message, it just ignores the message. It is not yet capable of communicating the problem to the other IKE daemon (in the future it might use Notifications to accomplish this in many cases). It does log a diagnostic, so there's that 🌸

When pluto gets no response from a message, it resends the same message (a message will be sent at most three times). This is appropriate: UDP is unreliable. periodt.

When pluto gets a message that it has already seen, there are many cases when it notices and discards it. This too is appropriate for UDP.

Combine these three rules, and you can explain many apparently mysterious behaviours 👑. In a pluto log, retrying isn't usually the interesting event. The critical thing is either earlier (pluto got a message that it didn't like and so ignored, so it was still awaiting an acceptable message and got impatient) or on the other system (pluto didn't send a reply because it wasn't happy with the previous message).

📝 Notes

Each IPsec SA is assigned an SPI, a 32-bit number used to refer to the SA. The IKE protocol lets the destination of the SA choose the SPI. The range 0 to 0xFF is reserved for IANA. Pluto also avoids choosing an SPI in the range 0x100 to 0xFFF, leaving these SPIs free for manual keying. Remember that the peer, if not pluto, may well choose SPIs in this range 🎀

📜 Policies

This catalogue of policies may be of use when trying to configure Pluto and another IKE implementation to interoperate.

In Phase 1, only Main Mode is supported. We are not sure that Aggressive Mode is secure. For one thing, it does not support identity protection. It may allow more severe Denial Of Service attacks. 🚩

No Informational Exchanges are supported. These are optional and since their delivery is not assured, they must not matter. It is the case that some IKE implementations won't interoperate without Informational Exchanges, but we feel they are broken 🙅‍♀️

No Informational Payloads are supported. These are optional, but useful. It is of concern that these payloads are not authenticated in Phase 1, nor in those Phase 2 messages authenticated with HASH(3).

  • Diffie Hellman Groups MODP 1024 and MODP 1536 (2 and 5) are supported. Group MODP768 (1) is not supported because it is too weak 💪
  • Host authentication can be done by RSA Signatures or Pre-Shared Secrets.
  • 3DES CBC (Cypher Block Chaining mode) is the only encryption supported, both for ISAKMP SAs and IPSEC SAs.
  • MD5 and SHA1 hashing are supported for packet authentication in both kinds of SAs.
  • The ESP, AH, or AH plus ESP are supported. If, and only if, AH and ESP are combined, the ESP need not have its own authentication component. The selection is controlled by the --encrypt and --authenticate flags.
  • Each of these may be combined with IPCOMP Deflate compression, but only if the potential connection specifies compression.
  • The IPSEC SAs may be tunnel or transport mode, where appropriate. The --tunnel flag controls this when pluto is initiating.
  • When responding to an ISAKMP SA proposal, the maximum acceptable lifetime is eight hours. The default is one hour. There is no minimum. The --ikelifetime flag controls this when pluto is initiating.
  • When responding to an IPSEC SA proposal, the maximum acceptable lifetime is one day. The default is eight hours. There is no minimum. The --ipseclifetime flag controls this when pluto is initiating.
  • PFS is acceptable, and will be proposed if the --pfs flag was specified. The DH group proposed will be the same as negotiated for Phase 1.

⚡ SIGNALS

Pluto responds to SIGHUP by issuing a suggestion that `whack --listen` might have been intended. like, a little hint, a little nudge 🫶

Pluto exits when it receives SIGTERM. bye bestie 😭

🚪 EXIT STATUS

pluto normally forks a daemon process, so the exit status is normally a very preliminary result.

  1. 0 — means that all is OK so far. slay ✨
  2. 1 — means that something was wrong.
  3. 10 — means that the lock file already exists.

If whack detects a problem, it will return an exit status of 1. If it received progress messages from pluto, it returns as status the value of the numeric prefix from the last such message that was not a message sent to syslog or a comment (but the prefix for success is treated as 0). Otherwise, the exit status is 0.

📁 FILES

  • /var/run/pluto/pluto.pid
  • /var/run/pluto/pluto.ctl
  • /etc/ipsec.secrets
  • /dev/urandom

🌍 ENVIRONMENT

pluto does not use any environment variables 🙅‍♀️ (yes, zero, none, the void)

👀 SEE ALSO

The rest of the Libreswan distribution, in particular ipsec(8).

ipsec_auto(8) is designed to make using pluto more pleasant. Use it! fr fr 💖

ipsec.secrets(5) describes the format of the secrets file.

ipsec_atoaddr(3), part of the Libreswan distribution, describes the forms that IP addresses may take. ipsec_atosubnet(3), part of the Libreswan distribution, describes the forms that subnet specifications.

For more information on IPsec, the mailing list, and the relevant documents, see:

https://datatracker.ietf.org/wg/ipsecme/charter/

At the time of writing, the latest IETF IKE RFC is:

RFC 7296 Internet Key Exchange Protocol Version 2 (IKEv2)

The Libreswan web site <https://libreswan.org> and the mailing lists described there.

The Libreswan wiki <https://libreswan.org/wiki> and the mailing lists described there.

The Libreswan list of implemented RFCs <https://libreswan.org/wiki/Implemented_Standards>

🦋 HISTORY

This code is released under the GPL terms. See the accompanying files CHANGES COPYING and CREDITS.* for more details.

Detailed history (including FreeS/WAN and Openswan) can be found in the docs/ directory.

🐛 BUGS

Please see <https://bugs.libreswan.org> for a list of currently known bugs and missing features.

Bugs should be reported to the <swan-dev@lists.libreswan.org> mailing list. we love a good bug report 💜

👑 AUTHOR

Paul Wouters

  • placeholder to suppress warning

okay that's the whole page bestie, you made it to the end 🎉 this one's from libreswan, dated 10/19/2026, and it's IPSEC_PLUTO(8) — go forth and configure your IPsec responsibly 💅✨🌸

📦 where this page comes from