Troubleshooting Teleport Auth Server TLS Startup Failures

The Problem: Auth Server Crash-Loops

When the Teleport Auth Server fails to start, it typically enters a crash-loop or exits immediately with a non-zero status. The most common cause is an invalid, expired, or mismatched TLS certificate. Because the Auth Server manages the cluster's identity, any failure in its certificate chain prevents the entire cluster from establishing trust, blocking all tsh and tctl operations.

The primary indicator of this issue is found in the service logs (e.g., journalctl -u teleport), where you will see errors such as tls: failed to parse certificate or x509: certificate signed by unknown authority.

Diagnostic Matrix

Symptom	Likely Cause	Diagnostic Note
TLS parse error	Corrupt or malformed PEM file	Often caused by manual edits or incorrect encoding during transfer.
Unknown authority	Missing or outdated CA bundle	Teleport cannot verify the cert against the root CA in /etc/teleport/ca.pem.
Certificate expired	Validity period passed	The NotAfter date in the certificate has passed.
Key mismatch	Private key does not match public cert	Occurs if only one part of the pair was regenerated.

Step-by-Step Verification Sequence

Run these checks on the Auth Server host. You will need root or sudo permissions to access the certificate directory.

1. Check File Permissions: Ensure the certificates are not world-readable and are owned by the teleport user.

   # Run on Auth Server
   ls -l /var/lib/teleport/*.pem
   # Expected: -rw------- 1 teleport teleport ...

2. Verify Certificate Validity: Check the expiration date and the signature chain.

   # Run on Auth Server
   openssl x509 -in /var/lib/teleport/auth.crt -text -noout | grep -A 2 "Validity"
   # Check the "Not After" date to ensure it is in the future.

3. Validate Private Key Integrity: Ensure the key file is not corrupt.

   # Run on Auth Server
   openssl rsa -in /var/lib/teleport/auth.key -check
   # Expected: RSA key ok

4. Confirm CA Configuration: Check the teleport.yaml file to ensure the ca_file path points to a non-empty, valid root CA file.
5. Analyze Startup Logs: If the server still fails, check for specific handshake errors.

   # Run on Auth Server
   journalctl -u teleport -n 50

Resolving the Failure

Apply the fix that corresponds to your diagnostic finding. Important: Back up your existing /var/lib/teleport/ directory before replacing any files.

• For Corrupt or Mismatched Keys: Regenerate the pair together to ensure they match.

  # Run as root/sudo
  tctl auth create --type=node --save-to /var/lib/teleport
  chmod 600 /var/lib/teleport/auth.key
  systemctl restart teleport

• For Expired Certificates: Renew the certificate via your automation tool or use tctl auth create to generate a new one.
• For Missing CA: Copy the correct root CA from your PKI or the original Auth service installation into the path specified by ca_file in teleport.yaml, then restart the service.

Verification of Fix

Once the service is restarted, verify the recovery using these three methods:

1. Service Status: Check that the logs report "Auth server started" and the process is running.
2. Health Endpoint: Test the HTTPS port (default 3080) directly.

   # Run from a remote machine or localhost
   curl -k https://<auth-host>:3080/healthz
   # Expected: 200 OK with JSON health status

3. Cluster Connectivity: Confirm the cluster is reachable via the CLI.

   # Run from a management workstation
   tsh login --proxy=<proxy-address>
   # Expected: Successful authentication prompt

Escalation Criteria

If the certificates are valid, the keys match, and the CA is correctly referenced but the server still fails to start, collect the following for support:

• Debug logs generated via TELEPORT_DEBUG=true teleport start --debug.
• The output of the OpenSSL verification commands used in the checks section.
• A redacted copy of teleport.yaml.