Fix a Kopano SSL Handshake Error on a Custom Port

Define What a Successful Fix Looks Like

A Kopano SSL handshake error means a client and a server could not agree on or complete the TLS connection. The custom port may be correct for one part of the setup and wrong for another. Before changing certificates or protocol settings, identify which service owns the port and whether TLS is expected there.

For a working configuration, the intended port accepts a TLS connection, presents a certificate valid for the hostname clients use, and allows the next protocol step to complete. A browser should reach the WebApp sign-in page without a certificate warning. A Kopano Core client should connect using the matching TLS port and, where configured, its trusted client certificate. A successful TLS probe by itself does not prove that WebApp login, Kopano authentication, or mail delivery works.

First Separate the Two Common Port Setups

Verified for Kopano Core: Kopano’s Core Administrator Manual 8.0 describes a native TLS listener controlled by server_listen_tls. Its example uses port 237, says the port can be changed, and configures certificate and CA files in /etc/kopano/server.cfg. The manual also shows the clients using an https:// server socket with the matching port and client certificate. See Kopano Core: SSL connections and certificates and Kopano Core special configurations.

Separately, for WebApp access: users normally open a browser URL served by Apache, Nginx, or Kopano Web. TLS can terminate at that front-end server while it forwards requests to Kopano services. Kopano’s manual documents HTTP proxying to the Core listener on port 236, while its Kopano Web guide documents TLS certificate settings in /etc/kopano/kwebd.cfg. That front-end HTTPS port is not automatically the same as the Core TLS port. Check the Core reverse-proxy example and the Kopano Web installation guide.

Action: write down the client URL, the custom port, the process expected to listen there, and whether TLS ends at the proxy or at Kopano Core. Do not change both listeners at once.

1. Check What Is Listening on the Custom Port

On the Kopano host, replace 8443 below with the port that is failing:

sudo ss -ltnp | grep ':8443'

A matching row should show a listening socket. If there is no row, the service is not bound to that port, or it is bound to a different address. If the port belongs to a local reverse proxy, inspect the proxy’s virtual host. If it should be Kopano Core’s native TLS port, inspect server_listen_tls in /etc/kopano/server.cfg. A process listening only on 127.0.0.1 cannot accept remote connections directly; that may be intentional when a proxy sits in front.

Also check the host firewall, cloud firewall, and any load balancer or NAT rule. The public port must reach the intended internal listener. A timeout or connection refusal points to reachability or listener configuration; it does not by itself indicate a bad certificate.

2. Probe TLS on the Exact Hostname and Port

From a client machine, test the public endpoint with OpenSSL. Use the DNS name that appears in the certificate, not an unrelated IP address:

openssl s_client -connect mail.example.com:8443 -servername mail.example.com -showcerts

Look for a presented certificate, the negotiated protocol and cipher, and any verification errors. The -servername option sends the TLS SNI hostname; this matters when a server hosts more than one TLS site. OpenSSL documents these options in its s_client manual. Press Ctrl+C to leave the interactive probe.

If the certificate is absent, the endpoint may be speaking plain HTTP, the wrong service may own the port, or a proxy may be forwarding to an incorrect upstream. If a certificate appears but its name, issuer, or expiration is wrong, fix the certificate selection or chain on the TLS endpoint. A hostname mismatch is not fixed by changing the Kopano Core listener port.

For a browser-facing endpoint, follow with:

curl -v https://mail.example.com:8443/webapp/

The verbose output helps distinguish TLS verification from an HTTP response such as a redirect, 404, or 502. A 404 after a completed handshake is a path or routing issue, not a TLS negotiation failure. For a one-time diagnosis only, curl -vk can show whether bypassing certificate verification changes the result. Do not leave certificate checks disabled in a browser, client, or proxy.

Important limit: Kopano Core native TLS can use client certificates. A basic s_client test without a client certificate may be rejected even when the TLS listener is operating correctly. If the server requests client authentication, repeat the test with the authorized client certificate and key, or test with the configured Kopano service client. Never expose a private key in a command transcript or support ticket.

