IPSEC-WHACK(8)

📦
version 5.4.1 · 10 versions
, in fedora 43, fedora 44

🎀 ipsec-whack(8) 🎀

okay so bestie, this is ipsec-whack from the Executable programs manual, section 8, and it's a lot — but don't panic, we're doing this together 💖

✨ NAME ✨

ipsec-whack — ipsec whack : the low-level control interface for the IPsec IKE keying daemon. it's giving "the remote control for pluto" energy 👑

🌸 SYNOPSIS 🌸

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]
            [--send-supported-auth-methods yes | no]
            [--ikeport portnumber] [--nexthop ip-address]
            [[--client subnet] | [--subnet subnet]]
            [--clientprotoport protocol/port]
            [--fragmentation yes | no | force] [--narrowing yes | no]
            [--sourceip ip-address] [--interface-ip ip-address/mask]
            [--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] [--subnet subnet] [--client subnet]
            [--clientprotoport protocol/port] [--sourceip ip-address]
            [--interface-ip ip-address/mask] [--xauthserver]
            [--xauthclient] [--modecfgserver] [--modecfgclient]
            [--modecfgdns ip-address, ip-address, ...]
            [--modecfgdomains DNS-domain, DNS-domain, ...]
            [--dnskeyondemand] [--updown updown]

            [--tunnel] [--psk] [--rsasig]
            [--encapsulation [yes] | [no] | [auto]] [--encrypt]
            [--authenticate] [--compress] [--pfs]
            [--ikelifetime seconds] [--ipseclifetime seconds]
            [--rekeymargin seconds] [--rekeyfuzz percentage]
            [--ike ike-proposal] [--esp esp-proposal] [--ah ah-proposal]
            [--dontrekey] [--aggrmode] [--modecfgpull] [--metric metric]
            [--nflog-group nflognum] [--conn-mark mark/mask]
            [[--dpddelay seconds] | [--dpdtimeout seconds]]
            [--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]

