SF Patch #1470711 - Fix documentation about SSL install/config

git-svn-id: http://scm.dspace.org/svn/repo/trunk@1511 9c30dcfa-912a-0410-8fc2-9e0234be79fd

dspace/CHANGES

@@ -58,6 +58,7 @@
   SF Patch #1456135 - Update search section of business.html
   SF bug #1456531 - Installation doc updates
   SF bug #1456557 - Upgrade docs modifications
+  SF Patch #1470711 - Fix documentation about SSL install/config
   
 (Zuki Ebetsu)
 - Fix malformed Japanese texts in RSS feed

dspace/docs/configure.html

@@ -466,14 +466,14 @@ metadata.dc.description.abstract = Abstract</pre>
   </li>
   <p><li>
   Add the <code>org.dspace.eperson.X509Authentication</code> plugin
-  to the list of stackable authentication methods in the value
+  <em>first</em> to the list of stackable authentication methods in the value
   of the configuration key <code>plugin.sequence.org.dspace.eperson.AuthenticationMethod</code>
   <i>E.g.:</i>
   </p>
   <pre>
     plugin.sequence.org.dspace.eperson.AuthenticationMethod = \
-        org.dspace.eperson.PasswordAuthentication, \
-        org.dspace.eperson.X509Authentication
+        org.dspace.eperson.X509Authentication, \
+        org.dspace.eperson.PasswordAuthentication
   </pre>
 
   </li>

dspace/docs/install.html

@@ -286,27 +286,14 @@ See the <code>dspace.cfg</code> file for examples.
 
     <p>
     The solution is to use <em>HTTPS</em> (HTTP over SSL, i.e. Secure
-    Socket Layer, an encrypted transport), which keeps your passwords
-    from being captured.  You can configure DSpace to require SSL on
+    Socket Layer, an encrypted transport), which protects your passwords
+    against being captured.  You can configure DSpace to require SSL on
     all "authenticated" transactions so it only accepts passwords
     on SSL connections.
     <p>
-    The steps are:
+	The following sections show how to set up the most commonly-used Java Servlet containers to support HTTP over SSL.
 
-    <ol><li>Configure DSpace to require SSL from the webserver.  Add or
-    uncomment this line in <code>[dspace-source]/conf/dspace.cfg</code>:
-    <pre>webui.require.confidential = true</pre>
-
-    (Note that you are chaning this in the <em>source</em> directory's
-    configuration; changing the installed <code>dspace.cfg</code> has no
-    effect.)  Now, rebuild and redeploy the webapp WAR files, e.g.
-    <pre>ant build_wars</pre>
-
-    <p><li>Configure your Web server or servlet container to support HTTPS,
-    using one of the options below.
-    </ol>
-
-    <P><strong>To enable the HTTPS support in Tomcat 5.0:</strong>
+    <h4>To enable the HTTPS support in Tomcat 5.0:</h4>
 
     <ol><li><b>For Production use:</b> Follow this procedure to
       set up SSL on your server.  Using a "real" server certificate
@@ -405,17 +392,44 @@ See the <code>dspace.cfg</code> file for examples.
         </ol>
     </ol>
 
-    <P><strong>To use Apache HTTPD:</strong> The DSpace source bundle includes a partial Apache configuration <code>apache13.conf</code>, which contains most of the DSpace-specific configuration required.  It assumes you're using <A HREF="http://jakarta.apache.org/tomcat/tomcat-4.1-doc/config/webapp.html">mod_webapp</A>, which is deprecated and tricky to compile but a lot easier to configure than <code>mod_jk2</code> which is the current recommendation from Tomcat.   Use of this is optional, you might just want to use it as an example.  To use it directly, in the main Apache <code>httpd.conf</code>, you should:</P>
+	<h4>To use SSL on Apache HTTPD with mod_jk:</h4>
+    If you choose <a href="http://httpd.apache.org/">Apache HTTPD</a>
+    as your primary HTTP server, you can have it forward requests to
+    the <a href="http://tomcat.apache.org/">Tomcat servlet container</a> via
+    <a href="http://tomcat.apache.org/connectors-doc/">Apache
+    Jakarta Tomcat Connector</a>.  This can be configured to work
+    over SSL as well.
+    <p>
+    First, you must configure Apache for SSL; for Apache 2.0
+    see <a href="http://httpd.apache.org/docs/2.0/ssl/">
+    Apache SSL/TLS Encryption</a> for information about using
+    <a href="http://httpd.apache.org/docs/2.0/mod/mod_ssl.html">mod_ssl</a>.
+    <p>
+    <em><b>If you are using X.509 Client Certificates for authentication:</b></em>
+    add these configuration options to the appropriate <i>httpd</i>
+    configuration file, e.g. <code>ssl.conf</code>, and be sure they
+    are in force for the virtual host and namespace locations dedicated to DSpace:
+    <pre>
+        ##  SSLVerifyClient can be "optional" or "require"
+        SSLVerifyClient optional
+        SSLVerifyDepth  10
+        SSLCACertificateFile  <i>path-to-your-client-CA-certificate</i>
+        SSLOptions StdEnvVars ExportCertData
+    </pre>
+    <p>
+    Now consult the
+    <a href="http://tomcat.apache.org/connectors-doc/">Apache
+    Jakarta Tomcat Connector</a> documentation to configure the
+    <code>mod_jk</code> (note: <b>NOT</b> <code>mod_jk2</code>) module.
+    Select the AJP 1.3 connector protocol.
+    Also follow the instructions there to configure your Tomcat server to
+    respond to AJP.
 
-    <UL>
-      <LI>Make sure <code>mod_ssl</code> and <code>mod_webapp</code> are configured and loaded</LI>
-      <LI>Remove/comment out etc. any existing or default SSL virtual host</LI>
-      <LI>Ensure Apache will run with the UNIX user and group DSpace will run as</LI>
-      <LI>Include the DSpace part, e.g. with: <code>Include <i>[dspace]</i>/config/httpd.conf</code>.  You can decide where the DSpace part will go in your file system--see the <A HREF="configure.html#templates">configuration section</A>.</LI>
-    </UL>
+	<p><strong>NOTE:</strong> Apache have deprecated the mod_webapp connector and recommend mod_jk. If you intend to use mod_webapp there are some notes on setting this up in the DSpace 1.3.2 documentation.</p>
 
-    <P><strong>To use Jetty's HTTPS support</strong> consult the documentation for the relevant tool.</P>
+    <p><strong>To use SSL on Apache HTTPD with mod_webapp</strong> consult the DSpace 1.3.2 documentation. Apache have deprecated the <code>mod_webapp</code> connector and recommend using <code>mod_jk</code>.</p>
 
+    <p><strong>To use Jetty's HTTPS support</strong> consult the documentation for the relevant tool.</p>
 
 
     <H3><A NAME="handles">The Handle Server</A></H3>