freeswan/utils/manual.8

   1 .TH IPSEC_MANUAL 8 "17 July 2001"
   2 .\" RCSID $Id: manual.8,v 1.52 2001/07/17 20:45:55 henry Exp $
   3 .SH NAME
   4 ipsec manual \- take manually-keyed IPsec connections up and down
   5 .SH SYNOPSIS
   6 .B ipsec
   7 .B manual
   8 [
   9 .B \-\-show
  10 ] [
  11 .B \-\-showonly
  12 ] [
  13 .B \-\-other
  14 ]
  15 .br
  16 \ \ \ [
  17 .B \-\-iam
  18 .RB address "@" interface
  19 ] [
  20 .B \-\-config
  21 configfile
  22 ]
  23 .br
  24 \ \ \ operation connection
  25 .sp 0.5
  26 .B ipsec
  27 .B manual
  28 [
  29 .I options
  30 ]
  31 .B \-\-union
  32 operation part ...
  33 .SH DESCRIPTION
  34 .I Manual
  35 manipulates manually-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 \-\-up ,
  44 .BR \-\-down ,
  45 .BR \-\-route ,
  46 or
  47 .BR \-\-unroute .
  48 .I Manual
  49 generates setup (\c
  50 .BR \-\-route
  51 or
  52 .BR \-\-up )
  53 or
  54 teardown (\c
  55 .BR \-\-down
  56 or
  57 .BR \-\-unroute )
  58 commands for the connection and feeds them to a shell for execution.
  59 .PP
  60 The
  61 .B \-\-up
  62 operation brings the specified connection up, including establishing a
  63 suitable route for it if necessary.
  64 .PP
  65 The
  66 .B \-\-route
  67 operation just establishes the route for a connection.
  68 Unless and until an
  69 .B \-\-up
  70 operation is done, packets routed by that route will simply be discarded.
  71 .PP
  72 The
  73 .B \-\-down
  74 operation tears the specified connection down,
  75 .I except
  76 that it leaves the route in place.
  77 Unless and until an
  78 .B \-\-unroute
  79 operation is done, packets routed by that route will simply be discarded.
  80 This permits establishing another connection to the same destination
  81 without any ``window'' in which packets can pass without encryption.
  82 .PP
  83 The
  84 .B \-\-unroute
  85 operation (and only the
  86 .B \-\-unroute
  87 operation) deletes any route established for a connection.
  88 .PP
  89 In the
  90 .B \-\-union
  91 usage, each
  92 .I part
  93 is the name of a partial connection specification in the configuration file,
  94 and the union of all the partial specifications is the
  95 connection specification used.
  96 The effect is as if the contents of the partial specifications were
  97 concatenated together;
  98 restrictions on duplicate parameters, etc., do apply to the result.
  99 (The same effect can now be had, more gracefully, using the
 100 .B also
 101 parameter in connection descriptions;
 102 see
 103 .IR ipsec.conf (5)
 104 for details.)
 105 .PP
 106 The
 107 .B \-\-show
 108 option turns on the
 109 .B \-x
 110 option of the shell used to execute the commands,
 111 so each command is shown as it is executed.
 112 .PP
 113 The
 114 .B \-\-showonly
 115 option causes
 116 .I manual
 117 to show the commands it would run, on standard output,
 118 and not run them.
 119 .PP
 120 The
 121 .B \-\-other
 122 option causes
 123 .I manual
 124 to pretend it is the other end of the connection.
 125 This is probably not useful except in combination with
 126 .BR \-\-showonly .
 127 .PP
 128 The
 129 .B \-\-iam
 130 option causes
 131 .I manual
 132 to believe it is running on the host with the specified IP
 133 .IR address ,
 134 and that it should use the specified
 135 .I interface
 136 (normally it determines all this automatically,
 137 based on what IPsec interfaces are up and how they are configured).
 138 .PP
 139 The
 140 .B \-\-config
 141 option specifies a non-standard location for the FreeS/WAN IPsec
 142 configuration file (default
 143 .IR /etc/ipsec.conf ).
 144 .PP
 145 See
 146 .IR ipsec.conf (5)
 147 for details of the configuration file.
 148 Apart from the basic parameters which specify the endpoints and routing
 149 of a connection (\fBleft\fR
 150 and
 151 .BR right ,
 152 plus possibly
 153 .BR leftsubnet ,
 154 .BR leftnexthop ,
 155 .BR leftfirewall ,
 156 their
 157 .B right
 158 equivalents,
 159 and perhaps
 160 .BR type ),
 161 a non-\fBpassthrough\fR
 162 .I manual
 163 connection needs an
 164 .B spi
 165 or
 166 .B spibase
 167 parameter and some parameters specifying encryption, authentication, or
 168 both, most simply
 169 .BR esp ,
 170 .BR espenckey ,
 171 and
 172 .BR espauthkey .
 173 Moderately-secure keys can be obtained from
 174 .IR ipsec_ranbits (8).
 175 For production use of manually-keyed connections,
 176 it is strongly recommended that the keys be kept in a separate file
 177 (with permissions
 178 .BR rw\-\-\-\-\-\-\- )
 179 using the
 180 .B include
 181 and
 182 .B also
 183 facilities of the configuration file (see
 184 .IR ipsec.conf (5)).
 185 .PP
 186 If an
 187 .B spi
 188 parameter is given,
 189 .I manual
 190 uses that value as the SPI number for all the SAs
 191 (which are in separate number spaces anyway).
 192 If an
 193 .B spibase
 194 parameter is given instead,
 195 .I manual
 196 assigns SPI values by altering the bottom digit
 197 of that value;
 198 SAs going from left to right get even digits starting at 0,
 199 SAs going from right to left get odd digits starting at 1.
 200 Either way, it is suggested that manually-keyed connections use
 201 three-digit SPIs with the first digit non-zero,
 202 i.e. in the range
 203 .B 0x100
 204 through
 205 .BR 0xfff ;
 206 FreeS/WAN reserves those for manual keying and will not
 207 attempt to use them for automatic keying (unless requested to,
 208 presumably by a non-FreeS/WAN other end).
 209 .SH FILES
 210 .ta \w'/var/run/ipsec.nexthop'u+4n
 211 /etc/ipsec.conf default IPsec configuration file
 212 .br
 213 /var/run/ipsec.info     \fB%defaultroute\fR information
 214 .SH SEE ALSO
 215 ipsec(8), ipsec.conf(5), ipsec_spi(8), ipsec_eroute(8), ipsec_spigrp(8),
 216 route(8)
 217 .SH HISTORY
 218 Written for the FreeS/WAN project
 219 <http://www.freeswan.org/>
 220 by Henry Spencer.
 221 .SH BUGS
 222 It's not nearly as generous about the syntax of subnets,
 223 addresses, etc. as the usual FreeS/WAN user interfaces.
 224 Four-component dotted-decimal must be used for all addresses.
 225 It
 226 .I is
 227 smart enough to translate bit-count netmasks to dotted-decimal form.
 228 .PP
 229 If the connection specification for a connection is changed between an
 230 .B \-\-up
 231 and the ensuing
 232 .BR \-\-down ,
 233 chaos may ensue.
 234 .PP
 235 The
 236 .B \-\-up
 237 operation is not smart enough to notice whether the connection is already up.
 238 .PP
 239 .I Manual
 240 is not smart enough to reject insecure combinations of algorithms,
 241 e.g. encryption with no authentication at all.
 242 .PP
 243 Any non-IPsec route to the other end which is replaced by the
 244 .B \-\-up
 245 or
 246 .B \-\-route
 247 operation will not be re-established by
 248 .BR \-\-unroute .
 249 Whether this is a feature or a bug depends on your viewpoint.
 250 .PP
 251 The optional parameters which
 252 override the automatic
 253 .BR spibase -based
 254 SPI assignment are a messy area of the code and bugs are likely.
 255 .PP
 256 ``Road warrior'' handling,
 257 and other special forms of setup which
 258 require negotiation between the two security gateways,
 259 inherently cannot be done with
 260 .IR manual .
 261 .PP
 262 .I Manual
 263 generally lags behind
 264 .I auto
 265 in support of various features,
 266 even when implementation \fIwould\fR be possible.
 267 For example, currently it does not do IPComp content compression.