IPSEC_AUTO(8) IPSEC_AUTO(8)
NAME
ipsec(5,8) auto(5,8) - control automatically-keyed IPsec connections
SYNOPSIS
ipsec(5,8) auto(5,8) [ --show ] [ --showonly ] [ --asynchronous ]
[ --config configfile ] [ --verbose ]
operation connection
ipsec(5,8) auto(5,8) [ --show ] [ --showonly ] operation
DESCRIPTION
Auto manipulates automatically-keyed FreeS/WAN IPsec connections, set-
ting them up and shutting them down based on the information in(1,8) the
IPsec configuration file. In the normal usage, connection is the name
of a connection specification in(1,8) the configuration file(1,n); 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(3,n) pluto already has a specifica-
tion by that name. The --delete operation deletes a connection speci-
fication from pluto's internal database (also tearing down any connec-
tions based on it); it will fail if(3,n) the specification does not exist.
The --replace operation is equivalent to --delete (if(3,n) there is already
a specification by the given name) followed by --add, and is a conve-
nience for updating pluto's internal specification to match an external
one. (Note that a --rereadsecrets may also be needed.) The --reread-
groups 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(1,8) 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(1,8) place when a --down
operation is used to take the connection down (or if(3,n) connection setup(2,8),
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(1,8) 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(1,2,7) 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(1,n), which it normally reads only at
startup time. (This is currently a synonym for --ready, but that may
change.)
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 --showonly option causes auto(5,8) 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 connec-
tions in(1,8) parallel when network links are slow.
The --verbose option instructs auto(5,8) 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(1,n) (default /etc/ipsec.conf).
See ipsec.conf(5) for details of the configuration file. Apart from
the basic parameters which specify the endpoints and routing of a con-
nection (left and right, plus possibly leftsubnet, leftnexthop, left-
firewall, their right equivalents, and perhaps type), an auto(5,8) connec-
tion almost certainly needs a keyingtries parameter (since the key-
ingtries default is poorly chosen).
FILES
/etc/ipsec.conf default IPSEC configuration file(1,n)
/var/run/ipsec.info %defaultroute information
SEE ALSO
ipsec.conf(5), ipsec(5,8)(8), ipsec_pluto(8), ipsec_whack(8), ipsec_man-
ual(8)
HISTORY
Written for the FreeS/WAN project <http://www.freeswan.org> by Henry
Spencer.
BUGS
Although an --up operation does connection setup(2,8) on both ends, --down
tears only one end of the connection down (although the orphaned end
will eventually time(1,2,n) out).
There is no support for passthrough connections.
A connection description which uses %defaultroute for one of its nex-
thop parameters but not the other may be falsely rejected as erroneous
in(1,8) some circumstances.
The exit(3,n,1 builtins) 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(1,8) scripts.)
31 Jan 2002 IPSEC_AUTO(8)