openconnect.8.in

.TH OPENCONNECT 8
.SH NAME
openconnect \- Connect to Cisco AnyConnect VPN
.SH SYNOPSIS
.SY openconnect
.OP \-\-config configfile
.OP \-b,\-\-background
.OP \-\-pid\-file pidfile
.OP \-c,\-\-certificate cert
.OP \-e,\-\-cert\-expire\-warning days
.OP \-k,\-\-sslkey key
.OP \-C,\-\-cookie cookie
.OP \-\-cookie\-on\-stdin
.OP \-\-compression MODE
.OP \-d,\-\-deflate
.OP \-D,\-\-no\-deflate
.OP \-\-force\-dpd interval
.OP \-g,\-\-usergroup group
.OP \-h,\-\-help
.OP \-\-http\-auth methods
.OP \-i,\-\-interface ifname
.OP \-l,\-\-syslog
.OP \-\-timestamp
.OP \-\-passtos
.OP \-U,\-\-setuid user
.OP \-\-csd\-user user
.OP \-m,\-\-mtu mtu
.OP \-\-base\-mtu mtu
.OP \-p,\-\-key\-password pass
.OP \-P,\-\-proxy proxyurl
.OP \-\-proxy\-auth methods
.OP \-\-no\-proxy
.OP \-\-libproxy
.OP \-\-key\-password\-from\-fsid
.OP \-q,\-\-quiet
.OP \-Q,\-\-queue\-len len
.OP \-s,\-\-script vpnc\-script
.OP \-S,\-\-script\-tun
.OP \-u,\-\-user name
.OP \-V,\-\-version
.OP \-v,\-\-verbose
.OP \-x,\-\-xmlconfig config
.OP \-\-authgroup group
.OP \-\-authenticate
.OP \-\-cookieonly
.OP \-\-printcookie
.OP \-\-cafile file
.OP \-\-disable\-ipv6
.OP \-\-dtls\-ciphers list
.OP \-\-dtls\-local\-port port
.OP \-\-dump\-http\-traffic
.OP \-\-no\-system\-trust
.OP \-\-pfs
.OP \-\-no\-dtls
.OP \-\-no\-http\-keepalive
.OP \-\-no\-passwd
.OP \-\-no\-xmlpost
.OP \-\-non\-inter
.OP \-\-passwd\-on\-stdin
.OP \-\-protocol proto
.OP \-\-token\-mode mode
.OP \-\-token\-secret {secret\fR[\fI,counter\fR]|@\fIfile\fR}
.OP \-\-reconnect\-timeout
.OP \-\-resolve host:ip
.OP \-\-servercert sha1
.OP \-\-useragent string
.OP \-\-local-hostname string
.OP \-\-os string
.B [https://]\fIserver\fB[:\fIport\fB][/\fIgroup\fB]
.YS

.SH DESCRIPTION
The program
.B openconnect
connects to Cisco "AnyConnect" VPN servers, which use standard TLS
and DTLS protocols for data transport.

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

The second phase uses that cookie in an HTTPS
.I CONNECT
request, and data packets can be passed over the resulting
connection. In auxiliary headers exchanged with the
.I CONNECT
request, a Session\-ID and Master Secret for a DTLS connection are also
exchanged, which allows data transport over UDP to occur.


.SH OPTIONS
.TP
.B \-\-config=CONFIGFILE
Read further options from
.I 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
.B config
option may be specified in the file.
.TP
.B \-b,\-\-background
Continue in background after startup
.TP
.B \-\-pid\-file=PIDFILE
Save the pid to
.I PIDFILE
when backgrounding
.TP
.B \-c,\-\-certificate=CERT
Use SSL client certificate
.I CERT
which may be either a file name or, if OpenConnect has been built with an appropriate
version of GnuTLS, a PKCS#11 URL.
.TP
.B \-e,\-\-cert\-expire\-warning=DAYS
Give a warning when SSL client certificate has
.I DAYS
left before expiry
.TP
.B \-k,\-\-sslkey=KEY
Use SSL private key
.I KEY
which may be either a file name or, if OpenConnect has been built with an appropriate
version of GnuTLS, a PKCS#11 URL.
.TP
.B \-C,\-\-cookie=COOKIE
Use WebVPN cookie.
.I COOKIE
.TP
.B \-\-cookie\-on\-stdin
Read cookie from standard input.
.TP
.B \-d,\-\-deflate
Enable all compression, including stateful modes. By default, only stateless
compression algorithms are enabled.
.TP
.B \-D,\-\-no\-deflate
Disable all compression.
.TP
.B \-\-compression=MODE
Set compression mode, where
.I MODE
is one of
.I "stateless"
,
.I "none"
, or
.I "all".

By default, only stateless compression algorithms which do not maintain state
from one packet to the next (and which can be used on UDP transports) are
enabled. By setting the mode to
.I "all"
stateful algorithms (currently only zlib deflate) can be enabled. Or all
compression can be disabled by setting the mode to
.I "none".
.TP
.B \-\-force\-dpd=INTERVAL
Use
.I INTERVAL
as minimum Dead Peer Detection interval for CSTP and DTLS, forcing use of DPD even when the server doesn't request it.
.TP
.B \-g,\-\-usergroup=GROUP
Use
.I GROUP
as login UserGroup
.TP
.B \-h,\-\-help
Display help text
.TP
.B \-\-http\-auth=METHODS
Use only the specified methods for HTTP authentication to a server.  By default,
only Negotiate, NTLM and Digest authentication are enabled. Basic authentication
is also supported but because it is insecure it must be explicitly enabled. The
argument is a comma-separated list of methods to be enabled. Note that the order
does not matter: OpenConnect will use Negotiate, NTLM, Digest and Basic
authentication in that order, if each is enabled, regardless of the order
specified in the METHODS string.
.TP
.B \-i,\-\-interface=IFNAME
Use
.I IFNAME
for tunnel interface
.TP
.B \-l,\-\-syslog
Use syslog for progress messages
.TP
.B \-\-timestamp
Prepend a timestamp to each progress message
.TP
.B \-\-passtos
Copy TOS / TCLASS of payload packet into DTLS packets.
.TP
.B \-U,\-\-setuid=USER
Drop privileges after connecting, to become user
.I USER
.TP
.B \-\-csd\-user=USER
Drop privileges during CSD (Cisco Secure Desktop) script execution.
.TP
.B \-\-csd\-wrapper=SCRIPT
Run
.I SCRIPT
instead of the CSD (Cisco Secure Desktop) script.
.TP
.B \-m,\-\-mtu=MTU
Request
.I MTU
from server as the MTU of the tunnel.
.TP
.B \-\-base\-mtu=MTU
Indicate
.I MTU
as the path MTU between client and server on the unencrypted network. Newer
servers will automatically calculate the MTU to be used on the tunnel from
this value.
.TP
.B \-p,\-\-key\-password=PASS
Provide passphrase for certificate file, or SRK (System Root Key) PIN for TPM
.TP
.B \-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.
.TP
.B \-\-proxy\-auth=METHODS
Use only the specified methods for HTTP authentication to a proxy.  By default,
only Negotiate, NTLM and Digest authentication are enabled. Basic authentication
is also supported but because it is insecure it must be explicitly enabled. The
argument is a comma-separated list of methods to be enabled. Note that the order
does not matter: OpenConnect will use Negotiate, NTLM, Digest and Basic
authentication in that order, if each is enabled, regardless of the order
specified in the METHODS string.
.TP
.B \-\-no\-proxy
Disable use of proxy
.TP
.B \-\-libproxy
Use libproxy to configure proxy automatically (when built with libproxy support)
.TP
.B \-\-key\-password\-from\-fsid
Passphrase for certificate file is automatically generated from the
.I fsid
of the file system on which it is stored. The
.I fsid
is obtained from the 
.BR statvfs (2)
or
.BR statfs (2)
system call, depending on the operating system. On a Linux or similar system
with GNU coreutils, the
.I fsid
used by this option should be equal to the output of the command:
.EX
stat \-\-file\-system \-\-printf=%i\e\en $CERTIFICATE
.EE
It is not the same as the 128\-bit UUID of the file system.
.TP
.B \-q,\-\-quiet
Less output
.TP
.B \-Q,\-\-queue\-len=LEN
Set packet queue limit to
.I LEN
pkts
.TP
.B \-s,\-\-script=SCRIPT
Invoke
.I 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
.B vpnc\-script
which is shipped with the "vpnc" VPN client. See
.I http://www.infradead.org/openconnect/vpnc-script.html
for more information. This version of OpenConnect is configured to
use \fB@DEFAULT_VPNCSCRIPT@\fR by default.

On Windows, a relative directory for the default script will be handled 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 \fBcscript.exe\fR.
.TP
.B \-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.
.TP
.B \-u,\-\-user=NAME
Set login username to
.I NAME
.TP
.B \-V,\-\-version
Report version number
.TP
.B \-v,\-\-verbose
More output (may be specified multiple times for additional output)
.TP
.B \-x,\-\-xmlconfig=CONFIG
XML config file
.TP
.B \-\-authgroup=GROUP
Choose authentication login selection
.TP
.B \-\-authenticate
Authenticate only, and output the information needed to make the connection
a form which can be used to set shell environment variables. When invoked with
this option, openconnect will not make the connection, but if successful will
output something like the following to stdout:
.nf
.B COOKIE=3311180634@13561856@1339425499@B315A0E29D16C6FD92EE...
.B HOST=10.0.0.1
.B FINGERPRINT=469bb424ec8835944d30bc77c77e8fc1d8e23a42
.fi
Thus, you can invoke openconnect as a non-privileged user
.I (with access to the user's PKCS#11 tokens, etc.)
for authentication, and then invoke openconnect separately to make the actual
connection as root:
.nf
.B eval `openconnect --authenticate https://vpnserver.example.com`;
.B [ -n "$COOKIE" ] && echo "$COOKIE" |
.B \ \ sudo openconnect --cookie-on-stdin $HOST --servercert $FINGERPRINT
.fi
.TP
.B \-\-cookieonly
Fetch webvpn cookie only; don't connect
.TP
.B \-\-printcookie
Print webvpn cookie before connecting
.TP
.B \-\-cafile=FILE
Cert file for server verification
.TP
.B \-\-disable\-ipv6
Do not advertise IPv6 capability to server
.TP
.B \-\-dtls\-ciphers=LIST
Set OpenSSL ciphers to support for DTLS
.TP
.B \-\-dtls\-local\-port=PORT
Use
.I PORT
as the local port for DTLS datagrams
.TP
.B \-\-dump\-http\-traffic
Enable verbose output of all HTTP requests and the bodies of all responses
received from the server.
.TP
.B \-\-no\-system\-trust
Do not trust the system default certificate authorities. If this option is
given, only certificate authorities given with the
.B \-\-cafile
option, if any, will be trusted automatically.

.TP
.B \-\-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 connection 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
.B ssl encryption
setting.

.TP
.B \-\-no\-dtls
Disable DTLS
.TP
.B \-\-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
.B Connection: Keep\-Alive
directive. OpenConnect 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
response to the bug report and we don't know under what other
circumstances 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 recognising your
certificate, try this option. If it makes a difference, please report
this information to the
.B openconnect\-devel@lists.infradead.org
mailing list.
.TP
.B \-\-no\-passwd
Never attempt password (or SecurID) authentication.
.TP
.B \-\-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
compatibility issues with the code which falls back to the old method
automatically. It causes OpenConnect to behave more like older
versions (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
http://www.infradead.org/openconnect/mail.html and report this to the
developers.
.TP
.B \-\-non\-inter
Do not expect user input; exit if it is required.
.TP
.B \-\-passwd\-on\-stdin
Read password from standard input
.TP
.B \-\-protocol=PROTO
Select VPN protocol
.I PROTO
to be used for the connection. Supported protocols are
.I anyconnect
for Cisco AnyConnect (the default), and
.I nc
for experimental support for Juniper Network Connect (also supported
by Junos Pulse servers).

.TP
.B \-\-token\-mode=MODE
Enable one-time password generation using the
.I MODE
algorithm.
.B \-\-token\-mode=rsa
will call libstoken to generate an RSA SecurID tokencode,
.B \-\-token\-mode=totp
will call liboath to generate an RFC 6238 time-based password, and
.B \-\-token\-mode=hotp
will call liboath to generate an RFC 4226 HMAC-based password. Yubikey
tokens which generate OATH codes in hardware are supported with
.B \-\-token\-mode=yubioath
.TP
.B \-\-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 credential to be
used. If not provided, the first OATH credential found on the device will be
used.

.IR 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
.B ~/.stokenrc
by the "stoken import" command.
.TP
.B \-\-reconnect\-timeout
Keep reconnect attempts until so much seconds are elapsed. The default
timeout is 300 seconds, which means that openconnect can recover
VPN connection after a temporary network down time of 300 seconds.
.TP
.B \-\-resolve=HOST:IP
Automatically resolve the hostname
.IR HOST
to
.IR IP
instead of using the normal resolver to look it up.
.TP
.B \-\-servercert=HASH
Accept server's SSL certificate only if the provided fingerprint matches.
The allowed fingerprint types are
.IR SHA1 ,
.IR SHA256 ,
and
.IR 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 certain
testing use-cases, a partial match of the hash will also
be accepted, if it is at least 4 characters past the prefix.
.TP
.B \-\-useragent=STRING
Use
.I STRING
as 'User\-Agent:' field value in HTTP header.
(e.g. \-\-useragent 'Cisco AnyConnect VPN Agent for Windows 2.2.0133')
.TP
.B \-\-local-hostname=STRING
Use
.I STRING
as 'X\-CSTP\-Hostname:' field value in HTTP header. For example \-\-local\-hostname 'mypc',
will advertise the value 'mypc' as the suggested hostname to point to the provided IP address.
.TP
.B \-\-os=STRING
OS type to report to gateway.  Recognized values are:
.BR linux ,
.BR linux\-64 ,
.BR win ,
.BR mac\-intel ,
.BR android ,
.BR 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
.B \-\-csd\-wrapper
if this code is not executable on the local machine.
.SH SIGNALS
In the data phase of the connection, the following signals are handled:
.TP
.B SIGINT
performs a clean shutdown by logging the session off, disconnecting from the
gateway, and running the vpnc\-script to restore the network configuration.
.TP
.B SIGHUP
disconnects from the gateway and runs the vpnc\-script, but does not log the
session off; this allows for reconnection later using
.BR \-\-cookie .
.TP
.B SIGUSR2
forces an immediate disconnection and reconnection; this can be used to
quickly recover from LAN IP address changes.
.TP
.B SIGTERM
exits immediately without logging off or running vpnc\-script.
.SH LIMITATIONS
Note that although IPv6 has been tested on all platforms on which
.B openconnect
is known to run, it depends on a suitable
.B vpnc\-script
to configure the network. The standard
.B vpnc\-script
shipped with vpnc 0.5.3 is not capable of setting up IPv6 routes; the one from
.B git://git.infradead.org/users/dwmw2/vpnc\-scripts.git
will be required.

.SH AUTHORS
David Woodhouse <dwmw2@infradead.org>