Troubleshooting

Troubleshooting Guide

This guide provides deep-dive solutions for common operational issues in SSL-CLM.

1. Agent Connectivity Issues

`ERR_AGENT_OFFLINE` / Heartbeat Failure

Symptom: Agent shows as “Offline” in the dashboard. Jobs stuck in QUEUED.

Check Service Status:
- Windows: Get-Service ssl-clm-agent
- Linux: systemctl status ssl-clm-agent
Verify Network Reachability: The Agent must be able to reach the Backend URL defined in application.properties.
Terminal window
```
# Run this on the Agent machine
curl -v https://your-backend-api.com/api/health
```
- If timeout: Check outbound firewall (Port 443).
- If SSL Error: The Agent does not trust the Backend’s certificate (Self-signed?). Import the Root CA into the Agent’s Java Truststore.
Check Agent Logs: Look at logs/agent.log for 401 Unauthorized. If seen, regenerate the Agent Token in the UI and update application.properties.

2. Certificate Renewal Failures

`ERR_CA_DENIED` (Policy Violation)

Symptom: Job fails with “The request was denied by the CA.”

Cause 1: Restricted Domains: You requested google.com or a high-value domain that requires manual vetting.
Cause 2: Name Mismatch: The template requires O=MyCompany but the CSR had O=Default.
Fix: Check the “Failure Reason” in the Job Details view. Adjust the Certificate Policy in SSL-CLM to match CA requirements.

`ERR_ACME_CHALLENGE` (Validation Failed)

Symptom: Let’s Encrypt / ACME validation fails.

HTTP-01 Fails:
- Does the hostname resolve to your Agent’s IP?
- Is Port 80 open to the world? (Let’s Encrypt validates from multiple global IPs).
DNS-01 Fails:
- Did SSL-CLM successfully create the TXT record? Check your DNS dashboard.
- Is there a high TTL on the DNS record causing stale reads?

3. Discovery & Inventory Issues

”My Scan Found 0 Certificates”

Symptom: Network discovery job completes but finds nothing.

Firewall Check: The Agent must be able to connect to the target IP on Port 443.
- Test: Test-NetConnection -ComputerName 192.168.1.50 -Port 443
SNI (Server Name Indication): Some servers require a hostname to respond. IP-only scans might fail if the server drops non-SNI handshakes.
Timeout: Increase the scan timeout in the Scan Policy if your network is slow.

”Duplicate Certificates in Inventory”

Symptom: You see the same certificate twice.

Fix: This usually happens if the “Source” logic fails to merge. Run a System Maintenance > Re-Index job to force the canonical engine to de-duplicate based on SHA-256 fingerprints.

4. Integration Errors

Microsoft CA (MSCA): “RPC Server Unavailable”

Symptom: Agent cannot talk to AD CS.

Fix: DCOM requires Port 135 and the Dynamic RPC range (49152-65535). Ensure these are allowed between the Agent and the CA Server.
Auth: The Agent service account must be a Domain User with “Request Certificates” permission on the CA.

F5 BIG-IP: “Authentication Failed”

Fix: Ensure the user accounts provided to SSL-CLM has Resource Administrator role on the F5 device. It needs permission to write to /sys/file/ssl-cert.

5. Performance Tuning

UI is Slow / “Loading…”

Cause: Large inventory (>100k certificates).

Fix: Enable database indexing in MongoDB.

db.certificates.createIndex({ "validTo": 1 })
db.certificates.createIndex({ "fingerprint": 1 })

Getting Advanced Support

If issues persist, please gather the Support Bundle from the Admin Console, which includes:

Sanitized Config (application.properties)
Last 1000 lines of Backend/Agent logs
Thread Dumps (if stuck/frozen)

Contact: support@qcecuring.com