NFuse on Linux with Apache, Tomcat, and OpenSSL

Chris Purcell
July 2003
last updated 8/1/2003
nfuse at cjp dot us


Citrix NFuse on Linux with Apache, Tomcat, and OpenSSL


Software used
Apache 2.0.46
Tomcat 4.1.24
Sun Java2 SDK 1.4.1_03
OpenSSL 0.9.7b
Citrix Web Interface 2.0 (aka NFuse Classic)
mod_jk.so
Citrix MetaFrame XP FR3 for Windows 2000

Operating System
These instructions have been tested to work on Red Hat Linux 9.0, Red Hat Advanced Server 2.1, and SuSE Linux 8.2.

Downloads
Apache - http://www.apache.org/
Tomcat - http://jakarta.apache.org/tomcat/
Sun Java - http://java.sun.com/
OpenSSL - http://www.openssl.org/
mod_jk - http://jakarta.apache.org/builds/jakarta-tomcat-connectors/jk/release/v1.2.2/bin/linux/i386/mod_jk-2.0.43.so


Untar the sources to /usr/local/src/

tar zxvf apache_2.0.46.tar.gz -C /usr/local/src/
tar zxvf mod_ssl-2.8.14-1.3.27.tar.gz -C /usr/local/src/
tar zxvf jakarta-tomcat-4.1.24-LE-jdk14.tar.gz -C /usr/local/src/
tar zxvf openssl-0.9.7b.tar.gz -C /usr/local/src/


Copy the Tomcat folder to /usr/local and create a symlink for it to /usr/local/tomcat

cp -r jakarta-tomcat-4.1.24/ /usr/local/
ln -s /usr/local/jakarta-tomcat-4.1.24 /usr/local/tomcat



Install Sun Java2 SDK
./j2sdk-1_4_1_03-linux-i586.bin
# This will create a folder called j2sdk1.4.1_03 in the current directory
cp -r j2sdk1.4.1_03/ /usr/local/
ln -s /usr/local/j2sdk1.4.1_03/ /usr/local/java



Install OpenSSL to /usr/local/ssl
cd /usr/local/src/openssl-0.9.7b/
./config
make && make install



Set some environment variables in /etc/profile
export CATALINA_HOME=/usr/local/tomcat/
export JAVA_HOME=/usr/local/java
export SSL_BASE=/usr/local/ssl
export APACHE_HOME=/usr/local/apache2


Add the export commands to a startup file, such as /etc/profile

echo "" >> /etc/profile
echo "#Set a few environmental variables for Tomcat, Java, SSL, and Apache" >> /etc/profile
echo "export CATALINA_HOME=/usr/local/tomcat/" >> /etc/profile
echo "export JAVA_HOME=/usr/local/java" >> /etc/profile
echo "export SSL_BASE=/usr/local/ssl" >> /etc/profile
echo "export APACHE_HOME=/usr/local/apache2" >> /etc/profile



Apache 2.0.46 + SSL

Installation
tar zxvf httpd-2.0.46.tar.gz -C /usr/local/src
cd /usr/local/src/httpd-2.0.46
./configure --prefix=/usr/local/apache2 --enable-ssl --with-ssl=/usr/local/ssl
make && make install



mod_jk
The mod_jk.so library is a dynamically loaded module that Apache uses to recognize JSP Servlet requests that need to be handled by Tomcat. The communitation between Apache and Tomcat is coordinated by mod_jk

To get mod_jk, you can either search the Internet and download one that is pre-compiled for your version of Apache and your OS version, or you can compile one from source.

Copy the mod_jk.so module to /usr/local/apache2/modules

cp mod_jk-2.0.43.so /usr/local/apache2/modules/mod_jk.so



Changes in the /usr/local/apache2/conf/httpd.conf file

Listen 443
ServerName www.foo.org:443

# Put these SSL commands at the end of the file

SSLMutex sem
SSLRandomSeed startup builtin
SSLSessionCache none

NameVirtualHost 192.168.1.100

<VirtualHost www.foo.org:443>
SSLEngine On
SSLCertificateFile conf/ssl/server.crt
SSLCertificateKeyFile conf/ssl/server.key
</VirtualHost>

# The following commands are for integrating Tomcat with Apache

