openconnect.8.in

   1 .TH OPENCONNECT 8
   2 .SH NAME
   3 openconnect \- Connect to Cisco AnyConnect VPN
   4 .SH SYNOPSIS
   5 .SY openconnect
   6 .OP \-\-config configfile
   7 .OP \-b,\-\-background
   8 .OP \-\-pid\-file pidfile
   9 .OP \-c,\-\-certificate cert
  10 .OP \-e,\-\-cert\-expire\-warning days
  11 .OP \-k,\-\-sslkey key
  12 .OP \-C,\-\-cookie cookie
  13 .OP \-\-cookie\-on\-stdin
  14 .OP \-d,\-\-deflate
  15 .OP \-D,\-\-no\-deflate
  16 .OP \-\-force\-dpd interval
  17 .OP \-g,\-\-usergroup group
  18 .OP \-h,\-\-help
  19 .OP \-i,\-\-interface ifname
  20 .OP \-l,\-\-syslog
  21 .OP \-U,\-\-setuid user
  22 .OP \-\-csd\-user user
  23 .OP \-m,\-\-mtu mtu
  24 .OP \-\-basemtu mtu
  25 .OP \-p,\-\-key\-password pass
  26 .OP \-P,\-\-proxy proxyurl
  27 .OP \-\-no\-proxy
  28 .OP \-\-libproxy
  29 .OP \-\-key\-password\-from\-fsid
  30 .OP \-q,\-\-quiet
  31 .OP \-Q,\-\-queue\-len len
  32 .OP \-s,\-\-script vpnc\-script
  33 .OP \-S,\-\-script\-tun
  34 .OP \-u,\-\-user name
  35 .OP \-V,\-\-version
  36 .OP \-v,\-\-verbose
  37 .OP \-x,\-\-xmlconfig config
  38 .OP \-\-authgroup group
  39 .OP \-\-authenticate
  40 .OP \-\-cookieonly
  41 .OP \-\-printcookie
  42 .OP \-\-cafile file
  43 .OP \-\-disable\-ipv6
  44 .OP \-\-dtls\-ciphers list
  45 .OP \-\-dtls\-local\-port port
  46 .OP \-\-no\-cert\-check
  47 .OP \-\-no\-dtls
  48 .OP \-\-no\-http\-keepalive
  49 .OP \-\-no\-passwd
  50 .OP \-\-non\-inter
  51 .OP \-\-passwd\-on\-stdin
  52 .OP \-\-stoken[=\fItoken-string\fP]
  53 .OP \-\-reconnect\-timeout
  54 .OP \-\-servercert sha1
  55 .OP \-\-useragent string
  56 .B [https://]\fIserver\fB[:\fIport\fB][/\fIgroup\fB]
  57 .YS
  58
  59 .SH DESCRIPTION
  60 The program
  61 .B openconnect
  62 connects to Cisco "AnyConnect" VPN servers, which use standard TLS
  63 and DTLS protocols for data transport.
  64
  65 The connection happens in two phases. First there is a simple HTTPS
  66 connection over which the user authenticates somehow \- by using a
  67 certificate, or password or SecurID, etc.  Having authenticated, the
  68 user is rewarded with an HTTP cookie which can be used to make the
  69 real VPN connection.
  70
  71 The second phase uses that cookie in an HTTPS
  72 .I CONNECT
  73 request, and data packets can be passed over the resulting
  74 connection. In auxiliary headers exchanged with the
  75 .I CONNECT
  76 request, a Session\-ID and Master Secret for a DTLS connection are also
  77 exchanged, which allows data transport over UDP to occur.
  78
  79
  80 .SH OPTIONS
  81 .TP
  82 .B \-\-config=CONFIGFILE
  83 Read further options from
  84 .I CONFIGFILE
  85 before continuing to process options from the command line. The file
  86 should contain long-format options as would be accepted on the command line,
  87 but without the two leading \-\- dashes. Empty lines, or lines where the
  88 first non-space character is a # character, are ignored.
  89
  90 Any option except the
  91 .B config
  92 option may be specified in the file.
  93 .TP
  94 .B \-b,\-\-background
  95 Continue in background after startup
  96 .TP
  97 .B \-\-pid\-file=PIDFILE
  98 Save the pid to
  99 .I PIDFILE
 100 when backgrounding
 101 .TP
 102 .B \-c,\-\-certificate=CERT
 103 Use SSL client certificate
 104 .I CERT
 105 which may be either a file name or, if OpenConnect has been built with an appropriate
 106 version of GnuTLS, a PKCS#11 URL.
 107 .TP
 108 .B \-e,\-\-cert\-expire\-warning=DAYS
 109 Give a warning when SSL client certificate has
 110 .I DAYS
 111 left before expiry
 112 .TP
 113 .B \-k,\-\-sslkey=KEY
 114 Use SSL private key
 115 .I KEY
 116 which may be either a file name or, if OpenConnect has been built with an appropriate
 117 version of GnuTLS, a PKCS#11 URL.
 118 .TP
 119 .B \-C,\-\-cookie=COOKIE
 120 Use WebVPN cookie
 121 .I COOKIE
 122 .TP
 123 .B \-\-cookie\-on\-stdin
 124 Read cookie from standard input
 125 .TP
 126 .B \-d,\-\-deflate
 127 Enable compression (default)
 128 .TP
 129 .B \-D,\-\-no\-deflate
 130 Disable compression
 131 .TP
 132 .B \-\-force\-dpd=INTERVAL
 133 Use
 134 .I INTERVAL
 135 as minimum Dead Peer Detection interval for CSTP and DTLS, forcing use of DPD even when the server doesn't request it.
 136 .TP
 137 .B \-g,\-\-usergroup=GROUP
 138 Use
 139 .I GROUP
 140 as login UserGroup
 141 .TP
 142 .B \-h,\-\-help
 143 Display help text
 144 .TP
 145 .B \-i,\-\-interface=IFNAME
 146 Use
 147 .I IFNAME
 148 for tunnel interface
 149 .TP
 150 .B \-l,\-\-syslog
 151 Use syslog for progress messages
 152 .TP
 153 .B \-U,\-\-setuid=USER
 154 Drop privileges after connecting, to become user
 155 .I USER
 156 .TP
 157 .B \-\-csd\-user=USER
 158 Drop privileges during CSD (Cisco Secure Desktop) script execution.
 159 .TP
 160 .B \-\-csd\-wrapper=SCRIPT
 161 Run
 162 .I SCRIPT
 163 instead of the CSD (Cisco Secure Desktop) script.
 164 .TP
 165 .B \-m,\-\-mtu=MTU
 166 Request
 167 .I MTU
 168 from server as the MTU of the tunnel.
 169 .TP
 170 .B \-\-basemtu=MTU
 171 Indicate
 172 .I MTU
 173 as the path MTU between client and server on the unencrypted network. Newer
 174 servers will automatically calculate the MTU to be used on the tunnel from
 175 this value.
 176 .TP
 177 .B \-p,\-\-key\-password=PASS
 178 Provide passphrase for certificate file, or SRK (System Root Key) PIN for TPM
 179 .TP
 180 .B \-P,\-\-proxy=PROXYURL
 181 Use HTTP or SOCKS proxy for connection
 182 .TP
 183 .B \-\-no\-proxy
 184 Disable use of proxy
 185 .TP
 186 .B \-\-libproxy
 187 Use libproxy to configure proxy automatically (when built with libproxy support)
 188 .TP
 189 .B \-\-key\-password\-from\-fsid
 190 Passphrase for certificate file is automatically generated from the
 191 .I fsid
 192 of the file system on which it is stored. The
 193 .I fsid
 194 is obtained from the
 195 .BR statvfs (2)
 196 or
 197 .BR statfs (2)
 198 system call, depending on the operating system. On a Linux or similar system
 199 with GNU coreutils, the
 200 .I fsid
 201 used by this option should be equal to the output of the command:
 202 .EX
 203 stat \-\-file\-system \-\-printf=%i\e\en $CERTIFICATE
 204 .EE
 205 It is not the same as the 128\-bit UUID of the file system.
 206 .TP
 207 .B \-q,\-\-quiet
 208 Less output
 209 .TP
 210 .B \-Q,\-\-queue\-len=LEN
 211 Set packet queue limit to
 212 .I LEN
 213 pkts
 214 .TP
 215 .B \-s,\-\-script=SCRIPT
 216 Invoke
 217 .I SCRIPT
 218 to configure the network after connection. Without this, routing and name
 219 service are unlikely to work correctly. The script is expected to be
 220 compatible with the
 221 .B vpnc\-script
 222 which is shipped with the "vpnc" VPN client. See
 223 .I http://www.infradead.org/openconnect/vpnc-script.html
 224 for more information. This version of OpenConnect is configured to use
 225 .B @DEFAULT_VPNCSCRIPT@
 226 by default.
 227 .TP
 228 .B \-S,\-\-script\-tun
 229 Pass traffic to 'script' program over a UNIX socket, instead of to a kernel
 230 tun/tap device. This allows the VPN IP traffic to be handled entirely in
 231 userspace, for example by a program which uses lwIP to provide SOCKS access
 232 into the VPN.
 233 .TP
 234 .B \-u,\-\-user=NAME
 235 Set login username to
 236 .I NAME
 237 .TP
 238 .B \-V,\-\-version
 239 Report version number
 240 .TP
 241 .B \-v,\-\-verbose
 242 More output
 243 .TP
 244 .B \-x,\-\-xmlconfig=CONFIG
 245 XML config file
 246 .TP
 247 .B \-\-authgroup=GROUP
 248 Choose authentication login selection
 249 .TP
 250 .B \-\-authenticate
 251 Authenticate only, and output the information needed to make the connection
 252 a form which can be used to set shell environment variables. When invoked with
 253 this option, openconnect will not make the connection, but if successful will
 254 output something like the following to stdout:
 255 .nf
 256 .B COOKIE=3311180634@13561856@1339425499@B315A0E29D16C6FD92EE...
 257 .B HOST=10.0.0.1
 258 .B FINGERPRINT=469bb424ec8835944d30bc77c77e8fc1d8e23a42
 259 .fi
 260 Thus, you can invoke openconnect as a non-privileged user
 261 .I (with access to the user's PKCS#11 tokens, etc.)
 262 for authentication, and then invoke openconnect separately to make the actual
 263 connection as root:
 264 .nf
 265 .B eval `openconnect --authenticate https://vpnserver.example.com`;
 266 .B [ -n "$COOKIE" ] && echo "$COOKIE" |
 267 .B \ \ sudo openconnect --cookie-on-stdin $HOST --servercert $FINGERPRINT
 268 .fi
 269 .TP
 270 .B \-\-cookieonly
 271 Fetch webvpn cookie only; don't connect
 272 .TP
 273 .B \-\-printcookie
 274 Print webvpn cookie before connecting
 275 .TP
 276 .B \-\-cafile=FILE
 277 Cert file for server verification
 278 .TP
 279 .B \-\-disable\-ipv6
 280 Do not advertise IPv6 capability to server
 281 .TP
 282 .B \-\-dtls\-ciphers=LIST
 283 Set OpenSSL ciphers to support for DTLS
 284 .TP
 285 .B \-\-no\-cert\-check
 286 Do not require server SSL certificate to be valid. Checks will still happen
 287 and failures will cause a warning message, but the connection will continue
 288 anyway. You should not need to use this option \- if your servers have SSL
 289 certificates which are not signed by a trusted Certificate Authority, you can
 290 still add them (or your private CA) to a local file and use that file with the
 291 .B \-\-cafile
 292 option.
 293
 294 .TP
 295 .B \-\-no\-dtls
 296 Disable DTLS
 297 .TP
 298 .B \-\-no\-http\-keepalive
 299 Version 8.2.2.5 of the Cisco ASA software has a bug where it will forget
 300 the client's SSL certificate when HTTP connections are being re\-used for
 301 multiple requests. So far, this has only been seen on the initial connection,
 302 where the server gives an HTTP/1.0 redirect response with an explicit
 303 .B Connection: Keep\-Alive
 304 directive. OpenConnect as of v2.22 has an unconditional workaround for this,
 305 which is never to obey that directive after an HTTP/1.0 response.
 306
 307 However, Cisco's support team has failed to give any competent
 308 response to the bug report and we don't know under what other
 309 circumstances their bug might manifest itself. So this option exists
 310 to disable ALL re\-use of HTTP sessions and cause a new connection to be
 311 made for each request. If your server seems not to be recognising your
 312 certificate, try this option. If it makes a difference, please report
 313 this information to the
 314 .B openconnect\-devel@lists.infradead.org
 315 mailing list.
 316 .TP
 317 .B \-\-no\-passwd
 318 Never attempt password (or SecurID) authentication.
 319 .TP
 320 .B \-\-non\-inter
 321 Do not expect user input; exit if it is required.
 322 .TP
 323 .B \-\-passwd\-on\-stdin
 324 Read password from standard input
 325 .TP
 326 .B \-\-stoken[=\fItoken-string\fP]
 327 Use libstoken to generate one-time passwords compatible with the RSA SecurID
 328 system (when built with libstoken support).  If \fItoken-string\fP is omitted,
 329 libstoken will try to use the software token seed stored in \fI~/.stokenrc\fP,
 330 if this file exists.
 331 .TP
 332 .B \-\-reconnect\-timeout
 333 Keep reconnect attempts until so much seconds are elapsed. The default
 334 timeout is 300 seconds, which means that openconnect can recover
 335 VPN connection after a temporary network down time of 300 seconds.
 336 .TP
 337 .B \-\-servercert=SHA1
 338 Accept server's SSL certificate only if its fingerprint matches
 339 .IR SHA1 .
 340 .TP
 341 .B \-\-useragent=STRING
 342 Use
 343 .I STRING
 344 as 'User\-Agent:' field value in HTTP header.
 345 (e.g. \-\-useragent 'Cisco AnyConnect VPN Agent for Windows 2.2.0133')
 346 .TP
 347 .B \-\-dtls\-local\-port=PORT
 348 Use
 349 .I PORT
 350 as the local port for DTLS datagrams
 351
 352 .SH LIMITATIONS
 353 Note that although IPv6 has been tested on all platforms on which
 354 .B openconnect
 355 is known to run, it depends on a suitable
 356 .B vpnc\-script
 357 to configure the network. The standard
 358 .B vpnc\-script
 359 shipped with vpnc 0.5.3 is not capable of setting up IPv6 routes; the one from
 360 .B git://git.infradead.org/users/dwmw2/vpnc\-scripts.git
 361 will be required.
 362
 363 .SH AUTHORS
 364 David Woodhouse <dwmw2@infradead.org>