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