Merge branch 'doc_updates' into 'master'

Documentation updates See merge request openconnect/openconnect!327
sailfishos-mirror · Jan 30, 2022 · f9bff45 · f9bff45
2 parents 26d6941 + 2beb06b
commit f9bff45
Show file tree

Hide file tree

Showing 9 changed files with 268 additions and 15 deletions.
diff --git a/www/Makefile.am b/www/Makefile.am
@@ -7,9 +7,10 @@ FTR_PAGES = csd.html charset.html token.html pkcs11.html tpm.html features.html
 START_PAGES = building.html connecting.html manual.html vpnc-script.html
 INDEX_PAGES = changelog.html download.html index.html packages.html platforms.html licence.html
 PROTO_PAGES = protocols.html anyconnect.html array.html fortinet.html f5.html globalprotect.html juniper.html pulse.html
-TOPLEVEL_PAGES = contribute.html mail.html
+CONTR_PAGES = contribute.html mitm.html
+TOPLEVEL_PAGES = mail.html
 
-ALL_PAGES = $(FTR_PAGES) $(START_PAGES) $(INDEX_PAGES) $(TOPLEVEL_PAGES) $(PROTO_PAGES)
+ALL_PAGES = $(FTR_PAGES) $(START_PAGES) $(INDEX_PAGES) $(TOPLEVEL_PAGES) $(PROTO_PAGES) $(CONTR_PAGES)
 
 html_DATA = $(ALL_PAGES)
 
