When something does not work

Each section starts with what you see in the appliance, word for word. Then comes the cause and what to do. Some messages are shown by the appliance in Danish only; those are quoted in Danish here, or described where the Danish text cannot be reproduced. If a section does not solve the problem, send a support bundle to FairSSL.

The appliance cannot open its keys

What you see: The appliance has restarted while it could not reach sslbrain Cloud. Logging in with sslbrain Cloud gives “Cloud authentication is currently unavailable. Try again or use emergency access.”

Cause: The vault, where the certificates’ private keys are stored, is opened at start-up with a key from sslbrain Cloud. If the appliance cannot reach sslbrain Cloud, the vault stays locked. The first task that needs the vault tries sslbrain Cloud again, so the vault opens by itself once the connection is back. The Vault row on Support does not show whether the vault is locked. Cloud connection under Appliance and licence › Overview does.

How to fix it:

Restore the connection to sslbrain Cloud, see sslbrain Cloud cannot be reached. The vault then opens by itself.
If you need to get in before the connection is back, click Lost access? Use backup words on the login page.
Enter the 12 backup words in the Backup words field and click Log in with backup words. The appliance opens the vault and signs you in as Admin Local. Overview shows the Emergency access active banner.

If the words are wrong, the appliance answers “Invalid backup key.” What Admin Local can do is in Security.

Installation locked

What you see: Every page shows Installation locked and the text “The cloud has temporarily paused this installation because another device is attempting a takeover, or a backup has been restored. Choose how to recover.” A code is shown under Reason. The page has the buttons Try to reconnect and Use backup key instead.

Cause: sslbrain Cloud has seen another machine report as the same installation, or the appliance has been restored from a backup. Usually a copy of the virtual machine is running, or you clicked Restore under System › Backup yourself. sslbrain Cloud then pauses the installation, and the vault is locked.

How to fix it:

If a copy of the appliance is running, for example a clone in the hypervisor, shut it down first.
Click Use backup key instead.
Enter the 12 backup words in the Backup key field, separated by spaces. Upper and lower case and extra spaces make no difference.
Click Unlock. The appliance opens the vault, lifts the lock and shows Overview with a short confirmation in Danish that the vault is unlocked.

If the words are wrong, the appliance answers with a message in Danish saying the emergency key is invalid.

Try to reconnect leads to the Awaiting confirmation page, see the next section.

The installation has been retired

What you see: This installation has been retired and “sslbrain Cloud no longer serves this appliance. Its licence has moved to another appliance, or it was taken out of service. Certificates are no longer renewed from here.”

Cause: The licence has been released in sslbrain Cloud, and another appliance has taken it over.

How to fix it: The appliance that holds the licence now is the one to use. Use backup key instead opens the data on the retired machine, for example if something needs to be copied across. See Move or restore the appliance.

The appliance is awaiting confirmation

What you see: The Awaiting confirmation page with the text “We sent a takeover request to your administrator in the sslbrain portal. This page refreshes automatically when there is a decision.” Below the text are Request ID, Expires and Last checked.

Cause: Someone clicked Try to reconnect on the Installation locked page. The appliance has asked sslbrain Cloud to take over the installation again and checks every minute whether there is a decision. The request expires after 7 days.

How to fix it: Open the appliance with the 12 backup words.

Click Back to lockdown.
Click Use backup key instead, enter the 12 backup words in the Backup key field, and click Unlock.

If you did not ask to reconnect yourself, contact FairSSL at info@fairssl.dk.

sslbrain Cloud cannot be reached

What you see: One or more of these:

Appliance and licence › Overview: Cloud connection shows Not connected.
The login page: “Cloud authentication is currently unavailable. Try again or use emergency access.”
Updates: “The update check could not reach sslbrain Cloud. Check the cloud connection.”
Actions on Overview, after 48 hours: Kan ikke kontrollere for opdateringer.

Cause: The appliance needs outbound HTTPS (443) to cloud.sslbrain.com, acme.sslbrain.com and registry.sslbrain.com. A firewall, a proxy or DNS is stopping the connection.

How to fix it:

