openconnect.8

   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 \-K,\-\-key\-type type
  13 .OP \-C,\-\-cookie cookie
  14 .OP \-\-cookie\-on\-stdin
  15 .OP \-d,\-\-deflate
  16 .OP \-D,\-\-no\-deflate
  17 .OP \-\-force\-dpd interval
  18 .OP \-g,\-\-usergroup group
  19 .OP \-h,\-\-help
  20 .OP \-i,\-\-interface ifname
  21 .OP \-l,\-\-syslog
  22 .OP \-U,\-\-setuid user
  23 .OP \-\-csd\-user user
  24 .OP \-m,\-\-mtu 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 \-\-key\-type type
  31 .OP \-q,\-\-quiet
  32 .OP \-Q,\-\-queue\-len len
  33 .OP \-s,\-\-script vpnc\-script
  34 .OP \-S,\-\-script\-tun
  35 .OP \-u,\-\-user name
  36 .OP \-V,\-\-version
  37 .OP \-v,\-\-verbose
  38 .OP \-x,\-\-xmlconfig config
  39 .OP \-\-authgroup group
  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 .TP
 104 .B \-e,\-\-cert\-expire\-warning=DAYS
 105 Give a warning when SSL client certificate has
 106 .I DAYS
 107 left before expiry
 108 .TP
 109 .B \-k,\-\-sslkey=KEY
 110 Use SSL private key file
 111 .I KEY
 112 .TP
 113 .B \-C,\-\-cookie=COOKIE
 114 Use WebVPN cookie
 115 .I COOKIE
 116 .TP
 117 .B \-\-cookie\-on\-stdin
 118 Read cookie from standard input
 119 .TP
 120 .B \-d,\-\-deflate
 121 Enable compression (default)
 122 .TP
 123 .B \-D,\-\-no\-deflate
 124 Disable compression
 125 .TP
 126 .B \-\-force\-dpd=INTERVAL
 127 Use
 128 .I INTERVAL
 129 as minimum Dead Peer Detection interval for CSTP and DTLS, forcing use of DPD even when the server doesn't request it.
 130 .TP
 131 .B \-g,\-\-usergroup=GROUP
 132 Use
 133 .I GROUP
 134 as login UserGroup
 135 .TP
 136 .B \-h,\-\-help
 137 Display help text
 138 .TP
 139 .B \-i,\-\-interface=IFNAME
 140 Use
 141 .I IFNAME
 142 for tunnel interface
 143 .TP
 144 .B \-l,\-\-syslog
 145 Use syslog for progress messages
 146 .TP
 147 .B \-U,\-\-setuid=USER
 148 Drop privileges after connecting, to become user
 149 .I USER
 150 .TP
 151 .B \-\-csd\-user=USER
 152 Drop privileges during CSD (Cisco Secure Desktop) script execution.
 153 .TP
 154 .B \-\-csd\-wrapper=SCRIPT
 155 Run
 156 .I SCRIPT
 157 instead of the CSD (Cisco Secure Desktop) script.
 158 .TP
 159 .B \-m,\-\-mtu=MTU
 160 Request
 161 .I MTU
 162 from server
 163 .TP
 164 .B \-p,\-\-key\-password=PASS
 165 Provide passphrase for certificate file, or SRK (System Root Key) PIN for TPM
 166 .TP
 167 .B \-P,\-\-proxy=PROXYURL
 168 Use HTTP or SOCKS proxy for connection
 169 .TP
 170 .B \-\-no\-proxy
 171 Disable use of proxy
 172 .TP
 173 .B \-\-libproxy
 174 Use libproxy to configure proxy automatically (when built with libproxy support)
 175 .TP
 176 .B \-\-key\-password\-from\-fsid
 177 Passphrase for certificate file is automatically generated from the
 178 .I fsid
 179 of the file system on which it is stored. The
 180 .I fsid
 181 is obtained from the
 182 .BR statvfs (2)
 183 or
 184 .BR statfs (2)
 185 system call, depending on the operating system. On a Linux or similar system
 186 with GNU coreutils, the
 187 .I fsid
 188 used by this option should be equal to the output of the command:
 189 .EX
 190 stat \-\-file\-system \-\-printf=%i\e\en $CERTIFICATE
 191 .EE
 192 It is not the same as the 128\-bit UUID of the file system.
 193 .TP
 194 .B \-\-key\-type=TYPE
 195 Type of private key file (PKCS#12, TPM or PEM)
 196 .TP
 197 .B \-q,\-\-quiet
 198 Less output
 199 .TP
 200 .B \-Q,\-\-queue\-len=LEN
 201 Set packet queue limit to
 202 .I LEN
 203 pkts
 204 .TP
 205 .B \-s,\-\-script=SCRIPT
 206 Invoke
 207 .I SCRIPT
 208 to configure the network after connection. Without this, routing and name
 209 service are unlikely to work correctly. The script is expected to be
 210 compatible with the
 211 .B vpnc\-script
 212 which is shipped with the "vpnc" VPN client. See
 213 .I http://www.infradead.org/openconnect/vpnc-script.html
 214 for more information. Unless OpenConnect was built in a non-standard way,
 215 the default is
 216 .B /etc/vpnc/vpnc-script
 217 .TP
 218 .B \-S,\-\-script\-tun
 219 Pass traffic to 'script' program over a UNIX socket, instead of to a kernel
 220 tun/tap device. This allows the VPN IP traffic to be handled entirely in
 221 userspace, for example by a program which uses lwIP to provide SOCKS access
 222 into the VPN.
 223 .TP
 224 .B \-u,\-\-user=NAME
 225 Set login username to
 226 .I NAME
 227 .TP
 228 .B \-V,\-\-version
 229 Report version number
 230 .TP
 231 .B \-v,\-\-verbose
 232 More output
 233 .TP
 234 .B \-x,\-\-xmlconfig=CONFIG
 235 XML config file
 236 .TP
 237 .B \-\-authgroup=GROUP
 238 Choose authentication login selection
 239 .TP
 240 .B \-\-cookieonly
 241 Fetch webvpn cookie only; don't connect
 242 .TP
 243 .B \-\-printcookie
 244 Print webvpn cookie before connecting
 245 .TP
 246 .B \-\-cafile=FILE
 247 Cert file for server verification
 248 .TP
 249 .B \-\-disable\-ipv6
 250 Do not advertise IPv6 capability to server
 251 .TP
 252 .B \-\-dtls\-ciphers=LIST
 253 Set OpenSSL ciphers to support for DTLS
 254 .TP
 255 .B \-\-no\-cert\-check
 256 Do not require server SSL certificate to be valid. Checks will still happen
 257 and failures will cause a warning message, but the connection will continue
 258 anyway. You should not need to use this option \- if your servers have SSL
 259 certificates which are not signed by a trusted Certificate Authority, you can
 260 still add them (or your private CA) to a local file and use that file with the
 261 .B \-\-cafile
 262 option.
 263
 264 .TP
 265 .B \-\-no\-dtls
 266 Disable DTLS
 267 .TP
 268 .B \-\-no\-http\-keepalive
 269 Version 8.2.2.5 of the Cisco ASA software has a bug where it will forget
 270 the client's SSL certificate when HTTP connections are being re\-used for
 271 multiple requests. So far, this has only been seen on the initial connection,
 272 where the server gives an HTTP/1.0 redirect response with an explicit
 273 .B Connection: Keep\-Alive
 274 directive. OpenConnect as of v2.22 has an unconditional workaround for this,
 275 which is never to obey that directive after an HTTP/1.0 response.
 276
 277 However, Cisco's support team has failed to give any competent
 278 response to the bug report and we don't know under what other
 279 circumstances their bug might manifest itself. So this option exists
 280 to disable ALL re\-use of HTTP sessions and cause a new connection to be
 281 made for each request. If your server seems not to be recognising your
 282 certificate, try this option. If it makes a difference, please report
 283 this information to the
 284 .B openconnect\-devel@lists.infradead.org
 285 mailing list.
 286 .TP
 287 .B \-\-no\-passwd
 288 Never attempt password (or SecurID) authentication.
 289 .TP
 290 .B \-\-non\-inter
 291 Do not expect user input; exit if it is required.
 292 .TP
 293 .B \-\-passwd\-on\-stdin
 294 Read password from standard input
 295 .TP
 296 .B \-\-reconnect\-timeout
 297 Keep reconnect attempts until so much seconds are elapsed. The default
 298 timeout is 300 seconds, which means that openconnect can recover
 299 VPN connection after a temporary network down time of 300 seconds.
 300 .TP
 301 .B \-\-servercert=SHA1
 302 Accept server's SSL certificate only if its fingerprint matches
 303 .IR SHA1 .
 304 .TP
 305 .B \-\-useragent=STRING
 306 Use
 307 .I STRING
 308 as 'User\-Agent:' field value in HTTP header.
 309 (e.g. \-\-useragent 'Cisco AnyConnect VPN Agent for Windows 2.2.0133')
 310
 311 .SH LIMITATIONS
 312 Note that although IPv6 has been tested on all platforms on which
 313 .B openconnect
 314 is known to run, it depends on a suitable
 315 .B vpnc\-script
 316 to configure the network. The standard
 317 .B vpnc\-script
 318 shipped with vpnc 0.5.3 is not capable of setting up IPv6 routes; the one from
 319 .B git://git.infradead.org/users/dwmw2/vpnc\-scripts.git
 320 will be required.
 321
 322 .SH AUTHORS
 323 David Woodhouse <dwmw2@infradead.org>