LoadModule jk_module modules/mod_jk.so
Include /usr/local/tomcat/conf/auto/mod_jk.conf




Generate your SSL certificates using OpenSSL

This creates a certificate signing request and a private key.
openssl req -new -out server.csr

This removes the passphrase from the private key.
openssl rsa -in privkey.pem -out server.key

This creates a self-signed certificate that you can use until you get a "real" one from a certificate authority (optional). This expires after 365 days.
openssl x509 -in server.csr -out server.crt -req -signkey server.key -days 365

If you want your users to install the certificate into their browsers, you need to create a DER-encoded version of the certificate and distribute it to themà
openssl x509 -in server.crt -out server.der.crt -outform DER

Create the /usr/local/apache2/conf/ssl directory and move server.key and server.crt into it.

mkdir /usr/local/apache2/conf/ssl
mv server.key server.crt /usr/local/apache2/conf/ssl

Search the httpd.conf and ssl.conf files for SSLCertificate and make sure the path and file names are correct, or else Apache won't start. You'll definitely have to change the paths in the ssl.conf file.

grep -i SSLCertificate /usr/local/apache2/conf/httpd.conf
grep -i SSLCertificate /usr/local/apache2/conf/ssl.conf




Create startup/shutdown scripts for Apache and Tomcat
You need to start Tomcat before starting Apache so that the /usr/local/tomcat/conf/auto/mod_jk.conf file is created before Apache starts.

[root@citrix root]# vi /usr/local/sbin/start.sh
echo "Starting Tomcat.................."
/usr/local/tomcat/bin/startup.sh
echo "Waiting 20 seconds to start Apache............."
sleep 20
echo "Starting Apache..............."
/usr/local/apache2/bin/apachectl start

[root@citrix root]# vi /usr/local/sbin/stop.sh
echo "Stopping Tomcat.................."
/usr/local/tomcat/bin/shutdown.sh
echo "Stopping Apache..............."
/usr/local/apache2/bin/apachectl stop

[root@citrix root]# chmod 700 /usr/local/sbin/st*.sh




Configure Tomcat

Edit the $CATALINE_HOME/conf/server.xml file. Look for a line similar to this...

Server port="8005" shutdown="SHUTDOWN" debug="0">

...and add this below it...

<Listener className="org.apache.ajp.tomcat4.config.ApacheConfig" modJk="/usr/local/apache2/modules/mod_jk.so" />

Look for the host container, it will look something like this...

<!-- Define the default virtual host -->
<Host name="localhost" debug="0" appBase="webapps"
unpackWARs="true" autoDeploy="true">

Add this line directly below it...

<Listener className="org.apache.ajp.tomcat4.config.ApacheConfig" append="true" forwardAll="false" modJk="/usr/local/apache2/modules/mod_jk.so" />

***Make sure the hostname in Apache and Tomcat are the same, or else you won't be able to connect. The hostname in the above example is localhost, so this will need to be changed to something like ôcitrix.foo.orgö, whatever the ServerName directive in Apache is set to. The clients must use whatever name is listed here in order to connect.

Create a directory called $CATALINE_HOME/conf/jk. Create a file inside called ôworkers.propertiesö, and add the following inside...

# BEGIN workers.properties
worker.list=ajp13
worker.ajp13.port=8009
worker.ajp13.host=localhost
worker.ajp13.type=ajp13
# END workers.properties


In order for Tomcat stuff to work through Apache SSL, copy and paste the directories that you want in Tomcat from the /usr/local/tomcat/conf/auto/mod_jk.conf file and put them in the default SSL VirtualHost in Apache's httpd.conf file.




Testing Apache and Tomcat

Start Apache using /usr/local/apache2/bin/apachectl start

Open a web browser and try to open https://www.foo.org. If you can open this secure page, then Apache and SSL are working.

Next, try and open https://www.foo.org/examples. Click the 'jsp' link and run one of the JSP samples. If this works, then mod_jk and Tomcat are working correctly with Apache.




Create a new index.html in Apache
Rather than pointing your browser to http://servername/Citrix/MetaFrame, you can create an index.html file inside your "DocumentRoot" directive in the httpd.conf file like thisà

<html>
<body onLoad='location="/Citrix/MetaFrameXP/index.html";'>
</body>
</html>

