freeswan/utils/auto.8

   1 .TH IPSEC_AUTO 8 "31 Jan 2002"
   2 .\" RCSID $Id: auto.8,v 1.39 2002/01/31 20:29:59 henry Exp $
   3 .SH NAME
   4 ipsec auto \- control automatically-keyed IPsec connections
   5 .SH SYNOPSIS
   6 .B ipsec
   7 .B auto
   8 [
   9 .B \-\-show
  10 ] [
  11 .B \-\-showonly
  12 ] [
  13 .B \-\-asynchronous
  14 ]
  15 .br
  16 \ \ \ [
  17 .B \-\-config
  18 configfile
  19 ] [
  20 .B \-\-verbose
  21 ]
  22 .br
  23 \ \ \ operation
  24 connection
  25 .sp
  26 .B ipsec
  27 .B auto
  28 [
  29 .B \-\-show
  30 ] [
  31 .B \-\-showonly
  32 ] operation
  33 .SH DESCRIPTION
  34 .I Auto
  35 manipulates automatically-keyed FreeS/WAN IPsec connections,
  36 setting them up and shutting them down
  37 based on the information in the IPsec configuration file.
  38 In the normal usage,
  39 .I connection
  40 is the name of a connection specification in the configuration file;
  41 .I operation
  42 is
  43 .BR \-\-add ,
  44 .BR \-\-delete ,
  45 .BR \-\-replace ,
  46 .BR \-\-up ,
  47 .BR \-\-down ,
  48 .BR \-\-route ,
  49 or
  50 .BR \-\-unroute .
  51 The
  52 .BR \-\-ready ,
  53 .BR \-\-rereadsecrets ,
  54 and
  55 .BR \-\-status
  56 .I operations
  57 do not take a connection name.
  58 .I Auto
  59 generates suitable
  60 commands and feeds them to a shell for execution.
  61 .PP
  62 The
  63 .B \-\-add
  64 operation adds a connection specification to the internal database
  65 within
  66 .IR pluto ;
  67 it will fail if
  68 .I pluto
  69 already has a specification by that name.
  70 The
  71 .B \-\-delete
  72 operation deletes a connection specification from
  73 .IR pluto 's
  74 internal database (also tearing down any connections based on it);
  75 it will fail if the specification does not exist.
  76 The
  77 .B \-\-replace
  78 operation is equivalent to
  79 .B \-\-delete
  80 (if there is already a specification by the given name)
  81 followed by
  82 .BR \-\-add ,
  83 and is a convenience for updating
  84 .IR pluto 's
  85 internal specification to match an external one.
  86 (Note that a
  87 .B \-\-rereadsecrets
  88 may also be needed.)
  89 None of the other operations alters the internal database.
  90 .PP
  91 The
  92 .B \-\-up
  93 operation asks
  94 .I pluto
  95 to establish a connection based on an entry in its internal database.
  96 The
  97 .B \-\-down
  98 operation tells
  99 .I pluto
 100 to tear down such a connection.
 101 .PP
 102 Normally,
 103 .I pluto
 104 establishes a route to the destination specified for a connection as
 105 part of the
 106 .B \-\-up
 107 operation.
 108 However, the route and only the route can be established with the
 109 .B \-\-route
 110 operation.
 111 Until and unless an actual connection is established,
 112 this discards any packets sent there,
 113 which may be preferable to having them sent elsewhere based on a more
 114 general route (e.g., a default route).
 115 .PP
 116 Normally,
 117 .IR pluto 's
 118 route to a destination remains in place when a
 119 .B \-\-down
 120 operation is used to take the connection down
 121 (or if connection setup, or later automatic rekeying, fails).
 122 This permits establishing a new connection (perhaps using a
 123 different specification; the route is altered as necessary)
 124 without having a ``window'' in which packets might go elsewhere
 125 based on a more general route.
 126 Such a route can be removed using the
 127 .B \-\-unroute
 128 operation
 129 (and is implicitly removed by
 130 .BR \-\-delete ).
 131 .PP
 132 The
 133 .B \-\-ready
 134 operation tells
 135 .I pluto
 136 to listen for connection-setup requests from other hosts.
 137 Doing an
 138 .B \-\-up
 139 operation before doing
 140 .B \-\-ready
 141 on both ends is futile and will not work,
 142 although this is now automated as part of IPsec startup and
 143 should not normally be an issue.
 144 .PP
 145 The
 146 .B \-\-status
 147 operation asks
 148 .I pluto
 149 for current connection status.
 150 The output format is ad-hoc and likely to change.
 151 .PP
 152 The
 153 .B \-\-rereadsecrets
 154 operation tells
 155 .I pluto
 156 to re-read the
 157 .I /etc/ipsec.secrets
 158 secret-keys file,
 159 which it normally reads only at startup time.
 160 (This is currently a synonym for
 161 .BR \-\-ready ,
 162 but that may change.)
 163 .PP
 164 The
 165 .B \-\-show
 166 option turns on the
 167 .B \-x
 168 option of the shell used to execute the commands,
 169 so each command is shown as it is executed.
 170 .PP
 171 The
 172 .B \-\-showonly
 173 option causes
 174 .I auto
 175 to show the commands it would run, on standard output,
 176 and not run them.
 177 .PP
 178 The
 179 .B \-\-asynchronous
 180 option, applicable only to the
 181 .B up
 182 operation,
 183 tells
 184 .I pluto
 185 to attempt to establish the connection,
 186 but does not delay to report results.
 187 This is especially useful to start multiple connections in parallel
 188 when network links are slow.
 189 .PP
 190 The
 191 .B \-\-verbose
 192 option instructs
 193 .I auto
 194 to pass through all output from
 195 .IR ipsec_whack (8),
 196 including log output that is normally filtered out as uninteresting.
 197 .PP
 198 The
 199 .B \-\-config
 200 option specifies a non-standard location for the IPsec
 201 configuration file (default
 202 .IR /etc/ipsec.conf ).
 203 .PP
 204 See
 205 .IR ipsec.conf (5)
 206 for details of the configuration file.
 207 Apart from the basic parameters which specify the endpoints and routing
 208 of a connection (\fBleft\fR
 209 and
 210 .BR right ,
 211 plus possibly
 212 .BR leftsubnet ,
 213 .BR leftnexthop ,
 214 .BR leftfirewall ,
 215 their
 216 .B right
 217 equivalents,
 218 and perhaps
 219 .BR type ),
 220 an
 221 .I auto
 222 connection almost certainly needs a
 223 .B keyingtries
 224 parameter (since the
 225 .B keyingtries
 226 default is poorly chosen).
 227 .SH FILES
 228 .ta \w'/var/run/ipsec.info'u+4n
 229 /etc/ipsec.conf default IPSEC configuration file
 230 .br
 231 /var/run/ipsec.info     \fB%defaultroute\fR information
 232 .SH SEE ALSO
 233 ipsec.conf(5), ipsec(8), ipsec_pluto(8), ipsec_whack(8), ipsec_manual(8)
 234 .SH HISTORY
 235 Written for the FreeS/WAN project
 236 <http://www.freeswan.org>
 237 by Henry Spencer.
 238 .SH BUGS
 239 Although an
 240 .B \-\-up
 241 operation does connection setup on both ends,
 242 .B \-\-down
 243 tears only one end of the connection down
 244 (although the orphaned end will eventually time out).
 245 .PP
 246 There is no support for
 247 .B passthrough
 248 connections.
 249 .PP
 250 A connection description which uses
 251 .B %defaultroute
 252 for one of its
 253 .B nexthop
 254 parameters but not the other may be falsely
 255 rejected as erroneous in some circumstances.
 256 .PP
 257 The exit status of
 258 .B \-\-showonly
 259 does not always reflect errors discovered during processing of the request.
 260 (This is fine for human inspection, but not so good for use in scripts.)