Choose 2 Test the connection to sslbrain Cloud in the console menu on the virtual appliance. Each name shows reachable (HTTP nnn), NAME DOES NOT RESOLVE or NO ANSWER.
NAME DOES NOT RESOLVE is a DNS problem. Correct the DNS servers under 3 Configure the network, see Console menu.
NO ANSWER is usually a firewall. Open outbound 443 to the three names.

If the appliance runs in Docker, test from the host:

curl -sS -o /dev/null -w '%{http_code}\n' https://cloud.sslbrain.com/api/v1/health

What still works while sslbrain Cloud cannot be reached:

The certificates on your servers. They work until they expire.
Login with e-mail and password for a Cloud user who has logged in with a password before, and login with a local password, see Users and sign-in.
Alerts through E-mail (SMTP) and Webhook, see Keep an eye on your certificates.

Certificates ordered through sslbrain Cloud wait until the connection is back.

A service agent does not check in

What you see:

Monitoring › Alerts: “The agent on … is offline” when the agent has not checked in for 15 minutes.
The server’s page: “The agent has not checked in for over a day.”
Actions on Overview: “Agent: …” with “Sidste check-in for … timer siden”, after 48 hours.
The Agent stale alert rule, after 48 hours.

Cause: The service agent contacts the appliance itself over outbound HTTPS. It does not check in when the service is stopped, when the server cannot reach the appliance’s address and port, or when the appliance has a different address. An agent installed with an install code checks in every 5 minutes by default, and a Windows agent installed without an install code every 15 minutes.

How to fix it on the Windows server, in PowerShell as administrator:

Get-Service SSLBrainAgent
Test-NetConnection -ComputerName <appliance-address> -Port 443
Get-Content "C:\ProgramData\SSLBrain\logs\agent-$(Get-Date -Format yyyy-MM-dd).log" -Tail 50
Restart-Service SSLBrainAgent

Port 443 is the default. If you chose another Ekstern HTTPS-port under Network and DNS › Network, test that one.

The service is stopped: Start it with Restart-Service SSLBrainAgent, and read the log if it stops again. See Windows servers.
TcpTestSucceeded is False: The server cannot reach the appliance. Open outbound HTTPS from the server to the appliance.
The server is outside your network (a branch office, hosting, behind a firewall): Let the service agent connect via sslbrain Cloud, see Servers outside your network.
The appliance has a different address or port: The agents need the appliance’s current address, see How the agent reaches the appliance.

After a restore from backup, the server’s page shows “The appliance was restored from a backup. The agent gets no work until it has answered the appliance challenge.” The agent gets work again once it has answered. See Save a backup and restore from it.

A server without an agent cannot be reached

What you see:

Servers: status Unreachable or Auth failed.
Actions on Overview: the server’s hostname with a Danish message saying it is not available, or “Autentificering fejlet”.
Monitoring › Alerts: ”… is not responding”.
The Connection lost alert rule, when sslbrain has not been able to reach the server for more than 2 hours.

Cause: For devices without a service agent, the appliance connects itself over SSH or the device’s API. Unreachable means the device does not answer on the port. Auth failed means the device has rejected the credentials.

How to fix it:

Open the server under Servers and click Test connection.
For Unreachable: Check that the device is running and that the appliance can reach it on the port: 22 for SSH and the device’s HTTPS port for API.
For Auth failed: Correct the credentials under Credentials, see Devices without an agent.

The most secure way to connect a Windows server is the service agent, see Connect servers.

Domain validation fails

What you see: One of these messages on the source under Sources, on the profile under Profiles, on the certificate’s page or under Deployment › Scheduled:

Message	How to fix it
”The CA could not find the DCV record in DNS. Check that `_acme-challenge` points to the right place, then try again.”	Check the CNAME delegation in public DNS, see below.
”… cannot be validated because the appliance has no DNS access to the zone. Create a CNAME from … to …, or add a DNS API credential for the zone.”	Create the CNAME the message names, see CNAME delegation.
”… cannot be validated because no DNS API credential covers the name. …”	Create a CNAME delegation or a DNS API credential for the zone, see DNS API.
”The DNS API credential could not create the DCV record for …. Open the credential, press Test access, and fix what it reports.”	Click Test access on the credential, and correct the key or its permissions at the DNS provider.
”The CA is not accepting more orders for these names right now (rate limit). Wait, then try again later.”	Wait and try again.
”The appliance is not connected to sslbrain Cloud. Sign in with sslbrain Cloud again, then try again.”	See sslbrain Cloud cannot be reached.

