IPSEC_AUTO(8)

📦

version 4.15 · 4 versions

💅 IPSEC_AUTO(8) — the `ipsec_auto` page, but make it make sense

okay bestie, this is the manual page for ipsec_auto, and it lives in the Executable programs section. It's giving "control panel for your automatically-keyed IPsec connections," and honestly? Once you get the vibe, it's lowkey iconic. Let's go 🎀

✨ SYNOPSIS ✨

ipsec auto [--showonly] [--asynchronous]
      [--config configfile] [--verbose] operation connection

ipsec auto [--showonly] [--asynchronous]
      [--config configfile] [--verbose] operation connection

(yes, the synopsis is listed twice on the page — that's not me glitching, that's canon 💀)

🌸 EXAMPLES 🌸

Like, here are literally the forms the page hands you:

ipsec auto { --add | --delete | --replace | --start } connection

ipsec auto { --up | --down } connection

ipsec auto { --route | --unroute | --ondemand } connection

ipsec auto { --status | --ready }

ipsec auto [--utc] [--listall | --rereadall] [--rereadsecrets]
      [--listcerts] [--listpubkeys] [--checkpubkeys] [--listcacerts]
      [--fetchcrls] [--listcrls] [--purgeocsp]

ipsec auto [--utc] [--rereadcerts] connection

🦋 DESCRIPTION 🦋

So auto manipulates automatically-keyed Libreswan IPsec connections — setting them up and shutting them down based on whatever's chillin' in the IPsec configuration file. In normal usage, connection is the name of a connection specification in the configuration file, and operation is --add, --delete, --replace, --start, --up, --down, --route, --unroute, --ondemand. The --ready, --rereadsecrets, and --status operations do not take a connection name. Auto generates suitable commands and feeds them to a shell for execution. 💅

The --add operation adds a connection specification to the internal database within pluto; it will fail if pluto already has a specification by that name. The --delete operation deletes a connection specification from pluto's internal database (also tearing down any connections based on it). The --replace operation is equivalent to --delete (if there is already a loaded connection by the given name) followed by --add, and is a convenience for updating pluto's internal specification to match an external one. (Note that a --rereadsecrets may also be needed.) The --start operation is equivalent to running first with --add and then with --up, causing same effect as connection configuration option auto=start. ⭐

The --up operation asks pluto to establish a connection based on an entry in its internal database. The --down operation tells pluto to tear down such a connection.

Normally, pluto establishes a route to the destination specified for a connection as part of the --up operation. However, the route can be established with the --route operation. Until and unless an actual connection is established, this discards any packets sent there — which may be preferable to having them sent elsewhere based on a more general route (e.g., a default route). 🛣️

Normally, pluto's route to a destination remains in place when a --down operation is used to take the connection down (or if connection setup, or later automatic rekeying, fails). This permits establishing a new connection (perhaps using a different specification; the route is altered as necessary) without having a “window” in which packets might go elsewhere based on a more general route. Such a route can be removed using the --unroute operation (and is implicitly removed by --delete). 👑

The --ondemand operation is equivalent to running first with --add and then with --route, causing same effect as connection configuration option auto=ondemand.

The --ready operation tells pluto to listen for connection-setup requests from other hosts. Doing an --up operation before doing --ready on both ends is futile and will not work, although this is now automated as part of IPsec startup and should not normally be an issue. 🙈

