TLS issues
Common reasons why TLS might not be working are:
- The key store password is incorrect on Tomcat's server.xml
- HTTPS connector not defined in Tomcat's server.xml file. SSLEnabled must be set to true on the HTTPS connector.
- Mismatch between keystore aliases defined in server.xml and the aliases used in the keystore.
- Intermediate cert is missing. It is often necessary to go hunting for additional intermediate certificates on CA websites.
- DNS mismatch. For example, having a certificate issued for mailarchiva.company.com, yet accessing the console from https://mailarchiva.company.local.
- expired certificate
- wrong CA certificates installed
- https port bound by another process
- certificate is not a wildcard certificate (only applicable if using MailArchiva Multitenant)
The Tomcat startup logs are located in /var/opt/mailarchiva/tomcat/logs (Linux) or C:\ProgramData\MailArchiva\Tomcat\logs (Windows). When Tomcat starts up, if it cannot access certs & key in the key store, it will output the errors in one of the log files in that directory. Also, ensure there is not a local firewall blocking the comms on port 443 and that Tomcat is not attempting to bind to an IPv6 address. If the latter add "-Djava.net.preferIPv4Stack=true -Djava.net.preferIPv4Addresses=true " to CATALINA_OPTS in /opt/mailarchiva/server/startserver.
Certificate installation
Refer to Certificates for instructions on how to import certificates and keys into MailArchiva. The below covers additional troubleshooting steps not mentioned there.
Cannot import a server certificate
You are unable to import a server certificate and key.
Error: Failed to establish chain from reply
- The order in which certificates are imported is important. Import the root Certifying Authority (CA) certificate first, then intermediate CA certs, then lastly, server cert & key (i.e. moving up the chain)
- Be sure that you are not missing an intermediate cert. Sometimes, a CA has two intermediate certs, and one or more of them might not have been mailed to you. It may be necessary to go look on the CA website for other intermediate certs. If there is a certificate missing in the chain, the above error will be outputted.
- If the server certificate key was generated using MailArchiva's inbuilt certificate request (CSR) process, ensure that Save was clicked to persist the key after the certificate generation was completed.
- If importing a server certificate and key is generated outside MailArchiva, then the private key must also be imported (i.e. its no use just importing a server certificate by itself). MailArchiva currently supports importing a private key and server certificate in PKCS-12 format. If your server certificate and private key is stored in a different format, use OpenSSL utilities to copy them to a PKCS-12 file. Afterwards, click the Import Private Key button in MailArchiva certificate management (Configuration->Certificates), enter password to PKCS-12 file, and the server cert and key will be imported. Click Save to save your changes.
The GUI will not come up when the server starts.
After starting the server, the GUI will not come up if...
- The alias specified in Tomcat server.xml is different from the alias the certificate installed in the MailArchiva certificate store
- The password specified in Tomcat server.xml for mailarchivacerts key store is wrong
Examine the Tomcat startup logs in /var/opt/mailarchiva/tomcat/logs/ or C:\ProgramData\MailArchiva\Tomcat\logs. Edit the connector on server.xml, switch back to port 80, restart MailArchiva and retrace the certificate install steps.
Unable to receive traffic with SMTP Start TLS enabled
First, isolate whether TLS is the cause of miscommunication between the mail server and MailArchiva. Do so by temporarily reverting the SMTP listener back to using plaintext and examining the charts to determine whether mail is received from the mail server. If so, it likely indicates that the TLS setup is the cause. The Exchange server may not support or be able to authenticate the certificates imported into MailArchiva, since the CA certificates may not be imported into Exchange.
Found this information useful? Visit mailarchiva.com to learn more about MailArchiva.