Troubleshooting

The most common problems and how to solve them.

Vault Sealed

Problem: sslbrain shows "Vault sealed" and cannot issue or deploy certificates

Solution: Click Unseal in the web interface and enter your vault password.

Prevention: Enable auto-unseal under Settings > Vault. The vault then opens automatically on restart. See Security for details on unsealing methods.

Server Connection Failed

Problem: sslbrain shows "Connection failed" or "Timeout" when you add or test a server

Check these things:

  1. Hostname/IP: is the address correct? Can you ping the server from the sslbrain machine?
  2. Firewall: is the required port open?
    • SSH: port 22
    • WinRM: port 5985 (HTTP) or 5986 (HTTPS)
    • Agent: no inbound ports necessary (the agent calls out on its own)
  3. Credentials: are the username and password/key correct? Does the user have the necessary permissions?
  4. Server online: is the server running? Check that it responds on the expected port.

For WinRM: confirm that WinRM is enabled on the Windows server:

PowerShell 
winrm quickconfig

Certificate Issues

Certificate is not issued

Problem: Certificate issuance fails with a validation error

Check these things:

  1. DNS: is the domain set up correctly? Check with dig _acme-challenge.yourdomain.com TXT. If you are using DNS validation, the TXT record must exist. If you are using HTTP validation, port 80 must be open.
  2. Firewall: the CA must be able to reach your server. Let's Encrypt validates from the internet, so the server must be accessible from outside on port 80 (HTTP-01) or DNS must be correct (DNS-01).
  3. ACME account: is the account active? Check under Settings > ACME accounts.
  4. Rate limits: Let's Encrypt has rate limits. If you have issued many certificates in a short time, you may be limited. Wait an hour and try again. The error message typically mentions "rate limit".
Terminal 
dig _acme-challenge.yourdomain.com TXT

Certificate is not renewed

Problem: A certificate is approaching expiry, but sslbrain is not renewing it automatically

Check these things:

  1. Auto-renew: is auto-renew enabled for the certificate? Check the certificate details.
  2. ACME account: is the ACME account that issued the certificate still active?
  3. Scheduler: is sslbrain's scheduler running? Check under Dashboard that scheduled tasks are executing.
  4. Deploy log: check the certificate's deploy log for error messages. Perhaps the renewal succeeds but deployment fails.

Tip: sslbrain attempts renewal 30 days before expiry and retries daily if it fails. Check the deploy log to see what is going wrong.

Deployment Failed

Problem: The certificate is issued, but installation on the server fails

Check these things:

  1. Deploy log: open the certificate and click Deploy log. Here you can see exactly what went wrong, step by step.
  2. IIS site name: does the site name in sslbrain match the actual site name in IIS? Names are case-sensitive.
  3. Permissions: does the user sslbrain connects with have the necessary permissions? IIS certificate installation requires local administrator.
  4. Port conflict: is port 443 already in use by another binding? IIS only allows one certificate binding per IP/port combination (unless SNI is used).

Windows Agent Not Connecting

Problem: A Windows server with the agent installed shows as "Offline" in sslbrain

Check these things:

  1. Service running: check that the SSLBrainAgent service is running
  2. Log files: check the agent's log files in C:\ProgramData\SSLBrain\logs\
  3. DNS: can the server resolve the sslbrain server's hostname?
  4. Registry: is ServerURL correct?
  5. Firewall: can the server reach sslbrain on the configured port? The agent uses outbound HTTPS.
  6. Restart the agent: sometimes restarting the service solves the problem.

Diagnose with these commands:

CMD 
sc query SSLBrainAgent
nslookup your-sslbrain-server.example.com
reg query "HKLM\SOFTWARE\SSLBrain" /v ServerURL
PowerShell 
Test-NetConnection -ComputerName your-sslbrain -Port 8443

Restart the agent if necessary:

CMD 
net stop SSLBrainAgent && net start SSLBrainAgent

See also Windows Service Agent for more details on the agent's setup and configuration.

Cannot Log In

Forgotten admin password

Reset the admin password via the command line:

Terminal 
docker exec sslbrain php artisan sslbrain:reset-admin

The command generates a new password and displays it in the terminal. Log in and change the password afterwards.

AD/LDAP login fails

Problem: AD/LDAP users cannot log in

Check these things:

  1. Check that the AD server is accessible from the sslbrain machine
  2. Check the LDAP configuration under Settings > Security > LDAP
  3. Click Test connection to confirm sslbrain can reach the AD server
  4. Check that the user's AD group is mapped to an sslbrain role

Tip: Local admin accounts always work, regardless of the AD connection. Use the local admin to troubleshoot AD issues.

Update Fails

Problem: An update starts but fails during the process

sslbrain automatically creates a backup before updating and rolls back if the update fails. Your installation should be in the same state as before the update.

Check these things:

  1. Disk space: is there enough free space? Updates require temporary space for download and backup.
  2. Update log: check the log under Settings > Updates > Log for the exact error message.
  3. Network: can sslbrain reach the update server? Check proxy settings if you use one.

Tip: Auto-rollback is safe, your installation and data are not affected by a failed update.

License Expired

Problem: sslbrain shows "License expired"

When the license expires, you have a 30-day grace period where everything works normally. After that, sslbrain falls back to Community level:

  • Existing certificates and servers are not affected
  • Auto-renew continues to work
  • Features that require Pro or Enterprise are disabled (LDAP, offline mode, etc.)
  • The server limit is set to the Community level

Solution: Renew the license under Settings > License to reactivate all features immediately.

Disk Full

Problem: sslbrain behaves slowly or fails with disk-related errors

Free up space:

  1. Deployment logs: old deploy logs accumulate over time. Go to Settings > Maintenance and delete logs older than e.g. 90 days.
  2. Temp files: sslbrain normally cleans up after itself, but on errors there may be remnants. Restart sslbrain to trigger cleanup.
  3. Backups: archive or delete old backups that are no longer needed.

Check disk usage:

Terminal 
docker exec sslbrain df -h /data