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 connects to the appliance itself, over HTTPS. The appliance never connects to the agent. This page applies to agents installed with an install code. An agent installed without an install code uses the address it was given at installation and does not follow Agents › Connection until it has moved over to an install code (Agents installed without an install code).
Directly to the appliance
Copy link to the section “Directly to the appliance”The server must reach the appliance over HTTPS, on port 443 by default. The address the agents are given is always the appliance’s hostname from Network and DNS and the agent port. If the appliance has no hostname, it is its IP address.
Under Network and DNS › Network the address is shown at Agents connect to. It cannot be edited there. The card has one field:
- External HTTPS port: 443 by default. A Docker install publishes the appliance on port 8443, so enter 8443 here.
The agent accepts the appliance’s certificate when the server trusts it, or when it matches the keys the agent received from the appliance.
If you change the hostname or the port, the install command under Servers › Add server shows the new address at once. Agents installed with an install code get the new address in their next configuration, the next time they check in. Until then they must be able to reach the address they have now, or sslbrain Cloud. Agents installed without an install code must be installed again with the new SERVER (MSI properties).
Addresses and order
Copy link to the section “Addresses and order”The Addresses card under Agents › Connection shows the addresses agents installed with an install code use. The card cannot be edited.
- Appliance address: the address from Directly to the appliance. It is changed under Network and DNS, not here.
- sslbrain Cloud: after the appliance address, while Allow agent communication through Cloud is on under Settings › Security.
A server that must reach the appliance on another address, for example through NAT or a reverse proxy, gets it in its install command (DESTINATIONS) or afterwards on the server’s page (Settings for one agent).
Upgrading the appliance removes previously saved address lists. If one held an address other than the appliance’s hostname or IP address, the audit log names it under agent_protocol.saved_agent_addresses_removed; give the servers that need it that address on the server’s page.
The first time, the agent uses the addresses on its install code. After that it follows the addresses here, or its own list on the server’s page.
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.
-
Open Settings for this agent in the Service agent panel.
-
Fill in only the fields that should differ. Empty fields follow Agents › Connection.
- Addresses in priority order (comma-separated, cloud for sslbrain Cloud):
httpsaddresses andcloud, no more than eight and at least onehttpsaddress. An address may not have a user name, query or fragment, and may not point at sslbrain Cloud. The list stays when the appliance changes hostname. - Debug for hours (1 to 24): debug logging for a limited time.
- Addresses in priority order (comma-separated, cloud for sslbrain Cloud):
-
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.
Through sslbrain Cloud
Copy link to the section “Through sslbrain Cloud”With Allow agent communication through Cloud on under Settings › Security, agents reach the appliance through sslbrain Cloud while the direct route is down. It is on by default. Every licence can connect through Cloud; if the licence does not cover a Cloud connection, a server that runs through Cloud gets no work (The licence). How to keep a single agent out: One agent with its own addresses.
Check that it works
Copy link to the section “Check that it works”The Service agent panel on the server’s page shows:
- Configuration: “sent v…, in use v…”. Matching numbers mean the agent uses the latest configuration.
- 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.
- A value cannot be saved: it is outside the limits in the tables below.
- The agent does not check in: A service agent does not check in.
- The server cannot reach any direct address: Servers outside your network.
The Check-in, retries and timeouts card controls how often the agent asks the appliance for work. The agents receive a saved change the next time they check in. If an agent cannot reach the appliance with the new configuration, it uses its last working one.
| 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 |
A Windows agent installed without an install code checks in every 900 seconds by default. The interval is set with CHECKININTERVAL at installation (MSI properties).
Retries and timeouts
Copy link to the section “Retries and timeouts”When an address does not answer, the agent waits longer and longer between attempts. 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 |
- Largest backoff must be at least First backoff.
- Connect timeout must be less than Request timeout.
- Request timeout may be no more than Probe timeout.
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. The install codes carry the same fingerprint.
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, because a backup from before the change cannot serve the agents (Take a backup).