By default, Apache's DocumentRoot is set to /usr/local/apache2/htdocs, so you can simply place the index.html file inside that directory.

Now you can point your browser to http://www.foo.org to get to the MetaFrame login page.



Installing Citrix Web Interface 2.0 (formerly known as NFuse)

Copy the NfuseClassic.war file from the Citrix Components CDROM into the /usr/local/tomcat/webapps directory. Rename the file Citrix.war. When you start Tomcat, it will automatically ôunzipö this file and create a directory called ôCitrixö. Run the postInstall script in the new Citrix directory to install NFuse. This will create another directory called ôMetaFrameXPö. Edit the ./Citrix/WEB-INF/NFuse.conf file to configure NFuse settings.

sh /usr/local/tomcat/webapps/Citrix/postInstall.sh

To visit the NFuse website, restart Tomcat and Apache and visit http(s)://servername/Citrix/MetaFrameXP

If you want the above to work in an SSL-enabled Apache, then open the $CATALINA_HOME/conf/auto/mod_jk.conf file and copy everything in the Citrix section. Paste this into the default SSL VirtualHost in the Apache httpd.conf file.




altaddr and AlternateAddress

If the MetaFrame servers are located behind a firewall, and you are NOT using the SSL Relay on the MetaFrame servers, set "AlternateAddress=on" in the NFuse.conf file and run the "altaddr" command on each MetaFrame server in the farm. The external IP of each MetaFrame server needs to be NAT'ed on the firewall.

Use the altaddr command to query and set the alternate (external) IP address for a MetaFrame XP server. The alternate address is returned to ICA clients that request it and is used to access a MetaFrame XP server that is behind a firewall.

On each MetaFrame server, runà

altaddr /set 12.34.5.67

Run 'altaddr' with no options to view which alternate address is currently set on the MetaFrame server. You can run 'altaddr /?' to see a help screen for the command.

If you are using the SSL Relay on the MetaFrame servers, you don't need to run this command since SSL uses hostnames, not IP addresses in the NFuse.conf file. Since it uses hostnames, you must ensure that your internal and external DNS servers can both resolve the hostname to either the MetaFrame servers internal or external hostname.





SSL Relay service with NFuse
If your going to run the SSL Relay service on your MetaFrame XP servers, you'll need to change these fields in the NFuse.conf fileà

AddressResolutionType=dns-port
SessionField.NFuse_Farm1=citrix1.foo.org,Name:Farm1,Transport:SSL,SSLRelayPort:443,BypassDuration:60,LoadBalance:On
SslKeystore=./WEB-INF/cacerts/





SSL Certificates for the MetaFrame servers running the SSL Relay service

If using the SSL Relay service on the MetaFrame servers, you'll need to install an SSL certificate on each MetaFrame server. You can either use self-signed certificates or purchase a certificate from a well-known CA (Certificate Authority), such as Verisign, Baltimore, or Thawte. If you use a self-signed certificate, you'll have to distribute and install the root certificate on every machine that will connect to the MetaFrame servers. If you decide to purchase a certificate from a well-known CA, no configuration is needed on the client since the root CA should already be installed in their browsers.

To purchase a certificate, check out www.whichssl.org for information on the CA's out there. Verisign is the most well-known CA, but they are also by far the most expensive. You can get a very cheap 128-bit SSL certificate from www.freessl.com for about $35/year. FreeSSL claims that they have 92% Browser Recognition rate, so this is ideal for most non-commercial sites. Verisign and the other expensive CAs have a 99% browser recognition rate.




Generating a CSR using OpenSSL

If your going to purchase an SSL certificate from a commercial CA, you'll need to generate a CSR (Certificate Signing Request) to send to them. A CSR contains the information required by a certificate authority to create the certificate. The CSR contains an encrypted version of the private key's complimentary algorithm, common value, and information that identifies the server. This information includes, but is not limited to, country, state, organization, common name (domain name), and contact information.

To generate a CSR, use the openssl command from a Linux/Unix machine with OpenSSL installedà.

Step one - create the key and request:

openssl req -new > www.foo.com.csr

Step two - remove the passphrase from the key (optional):

openssl rsa -in privkey.pem -out www.foo.com.key

Step three - convert request into signed certificate (optional - only do this if your NOT going to puchase an SSL certificate from a commercial CA. This will create a self-signed certificate):

