Ubuntu Manpage: ipsec_auto - control automatically-keyed IPsec connections

NAME

       ipsec_auto - control automatically-keyed IPsec connections

SYNOPSIS

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

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

EXAMPLES

       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] [--listcrls | --rereadcrls]
             [--listgroups | --rereadgroups] [--purgeocsp]

DESCRIPTION

Auto manipulates automatically-keyed Libreswan IPsec connections, setting them up and
shutting them down based on the information in the IPsec configuration file. In the normal
usage, connection is the name of a connection specification in the configuration file;
operation is --add, --delete, --replace, --start, --up, --down, --route, --unroute, or
--ondemand. The --ready, --rereadsecrets, --rereadgroups, 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 --rereadgroups operation causes any changes to the policy group files to
take effect (this is currently a synonym for --ready, but that may change). None of the
other operations alters the internal database.

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 (for KLIPS) and packet capture (KLIPS and
NETKEY) 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 (KLIPS) or packet capture (NETKEY) 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.

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 --rereadcrls operation reads all certificate revocation list (CRL) files contained in
the /etc/ipsec.d/crls directory and adds them to pluto's list of CRLs. Note CRLs can and
should be stored inside NSS instead of in the /etc/ipsec.d/crls directory which will
result in automatic updates. This option will be obsoleted in the near future.

The --rereadall operation is equivalent to the execution of --rereadsecrets and
--rereadcrls.

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 rightr- sasigkey / 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 which are about to expire
or have been expired.

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

The --listgroups operation lists all groups that are either used in connection definitions
in ipsec.conf(5) or are embedded in loaded X.509 attributes certificates.

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

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 <http://www.freeswan.org> by Henry Spencer.

BUGS

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