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