Cause: The CA looks up a TXT record under _acme-challenge.<name> in public DNS. sslbrain creates it either through the CNAME delegation to your Auto-DNS name or with a DNS API credential. If neither exists for the name, the certificate is not ordered.

To check the CNAME delegation against a public DNS server:

dig @1.1.1.1 +short CNAME _acme-challenge.<domain>

Resolve-DnsName -Server 1.1.1.1 -Type CNAME _acme-challenge.<domain>

The answer must be the Auto-DNS name shown under Domain validation › CNAME delegation (Auto-DNS). The CA cannot see a record that exists only in your internal DNS.

A certificate is not renewed

What you see: The certificate is listed under Actions with “Expires in … days” without being renewed, the Renewal failed alert rule sends a message, or the source shows Error under Sources.

How sslbrain renews: The appliance looks for certificates due for renewal every 3 hours. A certificate of 90 days or less is renewed when two thirds of its validity has passed, and a longer certificate 30 days before expiry. At the latest it is renewed when 7 days are left. Renewal has no setting, and the operation mode does not affect it. See First certificate on a server.

Causes and what to do:

Domain validation fails: See Domain validation fails.
The appliance cannot reach sslbrain Cloud: See sslbrain Cloud cannot be reached.
All the certificate’s rules point to servers the licence does not cover: The run is shown as “Sprunget over: mangler licens…”. See The licence has expired or is too small.
The certificate has no rule: Create a rule, see First certificate on a server. Certificates you uploaded yourself are not renewed by sslbrain.
The certificate was renewed but not deployed: See Deployment to the server fails.

Deployment to the server fails

What you see:

Actions on Overview: “Failed deployment: …” with “Endpoint: … on …”, for failures within the last 7 days.
Monitoring › Alerts: “Deploy failed on …”.
The Deployment failed alert rule.

Cause: The run’s output says why. Often the service agent is not checking in, the server cannot be reached, or the account on the server lacks permissions.

How to fix it:

Open Deployment › Runs, choose Failing now, and open the run. It shows the output, events on the server and Executed via.
Fix the cause. If the agent is not checking in, see A service agent does not check in. If the server cannot be reached, see A server without an agent cannot be reached.
Click Run again. Operator and the roles above it can run a deployment again, but not while it is running.

A renewed certificate is only deployed by itself when the rule is active and Auto-deploy on certificate renewal is on, and only within the rule’s maintenance window if it has one. See First certificate on a server.

What you see	Cause	How to fix it
”E-mail eller adgangskode er forkert.”	Wrong e-mail or password, for a local user or a Cloud user.	If the user created their Cloud account with GitHub, Google or Microsoft, it has no Cloud password. Use Log in with sslbrain Cloud.
A Danish message about too many login attempts, with the number of seconds to wait.	More than 30 failed attempts.	Wait the number of seconds the message gives.
”Cloud authentication failed. Please try again.”	Login through sslbrain Cloud did not complete.	Try again.
”Cloud authentication is currently unavailable. Try again or use emergency access.”	The appliance cannot reach sslbrain Cloud.	See sslbrain Cloud cannot be reached.
”You do not have access to this installation.”	The Cloud account is neither owner nor administrator on the account, nor a member of this appliance.	Give the person access under Team in sslbrain Cloud, see sslbrain Cloud.
”The licence on this appliance does not allow another login. Release one, or upgrade the licence, and try again.”	All the licence’s logins are in use.	See Users and sign-in.
”Your session has expired. Please log in again.”	A session lasts 120 minutes.	Log in again. The appliance takes you back to the page.

If nobody can get in, use Lost access? Use backup words on the login page with the 12 backup words. You are signed in as Admin Local. Then give a user a local password, so there is a way in that does not depend on sslbrain Cloud, see Users and sign-in.

The update fails

What you see: Update log on Maintenance and support › Updates shows “Failed: …” or “Rolled back: …” with a reason, and Last update shows “Aborted, the version did not change”. The appliance keeps running the version it had.