openssl x509 -in www.foo.com.csr -out www.foo.com.cert -req -signkey www.foo.com.key -days 365


Simply "cat" the www.foo.com.csr file to view the certificate signing request that you'll need to submit to your CAà.

/bin/cat www.foo.com.csr




Installing an SSL Certificate on a MetaFrame XP Server


After you receive your certificate from a CA, your ready to install it. Since I created the CSR and private key using OpenSSL on a Linux machine, this is how I got it working on my MetaFrame XP serversà.

Copy and paste the contents of the privkey.pem file to a new text file (call it cert.pem, or whatever you want as it is only a temporary file that you will later delete). Right below that, paste the contents from the www.foo.com.cert file that you received from your CA. When your done, you'll have a cert.pem file that will look something like this (I removed a few lines here)...

-----BEGIN RSA PRIVATE KEY-----
Proc-Type: 4,ENCRYPTED
DEK-Info: DES-EDE3-CBC,FEFAD98766EA158D

M6r8O+bS0ruVPwYN49FUzsWJrnATWyXmRQurZISE8ZJ99v3YI53D3sSKSQqo0sUo
c4DG0IzCCWcP62y6ucsCewjIbw8YqV788miZ3PZ38cVOD6Zt6XkCrGEDiYNTWRjE
WtfHnvvD1g+FSqCOpgaPbRfhVd7NNzKXEaUCe5CJ63wEh3FS3Z1NmNQDqDYbXHT+
MOahXOdHfMtLPyOBBduDSS1LUrYvksCPWZqkUF4AbNcmeJE1HVBCNA==
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
YTBxDBPMOCfNU1XuW9BBqujKMRIIH/BKKV9Fhhm2hJnF2U57aka6V7lGiv5nqFOl
cq5CZSLSR4avbnF8dH5UvTcM0xYkvyOi56LptYTnTFnmsx27i8aKNetiv+B1jYtJ
4Hr1LKuLE/RX4WxrgCOXX5ePwVS69btiv955OjgpY4IkEVcgKFbPwT8bxU3j1jpr
7RkhC1kB7+r5C4fk1tsR3W0tPHQ/WzuuzZw8zuvpMbvkkt9n/Oo8
-----END CERTIFICATE-----


Next, use the "pemtopfx.exe" utility that comes with MetaFrame XP. From the command prompt...

pemtopfx.exe X:\cert.pem

This will create a cert.pfx file at the root of X:\.

To install this certificateà.
Start - Run - mmc
Console - Add/Remove Snap-ins
Add - Certificates - Computer Account - Local Computer

Personal - All Tasks - Import - browse for the .pfx file


Citrix SSL Relay Configuration

Make sure the certificate shows up on the Relay Credentials Tab.
Under the Connection tab, edit the existing connection. Add port 1494 so that it says "80 1494"
Start the Citrix SSL Relay service.


Installing the root certificate on the NFuse server

You'll need to install the root certificate on the NFuse server so that the NFuse server trusts the certificates installed on the MetaFrame servers.

In the NFuse.conf file, look for a line that looks like thisà

SslKeystore=./WEB-INF/cacerts/

This is where you need to place your root certificates.

On a MetaFrame server, open Internet Explorer and select Tools - Internet Options - Content - Certificates. Look for your installed certificate under the Personal tab and select Export. Export the file as a "DER encoded binary X.509 (.CER)". This will save the file as a *.cer file. You'll need to rename this to *.der.

Copy the *.der file to the /usr/local/tomcat/webapps/Citrix/WEB-INF/cacerts directory (or wherever yours is located) and restart Tomcat and Apache.

As an alternative, you can probably download the root certificate from your Certificate Authorities website. For example, you can download the FreeSSL root certificate from here --> http://www.freessl.com/freessl/freessl-installcert.html. You will need to rename it from UTN.cer to UTN.der before placing it in your cacerts directory.

If you do not follow this step correctly, you will see an error message similar to thisà

"ERROR: The Citrix MetaFrame servers cannot process your request at this time. An SSL connection could not be established: You have not chosen to trust "Some CA", the issuer of the server's security certificate."




If anyone has any suggestions or comments, please feel free to email me.

Please rate this FAQ.