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