3. Match the Protocol to the Listener

A common custom-port mistake is configuring an HTTPS client to contact a plain HTTP listener, or forwarding HTTPS traffic to an upstream that is expecting HTTP. The scheme and port must describe the same endpoint.

• https://mail.example.com:8443/webapp/ means the browser expects TLS on port 8443.
• Kopano Core’s documented example sends proxied HTTP to 127.0.0.1:236. If your deployment uses that pattern, the proxy upstream must use http://, even though the public browser connection uses HTTPS.
• For native Kopano Core TLS, the manual’s example uses server_listen_tls = *:237 and a client URL beginning https://. If you change 237 to a custom port, update every dependent client or proxy to that same value.

Check for copied configuration lines that disagree about the port or scheme. In a multi-server setup, also review the published server or proxy URL: a client may complete an initial connection and then fail after Kopano redirects it to an old hostname or port.

4. Repair the Listener and Certificate Configuration

If this is Kopano Core’s native TLS listener, edit the existing configuration rather than adding duplicate directives. The following is a simplified example for a custom port; keep the certificate paths and CA appropriate to your installation:

server_listen_tls = *:1237
server_ssl_ca_file = /etc/kopano/ssl/ca.pem
server_ssl_key_file = /etc/kopano/ssl/server.pem
server_ssl_key_pass = your-key-passphrase

Kopano’s manual specifies the listener, CA, server-key, and key-pass settings and requires restarting kopano-server after this native listener change. Confirm that the installed version supports the options shown; package layouts and directives can differ. Protect the key directory and make sure the Kopano service account can read the required files.

Verify that the certificate is for the hostname clients actually use, is within its validity dates, and includes any required intermediate certificates. The Kopano manual notes that its components check the certificate common name and subject alternative names. In a multi-server TLS setup, the server must also trust the CA that signed client certificates, and authorized client certificates must be configured. Do not replace a certificate with a self-signed one as a shortcut for a public browser service.

If TLS terminates at Apache, Nginx, or Kopano Web, configure the certificate and custom listen port at that front end instead. Then set the upstream scheme and port according to the backend’s actual listener. Do not enable upstream TLS just because the public side uses HTTPS; first confirm that the backend port is also serving TLS.

5. Validate and Reload the Correct Service

Before reloading a web server, run its configuration check, such as sudo nginx -t for Nginx or sudo apachectl configtest for Apache. If the test reports an error, correct it before reloading. Use the service name installed on your distribution; for example:

sudo systemctl restart kopano-server
sudo systemctl status kopano-server --no-pager

Restart Kopano Core only when you changed its configuration. For a front-end-only port or certificate change, validate and reload the front-end service instead. Check its journal or error log immediately after the change and repeat the exact OpenSSL probe from the client network. The handshake should now present the expected certificate. Then test the actual WebApp URL or Kopano client connection, since TLS success alone does not validate the application route or authentication.

Read the Result Before Changing More

• No listening socket: check the configured listener, service status, and bind address.
• Connection refused or timeout: check firewall, NAT, load balancer, and whether the target port is reachable.
• Wrong certificate: inspect the certificate configured on the endpoint answering that port, including SNI selection and certificate chain.
• TLS works locally but not remotely: compare the public proxy or load balancer path with the local listener and review forwarded host and port values.
• Handshake succeeds but WebApp fails: inspect the HTTP status, proxy path, PHP/WebApp logs, and Kopano Core connectivity. Continue at the application layer.
• Only Core clients fail: verify their server_socket, custom port, trusted CA, and client certificate settings. The Core TLS path may require mutual certificate authentication.

A reliable fix changes only the endpoint that owns the failing handshake. The Kopano Core Administrator Manual available for this procedure is version 8.0.0, and its examples should be checked against the installed packages and local manual pages. If your deployment uses a different Kopano release, a container, or a managed reverse proxy, confirm that component’s current configuration before applying the sample directives.