'\" t .\" Title: IPSEC_AUTO .\" Author: Paul Wouters .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 08/10/2023 .\" Manual: Executable programs .\" Source: libreswan .\" Language: English .\" .TH "IPSEC_AUTO" "8" "08/10/2023" "libreswan" "Executable programs" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * 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 [\-\-showonly] [\-\-asynchronous] .br [\-\-config\ \fIconfigfile\fR] [\-\-verbose] \fIoperation\ connection\fR .br .HP \w'\fBipsec\fR\ 'u \fBipsec\fR \fIauto\fR [\-\-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\ |\ \-\-start\ } \fIconnection\fR .HP \w'\fBipsec\fR\ 'u \fBipsec\fR \fIauto\fR {\ \-\-up\ |\ \-\-down\ } \fIconnection\fR .HP \w'\fBipsec\fR\ 'u \fBipsec\fR \fIauto\fR {\ \-\-route\ |\ \-\-unroute\ |\ \-\-ondemand\ } \fIconnection\fR .HP \w'\fBipsec\fR\ 'u \fBipsec\fR \fIauto\fR {\ \-\-status\ |\ \-\-ready\ } .HP \w'\fBipsec\fR\ 'u \fBipsec\fR \fIauto\fR [\-\-utc] [\-\-listall\ |\ \-\-rereadall] [\-\-rereadsecrets] [\-\-listcerts] [\-\-listpubkeys] [\-\-checkpubkeys] [\-\-listcacerts] [\-\-fetchcrls] [\-\-listcrls] [\-\-purgeocsp] .HP \w'\fBipsec\fR\ 'u \fBipsec\fR \fIauto\fR [\-\-utc] [\-\-rereadcerts] \fIconnection\fR .SH "DESCRIPTION" .PP \fIAuto\fR manipulates automatically\-keyed Libreswan 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\-\-start\fR, \fB\-\-up\fR, \fB\-\-down\fR, \fB\-\-route\fR, \fB\-\-unroute\fR, \fB\-\-ondemand\fR, The \fB\-\-ready\fR, \fB\-\-rereadsecrets\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\*(Aqs internal database (also tearing down any connections based on it); The \fB\-\-replace\fR operation is equivalent to \fB\-\-delete\fR (if there is already a loaded connection by the given name) followed by \fB\-\-add\fR, and is a convenience for updating \fIpluto\fR\*(Aqs internal specification to match an external one\&. (Note that a \fB\-\-rereadsecrets\fR may also be needed\&.) The \fB\-\-start\fR operation is equivalent to running first with \fB\-\-add\fR and then with \fB\-\-up\fR, causing same effect as connection configuration option \fBauto=start\fR\&. .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 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\*(Aqs 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\-\-ondemand\fR operation is equivalent to running first with \fB\-\-add\fR and then with \fB\-\-route\fR, causing same effect as connection configuration option \fBauto=ondemand\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\-\-fetchcrls\fR operation reads all certificate revocation list (CRL) entries of loaded certificates and tries to fetch updates for these from the CRL servers\&. .PP The \fB\-\-rereadall\fR operation is equivalent to the execution of \-\-rereadsecrets (in the past there were other kinds of reread operations) .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)\&. To see all certificates in the NSS database, use \fBcertutil \-d /var/lib/ipsec/nss \-L\fR\&. .PP The \fB\-\-checkpubkeys\fR operation lists all loaded X\&.509 certificates that are about to expire or have expired\&. .PP The \fB\-\-listcacerts\fR operation lists all X\&.509 CA certificates contained in the NSS database\&. .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\-\-listall\fR operation is equivalent to the execution of \-\-listpubkeys, \-\-listcerts, \-\-listcacerts, \-\-listcrls\&. .PP The \fB\-\-purgeocsp\fR operation displays \-\-listall and purges the NSS OCSP cache\&. .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\-\-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 .if n \{\ .RS 4 .\} .nf /etc/ipsec\&.conf default IPSEC configuration file /var/lib/ipsec/nss X\&.509 and Opportunistic Encryption files /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) .SH "HISTORY" .PP Originally written for the FreeS/WAN project <\m[blue]\fBhttps://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 that 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\&.) .SH "AUTHOR" .PP \fBPaul Wouters\fR .RS 4 placeholder to suppress warning .RE