Page History

Note:  Next revision cycle, start building everything into
$HOME/[app]-[version#] and creating a symlink to $HOME/[app] so that there is
no question about what the current, in use, directory is.

Note: When downloading software to install in these instructions, always
download the source code, and avoid binary installers.  Binary installers tend
to make inaccurate assumptions about what libraries you have installed on your
system, as well as other problems.

1. download openssl 0.9.8a source from http://www.openssl.org/source/. follow
   the instruction in the INSTALL document, compile and install the
   binaries. the default location is /usr/local/ssl. If you want to change it,
   run config like this:

cd /opt
tar -xzvf /root/openssl-0.9.8a.tar.gz
cd openssl-0.9.8a
./config --prefix=/usr/local/ssl --openssldir=/usr/local/ssl
make
make install

2. set up certificates:

  2a:  get the mitca at http://mv.ezproxy.com.ezproxyberklee.flo.org/mitClient.crt and save it as
       /usr/local/ssl/certs/mitClient.crt

  2b:  convert mitCA.crt to pem format:

openssl x509 -in /usr/local/ssl/certs/mitClient.crt -inform DER -outform \
PEM -out /usr/local/ssl/certs/mitCA.pem

  2c: Generate rsa key

      This simply generates some random stuff:

ps > /tmp/foo
ps -elf >> /tmp/foo
cd /usr/local/ssl/bin
./openssl genrsa -rand /tmp/foo 1024 >/usr/local/ssl/private/`hostname`-key.pem

  2d: Generate request for a certificate 

cd /usr/local/ssl/bin
./openssl req -key /usr/local/ssl/private/`hostname`-key.pem -new >../certs/`hostname`-req.pem

   send the file /usr/local/ssl/certs/`hostname`-req.pem to mitcert@mit.edu,

      Please be aware, the organization (O) is:
      Massachusetts Institute of Technology
      and the common name (CN) is the name of the server or
      service, including the domain name (.mit.edu).  Also, some servers, such
      as Thalia servers, can represent an entire subdomain.  These servers
      will need certificates issued with a wildcard in the domain name, such
      as *.isda-thalia-1.mit.edu.  

   Remember, if the server is a Thalia server, if will need a wildcard
   certificate and DNS record for *.[hostname], and if it is doing any type of
   authentication, it will need a joint client/server certificate to be able
   to connect to the Shibboleth server (and have end users connect to it as
   well).

   2db. To generate a self signed temporary certificate, add the x509 and
        nodes options to the openssl command line.

cd /usr/local/ssl/bin
./openssl req -key /usr/local/ssl/private/`hostname`-key.pem -new -x509 -nodes >../certs/`hostname`-temp.cert

  2e:When you receive a certificate from MIT Certificates, save it as  /usr/local/ssl/certs/`hostname`-cert.pem

  2f:  to look at a request:     

openssl req -in ./req.pem -text

      to look at the private key:   

openssl rsa -in /usr/local/ssl/private/`hostname`-key.pem -text

      to look at the server certificate:   

openssl x509 -in /usr/localx/ssl/certs/`hostname`-cert.pem -text

3 set up apache-ssl
  3a: download Apache 2.2.4 from apache archive site at
      http://archive.apache.org/dist/httpd/

  3b: Unpack apache 2.2.4 (tar -xzvf) and do "cd httpd-2.2.4"

cd /opt
tar -xzvf /root/httpd-2.2.4.tar.gz
cd httpd-2.2.4

  3c. compile apache following the instruction in the INSTALL file.
      To enable the SSL, do the following:

./configure --prefix=/home/apache --enable-ssl \
    --with-ssl=/usr/local/ssl \
    --enable-modules="most mod_rewrite"
make
make install

4. set up mod-jk

  4a. download mod-jk 1.2.21 source (previous versions have a security hole
      that could allow a remote attacker to execute arbitary code) from
      http://tomcat.apache.org/connectors-doc/.

cd /opt
tar -xzvf /root/tomcat-connectors-1.2.21-src.tar.gz
cd tomcat-connectors-1.2.21-src

  4b. build and install binaries according to BUILD.txt. apxs is at
      /home/apache/bin/apxs. mod_jk.so will be put at /home/apache/modules

cd native
./configure --with-apxs=/home/apache/bin/apxs --enable-ssl
make
make install

5. install jdk 1.6 which is required by tomcat 5.5.25

   5a. download jdk 1.6 binary at  http://java.sun.com/javase/downloads/index.jsp

   5b. You may need to set the binary file to be executable:

chmod u+x,u-w jdk-6-linux-i586.bin

5c. execute the binary installer as root. If it produces a rpm file,
use rpm -ivh to install it. If you downloaded the straight binary
installer, move to a directory with installed software, such as
/usr/local. Also, you will need to page through a licensing agreement
and type yes to accept it.

cd /usr/local
/root/jdk-6-linux-i586.bin

       or

./jdk-6-linux-i586-rpm.bin
rpm \-ivh jdk-6-linux-i586

   5d. create a file in /etc/profile.d named java_home.sh.  It should contain
        a line exporting a variable pointing to the Java home directory.  Then
        make this file world executable.:

cat > /etc/profile.d/java_home.sh
export JAVA_HOME=/usr/local/jdk1.6.0
^C
chmod a+xr,a-w /etc/profile.d/java_home.sh

6. install tomcat

   6a. download apache-tomcat-5.5.25.tar.gz from:   http://tomcat.apache.org/download-55.cgi

   6b. unzip and untar (gunzip , tar -xvf) into your working  directory, such as /home

cd /home
tar -xzvf /root/apache-tomcat-5.5.25.tar.gz
cd apache-tomcat-5.5.25

8. Do the configuration:
  8a. Tomcat part: cd into the tomcat home directory

cd /home/apache-tomcat-5.5.25

  8aa. enter the conf directory and create a jk directory

cd conf
mkdir jk
cd jk

    8ab. copy the workers.properties file from  /opt/tomcat-connectors-1.2.21-src/conf and put it in conf/jk

cp /opt/tomcat-connectors-1.2.21-src/conf/workers.properties /home/apache-tomcat-5.5.25/conf/jk

    8ac. make certain the following directives in workers.properties are set:

workers.tomcat_home=/home/apache-tomcat-5.5.25
workers.java_home=/usr/local/jdk1.6.0
ps=/
worker.list=ajp13
worker.ajp13.port=8009
worker.ajp13.host=localhost
worker.ajp13.type=ajp13
worker.ajp13.lbfactor=1
worker.loadbalancer.type=lb
worker.loadbalancer.balanced_workers= ajp13

    8aa. enter the conf directory and create a jk directory

      after

<Server port="8005" shutdown="SHUTDOWN">

add

<Listener className="org.apache.jk.config.ApacheConfig"
      modJk="/home/apache/modules/mod_jk.so" jkDebug="info"
      workersConfig="/home/apache-tomcat-5.5.25/conf/jk/workers.properties"
      jkLog="/home/apache-tomcat-5.5.25/logs/mod_jk.log"/>

      after

<Engine name="Catalina" defaultHost="localhost">

      add

<Listener className="org.apache.jk.config.ApacheConfig" append="true" />

     8ae. If this is going to be a Web Services servers, disable direct
          connections to tomcat and force communications to go through apache,
          by commenting out the port 8080 connector block in server.xml:

<\!-\-
     <Connector port="8080" maxHttpHeaderSize="8192"
            maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
            enableLookups="false" redirectPort="8443" acceptCount="100"
            connectionTimeout="20000" disableUploadTimeout="true" />
\-->

          If this is going to be a Thalia server, skip this step.

     8af. edit tomcat_users.xml, and add the following user definition just above the '</tomcat-users>' line:

<role rolename="manager"/>
         <user username="tomcat" password="*****" roles="tomcat,manager"/>

          be certain to change the password to be the password for the team the server is providing services to.  Check with your groups manager to see what the password
          standards for your group are.  Do not cut and paste this password into place, do not use "*****" as a password, etc.
     
     8ag. Run the java_home.sh script and start tomcat

source /etc/profile.d/java_home.sh
/home/apache-tomcat-5.5.25/bin/startup.sh

     8ah. Tomcat creates a mod_jk.conf file in conf/auto directory the first
          time is runs.  Correct it to point to where mod_jk.so resides

       change

LoadModule jk_module "/usr/local/apache/libexec/mod_jk.so"

       to

LoadModule jk_module "/home/apache/modules/mod_jk.so"

  8b. apache side: edit /home/apache/conf/httpd.conf
   edit the following directives:

ServerRoot "/home/apache" # change to apache home directory
User apache # change from daemon
Group apache # change from daemon
Include conf/extra/httpd-vhosts.conf # Uncomment
Include conf/extra/httpd-ssl.conf # Uncomment

  8c. add to /home/apache/conf/httpd.conf, near the end of the file,
       above the 'Include conf/extra/httpd-ssl.conf' directive:

<IfModule \!mod_rewrite.c>
LoadModule rewrite_module modules/mod_rewrite.so
</IfModule>

<IfModule \!mod_jk.c>
LoadModule jk_module "/home/apache/modules/mod_jk.so"
</IfModule>

JkWorkersFile "/home/apache-tomcat-5.5.25/conf/jk/workers.properties"
JkLogFile "/home/apache-tomcat-5.5.25/logs/mod_jk.log"

JkLogLevel info

  8d. edit /home/apache/conf/extra/httpd-vhosts.conf to have ONLY one of the
       following VirtualHost blocks:

     8d1. Thalia:

NameVirtualHost \*:80

<VirtualHost \*:80>
ServerName \*.isda-thalia2.mit.edu

RewriteEngine On

RewriteCond %{HTTP_HOST}   !^isda-thalia2\.mit\.edu [NC]
RewriteCond %{HTTP_HOST}   !^test\.isda-thalia2\.mit\.edu [NC]
RewriteCond %{HTTP_HOST}   !^demo\.isda-thalia2\.mit\.edu [NC]
RewriteCond %{HTTP_HOST}   !^hst\.isda-thalia2\.mit\.edu [NC]
RewriteCond %{HTTP_HOST}   !^ap\.isda-thalia2\.mit\.edu [NC]
RewriteRule ^/(.*)         [http://mv.ezproxy.com.ezproxyberklee.flo.org/$1] [L,R]
</VirtualHost>

     8d2. Web Services:

<VirtualHost \*:80>
RedirectPermanent [https://mv-ezproxy-com.ezproxyberklee.flo.org/]
</VirtualHost>

  8e. edit /home/apache/conf/extra/httpd-ssl.conf and alter the following
       directives:

# points to directory for static html files
DocumentRoot "/home/apache/htdocs"

# the servername of the server
ServerName isda-ws2.mit.edu:443

# the admins of this server
ServerAdmin dracus@mit.edu,dongq@mit.edu,dtanner@mit.edu

# error log file
ErrorLog /home/apache/logs/error_log

# access log file
TransferLog /home/apache/logs/access_log

# public server certificate
SSLCertificateFile /usr/local/ssl/certs/isda-ws2.pem

# private server certificate
SSLCertificateKeyFile /usr/local/ssl/private/https-key.pem

#certificate path
SSLCACertificatePath /usr/local/ssl/certs

# certificate authority key
SSLCACertificateFile /usr/local/ssl/certs/mitCA.pem

SSLVerifyClient require
SSLVerifyDepth  10

   8f. add the following after the '<Directory "/home/apache/cgi-bin">'
       block in /home/apache/conf/extras/httpd-ssl.conf

SSLOptions \+StdEnvVars \+ExportCertData

   8g. add the following at the end of /home/apache/conf/extra/httpd-ssl.conf:

JKMount / ajp13
JKMount /* ajp13

JkMount /manager ajp13
JkMount /manager/* ajp13

JkMount /uaws ajp13
JkMount /uaws/* ajp13

JkMount /webdav ajp13
JkMount /webdav/* ajp13

JkMount /geows ajp13
JkMount /geows/* ajp13

JkMount /servlets-examples ajp13
JkMount /servlets-examples/* ajp13
JkMount /tomcat-docs ajp13
JkMount /tomcat-docs/* ajp13
JkMount /host-manager ajp13
JkMount /host-manager/* ajp13

JkMount /jsp-examples ajp13
JkMount /jsp-examples/* ajp13

JkMount /balancer ajp13
JkMount /balancer/* ajp13

JkMount /mitidws ajp13
JkMount /mitidws/* ajp13

9. to pass environment variables from apache to tomcat, add the following to
   the end of httpd.conf (note, the name for those environment variables might
   change between different apache versions. Apache comes with a cgi script in
   cgi-bin/printenv. Run this script in your https enabled browser to verify
   that these variables still holds).

JkEnvVar SSL_CLIENT_DN nodefault
JkEnvVar SSL_CLIENT_S_DN_CN nodefault
JkEnvVar SSL_CLIENT_S_DN_Email nodefault
JkEnvVar SSL_CLIENT_S_DN nodefault
JkEnvVar HTTP_ACCEPT_LANGUAGE nodefault
JkEnvVar SSL_CLIENT_CERT none

10. copy the following files to the noted locations.  They should be bundled
   with this document:

     MitIdService.jar   moves to:
        /home/apache-tomcat-5.5.25/shared/lib

     rolesApplicationContext.xml   moves to:
        /home/apache-tomcat-5.5.25/shared/classes

     rootauth  moves to
        /root

11. install the web init script into /etc/init.d, and place starter links into
    the /etc/rc.d/ runlevel directories.  It should be bundled with this
    document.

  11a.  edit the variables in the top section of the web file to use the
        directories and binaries correct for this system

  11b.  be certain to check if apache is using a httpdctl or apachectl starter
        program, usually contained in /home/apache/bin, and set the apachectl
        variable accordingly

  11c.  set web to be executable

chmod a+rx,a-w /etc/init.d/web

  11d.  link startweb and stopweb to the web program, from wherever it is
        located, and link start scripts in /etc/init.d:

ln \-s /etc/init.d/web /root/startweb
ln \-s /etc/init.d/web /root/stopweb
ln \-s /etc/init.d/web /etc/rc.d/rc1.d/K15web
ln \-s /etc/init.d/web /etc/rc.d/rc2.d/K15web
ln \-s /etc/init.d/web /etc/rc.d/rc3.d/K15web
ln \-s /etc/init.d/web /etc/rc.d/rc4.d/K15web
ln \-s /etc/init.d/web /etc/rc.d/rc5.d/K15web
ln \-s /etc/init.d/web /etc/rc.d/rc6.d/K15web
ln \-s /etc/init.d/web /etc/rc.d/rc2.d/S15web
ln \-s /etc/init.d/web /etc/rc.d/rc3.d/S15web
ln \-s /etc/init.d/web /etc/rc.d/rc4.d/S15web
ln \-s /etc/init.d/web /etc/rc.d/rc5.d/S15web

12. Add line to /var/spool/cron/root to cause rootauth to run every 15 min, and
    freshen the Kerberos tickets.

cat >> /var/spool/cron/root
0,15,30,45 * * * * /root/rootauth
\^C

13. update paths in /etc/profile, by adding the following line in the path
    manipulation code block (you can find it by searching for /usr/local/sbin)

pathmunge /usr/local/bin
pathmunge /usr/kerberos/bin

14. If this is an upgrade on a server that had previously had a tomcat on it,
    there are additional steps to move necessay files and code to the new
    directories.

  14a.  copy the webapps from the old deploy of tomcat to the new one.  Be certain
        to restart the server if it was running previously.

cd /home/apache-tomcat-5.5.25
cp \-a geows\* mapws\* mitidws\* uaws\* testcert\* TestRemoteAlfresco\* /home/apache-tomcat-5.5.25/webapps/

    to see the applications deployed on a server that are not part of the
    default tomcat install, get a listing of the directory:

ls \-1 \--hide=balancer \--hide ROOT \--hide=jsp-examples \--hide=servlets-examples \--hide=tomcat-docs \--hide=webdav

  14b.  Move the /home/https/weblib directory into /home

mv /home/https/weblib/ /home/weblib
ln \-s /home/weblib /home/https/weblib

        Alternatively, if there is not /home/https/weblib, create a /home/weblib directory

mkdir /home/weblib

  14c.  Edit /etc/init.d/web to have the following global variable:

export LD_LIBRARY_PATH=/usr/lib:/home/weblib

  14d.  Restart web services and tomcat

/etc/init.d/web restart

15. Install an AFS client, or check that a client is installed.

  15a. Check if an AFS client is installed by looking at the root directory.
       If a client is installed, the afs directory will be near the top.

ls \-l /

  15b. If an AFS client is not installed, download these packages from the MIT
       Athena or Thalia software lockers:

mit-openafs-setup-1.2-3.noarch.rpm
mit-krb-config-1.0-3.noarch.rpm
mit-openafs-package.patch

  15c. Use rpm to install these packages, installing the Kerberos
       configuration package first.

rpm \-ivh mit-krb-config-1.0-3.noarch.rpm
rpm \-ivh mit-openafs-setup-1.2-3.noarch.rpm

       Please note: There are no paths in these commands.  Store them in a
       conveinent install directory, and cd to it first.

  15d. Go to the OpenAFS client binary directory and execute the setup It will ask if you want the AFS client to be started at boot time.  Type yes.

cd /opt/mit-openafs-setup/bin
./setup

       If system is a SMP (multiprocessor) machine, apply the SMP patch before compiling.

patch /root/mit-openafs-package.patch
cd /opt/mit-openafs-setup/bin
./setup

16. Install version of moira that uses Kerberos 5

  16a. upload moira-rhel4-clients.tar.gz onto the server, and untar to /usr/local

cd /usr/local
tar \-xzvf /root/moira-rhel4-clients.tar.gz

17. To start and stop tomcat and apache, use the initialization scripts in
    /etc/init.d.  Be certain to leave them running when you are finished.

   starting

/etc/init.d/web start

   stopping

/etc/init.d/web stop