ipsec whack --initiate --name connection [--remote-host ip-address]
            [--xauthuser user] [--xauthpass pass] [--bg[={yes,no}] |
            [--asynchronous[={yes,no}]]

ipsec whack --down --name connection [--bg[={yes,no}] |
            [--asynchronous[={yes,no}]]

ipsec whack {--rekey-ike | --rekey-child | --delete-ike | --delete-child
            | --down-ike | --down-child} --name connection
            [--bg[={yes,no}] | [--asynchronous[={yes,no}]]

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 [--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 --addresspoolstatus --briefstatus
            --connectionstatus --fipsstatus --processstatus
            --shuntstatus --trafficstatus [--rundir path]
            [--ctlsocket path/file] [--label string]

ipsec whack --globalstatus --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]

no cap, that's the whole vibe right there 💅

🦋 DESCRIPTION 🦋

🌈 GENERAL

okay so. ipsec whack is an auxiliary program — a little helper bestie — that lets you send requests to a running pluto. and how does it talk to pluto? through a UNIX domain socket, duh. by default that's /run/pluto/pluto.ctl 🔌

now, whack has an intricate argument syntax. like, intricate intricate. and that's on purpose, because this one syntax carries a whole bunch of different functions:

  • the help form shows you the usage or the version info
  • the connection form hands pluto a description of a potential connection
  • the public key form tells pluto the RSA public key for a potential peer
  • the delete form deletes a connection description and all the SAs that correspond to it
  • the listen form tells pluto to start or stop listening on the public interfaces for IKE requests from peers
  • the route form tells pluto to set up routing for a connection, and the unroute form undoes exactly that
  • the initiate form tells pluto to negotiate an SA corresponding to a connection
  • the terminate form tells pluto to remove all SAs corresponding to a connection — including the ones still being negotiated 😳
  • the status form shows pluto's internal state
  • the debug form tells pluto to change which debugging output it produces, "on the fly"
  • the shutdown form tells pluto to shut down, deleting all SAs

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. (Dead Peer Detection is the upgrade, --crash is the manual override, iykyk 🫶)

Most options belong to exactly one of those forms, and we'll describe them alongside that form. But there are three options that apply to all forms. the universal trio, the main characters:

  • --ctlsocket /run/pluto/pluto.ctl — this file is used as the UNIX domain socket for talking to pluto. use either this option or --rundir, but not both. pick a lane bestie 🙈
  • --rundir path — the path where the UNIX domain socket for talking to pluto lives, along with the pluto.pid file and the pluto.ctl files. use either this option or --ctlsocket, but not both.
  • --label string — adds the string to all error messages generated by whack. little signature on every oopsie ✨

The help form of whack is self-explanatory. (it really is, she explains herself 💅)

  • --help — Display the usage message.
  • --version — Display the version of whack.

👑 CONTROLLING PLUTO 👑

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. Note that the init system used might clean up the kernel state regardless — so like, you can leave it, but the init system might sweep it up anyway, no promises 🤷‍♀️

  • --shutdown — To be documented.

The listen form tells pluto to start listening for IKE requests on its public interfaces. To avoid race conditions, it is normal to load the appropriate connections into pluto before allowing it to listen. And here's the thing: if pluto isn't listening, it is 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. (yes, repeated listens, it's a whole thing, she's multi-talented 💜)

  • --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 tells 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 option tells 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. 🍪 (yes, DCOOKIEs. iconic name, honestly.)

  • --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. (let her decide for herself, she's got this 🧚)

pluto supports various X.509 Certificate related options. the certificate corner of the group chat 🎀

  • --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. (the "check on your friends" flag 😭)
  • --listcacerts — List all the Certificate Authority X.509 certificates that are currently loaded.
  • --listcrls — List all the loaded Certificate Revocation Lists (CRLs).

The corresponding options --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 the --ddns triggers the Dynamic DNS update event that is normally scheduled to run once every minute. ⏰

  • --ikelifetime seconds — How long pluto will propose that an ISAKMP SA be allowed to live. The default is 28800 (eight hours) and the maximum is 86400 (1 day). This option will not affect what is accepted. pluto will reject proposals that exceed the maximum. so like, don't try it, she will say no 🚫
  • --ipseclifetime seconds — how long pluto will propose that an IPsec SA lives. default is 28800 (eight hours) and the max is 86400 (one day). this option will not affect what's accepted. pluto will reject proposals that exceed the max. periodt. 💅
  • --rekeymargin seconds — how long before an SA's expiration should pluto try to negotiate a replacement SA. only happens if pluto was the initiator. default is 540 (nine minutes). ⏳
  • --rekeyfuzz percentage — max size of random component to add 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 greater determinism is desired, specify 0. it may be appropriate for the percentage to be much larger than 100. no cap. 🎲
  • --dontrekey — a misnomer, bestie. only rekey a connection if we were the Initiator and there was recent traffic on the existing connection. this applies to Phase 1 and Phase 2. this is 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 that everything works. this interacts badly with --dontrekey. in this case, the Responder will end up rekeying to rectify a shortfall in an IPsec SA lifetime; for an ISAKMP SA, the Responder will accept the negotiated lifetime. 💀
  • --deletestate state-number — the deletestate form deletes the state object with the specified serial number. this is useful for selectively deleting instances of connections. 👑

The route form of the whack command tells pluto to set up routing for a connection. although 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 will be installed; if outbound traffic is caught, Pluto will initiate the connection. an explicit whack route is not 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 will be 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). currently whack simply 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 will cause 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-ike --name connection --asynchronous and --rekey-child --name connection --asynchronous — initiate a rekey of the connection's established IKE or Child SA. 🔑
  • --delete-ike --name connection --asynchronous, --delete-child --name connection --asynchronous, --down-ike --name connection --asynchronous, --down-child --name connection --asynchronous — initiate a delete of the connection's established IKE or Child SA. for --down-ike and --down-child first clear connection's UP policy. 🗑️
    • deleting an IKE SA implicitly deletes all the IKE SA's children (IKEv2)
    • any affected connection with policy UP will try to revive (for --down-ike and --down-child, since the connection's UP policy was cleared, will not revive)

Ending a connection 💔

  • --delete --name connection — delete the specified connection. any negotiating or established SAs are terminated. any routing is removed. bye bye 👋
  • --down --name connection --asynchronous — delete any Child SAs associated with the connection, and remove UP from the connection's policy (so the connection is no longer required to stay up). if the connection has an IKE SA that is not not shared with other connections then that is also is deleted. since the connection is still in place --down does not prevent new negotiations. for instance, the peer may initiate, or a routed (on-demand) connection will initiate when there is traffic. --unroute will also prevent traffic initiating the connection, and --delete will prevent all negotiation. 😴
  • --crash ip-address — if the remote peer has crashed, and therefore did not notify us, we keep sending encrypted traffic, and rejecting all plaintext (non-IKE) traffic from that remote peer. --crash brings our end down as well for all the known connections to the specified ip-address. 💥
  • ip-address — if the remote peer has crashed, and therefore did not notify us, we keep sending encrypted traffic, and rejecting all plaintext (non-IKE) traffic from that remote peer. --crash brings our end down as well for all the known connections to the specified ip-address. (yes, it's the same as above, bestie) 🙈

Redirecting clients can be done using IKEv2 redirect mechanism. 🔀

  • --global-redirect yes|no|auto — controls whether pluto will instruct remote peers to redirect IKE/Child SA's during IKE_SA_INIT. valid options are no, yes and auto, where auto means remote peers will be redirected if DDoS mode is active. 🎯
  • --global-redirect-to ip-address(es) — the destination, or a 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 not specified the mechanism will redirect all currently active peers. if specified, only the peers from connection connection_name will be redirected. 👑

The public key for informs pluto of the RSA public key for a potential peer. private keys must be kept secret, so they are 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 a FQDN) or through reverse lookup (if an IP address). note that there 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. ➕
  • --pubkeyrsa key — specifies the value of the RSA public key. it is a sequence of bytes as described in RFC 2537 "RSA/MD5 KEYs and SIGs in the Domain Name System (DNS)". it is base-64 encoded with the prefix 0s prepended. 🔐

The status form will display information about the internal state of pluto: information about each potential connection, about each state object, and about each shunt that pluto is managing without an associated connection. 📊

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

  • --status — to be documented. 📝

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

  • --trafficstatus — to be documented 📝

LOADING CONNECTIONS 📦

The connection form describes a potential connection to pluto. pluto needs to know what 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 is is willing to set up the proposed connection. 💭

Tip 🫶 It is also possible to add connections from the command line using addconn. the syntax is identical to ipsec.conf(5) with all options supported (since Libreswan version 5.3). ✨

The description of a potential connection can specify a large number of details. each connection has a unique name. this name will appear in a updown shell command, so it should not contain punctuation that would make the command ill-formed. 🚫

  • --name connection-name — sets the name of the connection. 🏷️

The topology of a connection is symmetric, so to save space here is half a picture: 🖼️

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

A similar trick is used in the flags. the same flag names are used for both ends. those before the --to flag describe the left side and those afterwards describe the right side. when pluto attempts to use the connection, it decides whether it is the left side or the right side of the connection, based on the IP numbers of its interfaces. 🔄

  • --id id — the identity of the end. currently, this can be an IP address (specified as dotted quad or as a Fully Qualified Domain Name, which will be resolved immediately) or as a Fully Qualified Domain Name itself (prefixed by @ to signify that it should not be resolved), or as user@FQDN, or an X.509 DN. pluto only authenticates the identity, and does not use it for addressing, so, for example, an IP address need not be the one to which packets are to be sent. if the option is absent, the identity defaults to the IP address specified by --host. 🆔
  • --host ip-address, --host %any, --host %opportunistic — this is the IP of the end, which is usually the public interface tbh. If pluto is gonna be a responder for IKE negotiations that come from IPs nobody knows yet (the iconic "Road Warrior" case 👑), write it as %any (and yes, the ancient obsolete notation 0.0.0.0 still gets accepted for this, we don't talk about it 💀). But if pluto should opportunistically initiate the connection, hit it with %opportunistic.
  • --cert friendly_name — the friendly_name (aka the nickname 💫) of the X.509 certificate that you used back when you imported it into the NSS database. Wanna know how to yank that name out of the PKCS#12 file? See ipsec.conf(5), bestie, it's all there.
  • --ckaid CKAID — the CKAID of the X.509 certificate or the host key.

For X.509 certs, the CKAID is either the certificate's SubjectKeyIdentifier, or — when there's no SubjectKeyIdentifier specified — the SHA1 fingerprint of the public key. For host keys, the CKAID is the SHA1 fingerprint of the public key. That's it, that's the tea ☕

  • --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, plus the certificate of the incoming client. Both. Yeah. 🫶
  • --groups access control groups — the access control groups being used.
  • --sendcert yes|forced|always|ifasked|no|never — do we send our X.509 certificate credentials or not? Careful tho: this could hand an attacker way too much info about which identities are allowed to connect to this host. Default behavior: we use ifasked when we're a Responder, and we use yes (which is literally the same thing as forced and always) when we're an Initiator. And no and never? Totally equivalent twins.
NOTE: forced doesn't actually seem to be implemented — do not use it. Not even a little. 🙈
  • --sendca none|issuer|all — how much of our available X.509 trust chain do we send alongside the end certificate? (Root CAs are excluded, btw.) issuer sends just the issuing intermediate CA, all sends the entire chain of intermediate CAs, and none sends no CA certs at all. Default is none, which keeps things in line with current libreswan behavior. ✨
  • --certtype number — the X.509 certificate type number.
  • --send-supported-auth-methods — should we send the SUPPORTED_AUTH_METHODS notification to the remote peer? When this is enabled, our locally supported authentication methods get announced in the IKE_SA_INIT response and the IKE_AUTH request, so the peer can pick a compatible method before it even sends its AUTH payload. So considerate 💅. Default is no.
  • --ikeport port-number — the UDP port that IKE listens to on that host. Default is 500. (Heads up: pluto on this machine uses the port from its own command line argument, so this option only affects where pluto sends messages. One-way trip, no cap.)
  • --nexthop ip-address — where to route packets for the peer's client (presumably for the peer too, but nope, it won't be used for that). When pluto installs an IPsec SA, it fires off a route command and uses the nexthop as the gateway. The default is the peer's IP address (you can write that explicitly as %direct, and the obsolete notation 0.0.0.0 is accepted too). You need this option if pluto's host's interface for sending packets to the peer is neither point-to-point nor directly connected to the peer.
  • --subnet subnet, --client subnet — the subnet that the IPsec traffic will be destined for. Don't specify it and the host becomes the client. You can write the subnet in the general form address/mask, and the comfiest mask form is a decimal integer = the number of leading one bits in the mask. So like, 10.0.0.0/8 specifies the class A network "Net 10". Slay. 🎀
  • --clientprotoport protocol/port — specifies the Port Selectors (filters) used on this connection. General form is protocol/port. This is most commonly used to limit a connection to L2TP traffic only by specifying 17/1701 for UDP (protocol 17) and port 1701. And the notation 17/%any allows all UDP traffic, which you need for L2TP connections with Windows XP machines before Service Pack 2. (XP. Service Pack 2. We're in the archives, bestie 💀)
  • --narrowing yes|no|auto — IKEv2 (RFC5996) Section 2.9 Traffic Selector narrowing options. Go read the narrowing entry in ipsec.conf(5) for the full lore.
  • --sourceip ip-address — the IP address this host uses when transmitting a packet to the remote IPsec gateway itself. This option makes the gateway use its internal IP, which is part of the --client subnet. Otherwise it'd use its nearest IP address — which is its public IP address — which is not part of the subnet-subnet IPsec tunnel, and therefore wouldn't get encrypted. Sneaky but it's giving necessary. 💅
  • --xauthserver — this end is an xauthserver. It'll look up the xauth user name and password and verify it before letting the connection get established. Gatekeeping, but make it secure. 🔥
  • --xauthclient — this end is an xauthclient. To bring this connection up with --initiate, the client also has to specify --xauthuser username and --xauthpass password.
  • --xauthuser — the username for the xauth authentication. This option is normally passed along by ipsec-up(8) when an xauth connection is started using ipsec up connection.
  • --xauthpass — the password for the xauth authentication. This option is normally passed along by ipsec-up(8) when an xauth connection is started using ipsec up connection.
  • --modecfgserver — this end is a Mode Config server.
  • --modecfgclient — this end is a Mode Config client.
  • --modecfgdns — a comma separated list of DNS server IP's to pass along to connecting clients.
  • --modecfgdomains — a comma separated list of internal DNS domains to pass along to connecting clients.
  • --dnskeyondemand — says that when an RSA public key is needed to authenticate this host and it isn't already known, go fetch it from DNS. Manifesting it, essentially ✨
  • --updown updown — specifies an external shell command to run whenever pluto brings a connection up or down. The script is used to build a shell command, so it may contain positional parameters, but it ought not to have punctuation that would make the resulting command ill-formed. The default is ipsec _updown. And pluto passes like a dozen environment variables about the connection to the script. A dozen!! 🌈
  • --to — separates the specification of the left and right ends of the connection. Pluto tries to figure out whether it's left or right based on the info you gave it on both sides of this option. Detective mode 🕵️

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

  • --psk — propose and allow preshared secret authentication for IKE peers. This auth requires each side to use the same secret. May be combined with --rsasig; at least one of them must be specified.
  • --rsasig — propose and allow RSA signatures for authentication of IKE peers. This auth requires each side to have a private key of its own and to 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. And note that this has nothing to do with IKE authentication, okay? Different thing entirely.
  • --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 get 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 — they do not mix, periodt).
  • --ipv6 — the host addresses (including nexthop) get interpreted as IPv6 addresses. Note that for a connection, all host addresses must be of the same Address Family (again: IPv4 and IPv6 use different Address Families).
  • --tunnelipv4 — the client addresses get interpreted as IPv4 addresses. The default is to match whatever the host will be. This does not imply --tunnel, so the flag is safe to use even 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 get interpreted as IPv6 addresses. The default is to match whatever the host will be. This does not imply --tunnel, so the flag is safe to use even when no tunnel is actually specified. Note that for a connection, all tunnel addresses must be of the same Address Family.
  • --pfs — there should be Perfect Forward Secrecy, meaning brand new keying material gets generated for each IPsec SA when running Quick Mode in IKEv1 or Create Child in IKEv2. Without this option, the SAKMP SA keying material is used instead. And pluto will propose the same group that was used with the original IKE SA. Fresh keys, main character energy 👑
  • --ike ike-proposals, --esp esp-proposals, --ah ah-proposals — the algorithms to propose and accept when negotiating either an IKE (ISAKMP) SA or a Child (IPsec) SA. See ipsec.conf(5) for a detailed description of the proposal format. (It's detailed. Very detailed. Go read it.)
  • --aggrmode — this tunnel is using aggressive mode ISAKMP negotiation. The default is main mode. And ngl, aggressive mode is less secure than main mode because it reveals your identity to an eavesdropper — but you need it to support road warriors using PSK keys, or to interoperate with other buggy implementations that insist on using aggressive mode. 🙈
  • --modecfgpull — pull the Mode Config network information from the peer.
  • --dpddelay seconds — set 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 — set the length of time (in seconds) we'll idle without hearing either an R_U_THERE poll from our peer or an R_U_THERE_ACK reply. Once this period elapses with no response and no traffic, we declare the peer dead and remove the SA. Default is 120 seconds. 💀
  • --encapsulation yes|no|auto — okay so sometimes you just gotta force the vibe</p> ✨. Say ESP packets are getting filtered, or a broken IPsec peer is out here ✨refusing✨ to recognise NAT — that's when you reach for this. It makes pluto straight-up lie to the remote peer and tell them that RFC-3948 encapsulation (aka ESP in UDP port 4500 packets, iykyk) is required. 🫶

Real talk: if none of --encrypt, --authenticate, --compress, or --pfs is given, then whoever's initiating the connection will only build an ISAKMP SA. And for a connection like that, client subnets literally have no meaning — you must not specify them. Periodt. 💅

Other than initiating straight up with the --initiate option, a tunnel can be loaded with a different policy. That's the whole flex. 🎀

  • --initiateontraffic — only initiate the connection when we actually have traffic we wanna send over it. No traffic, no drama. 🌸
  • --pass — let unencrypted traffic flow on through until the tunnel gets initiated. yeah, it's naked traffic, we know 🙈
  • --drop — drop unencrypted traffic silently. not a word. 💀
  • --reject — drop unencrypted traffic silently but send an ICMP message telling the other end what happened. it's giving ghosting-with-a-read-receipt. 😭

These options need to be documented (not me, bestie, the docs):

  • --failnone — To be documented.
  • --failpass — To be documented.
  • --faildrop — To be documented.
  • --failreject — To be documented.

🦋 Examples 🦋

It would be normal to start pluto in one of the system initialization scripts, bestie. It needs to be run by the superuser (👑 root only, no exceptions). Generally? No arguments needed. To run it manually the superuser can simply type:

ipsec pluto

The command will return immediately, but a pluto process will be left running, just chilling, waiting for requests from whack or from a peer. 🫶

Using whack, several potential connections get described:

ipsec whack --name silly --host127.0.0.1 --to --host 127.0.0.2
--ikelifetime 900 --ipseclifetime 800

Since this silly connection description specifies neither encryption, authentication, nor tunneling, it could only be used to establish an ISAKMP SA. It's a baby connection. 🍼

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. And if the other side is pluto, the same whack command could be used on it — the command syntax is literally designed so it doesn't distinguish which end is ours. symmetry, iconic. ✨

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; and if there is no SA, they will simply be discarded. 🗑️

ipsec whack --route conn_name

Finally — the moment we've all been waiting for — we're 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, yeah, the whole thing is lowkey unhinged. 💀

🔐 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 — you, at a terminal, typing. main character energy. ⌨️ 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. 🧚

🔁 Rekeying 🔁

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 both ISAKMP and IPsec SAs. The rekeying kicks off when the SA's remaining lifetime is less than the rekeymargin plus a random percentage — between 0 and rekeyfuzz — of the rekeymargin. 🎲

Similarly, when an SA that was initiated by the peer has only a bit of lifetime left, pluto will try to initiate the creation of a replacement. But to give preference to the initiator, this rekeying will only be initiated when the SA's remaining lifetime is half of rekeymargin. If rekeying is done by the responder, the roles get reversed: the responder for the old SA will be 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 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 haven't been used in a successful negotiation, after all). To reduce the chances of that happening — and to prevent loss of security — the policy settings are taken from the old SA (and yes, this is the case even if the former initiator is the one initiating). 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. This avoids creating redundant SAs. no duplicates in this group chat. 🙅

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

Another, more important case occurs when a security gateway has SAs with many other security gateways. Each of these connections might need to be rekeyed at the same time. That would cause a high peak requirement for resources (network bandwidth, CPU time, entropy for random numbers). The rekeyfuzz can be used to stagger the rekeying times. 🌈

Once a new set of SAs has been negotiated, pluto will never send traffic on a superseded one. Traffic will be accepted on an old SA until it expires. that's the rule, bestie. 💅

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

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 got assigned a dynamic IP address for other reasons). We call this situation "Road Warrior" 🛣️. It is fairly tricky and has some important limitations — most of which are features of the IKE protocol, so don't come for pluto about it.

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. After all, the real IP address was apparently unknown to the configuration, so it is 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. 💀

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. This 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 (which uses the responder's private key, so that one 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. periodt. 🎀

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; 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. manual labour, 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 literally cannot reject an exchange initiated by an unknown host until it has determined that the secret is not shared or the signature is invalid. 😬 That means it has to wait for the third Main Mode message from the initiator. But if no Road Warrior connection is supported, the very first message from an unknown source would get rejected immediately. This has implications for ease of debugging configurations and for denial of service attacks. 🫠

And bestie, even though 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. 💅

🌸 Miscellaneous Options 🌸

  • --interface interfacename — Says that the named real public network interface should be considered. 🫶 The interface name you specify should not be ipsecN. If the option doesn't appear, all interfaces are considered. Wanna 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). 🔌
  • --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). Also, 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 — If this option has been selected, pluto will be forced to be "busy". In this state, which happens when there is a Denial of Service attack, will force pluto to use cookies before accepting new incoming IKE packets. Cookies are send and required in ikev1 Aggressive Mode and in ikev2. 🍪 This option is mostly used for testing purposes, but can be selected by paranoid administrators as well.
  • --stderrlog — Log goes to standard out (default is to use syslogd(8)). 📢

🔍 Debugging 🔍

whack accepts the --debug to control the level of debugging enabled within pluto:

  • --debug help (whack only) — List the debugging classes recognised by pluto. 📋
  • --debug class, --no-debug class, --debug no-class — Enable (disable) logging of the specified debugging class within pluto. 🔥

For more details, see plutodebug= in ipsec.conf(5).

🙈 Impairing 🙈

pluto and whack accept several optional arguments that alter (impair) correct behaviour. 😭

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

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

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 chose 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 Group MODP 1536 (5) is supported. Groups MODP768 and MODP 1024 (1 and 2) are not supported because those are too weak. 💪
  • Host authentication can be done by RSA Signatures or Pre-Shared Secrets. 🔑
  • TODO! This information is outdated. 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. 🤝

🌈 EXIT STATUS 🌈

If ipsec 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 📁

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

🌱 ENVIRONMENT 🌱

pluto does not use any environment variables. nope, none, zero, nada 🫶

🦋 SEE ALSO 🦋

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

ipsec(8) is designed to make using pluto more pleasant. Use it! 💅

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

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.

The --pfsgroup was removed in Libreswan version 5.3. Both --ike and --esp have supported compound proposals since version 4.0. See ipsec.conf(5). 👋

🐛 BUGS 🐛

Please see <https://github.com/libreswan/libreswan/issues> for a list of currently known bugs and missing features. 🕷️

Bugs should be reported to the <swan-dev@lists.libreswan.org> mailing list. 📬

💖 AUTHOR 💖

Andrew Cagney, Antony Antony, Daniel Kahn Gillmor, D. Hugh Redelmeier, Harald Jenny, Jose Quaresma, Matt Rogers, Max-Julian Pogner, Michael Richardson, Paul Wouters, Pietro Monteiro, Simon Deziel, Tuomo Soini, Vukasin Karadzic 👑

okay bestie that's literally the whole page, we ate and left no crumbs 🍓 This is Libreswan 5.4.1, dated 10/23/2026, and it's the IPSEC-WHACK(8) page — go forth and whack responsibly, no cap 💅✨

📦 where this page comes from