Skip to main content

Apache Tomcat

Deploys certificates to Apache Tomcat servers via SSH, using a CLM agent as an intermediary.

Compatibility
The CLM Unix store delivers certificates in **PEM** format (`.crt` and `.key` files). Support depends on how Tomcat is configured — see the compatibility table below before proceeding.

Compatibility by version and configuration​

Version / ConfigurationFormatCompatible with CLM?
Tomcat ≤ 8.5 with JKS (Java KeyStore)JKS / PKCS12❌ Not supported
Tomcat 8.5+ with APR/OpenSSLPEM✅ Supported
Tomcat 9+ with NIO2 and PEMPEM✅ Supported
Tomcat 10+ (PEM by default)PEM✅ Supported
If your Tomcat uses JKS (Java KeyStore), deployment via the Unix store isn't compatible. JKS requires converting from PEM to PKCS12/JKS format before installation, which the Unix Provider doesn't support. Support for Java Keystores is planned for a future CLM release.

How to identify your Tomcat configuration​

Check Tomcat's server.xml file:

grep -A5 "SSLCertificateFile\|keystoreFile\|certificateFile" /etc/tomcat*/conf/server.xml
# or
grep -A5 "SSLCertificateFile\|keystoreFile\|certificateFile" /opt/tomcat/conf/server.xml

JKS configuration — ❌ Not supported​

<Connector port="443"
    keystoreFile="/etc/tomcat/keystore.jks"
    keystorePass="password" />

APR/OpenSSL configuration — ✅ Supported​

<Connector port="443" protocol="org.apache.coyote.http11.Http11AprProtocol"
    SSLCertificateFile="/etc/tomcat/ssl/my-site.crt"
    SSLCertificateKeyFile="/etc/tomcat/ssl/my-site.key" />

NIO2 + PEM configuration (Tomcat 9+) — ✅ Supported​

<Connector port="443" protocol="org.apache.coyote.http11.Http11NioProtocol">
    <SSLHostConfig>
        <Certificate certificateFile="/etc/tomcat/ssl/my-site.crt"
                     certificateKeyFile="/etc/tomcat/ssl/my-site.key"
                     type="RSA" />
    </SSLHostConfig>
</Connector>

Prerequisites​

  • Tomcat configured with APR/OpenSSL or NIO2 + PEM (see compatibility above)
  • Linux CLM agent installed and online with SSH access to the target server
  • SSH user with write permission on the target file paths
  • Certificate destination directory created on the server

Prepare the server​

Create the certificate directory​

mkdir -p /etc/tomcat/ssl
chmod 755 /etc/tomcat/ssl

Identify the certificate paths​

Use the paths defined in server.xml as identified above.

SSH user permissions​

The SSH user configured on the store needs write permission on the certificate directory. If you're using a non-root user:

# Grant permission on the directory to the user
chown root:<user> /etc/tomcat/ssl/
chmod 770 /etc/tomcat/ssl/

# Allow passwordless Tomcat restart via sudo
echo "<user> ALL=(ALL) NOPASSWD: /bin/systemctl restart tomcat" >> /etc/sudoers
Reload vs Restart on Tomcat
Unlike Nginx and Apache, Tomcat doesn't support reloading certificates without restarting the service. Use `systemctl restart tomcat` as the Reload command, which causes a brief service interruption while the new certificate is applied. Plan renewals around maintenance windows when needed.

Create via the Stores screen​

Step 1 — Provider​

Select Unix Provider.

Step 2 — Agent​

Select the Linux agent that will establish the SSH connection to the target server.

Step 3 — Configuration​

SSH Connection:

FieldDescription
Host / IPAddress of the Tomcat server
SSH PortSSH port (default: 22)
SSH UserUser with write permission on the configured paths
SSH PasswordUser's password (optional if using an SSH key)

Certificate file paths:

FieldExampleDescription
Certificate file path/etc/tomcat/ssl/my-site.crtPath defined in certificateFile or SSLCertificateFile in server.xml
Private key file path/etc/tomcat/ssl/my-site.keyPath defined in certificateKeyFile or SSLCertificateKeyFile in server.xml
CA Chain file path/etc/tomcat/ssl/my-site-chain.crtIntermediate chain (optional)
The correct paths are the ones defined in Tomcat's `server.xml`, in the `certificateFile` and `certificateKeyFile` directives (NIO2) or `SSLCertificateFile` and `SSLCertificateKeyFile` (APR). See the [How to identify your Tomcat configuration](#how-to-identify-your-tomcat-configuration) section.

Service configuration:

FieldValue
Reload commandsystemctl restart tomcat

If the SSH user isn't root, use sudo systemctl restart tomcat and configure sudoers as described in SSH user permissions.

Step 4 — Review​

Set the Repository Name, confirm the settings, and click Create Repository.

How the deploy works​

When a certificate is installed or renewed, the CLM:

  1. Connects to the server via SSH using the configured agent
  2. Writes the files to the configured paths (certificate, key, chain)
  3. Runs the Reload command to restart Tomcat and apply the new certificate

Install a certificate​

On the Store details screen, click Install Certificate, select the certificate from the inventory, and confirm.

Troubleshooting​

Deploy fails at step 1​

The agent couldn't write the file to the destination. Check:

# Confirm the directory exists
ls -la /etc/tomcat/ssl/

# Test write access with the configured SSH user
su - <user> -c "touch /etc/tomcat/ssl/test && echo OK && rm /etc/tomcat/ssl/test"

If it returns Permission denied, adjust the permissions as described in SSH user permissions.

Tomcat doesn't apply the new certificate after the deploy​

Check that server.xml points to the same paths configured in the store and restart manually:

systemctl restart tomcat
systemctl status tomcat

"keystoreFile not found" error​

This means Tomcat is configured with JKS, which isn't compatible with the Unix Provider. See the Compatibility section.