FreeBSD Manual Pages

home | help

OPENCONNECT(8) System Manager's Manual OPENCONNECT(8)

NAME
openconnect - Multi-protocol VPN client, for Cisco AnyConnect VPNs and oth-
ers

SYNOPSIS
openconnect [--config configfile] [-b,--background] [--pid-file pidfile]
[-c,--certificate cert] [-e,--cert-expire-warning days]
[-k,--sslkey key] [-C,--cookie cookie] [--cookie-on-stdin]
[--compression MODE] [-d,--deflate] [-D,--no-deflate]
[--force-dpd interval] [--force-trojan interval]
[-F,--form-entry form:opt=value] [-g,--usergroup group]
[-h,--help] [--http-auth methods] [--external-browser browser]
[-i,--interface ifname] [-l,--syslog] [--timestamp] [--passtos]
[-U,--setuid user] [--csd-user user] [-m,--mtu mtu]
[--base-mtu mtu] [-p,--key-password pass] [-P,--proxy proxyurl]
[--proxy-auth methods] [--no-proxy] [--libproxy]
[--key-password-from-fsid] [-q,--quiet] [-Q,--queue-len len]
[-s,--script vpnc-script] [-S,--script-tun] [-u,--user name]
[-V,--version] [-v,--verbose] [-x,--xmlconfig config]
[--authgroup group] [--authenticate] [--cookieonly]
[--printcookie] [--cafile file] [--disable-ipv6]
[--dtls-ciphers list] [--dtls12-ciphers list]
[--dtls-local-port port] [--dump-http-traffic]
[--no-system-trust] [--pfs] [--no-dtls] [--no-http-keepalive]
[--no-passwd] [--no-xmlpost] [--non-inter] [--passwd-on-stdin]
[--protocol proto] [--token-mode mode]
[--token-secret {secret[,counter]|@file}]
[--reconnect-timeout seconds] [--resolve host:ip] [--sni host]
[--servercert sha1] [--useragent string]
[--version-string string] [--local-hostname string]
[--os string] [--server] [https://]host[:port][/group]

DESCRIPTION
The program openconnect connects to VPN servers which use standard TLS/SSL,
DTLS, and ESP protocols for data transport.

It was originally written to support Cisco "AnyConnect" VPN servers, and
has since been extended with experimental support for Juniper Network Con-
nect (--protocol=nc), Pulse/Ivanti Connect Secure VPN servers (--proto-
col=pulse), Palo Alto Networks GlobalProtect VPN servers (--protocol=gp),
F5 Big-IP VPN servers (--protocol=f5), Fortinet Fortigate VPN servers
(--protocol=fortinet), and Array Networks SSL VPN servers (--protocol=ar-
ray).

The connection happens in two phases. First there is a simple HTTPS connec-
tion over which the user authenticates somehow - by using a certificate, or
password or SecurID, etc. Having authenticated, the user is rewarded with
an authentication cookie which can be used to make the real VPN connection.

The second phase uses that cookie to connect to a tunnel via HTTPS, and
data packets can be passed over the resulting connection. When possible, a
UDP tunnel is also configured: AnyConnect uses DTLS, while Juniper and
GlobalProtect use UDP-encapsulated ESP. The UDP tunnel may be disabled with
--no-dtls, but is preferred when correctly supported by the server and net-
work for performance reasons. (TCP performs poorly and unreliably over TCP-
based tunnels; see
https://web.archive.org/web/20230228035749/https://sites.inka.de/~W1011/de-
vel/tcp-tcp.html.)

OPTIONS
--config=CONFIGFILE
Read further options from CONFIGFILE before continuing to process
options from the command line. The file should contain long-format
options as would be accepted on the command line, but without the
two leading -- dashes. Empty lines, or lines where the first non-
space character is a # character, are ignored.

Any option except the config option may be specified in the file.

-b,--background
Continue in background after startup

--pid-file=PIDFILE
Save the pid to PIDFILE when backgrounding

-c,--certificate=CERT [,--mca-certificate=CERT]
Use SSL client certificate CERT which may be either a file name or,
if OpenConnect has been built with an appropriate version of GnuTLS,
a PKCS#11 URL.

The --mca-certificate option sets the secondary certificate for
multi-certificate authentication (according to Cisco's terminology,
the SSL client certificate is called the "machine" certificate, and
the second certificate is called the "user" certificate).

-e,--cert-expire-warning=DAYS
Give a warning when SSL client certificate has DAYS left before ex-
piry

-k,--sslkey=KEY [,--mca-key=KEY]
Use SSL private key KEY which may be either a file name or, if Open-
Connect has been built with an appropriate version of GnuTLS, a
PKCS#11 URL.

The --mca-key option sets the private key for the secondary certifi-
cate (see --mca-certificate).

-C,--cookie=COOKIE
Use authentication cookie COOKIE.

--cookie-on-stdin
Read cookie from standard input.

-d,--deflate
Enable all compression, including stateful modes. By default, only
stateless compression algorithms are enabled.

-D,--no-deflate
Disable all compression.

--compression=MODE
Set compression mode, where MODE is one of stateless, none, or all.

By default, only stateless compression algorithms which do not main-
tain state from one packet to the next (and which can be used on UDP
transports) are enabled. By setting the mode to all stateful algo-
rithms (currently only zlib deflate) can be enabled. Or all compres-
sion can be disabled by setting the mode to none.

--force-dpd=INTERVAL
Use INTERVAL as Dead Peer Detection interval (in seconds). This will
cause the client to use DPD at the specified interval even if the
server hasn't requested it, or at a different interval from the one
requested by the server.

DPD mechanisms vary by protocol and by transport (TLS or DTLS/ESP),
but are all functionally similar: they enable either the VPN client
or the VPN server to transmit a signal to the peer, requesting an
immediate reply which can be used to confirm that the link between
the two peers is still working.

-g,--usergroup=GROUP
Set the URL path of the initial HTTPS connection to the server.

With some protocols, this path may function as a login group or
realm, hence the naming of this option. For example, the following
invocations of OpenConnect are equivalent:
openconnect --usergroup=loginPath vpn.server.com
openconnect https://vpn.server.com/loginPath

-F,--form-entry=FORM:OPTION[=VALUE]
Provide authentication form input, where FORM and OPTION are the
identifiers from the form and the specific input field, and VALUE is
the string to be filled in automatically. For example, the standard
username field (also handled by the --user option) could also be
provided with this option thus: --form-entry main:username=joe-
bloggs.

If VALUE is not specified, this option will cause a hidden form
field to be treated as a standard text-input field.

This option should not be used to enter passwords.
--passwd-on-stdin should be used for that purpose. Not only will
this option expose the password value via the OpenConnect process's
command line, but unlike --passwd-on-stdin this option will not rec-
ognize the case of an incorrect password, and stop trying to re-en-
ter it repeatedly.

-h,--help
Display help text

--http-auth=METHODS
Use only the specified methods for HTTP authentication to a server.
By default, only Negotiate, NTLM and Digest authentication are en-
abled. Basic authentication is also supported but because it is in-
secure it must be explicitly enabled. The argument is a comma-sepa-
rated list of methods to be enabled. Note that the order does not
matter: OpenConnect will use Negotiate, NTLM, Digest and Basic au-
thentication in that order, if each is enabled, regardless of the
order specified in the METHODS string.

--external-browser=BROWSER
Set BROWSER as the executable used by OpenConnect to handle the au-
thentication process with gateways that support the single-sign-on-
external-browser authentication method.

-i,--interface=IFNAME
Use IFNAME for tunnel interface

-l,--syslog
After tunnel is brought up, use syslog for further progress messages

--timestamp
Prepend a timestamp to each progress message

--passtos
Copy TOS / TCLASS of payload packet into DTLS and ESP packets. This
is not set by default because it may leak information about the pay-
load (for example, by differentiating voice/video traffic).

-U,--setuid=USER
Drop privileges after connecting, to become user USER

--csd-user=USER
Drop privileges during execution of trojan binary or script (CSD,
TNCC, or HIP).

--csd-wrapper=SCRIPT
Run SCRIPT instead of the trojan binary or script.

--force-trojan=INTERVAL
Use INTERVAL as interval (in seconds) for repeat execution of Trojan
binary or script, overriding default and/or server-set interval.

-m,--mtu=MTU
Request MTU from server as the MTU of the tunnel.

--base-mtu=MTU
Indicate MTU as the path MTU between client and server on the unen-
crypted network. Newer servers will automatically calculate the MTU
to be used on the tunnel from this value.

-p,--key-password=PASS [,--mca-key-password=PASS]
Provide passphrase for certificate file, or SRK (System Root Key)
PIN for TPM

--mca-key-password provides the passphrase for the secondary cer-
tificate (see --mca-certificate).

-P,--proxy=PROXYURL
Use HTTP or SOCKS proxy for connection. A username and password can
be provided in the given URL, and will be used for authentication.
If authentication is required but no credentials are given, GSSAPI
and automatic NTLM authentication using Samba's ntlm_auth helper
tool may be attempted.

--proxy-auth=METHODS
Use only the specified methods for HTTP authentication to a proxy.
By default, only Negotiate, NTLM and Digest authentication are en-
abled. Basic authentication is also supported but because it is in-
secure it must be explicitly enabled. The argument is a comma-sepa-
rated list of methods to be enabled. Note that the order does not
matter: OpenConnect will use Negotiate, NTLM, Digest and Basic au-
thentication in that order, if each is enabled, regardless of the
order specified in the METHODS string.

--no-proxy
Disable use of proxy

--libproxy
Use libproxy to configure proxy automatically (when built with
libproxy support)

--key-password-from-fsid
Passphrase for certificate file is automatically generated from the
fsid of the file system on which it is stored. The fsid is obtained
from the statvfs(2) or statfs(2) system call, depending on the oper-
ating system. On a Linux or similar system with GNU coreutils, the
fsid used by this option should be equal to the output of the com-
mand:
stat --file-system --printf=%i\\n $CERTIFICATE
It is not the same as the 128-bit UUID of the file system.

-q,--quiet
Less output

-Q,--queue-len=LEN
Set packet queue limit to LEN packets. The default is 32. A high
value may allow better overall bandwidth but at a cost of latency.
If you run Voice over IP or other interactive traffic over the VPN,
you don't want those packets to be queued behind thousands of other
large packets which are part of a bulk transfer.

This option sets the maximum inbound and outbound packet queue sizes
in OpenConnect itself, which control how many packets will be sent
and received in a single batch, as well as affecting other buffering
such as the socket send buffer (SO_SNDBUF) for network connections
and the OS tunnel device.

Ultimately, the right size for a queue is "just enough packets that
it never quite gets empty before more are pushed to it". Any higher
than that is simply introducing bufferbloat and additional latency
with no benefit. With the default of 32, we are able to saturate a
single Gigabit Ethernet from modest hardware, which is more than
enough for most VPN users.

If OpenConnect is built with vhost-net support, it will only be used
if the queue length is set to 16 or more. This is because vhost-net
introduces a small amount of additional latency, but improves total
bandwidth quite considerably for those operating at high traffic
rates. Thus it makes sense to use it when the user has indicated a
preference for bandwidth over latency, by increasing the queue size.

-s,--script=SCRIPT
Invoke SCRIPT to configure the network after connection. Without
this, routing and name service are unlikely to work correctly. The
script is expected to be compatible with the vpnc-script which is
shipped with the "vpnc" VPN client. See https://www.in-
fradead.org/openconnect/vpnc-script.html for more information. This
version of OpenConnect is configured to use /usr/local/sbin/vpnc-
script by default.

On Windows, a relative directory for the default script will be han-
dled as starting from the directory that the openconnect executable
is running from, rather than the current directory. The script will
be invoked with the command-based script host cscript.exe.

-S,--script-tun
Pass traffic to 'script' program over a UNIX socket, instead of to a
kernel tun/tap device. This allows the VPN IP traffic to be handled
entirely in userspace, for example by a program which uses lwIP to
provide SOCKS access into the VPN.

--server=[https://]HOST[:PORT][/PATH]
Define the VPN server as a simple HOST or as an URL containing the
HOST and optionally the PORT number and the PATH; with some proto-
cols, the path may function as a login group or realm, and it may
equivalently be specified with --usergroup.

As an alternative, define the VPN server as non-option command line
argument.

-u,--user=NAME
Set login username to NAME

-V,--version
Report version number

-v,--verbose
More output (may be specified multiple times for additional output)

-x,--xmlconfig=CONFIG
XML config file

--authgroup=GROUP
Select GROUP from authentication dropdown or list entry.

Many VPNs require a selection from a dropdown or list during the au-
thentication process. This selection may be known as authgroup (on
Cisco VPNs), realm (Juniper, Pulse, Fortinet), domain (F5), and
gateway (GlobalProtect). This option attempts to automatically fill
the appropriate protocol-specific field with the desired value.

--authenticate
Authenticate to the VPN, output the information needed to make the
connection in a form which can be used to set shell environment
variables, and then exit.

When invoked with this option, OpenConnect will not actually create
the VPN connection or configure a tunnel interface, but if success-
ful will print something like the following to stdout:
COOKIE='3311180634@13561856@1339425499@B315A0E29D16C6FD92EE...'
HOST='10.0.0.1'
CONNECT_URL='https://vpnserver.example.com'
FINGERPRINT='469bb424ec8835944d30bc77c77e8fc1d8e23a42'
RESOLVE='vpnserver.example.com:10.0.0.1'
Thus, you can invoke openconnect as a non-privileged user (with ac-
cess to the user's PKCS#11 tokens, etc.) for authentication, and
then invoke openconnect separately to make the actual connection as
root:
eval `openconnect --authenticate https://vpnserver.example.com`;
[ -n ["$COOKIE"] ] && echo ["$COOKIE"] |
sudo openconnect --cookie-on-stdin $CONNECT_URL --servercert $FINGERPRINT --resolve $RESOLVE

Earlier versions of OpenConnect produced only the HOST variable
(containing the numeric server address), and not the CONNECT_URL or
RESOLVE variables. Subsequently, we discovered that servers behind
proxies may not respond correctly unless the correct DNS name is
present in the connection phase, and we added support for VPN proto-
cols where the server URL's path component may be significant in the
connection phase, prompting the addition of CONNECT_URL and RESOLVE,
and the recommendation to use them as described above. If you are
not certain that you are invoking a newer version of OpenConnect
which outputs these variables, use the following command-line (com-
patible with most Bourne shell derivatives) which will work with ei-
ther a newer or older version:
sudo openconnect --cookie-on-stdin ${CONNECT_URL:-$HOST} --servercert $FINGERPRINT ${RESOLVE:+--resolve=$RESOLVE}

--cookieonly
Fetch and print cookie only; don't connect (this is essentially a
subset of --authenticate).

--printcookie
Print cookie to stdout before connecting (see --authenticate for the
meaning of this cookie)

--cafile=FILE
Additional CA file for server verification. By default, this simply
causes OpenConnect to trust additional root CA certificate(s) in ad-
dition to those trusted by the system. Use --no-system-trust to pre-
vent OpenConnect from trusting the system default certificate au-
thorities.

--no-system-trust
Do not trust the system default certificate authorities. If this op-
tion is given, only certificate authorities given with the --cafile
option, if any, will be trusted automatically.

--disable-ipv6
Do not advertise IPv6 capability to server

--dtls-ciphers=LIST
Set OpenSSL ciphers to support for DTLS

--dtls12-ciphers=LIST
Set OpenSSL ciphers for Cisco's DTLS v1.2

--dtls-local-port=PORT
Use PORT as the local port for DTLS and UDP datagrams

--dump-http-traffic
Enable verbose output of all HTTP requests and the bodies of all re-
sponses received from the server.

--pfs Enforces Perfect Forward Secrecy (PFS). That ensures that if the
server's long-term key is compromised, any session keys established
before the compromise will be unaffected. If this option is provided
and the server does not support PFS in the TLS channel the connec-
tion will fail.

PFS is available in Cisco ASA releases 9.1(2) and higher; a suitable
cipher suite may need to be manually enabled by the administrator
using the ssl encryption setting.

--no-dtls
Disable DTLS and ESP

--no-http-keepalive
Version 8.2.2.5 of the Cisco ASA software has a bug where it will
forget the client's SSL certificate when HTTP connections are being
re-used for multiple requests. So far, this has only been seen on
the initial connection, where the server gives an HTTP/1.0 redirect
response with an explicit Connection: Keep-Alive directive. OpenCon-
nect as of v2.22 has an unconditional workaround for this, which is
never to obey that directive after an HTTP/1.0 response.

However, Cisco's support team has failed to give any competent re-
sponse to the bug report and we don't know under what other circum-
stances their bug might manifest itself. So this option exists to
disable ALL re-use of HTTP sessions and cause a new connection to be
made for each request. If your server seems not to be recognizing
your certificate, try this option. If it makes a difference, please
report this information to the openconnect-devel@lists.infradead.org
mailing list.

--no-passwd
Never attempt password (or SecurID) authentication.

--no-external-auth
Prevent OpenConnect from advertising to the server that it supports
any kind of authentication mode that requires an external browser.

Some servers will force the client to use such an authentication
mode if the client advertises it, but fallback to a more "script-
able" authentication mode if the client doesn't appear to support
it.

--no-xmlpost
Do not attempt to post an XML authentication/configuration request
to the server; use the old style GET method which was used by older
clients and servers instead.

This option is a temporary safety net, to work around potential com-
patibility issues with the code which falls back to the old method
automatically. It causes OpenConnect to behave more like older ver-
sions (4.08 and below) did. If you find that you need to use this
option, then you have found a bug in OpenConnect. Please see
https://www.infradead.org/openconnect/mail.html and report this to
the developers.

--allow-insecure-crypto
The ancient, broken 3DES and RC4 ciphers are insecure; we explicitly
disable them by default. However, some still-in-use VPN servers
can't do any better.

This option enables use of these insecure ciphers, as well as the
use of SHA1 for server certificate validation.

--non-inter
Do not expect user input; exit if it is required.

--passwd-on-stdin
Read password from standard input

--protocol=PROTO
Select VPN protocol PROTO to be used for the connection. Supported
protocols are anyconnect for Cisco AnyConnect (the default), nc for
experimental support for Juniper Network Connect (also supported by
most Ivanti/Pulse Connect Secure servers), pulse for experimental
support for Ivanti/Pulse Connect Secure, gp for experimental support
for Palo Alto Networks GlobalProtect, f5 for experimental support
for F5 Big-IP, fortinet for experimental support for Fortinet Forti-
gate, and array for experimental support for Array Networks SSL VPN.

See https://www.infradead.org/openconnect/protocols.html for details
on features and deficiencies of the individual protocols.

OpenConnect does not yet support all of the authentication options
used by Pulse, nor does it support Host Checker/TNCC with Pulse. If
your Junos/Ivanti Pulse VPN is not yet supported with --proto-
col=pulse, then --protocol=nc may be a useful fallback option.

--token-mode=MODE
Enable one-time password generation using the MODE algorithm. --to-
ken-mode=rsa will call libstoken to generate an RSA SecurID token-
code, --token-mode=totp will generate an RFC 6238 time-based pass-
word, and --token-mode=hotp will generate an RFC 4226 HMAC-based
password. Yubikey tokens which generate OATH codes in hardware are
supported with --token-mode=yubioath. --token-mode=oidc will use
the provided OpenIDConnect token as an RFC 6750 bearer token.

--token-secret={ SECRET[,COUNTER] | @FILENAME }
The secret to use when generating one-time passwords/verification
codes. Base 32-encoded TOTP/HOTP secrets can be used by specifying
"base32:" at the beginning of the secret, and for HOTP secrets the
token counter can be specified following a comma.

RSA SecurID secrets can be specified as an Android/iPhone URI or a
raw numeric CTF string (with or without dashes).

For Yubikey OATH the token secret specifies the name of the creden-
tial to be used. If not provided, the first OATH credential found on
the device will be used.

For OIDC the secret is the bearer token to be used.

FILENAME, if specified, can contain any of the above strings. Or,
it can contain a SecurID XML (SDTID) seed.

If this option is omitted, and --token-mode is "rsa", libstoken will
try to use the software token seed saved in ~/.stokenrc by the "sto-
ken import" command.

--reconnect-timeout=SECONDS
After disconnection or Dead Peer Detection, keep trying to reconnect
for SECONDS. The default is 300 seconds, which means that opencon-
nect can recover a VPN connection after a temporary network outage
lasting up to 300 seconds.

--resolve=HOST:IP
Automatically resolve the hostname HOST to IP instead of using the
normal resolver to look it up.

--sni=HOST
When creating new TLS connections, always present the hostname HOST
as the SNI (Server Name Indication) in place of the correct host-
name, which will still be sent in the HTTP 'Host:' header, and ex-
pect the peer's certificate to match the SNI rather than the correct
hostname. This may be useful for Domain Fronting, by which some
filtered or censored Internet connections can be bypassed.

Note that sending different values for the SNI and 'Host:' header
violates HTTP standards and is prevented by many cloud hosting
providers.

--servercert=HASH
Accept server's SSL certificate only if it matches the provided fin-
gerprint. This option implies --no-system-trust, and may be speci-
fied multiple times in order to accept multiple possible finger-
prints.

The allowed fingerprint types are SHA1, SHA256, and PIN-SHA256.
They are distinguished by the 'sha1:', 'sha256:' and 'pin-sha256:'
prefixes to the encoded hash. The first two are custom identifiers
providing hex encoding of the peer's public key, while 'pin-sha256:'
is the RFC7469 key PIN, which utilizes base64 encoding. To ease cer-
tain testing use-cases, a partial match of the hash will also be ac-
cepted, if it is at least 4 characters past the prefix.

--useragent=STRING
Use STRING as 'User-Agent:' field value in HTTP header.

Some VPN servers may require specific values matching those sent by
proprietary VPN clients in order to successfully authenticate or
connect. For example, when connecting to a Cisco VPN server, --user-
agent 'AnyConnect Windows 4.10.06079' or --useragent 'Cisco AnyCon-
nect VPN Agent for Windows 2.2.0133', or when connecting to a Pulse
server, --useragent 'Pulse-Secure/9.1.11.6725'.

--version-string=STRING
Use STRING as the software version reported to the head end. (e.g.
--version-string '2.2.0133')

--local-hostname=STRING
Use STRING as 'X-CSTP-Hostname:' field value in HTTP header. For ex-
ample --local-hostname 'mypc', will advertise the value 'mypc' as
the suggested hostname to point to the provided IP address.

--os=STRING
OS type to report to gateway. Recognized values are: linux,
linux-64, win, mac-intel, android, apple-ios. Reporting a different
OS type may affect the dynamic access policy (DAP) applied to the
VPN session. If the gateway requires CSD, it will also cause the
corresponding CSD trojan binary to be downloaded, so you may need to
use --csd-wrapper if this code is not executable on the local ma-
chine.

SIGNALS
In the data phase of the connection, the following signals are handled:

SIGINT / SIGTERM
performs a clean shutdown by logging the session off, disconnecting
from the gateway, and running the vpnc-script to restore the network
configuration.

SIGHUP
disconnects from the gateway and runs the vpnc-script, but does not
log the session off; this allows for reconnection later using
--cookie.

SIGUSR1
writes progress message with detailed connection information and
statistics.

SIGUSR2
forces an immediate disconnection and reconnection; this can be used
to quickly recover from LAN IP address changes.

LIMITATIONS
See https://www.infradead.org/openconnect/contribute.html for various fea-
tures that we wish OpenConnect had, and https://www.infradead.org/opencon-
nect/protocols.html for information on the quirks and limitations of the
individual VPN protocols.

Header And Logo

Peripheral Links

Site Navigation

FreeBSD Manual Pages

Header And Logo

Peripheral Links

Search

Site Navigation

FreeBSD Manual Pages