NAME

       ipsec_auto - control automatically-keyed IPsec connections

SYNOPSIS

       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] [[--listocspcerts | --rereadocspcerts ] [--listocsp | --purgeocsp ]]
             [--listacerts | --rereadacerts] [--listaacerts | --rereadaacerts] [--listgroups |
             --rereadgroups]

DESCRIPTION

       Auto manipulates automatically-keyed Openswan 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 --rereadocspcerts operation reads all certificate files contained in the
       /etc/ipsec.d/ocspcerts directory and adds them to pluto’s list of OCSP signer
       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, --rereadocspcerts, --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 --listocspcerts operation lists all OCSP signer certificates either loaded locally
       from the /etc/ipsec.d/ocspcerts directory or received via the Online Certificate Status
       Protocol from an OCSP server.

       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 --listocsp operation lists the certicates status information fetched from OCSP
       servers.

       The --purgeocsp operation deletes any cached certificate status infor- mation and pending
       OCSP fetch requests.

       The --listall operation is equivalent to the execution of --listpubkeys, --listcerts,
       --listcacerts, --listaacerts, --listoc- spcerts, --listacerts, --listgroups,
       --listcainfos, --listcrls, --lis- tocsp.

       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/ipsec.info     %defaultroute information
           /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.)

[FIXME: source]                             07/25/2011                              IPSEC_AUTO(8)