@@ -23,6 +24,7 @@ $(ALL_PAGES): menu1.xml $(srcdir)/inc/*.tmpl
 $(FTR_PAGES): menu2-features.xml
 $(START_PAGES): menu2-started.xml
 $(PROTO_PAGES): menu2-protocols.xml
+$(CONTR_PAGES): menu2-contribute.xml
 $(MAIN_PAGES): menu2.xml
 
 manual.html: openconnect.8.inc

diff --git a/www/building.xml b/www/building.xml
@@ -47,14 +47,16 @@ on the command line.</p>
  <p>OpenConnect should be given a default <a href="vpnc-script.html">vpnc-script</a>
  for network configuration (routing and DNS) at compile-time. This can be overridden
  at runtime (with <tt>--script</tt>).</p>
- <p>The <tt>configure</tt> script will check whether <tt>/etc/vpnc/vpnc-script</tt>
+ <p>The <tt>configure</tt> script will check whether either
+ <tt>/etc/vpnc/vpnc-script</tt> or <tt>/usr/share/vpnc-scripts/vpnc-script</tt>
  exists and can be executed, and will fail if not. If you don't already have
  a copy then you should install one. It might be in a separate <tt>vpnc-script</tt>
  package for your operating system, it might be part of their <tt>vpnc</tt> package,
  and there's one linked from the <a href="vpnc-script.html">vpnc-script page</a>, if
  you need to download it manually. Install it as <tt>/etc/vpnc/vpnc-script</tt>.</p>
 
-<p>If you do not want to use the standard location, you can configure OpenConnect to
+<p>If you do not want to OpenConnect to use a vpnc-script from one of these
+ standard locations, you can configure OpenConnect to
  use a different location by default. When running the <tt>./configure</tt> script
  in the instructions below, you can append an argument such as <tt>--with-vpnc-script=<i>/where/I/put/vpnc-script</i></tt> to its command line. Note that the path you give will not be checked; the script doesn't have to be present when you <b>build</b> OpenConnect. But of course OpenConnect won't work very
 well without it, so you'll still have to install it later.</p>

diff --git a/www/changelog.xml b/www/changelog.xml
@@ -39,7 +39,7 @@
        <li>Add support for PPP-based protocols, currently over TLS only (<a href="https://gitlab.com/openconnect/openconnect/-/merge_requests/165">!165</a>).</li>
        <li>Add support for two PPP-based protocols, F5 with <tt>--protocol=f5</tt> and Fortinet with <tt>--protocol=fortinet</tt> (<a href="https://gitlab.com/openconnect/openconnect/-/merge_requests/169">!169</a>).</li>
        <li>Add experimental support for <a href="https://www.wintun.net/">Wintun</a> Layer 3 TUN driver under Windows (<a href="https://gitlab.com/openconnect/openconnect/-/issues/231">#231</a>, <a href="https://gitlab.com/openconnect/openconnect/-/merge_requests/178">!178</a>).</li>
-       <li>Clean up and improve Windows routing/DNS configuration script (<a href="https://gitlab.com/openconnect/vpnc-scripts/-/merge_requests/26">vpnc-scripts!26</a>).</li>
+       <li>Clean up and improve Windows routing/DNS configuration script (<a href="https://gitlab.com/openconnect/vpnc-scripts/-/merge_requests/26">vpnc-scripts!26</a>, <a href="https://gitlab.com/openconnect/vpnc-scripts/-/merge_requests/41">vpnc-scripts!41</a>, <a href="https://gitlab.com/openconnect/vpnc-scripts/-/merge_requests/44">vpnc-scripts!44</a>).</li>
        <li>On Windows, reclaim needed IP addresses from down network interfaces so that configuration script can succeed (<a href="https://gitlab.com/openconnect/openconnect/-/merge_requests/178">!178</a>).</li>
        <li>Fix output redirection under Windows (<a href="https://gitlab.com/openconnect/openconnect/-/issues/229">#229</a>)</li>
        <li>More gracefully handle idle timeouts and other fatal errors for Juniper and Pulse (<a href="https://gitlab.com/openconnect/openconnect/-/merge_requests/187">!187</a>)</li>

diff --git a/www/contribute.xml b/www/contribute.xml
@@ -2,7 +2,9 @@
 	<INCLUDE file="inc/header.tmpl" />
 
 	<VAR match="VAR_SEL_CONTRIBUTE" replace="selected" />
+	<VAR match="VAR_SEL_CONTRIB_MAIN" replace="selected" />
 	<PARSE file="menu1.xml" />
+	<PARSE file="menu2-contribute.xml" />
 
 	<INCLUDE file="inc/content.tmpl" />
 
@@ -98,8 +100,6 @@ bout it.</p>
 it should. There are some things which the regular developers don't have easy access to test,
 some help with testing these would be particularly welcome:</p>
 <ul>
-  <li><b>Testing a PAN GlobalProtect VPN with IPv6 internal addresses.</b><br/>
-  We think we know how this works, but we've not been able to test.</li>
   <li><b>Various authentication methods for Pulse Secure.</b><br/>
   Although it looked sane at first, the Pulse protocol has a lot of horrid
   special cases. Aside from the <a href="tncc.html">Host Checker</a> most
@@ -108,27 +108,42 @@ some help with testing these would be particularly welcome:</p>
 </ul>
 
 
+<a name="new-protocols"/>
 <h2>New Protocols</h2>
 
 <p>There are some other protocols which would be good to add to OpenConnect. Getting a new
 protocol to the point where it basically works to send and receive traffic is only a
 few hours of work, and can be very rewarding.</p>
 
-<p>For some protocols we already know how they work on the wire and it's mostly
-just a matter of typing. For others we might have to observe the existing clients
-to learn how they work.</p>
+<p>For some protocols we already know how they work on the wire and it's mostly just
+a matter of writing the code. For others we might have to <a href="mitm.html">observe
+the existing clients</a> to learn how they work.</p>
+
 <p>These would be great projects for someone to take on as a learning exercise, or
 perhaps even Google Summer of Code projects.</p>
 
 <ul>
   <li><b><a href="https://www.checkpoint.com/products/endpoint-remote-access-vpn-software-blade/">CheckPoint VPN</a></b><br/>
-  This is an IPSec-based VPN with fallback to using the SSL transport. Some discussion of OpenConnect support in this <a href="https://gitlab.com/openconnect/openconnect/issues/13">GitLab ticket</a>. </li>
+  This is an IPSec-based VPN with fallback to using the SSL transport. Some discussion of OpenConnect support in this <a href="https://gitlab.com/openconnect/openconnect/issues/13">GitLab ticket</a>,
+  and working code contributed in <a href="https://gitlab.com/openconnect/openconnect/-/merge_requests/207">MR !207</a>.</li>
   <li><b>Cisco / Nortel IPSec VPN</b><br/>
   These IPSec-based protocols are already supported by <a href="https://www.unix-ag.uni-kl.de/~massar/vpnc/">vpnc</a> to differing extents, but vpnc is no longer actively maintained.
   Since OpenConnect now has ESP support, and since some of these protocols also fall back to operating over TCP when UDP and native ESP aren't available, it may make sense to implement them in OpenConnect now.</li>
+  <li><b>External authentication support for multiple protocols.</b><br/>
+  Many VPNs now use SAML or other technologies to hand off the login/authentication
+  process to a <a href="https://en.wikipedia.org/wiki/Single_sign-on">single sign-on</a> (SSO)
+  provider. Okta and Microsoft Azure are well known cloud-based SSO providers.
+  We have numerous <a href="https://gitlab.com/openconnect/openconnect/-/issues?label_name%5B%5D=External+Auth%2FSAML%2FSSO">issues</a> and
+  <a href="https://gitlab.com/openconnect/openconnect/-/merge_requests?label_name[]=External+Auth%2FSAML%2FSSO">merge requests</a> labeled
+  <tt>External Auth/SAML/SSO</tt>. This is an area where there is a large amount of
+  commonal functionality across protocols, but also a large amount of variation in
+  the details, and where we need careful help designing suitable interfaces for
+  the interactions between OpenConnect's core code, VPN protocol-specific authentication code,
+  and external interfaces for authentication (e.g. web browsers or graphical pop-up
+  interfaces).</li>
 </ul>
 
-<p>Suggestions for other protocols which OpenConnect could usefully implement, are also welcome.</p>
+<p>Suggestions for other protocols which OpenConnect could usefully implement are also welcome.</p>
 
 <h2>Other enhancements</h2>
 

diff --git a/www/html.py b/www/html.py
@@ -44,6 +44,9 @@ def usage():
 def replaceVars(line):
     cnt = 0
     while cnt < len(replace):
+	# FIXME: this will match partial variable names, e.g. if XYZ and XYZ_ABC
+	# are both in the replacement list, and XYZ appears first, it will
+	# match and (partially) replace occurrences of XYZ_ABC.
         if line.find(replace[cnt]) >= 0:
             line = line.replace(replace[cnt], replace[cnt+1])
         cnt += 2

diff --git a/www/mail.xml b/www/mail.xml
@@ -20,12 +20,18 @@
 
 	<h1>GitLab</h1>
 
-	<p>As an experiment we have created an <a href="https://gitlab.com/openconnect/openconnect">OpenConnect project</a> on GitLab.</p>
+	<p>We have created an <a href="https://gitlab.com/openconnect/openconnect">OpenConnect project</a> on GitLab.</p>
 
 	<p>You can file <a href="https://gitlab.com/openconnect/openconnect/issues">issues</a>
-	there, which may be slightly more effective than sending them in email. You can also
+	there, which may be more effective than sending them in email. You can also
 	submit <a href="https://gitlab.com/openconnect/openconnect/merge_requests">merge requests</a>.</p>
 
+	<p>In addition to allowing discussion of issues and code changes, OpenConnect is now
+	also using <a href="https://docs.gitlab.com/ee/ci/">GitLab CI</a> for continuous integration,
+	testing, and building of the software. For example, GitLab CI builds the the
+	<a href="packages.html#windows">Windows installers</a> for OpenConnect with each new
+	commit.</p>
+
     	<h1>Mailing list</h1>
 
 	<p>There is a mailing list at <tt><a href="mailto:[email protected]">

diff --git a/www/menu2-contribute.xml b/www/menu2-contribute.xml
@@ -0,0 +1,6 @@
+<PAGE>
+	<STARTMENU level="2"/>
+	<MENU topic="Contributing" link="contribute.html" mode="VAR_SEL_CONTRIB_MAIN" />
+	<MENU topic="Observing VPN clients" link="mitm.html" mode="VAR_SEL_CONTRIB_MITM" />
+	<ENDMENU />
+</PAGE>