Version: Added in version 2026.3.0.

Beginning in version 2026.3.0 of Tableau Server, server administrators have the option to replace the self-signed certificates used by Tableau Server with custom certificates. If you have configured Tableau Server to use custom certificates and then have issues with the Coordination Service (for example due to an expired certificate, a key mismatch, or a customer-supplied chain that no longer validates), you need to take special action to fix the problem without requiring a fresh installation of Tableau Server and a restore of an existing backup. For more information about using custom certificates for internal service communication, see Configuring Internal Custom Certificates for Tableau Server.

Use the per-node recover-coordination-service-cert tool to replace the Coordination Service (ZooKeeper) mTLS certificate and key material directly on disk. You must apply the same server and client certificate/key pair on every node.

Prerequisites

• You must run the tool on an existing Tableau Server node, as root or as the unprivileged Tableau run-as user.

• Have one server certificate/key pair and one client certificate/key pair ready. Optional chain files and passphrases for encrypted keys are supported.

Recover the custom certificate

1. If you do not already have a certificate, generate a fresh self-signed pair once, on a single node, and copy the identical files to every node. The pair should mirror what TSM generates internally (EC P-256, self-signed, CN=*):

   openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -days 1825 -nodes -subj "/CN=*" -keyout server.key -out server.crt

   openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -days 1825 -nodes -subj "/CN=*" -keyout client.key -out client.crt

   To produce a passphrase-encrypted key, omit -nodes. OpenSSL prompts for a passphrase, which you then pass with the matching --server-passphrase or --client-passphrase option.

2. Run the recovery tool on the first node. Start with a node that hosts the Coordination Service so that quorum can re-form:

   recover-coordination-service-cert --server-cert server.crt --server-key server.key --client-cert client.crt --client-key client.key [--server-chain <file.crt>] [--client-chain <file.crt>] [--server-passphrase <passphrase>] [--client-passphrase <passphrase>]

   The tool pre-validates the inputs before it stops anything: it confirms the certificate parses as X.509, that any supplied passphrase decrypts the key, and that the first certificate in any supplied chain is the leaf's issuer. It then stops the local services, patches every service's configuration and keystore, and restarts the control plane (ZooKeeper first, then the administration agent, then the rest).

3. Run the exact same command on every remaining node, using the identical certificate and key files. Recover the nodes that host the Coordination Service first, then recover any remaining nodes. The cluster is not recovered until the tool has run on every node—any node still holding the old keystore does not rejoin.

   Note: At this stage, tsm status shows business services in an error state. This is expected. The tool patches the services but leaves them stopped. The set command in the next step brings them up.

4. After every node is done, run the following set command once from the controller or initial node to sync the Coordination Service's persisted configuration with what is now on disk:

   tsm security coordination-service-internal-cert set --server-cert server.crt --server-key server.key --client-cert client.crt --client-key client.key [--server-chain <file.crt>] [--client-chain <file.crt>] [--server-passphrase <passphrase>] [--client-passphrase <passphrase>]

   The recovery tool prints this command for you, pre-filled with the paths you passed. It reminds you to re-add the passphrase options but never echoes the passphrase value. The command's identical-certificate short-circuit syncs the configuration and brings the whole cluster—including the stopped business services—back up, clearing the error state.

Troubleshooting: Each run writes a structured log to ${TABLEAU_SERVER_DATA_DIR}/logs/app-recover-coordination-service-cert.log.

Note: On Windows, an equivalent wrapper, recover-coordination-service-cert.cmd, takes the same options and behaves the same way.