Appearance
Call-Home Agents
Normally, the Situate server connects out to each agent on the agent's directory port (14000 by default). A call-home agent works the other way around: the agent opens the connection to the server and keeps it open. The server never connects out to it.
Use call-home when the agent is behind NAT or a firewall that blocks inbound connections to the agent.
File transfers and remote execution work with call-home assets. The server sends them over the connection the agent opened.
WARNING
Because call-home agents add themselves to the domain, don't use them on untrusted networks: anyone there could add an agent to your domain.
How It Works
- The agent connects to the server's directory port (14000 by default) using its agent certificate.
- The first time it connects, the agent registers itself through discovery: it adds itself to the domain, so you don't add the asset by hand. The server accepts discovery requests by default.
- If no asset exists for that agent, the server creates one as a call-home asset, using the asset name the agent sent and the agent's address.
- On every later connection, the server identifies the agent from its certificate and attaches the connection to the matching asset.
In the asset data and the AI chat tools, a call-home asset has masq set to true.
Settings
| Setting | Meaning | Default |
|---|---|---|
| discover | <domain>,<host>,<port>: the domain to join, the server to connect to, and the server's port | None |
| discover name | Name of the asset to create | The agent's hostname |
| discover description | Description of the asset to create | "Added via discovery" |
| groups | Groups to add the asset to | None |
| update | <domain>,<host>,<port>: reconnect to a domain the agent already belongs to, without discovering | None |
For <host>, we suggest using the domain alias sit-<domain>. <port> is the server's directory port, normally 14000. All three parts are required: if one is missing, the agent logs Error: expected domain,host,port to be specified in 'update' or 'discover' configuration and ignores the setting.
To join more than one domain, separate the entries with semicolons, for example acme,sit-acme,14000;acmedev,sit-acmedev,14000.
Configuring on Linux / UNIX
In the Config File
To keep the settings across restarts, add them to the agent's config file. The agent reads /etc/situate.conf at startup, or the file given with the -config option.
The file is read as a shell script, so use KEY=value and quote any value that contains spaces:
sh
DISCOVER=<domain>,<host>,<port>
DISCOVER_NAME=<asset name>
DISCOVER_DESCRIPTION='<description>'
GROUPS=<groups>
UPDATE=<domain>,<host>,<port>For example, to join the domain acme through the server alias sit-acme:
sh
DISCOVER=acme,sit-acme,14000
DISCOVER_NAME=web-dmz-01
DISCOVER_DESCRIPTION='Web server in the DMZ'The installer doesn't write these settings. Add them by hand, then restart the agent.
On the Command Line
You can also pass the settings when starting the agent:
situated -discover <domain>,<host>,<port> -discover_asset_name <name> -discover_description <desc>These options apply only to that run of the agent. There is no command-line option for groups; use GROUPS in the config file.
Configuring on Windows
On Windows, pass the settings when you install the agent service (see Advanced Installation on Windows):
situated.exe -install -discover <domain>,<host>,<port> -discover_name <name> -discover_description <desc>-update <domain>,<host>,<port> is also accepted.
The installer saves these settings as values under the agent's registry key (HKEY_LOCAL_MACHINE\SOFTWARE\Situate\SituateAgent for the default instance), and the service reads them on every start. Value names are not case-sensitive.
There is no installer option for groups. To add the asset to groups, create a REG_SZ value named groups under the agent's registry key.
Connection Timing
The agent sends heartbeats over the connection and treats it as lost if no traffic arrives in time. Both timings can be set in the agent's situate.properties file.
| Property | Meaning | Default |
|---|---|---|
| masq_timeout | Time with no traffic, in milliseconds, before the connection is treated as lost | 120000 (2 minutes) |
| masq_hb_rate | How often the agent sends a heartbeat, in milliseconds | 30000 (30 seconds) |
Limitations
- A call-home asset can't be a replication backup target. The server reports "a backup must be directly reachable".