Automating SSL/TLS Certificate Renewals in Tomcat

In short: to automate SSL/TLS certificate renewal in Tomcat with ITVA, configure Tomcat to read PEM files and issue the certificate with a key generated on the server. Then add an SSH install that copies the key and certificate into place and restarts Tomcat. Last, turn on Auto Renew.

This guide sets up hands-off certificate renewal for Apache Tomcat on Linux, using PEM files instead of a Java keystore. When you finish, ITVA renews the certificate before it expires, installs the new certificate and key on the server, and restarts Tomcat to load them. The example uses Tomcat 11. Other versions differ only in paths and the service name.

For how installs work in general, see How certificate installs work.

Before you begin

• Add the Tomcat server to ITVA as a device with SSH credentials and a probe. See Add your first device.
• Make sure the SSH account can run sudo cp and sudo systemctl restart tomcat11 without a password prompt. The install script runs without a terminal, so it cannot answer a prompt.
• Create an enrollment for the site, with an enabled CA template. See Set up certificate templates.
• Configure the HTTPS connector in server.xml to read PEM files. This guide uses the paths below. Change them to match your server.

<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol" SSLEnabled="true">
  <SSLHostConfig>
    <Certificate certificateFile="/etc/tomcat11/ssl/itva_tomcat.crt"
                 certificateKeyFile="/etc/tomcat11/ssl/itva_tomcat.key" />
  </SSLHostConfig>
</Connector>

Step 1: Issue the certificate with a key generated on the server

Generate the key on the Tomcat server so that it never leaves the server. ITVA then creates a new key at the same path at each renewal.

1. Open the enrollment and select Issue.
2. Select Generate on Device. In Device, select the Tomcat server.
3. In Private Key Path, type .itva/itva_tomcat.key. A relative path starts in the home folder of the SSH account. ITVA creates the folder if it does not exist.
4. In Private Key Algorithm, select an RSA or ECDSA algorithm that the CA template allows.
5. Submit the request and wait for the certificate to issue.

Tomcat can serve an ML-DSA certificate from PEM files only when it uses OpenSSL 3.5 or later, through Tomcat Native or FFM. This needs Tomcat 11.0.12, 10.1.47, 9.0.110, or later. With the default Java (JSSE) setup, use RSA or ECDSA.

Step 2: Add an install with the Tomcat restart script

1. On the Installs card of the enrollment, select Install.
2. In Format, select OpenSSL - PEM. Keep Include private key off. The key is already on the server.
3. Turn on Include certificate chain. ITVA writes the server certificate first and the chain after it.
4. Make sure Auto Install is on.
5. Select SSH. In Device, select the Tomcat server.
6. In Path, type .itva/itva_tomcat.crt. The probe writes the certificate here.
7. In Script, paste the script below. Change the destination paths and the service name to match your server.

sudo cp .itva/itva_tomcat.key /etc/tomcat11/ssl/itva_tomcat.key
sudo cp {{PATH}} /etc/tomcat11/ssl/itva_tomcat.crt
sudo systemctl restart tomcat11

8. Select Save. ITVA installs the current certificate immediately.

The script copies the key and the new certificate to the paths in server.xml, then restarts Tomcat. ITVA replaces {{PATH}} with the value of Path before it runs the script.

Caution: a restart stops Tomcat for a short time, and open requests are dropped. Unlike Apache and NGINX, Tomcat has no graceful reload in this setup. If you run more than one Tomcat server behind a load balancer, give each server its own enrollment or install, so that they do not all restart at once.

Tomcat runs as its own service account, not as root, so it must be able to read the key file. cp keeps the owner and mode of a file that already exists. If the destination files do not exist yet, sudo cp creates them owned by root, and Tomcat cannot read the key. In that case, add these lines before the restart. Change tomcat to the group that your Tomcat service uses.

sudo chown root:tomcat /etc/tomcat11/ssl/itva_tomcat.key /etc/tomcat11/ssl/itva_tomcat.crt
sudo chmod 640 /etc/tomcat11/ssl/itva_tomcat.key

Step 3: Turn on auto renew

1. Open the enrollment.
2. Turn on the Auto Renew switch.

By default, ITVA renews the certificate 14 days before it expires. At each renewal, ITVA generates a new key at .itva/itva_tomcat.key, gets the new certificate from the issuer, writes it to .itva/itva_tomcat.crt, and runs the script. Tomcat keeps using its own copies in /etc/tomcat11/ssl until the script replaces them together.

Check that it worked

1. On the Installs card, make sure the latest job has the status Completed.
2. Make sure Tomcat started again.

sudo systemctl status tomcat11

3. From any computer that can reach Tomcat, check the certificate it serves. Replace <HOSTNAME> with the name of the server, and change the port if your connector does not use 8443.

echo | openssl s_client -connect <HOSTNAME>:8443 -servername <HOSTNAME> 2>/dev/null | openssl x509 -noout -subject -serial -enddate

4. Make sure the serial number and expiry date match the latest certificate of the enrollment.

Caution: if the last renewal failed, do not select Reinstall. The renewal may have replaced the key at .itva/itva_tomcat.key without issuing a certificate for it. Fix the cause and renew again first.

Troubleshooting