openconnect.8.in 16.6 KB
Newer Older
Ray Kohler's avatar
Ray Kohler committed
1
.TH OPENCONNECT 8
David Woodhouse's avatar
David Woodhouse committed
2 3 4
.SH NAME
openconnect \- Connect to Cisco AnyConnect VPN
.SH SYNOPSIS
5
.SY openconnect
6
.OP \-\-config configfile
7 8 9 10 11 12 13
.OP \-b,\-\-background
.OP \-\-pid\-file pidfile
.OP \-c,\-\-certificate cert
.OP \-e,\-\-cert\-expire\-warning days
.OP \-k,\-\-sslkey key
.OP \-C,\-\-cookie cookie
.OP \-\-cookie\-on\-stdin
14
.OP \-\-compression MODE
15 16 17 18 19
.OP \-d,\-\-deflate
.OP \-D,\-\-no\-deflate
.OP \-\-force\-dpd interval
.OP \-g,\-\-usergroup group
.OP \-h,\-\-help
20
.OP \-\-http\-auth methods
21 22
.OP \-i,\-\-interface ifname
.OP \-l,\-\-syslog
23
.OP \-\-timestamp
24
.OP \-\-passtos
25 26 27
.OP \-U,\-\-setuid user
.OP \-\-csd\-user user
.OP \-m,\-\-mtu mtu
28
.OP \-\-base\-mtu mtu
29 30
.OP \-p,\-\-key\-password pass
.OP \-P,\-\-proxy proxyurl
31
.OP \-\-proxy\-auth methods
32 33 34 35 36 37 38 39 40 41 42 43
.OP \-\-no\-proxy
.OP \-\-libproxy
.OP \-\-key\-password\-from\-fsid
.OP \-q,\-\-quiet
.OP \-Q,\-\-queue\-len len
.OP \-s,\-\-script vpnc\-script
.OP \-S,\-\-script\-tun
.OP \-u,\-\-user name
.OP \-V,\-\-version
.OP \-v,\-\-verbose
.OP \-x,\-\-xmlconfig config
.OP \-\-authgroup group
44
.OP \-\-authenticate
45 46 47 48 49
.OP \-\-cookieonly
.OP \-\-printcookie
.OP \-\-cafile file
.OP \-\-disable\-ipv6
.OP \-\-dtls\-ciphers list
50
.OP \-\-dtls\-local\-port port
51
.OP \-\-dump\-http\-traffic
52
.OP \-\-no\-system\-trust
53
.OP \-\-pfs
54 55 56
.OP \-\-no\-dtls
.OP \-\-no\-http\-keepalive
.OP \-\-no\-passwd
57
.OP \-\-no\-xmlpost
58 59
.OP \-\-non\-inter
.OP \-\-passwd\-on\-stdin
David Woodhouse's avatar
David Woodhouse committed
60
.OP \-\-protocol proto
61 62
.OP \-\-token\-mode mode
.OP \-\-token\-secret {secret\fR[\fI,counter\fR]|@\fIfile\fR}
63
.OP \-\-reconnect\-timeout
64
.OP \-\-resolve host:ip
65 66
.OP \-\-servercert sha1
.OP \-\-useragent string
67
.OP \-\-local-hostname string
68
.OP \-\-os string
69 70
.B [https://]\fIserver\fB[:\fIport\fB][/\fIgroup\fB]
.YS
David Woodhouse's avatar
David Woodhouse committed
71 72 73 74 75 76 77 78 79 80 81 82 83

.SH DESCRIPTION
The program
.B openconnect
connects to Cisco "AnyConnect" VPN servers, which use standard TLS
and DTLS protocols for data transport.

The connection happens in two phases. First there is a simple HTTPS
connection over which the user authenticates somehow \- by using a
certificate, or password or SecurID, etc.  Having authenticated, the
user is rewarded with an HTTP cookie which can be used to make the
real VPN connection.

84
The second phase uses that cookie in an HTTPS
David Woodhouse's avatar
David Woodhouse committed
85 86 87 88
.I CONNECT
request, and data packets can be passed over the resulting
connection. In auxiliary headers exchanged with the
.I CONNECT
89
request, a Session\-ID and Master Secret for a DTLS connection are also
David Woodhouse's avatar
David Woodhouse committed
90 91 92 93 94
exchanged, which allows data transport over UDP to occur.


.SH OPTIONS
.TP
95 96 97 98 99 100 101 102 103 104 105 106
.B \-\-config=CONFIGFILE
Read further options from
.I CONFIGFILE
before continuing to process options from the command line. The file
should contain long-format options as would be accepted on the command line,
but without the two leading \-\- dashes. Empty lines, or lines where the
first non-space character is a # character, are ignored.

Any option except the
.B config
option may be specified in the file.
.TP
107
.B \-b,\-\-background
108 109
Continue in background after startup
.TP
110
.B \-\-pid\-file=PIDFILE
Steven Allen's avatar
Steven Allen committed
111 112 113 114
Save the pid to
.I PIDFILE
when backgrounding
.TP
115
.B \-c,\-\-certificate=CERT
David Woodhouse's avatar
David Woodhouse committed
116 117
Use SSL client certificate
.I CERT
118 119
which may be either a file name or, if OpenConnect has been built with an appropriate
version of GnuTLS, a PKCS#11 URL.
David Woodhouse's avatar
David Woodhouse committed
120
.TP
121
.B \-e,\-\-cert\-expire\-warning=DAYS
122 123 124 125
Give a warning when SSL client certificate has
.I DAYS
left before expiry
.TP
126
.B \-k,\-\-sslkey=KEY
127
Use SSL private key
David Woodhouse's avatar
David Woodhouse committed
128
.I KEY
129 130
which may be either a file name or, if OpenConnect has been built with an appropriate
version of GnuTLS, a PKCS#11 URL.
David Woodhouse's avatar
David Woodhouse committed
131
.TP
132
.B \-C,\-\-cookie=COOKIE
133
Use WebVPN cookie.
David Woodhouse's avatar
David Woodhouse committed
134 135
.I COOKIE
.TP
136
.B \-\-cookie\-on\-stdin
137
Read cookie from standard input.
David Woodhouse's avatar
David Woodhouse committed
138
.TP
139
.B \-d,\-\-deflate
140 141
Enable all compression, including stateful modes. By default, only stateless
compression algorithms are enabled.
David Woodhouse's avatar
David Woodhouse committed
142
.TP
143
.B \-D,\-\-no\-deflate
144
Disable all compression.
David Woodhouse's avatar
David Woodhouse committed
145
.TP
146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162
.B \-\-compression=MODE
Set compression mode, where
.I MODE
is one of
.I "stateless"
,
.I "none"
, or
.I "all".

By default, only stateless compression algorithms which do not maintain state
from one packet to the next (and which can be used on UDP transports) are
enabled. By setting the mode to
.I "all"
stateful algorithms (currently only zlib deflate) can be enabled. Or all
compression can be disabled by setting the mode to
.I "none".
163
.TP
164
.B \-\-force\-dpd=INTERVAL
David Woodhouse's avatar
David Woodhouse committed
165 166 167 168
Use
.I INTERVAL
as minimum Dead Peer Detection interval for CSTP and DTLS, forcing use of DPD even when the server doesn't request it.
.TP
169
.B \-g,\-\-usergroup=GROUP
David Woodhouse's avatar
David Woodhouse committed
170 171 172 173
Use
.I GROUP
as login UserGroup
.TP
174
.B \-h,\-\-help
David Woodhouse's avatar
David Woodhouse committed
175 176
Display help text
.TP
177 178 179 180 181 182 183 184 185
.B \-\-http\-auth=METHODS
Use only the specified methods for HTTP authentication to a server.  By default,
only Negotiate, NTLM and Digest authentication are enabled. Basic authentication
is also supported but because it is insecure it must be explicitly enabled. The
argument is a comma-separated list of methods to be enabled. Note that the order
does not matter: OpenConnect will use Negotiate, NTLM, Digest and Basic
authentication in that order, if each is enabled, regardless of the order
specified in the METHODS string.
.TP
186
.B \-i,\-\-interface=IFNAME
David Woodhouse's avatar
David Woodhouse committed
187 188 189 190
Use
.I IFNAME
for tunnel interface
.TP
191
.B \-l,\-\-syslog
David Woodhouse's avatar
David Woodhouse committed
192 193
Use syslog for progress messages
.TP
194 195 196
.B \-\-timestamp
Prepend a timestamp to each progress message
.TP
197 198 199
.B \-\-passtos
Copy TOS / TCLASS of payload packet into DTLS packets.
.TP
200
.B \-U,\-\-setuid=USER
David Woodhouse's avatar
David Woodhouse committed
201 202 203
Drop privileges after connecting, to become user
.I USER
.TP
204
.B \-\-csd\-user=USER
Paul Brook's avatar
Paul Brook committed
205 206
Drop privileges during CSD (Cisco Secure Desktop) script execution.
.TP
207
.B \-\-csd\-wrapper=SCRIPT
Paul Brook's avatar
Paul Brook committed
208 209 210
Run
.I SCRIPT
instead of the CSD (Cisco Secure Desktop) script.
211
.TP
212
.B \-m,\-\-mtu=MTU
David Woodhouse's avatar
David Woodhouse committed
213 214
Request
.I MTU
215 216
from server as the MTU of the tunnel.
.TP
217
.B \-\-base\-mtu=MTU
218 219 220 221 222
Indicate
.I MTU
as the path MTU between client and server on the unencrypted network. Newer
servers will automatically calculate the MTU to be used on the tunnel from
this value.
David Woodhouse's avatar
David Woodhouse committed
223
.TP
224
.B \-p,\-\-key\-password=PASS
225 226
Provide passphrase for certificate file, or SRK (System Root Key) PIN for TPM
.TP
227
.B \-P,\-\-proxy=PROXYURL
228 229 230 231
Use HTTP or SOCKS proxy for connection. A username and password can be provided
in the given URL, and will be used for authentication. If authentication is
required but no credentials are given, GSSAPI and automatic NTLM authentication
using Samba's ntlm_auth helper tool may be attempted.
232
.TP
233
.B \-\-proxy\-auth=METHODS
234 235 236 237 238 239 240
Use only the specified methods for HTTP authentication to a proxy.  By default,
only Negotiate, NTLM and Digest authentication are enabled. Basic authentication
is also supported but because it is insecure it must be explicitly enabled. The
argument is a comma-separated list of methods to be enabled. Note that the order
does not matter: OpenConnect will use Negotiate, NTLM, Digest and Basic
authentication in that order, if each is enabled, regardless of the order
specified in the METHODS string.
241
.TP
242
.B \-\-no\-proxy
243
Disable use of proxy
244
.TP
245
.B \-\-libproxy
246 247
Use libproxy to configure proxy automatically (when built with libproxy support)
.TP
248
.B \-\-key\-password\-from\-fsid
249 250 251 252 253 254 255 256 257 258 259
Passphrase for certificate file is automatically generated from the
.I fsid
of the file system on which it is stored. The
.I fsid
is obtained from the 
.BR statvfs (2)
or
.BR statfs (2)
system call, depending on the operating system. On a Linux or similar system
with GNU coreutils, the
.I fsid
260 261 262 263 264
used by this option should be equal to the output of the command:
.EX
stat \-\-file\-system \-\-printf=%i\e\en $CERTIFICATE
.EE
It is not the same as the 128\-bit UUID of the file system.
265
.TP
266
.B \-q,\-\-quiet
David Woodhouse's avatar
David Woodhouse committed
267 268
Less output
.TP
269
.B \-Q,\-\-queue\-len=LEN
270
Set packet queue limit to
David Woodhouse's avatar
David Woodhouse committed
271 272 273
.I LEN
pkts
.TP
274 275 276 277 278 279 280 281 282
.B \-s,\-\-script=SCRIPT
Invoke
.I SCRIPT
to configure the network after connection. Without this, routing and name
service are unlikely to work correctly. The script is expected to be
compatible with the
.B vpnc\-script
which is shipped with the "vpnc" VPN client. See
.I http://www.infradead.org/openconnect/vpnc-script.html
283 284 285 286 287 288 289
for more information. This version of OpenConnect is configured to
use \fB@DEFAULT_VPNCSCRIPT@\fR by default.

On Windows, a relative directory for the default script will be handled as
starting from the directory that the openconnect executable is running from,
rather than the current directory. The script will be invoked with the
command-based script host \fBcscript.exe\fR.
290 291
.TP
.B \-S,\-\-script\-tun
292 293 294 295
Pass traffic to 'script' program over a UNIX socket, instead of to a kernel
tun/tap device. This allows the VPN IP traffic to be handled entirely in
userspace, for example by a program which uses lwIP to provide SOCKS access
into the VPN.
David Woodhouse's avatar
David Woodhouse committed
296
.TP
297
.B \-u,\-\-user=NAME
David Woodhouse's avatar
David Woodhouse committed
298 299 300
Set login username to
.I NAME
.TP
301
.B \-V,\-\-version
David Woodhouse's avatar
David Woodhouse committed
302 303
Report version number
.TP
304
.B \-v,\-\-verbose
305
More output (may be specified multiple times for additional output)
David Woodhouse's avatar
David Woodhouse committed
306
.TP
307
.B \-x,\-\-xmlconfig=CONFIG
David Woodhouse's avatar
David Woodhouse committed
308 309
XML config file
.TP
310
.B \-\-authgroup=GROUP
311 312
Choose authentication login selection
.TP
313
.B \-\-authenticate
314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332
Authenticate only, and output the information needed to make the connection
a form which can be used to set shell environment variables. When invoked with
this option, openconnect will not make the connection, but if successful will
output something like the following to stdout:
.nf
.B COOKIE=3311180634@13561856@1339425499@B315A0E29D16C6FD92EE...
.B HOST=10.0.0.1
.B FINGERPRINT=469bb424ec8835944d30bc77c77e8fc1d8e23a42
.fi
Thus, you can invoke openconnect as a non-privileged user
.I (with access to the user's PKCS#11 tokens, etc.)
for authentication, and then invoke openconnect separately to make the actual
connection as root:
.nf
.B eval `openconnect --authenticate https://vpnserver.example.com`;
.B [ -n "$COOKIE" ] && echo "$COOKIE" |
.B \ \ sudo openconnect --cookie-on-stdin $HOST --servercert $FINGERPRINT
.fi
.TP
333
.B \-\-cookieonly
David Woodhouse's avatar
David Woodhouse committed
334 335
Fetch webvpn cookie only; don't connect
.TP
336
.B \-\-printcookie
David Woodhouse's avatar
David Woodhouse committed
337 338
Print webvpn cookie before connecting
.TP
339
.B \-\-cafile=FILE
David Woodhouse's avatar
David Woodhouse committed
340 341
Cert file for server verification
.TP
342
.B \-\-disable\-ipv6
David Woodhouse's avatar
David Woodhouse committed
343 344
Do not advertise IPv6 capability to server
.TP
345
.B \-\-dtls\-ciphers=LIST
346
Set OpenSSL ciphers to support for DTLS
347
.TP
348 349 350 351 352 353 354 355 356
.B \-\-dtls\-local\-port=PORT
Use
.I PORT
as the local port for DTLS datagrams
.TP
.B \-\-dump\-http\-traffic
Enable verbose output of all HTTP requests and the bodies of all responses
received from the server.
.TP
357 358 359 360 361
.B \-\-no\-system\-trust
Do not trust the system default certificate authorities. If this option is
given, only certificate authorities given with the
.B \-\-cafile
option, if any, will be trusted automatically.
362

363 364 365 366 367 368 369
.TP
.B \-\-pfs
Enforces Perfect Forward Secrecy (PFS). That ensures that if the server's
long-term key is compromised, any session keys established before the compromise
will be unaffected. If this option is provided and the server does not support PFS
in the TLS channel the connection will fail.

370 371 372 373 374
PFS is available in Cisco ASA releases 9.1(2) and higher; a suitable cipher
suite may need to be manually enabled by the administrator using the
.B ssl encryption
setting.

375
.TP
376
.B \-\-no\-dtls
David Woodhouse's avatar
David Woodhouse committed
377 378
Disable DTLS
.TP
379
.B \-\-no\-http\-keepalive
380
Version 8.2.2.5 of the Cisco ASA software has a bug where it will forget
381
the client's SSL certificate when HTTP connections are being re\-used for
382 383
multiple requests. So far, this has only been seen on the initial connection,
where the server gives an HTTP/1.0 redirect response with an explicit
384
.B Connection: Keep\-Alive
385 386 387 388 389 390
directive. OpenConnect as of v2.22 has an unconditional workaround for this,
which is never to obey that directive after an HTTP/1.0 response.

However, Cisco's support team has failed to give any competent
response to the bug report and we don't know under what other
circumstances their bug might manifest itself. So this option exists
391
to disable ALL re\-use of HTTP sessions and cause a new connection to be
392 393 394
made for each request. If your server seems not to be recognising your
certificate, try this option. If it makes a difference, please report
this information to the
395
.B openconnect\-devel@lists.infradead.org
396 397
mailing list.
.TP
398
.B \-\-no\-passwd
David Woodhouse's avatar
David Woodhouse committed
399 400
Never attempt password (or SecurID) authentication.
.TP
401 402 403 404 405 406 407 408 409 410 411 412 413
.B \-\-no\-xmlpost
Do not attempt to post an XML authentication/configuration request to the
server; use the old style GET method which was used by older clients and
servers instead.

This option is a temporary safety net, to work around potential
compatibility issues with the code which falls back to the old method
automatically. It causes OpenConnect to behave more like older
versions (4.08 and below) did. If you find that you need to use this
option, then you have found a bug in OpenConnect. Please see
http://www.infradead.org/openconnect/mail.html and report this to the
developers.
.TP
414
.B \-\-non\-inter
David Woodhouse's avatar
David Woodhouse committed
415
Do not expect user input; exit if it is required.
416
.TP
417
.B \-\-passwd\-on\-stdin
David Woodhouse's avatar
David Woodhouse committed
418
Read password from standard input
David Woodhouse's avatar
David Woodhouse committed
419 420 421 422 423 424 425 426 427 428 429
.TP
.B \-\-protocol=PROTO
Select VPN protocol
.I PROTO
to be used for the connection. Supported protocols are
.I anyconnect
for Cisco AnyConnect (the default), and
.I nc
for experimental support for Juniper Network Connect (also supported
by Junos Pulse servers).

430
.TP
431 432 433 434 435
.B \-\-token\-mode=MODE
Enable one-time password generation using the
.I MODE
algorithm.
.B \-\-token\-mode=rsa
436
will call libstoken to generate an RSA SecurID tokencode,
437
.B \-\-token\-mode=totp
438 439
will call liboath to generate an RFC 6238 time-based password, and
.B \-\-token\-mode=hotp
440 441 442
will call liboath to generate an RFC 4226 HMAC-based password. Yubikey
tokens which generate OATH codes in hardware are supported with
.B \-\-token\-mode=yubioath
443
.TP
444
.B \-\-token\-secret={ SECRET[,COUNTER] | @FILENAME }
445
The secret to use when generating one-time passwords/verification codes.
446 447 448 449
Base 32-encoded TOTP/HOTP secrets can be used by specifying "base32:" at the
beginning of the secret, and for HOTP secrets the token counter can be
specified following a comma.

450 451 452
RSA SecurID secrets can be specified as an Android/iPhone URI or a raw numeric
CTF string (with or without dashes).

453 454 455 456
For Yubikey OATH the token secret specifies the name of the credential to be
used. If not provided, the first OATH credential found on the device will be
used.

457 458 459 460
.IR FILENAME ,
if specified, can contain any of the above strings.  Or, it can contain a
SecurID XML (SDTID) seed.

461
If this option is omitted, and \-\-token\-mode is
462 463 464
"rsa", libstoken will try to use the software token seed saved in
.B ~/.stokenrc
by the "stoken import" command.
465
.TP
466
.B \-\-reconnect\-timeout
467 468 469
Keep reconnect attempts until so much seconds are elapsed. The default
timeout is 300 seconds, which means that openconnect can recover
VPN connection after a temporary network down time of 300 seconds.
470
.TP
471 472 473 474 475 476 477
.B \-\-resolve=HOST:IP
Automatically resolve the hostname
.IR HOST
to
.IR IP
instead of using the normal resolver to look it up.
.TP
478 479 480 481 482 483 484 485 486
.B \-\-servercert=HASH
Accept server's SSL certificate only if the provided fingerprint matches.
The allowed fingerprint types are
.IR SHA1 ,
and
.IR SHA256 .
They are distinguished by the 'sha1:' or 'sha256:' prefixes to the hex encoded
hash. To ease certain testing use-cases, a partial match of the hash will also
be accepted, if it is at least 4 characters.
Antonio Borneo's avatar
Antonio Borneo committed
487
.TP
488 489 490 491 492
.B \-\-useragent=STRING
Use
.I STRING
as 'User\-Agent:' field value in HTTP header.
(e.g. \-\-useragent 'Cisco AnyConnect VPN Agent for Windows 2.2.0133')
493
.TP
494 495 496 497 498 499
.B \-\-local-hostname=STRING
Use
.I STRING
as 'X\-CSTP\-Hostname:' field value in HTTP header. For example \-\-local\-hostname 'mypc',
will advertise the value 'mypc' as the suggested hostname to point to the provided IP address.
.TP
500
.B \-\-os=STRING
501 502 503 504 505 506 507 508 509 510 511 512
OS type to report to gateway.  Recognized values are:
.BR linux ,
.BR linux\-64 ,
.BR win ,
.BR mac\-intel ,
.BR android ,
.BR apple\-ios .
Reporting a different OS type may affect the dynamic access policy (DAP)
applied to the VPN session.  If the gateway requires CSD, it will also cause
the corresponding CSD trojan binary to be downloaded, so you may need to use
.B \-\-csd\-wrapper
if this code is not executable on the local machine.
513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530
.SH SIGNALS
In the data phase of the connection, the following signals are handled:
.TP
.B SIGINT
performs a clean shutdown by logging the session off, disconnecting from the
gateway, and running the vpnc\-script to restore the network configuration.
.TP
.B SIGHUP
disconnects from the gateway and runs the vpnc\-script, but does not log the
session off; this allows for reconnection later using
.BR \-\-cookie .
.TP
.B SIGUSR2
forces an immediate disconnection and reconnection; this can be used to
quickly recover from LAN IP address changes.
.TP
.B SIGTERM
exits immediately without logging off or running vpnc\-script.
David Woodhouse's avatar
David Woodhouse committed
531
.SH LIMITATIONS
532
Note that although IPv6 has been tested on all platforms on which
David Woodhouse's avatar
David Woodhouse committed
533
.B openconnect
534
is known to run, it depends on a suitable
535
.B vpnc\-script
536
to configure the network. The standard
537
.B vpnc\-script
538
shipped with vpnc 0.5.3 is not capable of setting up IPv6 routes; the one from
539
.B git://git.infradead.org/users/dwmw2/vpnc\-scripts.git
540
will be required.
David Woodhouse's avatar
David Woodhouse committed
541 542 543

.SH AUTHORS
David Woodhouse <dwmw2@infradead.org>