.TH IPSEC_AUTO 8 "31 Jan 2002"
.\" RCSID $Id: auto.8,v 1.41 2003/01/09 08:36:57 dhr Exp $
.SH NAME
ipsec auto \- control automatically-keyed IPsec connections
.SH SYNOPSIS
.B ipsec
.B auto
[
.B \-\-show
] [
.B \-\-showonly
] [
.B \-\-asynchronous
]
.br
\ \ \ [
.B \-\-config
configfile
] [
.B \-\-verbose
]
.br
\ \ \ operation
connection
.sp
.B ipsec
.B auto
[
.B \-\-show
] [
.B \-\-showonly
] operation
.SH DESCRIPTION
.I Auto
manipulates automatically-keyed FreeS/WAN IPsec connections,
setting them up and shutting them down
based on the information in the IPsec configuration file.
In the normal usage,
.I connection
is the name of a connection specification in the configuration file;
.I operation
is
.BR \-\-add ,
.BR \-\-delete ,
.BR \-\-replace ,
.BR \-\-up ,
.BR \-\-down ,
.BR \-\-route ,
or
.BR \-\-unroute .
The
.BR \-\-ready ,
.BR \-\-rereadsecrets ,
.BR \-\-rereadgroups ,
and
.BR \-\-status
.I operations
do not take a connection name.
.I Auto
generates suitable
commands and feeds them to a shell for execution.
.PP
The
.B \-\-add
operation adds a connection specification to the internal database
within
.IR pluto ;
it will fail if
.I pluto
already has a specification by that name.
The
.B \-\-delete
operation deletes a connection specification from
.IR pluto 's
internal database (also tearing down any connections based on it);
it will fail if the specification does not exist.
The
.B \-\-replace
operation is equivalent to
.B \-\-delete
(if there is already a specification by the given name)
followed by
.BR \-\-add ,
and is a convenience for updating
.IR pluto 's
internal specification to match an external one.
(Note that a
.B \-\-rereadsecrets
may also be needed.)
The
.B \-\-rereadgroups
operation causes any changes to the policy group files to take effect
(this is currently a synonym for
.BR \-\-ready ,
but that may change).
None of the other operations alters the internal database.
.PP
The
.B \-\-up
operation asks
.I pluto
to establish a connection based on an entry in its internal database.
The
.B \-\-down
operation tells
.I pluto
to tear down such a connection.
.PP
Normally,
.I pluto
establishes a route to the destination specified for a connection as
part of the
.B \-\-up
operation.
However, the route and only the route can be established with the
.B \-\-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).
.PP
Normally,
.IR pluto 's
route to a destination remains in place when a
.B \-\-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
.B \-\-unroute
operation
(and is implicitly removed by
.BR \-\-delete ).
.PP
The
.B \-\-ready
operation tells
.I pluto
to listen for connection-setup requests from other hosts.
Doing an
.B \-\-up
operation before doing
.B \-\-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.
.PP
The
.B \-\-status
operation asks
.I pluto
for current connection status.
The output format is ad-hoc and likely to change.
.PP
The
.B \-\-rereadsecrets
operation tells
.I pluto
to re-read the
.I /etc/ipsec.secrets
secret-keys file,
which it normally reads only at startup time.
(This is currently a synonym for
.BR \-\-ready ,
but that may change.)
.PP
The
.B \-\-show
option turns on the
.B \-x
option of the shell used to execute the commands,
so each command is shown as it is executed.
.PP
The
.B \-\-showonly
option causes
.I auto
to show the commands it would run, on standard output,
and not run them.
.PP
The
.B \-\-asynchronous
option, applicable only to the
.B up
operation,
tells
.I 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.
.PP
The
.B \-\-verbose
option instructs
.I auto
to pass through all output from
.IR ipsec_whack (8),
including log output that is normally filtered out as uninteresting.
.PP
The
.B \-\-config
option specifies a non-standard location for the IPsec
configuration file (default
.IR /etc/ipsec.conf ).
.PP
See
.IR ipsec.conf (5)
for details of the configuration file.
Apart from the basic parameters which specify the endpoints and routing
of a connection (\fBleft\fR
and
.BR right ,
plus possibly
.BR leftsubnet ,
.BR leftnexthop ,
.BR leftfirewall ,
their
.B right
equivalents,
and perhaps
.BR type ),
an
.I auto
connection almost certainly needs a
.B keyingtries
parameter (since the
.B keyingtries
default is poorly chosen).
.SH FILES
.ta \w'/var/run/ipsec.info'u+4n
/etc/ipsec.conf	default IPSEC configuration file
.br
/var/run/ipsec.info	\fB%defaultroute\fR information
.SH SEE ALSO
ipsec.conf(5), ipsec(8), ipsec_pluto(8), ipsec_whack(8), ipsec_manual(8)
.SH HISTORY
Written for the FreeS/WAN project
<http://www.freeswan.org>
by Henry Spencer.
.SH BUGS
Although an
.B \-\-up
operation does connection setup on both ends,
.B \-\-down
tears only one end of the connection down
(although the orphaned end will eventually time out).
.PP
There is no support for
.B passthrough
connections.
.PP
A connection description which uses
.B %defaultroute
for one of its
.B nexthop
parameters but not the other may be falsely
rejected as erroneous in some circumstances.
.PP
The exit status of
.B \-\-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.)