Update documentation for the --authenticate option

Mention the CONNECT_URL and RESOLVE options, and how to use them to invoke
the connection phase in the maximally-robust way (which should work for all
protocols, and all possible proxies).

Signed-off-by: Daniel Lenski <dlenski@gmail.com>

diff --git a/openconnect.8.in b/openconnect.8.in
index 8036c399a860e3d3fd945339a8f22c967c22dca8..5f2e90e95367d28aca6bee6a0d0f2f45d643b908 100644 (file)
--- a/openconnect.8.in
+++ b/openconnect.8.in
@@ -363,14 +363,18 @@ XML config file
 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:
+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 successful will print something like the
+following to stdout:
 .nf
-.B COOKIE=3311180634@13561856@1339425499@B315A0E29D16C6FD92EE...
-.B HOST=10.0.0.1
-.B FINGERPRINT=469bb424ec8835944d30bc77c77e8fc1d8e23a42
+.B COOKIE='3311180634@13561856@1339425499@B315A0E29D16C6FD92EE...'
+.B HOST='10.0.0.1'
+.B CONNECT_URL='https://vpnserver.example.com'
+.B FINGERPRINT='469bb424ec8835944d30bc77c77e8fc1d8e23a42'
+.B RESOLVE='vpnserver.example.com:10.0.0.1'
 .fi
 Thus, you can invoke openconnect as a non-privileged user
 .I (with access to the user's PKCS#11 tokens, etc.)
@@ -379,14 +383,39 @@ 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
+.B \ \ sudo openconnect --cookie-on-stdin $CONNECT_URL --servercert $FINGERPRINT --resolve $RESOLVE
+.fi
+
+Earlier versions of OpenConnect produced only the
+.B HOST
+variable (containing the numeric server address), and not the
+.B CONNECT_URL
+or
+.B 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 protocols where the server URL's
+.I path
+component may be significant in the connection phase, prompting the addition of
+.B CONNECT_URL
+and
+.BR 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 (compatible with most Bourne shell derivatives)
+which will work with either a newer or older version:
+.nf
+.B sudo openconnect --cookie-on-stdin ${CONNECT_URL:-$HOST} --servercert $FINGERPRINT ${RESOLVE:+--resolve=$RESOLVE}
 .fi
 .TP
 .B \-\-cookieonly
-Fetch and print cookie only; don't connect
+Fetch and print cookie only; don't connect (this is essentially a subset of
+.BR \-\-authenticate ).
 .TP
 .B \-\-printcookie
-Print cookie before connecting
+Print cookie to stdout before connecting (see
+.B \-\-authenticate
+for the meaning of this cookie)
 .TP
 .B \-\-cafile=FILE
 Additional CA file for server verification. By default, this simply