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