1OPENCONNECT(8)              System Manager's Manual             OPENCONNECT(8)
2
3
4

NAME

6       openconnect  - Multi-protocol VPN client, for Cisco AnyConnect VPNs and
7       others
8

SYNOPSIS

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

DESCRIPTION

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

OPTIONS

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

SIGNALS

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

SEE ALSO

495       ocserv(8)
496
497

AUTHORS

499       David Woodhouse <dwmw2@infradead.org>
500
501
502
503                                                                OPENCONNECT(8)
Impressum