Apache Tomcat
Copy link to the page “Apache Tomcat”Installs the selected certificate alias in Tomcat’s PKCS12 or JKS keystore and restarts only the selected service.
What happens
- The service agent on the server fetches the task from the appliance over outbound HTTPS, port 443.
- The appliance supplies a prepared keystore as base64. The integration checks its hash, alias and private-key recovery before installing the selected alias. Other key and certificate entries are preserved. For a connector without a configured alias and a store with one private key, that selected key is replaced with the new alias. If it fails: Failures before the switch leave the active keystore in place.
- Only the selected Tomcat service is restarted. The integration waits for active state and the selected certificate on the local TLS port. If it fails: If a working service loses TLS, the integration attempts restore from its saved checkpoint. Serving the old certificate alone does not trigger restore. Rollback does not repeat a completed restore.
- Verification reads the certificate under the selected alias. Read failures return an error. With a local TLS port it also checks the served certificate; without local TLS proof, verification returns an activation warning.
Technical details
- Connection
- The integration runs through the service agent on the server. The service agent connects over outbound HTTPS to the appliance, port 443 by default. You open no port into the server.
- Service ports
- 443, 8443
- What you need
- The service agent installed on the server. The account needs write access to the keystore directory and readable service status. Passwordless sudo must permit the exact restart: systemctl restart -- SERVICE_NAME or service SERVICE_NAME restart. Status uses systemctl is-active -- SERVICE_NAME or service SERVICE_NAME status; sudo status is needed only when the account cannot read it directly.
- Actions
- Discovery, Installation, Verification, Rollback
- Integrations
-
tomcat-ssh1.4.0 - Note
-
- Discovery reads the server.xml of each running Tomcat (catalina.base and -config) and of the tomcat units' CATALINA_BASE, before the fixed install folders. Deploy also accepts a keystore outside the Tomcat folders when the server.xml of such an instance uses it. The certificate chain consists of the intermediate certificates that link the server certificate to a root certificate the browser trusts.
- The default alias is tomcat and must match the connector. JKS can use a separate KEY_PASSWORD; PKCS12 uses the same store and key password with Java keytool. Otherwise the store password is used. Configuration passwords must match. Existing raw passwords are preserved; optional KEYSTORE_PASSWORD_BASE64 and KEY_PASSWORD_BASE64 explicitly select base64.
- STARTUP_TIMEOUT defaults to 60 seconds, optionally 1–300. Local observation uses 127.0.0.1:8443; port and SNI can be selected. Observation proves certificate identity, not chain trust. Verify without a selected port inspects only the keystore.
- Discover finds Tomcat, connectors and possible certificate writers. A reference does not establish ownership; confirm another writer’s exact scope before takeover. The integration does not edit server.xml or other services’ certificate management.
- An active service accepting TCP before TLS is ready returns a startup warning. Pending journals are reconciled on the next run; an unproved certificate does not replace the previous restore checkpoint. Interrupted service control can resume when the selected service is stopped.
- Rollback uses a pending deployment journal; it does not undo a completed successful deployment.
- tomcat-ssh 2.0.0 is the next version, built for sslbrain v4 and released with it; until then the appliance installs 1.4.0 as described above. 2.0.0 runs the same script through the service agent on the server or over SSH. Over SSH it needs root or an account that may run sudo -n bash without a password, because the whole action runs as root. It keeps the inputs, the keystore's other entries and the replacement of the key when the connector names no alias. A failure after the write puts the previous keystore back and restarts Tomcat, and rollback puts the deploy's backup back, also after a deploy that succeeded.