[LON-CAPA-cvs] cvs: loncom /html/adm/help/tex Domain_Configuration_SSL.tex doc/help domain.manual.texxml

[raeburn]

raeburn		Thu May 26 01:08:10 2011 EDT

  Added files:                 
    /loncom/html/adm/help/tex	Domain_Configuration_SSL.tex 

  Modified files:              
    /doc/help	domain.manual.texxml 
  Log:
  - Documentation on use of SSL in Domain Coordination manual.
  
  
Index: doc/help/domain.manual.texxml
diff -u doc/help/domain.manual.texxml:1.9 doc/help/domain.manual.texxml:1.10
--- doc/help/domain.manual.texxml:1.9	Mon May 23 22:17:10 2011
+++ doc/help/domain.manual.texxml	Thu May 26 01:08:06 2011
@@ -56,6 +56,9 @@
         <subsection name="User Session Hosting">
                 <file name="Domain_Configuration_User_Sessions.tex" />
         </subsection>
+        <subsection name="Encrypting server traffic with SSL">
+                <file name="Domain_Configuration_SSL.tex" />
+        </subsection>
 </section>
 <section name="Domain Management">
         <subsection name="Creating Domain Coordinators">

Index: loncom/html/adm/help/tex/Domain_Configuration_SSL.tex
+++ loncom/html/adm/help/tex/Domain_Configuration_SSL.tex
\label{Domain_Configuration_SSL}
There are two different contexts in which a LON-CAPA server may communicate
via SSL (Secure Sockets Layer):

\begin{itemize}
\item Encrypted web pages served by Apache via port 443.
In this case, client requests will be for URLs beginning https://.
\item Encrypted internal communication between LON-CAPA servers via port 5663.


\textbf{Apache SSL}


In the case of Apache, the steps required depend on the Linux distro.
\begin{itemize}
\item CentOS/RedHat/Scientific Linux/Fedora:
\begin{quote}
\emph{yum install mod\_ssl}
\end{quote}
\item SuSE/SLES:
\begin{quote}
Check that ssl is included in the list of modules in the \emph{APACHE\_MODULES} string 
in \emph{/etc/sysconfig/apache2}.
\end{quote}
\item Debian/Ubuntu LTS:
\begin{quote}
\emph{a2enmod ssl}
\end{quote}
\end{itemize}


For all distros you will need to install a key, generate a certificate signing
request with that key, and have the certificate signed. You will also want to 
disable the passphrase prompt on web server restart by removing the password from
the copy of the key you use with Apache, e.g., 
\begin{quote}
\emph{openssl rsa -in server.key -out server.key.nopass}
\end{quote}
You will then put the the (nopass) key and certificate files in locations 
accessible to Apache, and include information about the locations of those files 
in a config file containing the following lines: 
\begin{quote}
  SSLCertificateFile <path to signed certificate>
\end{quote}
\begin{quote}
  SSLCertificateKeyFile <path to key>
\end{quote}
replacing <path to ...> with the path to the location of the particular file.


Which Apache config file contains these entries depends on the distro: 

\begin{itemize}
\item CentOS/RedHat/Scientific Linux/Fedora:
\begin{quote}
/etc/httpd/conf.d/ssl.conf
\end{quote}
\item SuSE/SLES
\begin{quote}
/etc/apache2/vhosts.d/vhost-ssl.conf 
\end{quote}
\begin{quote}
(copied from vhost-ssl.conf with
the entry for DocumentRoot changed to ``/home/httpd/html'').
\end{quote}
\item Debian/Ubuntu LTS
\begin{quote}
/etc/apache2/sites-available/000-default-ssl
\end{quote}
\end{itemize}

If you want to use rewrite rules to ensure that all external web requests are 
served using SSL, you should verify that mod\_rewrite is enabled:

\begin{itemize}
\item CentOS/RedHat/Scientific Linux/Fedora
\begin{quote}
Verify that the following entry in /etc/httpd/conf/httpd.conf is not commented out:
\emph{LoadModule rewrite\_module modules/mod\_rewrite.so}
\end{quote}
\item SuSE/SLES
\begin{quote}
Check that \emph{rewrite} is included in the list of modules in the 
\emph{APACHE\_MODULES} string in /etc/sysconfig/apache2.
\end{quote}
\item Debian/Ubuntu LTS
\begin{quote}
\emph{a2enmod rewrite}
\end{quote}
\end{itemize}

