'\" t .\" Title: IPSEC_AUTO .\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] .\" Generator: DocBook XSL Stylesheets v1.75.2 .\" Date: 07/25/2011 .\" Manual: [FIXME: manual] .\" Source: [FIXME: source] .\" Language: English .\" .TH "IPSEC_AUTO" "8" "07/25/2011" "[FIXME: source]" "[FIXME: manual]" .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" ipsec_auto \- control automatically\-keyed IPsec connections .SH "SYNOPSIS" .HP \w'\fBipsec\fR\ 'u \fBipsec\fR \fIauto\fR [\-\-show] [\-\-showonly] [\-\-asynchronous] .br [\-\-config\ \fIconfigfile\fR] [\-\-verbose] \fIoperation\ connection\fR .br .HP \w'\fBipsec\fR\ 'u \fBipsec\fR \fIauto\fR [\-\-show] [\-\-showonly] [\-\-asynchronous] .br [\-\-config\ \fIconfigfile\fR] [\-\-verbose] \fIoperation\ connection\fR .br .SH "EXAMPLES" .HP \w'\fBipsec\fR\ 'u \fBipsec\fR \fIauto\fR {\ \-\-add\ |\ \-\-delete\ |\ \-\-replace\ |\ \-\-up\ |\ \-\-down\ } \fIconnection\fR .HP \w'\fBipsec\fR\ 'u \fBipsec\fR \fIauto\fR {\ \-\-status\ |\ \-\-ready\ } \fIconnection\fR .HP \w'\fBipsec\fR\ 'u \fBipsec\fR \fIauto\fR {\ \-\-route\ |\ \-\-unroute\ } \fIconnection\fR .HP \w'\fBipsec\fR\ 'u \fBipsec\fR \fIauto\fR [\-\-utc] [\-\-listall | \-\-rereadall] [\-\-rereadsecrets] [\-\-listcerts] [\-\-listpubkeys] [\-\-checkpubkeys] [\-\-listcacerts | \-\-rereadcacerts] [\-\-listcrls | \-\-rereadcrls] [[\-\-listocspcerts | \-\-rereadocspcerts\ ]\ [\-\-listocsp | \-\-purgeocsp\ ]] [\-\-listacerts | \-\-rereadacerts] [\-\-listaacerts | \-\-rereadaacerts] [\-\-listgroups | \-\-rereadgroups] .SH "DESCRIPTION" .PP \fIAuto\fR 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, \fIconnection\fR is the name of a connection specification in the configuration file; \fIoperation\fR is \fB\-\-add\fR, \fB\-\-delete\fR, \fB\-\-replace\fR, \fB\-\-up\fR, \fB\-\-down\fR, \fB\-\-route\fR, or \fB\-\-unroute\fR\&. The \fB\-\-ready\fR, \fB\-\-rereadsecrets\fR, \fB\-\-rereadgroups\fR, and \fB\-\-status\fR \fIoperations\fR do not take a connection name\&. \fIAuto\fR generates suitable commands and feeds them to a shell for execution\&. .PP The \fB\-\-add\fR operation adds a connection specification to the internal database within \fIpluto\fR; it will fail if \fIpluto\fR already has a specification by that name\&. The \fB\-\-delete\fR operation deletes a connection specification from \fIpluto\fR\'s internal database (also tearing down any connections based on it); it will fail if the specification does not exist\&. The \fB\-\-replace\fR operation is equivalent to \fB\-\-delete\fR (if there is already a specification by the given name) followed by \fB\-\-add\fR, and is a convenience for updating \fIpluto\fR\'s internal specification to match an external one\&. (Note that a \fB\-\-rereadsecrets\fR may also be needed\&.) The \fB\-\-rereadgroups\fR operation causes any changes to the policy group files to take effect (this is currently a synonym for \fB\-\-ready\fR, but that may change)\&. None of the other operations alters the internal database\&. .PP The \fB\-\-up\fR operation asks \fIpluto\fR to establish a connection based on an entry in its internal database\&. The \fB\-\-down\fR operation tells \fIpluto\fR to tear down such a connection\&. .PP Normally, \fIpluto\fR establishes a route to the destination specified for a connection as part of the \fB\-\-up\fR operation\&. However, the route and only the route can be established with the \fB\-\-route\fR 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, \fIpluto\fR\'s route to a destination remains in place when a \fB\-\-down\fR 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 \(lqwindow\(rq in which packets might go elsewhere based on a more general route\&. Such a route can be removed using the \fB\-\-unroute\fR operation (and is implicitly removed by \fB\-\-delete\fR)\&. .PP The \fB\-\-ready\fR operation tells \fIpluto\fR to listen for connection\-setup requests from other hosts\&. Doing an \fB\-\-up\fR operation before doing \fB\-\-ready\fR 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 \fB\-\-status\fR operation asks \fIpluto\fR for current connection status\&. The output format is ad\-hoc and likely to change\&. .PP The \fB\-\-rereadsecrets\fR operation tells \fIpluto\fR to re\-read the /etc/ipsec\&.secrets secret\-keys file, which it normally reads only at startup time\&. (This is currently a synonym for \fB\-\-ready\fR, but that may change\&.) .PP The \fB\-\-rereadsecrets\fR 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 \fB\-\-ready,\fR but that may change\&.) .PP The \fB\-\-rereadcacerts\fR operation reads all certificate files contained in the /etc/ipsec\&.d/cacerts directory and adds them to pluto\(^a€™s list of Certification Authority (CA) certificates\&. .PP The \fB\-\-rereadaacerts\fR operation reads all certificate files contained in the /etc/ipsec\&.d/aacerts directory and adds them to pluto\(^a€™s list of Authorization Authority (AA) certificates\&. .PP The \fB\-\-rereadocspcerts\fR operation reads all certificate files contained in the /etc/ipsec\&.d/ocspcerts directory and adds them to pluto\(^a€™s list of OCSP signer certificates\&. .PP The \fB\-\-rereadacerts\fR operation reads all certificate files contained in the /etc/ipsec\&.d/acerts directory and adds them to pluto\(^a€™s list of attribute certificates\&. .PP The \fB\-\-rereadcrls\fR operation reads all certificate revocation list (CRL) files contained in the /etc/ipsec\&.d/crls directory and adds them to pluto\(^a€™s list of CRLs\&. .PP The \fB\-\-rereadall\fR operation is equivalent to the execution of \-\-rereadse\- crets, \fB\-\-rereadcacerts,\fR \-\-rereadaacerts, \-\-rereadocspcerts, \-\-rereadac\- erts, and \-\-rereadcrls\&. .PP The \fB\-\-listpubkeys\fR 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)\&. .PP The \fB\-\-listcerts\fR operation lists all X\&.509 certificates loaded locally using the rightcert and leftcert parameters in ipsec\&.conf(5)\&. .PP The \fB\-\-checkpubkeys\fR operation lists all loaded X\&.509 certificates which are about to expire or have been expired\&. .PP The \fB\-\-listcacerts\fR 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\&. .PP The \fB\-\-listaacerts\fR operation lists all X\&.509 AA certificates loaded locally from the /etc/ipsec\&.d/aacerts directory\&. .PP The \fB\-\-listocspcerts\fR 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\&. .PP The \fB\-\-listacerts\fR operation lists all X\&.509 attribute certificates loaded locally from the /etc/ipsec\&.d/acerts directory\&. .PP The \fB\-\-listgropus\fR operation lists all groups that are either used in connection definitions in ipsec\&.conf(5) or are embedded in loaded X\&.509 attributes certificates\&. .PP The \fB\-\-listcainfos\fR operation lists the certification authority informa\- tion specified in the ca sections of ipsec\&.conf(5)\&. .PP The \fB\-\-listcrls\fR 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\&. .PP The \fB\-\-listocsp\fR operation lists the certicates status information fetched from OCSP servers\&. .PP The \fB\-\-purgeocsp\fR operation deletes any cached certificate status infor\- mation and pending OCSP fetch requests\&. .PP The \fB\-\-listall\fR operation is equivalent to the execution of \-\-listpubkeys, \-\-listcerts, \-\-listcacerts, \-\-listaacerts, \-\-listoc\- spcerts, \-\-listacerts, \-\-listgroups, \-\-listcainfos, \-\-listcrls, \-\-lis\- tocsp\&. .PP The \fB\-\-showonly\fR option causes \fIauto\fR to show the commands it would run, on standard output, and not run them\&. .PP The \fB\-\-asynchronous\fR option, applicable only to the \fBup\fR operation, tells \fIpluto\fR 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 \fB\-\-verbose\fR option instructs \fIauto\fR to pass through all output from \fBipsec_whack\fR(8), including log output that is normally filtered out as uninteresting\&. .PP The \fB\-\-show\fR option turns on the \fB\-x\fR option of the shell used to execute the commands, so each command is shown as it is executed\&. .PP The \fB\-\-config\fR option specifies a non\-standard location for the IPsec configuration file (default /etc/ipsec\&.conf)\&. .PP See \fBipsec.conf\fR(5) for details of the configuration file\&. .SH "FILES" .PP .sp .if n \{\ .RS 4 .\} .nf /etc/ipsec\&.conf default IPSEC configuration file /etc/ipsec\&.d/ X\&.509 and Opportunistic Encryption files /var/run/pluto/ipsec\&.info \fB%defaultroute\fR information /var/run/pluto/pluto\&.ctl Pluto command socket .fi .if n \{\ .RE .\} .sp .SH "SEE ALSO" .PP \fBipsec.conf\fR(5), \fBipsec\fR(8), \fBipsec_pluto\fR(8), \fBipsec_whack\fR(8), \fBipsec_manual\fR(8) .SH "HISTORY" .PP Originally written for the FreeS/WAN project <\m[blue]\fBhttp://www\&.freeswan\&.org\fR\m[]> by Henry Spencer\&. .SH "BUGS" .PP Although an \fB\-\-up\fR operation does connection setup on both ends, \fB\-\-down\fR tears only one end of the connection down (although the orphaned end will eventually time out)\&. .PP There is no support for \fBpassthrough\fR connections\&. .PP A connection description which uses \fB%defaultroute\fR for one of its \fBnexthop\fR parameters but not the other may be falsely rejected as erroneous in some circumstances\&. .PP The exit status of \fB\-\-showonly\fR 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\&.)