The --status operation asks pluto for current connection status. The output format is ad-hoc and likely to change. (so don't build your whole personality around parsing it, k?)

The --rereadsecrets operation tells pluto to re-read the /etc/ipsec.secrets secret-keys file, which it normally reads only at startup time. (This is currently a synonym for --ready, but that may change.) 🔐

The --fetchcrls operation reads all certificate revocation list (CRL) entries of loaded certificates and tries to fetch updates for these from the CRL servers.

The --rereadall operation is equivalent to the execution of --rereadsecrets (in the past there were other kinds of reread operations).

The --listpubkeys operation lists all RSA public keys either received from peers via the IKE protocol embedded in authenticated certificate payloads or loaded locally using the rightcert / leftcert or rightrsasigkey / leftrsasigkey parameters in ipsec.conf(5). 🗝️

The --listcerts operation lists all X.509 certificates loaded locally using the rightcert and leftcert parameters in ipsec.conf(5). To see all certificates in the NSS database, use certutil -d /var/lib/ipsec/nss -L.

The --checkpubkeys operation lists all loaded X.509 certificates that are about to expire or have expired. ⏰

The --listcacerts operation lists all X.509 CA certificates contained in the NSS database.

The --listcrls operation lists all Certificate Revocation Lists (CRLs) either loaded locally from the /etc/ipsec.d/crls directory or fetched dynamically from an HTTP or LDAP server.

The --listall operation is equivalent to the execution of --listpubkeys, --listcerts, --listcacerts, --listcrls.

The --purgeocsp operation displays --listall and purges the NSS OCSP cache. 🧹

The --showonly option causes auto to show the commands it would run, on standard output, and not run them.

The --asynchronous option, applicable only to the up operation, tells pluto to attempt to establish the connection, but does not delay to report results. This is especially useful to start multiple connections in parallel when network links are slow. 🔥

The --verbose option instructs auto to pass through all output from ipsec_whack(8), including log output that is normally filtered out as uninteresting.

The --config option specifies a non-standard location for the IPsec configuration file (default /etc/ipsec.conf).

See ipsec.conf(5) for details of the configuration file.

🎀 OPTIONS 🎀

--showonly — shows you the commands it would run, straight to standard output, and then does not run them. window-shopping for shell commands, basically 🛍️
--asynchronous — only applies to the up operation: tells pluto to attempt to establish the connection but not delay to report results. Obsessed for starting multiple connections in parallel when network links are slow.
--verbose — passes through all output from ipsec_whack(8), including the log output that's normally filtered out as uninteresting. yap mode: enabled 💬
--config configfile — points at a non-standard location for the IPsec configuration file (default /etc/ipsec.conf).
--utc — ngl the page only ever shows this one in the synopsis/EXAMPLES lines above, so that's exactly where it lives: ipsec auto [--utc] [--listall | --rereadall] [--rereadsecrets] [--listcerts] [--listpubkeys] [--checkpubkeys] [--listcacerts] [--fetchcrls] [--listcrls] [--purgeocsp] and ipsec auto [--utc] [--rereadcerts] connection. no extra lore given, don't @ me 💀

🫶 OPERATIONS, RUNDOWN STYLE 🫶

--add — drops a connection specification into the internal database within pluto. Fails if pluto already has a spec by that name.
--delete — removes a connection specification from pluto's internal database, and also tears down any connections based on it.
--replace — equivalent to --delete (if there's already a loaded connection by the given name) followed by --add. It's the convenience move for updating pluto's internal spec to match an external one. (a --rereadsecrets may also be needed, bestie.)
--start — equivalent to running first with --add and then with --up, causing same effect as the connection configuration option auto=start.
--up — asks pluto to establish a connection based on an entry in its internal database.
--down — tells pluto to tear down such a connection.
--route — establishes the route to the destination without the full --up dance.
--unroute — removes that route.
--ondemand — equivalent to running first with --add and then with --route, causing same effect as the connection configuration option auto=ondemand.
--ready — tells pluto to listen for connection-setup requests from other hosts. Takes no connection name.
--status — asks pluto for current connection status. Output format is ad-hoc and likely to change. Takes no connection name.
--rereadsecrets — tells pluto to re-read /etc/ipsec.secrets, which it normally reads only at startup time. Currently a synonym for --ready, but that may change. Takes no connection name.
--rereadall — equivalent to the execution of --rereadsecrets (in the past there were other kinds of reread operations).
--fetchcrls — reads all CRL entries of loaded certificates and tries to fetch updates for these from the CRL servers.
--listpubkeys — lists all RSA public keys either received from peers via the IKE protocol embedded in authenticated certificate payloads, or loaded locally using the rightcert / leftcert or rightrsasigkey / leftrsasigkey parameters in ipsec.conf(5).
--listcerts — lists all X.509 certificates loaded locally using the rightcert and leftcert parameters in ipsec.conf(5). To see all certificates in the NSS database, use certutil -d /var/lib/ipsec/nss -L.
--checkpubkeys — lists all loaded X.509 certificates that are about to expire or have expired.
--listcacerts — lists all X.509 CA certificates contained in the NSS database.
--listcrls — lists all CRLs either loaded locally from /etc/ipsec.d/crls or fetched dynamically from an HTTP or LDAP server.
--listall — equivalent to the execution of --listpubkeys, --listcerts, --listcacerts, --listcrls.
--purgeocsp — displays --listall and purges the NSS OCSP cache.

🌈 FILES 🌈

/etc/ipsec.conf — default IPSEC configuration file
/var/lib/ipsec/nss — X.509 and Opportunistic Encryption files
/var/run/pluto/pluto.ctl — Pluto command socket

💜 HISTORY 💜

Originally written for the FreeS/WAN project https://www.freeswan.org by Henry Spencer. vintage. iconic. we respect the lineage 🫡

💀 BUGS 💀

Real talk, these are the rough edges, keep them in mind fr fr:

Although an --up operation does connection setup on both ends, --down tears only one end of the connection down (although the orphaned end will eventually time out).
There is no support for passthrough connections.
A connection description that uses %defaultroute for one of its nexthop parameters but not the other may be falsely rejected as erroneous in some circumstances.
The exit status of --showonly does not always reflect errors discovered during processing of the request. (This is fine for human inspection, but not so good for use in scripts. 😭)

🌸 AUTHOR 🌸

Paul Wouters placeholder to suppress warning

aaaand that's the page, bestie 🧚 this whole thing shipped as libreswan, dated 10/19/2026 — go forth and key your connections automatically, periodt 💅✨

📦 where this page comes from

centos-stream 9: libreswan 4.15-11.el9 · GPLv2
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms