/
openconnect.8.in
610 lines (590 loc) · 19.1 KB
1
.TH OPENCONNECT 8
2
.SH NAME
3
openconnect \- Multi-protocol VPN client, for Cisco AnyConnect VPNs and others
4
.SH SYNOPSIS
5
.SY openconnect
6
.OP \-\-config configfile
7
8
9
10
11
12
13
.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
14
.OP \-\-compression MODE
15
16
17
.OP \-d,\-\-deflate
.OP \-D,\-\-no\-deflate
.OP \-\-force\-dpd interval
18
.OP \-\-force\-trojan interval
19
.OP \-F,\-\-form\-entry form:opt=value
20
21
.OP \-g,\-\-usergroup group
.OP \-h,\-\-help
22
.OP \-\-http\-auth methods
23
24
.OP \-i,\-\-interface ifname
.OP \-l,\-\-syslog
25
.OP \-\-timestamp
26
.OP \-\-passtos
27
28
29
.OP \-U,\-\-setuid user
.OP \-\-csd\-user user
.OP \-m,\-\-mtu mtu
30
.OP \-\-base\-mtu mtu
31
32
.OP \-p,\-\-key\-password pass
.OP \-P,\-\-proxy proxyurl
33
.OP \-\-proxy\-auth methods
34
35
36
37
38
39
40
41
42
43
44
45
.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
46
.OP \-\-authenticate
47
48
49
50
51
.OP \-\-cookieonly
.OP \-\-printcookie
.OP \-\-cafile file
.OP \-\-disable\-ipv6
.OP \-\-dtls\-ciphers list
52
.OP \-\-dtls12\-ciphers list
53
.OP \-\-dtls\-local\-port port
54
.OP \-\-dump\-http\-traffic
55
.OP \-\-no\-system\-trust
56
.OP \-\-pfs
57
58
59
.OP \-\-no\-dtls
.OP \-\-no\-http\-keepalive
.OP \-\-no\-passwd
60
.OP \-\-no\-xmlpost
61
62
.OP \-\-non\-inter
.OP \-\-passwd\-on\-stdin
63
.OP \-\-protocol proto
64
65
.OP \-\-token\-mode mode
.OP \-\-token\-secret {secret\fR[\fI,counter\fR]|@\fIfile\fR}
66
.OP \-\-reconnect\-timeout
67
.OP \-\-resolve host:ip
68
69
.OP \-\-servercert sha1
.OP \-\-useragent string
70
.OP \-\-version\-string string
71
.OP \-\-local-hostname string
72
.OP \-\-os string
73
74
.B [https://]\fIserver\fB[:\fIport\fB][/\fIgroup\fB]
.YS
75
76
77
78
.SH DESCRIPTION
The program
.B openconnect
79
80
81
82
83
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
84
Network Connect
85
.RB ( \-\-protocol=nc )
86
87
and Junos Pulse VPN servers
.RB ( \-\-protocol=pulse )
88
89
and PAN GlobalProtect VPN servers
.RB ( \-\-protocol=gp ).
90
91
92
93
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
94
user is rewarded with an authentication cookie which can be used to make the
95
96
real VPN connection.
97
98
99
100
101
102
103
104
105
106
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
.BR \-\-no\-dtls ,
but is preferred when correctly supported by the server and network
for performance reasons. (TCP performs poorly and unreliably over
TCP-based tunnels; see
.IR http://sites.inka.de/~W1011/devel/tcp-tcp.html .)
107
108
109
.SH OPTIONS
.TP
110
111
112
113
114
115
116
117
118
119
120
121
.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
122
.B \-b,\-\-background
123
124
Continue in background after startup
.TP
125
.B \-\-pid\-file=PIDFILE
126
127
128
129
Save the pid to
.I PIDFILE
when backgrounding
.TP
130
.B \-c,\-\-certificate=CERT
131
132
Use SSL client certificate
.I CERT
133
134
which may be either a file name or, if OpenConnect has been built with an appropriate
version of GnuTLS, a PKCS#11 URL.
135
.TP
136
.B \-e,\-\-cert\-expire\-warning=DAYS
137
138
139
140
Give a warning when SSL client certificate has
.I DAYS
left before expiry
.TP
141
.B \-k,\-\-sslkey=KEY
142
Use SSL private key
143
.I KEY
144
145
which may be either a file name or, if OpenConnect has been built with an appropriate
version of GnuTLS, a PKCS#11 URL.
146
.TP
147
.B \-C,\-\-cookie=COOKIE
148
149
Use authentication cookie
.IR COOKIE .
150
.TP
151
.B \-\-cookie\-on\-stdin
152
Read cookie from standard input.
153
.TP
154
.B \-d,\-\-deflate
155
156
Enable all compression, including stateful modes. By default, only stateless
compression algorithms are enabled.
157
.TP
158
.B \-D,\-\-no\-deflate
159
Disable all compression.
160
.TP
161
162
163
164
.B \-\-compression=MODE
Set compression mode, where
.I MODE
is one of
165
166
167
168
.IR "stateless" ,
.IR "none" ,
or
.IR "all" .
169
170
171
172
173
174
175
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
176
.IR "none" .
177
.TP
178
.B \-\-force\-dpd=INTERVAL
179
180
Use
.I INTERVAL
181
as minimum Dead Peer Detection interval (in seconds) for CSTP and DTLS, forcing use of DPD even when the server doesn't request it.
182
.TP
183
.B \-g,\-\-usergroup=GROUP
184
185
186
187
Use
.I GROUP
as login UserGroup
.TP
188
189
190
191
192
193
194
195
196
197
198
199
200
.B \-F,\-\-form\-entry=FORM:OPTION=VALUE
Provide authentication form input, where
.I FORM
and
.I OPTION
are the identifiers from the form and the specific input field, and
.I VALUE
is the string to be filled in automatically. For example, the standard username field
.I (also handled by the \-\-user option)
could also be provided with this option thus:
.I \-\-form\-entry
.IR main:username=joebloggs .
.TP
201
.B \-h,\-\-help
202
203
Display help text
.TP
204
205
206
207
208
209
210
211
212
.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
213
.B \-i,\-\-interface=IFNAME
214
215
216
217
Use
.I IFNAME
for tunnel interface
.TP
218
.B \-l,\-\-syslog
219
220
Use syslog for progress messages
.TP
221
222
223
.B \-\-timestamp
Prepend a timestamp to each progress message
.TP
224
.B \-\-passtos
225
226
227
Copy TOS / TCLASS of payload packet into DTLS and ESP packets. This is
not set by default because it may leak information about the payload
(for example, by differentiating voice/video traffic).
228
.TP
229
.B \-U,\-\-setuid=USER
230
231
232
Drop privileges after connecting, to become user
.I USER
.TP
233
.B \-\-csd\-user=USER
234
Drop privileges during execution of trojan binary or script (CSD, TNCC, or HIP).
235
.TP
236
.B \-\-csd\-wrapper=SCRIPT
237
238
Run
.I SCRIPT
239
instead of the trojan binary or script.
240
.TP
241
242
243
244
245
246
.B \-\-force-trojan=INTERVAL
Use
.I INTERVAL
as interval (in seconds) for repeat execution of Trojan binary or script, overriding default and/or
server-set interval.
.TP
247
.B \-m,\-\-mtu=MTU
248
249
Request
.I MTU
250
251
from server as the MTU of the tunnel.
.TP
252
.B \-\-base\-mtu=MTU
253
254
255
256
257
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.
258
.TP
259
.B \-p,\-\-key\-password=PASS
260
261
Provide passphrase for certificate file, or SRK (System Root Key) PIN for TPM
.TP
262
.B \-P,\-\-proxy=PROXYURL
263
264
265
266
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.
267
.TP
268
.B \-\-proxy\-auth=METHODS
269
270
271
272
273
274
275
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.
276
.TP
277
.B \-\-no\-proxy
278
Disable use of proxy
279
.TP
280
.B \-\-libproxy
281
282
Use libproxy to configure proxy automatically (when built with libproxy support)
.TP
283
.B \-\-key\-password\-from\-fsid
284
285
286
287
Passphrase for certificate file is automatically generated from the
.I fsid
of the file system on which it is stored. The
.I fsid
288
is obtained from the
289
290
291
292
293
294
.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
295
296
297
298
299
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.
300
.TP
301
.B \-q,\-\-quiet
302
303
Less output
.TP
304
.B \-Q,\-\-queue\-len=LEN
305
Set packet queue limit to
306
307
308
.I LEN
pkts
.TP
309
310
311
312
313
314
315
316
317
.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
318
319
320
321
322
323
324
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.
325
326
.TP
.B \-S,\-\-script\-tun
327
328
329
330
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.
331
.TP
332
.B \-u,\-\-user=NAME
333
334
335
Set login username to
.I NAME
.TP
336
.B \-V,\-\-version
337
338
Report version number
.TP
339
.B \-v,\-\-verbose
340
More output (may be specified multiple times for additional output)
341
.TP
342
.B \-x,\-\-xmlconfig=CONFIG
343
344
XML config file
.TP
345
.B \-\-authgroup=GROUP
346
347
Choose authentication login selection
.TP
348
.B \-\-authenticate
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
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
368
.B \-\-cookieonly
369
Fetch and print cookie only; don't connect
370
.TP
371
.B \-\-printcookie
372
Print cookie before connecting
373
.TP
374
.B \-\-cafile=FILE
375
376
377
378
379
380
381
382
383
384
385
386
Additional CA file for server verification. By default, this simply
causes OpenConnect to trust additional root CA certificate(s) in
addition to those trusted by the system. Use
.B \-\-no\-system\-trust
to prevent OpenConnect from trusting the system default certificate
authorities.
.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.
387
.TP
388
.B \-\-disable\-ipv6
389
390
Do not advertise IPv6 capability to server
.TP
391
.B \-\-dtls\-ciphers=LIST
392
Set OpenSSL ciphers to support for DTLS
393
.TP
394
395
396
.B \-\-dtls12\-ciphers=LIST
Set OpenSSL ciphers for Cisco's DTLS v1.2
.TP
397
398
399
.B \-\-dtls\-local\-port=PORT
Use
.I PORT
400
as the local port for DTLS and UDP datagrams
401
402
403
404
.TP
.B \-\-dump\-http\-traffic
Enable verbose output of all HTTP requests and the bodies of all responses
received from the server.
405
406
407
408
409
410
411
412
.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.
413
414
415
416
417
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.
418
.TP
419
.B \-\-no\-dtls
420
Disable DTLS and ESP
421
.TP
422
.B \-\-no\-http\-keepalive
423
Version 8.2.2.5 of the Cisco ASA software has a bug where it will forget
424
the client's SSL certificate when HTTP connections are being re\-used for
425
426
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
427
.B Connection: Keep\-Alive
428
429
430
431
432
433
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
434
to disable ALL re\-use of HTTP sessions and cause a new connection to be
435
436
437
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
438
.B openconnect\-devel@lists.infradead.org
439
440
mailing list.
.TP
441
.B \-\-no\-passwd
442
443
Never attempt password (or SecurID) authentication.
.TP
444
445
446
447
448
449
450
451
452
453
454
455
456
.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
457
.B \-\-non\-inter
458
Do not expect user input; exit if it is required.
459
.TP
460
.B \-\-passwd\-on\-stdin
461
Read password from standard input
462
463
464
465
466
467
.TP
.B \-\-protocol=PROTO
Select VPN protocol
.I PROTO
to be used for the connection. Supported protocols are
.I anyconnect
468
for Cisco AnyConnect (the default),
469
470
.I nc
for experimental support for Juniper Network Connect (also supported
471
472
473
by most Junos Pulse servers),
.I pulse
for experimental support for Junos Pulse, and
474
475
.I gp
for experimental support for PAN GlobalProtect.
476
477
478
479
480
481
482
483
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 Pulse VPN is not yet supported with
.BR \-\-protocol=pulse ,
then
.B \-\-protocol=nc
may be a useful fallback option.
484
.TP
485
486
487
488
489
.B \-\-token\-mode=MODE
Enable one-time password generation using the
.I MODE
algorithm.
.B \-\-token\-mode=rsa
490
will call libstoken to generate an RSA SecurID tokencode,
491
.B \-\-token\-mode=totp
492
493
will call liboath to generate an RFC 6238 time-based password, and
.B \-\-token\-mode=hotp
494
495
will call liboath to generate an RFC 4226 HMAC-based password. Yubikey
tokens which generate OATH codes in hardware are supported with
496
497
.B \-\-token\-mode=yubioath. \-\-token\-mode=oidc will use the provided
OpenIDConnect token as an RFC 6750 bearer token.
498
.TP
499
.B \-\-token\-secret={ SECRET[,COUNTER] | @FILENAME }
500
The secret to use when generating one-time passwords/verification codes.
501
502
503
504
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.
505
506
507
RSA SecurID secrets can be specified as an Android/iPhone URI or a raw numeric
CTF string (with or without dashes).
508
509
510
511
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.
512
513
For OIDC the secret is the bearer token to be used.
514
515
516
517
.IR FILENAME ,
if specified, can contain any of the above strings. Or, it can contain a
SecurID XML (SDTID) seed.
518
If this option is omitted, and \-\-token\-mode is
519
520
521
"rsa", libstoken will try to use the software token seed saved in
.B ~/.stokenrc
by the "stoken import" command.
522
.TP
523
.B \-\-reconnect\-timeout
524
525
526
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.
527
.TP
528
529
530
531
532
533
534
.B \-\-resolve=HOST:IP
Automatically resolve the hostname
.IR HOST
to
.IR IP
instead of using the normal resolver to look it up.
.TP
535
536
537
538
.B \-\-servercert=HASH
Accept server's SSL certificate only if the provided fingerprint matches.
The allowed fingerprint types are
.IR SHA1 ,
539
.IR SHA256 ,
540
and
541
542
543
544
545
546
547
.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.
548
.TP
549
550
551
552
553
.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')
554
.TP
555
556
557
558
559
560
.B \-\-version\-string=STRING
Use
.I STRING
as the software version reported to the head end.
(e.g. \-\-version\-string '2.2.0133')
.TP
561
562
563
564
565
566
.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
567
.B \-\-os=STRING
568
569
570
571
572
573
574
575
576
577
578
579
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.
580
581
582
.SH SIGNALS
In the data phase of the connection, the following signals are handled:
.TP
583
.B SIGINT / SIGTERM
584
585
586
587
588
589
590
591
592
593
594
595
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
596
.SH LIMITATIONS
597
Note that although IPv6 has been tested on all platforms on which
598
.B openconnect
599
is known to run, it depends on a suitable
600
.B vpnc\-script
601
to configure the network. The standard
602
.B vpnc\-script
603
shipped with vpnc 0.5.3 is not capable of setting up IPv6 routes; the one from
604
.B git://git.infradead.org/users/dwmw2/vpnc\-scripts.git
605
will be required.
606
607
.SH SEE ALSO
.BR ocserv (8)
608
609
610
.SH AUTHORS
David Woodhouse <dwmw2@infradead.org>