DEV Community: Jesús G. Calderín

Install SSL server and client certificates in Apache Web Server

Jesús G. Calderín — Tue, 30 Sep 2025 09:51:39 +0000

SSL (Secure Socket Layer) is the technology behind the https urls you can see when browsing secure sites (which is nearly all of them). It's a protocol that allows server and browser (or more generally, the "agent" or just the "client") to establish a "handshake" prior to start exchanging request and responses. Its two main purposes are to enable the client to reliably identify the server and allow both to communicate via an encrypted channel.

During this handshake, the server will present the client with its "certificate", which is a X501-formatted data structure. The way the client will verify that the server is who it claims to be is by checking that this certificate is signed by some organisation it trusts, a list of which it must have available on its side and also checking that the certificate is issued to the same domain we are accessing.

Additionally, the server can ask the client to provide him with a "client certificate" for identification purposes. The server can then use this information to grant or block the client from visiting certain areas of the site or executing certain functions.

We will see below how to

activate SSL in our Apache Web Server,
create a server certificate for our site,
instruct the server to ask the client to provide a certificate,
create and install a client certificate in our browser

Prerequisites

1) Verify Linux's builtin Apache Web Server is installed and running:

$ sudo systemctl status apache2
● apache2.service - The Apache HTTP Server
     Loaded: loaded (/lib/systemd/system/apache2.service; 
     enabled; vendor preset: enabled)
     Active: active (running) since Sun 2025-09-21 12:43:12 CEST;

2) Although not mandatory, I find convenient to map the ip address of the Linux box containing our Apache server to a DNS name of our choosing, for example I will use:
test-980.com

In Windows, you can do this mapping by editing the file

C:\Windows\System32\drivers\etc\hosts

and adding your <Apache server ip> + blank-space + <domain name>:

# Added by me
172.31.36.52 test-980.com

Now when I call that domain from my Windows host, I will get the home page of my Apache Web Server:

#Before changing C:\Windows\System32\drivers\etc\hosts file:
PS> curl.exe -v http://test-980.com/
* Could not resolve host: test-980.com
* shutting down connection #0
curl: (6) Could not resolve host: test-980.com

