Step 5 of 8 · Connection
How the agent reaches the appliance
Copy link to the page “How the agent reaches the appliance”The service agent always opens the connection to the appliance itself, over HTTPS. The appliance never opens a connection to the agent. The settings on this page apply to agents installed with an install code. An agent installed with the registration token uses the address it was given at installation and does not follow Agents › Connection.
Directly to the appliance
Copy link to the section “Directly to the appliance”Direct means the agent sends its messages to the appliance’s own address over HTTPS. The server must be able to reach the appliance on the port in that address, 443 by default.
The address and port the agents are given are under Network and DNS › Network, in the section Serviceagent-forbindelse & Ekstern port:
- Ekstern HTTPS-port: 443 by default.
- Annonceret forbindelses-URL (valgfri overstyring): used when the agents must reach the appliance on a different address from the one the browser uses, for example through NAT.
If you change the port or the address while agents are connected, the connected servers need the new address. Agents installed with an install code get it through Agents › Connection. Agents installed with the registration token must be installed again with the new SERVER (MSI properties).
The agent accepts the appliance’s certificate when the server trusts it, or when it matches the keys the agent received from the appliance in its configuration. That is why an IP address also works as a direct address.
Addresses and order
Copy link to the section “Addresses and order”The Addresses card under Agents › Connection is the default for every agent installed with an install code. Only administrators can change it.
- Direct addresses of the appliance: one per line, in the order the agent tries them.
https, with no user name, query or fragment. - Agent traffic through Cloud: puts sslbrain Cloud last in the list (Servers outside your network).
The list must have at least one direct address and no more than eight addresses in total. A direct address may not point at sslbrain Cloud. If the card has never been saved, the agents use the address set under Network and DNS › Network, then sslbrain Cloud.
The agent uses the addresses on an install code to reach the appliance the first time. After that it follows the list here, or its own list on the server’s page (Settings for one agent). An agent installed without cloud in its list has opted out of sslbrain Cloud and gets it back only when an administrator turns it on from the server’s page.
How often the agent checks in
Copy link to the section “How often the agent checks in”The Check-in, retries and timeouts card controls how often the agent asks the appliance for work.
| Field | Default | Limits |
|---|---|---|
| Check-in interval (seconds) | 300 | 30 to 3600 |
| Check-in jitter (%) | 20 | 5 to 50 |
| Quick follow-up after work (seconds) | 5 | 1 to 60 |
The jitter keeps the agents from checking in on the same second. After a task, the agent checks in again quickly with the result.
A Windows agent installed with the registration token checks in every 900 seconds by default. The interval is set with CHECKININTERVAL at installation (MSI properties).
Retries, switching address and timeouts
Copy link to the section “Retries, switching address and timeouts”When an address does not answer, the agent waits longer and longer between attempts, and after a number of failures in a row it switches to the next address in the list.
| Field | Default | Limits |
|---|---|---|
| First backoff (seconds) | 60 | 10 to 600 |
| Backoff factor (%) | 200 | 150 to 400 |
| Largest backoff (seconds) | 3600 | 300 to 86400 |
| Switch address after failures in a row | 3 | 1 to 10 |
| Retry the first address after (seconds) | 1800 | 300 to 86400 |
| Connect timeout (seconds) | 10 | 2 to 60 |
| Request timeout (seconds) | 60 | 10 to 300 |
| Probe timeout (seconds) | 120 | 30 to 600 |
| Log level | info | error, warn, info |
- A value outside the limits is refused when you save. It is not adjusted, because the agent would otherwise refuse the whole configuration.
- Largest backoff must be at least First backoff. Connect timeout must be less than Request timeout, and Request timeout no more than Probe timeout.
- Debug logging is turned on for one agent at a time from the server’s page, for at most 24 hours.
The agents receive a saved change the next time they check in. The agent tries the new configuration before it takes it into use. If it cannot reach the appliance with it, it uses its last working configuration.
Settings for one agent
Copy link to the section “Settings for one agent”A single agent can have its own values, for example a different order of addresses or debug logging.
-
Open the server under Servers.
-
In the Service agent panel, open Settings for this agent.
-
Fill in only the fields that should differ. Empty fields follow Agents › Connection, and the limits are the same.
- Addresses in priority order (comma-separated, cloud for sslbrain Cloud): the agent’s own list. It may contain only the direct addresses from Agents › Connection and
cloud. - Debug for hours (1 to 24): debug logging for a limited time.
- Addresses in priority order (comma-separated, cloud for sslbrain Cloud): the agent’s own list. It may contain only the direct addresses from Agents › Connection and
-
Save. The agent gets the settings the next time it checks in.
The Agents with their own settings card under Agents › Connection lists every agent with its own values and links to its server page.
Through sslbrain Cloud
Copy link to the section “Through sslbrain Cloud”The switch Agent traffic through Cloud puts sslbrain Cloud last in the agents’ address list, so an agent can reach the appliance when the direct route is down. It needs a Professional or Enterprise licence and an appliance connected to sslbrain Cloud. What Cloud can see, how you turn it on and off, and how a single agent opts out: Servers outside your network.
The appliance’s agent key
Copy link to the section “The appliance’s agent key”The card The appliance agent key shows the fingerprint of the key the appliance signs its messages to the agents with. It is the same fingerprint the install codes carry.
Only the owner can use Change the signing key. The agents follow the next time they check in. Unused install codes stop working. Take a new backup afterwards: a backup from before the change cannot serve the agents that have the current key (Take a backup).
Check that it works
Copy link to the section “Check that it works”The Service agent panel on the server’s page shows what the agent is using:
- Configuration: “sent v…, in use v…”. When the numbers match, the agent has taken the latest configuration into use.
- Last answer: Taken into use or Taken into use after a probe.
- Addresses in use: the list, with “in use now” next to the address the agent is using.
- Last reached: Directly or Through Cloud.
If it fails
Copy link to the section “If it fails”- Last answer is Refused or Using its last working configuration: the agent could not reach the appliance with the new configuration. Check the addresses and the port, and that the server can reach them.
- The agent does not check in: A service agent does not check in.
- The server is outside your network and cannot reach any direct address: Servers outside your network.