Step 5 of 8 · Linux

Linux servers

The service agent for Linux is a systemd service. It fetches certificates from the appliance and installs them on the server. You connect the server with one line, copied from the appliance.

Before you start

You need:

An x86_64 or arm64 server with systemd, for example Ubuntu, Debian, Red Hat Enterprise Linux, Rocky Linux or AlmaLinux.
Root access to the server, or an account with sudo.
The server can reach the appliance directly over HTTPS, or reach sslbrain.com and cloud.sslbrain.com on port 443. If it is somewhere other than the appliance, see Servers outside your network.

Connect the server

The Install service agent page shows a Linux line once the appliance has Linux agent 0.7.0. Until then it says Linux servers can be added with the next Linux agent. under Linux.

Open Servers › Install service agent in sslbrain and choose Linux. The page shows an open install code or creates one itself.

Copy the line under Linux. It looks like this:

curl -fsSL https://<appliance>/agent.sh | sudo sh -s -- --code <code> --server https://<appliance>

Paste the line into a terminal on the server and press Enter.

agent.sh fetches the newest agent package from the same address, checks its SHA-256 and installs the agent with the code. The package picks the architecture itself. After a minute or two the server is listed under Servers.

The agent is installed so it can install certificates and reload services. The same code works on as many servers as you like, until you close it under Install codes on the same page, or until the last day you gave it.

If the appliance uses its own self-signed certificate, the line fetches agent.sh from sslbrain.com instead, and the agent then connects directly to the appliance. Give the appliance a real certificate, and the agent is fetched from the appliance itself (Free name).

Connect through sslbrain Cloud

If the server cannot reach the appliance directly, open The server cannot reach the appliance directly and use the line there:

curl -fsSL https://sslbrain.com/agent.sh | sudo sh -s -- --code <code>

The agent finds the appliance through sslbrain Cloud with the code. Cloud can neither read nor change what the appliance and the agent send each other (Servers outside your network).

The section is on the Linux tab once the appliance has Linux agent 0.7.0.
The section is shown only while Allow agent communication through Cloud is on under Settings › Security.
Every licence can connect through Cloud. If the licence does not cover a Cloud connection, the server is listed as Blocked under Servers and gets no work until it is switched to a direct connection or the licence is upgraded (Servers outside your network).

Several servers at once

Run the line on each server, for example with Ansible or another configuration management tool. It needs no file and no answer along the way.

The server appears

A server that connects with the code is approved and listed under Servers. sslbrain looks for Nginx and Apache on the server and lists what it finds under Services.

A server that looks like a reinstall of one already connected waits under Servers waiting for approval on Install service agent instead.

Compare Agent key with the key the agent wrote to its log on the server (Log files).
Click Approve.

Next step

Prove that the domain is yours, so sslbrain can get certificates for it: Prove the domain is yours.

If it fails

agent.sh says “specify —code or —server”: the line lacks the code. Copy it again from Install service agent.
agent.sh says “does not match its checksum”: the package changed while it was being fetched. Run the line again.
agent.sh says “no verified Linux agent package”: the appliance has not yet fetched the agent from sslbrain Cloud. It fetches it every night at 03:15. Try again later; the line through sslbrain Cloud needs the same package.
curl says “SSL certificate problem”: the server does not trust the appliance’s certificate. Give the appliance the free name (Free name).
install.sh says “this package has no protocol core”: the server is neither x86_64 nor arm64.
A tool is missing: the agent needs bash 4.4 or later, openssl, tar, curl or wget, flock, timeout, base64, find, od and sed.
The server has no systemd: add --mode cron to the line.
The server is listed as Blocked: it is connected through sslbrain Cloud, and the licence does not cover it. Open the server and click Switch to direct (Servers outside your network).
The server does not appear: read the agent’s log (Log files), and check that the server can reach the appliance (The agent does not check in).
The certificate is not installed: The installation fails.

Log files

The agent writes to the journal:

systemctl status sslbrain-agent.service
journalctl -u sslbrain-agent.service -n 50 --no-pager

With --mode cron the log is in /var/lib/sslbrain/state/agent.log.

Options for agent.sh and install.sh

agent.sh passes its options on to install.sh in the package.

Option	Meaning
`--code <code>`	The install code from Install service agent. With `--server` the agent connects directly and has sslbrain Cloud as fail-over. Without it, it goes through sslbrain Cloud
`--server <address>`	The appliance’s address. Without `--code` the server waits for an administrator to approve it. Used only for the first contact; after that the appliance manages the addresses
`--cloud-deny`	The agent never contacts sslbrain Cloud, whatever the appliance sends
`--profile deploy`	Runs as root, installs certificates and reloads services. The default
`--profile scoped`	Writes only in the certificate folders you give it access to, and reloads the service through a hook root owns. Needs local setup
`--profile inventory`	Finds and monitors certificates, but installs none
`--mode systemd\|timer\|cron`	How the agent runs. The default is `systemd`
`--code-file <file>`	Read the code from a file, or `-` for standard input, instead of `--code`

One of --code and --server is required. If the installation runs again without --profile, the agent keeps its profile. The agent is in /usr/local/lib/sslbrain/sslbrain-agent, its settings in /etc/sslbrain/agent.conf and its state in /var/lib/sslbrain/state.