Paul Wouters

placeholder to suppress warning

IPSEC_AUTO 8 25 Oct 2006 libreswan Executable programs
ipsec auto control automatically-keyed IPsec connections
`ipsec` auto --show --showonly --asynchronous
--config configfile --verbose operation connection
`ipsec` auto --show --showonly --asynchronous
--config configfile --verbose operation connection

## EXAMPLES

`ipsec` auto { --add | --delete | --replace | --up | --down } connection `ipsec` auto { --status | --ready } connection `ipsec` auto { --route | --unroute } connection `ipsec` auto --utc --listall | --rereadall --rereadsecrets --listcerts --listpubkeys --checkpubkeys --listcacerts | --rereadcacerts --listcrls | --rereadcrls --listacerts | --rereadacerts --listaacerts | --rereadaacerts --listgroups | --rereadgroups

## 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`, `--up`, `--down`, `--route`, or `--unroute`. 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); it will fail if the specification does not exist. The `--replace` operation is equivalent to `--delete` (if there is already a specification 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 `--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 and only 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 `--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 `--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 `--rereadcacerts` operation reads all certificate files contained in the /etc/ipsec.d/cacerts directory and adds them to pluto’s list of Certification Authority (CA) certificates.

The `--rereadaacerts` operation reads all certificate files contained in the /etc/ipsec.d/aacerts directory and adds them to pluto’s list of Authorization Authority (AA) certificates.

The `--rereadacerts` operation reads all certificate files contained in the /etc/ipsec.d/acerts directory and adds them to pluto’s list of attribute certificates.

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.

The `--rereadall` operation is equivalent to the execution of --rereadse- crets, `--rereadcacerts,` --rereadaacerts, --rereadac- erts, 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).

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 either loaded locally from the /etc/ipsec.d/cacerts directory or received in PKCS#7-wrapped certificate payloads via the IKE protocol.

The `--listaacerts` operation lists all X.509 AA certificates loaded locally from the /etc/ipsec.d/aacerts directory.

The `--listacerts` operation lists all X.509 attribute certificates loaded locally from the /etc/ipsec.d/acerts directory.

The `--listgropus` 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 `--listcainfos` operation lists the certification authority informa- tion specified in the ca sections of ipsec.conf(5).

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, --listaacerts, --listoc- spcerts, --listacerts, --listgroups, --listcainfos, --listcrls.

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 `--show` option turns on the `-x` option of the shell used to execute the commands, so each command is shown as it is executed.

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
    /etc/ipsec.d/			X.509 and Opportunistic Encryption files
    /var/run/pluto/pluto.ctl	Pluto command socket

## SEE ALSO

ipsec.conf 5, ipsec 8, ipsec_pluto 8, ipsec_whack 8, ipsec_manual 8

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