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