482 lines
10 KiB
Plaintext
482 lines
10 KiB
Plaintext
.TH IPSEC_AUTO 8 "17 December 2004"
|
|
.\" RCSID $Id: auto.8,v 1.6 2004/12/17 22:34:38 as 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
|
|
] [
|
|
.B \-\-type conn
|
|
]
|
|
.br
|
|
\ \ \ operation
|
|
connection
|
|
.sp
|
|
.B ipsec
|
|
.B auto
|
|
[
|
|
.B \-\-show
|
|
] [
|
|
.B \-\-showonly
|
|
]
|
|
.br
|
|
\ \ \ [
|
|
.B \-\-config
|
|
configfile
|
|
] [
|
|
.B \-\-verbose
|
|
]
|
|
.B \-\-type ca
|
|
.br
|
|
\ \ \ operation
|
|
ca
|
|
.sp
|
|
.B ipsec
|
|
.B auto
|
|
[
|
|
.B \-\-show
|
|
] [
|
|
.B \-\-showonly
|
|
] operation
|
|
.SH DESCRIPTION
|
|
.I Auto
|
|
manipulates automatically-keyed strongSwan 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 ca
|
|
is the name of a Certification Authority (CA) 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 \-\-status
|
|
and
|
|
.BR \-\-statusall
|
|
.I operations
|
|
may take a
|
|
.I connection
|
|
name.
|
|
The
|
|
.BR \-\-ready ,
|
|
.BR \-\-rereadsecrets ,
|
|
.BR \-\-rereadgroups ,
|
|
.BR \-\-rereadcacerts ,
|
|
.BR \-\-rereadaacerts ,
|
|
.BR \-\-rereadocspcerts ,
|
|
.BR \-\-rereadacerts ,
|
|
.BR \-\-rereadcrls ,
|
|
.BR \-\-rereadall ,
|
|
.BR \-\-listalgs ,
|
|
.BR \-\-listpubkeys ,
|
|
.BR \-\-listcerts ,
|
|
.BR \-\-listcacerts ,
|
|
.BR \-\-listaacerts ,
|
|
.BR \-\-listocspcerts ,
|
|
.BR \-\-listacerts ,
|
|
.BR \-\-listgroups ,
|
|
.BR \-\-listcainfos ,
|
|
.BR \-\-listcrls ,
|
|
.BR \-\-listocsp ,
|
|
.BR \-\-listcards ,
|
|
.BR \-\-listall ,
|
|
and
|
|
.BR \-\-purgeocsp
|
|
.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 or ca 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 or ca 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 either for all connections
|
|
(no connection argument) or a for specified
|
|
.I connection
|
|
name. For more detailed information use
|
|
.B \-\-statusall
|
|
\. 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 \-\-rereadcacerts
|
|
operation reads all certificate files contained in the
|
|
.IR /etc/ipsec.d/cacerts
|
|
directory and adds them to
|
|
.IR pluto 's
|
|
list of Certification Authority (CA) certificates.
|
|
.PP
|
|
The
|
|
.B \-\-rereadaacerts
|
|
operation reads all certificate files contained in the
|
|
.IR /etc/ipsec.d/aacerts
|
|
directory and adds them to
|
|
.IR pluto 's
|
|
list of Authorization Authority (AA) certificates.
|
|
.PP
|
|
The
|
|
.B \-\-rereadocspcerts
|
|
operation reads all certificate files contained in the
|
|
.IR /etc/ipsec.d/ocspcerts
|
|
directory and adds them to
|
|
.IR pluto 's
|
|
list of OCSP signer certificates.
|
|
.PP
|
|
The
|
|
.B \-\-rereadacerts
|
|
operation reads all certificate files contained in the
|
|
.IR /etc/ipsec.d/acerts
|
|
directory and adds them to
|
|
.IR pluto 's
|
|
list of attribute certificates.
|
|
.PP
|
|
The
|
|
.B \-\-rereadcrls
|
|
operation reads all certificate revocation list (CRL) files
|
|
contained in the
|
|
.IR /etc/ipsec.d/crls
|
|
directory and adds them to
|
|
.IR pluto 's
|
|
list of CRLs.
|
|
.PP
|
|
The
|
|
.B \-\-rereadall
|
|
operation is equivalent to the execution of
|
|
.BR \-\-rereadsecrets ,
|
|
.BR \-\-rereadcacerts ,
|
|
.BR \-\-rereadaacerts ,
|
|
.BR \-\-rereadocspcerts ,
|
|
.BR \-\-rereadacerts ,
|
|
and
|
|
.BR \-\-rereadcrls .
|
|
.PP
|
|
The
|
|
.B \-\-listalgs
|
|
operation lists all registed IKE encryption and hash algorithms,
|
|
that are available to
|
|
.IR pluto ,
|
|
as well as the Diffie-Hellman (DH) groups.
|
|
.PP
|
|
The
|
|
.B \-\-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
|
|
.BR rightcert \ /
|
|
.BR leftcert
|
|
or
|
|
.BR rightrsasigkey \ /
|
|
.BR leftrsasigkey
|
|
parameters in
|
|
.IR ipsec.conf (5).
|
|
.PP
|
|
The
|
|
.B \-\-listcerts
|
|
operation lists all X.509 and OpenPGP certificates loaded locally using the
|
|
.BR rightcert
|
|
and
|
|
.BR leftcert
|
|
parameters in
|
|
.IR ipsec.conf (5).
|
|
.PP
|
|
The
|
|
.B \-\-listcacerts
|
|
operation lists all X.509 CA certificates either loaded locally from the
|
|
.IR /etc/ipsec.d/cacerts
|
|
directory or received in PKCS#7-wrapped certificate payloads via
|
|
the IKE protocol.
|
|
.PP
|
|
The
|
|
.B \-\-listaacerts
|
|
operation lists all X.509 AA certificates loaded locally from the
|
|
.IR /etc/ipsec.d/aacerts
|
|
directory.
|
|
.PP
|
|
The
|
|
.B \-\-listocspcerts
|
|
operation lists all OCSP signer certificates either loaded locally from the
|
|
.IR /etc/ipsec.d/ocspcerts
|
|
directory or received via the Online Certificate Status Protocol
|
|
from an OCSP server.
|
|
.PP
|
|
The
|
|
.B \-\-listacerts
|
|
operation lists all X.509 attribute certificates loaded locally from the
|
|
.IR /etc/ipsec.d/acerts
|
|
directory.
|
|
.PP
|
|
The
|
|
.B \-\-listgropus
|
|
operation lists all groups that are either used in connection definitions in
|
|
.IR ipsec.conf (5)
|
|
or are embedded in loaded X.509 attributes certificates.
|
|
.PP
|
|
The
|
|
.B \-\-listcainfos
|
|
operation lists the certification authority information specified in the ca
|
|
sections of
|
|
.IR ipsec.conf (5).
|
|
.PP
|
|
The
|
|
.B \-\-listcrls
|
|
operation lists all Certificate Revocation Lists (CRLs) either loaded
|
|
locally from the
|
|
.IR /etc/ipsec.d/crls
|
|
directory or fetched dynamically from an HTTP or LDAP server.
|
|
.PP
|
|
The
|
|
.B \-\-listocsp
|
|
operation lists the certicates status information fetched from
|
|
OCSP servers.
|
|
.PP
|
|
The
|
|
.B \-\-purgeocsp
|
|
operation deletes any cached certificate status information and pending
|
|
OCSP fetch requests.
|
|
.PP
|
|
The
|
|
.B \-\-listcards
|
|
operation lists information about attached smartcards or crypto tokens.
|
|
.PP
|
|
The
|
|
.B \-\-listall
|
|
operation is equivalent to the execution of
|
|
.BR \-\-listalgs ,
|
|
.BR \-\-listpubkeys ,
|
|
.BR \-\-listcerts ,
|
|
.BR \-\-listcacerts ,
|
|
.BR \-\-listaacerts ,
|
|
.BR \-\-listocspcerts ,
|
|
.BR \-\-listacerts ,
|
|
.BR \-\-listgroups ,
|
|
.BR \-\-listcainfos ,
|
|
.BR \-\-listcrls ,
|
|
.BR \-\-listocsp ,
|
|
and
|
|
.BR \-\-listcards .
|
|
.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.
|
|
Extended for the strongSwan project
|
|
<http://www.strongswan.org>
|
|
by Andreas Steffen.
|
|
.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.)
|