1OPENCONNECT(8) System Manager's Manual OPENCONNECT(8)
2
6 openconnect - Multi-protocol VPN client, for Cisco AnyConnect VPNs and
7 others
8
10 openconnect [--config configfile] [-b,--background]
11 [--pid-file pidfile] [-c,--certificate cert]
12 [-e,--cert-expire-warning days] [-k,--sslkey key]
13 [-C,--cookie cookie] [--cookie-on-stdin]
14 [--compression MODE] [-d,--deflate] [-D,--no-deflate]
15 [--force-dpd interval] [--force-trojan interval]
16 [-F,--form-entry form:opt=value] [-g,--usergroup group]
17 [-h,--help] [--http-auth methods] [-i,--interface ifname]
18 [-l,--syslog] [--timestamp] [--passtos] [-U,--setuid user]
19 [--csd-user user] [-m,--mtu mtu] [--base-mtu mtu]
20 [-p,--key-password pass] [-P,--proxy proxyurl]
21 [--proxy-auth methods] [--no-proxy] [--libproxy]
22 [--key-password-from-fsid] [-q,--quiet]
23 [-Q,--queue-len len] [-s,--script vpnc-script]
24 [-S,--script-tun] [-u,--user name] [-V,--version]
25 [-v,--verbose] [-x,--xmlconfig config] [--authgroup group]
26 [--authenticate] [--cookieonly] [--printcookie]
27 [--cafile file] [--disable-ipv6] [--dtls-ciphers list]
28 [--dtls12-ciphers list] [--dtls-local-port port]
29 [--dump-http-traffic] [--no-system-trust] [--pfs]
30 [--no-dtls] [--no-http-keepalive] [--no-passwd]
31 [--no-xmlpost] [--non-inter] [--passwd-on-stdin]
32 [--protocol proto] [--token-mode mode]
33 [--token-secret {secret[,counter]|@file}]
34 [--reconnect-timeout seconds] [--resolve host:ip]
35 [--servercert sha1] [--useragent string]
36 [--version-string string] [--local-hostname string]
37 [--os string] [--server] [https://]host[:port][/group]
38
41 The program openconnect connects to VPN servers which use standard
42 TLS/SSL, DTLS, and ESP protocols for data transport.
43 It was originally written to support Cisco "AnyConnect" VPN servers,
45 and has since been extended with experimental support for Juniper Net‐
46 work Connect (--protocol=nc) Junos Pulse VPN servers, (--proto‐
47 col=pulse) PAN GlobalProtect VPN servers, (--protocol=gp) F5 Big-IP VPN
48 servers, (--protocol=f5) Fortinet Fortigate VPN servers, (--proto‐
49 col=fortinet) and Array Networks SSL VPN servers, (--protocol=array)
50 The connection happens in two phases. First there is a simple HTTPS
52 connection over which the user authenticates somehow - by using a cer‐
53 tificate, or password or SecurID, etc. Having authenticated, the user
54 is rewarded with an authentication cookie which can be used to make the
55 real VPN connection.
56 The second phase uses that cookie to connect to a tunnel via HTTPS, and
58 data packets can be passed over the resulting connection. When possi‐
59 ble, a UDP tunnel is also configured: AnyConnect uses DTLS, while Ju‐
60 niper and GlobalProtect use UDP-encapsulated ESP. The UDP tunnel may be
61 disabled with --no-dtls, but is preferred when correctly supported by
62 the server and network for performance reasons. (TCP performs poorly
63 and unreliably over TCP-based tunnels; see
64 http://sites.inka.de/~W1011/devel/tcp-tcp.html.)
65
68 --config=CONFIGFILE
69 Read further options from CONFIGFILE before continuing to
70 process options from the command line. The file should contain
71 long-format options as would be accepted on the command line,
72 but without the two leading -- dashes. Empty lines, or lines
73 where the first non-space character is a # character, are ig‐
74 nored.
75 Any option except the config option may be specified in the
77 file.
78 -b,--background
80 Continue in background after startup
81 --pid-file=PIDFILE
83 Save the pid to PIDFILE when backgrounding
84 -c,--certificate=CERT [,--mca-certificate=CERT]
86 Use SSL client certificate CERT which may be either a file name
87 or, if OpenConnect has been built with an appropriate version of
88 GnuTLS, a PKCS#11 URL.
89 The --mca-certificate option sets the secondary certificate for
91 multi-certificate authentication (according to Cisco's terminol‐
92 ogy, the SSL client certificate is called the "machine" certifi‐
93 cate, and the second certificate is called the "user" certifi‐
94 cate).
95 -e,--cert-expire-warning=DAYS
97 Give a warning when SSL client certificate has DAYS left before
98 expiry
99 -k,--sslkey=KEY [,--mca-key=KEY]
101 Use SSL private key KEY which may be either a file name or, if
102 OpenConnect has been built with an appropriate version of
103 GnuTLS, a PKCS#11 URL.
104 The --mca-key option sets the private key for the secondary cer‐
106 tificate (see --mca-certificate ).
107 -C,--cookie=COOKIE
109 Use authentication cookie COOKIE.
110 --cookie-on-stdin
112 Read cookie from standard input.
113 -d,--deflate
115 Enable all compression, including stateful modes. By default,
116 only stateless compression algorithms are enabled.
117 -D,--no-deflate
119 Disable all compression.
120 --compression=MODE
122 Set compression mode, where MODE is one of stateless, none, or
123 all.
124 By default, only stateless compression algorithms which do not
126 maintain state from one packet to the next (and which can be
127 used on UDP transports) are enabled. By setting the mode to all
128 stateful algorithms (currently only zlib deflate) can be en‐
129 abled. Or all compression can be disabled by setting the mode to
130 none.
131 --force-dpd=INTERVAL
133 Use INTERVAL as Dead Peer Detection interval (in seconds). This
134 will cause the client to use DPD at the specified interval even
135 if the server hasn't requested it, or at a different interval
136 from the one requested by the server.
137 DPD mechanisms vary by protocol and by transport (TLS or
139 DTLS/ESP), but are all functionally similar: they enable either
140 the VPN client or the VPN server to transmit a signal to the
141 peer, requesting an immediate reply which can be used to confirm
142 that the link between the two peers is still working.
143 -g,--usergroup=GROUP
145 Use GROUP as login UserGroup
146 -F,--form-entry=FORM:OPTION=VALUE
148 Provide authentication form input, where FORM and OPTION are the
149 identifiers from the form and the specific input field, and
150 VALUE is the string to be filled in automatically. For example,
151 the standard username field (also handled by the --user option)
152 could also be provided with this option thus: --form-entry
153 main:username=joebloggs.
154 This option should not be used to enter passwords.
156 --passwd-on-stdin should be used for that purpose. Not only will
157 this option expose the password value via the OpenConnect
158 process's command line, but unlike --passwd-on-stdin this option
159 will not recognize the case of an incorrect password, and stop
160 trying to re-enter it repeatedly.
161 -h,--help
163 Display help text
164 --http-auth=METHODS
166 Use only the specified methods for HTTP authentication to a
167 server. By default, only Negotiate, NTLM and Digest authentica‐
168 tion are enabled. Basic authentication is also supported but be‐
169 cause it is insecure it must be explicitly enabled. The argument
170 is a comma-separated list of methods to be enabled. Note that
171 the order does not matter: OpenConnect will use Negotiate, NTLM,
172 Digest and Basic authentication in that order, if each is en‐
173 abled, regardless of the order specified in the METHODS string.
174 -i,--interface=IFNAME
176 Use IFNAME for tunnel interface
177 -l,--syslog
179 After tunnel is brought up, use syslog for further progress mes‐
180 sages
181 --timestamp
183 Prepend a timestamp to each progress message
184 --passtos
186 Copy TOS / TCLASS of payload packet into DTLS and ESP packets.
187 This is not set by default because it may leak information about
188 the payload (for example, by differentiating voice/video traf‐
189 fic).
190 -U,--setuid=USER
192 Drop privileges after connecting, to become user USER
193 --csd-user=USER
195 Drop privileges during execution of trojan binary or script
196 (CSD, TNCC, or HIP).
197 --csd-wrapper=SCRIPT
199 Run SCRIPT instead of the trojan binary or script.
200 --force-trojan=INTERVAL
202 Use INTERVAL as interval (in seconds) for repeat execution of
203 Trojan binary or script, overriding default and/or server-set
204 interval.
205 -m,--mtu=MTU
207 Request MTU from server as the MTU of the tunnel.
208 --base-mtu=MTU
210 Indicate MTU as the path MTU between client and server on the
211 unencrypted network. Newer servers will automatically calculate
212 the MTU to be used on the tunnel from this value.
213 -p,--key-password=PASS [,--mca-key-password=PASS]
215 Provide passphrase for certificate file, or SRK (System Root
216 Key) PIN for TPM
217 --mca-key-password provides the passphrase for the secondary
219 certificate (see --mca-certificate ).
220 -P,--proxy=PROXYURL
222 Use HTTP or SOCKS proxy for connection. A username and password
223 can be provided in the given URL, and will be used for authenti‐
224 cation. If authentication is required but no credentials are
225 given, GSSAPI and automatic NTLM authentication using Samba's
226 ntlm_auth helper tool may be attempted.
227 --proxy-auth=METHODS
229 Use only the specified methods for HTTP authentication to a
230 proxy. By default, only Negotiate, NTLM and Digest authentica‐
231 tion are enabled. Basic authentication is also supported but be‐
232 cause it is insecure it must be explicitly enabled. The argument
233 is a comma-separated list of methods to be enabled. Note that
234 the order does not matter: OpenConnect will use Negotiate, NTLM,
235 Digest and Basic authentication in that order, if each is en‐
236 abled, regardless of the order specified in the METHODS string.
237 --no-proxy
239 Disable use of proxy
240 --libproxy
242 Use libproxy to configure proxy automatically (when built with
243 libproxy support)
244 --key-password-from-fsid
246 Passphrase for certificate file is automatically generated from
247 the fsid of the file system on which it is stored. The fsid is
248 obtained from the statvfs(2) or statfs(2) system call, depending
249 on the operating system. On a Linux or similar system with GNU
250 coreutils, the fsid used by this option should be equal to the
251 output of the command:
252 stat --file-system --printf=%i\\n $CERTIFICATE
253 It is not the same as the 128-bit UUID of the file system.
254 -q,--quiet
256 Less output
257 -Q,--queue-len=LEN
259 Set packet queue limit to LEN packets. The default is 10. A high
260 value may allow better overall bandwidth but at a cost of la‐
261 tency. If you run Voice over IP or other interactive traffic
262 over the VPN, you don't want those packets to be queued behind
263 thousands of other large packets which are part of a bulk trans‐
264 fer.
265 This option sets the maximum inbound and outbound packet queue
267 sizes in OpenConnect itself, which control how many packets will
268 be sent and received in a single batch, as well as affecting
269 other buffering such as the socket send buffer (SO_SNDBUF) for
270 network connections and the OS tunnel device.
271 Ultimately, the right size for a queue is "just enough packets
273 that it never quite gets empty before more are pushed to it".
274 Any higher than that is simply introducing bufferbloat and addi‐
275 tional latency with no benefit. With the default of 10, we are
276 able to saturate a single Gigabit Ethernet from modest hardware,
277 which is more than enough for most VPN users.
278 If OpenConnect is built with vhost-net support, it will only be
280 used if the queue length is set to 16 or more. This is because
281 vhost-net introduces a small amount of additional latency, but
282 improves total bandwidth quite considerably for those operating
283 at high traffic rates. Thus it makes sense to use it when the
284 user has indicated a preference for bandwidth over latency, by
285 increasing the queue size.
286 -s,--script=SCRIPT
289 Invoke SCRIPT to configure the network after connection. Without
290 this, routing and name service are unlikely to work correctly.
291 The script is expected to be compatible with the vpnc-script
292 which is shipped with the "vpnc" VPN client. See https://www.in‐
293 fradead.org/openconnect/vpnc-script.html for more information.
294 This version of OpenConnect is configured to use /etc/vpnc/vpnc-
295 script by default.
296 On Windows, a relative directory for the default script will be
298 handled as starting from the directory that the openconnect exe‐
299 cutable is running from, rather than the current directory. The
300 script will be invoked with the command-based script host
301 cscript.exe.
302 -S,--script-tun
304 Pass traffic to 'script' program over a UNIX socket, instead of
305 to a kernel tun/tap device. This allows the VPN IP traffic to be
306 handled entirely in userspace, for example by a program which
307 uses lwIP to provide SOCKS access into the VPN.
308 --server=[https://]HOST[:PORT][/GROUP]
310 Define the VPN server as a simple HOST or as an URL containing
311 the HOST and optionally the PORT number and the login GROUP or
312 realm.
313 As an alternative, define the VPN server as non-option command
315 line argument.
316 -u,--user=NAME
318 Set login username to NAME
319 -V,--version
321 Report version number
322 -v,--verbose
324 More output (may be specified multiple times for additional out‐
325 put)
326 -x,--xmlconfig=CONFIG
328 XML config file
329 --authgroup=GROUP
331 Choose authentication login selection
332 --authenticate
334 Authenticate to the VPN, output the information needed to make
335 the connection in a form which can be used to set shell environ‐
336 ment variables, and then exit.
337 When invoked with this option, OpenConnect will not actually
339 create the VPN connection or configure a tunnel interface, but
340 if successful will print something like the following to stdout:
341 COOKIE='3311180634@13561856@1339425499@B315A0E29D16C6FD92EE...'
342 HOST='10.0.0.1'
343 CONNECT_URL='https://vpnserver.example.com'
344 FINGERPRINT='469bb424ec8835944d30bc77c77e8fc1d8e23a42'
345 RESOLVE='vpnserver.example.com:10.0.0.1'
346 Thus, you can invoke openconnect as a non-privileged user (with
347 access to the user's PKCS#11 tokens, etc.) for authentication,
348 and then invoke openconnect separately to make the actual con‐
349 nection as root:
350 eval `openconnect --authenticate https://vpnserver.example.com`;
351 [ -n $COOKIE ] && echo $COOKIE |
352 sudo openconnect --cookie-on-stdin $CONNECT_URL --servercert $FINGERPRINT --resolve $RESOLVE
353 Earlier versions of OpenConnect produced only the HOST variable
355 (containing the numeric server address), and not the CONNECT_URL
356 or RESOLVE variables. Subsequently, we discovered that servers
357 behind proxies may not respond correctly unless the correct DNS
358 name is present in the connection phase, and we added support
359 for VPN protocols where the server URL's path component may be
360 significant in the connection phase, prompting the addition of
361 CONNECT_URL and RESOLVE, and the recommendation to use them as
362 described above. If you are not certain that you are invoking a
363 newer version of OpenConnect which outputs these variables, use
364 the following command-line (compatible with most Bourne shell
365 derivatives) which will work with either a newer or older ver‐
366 sion:
367 sudo openconnect --cookie-on-stdin ${CONNECT_URL:-$HOST} --servercert $FINGERPRINT ${RESOLVE:+--resolve=$RESOLVE}
368 --cookieonly
370 Fetch and print cookie only; don't connect (this is essentially
371 a subset of --authenticate).
372 --printcookie
374 Print cookie to stdout before connecting (see --authenticate for
375 the meaning of this cookie)
376 --cafile=FILE
378 Additional CA file for server verification. By default, this
379 simply causes OpenConnect to trust additional root CA certifi‐
380 cate(s) in addition to those trusted by the system. Use
381 --no-system-trust to prevent OpenConnect from trusting the sys‐
382 tem default certificate authorities.
383 --no-system-trust
385 Do not trust the system default certificate authorities. If this
386 option is given, only certificate authorities given with the
387 --cafile option, if any, will be trusted automatically.
388 --disable-ipv6
390 Do not advertise IPv6 capability to server
391 --dtls-ciphers=LIST
393 Set OpenSSL ciphers to support for DTLS
394 --dtls12-ciphers=LIST
396 Set OpenSSL ciphers for Cisco's DTLS v1.2
397 --dtls-local-port=PORT
399 Use PORT as the local port for DTLS and UDP datagrams
400 --dump-http-traffic
402 Enable verbose output of all HTTP requests and the bodies of all
403 responses received from the server.
404 --pfs Enforces Perfect Forward Secrecy (PFS). That ensures that if the
407 server's long-term key is compromised, any session keys estab‐
408 lished before the compromise will be unaffected. If this option
409 is provided and the server does not support PFS in the TLS chan‐
410 nel the connection will fail.
411 PFS is available in Cisco ASA releases 9.1(2) and higher; a
413 suitable cipher suite may need to be manually enabled by the ad‐
414 ministrator using the ssl encryption setting.
415 --no-dtls
418 Disable DTLS and ESP
419 --no-http-keepalive
421 Version 8.2.2.5 of the Cisco ASA software has a bug where it
422 will forget the client's SSL certificate when HTTP connections
423 are being re-used for multiple requests. So far, this has only
424 been seen on the initial connection, where the server gives an
425 HTTP/1.0 redirect response with an explicit Connection:
426 Keep-Alive directive. OpenConnect as of v2.22 has an uncondi‐
427 tional workaround for this, which is never to obey that direc‐
428 tive after an HTTP/1.0 response.
429 However, Cisco's support team has failed to give any competent
431 response to the bug report and we don't know under what other
432 circumstances their bug might manifest itself. So this option
433 exists to disable ALL re-use of HTTP sessions and cause a new
434 connection to be made for each request. If your server seems not
435 to be recognizing your certificate, try this option. If it makes
436 a difference, please report this information to the opencon‐
437 nect-devel@lists.infradead.org mailing list.
438 --no-passwd
440 Never attempt password (or SecurID) authentication.
441 --no-xmlpost
443 Do not attempt to post an XML authentication/configuration re‐
444 quest to the server; use the old style GET method which was used
445 by older clients and servers instead.
446 This option is a temporary safety net, to work around potential
448 compatibility issues with the code which falls back to the old
449 method automatically. It causes OpenConnect to behave more like
450 older versions (4.08 and below) did. If you find that you need
451 to use this option, then you have found a bug in OpenConnect.
452 Please see https://www.infradead.org/openconnect/mail.html and
453 report this to the developers.
454 --allow-insecure-crypto
456 The ancient, broken 3DES and RC4 ciphers are insecure; we ex‐
457 plicitly disable them by default. However, some still-in-use VPN
458 servers can't do any better.
459 This option enables use of these insecure ciphers, as well as
461 the use of SHA1 for server certificate validation.
462 --non-inter
464 Do not expect user input; exit if it is required.
465 --passwd-on-stdin
467 Read password from standard input
468 --protocol=PROTO
470 Select VPN protocol PROTO to be used for the connection. Sup‐
471 ported protocols are anyconnect for Cisco AnyConnect (the de‐
472 fault), nc for experimental support for Juniper Network Connect
473 (also supported by most Junos Pulse servers), pulse for experi‐
474 mental support for Junos Pulse, gp for experimental support for
475 PAN GlobalProtect, f5 for experimental support for F5 Big-IP,
476 fortinet for experimental support for Fortinet Fortigate, and
477 array for experimental support for Array Networks SSL VPN.
478 See https://www.infradead.org/openconnect/protocols.html for de‐
480 tails on features and deficiencies of the individual protocols.
481 OpenConnect does not yet support all of the authentication op‐
483 tions used by Pulse, nor does it support Host Checker/TNCC with
484 Pulse. If your Junos Pulse VPN is not yet supported with --pro‐
485 tocol=pulse, then --protocol=nc may be a useful fallback option.
486 --token-mode=MODE
488 Enable one-time password generation using the MODE algorithm.
489 --token-mode=rsa will call libstoken to generate an RSA SecurID
490 tokencode, --token-mode=totp will call liboath to generate an
491 RFC 6238 time-based password, and --token-mode=hotp will call
492 liboath to generate an RFC 4226 HMAC-based password. Yubikey to‐
493 kens which generate OATH codes in hardware are supported with
494 --token-mode=yubioath. --token-mode=oidc will use the provided
495 OpenIDConnect token as an RFC 6750 bearer token.
496 --token-secret={ SECRET[,COUNTER] | @FILENAME }
498 The secret to use when generating one-time passwords/verifica‐
499 tion codes. Base 32-encoded TOTP/HOTP secrets can be used by
500 specifying "base32:" at the beginning of the secret, and for
501 HOTP secrets the token counter can be specified following a
502 comma.
503 RSA SecurID secrets can be specified as an Android/iPhone URI or
505 a raw numeric CTF string (with or without dashes).
506 For Yubikey OATH the token secret specifies the name of the cre‐
508 dential to be used. If not provided, the first OATH credential
509 found on the device will be used.
510 For OIDC the secret is the bearer token to be used.
512 FILENAME, if specified, can contain any of the above strings.
514 Or, it can contain a SecurID XML (SDTID) seed.
515 If this option is omitted, and --token-mode is "rsa", libstoken
517 will try to use the software token seed saved in ~/.stokenrc by
518 the "stoken import" command.
519 --reconnect-timeout=SECONDS
521 After disconnection or Dead Peer Detection, keep trying to re‐
522 connect for SECONDS. The default is 300 seconds, which means
523 that openconnect can recover a VPN connection after a temporary
524 network outage lasting up to 300 seconds.
525 --resolve=HOST:IP
527 Automatically resolve the hostname HOST to IP instead of using
528 the normal resolver to look it up.
529 --servercert=HASH
531 Accept server's SSL certificate only if it matches the provided
532 fingerprint. This option implies --no-system-trust, and may be
533 specified multiple times in order to accept multiple possible
534 fingerprints.
535 The allowed fingerprint types are SHA1, SHA256, and PIN-SHA256.
537 They are distinguished by the 'sha1:', 'sha256:' and 'pin-
538 sha256:' prefixes to the encoded hash. The first two are custom
539 identifiers providing hex encoding of the peer's public key,
540 while 'pin-sha256:' is the RFC7469 key PIN, which utilizes
541 base64 encoding. To ease certain testing use-cases, a partial
542 match of the hash will also be accepted, if it is at least 4
543 characters past the prefix.
544 --useragent=STRING
546 Use STRING as 'User-Agent:' field value in HTTP header. (e.g.
547 --useragent 'Cisco AnyConnect VPN Agent for Windows 2.2.0133')
548 --version-string=STRING
550 Use STRING as the software version reported to the head end.
551 (e.g. --version-string '2.2.0133')
552 --local-hostname=STRING
554 Use STRING as 'X-CSTP-Hostname:' field value in HTTP header. For
555 example --local-hostname 'mypc', will advertise the value 'mypc'
556 as the suggested hostname to point to the provided IP address.
557 --os=STRING
559 OS type to report to gateway. Recognized values are: linux,
560 linux-64, win, mac-intel, android, apple-ios. Reporting a dif‐
561 ferent OS type may affect the dynamic access policy (DAP) ap‐
562 plied to the VPN session. If the gateway requires CSD, it will
563 also cause the corresponding CSD trojan binary to be downloaded,
564 so you may need to use --csd-wrapper if this code is not exe‐
565 cutable on the local machine.
566
568 In the data phase of the connection, the following signals are handled:
569 SIGINT / SIGTERM
571 performs a clean shutdown by logging the session off, discon‐
572 necting from the gateway, and running the vpnc-script to restore
573 the network configuration.
574 SIGHUP disconnects from the gateway and runs the vpnc-script, but does
576 not log the session off; this allows for reconnection later us‐
577 ing --cookie.
578 SIGUSR1
580 writes progress message with detailed connection information and
581 statistics.
582 SIGUSR2
584 forces an immediate disconnection and reconnection; this can be
585 used to quickly recover from LAN IP address changes.
586 LIMITATIONS
589 Note that although IPv6 has been tested on all platforms on
590 which openconnect is known to run, it depends on a suitable
591 vpnc-script to configure the network. The standard vpnc-script
592 shipped with vpnc 0.5.3 is not capable of setting up IPv6
593 routes; the one from https://gitlab.com/openconnect/vpnc-scripts
594 will be required.
595
597 ocserv(8)
598
601 David Woodhouse <dwmw2@infradead.org>
602 OPENCONNECT(8)