Reason in the log	How to fix it
”there was not enough free disk to pull the new version; the running version was not stopped”	The update needs room for the new version (at least 4 GB) plus 2 GB. See The disk is filling up.
”the new version could not be downloaded”	The appliance cannot reach `registry.sslbrain.com`. See sslbrain Cloud cannot be reached.
”the signature could not be verified”	Do not try again. Send a support bundle to FairSSL.
”the new version could not start” or “the new version did not respond correctly after starting”	Read the controller’s log in the console menu: `4 View logs` and then `2 The controller: updates, restarts, signature checks`. Send a support bundle to FairSSL.
”a docker-compose override on the host pins a different image”	The appliance runs in Docker, and an override file on the host names a specific image. Remove the image line from the override file and update again.

If Updates says “This release is not signed yet and cannot be installed.”, wait and click Check now later. See Keep sslbrain up to date.

The licence has expired or is too small

What you see:

Actions on Overview: a Danish item saying the licence expires in a number of days, or a Danish item saying the licence has expired and must be renewed to keep using every feature.
Appliance and licence › Overview: “The licence has expired. Current limits are shown below.”
A banner on Overview: ”… of your … servers are deactivated because the licence covers …”, and the servers are marked Deactivated under Servers.
A new rule is refused: “The licence includes no more deploy rules. Upgrade the licence to create more, or delete a rule you no longer use. The rules you have keep renewing and installing.”

Cause: An expired licence falls back to Free, which covers 5 servers and 10 rules. The licence covers the oldest servers. Servers beyond that are not refused, but the certificates on them are neither renewed nor deployed.

How to fix it: Renew or upgrade the licence in sslbrain Cloud under Licences and units, see sslbrain Cloud. Or delete servers you no longer use, and the next servers in line get a licence.

Two messages during first-time setup:

“This account has no licence free right now.” Buy a licence, or release the one another appliance holds, see Move or restore the appliance.
“A free license already exists on this IP address.” There can be only one Free licence per IP address.

The disk is filling up

What you see: Actions on Overview shows a Danish item about low disk space when 80 % of the disk is used, and a Danish item about critically low disk space at 90 %. The critical item says that backups and updates that would fill the disk are refused, and that you should free up space or extend the disk now.

Cause: Backups, the appliance’s versions and log files share the same disk. Certificate renewal does not wait for disk space and carries on.

How to fix it:

Download the backups you want to keep and delete old backups under System › Backup, see Save a backup and restore from it.
Choose 7 Free disk space in the console menu. It removes unused images, including the version of the appliance that ran before the current one. The running appliance is not touched.
If that is not enough, extend the disk: shut down the virtual machine, make the virtual disk larger in the hypervisor, and start the machine. Then choose 9 Danger zone and 5 Claim new space from the virtual disk. See Console menu.

If the appliance runs in Docker, free up space on the host.

Send a support bundle to FairSSL

A support bundle is a JSON file with what FairSSL needs to find a fault. It is under Maintenance and support › Support in the Support bundle card, which only administrators see.

Download support bundle downloads the file sslbrain-debug-<date>-<time>.json. Send it to info@fairssl.dk.
Send to sslbrain Cloud sends the bundle to FairSSL through sslbrain Cloud once you have confirmed. The page says “Supportbundtet er sendt til sslbrain Cloud.” If the appliance cannot reach sslbrain Cloud, it says “The appliance is not connected to sslbrain Cloud.” Support bundles sent shows the latest 20.

The bundle contains system information, migration status, the queue, active orders, disk usage, the latest deployments with the agents’ output, agent tasks, rule runs, agent versions, the last 100 lines of the appliance’s log and every setting. Passwords, tokens, API keys and private keys are removed, both in what you download and in what is sent. Hostnames and IP addresses stay in the bundle. Download it first if you want to read exactly what is sent.

The bundle is only sent when someone clicks the button. See also Support and diagnostics.

When something does not work

The appliance cannot open its keys

Installation locked

The installation has been retired

The appliance is awaiting confirmation

sslbrain Cloud cannot be reached

A service agent does not check in

A server without an agent cannot be reached

Domain validation fails

A certificate is not renewed

Deployment to the server fails

Login fails

The update fails

The licence has expired or is too small

The disk is filling up

Send a support bundle to FairSSL