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] [--resolve host:ip]
35 [--servercert sha1] [--useragent string]
36 [--version-string string] [--local-hostname string]
37 [--os string] [https://]server[: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) and Junos Pulse VPN servers (--proto‐
47 col=pulse) and PAN GlobalProtect VPN servers (--protocol=gp).
48 The connection happens in two phases. First there is a simple HTTPS
50 connection over which the user authenticates somehow - by using a cer‐
51 tificate, or password or SecurID, etc. Having authenticated, the user
52 is rewarded with an authentication cookie which can be used to make the
53 real VPN connection.
54 The second phase uses that cookie to connect to a tunnel via HTTPS, and
56 data packets can be passed over the resulting connection. When possi‐
57 ble, a UDP tunnel is also configured: AnyConnect uses DTLS, while
58 Juniper and GlobalProtect use UDP-encapsulated ESP. The UDP tunnel may
59 be disabled with --no-dtls, but is preferred when correctly supported
60 by the server and network for performance reasons. (TCP performs poorly
61 and unreliably over TCP-based tunnels; see
62 http://sites.inka.de/~W1011/devel/tcp-tcp.html.)
63
66 --config=CONFIGFILE
67 Read further options from CONFIGFILE before continuing to
68 process options from the command line. The file should contain
69 long-format options as would be accepted on the command line,
70 but without the two leading -- dashes. Empty lines, or lines
71 where the first non-space character is a # character, are
72 ignored.
73 Any option except the config option may be specified in the
75 file.
76 -b,--background
78 Continue in background after startup
79 --pid-file=PIDFILE
81 Save the pid to PIDFILE when backgrounding
82 -c,--certificate=CERT
84 Use SSL client certificate CERT which may be either a file name
85 or, if OpenConnect has been built with an appropriate version of
86 GnuTLS, a PKCS#11 URL.
87 -e,--cert-expire-warning=DAYS
89 Give a warning when SSL client certificate has DAYS left before
90 expiry
91 -k,--sslkey=KEY
93 Use SSL private key KEY which may be either a file name or, if
94 OpenConnect has been built with an appropriate version of
95 GnuTLS, a PKCS#11 URL.
96 -C,--cookie=COOKIE
98 Use authentication cookie COOKIE.
99 --cookie-on-stdin
101 Read cookie from standard input.
102 -d,--deflate
104 Enable all compression, including stateful modes. By default,
105 only stateless compression algorithms are enabled.
106 -D,--no-deflate
108 Disable all compression.
109 --compression=MODE
111 Set compression mode, where MODE is one of stateless, none, or
112 all.
113 By default, only stateless compression algorithms which do not
115 maintain state from one packet to the next (and which can be
116 used on UDP transports) are enabled. By setting the mode to all
117 stateful algorithms (currently only zlib deflate) can be
118 enabled. Or all compression can be disabled by setting the mode
119 to none.
120 --force-dpd=INTERVAL
122 Use INTERVAL as minimum Dead Peer Detection interval (in sec‐
123 onds) for CSTP and DTLS, forcing use of DPD even when the server
124 doesn't request it.
125 -g,--usergroup=GROUP
127 Use GROUP as login UserGroup
128 -F,--form-entry=FORM:OPTION=VALUE
130 Provide authentication form input, where FORM and OPTION are the
131 identifiers from the form and the specific input field, and
132 VALUE is the string to be filled in automatically. For example,
133 the standard username field (also handled by the --user option)
134 could also be provided with this option thus: --form-entry
135 main:username=joebloggs.
136 -h,--help
138 Display help text
139 --http-auth=METHODS
141 Use only the specified methods for HTTP authentication to a
142 server. By default, only Negotiate, NTLM and Digest authentica‐
143 tion are enabled. Basic authentication is also supported but
144 because it is insecure it must be explicitly enabled. The argu‐
145 ment is a comma-separated list of methods to be enabled. Note
146 that the order does not matter: OpenConnect will use Negotiate,
147 NTLM, Digest and Basic authentication in that order, if each is
148 enabled, regardless of the order specified in the METHODS
149 string.
150 -i,--interface=IFNAME
152 Use IFNAME for tunnel interface
153 -l,--syslog
155 Use syslog for progress messages
156 --timestamp
158 Prepend a timestamp to each progress message
159 --passtos
161 Copy TOS / TCLASS of payload packet into DTLS and ESP packets.
162 This is not set by default because it may leak information about
163 the payload (for example, by differentiating voice/video traf‐
164 fic).
165 -U,--setuid=USER
167 Drop privileges after connecting, to become user USER
168 --csd-user=USER
170 Drop privileges during execution of trojan binary or script
171 (CSD, TNCC, or HIP).
172 --csd-wrapper=SCRIPT
174 Run SCRIPT instead of the trojan binary or script.
175 --force-trojan=INTERVAL
177 Use INTERVAL as interval (in seconds) for repeat execution of
178 Trojan binary or script, overriding default and/or server-set
179 interval.
180 -m,--mtu=MTU
182 Request MTU from server as the MTU of the tunnel.
183 --base-mtu=MTU
185 Indicate MTU as the path MTU between client and server on the
186 unencrypted network. Newer servers will automatically calculate
187 the MTU to be used on the tunnel from this value.
188 -p,--key-password=PASS
190 Provide passphrase for certificate file, or SRK (System Root
191 Key) PIN for TPM
192 -P,--proxy=PROXYURL
194 Use HTTP or SOCKS proxy for connection. A username and password
195 can be provided in the given URL, and will be used for authenti‐
196 cation. If authentication is required but no credentials are
197 given, GSSAPI and automatic NTLM authentication using Samba's
198 ntlm_auth helper tool may be attempted.
199 --proxy-auth=METHODS
201 Use only the specified methods for HTTP authentication to a
202 proxy. By default, only Negotiate, NTLM and Digest authentica‐
203 tion are enabled. Basic authentication is also supported but
204 because it is insecure it must be explicitly enabled. The argu‐
205 ment is a comma-separated list of methods to be enabled. Note
206 that the order does not matter: OpenConnect will use Negotiate,
207 NTLM, Digest and Basic authentication in that order, if each is
208 enabled, regardless of the order specified in the METHODS
209 string.
210 --no-proxy
212 Disable use of proxy
213 --libproxy
215 Use libproxy to configure proxy automatically (when built with
216 libproxy support)
217 --key-password-from-fsid
219 Passphrase for certificate file is automatically generated from
220 the fsid of the file system on which it is stored. The fsid is
221 obtained from the statvfs(2) or statfs(2) system call, depending
222 on the operating system. On a Linux or similar system with GNU
223 coreutils, the fsid used by this option should be equal to the
224 output of the command:
225 stat --file-system --printf=%i\\n $CERTIFICATE
226 It is not the same as the 128-bit UUID of the file system.
227 -q,--quiet
229 Less output
230 -Q,--queue-len=LEN
232 Set packet queue limit to LEN pkts
233 -s,--script=SCRIPT
235 Invoke SCRIPT to configure the network after connection. Without
236 this, routing and name service are unlikely to work correctly.
237 The script is expected to be compatible with the vpnc-script
238 which is shipped with the "vpnc" VPN client. See
239 http://www.infradead.org/openconnect/vpnc-script.html for more
240 information. This version of OpenConnect is configured to use
241 /etc/vpnc/vpnc-script by default.
242 On Windows, a relative directory for the default script will be
244 handled as starting from the directory that the openconnect exe‐
245 cutable is running from, rather than the current directory. The
246 script will be invoked with the command-based script host
247 cscript.exe.
248 -S,--script-tun
250 Pass traffic to 'script' program over a UNIX socket, instead of
251 to a kernel tun/tap device. This allows the VPN IP traffic to be
252 handled entirely in userspace, for example by a program which
253 uses lwIP to provide SOCKS access into the VPN.
254 -u,--user=NAME
256 Set login username to NAME
257 -V,--version
259 Report version number
260 -v,--verbose
262 More output (may be specified multiple times for additional out‐
263 put)
264 -x,--xmlconfig=CONFIG
266 XML config file
267 --authgroup=GROUP
269 Choose authentication login selection
270 --authenticate
272 Authenticate only, and output the information needed to make the
273 connection a form which can be used to set shell environment
274 variables. When invoked with this option, openconnect will not
275 make the connection, but if successful will output something
276 like the following to stdout:
277 COOKIE=3311180634@13561856@1339425499@B315A0E29D16C6FD92EE...
278 HOST=10.0.0.1
279 FINGERPRINT=469bb424ec8835944d30bc77c77e8fc1d8e23a42
280 Thus, you can invoke openconnect as a non-privileged user (with
281 access to the user's PKCS#11 tokens, etc.) for authentication,
282 and then invoke openconnect separately to make the actual con‐
283 nection as root:
284 eval `openconnect --authenticate https://vpnserver.example.com`;
285 [ -n $COOKIE ] && echo $COOKIE |
286 sudo openconnect --cookie-on-stdin $HOST --servercert $FINGERPRINT
287 --cookieonly
289 Fetch and print cookie only; don't connect
290 --printcookie
292 Print cookie before connecting
293 --cafile=FILE
295 Additional CA file for server verification. By default, this
296 simply causes OpenConnect to trust additional root CA certifi‐
297 cate(s) in addition to those trusted by the system. Use
298 --no-system-trust to prevent OpenConnect from trusting the sys‐
299 tem default certificate authorities.
300 --no-system-trust
302 Do not trust the system default certificate authorities. If this
303 option is given, only certificate authorities given with the
304 --cafile option, if any, will be trusted automatically.
305 --disable-ipv6
307 Do not advertise IPv6 capability to server
308 --dtls-ciphers=LIST
310 Set OpenSSL ciphers to support for DTLS
311 --dtls12-ciphers=LIST
313 Set OpenSSL ciphers for Cisco's DTLS v1.2
314 --dtls-local-port=PORT
316 Use PORT as the local port for DTLS and UDP datagrams
317 --dump-http-traffic
319 Enable verbose output of all HTTP requests and the bodies of all
320 responses received from the server.
321 --pfs Enforces Perfect Forward Secrecy (PFS). That ensures that if the
324 server's long-term key is compromised, any session keys estab‐
325 lished before the compromise will be unaffected. If this option
326 is provided and the server does not support PFS in the TLS chan‐
327 nel the connection will fail.
328 PFS is available in Cisco ASA releases 9.1(2) and higher; a
330 suitable cipher suite may need to be manually enabled by the
331 administrator using the ssl encryption setting.
332 --no-dtls
335 Disable DTLS and ESP
336 --no-http-keepalive
338 Version 8.2.2.5 of the Cisco ASA software has a bug where it
339 will forget the client's SSL certificate when HTTP connections
340 are being re-used for multiple requests. So far, this has only
341 been seen on the initial connection, where the server gives an
342 HTTP/1.0 redirect response with an explicit Connection:
343 Keep-Alive directive. OpenConnect as of v2.22 has an uncondi‐
344 tional workaround for this, which is never to obey that direc‐
345 tive after an HTTP/1.0 response.
346 However, Cisco's support team has failed to give any competent
348 response to the bug report and we don't know under what other
349 circumstances their bug might manifest itself. So this option
350 exists to disable ALL re-use of HTTP sessions and cause a new
351 connection to be made for each request. If your server seems not
352 to be recognising your certificate, try this option. If it makes
353 a difference, please report this information to the opencon‐
354 nect-devel@lists.infradead.org mailing list.
355 --no-passwd
357 Never attempt password (or SecurID) authentication.
358 --no-xmlpost
360 Do not attempt to post an XML authentication/configuration
361 request to the server; use the old style GET method which was
362 used by older clients and servers instead.
363 This option is a temporary safety net, to work around potential
365 compatibility issues with the code which falls back to the old
366 method automatically. It causes OpenConnect to behave more like
367 older versions (4.08 and below) did. If you find that you need
368 to use this option, then you have found a bug in OpenConnect.
369 Please see http://www.infradead.org/openconnect/mail.html and
370 report this to the developers.
371 --non-inter
373 Do not expect user input; exit if it is required.
374 --passwd-on-stdin
376 Read password from standard input
377 --protocol=PROTO
379 Select VPN protocol PROTO to be used for the connection. Sup‐
380 ported protocols are anyconnect for Cisco AnyConnect (the
381 default), nc for experimental support for Juniper Network Con‐
382 nect (also supported by most Junos Pulse servers), pulse for
383 experimental support for Junos Pulse, and gp for experimental
384 support for PAN GlobalProtect.
385 OpenConnect does not yet support all of the authentication
387 options used by Pulse, nor does it support Host Checker/TNCC
388 with Pulse. If your Junos Pulse VPN is not yet supported with
389 --protocol=pulse, then --protocol=nc may be a useful fallback
390 option.
391 --token-mode=MODE
393 Enable one-time password generation using the MODE algorithm.
394 --token-mode=rsa will call libstoken to generate an RSA SecurID
395 tokencode, --token-mode=totp will call liboath to generate an
396 RFC 6238 time-based password, and --token-mode=hotp will call
397 liboath to generate an RFC 4226 HMAC-based password. Yubikey
398 tokens which generate OATH codes in hardware are supported with
399 --token-mode=yubioath. --token-mode=oidc will use the provided
400 OpenIDConnect token as an RFC 6750 bearer token.
401 --token-secret={ SECRET[,COUNTER] | @FILENAME }
403 The secret to use when generating one-time passwords/verifica‐
404 tion codes. Base 32-encoded TOTP/HOTP secrets can be used by
405 specifying "base32:" at the beginning of the secret, and for
406 HOTP secrets the token counter can be specified following a
407 comma.
408 RSA SecurID secrets can be specified as an Android/iPhone URI or
410 a raw numeric CTF string (with or without dashes).
411 For Yubikey OATH the token secret specifies the name of the cre‐
413 dential to be used. If not provided, the first OATH credential
414 found on the device will be used.
415 For OIDC the secret is the bearer token to be used.
417 FILENAME, if specified, can contain any of the above strings.
419 Or, it can contain a SecurID XML (SDTID) seed.
420 If this option is omitted, and --token-mode is "rsa", libstoken
422 will try to use the software token seed saved in ~/.stokenrc by
423 the "stoken import" command.
424 --reconnect-timeout
426 Keep reconnect attempts until so much seconds are elapsed. The
427 default timeout is 300 seconds, which means that openconnect can
428 recover VPN connection after a temporary network down time of
429 300 seconds.
430 --resolve=HOST:IP
432 Automatically resolve the hostname HOST to IP instead of using
433 the normal resolver to look it up.
434 --servercert=HASH
436 Accept server's SSL certificate only if the provided fingerprint
437 matches. The allowed fingerprint types are SHA1, SHA256, and
438 PIN-SHA256. They are distinguished by the 'sha1:', 'sha256:'
439 and 'pin-sha256:' prefixes to the encoded hash. The first two
440 are custom identifiers providing hex encoding of the peer's pub‐
441 lic key, while 'pin-sha256:' is the RFC7469 key PIN, which uti‐
442 lizes base64 encoding. To ease certain testing use-cases, a par‐
443 tial match of the hash will also be accepted, if it is at least
444 4 characters past the prefix.
445 --useragent=STRING
447 Use STRING as 'User-Agent:' field value in HTTP header. (e.g.
448 --useragent 'Cisco AnyConnect VPN Agent for Windows 2.2.0133')
449 --version-string=STRING
451 Use STRING as the software version reported to the head end.
452 (e.g. --version-string '2.2.0133')
453 --local-hostname=STRING
455 Use STRING as 'X-CSTP-Hostname:' field value in HTTP header. For
456 example --local-hostname 'mypc', will advertise the value 'mypc'
457 as the suggested hostname to point to the provided IP address.
458 --os=STRING
460 OS type to report to gateway. Recognized values are: linux,
461 linux-64, win, mac-intel, android, apple-ios. Reporting a dif‐
462 ferent OS type may affect the dynamic access policy (DAP)
463 applied to the VPN session. If the gateway requires CSD, it
464 will also cause the corresponding CSD trojan binary to be down‐
465 loaded, so you may need to use --csd-wrapper if this code is not
466 executable on the local machine.
467
469 In the data phase of the connection, the following signals are handled:
470 SIGINT / SIGTERM
472 performs a clean shutdown by logging the session off, discon‐
473 necting from the gateway, and running the vpnc-script to restore
474 the network configuration.
475 SIGHUP disconnects from the gateway and runs the vpnc-script, but does
477 not log the session off; this allows for reconnection later
478 using --cookie.
479 SIGUSR2
481 forces an immediate disconnection and reconnection; this can be
482 used to quickly recover from LAN IP address changes.
483 LIMITATIONS
486 Note that although IPv6 has been tested on all platforms on
487 which openconnect is known to run, it depends on a suitable
488 vpnc-script to configure the network. The standard vpnc-script
489 shipped with vpnc 0.5.3 is not capable of setting up IPv6
490 routes; the one from
491 git://git.infradead.org/users/dwmw2/vpnc-scripts.git will be
492 required.
493
495 ocserv(8)
496
499 David Woodhouse <dwmw2@infradead.org>
500 OPENCONNECT(8)