You will also need to copy the rewrites/loncapa\_rewrite\_on.conf file to
loncapa\_rewrite.conf with the following commands: 
\begin{itemize}
\item CentOS/RedHat/Scientific Linux/Fedora
\begin{quote}
\emph{cp /etc/httpd/conf/rewrites/loncapa\_rewrite.conf /etc/httpd/conf/loncapa\_rewrite.conf}
\end{quote}
\item SuSE/SLES/Debian/Ubuntu LTS
\begin{quote}
\emph{cp /etc/apache2/rewrites/loncapa\_rewrite\_on.conf /etc/apache2/loncapa\_rewrite.conf}
\end{quote}
\end{itemize}

and then reload the web server:
\begin{itemize}
\item CentOS/RedHat/Scientific Linux/Fedora
\begin{quote}
\emph{cp /etc/init.d/httpd reload}
\end{quote}
\item SuSE/SLES/Debian/Ubuntu LTS
\begin{quote}
\emph{cp /etc/init.d/apache2 reload}
\end{quote}
\end{itemize}

If you want to disable rewriting of external web requests to https://, copy 
rewrites/loncapa\_rewrite\_off.conf to loncapa\_rewrite.conf and reload the web 
server.

You will need to open the server's Firewall to allow inbound traffic on port 443.
\begin{itemize}
\item CentOS/RedHat/Scientific Linux
\begin{quote}
\emph{/usr/bin/system-config-securitylevel-tui}
\end{quote}
\item Fedora
\begin{quote}
\emph{/usr/bin/system-config-firewall-tui}
\end{quote}
\item SuSE/SLES
\begin{quote}
yast -\> Security and Users -> Firewall 
\end{quote}
\item Debian 6/Ubuntu LTS
\begin{quote}
\emph{ufw allow 443/tcp}
\end{quote}
\end{itemize}

Note: changing firewall settings will cause iptables to reload, which means the
rules to allow connections from other LON-CAPA servers via port 5663 will need to
be re-established (if the LON-CAPA daemons were already running) by doing: \emph{/etc/init.d/loncontrol restart} as root.

\textbf{Internal LON-CAPA SSL} 


In the case of encrypted internal communication between LON-CAPA servers, 
you will need command line access as either root or www and enter the following
commands:

\begin{quote}
\emph{cd /home/httpd/lonCerts}
\end{quote}
\begin{quote}
\emph{sh request\_ssl\_key.sh}
\end{quote}

\textbf{Important}: for the Common Name you should enter the lonHostID.
This is displayed on the log-in page (Server: ) and is also an entry in the 
loncapa.conf file in /etc/httpd/conf (CentOS/RedHat/Scientific Linux/Fedora)
or /etc/apache2 (SuSE/SLES/Debian/Ubuntu LTS).  An example would be msul1.

By running \emph{request\_ssl\_key.sh} you will:
\begin{itemize}
\item Generate a private/public key pair. 
\begin{quote}
The private key will be stored in /home/httpd/lonCerts/lonKey.pem
It will be set so that only www can read this file. (You will want to
make sure this file stays secret).
\end{quote}
\item Automatically send an e-mail to the LON-CAPA certificate authority. 
containing your public key so LON-CAPA can sign it.
\end{itemize}

Your certificate will be signed by the certificate authority and an e-mail
will be sent to the e-mail address you gave when prompted for one 
when you ran request\_ssl\_key.sh.

Save the email you receive to a file, remove the headers from it, 
and run it (as the \emph{www} user).

If it successfully completes you will have:

\begin{itemize} 
\item /home/httpd/lonCerts/lonhostcert.pem
\begin{quote}
(your signed public key)
\end{quote}
\item /home/httpd/lonCerts/loncapaCA.pem  
\begin{quote}
(the public key of the Lon-CAPA certificate authority)
\end{quote}
\end{itemize}

Now when you machine connects to another server in the LON-CAPA 
network it will try to do so over an SSL connection. 
You can verify this by doing:
\begin{quote}

\emph{ps auxwww | grep lonc}

\end{quote}

You should see something like:
\begin{quote}
lonc: msul1 Connection count: 1 Retries remaining: 5 (ssl) 
\end{quote}
where before you saw something like:
\begin{quote}
lonc: msul1 Connection count: 1 Retries remaining: 5 (insecure)
\end{quote}