#After changing C:\Windows\System32\drivers\etc\hosts file:
PS> curl.exe -v http://test-980.com/
* Host test-980.com:80 was resolved.
* IPv6: (none)
* IPv4: 172.31.36.52
*   Trying 172.31.36.52:80...
* Connected to test-980.com (172.31.36.52) port 80
* using HTTP/1.x
> GET / HTTP/1.1
> Host: test-980.com
> User-Agent: curl/8.14.1
> Accept: */*
>
< HTTP/1.1 200 OK
... full content of the home page follows here ...

3) Create a virtual host for my test-980.com site, so we don't mess around with default virtual host in apache:

$ sudo mkdir -p /var/sites/test-980.com/conf
$ sudo mkdir -p /var/sites/test-980.com/www/html
$ sudo vi /var/sites/test-980.com/www/html/index.html
#add the content shown in the cat command below

$ cat /var/sites/test-980.com/www/html/index.html
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>test-980.com: It works</title>
  </head>
  <body>
        Welcome to test-980.com
  </body>
</html>
$ sudo cp /etc/apache2/sites-available/000-default.conf \
/var/sites/test-980.com/conf/localhost.conf

$ sudo vi /var/sites/test-980.com/conf/localhost.conf
#add the content shown in the cat command below

$ cat /var/sites/test-980.com/conf/localhost.conf
<VirtualHost *:80>
        ServerName test-980.com

        ServerAdmin webmaster@test-980.com
        DocumentRoot /var/sites/test-980.com/www/html

        <Directory /var/sites/test-980.com/www/>
          Options Indexes FollowSymLinks
          AllowOverride None
          Require all granted
        </Directory>

        ErrorLog ${APACHE_LOG_DIR}/error.log
        CustomLog ${APACHE_LOG_DIR}/access.log combined

</VirtualHost>

#Make our site available
$ sudo ln -s /var/sites/test-980.com/conf/localhost.conf \
/etc/apache2/sites-available/local-test-980.com.conf

#Maker our site enabled:
$ sudo a2ensite local-test-980.com
Enabling site local-test-980.com.
To activate the new configuration, you need to run:
  systemctl reload apache2

$ sudo  systemctl reload apache2

Now, curl will return our new page:

PS> curl.exe http://test-980.com/
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>test-980.com: It works</title>
  </head>
  <body>
        Welcome to test-980.com
  </body>
</html>

However, we cannnot access our site via https for the moment:

PS> curl.exe https://test-980.com/
curl: (35) schannel: next InitializeSecurityContext failed:
SEC_E_INVALID_TOKEN (0x80090308) - 
El token proporcionado a la función no es válido

We'll see next how to secure our site via SSL.

Enable SSL on Apache

Run

$ sudo a2ensite default-ssl.conf
Enabling site default-ssl.
To activate the new configuration, you need to run:
  systemctl reload apache2
$ sudo systemctl reload apache2

If we look at the content of /etc/apache2/sites-enabled/default-ssl.conf, we will see that we have done the following:

listen on port 443:

<VirtualHost _default_:443>

serve the pages under /var/www/html:

DocumentRoot /var/www/html

use SSL protocol on this virtual host:

SSLEngine on

send the client the following server certificate:

SSLCertificateFile /etc/ssl/certs/ssl-cert-snakeoil.pem

So, if we now test https, we will get a warning that the certificate is not trusted:

PS> curl.exe https://test-980.com/
curl: (60) schannel: SEC_E_UNTRUSTED_ROOT (0x80090325) - 
La cadena de certificación fue emitida por una entidad en la que no se confía.
More details here: https://curl.se/docs/sslcerts.html

curl failed to verify the legitimacy of the server and therefore could not
establish a secure connection to it. To learn more about this situation and
how to fix it, please visit the webpage mentioned above.

However, we can force curl to trust the certificate via the -k option:

PS> curl.exe -k https://test-980.com/
   ... full content of page /var/www/html/index.html will follow ...

But we don't want the default page in /var/www/html/index.html to be served, but the page in our test-980.com site, so we have to create a virtual host for our site that speaks https.
We do it as follows:

copy default ssl conf:

$ sudo cp /etc/apache2/sites-available/default-ssl.conf \
/var/sites/test-980.com/conf/localhost-ssl.conf

adapt it to our site by adding our domain name in ServerName and our html folder in DocumentRoot:

$ cat /var/sites/test-980.com/conf/localhost-ssl.conf
...
ServerName test-980.com
...
DocumentRoot /var/sites/test-980.com/www/html

We set our site available, enable it and reload Apache:

$ sudo ln -s /var/sites/test-980.com/conf/localhost-ssl.conf \
/etc/apache2/sites-available/local-test-980.com-ssl.conf
$ sudo a2ensite local-test-980.com-ssl.conf
$ sudo systemctl reload apache2

If we try again we will get:

PS> curl.exe -k https://test-980.com/
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html><head>
<title>403 Forbidden</title>
</head><body>
<h1>Forbidden</h1>
<p>You don't have permission to access this resource.</p>
<hr>
<address>Apache/2.4.52 (Ubuntu) Server at test-980.com Port 443</address>
</body></html>

That's because we have to grant access to our home folder in our new ssl conf, in the same way we did in /var/sites/test-980.com/conf/localhost.conf.

So, we have to modify localhost-ssl.conf to add the following Directory element:

$ more /var/sites/test-980.com/conf/localhost-ssl.conf
    ...
    DocumentRoot /var/sites/test-980.com/www/html
    <Directory /var/sites/test-980.com/www/>
      Options Indexes FollowSymLinks
      AllowOverride None
      Require all granted
    </Directory>
    ...

and reload:

$ sudo systemctl reload apache2

Now, we can get our home page via https:

PS> curl.exe -k https://test-980.com/
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>test-980.com: It works</title>
  </head>
  <body>
        Welcome to test-980.com
  </body>
</html>

Remember we are able to retrieve the page only because we have instructed curl to ignore (via option k) the fact that the certificate presented (or more precisely, the signer of the certificate) is not trusted:

PS> curl.exe -k https://test-980.com/
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>test-980.com: It works</title>
  </head>
  <body>
        Welcome to test-980.com
  </body>
</html>

#Removing the -k
PS> curl.exe https://test-980.com/
curl: (60) schannel: SEC_E_UNTRUSTED_ROOT (0x80090325) - La cadena de certificación fue emitida por una entidad en la que no se confía.
More details here: https://curl.se/docs/sslcerts.html

curl failed to verify the legitimacy of the server and therefore could not
establish a secure connection to it. To learn more about this situation and
how to fix it, please visit the webpage mentioned above.

We can tell curl to trust the certificate with the option cacert:

PS> curl.exe https://test-980.com --cacert ^
\\wsl.localhost\Ubuntu-22.04\etc\ssl\certs\ssl-cert-snakeoil.pem

curl: (60) schannel: CertGetNameString() failed to match connection hostname (test-980.com) against server certificate names
More details here: https://curl.se/docs/sslcerts.html

curl failed to verify the legitimacy of the server and therefore could not
establish a secure connection to it. To learn more about this situation and
how to fix it, please visit the webpage mentioned above.

We're not there yet. The reason is that the certificate is issued for a domaine named "DESKTOP-IUMEIDO", which is my computer's name:

$ openssl x509 -in /etc/ssl/certs/ssl-cert-snakeoil.pem -noout -text|\
grep "Subject:"
        Subject: CN = DESKTOP-IUMEID0.

, whereas our request is sent to a different domain (test-980.com). The client is being presented a certificate signed by someone he now trusts, but that is issued to a domain different that the one we are trying to connect to. This is deemed dangerous, hence the message and the refusal to connect.

In next section, we'll see how to create a server certificate for our domain test-980

Create SSL server certificate

First, let's generate a key of length 2048:

$ openssl genrsa -out test-980.com.key 2048

Now we need to create a certificate sign request or csr. We will be asked to provide information about the owner of the certificate such as it's company name, it's country, etc... Only Common Name is mandatory:

$ openssl req -new \
-key test-980.com.key \
-out test-980.com.csr
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:.
State or Province Name (full name) [Some-State]:.
Locality Name (eg, city) []:.
Organization Name (eg, company) [Internet Widgits Pty Ltd]:.
Organizational Unit Name (eg, section) []:.
Common Name (e.g. server FQDN or YOUR name) []:test-980.com
Email Address []:.

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:.
An optional company name []:.

Finally, we sign the request with the key generated above. This will generate our certificate and place it in the file specified in out:

$ openssl x509 -req -days 365 \
-in test-980.com.csr \
-signkey test-980.com.key \
-out test-980.com.crt
Certificate request self-signature ok
subject=CN = test-980.com

If we list our current folder, we will see the 3 files that we have just generated:

$ ls test-980*
test-980.com.crt  test-980.com.csr  test-980.com.key

Our certificate is the crt file.
We will now copy the crt and the key files inside our test-980.com's site configuration folder and reference them in our ssl conf file:

$ sudo cp test-980.com.crt /var/sites/test-980.com/conf
$ sudo cp test-980.com.key /var/sites/test-980.com/conf

#Modify localhost-ssl.conf to point to our new files:
$ cat /var/sites/test-980.com/conf/localhost-ssl.conf|grep SSLCertificate
SSLCertificateFile      /var/sites/test-980.com/conf/test-980.com.crt
SSLCertificateKeyFile   /var/sites/test-980.com/conf/test-980.com.key

#restart:
$ sudo systemctl stop apache2.service
$ sudo systemctl start apache2.service

Let's now copy the server certificate in our windows home folder (notice I've been using all this time my curl tool in Windows) for the sake of legibility:

PS> cp \\wsl.localhost\Ubuntu-22.04\var\sites\test-980.com\conf\test-980.com.crt .

If we try again, it should work:

PS> curl.exe https://test-980.com --cacert test-980.com.crt
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>test-980.com: It works</title>
  </head>
  <body>
        Welcome to test-980.com
  </body>
</html>

Create SSL client certificate

We can instruct our server to require a certificate to the client by editing localhost-ssl.conf as follows:

uncomment the following line:

SSLVerifyClient require

indicate where our signer certificate is with:

SSLCACertificateFile /var/sites/test-980.com/conf/test-980.com.crt

After restarting the server, we can't access our page anymore:

PS> curl.exe https://test-980.com --cacert test-980.com.crt
curl: (56) schannel: failed to read data from server: SEC_E_ILLEGAL_MESSAGE (0x80090326) - This error usually occurs when a fatal SSL/TLS alert is received (e.g. handshake failed). More detail may be available in the Windows System event log.

The message is quite cryptic but it is due to our curl client not providing a certificate.

Let's then create a client certificate for James Bond and sign it with our test-980.com server certificate:

#Step 1: generate key
$ openssl genpkey -algorithm RSA -out james.bond.key

#Step 2: generate request
$ openssl req -new -key james.bond.key -out james.bond.csr
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:.
State or Province Name (full name) [Some-State]:.
Locality Name (eg, city) []:.
Organization Name (eg, company) [Internet Widgits Pty Ltd]:.
Organizational Unit Name (eg, section) []:.
Common Name (e.g. server FQDN or YOUR name) []:BOND.James
Email Address []:.

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:.
An optional company name []:.

#Step 3: generate the certificate and sign it with our test-980.com server 
#certificate (notice that all files in the command are assumed to be in 
#current folder):
$ openssl x509 -req -in james.bond.csr -CA test-980.com.crt \
-CAkey test-980.com.key \
-CAcreateserial \
-out james.bond.crt \
-days 365 \
-sha256
Certificate request self-signature ok
subject=CN = BOND.James

#Step 4: optional
#If we want to import it in our browser or test it via curl in Windows, 
#we might need to convert it to .pfx format:
$ openssl pkcs12 -export -out james.bond.pfx \
-inkey james.bond.key \
-in james.bond.crt
Enter Export Password: mypwd
Verifying - Enter Export Password: mypwd

Now let's copy the .pfx in our Windows machine and try again by providing our client certificate and the password wiht the --cert option:

PS> curl.exe https://test-980.com/ ^
--cacert ./test-980.com.crt ^
--cert james.bond.pfx:mypwd
curl: (35) schannel: next InitializeSecurityContext failed: SEC_E_INTERNAL_ERROR (0x80090304) - No es posible ponerse en contacto con la autoridad de seguridad local

It's not working but it should :( . You might want to check this article for the reasons behind and try your luck, but I rather have my balls torched than messing around with my Windows registry. I will use my Chrome browser instead.

To import the client certificate in Chrome, go to chrome://certificate-manager/clientcerts and from there I'm sure you'll manage.

Now, when accessing our site via https, we will be asked to select a client certificate:

If you select it and click OK, you'll be granted access to the site:

Set up a reverse proxy in Linux

Jesús G. Calderín — Tue, 23 Sep 2025 21:23:29 +0000

A "reverse proxy" is just a web server that is placed in-between one or more application servers (the "back-end") and their clients, so that the back-end is only accessible via requests sent to the proxy. The latter will in turn decide whether to forward the request to the backend, to which server it should send it and many other considerations. The proxy is not only isolating the servers from the clients but providing added value like caching static content, load-balancing, etc...

It's called "reverse" in contrast with "forward proxies", that are placed in front of clients to provide them as well with different functionalities.

The distinction is blurry but overall, we can say that a reverse-proxy is intended to serve servers and a forward-proxy to serve clients.

This little guide refers to a reverse-proxy.

Prerequisites

1) Install and configure a Tomcat cluster, and set the following environment variables in ~/.bashrc:

$TOMCAT1_HOME=<your tomcat1 home folder>
$TOMCAT2_HOME=<your tomcat2 home folder>

2) Verify Linux's builtin apache is installed:

$ sudo systemctl status apache2
● apache2.service - The Apache HTTP Server
     Loaded: loaded (/lib/systemd/system/apache2.service; 
     enabled; vendor preset: enabled)
     Active: active (running) since Sun 2025-09-21 12:43:12 CEST;

Create a new website

Specify in .bashrc the home folder of our new website:

$ tail -n 3 ~/.bashrc
export TOMCAT1_HOME="/apps/myapp/clus1/tomcat1"
export TOMCAT2_HOME="/apps/myapp/clus1/tomcat2"
export MYSITE_HOME="/var/sites/mysite"
$ source ~/.bashrc

, and also set it in /etc/apache2/envvars:

$ tail -n 1 /etc/apache2/envvars
export MYSITE_HOME=/var/sites/mysite

Create our new website's conf and www/html folders:

$ sudo mkdir -p $MYSITE_HOME/conf
$ sudo mkdir -p $MYSITE_HOME/www/html

Create an index.html inside $MYSITE_HOME/www/html:

$ cat $MYSITE_HOME/www/html/index.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>MySite Default Page: It works</title>
  </head>
  <body>
        Welcome to MySite
  </body>
</html>

Create a virtual host for our site

We copy the default conf from built-in apache:

$ sudo cp /etc/apache2/sites-available/000-default.conf \
$MYSITE_HOME/conf/localhost.conf

, and add the following lines:

$ cat $MYSITE_HOME/conf/localhost.conf
<VirtualHost *:80>
        ServerName localhost
        ServerAdmin webmaster@localhost

        DocumentRoot ${MYSITE_HOME}/www/html
        <Directory ${MYSITE_HOME}/www/>
          Options Indexes FollowSymLinks
          AllowOverride None
          Require all granted
        </Directory>

        ErrorLog ${APACHE_LOG_DIR}/error.log
        CustomLog ${APACHE_LOG_DIR}/access.log combined

</VirtualHost>

Enable our site

We first make our site available:

$ sudo ln -s $MYSITE_HOME/conf/localhost.conf \
/etc/apache2/sites-available/local-localhost.conf

, and then we enable it:

$ sudo a2ensite local-localhost
Enabling site local-localhost.
To activate the new configuration, you need to run:
  systemctl reload apache2

Finally, stop and restart apache:

$ sudo systemctl stop apache2
$ sudo systemctl start apache2

, and test that our new site works:

$ curl http://localhost
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>MySite Default Page: It works</title>
  </head>
  <body>
        Welcome to MySite
  </body>
</html>

Set up mod_jk

There are two modules that I know for our apache web server to communicate with our backend Tomcat servers: mod_proxy and mod_jk.
I'm going to use the mod_jk plugin, which will communicate via the AJP protocol.

Enable AJP

First thing is to enable the AJP connectors in our Tomcats, which are disabled by default.
For that, we need to go to server.xml and uncomment the AJP connector element:

$ cat $TOMCAT1_HOME/conf/server.xml
    <!-- Define an AJP 1.3 Connector on port 8009 -->

    <Connector protocol="AJP/1.3"
               address="localhost"
               port="8009"
               redirectPort="8443"
               maxParameterCount="1000"
               secretRequired="false"
               />

N.B:

I had to add secretRequired="false"
The defaul value in address is "::1", but that doesn't work for me, so I set it to "localhost", although "127.0.0.1" will also do.

Do the same for tomcat2 but don't forget to use a different port, cause both tomcats are on the same machine:

<!-- Define an AJP 1.3 Connector on port 9009 -->

    <Connector protocol="AJP/1.3"
               address="127.0.0.1"
               port="9009"
               redirectPort="8443"
               maxParameterCount="1000"
               secretRequired="false"
               />

After restarting the tomcats, we should see both AJP ports in use:

$ netstat -nlp|grep -E "8009|9009"
tcp6       0      0 127.0.0.1:8009  :::*  LISTEN      60789/java
tcp6       0      0 127.0.0.1:9009  :::*  LISTEN      120768/java

So our situation is that our examples application is available via our tomcats:

$ curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8080/examples/
200
$ curl -s -o /dev/null -w "%{http_code}\n" http://localhost:9080/examples/
200

but not yet via our apache:

$ curl -s -o /dev/null -w "%{http_code}\n" http://localhost/examples/
404

That's what we will try to achieve with mod_jk: that requests for examples app are forwarded to the tomcats.

Configure and enable mod_jk

First we copy the default mod_jk conf:

$ sudo cp /etc/apache2/mods-available/jk.conf $MYSITE_HOME/conf/jk.conf
$ sudo cp /etc/apache2/mods-available/jk.load $MYSITE_HOME/conf/jk.load

Now we create 2 files inside $MYSITE_HOME/conf:

workers.properties: will contain pointers to our tomcat AJP connectors and will define a load-balancer type worker.
uriworkermap.properties: will contain the mapping from /examples uri to our load-balancer.

$ cat $MYSITE_HOME/conf/workers.properties
worker.list=worker1, worker2, lb

# Set properties for worker1 (our tomcat1 server)
worker.worker1.type=ajp13
worker.worker1.host=localhost
worker.worker1.port=8009

# Set properties for worker2 (our tomcat2 server)
worker.worker2.type=ajp13
worker.worker2.host=localhost
worker.worker2.port=9009

worker.lb.type=lb
worker.lb.balance_workers=worker1, worker2

$ cat $MYSITE_HOME/conf/uriworkermap.properties
# Send everything for context /examples to load-balancer worker
/examples/*=lb

Now we point to these 2 files in our jk.conf file:

$ cat $MYSITE_HOME/conf/jk.conf
...
JkWorkersFile ${MYSITE_HOME}/conf/workers.properties
...
JkMountFile ${MYSITE_HOME}/conf/uriworkermap.properties

The configuration is finished.

Next, we make our module available:

$ sudo ln -s $MYSITE_HOME/conf/jk.conf \
/etc/apache2/mods-available/local-jk.conf
$ sudo ln -s $MYSITE_HOME/conf/jk.load \
/etc/apache2/mods-available/local-jk.load

We now have to disable the default mod_jk cause only one JkWorkersFile is permitted:

$ sudo a2dismod jk

Next, enable our custom jk and reload:

$ sudo a2enmod local-jk
$ sudo systemctl reload apache2

Now, the forwarding should work:

$ curl http://localhost/examples/
<!DOCTYPE HTML><html lang="en"><head>
<meta charset="UTF-8">
<title>Apache Tomcat Examples</title>
</head>
<body>
<p>
<h3>Apache Tomcat Examples</H3>
<p></p>
<ul>
<li><a href="servlets">Servlets examples</a></li>
<li><a href="jsp">JSP Examples</a></li>
<li><a href="websocket/index.xhtml">WebSocket Examples</a></li>
</ul>
</body></html>

Next, we will test that load-balancing, sticky sessions and fail-over are all working as expected:

Testing load-balancing

To test that sessions are balanced, we can use servlet SessionExample in the examples app.

I have modified the following file

$TOMCAT_HOME/webapps/examples/WEB-INF/classes/LocalStrings.properties

in both tomcats to include the literal "1" and "2" respectively at the end of the following property:

sessions.title=Sessions Example Tomcat

, so I can easily identify to which tomcat requests are being forwarded.

Running different requests should bounce alternatively (or nearly) between tomcat1 and tomcat2:

$ curl http://localhost/examples/servlets/servlet/SessionExample|\
grep "<title>Sessions Example"
<title>Sessions Example Tomcat 1</title>
$ curl http://localhost/examples/servlets/servlet/SessionExample|\
grep "<title>Sessions Example"
<title>Sessions Example Tomcat 2</title>
$ curl http://localhost/examples/servlets/servlet/SessionExample|\
grep "<title>Sessions Example"
<title>Sessions Example Tomcat 1</title>
$ curl http://localhost/examples/servlets/servlet/SessionExample|\
grep "<title>Sessions Example"
<title>Sessions Example Tomcat 2</title>

Testing sticky sessions

For sticky sessions to work, we have to set the jvmRoute attribute in the engine element in tomcat's server.xml to the name of the respective node from workers.properties file (worker1 and worker2 in our case):

<Engine jvmRoute="worker1" name="Catalina" ...>
<Engine jvmRoute="worker2" name="Catalina" ...>

$ grep -r --include="server.xml" "jvmRoute=" /apps/myapp/clus1
/tomcat2/conf/server.xml:    <Engine name="Catalina" defaultHost="localhost" jvmRoute="worker2">
/tomcat1/conf/server.xml:    <Engine name="Catalina" defaultHost="localhost" jvmRoute="worker1">

To test that requests belonging to the same session "stick" to the same server, we can send the cookie JSESSIONID filled with the ID returned by the first request and check both that ID returned is the same and receiving tomcat too:

$ curl http://localhost/examples/servlets/servlet/SessionExample|\
grep "Session ID" -B 1
<h3>Sessions Example Tomcat 1</h3>
Session ID: 160ECEE2FE688B6649DC109F03EA1C7B.worker1

$ curl --cookie "JSESSIONID=160ECEE2FE688B6649DC109F03EA1C7B.worker1"\
http://localhost/examples/servlets/servlet/SessionExample|\
grep "Session ID" -B 1
<h3>Sessions Example Tomcat 1</h3>
Session ID: 160ECEE2FE688B6649DC109F03EA1C7B.worker1

Testing fail-over

We will proceed with the following sequence

send a request
note which tomcat served it and which session ID is returned
stop that tomcat
send another request for the same session via JESSIONID cookie
verify that the other tomcat has served it and the JESSSIONID returned is the same

$ curl http://localhost/examples/servlets/servlet/SessionExample|\
grep "<h3>Sessions Example" -A 1
<h3>Sessions Example Tomcat 1</h3>
Session ID: 2D3B488194BBC78479370196455D4384.worker1

$ /apps/myapp/clus1/tomcat1/shutdown.sh
Using CATALINA_BASE:   /apps/myapp/clus1/tomcat1
Using CATALINA_HOME:   /opt/apache-tomcat-9.0.109
Using CATALINA_TMPDIR: /apps/myapp/clus1/tomcat1/temp
Using JRE_HOME:        /opt/jdk1.8.0_451
Using CLASSPATH:       /opt/apache-tomcat-9.0.109/bin/bootstrap.jar:
/opt/apache-tomcat-9.0.109/bin/tomcat-juli.jar
Using CATALINA_OPTS:

$ curl --cookie "JSESSIONID=2D3B488194BBC78479370196455D4384.worker1"\
http://localhost/examples/servlets/servlet/SessionExample|\
grep "<h3>Sessions Example" -A 1
<h3>Sessions Example Tomcat 2</h3>
Session ID: 2D3B488194BBC78479370196455D4384.worker2

Setup Tomcat cluster in Linux

Jesús G. Calderín — Sat, 20 Sep 2025 17:45:29 +0000

Prerequisites

Install Java

And set JAVA_HOME variable accordingly in ~/.bashrc:

export JAVA_HOME=/opt/jdk1.8.0_451

Install Tomcat

And set CATALINA_HOME accordingly in ~/.bashrc:

export CATALINA_HOME=/opt/apache-tomcat-9.0.109

Create two instances of our Tomcat

(Kudos to Goran Vasic)

They will be the two nodes of our cluster.

First, we create one empty directory for our first tomcat:

$ mkdir -p /apps/myapp/clus1/tomcat1/

Then, we copy inside the following folders from CATALINA_HOME:

/conf
/webapps

$ cp -R $CATALINA_HOME/conf    /apps/myapp/clus1/tomcat1/
$ cp -R $CATALINA_HOME/webapps /apps/myapp/clus1/tomcat1/

We will also need to create an empty logs folder.

$ mkdir -p /apps/myapp/clus1/tomcat1/logs

Finally, we create start and stop scripts that set our CATALINA_BASE accordingly:

$ cat /apps/myapp/clus1/tomcat1/startup.sh
export CATALINA_BASE="/apps/myapp/clus1/tomcat1"
cd $CATALINA_HOME/bin
TITLE=tomcat1
./startup.sh $TITLE

$ cat /apps/myapp/clus1/tomcat1/shutdown.sh
export CATALINA_BASE="/apps/myapp/clus1/tomcat1"
cd $CATALINA_HOME/bin
./shutdown.sh

We now turn the files executable:

$ chmod u+x /apps/myapp/clus1/tomcat1/startup.sh
$ chmod u+x /apps/myapp/clus1/tomcat1/shutdown.sh

And test them:

$ /apps/myapp/clus1/tomcat1/startup.sh
Using CATALINA_BASE:   /apps/myapp/clus1/tomcat1
Using CATALINA_HOME:   /opt/apache-tomcat-9.0.109
Using CATALINA_TMPDIR: /apps/myapp/clus1/tomcat1/temp
Using JRE_HOME:        /opt/jdk1.8.0_451
Using CLASSPATH:       /opt/apache-tomcat-9.0.109/bin/bootstrap.jar:/opt/apache-tomcat-9.0.109/bin/tomcat-juli.jar
Using CATALINA_OPTS:
Tomcat started.

$ /apps/myapp/clus1/tomcat1/shutdown.sh
Using CATALINA_BASE:   /apps/myapp/clus1/tomcat1
Using CATALINA_HOME:   /opt/apache-tomcat-9.0.109
Using CATALINA_TMPDIR: /apps/myapp/clus1/tomcat1/temp
Using JRE_HOME:        /opt/jdk1.8.0_451
Using CLASSPATH:       /opt/apache-tomcat-9.0.109/bin/bootstrap.jar:/opt/apache-tomcat-9.0.109/bin/tomcat-juli.jar
Using CATALINA_OPTS:

We now need to create the same start/shutdown scripts for tomcat2, but bear in mind that since we are running our tomcats on the same machine, we need to use different listening and shutdown ports in each of them, otherwise the start and stop will fail. In my case, I'm going to replace default 8080 by 9080 in tomcat2's $CATALINA_BASE/conf/server.xml listening port:

<Connector port="9080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" maxParameterCount="1000" />

, and replace 8005 by 9005 in shutdown's port:

<Server port="9005" shutdown="SHUTDOWN"> <Listener className="org.apache.catalina.startup.VersionLoggerListener" />...

After starting both tomcats, we can see the ports they are using:

$ sudo netstat -nlp|grep -E '8080|9080'
tcp6       0      0 :::8080  :::*   LISTEN      20941/java
tcp6       0      0 :::9080  :::*   LISTEN      21014/java

$ lsof -i -P |grep 20941
java    20941 TCP *:8080 (LISTEN)
java    20941 TCP localhost:8005 (LISTEN)

$ lsof -i -P |grep 21014
java    21014  TCP *:9080 (LISTEN)
java    21014  TCP localhost:9005 (LISTEN)

Activate the cluster

We just need to uncomment the Cluster element under Engine in both tomcat's $CATALINA_BASE/conf/server.xml file:

<Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster"/>

, and restart.
This will make them multicast their membership to default 228.0.0.4 and port 45564, and will listen on the first port available between 4000-4100:

$ sudo netstat -nlp|grep 45564
udp6       0      0 :::45564    :::*  13411/java
udp6       0      0 :::45564    :::*  13273/java
$ lsof -i -P |grep 13411
java    13411 TCP *:9080 (LISTEN)
java    13411 TCP DESKTOP-IUMEID0.:4001 (LISTEN)
java    13411 UDP *:45564
java    13411 TCP localhost:42728->DESKTOP-IUMEID0.:4000 (ESTABLISHED)
java    13411 TCP DESKTOP-IUMEID0.:4001->localhost:36104 (ESTABLISHED)
java    13411 TCP localhost:9005 (LISTEN)
$ lsof -i -P |grep 13273
java    13273  TCP *:8080 (LISTEN)
java    13273  TCP DESKTOP-IUMEID0.:4000 (LISTEN)
java    13273  UDP *:45564
java    13273  TCP localhost:8005 (LISTEN)
java    13273  TCP DESKTOP-IUMEID0.:4000->localhost:42728 (ESTABLISHED)
java    13273  TCP localhost:36104->DESKTOP-IUMEID0.:4001 (ESTABLISHED)

In the output above, we can see that both tomcats are communicating with each other via the ports 4000 and 4001 respectively:

java    13411 TCP localhost:42728->DESKTOP-IUMEID0.:4000 (ESTABLISHED)
java    13411 TCP DESKTOP-IUMEID0.:4001->localhost:36104 (ESTABLISHED)
java    13273  TCP DESKTOP-IUMEID0.:4000->localhost:42728 (ESTABLISHED)
java    13273  TCP localhost:36104->DESKTOP-IUMEID0.:4001 (ESTABLISHED)

N.B: DESKTOP-IUMEID0 is just the name of my computer.

So that's it. Both tomcats now belong to the same cluster.

Enable session replication

The cluster is not very useful unless its nodes can replicate sessions between them. This would allow a session that was established in one node to be recoverable on the other node when the former dies out.
To test session replication, I will use the examples webapp that comes with out-of-the-box tomcat.

The session replication is enabled by simply adding

<distributable/>

under element web-app of $CATALINA_BASE/webapps/examples/WEB-INF/web.xml in both tomcats:

<web-app xmlns="http://xmln..."
  xmlns:xsi="http://www.w3...."
  xsi:schemaLocation="http:..."

  version="4.0"
  metadata-complete="true">

    <distributable/>
    ......

Test session replication

After restarting we can use curl to establish a session in tomcat1 by sending a request to servlet SessionExample:

$ curl http://localhost:8080/examples/servlets/servlet/SessionExample

<!DOCTYPE html>
<html>
....
<h3>Sessions Example</h3>
Session ID: 104F520BB401ED856048700D302D255A
...
The following data is in your session:<br>
....
</html>

We can now use the cookie JESSIONID to verify that the session also exists in tomcat2:

$ curl --cookie "JSESSIONID=104F520BB401ED856048700D302D255A" \
http://localhost:9080/examples/servlets/servlet/SessionExample

<!DOCTYPE html>
<html>
....
<h3>Sessions Example</h3>
Session ID: 104F520BB401ED856048700D302D255A
...
The following data is in your session:<br>
....
</html>

We will now put some data into the session via tomcat2 and verify if it is replicated in tomcat1:

#update the session via TOMCAT 2 (note that port=9080)
$ curl --data "dataname=james&datavalue=bond" \
--cookie "JSESSIONID=104F520BB401ED856048700D302D255A" \
http://localhost:9080/examples/servlets/servlet/SessionExample

<!DOCTYPE html>
<html>
....
<h3>Sessions Example</h3>
Session ID: 104F520BB401ED856048700D302D255A
...
The following data is in your session:<br>
james = bond
...
</html>

#recover the updated session via TOMCAT 1 (note that port=8080)
$ curl --cookie "JSESSIONID=104F520BB401ED856048700D302D255A" \ 
http://localhost:8080/examples/servlets/servlet/SessionExample

<!DOCTYPE html>
<html>
....
<h3>Sessions Example</h3>
Session ID: 104F520BB401ED856048700D302D255A
...
The following data is in your session:<br>
james = bond
...
</html>

So now we have a cluster of 2 tomcats that can replicate sessions between them. Not very useful, though, if we have to manually change the URL's and the JESSIONID cookie whenever one tomcat dies out or is responding slowly.

I'll soon cover how to front these tomcats with a web server that will provide us with new important functionalities:

request forwarding: web server will act as a reverse-proxy
load balancing: it will distribute the requests between the tomcats according, for example, to how busy they are
sticky sessions: it will always forward the requests pertaining to the same server session to the node that initiated it
fail-over: it will detect when one tomcat is down and refrain from sending it any requests until it is up again