1OPENCONNECT(8) System Manager's Manual OPENCONNECT(8)
2
3
4
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
39
41 The program openconnect connects to VPN servers which use standard
42 TLS/SSL, DTLS, and ESP protocols for data transport.
43
44 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
49 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
55 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
64
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
74 Any option except the config option may be specified in the
75 file.
76
77 -b,--background
78 Continue in background after startup
79
80 --pid-file=PIDFILE
81 Save the pid to PIDFILE when backgrounding
82
83 -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
88 -e,--cert-expire-warning=DAYS
89 Give a warning when SSL client certificate has DAYS left before
90 expiry
91
92 -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
97 -C,--cookie=COOKIE
98 Use authentication cookie COOKIE.
99
100 --cookie-on-stdin
101 Read cookie from standard input.
102
103 -d,--deflate
104 Enable all compression, including stateful modes. By default,
105 only stateless compression algorithms are enabled.
106
107 -D,--no-deflate
108 Disable all compression.
109
110 --compression=MODE
111 Set compression mode, where MODE is one of stateless, none, or
112 all.
113
114 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
121 --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
126 -g,--usergroup=GROUP
127 Use GROUP as login UserGroup
128
129 -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
137 -h,--help
138 Display help text
139
140 --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
151 -i,--interface=IFNAME
152 Use IFNAME for tunnel interface
153
154 -l,--syslog
155 Use syslog for progress messages
156
157 --timestamp
158 Prepend a timestamp to each progress message
159
160 --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
166 -U,--setuid=USER
167 Drop privileges after connecting, to become user USER
168
169 --csd-user=USER
170 Drop privileges during execution of trojan binary or script
171 (CSD, TNCC, or HIP).
172
173 --csd-wrapper=SCRIPT
174 Run SCRIPT instead of the trojan binary or script.
175
176 --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
181 -m,--mtu=MTU
182 Request MTU from server as the MTU of the tunnel.
183
184 --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
189 -p,--key-password=PASS
190 Provide passphrase for certificate file, or SRK (System Root
191 Key) PIN for TPM
192
193 -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
200 --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
211 --no-proxy
212 Disable use of proxy
213
214 --libproxy
215 Use libproxy to configure proxy automatically (when built with
216 libproxy support)
217
218 --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
228 -q,--quiet
229 Less output
230
231 -Q,--queue-len=LEN
232 Set packet queue limit to LEN pkts
233
234 -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
243 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
249 -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
255 -u,--user=NAME
256 Set login username to NAME
257
258 -V,--version
259 Report version number
260
261 -v,--verbose
262 More output (may be specified multiple times for additional out‐
263 put)
264
265 -x,--xmlconfig=CONFIG
266 XML config file
267
268 --authgroup=GROUP
269 Choose authentication login selection
270
271 --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
288 --cookieonly
289 Fetch and print cookie only; don't connect
290
291 --printcookie
292 Print cookie before connecting
293
294 --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
301 --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
306 --disable-ipv6
307 Do not advertise IPv6 capability to server
308
309 --dtls-ciphers=LIST
310 Set OpenSSL ciphers to support for DTLS
311
312 --dtls12-ciphers=LIST
313 Set OpenSSL ciphers for Cisco's DTLS v1.2
314
315 --dtls-local-port=PORT
316 Use PORT as the local port for DTLS and UDP datagrams
317
318 --dump-http-traffic
319 Enable verbose output of all HTTP requests and the bodies of all
320 responses received from the server.
321
322
323 --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
329 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
333
334 --no-dtls
335 Disable DTLS and ESP
336
337 --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
347 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
356 --no-passwd
357 Never attempt password (or SecurID) authentication.
358
359 --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
364 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
372 --non-inter
373 Do not expect user input; exit if it is required.
374
375 --passwd-on-stdin
376 Read password from standard input
377
378 --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
386 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
392 --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
402 --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
409 RSA SecurID secrets can be specified as an Android/iPhone URI or
410 a raw numeric CTF string (with or without dashes).
411
412 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
416 For OIDC the secret is the bearer token to be used.
417
418 FILENAME, if specified, can contain any of the above strings.
419 Or, it can contain a SecurID XML (SDTID) seed.
420
421 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
425 --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
431 --resolve=HOST:IP
432 Automatically resolve the hostname HOST to IP instead of using
433 the normal resolver to look it up.
434
435 --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
446 --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
450 --version-string=STRING
451 Use STRING as the software version reported to the head end.
452 (e.g. --version-string '2.2.0133')
453
454 --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
459 --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
471 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
476 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
480 SIGUSR2
481 forces an immediate disconnection and reconnection; this can be
482 used to quickly recover from LAN IP address changes.
483
484
485 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
497
499 David Woodhouse <dwmw2@infradead.org>
500
501
502
503 OPENCONNECT(8)