Site proxies
A site proxy is a small relay at a remote site, a branch office, a DMZ or any network segment that should not talk to the Gardience server directly. The site's machines connect only to the proxy; the proxy relays their two Salt connections to the server. The firewall then needs one opening, from the proxy to the server, instead of one per machine.
Nothing about management changes: the server still sees and manages every machine behind the proxy directly. Keys are approved on the server, every job and its result go through the server's permissions, approvals and audit log, and the machines appear in the console like any other, in a group named after their site.
What the proxy can and cannot see
Salt encrypts its traffic between each agent and the server with keys the proxy never holds. The proxy relays ciphertext: it cannot read jobs or results, change them, or impersonate the server or an agent. A compromised proxy can stop its site's traffic and see which machines connect and when, and nothing more. It stores no keys, no credentials and no data.
Requirements
- A Linux machine at the site with Docker. The relay only forwards encrypted connections, so a small machine (1 CPU, 1 GB of memory) suits a typical site; check
proxy statusand the machine's load as the site grows. - From the proxy to the Gardience server: TCP 4505 and 4506 (or your server's
--salt-ports). - From the site's machines to the proxy: TCP 4505 and 4506 (or the proxy's
--listen-ports).
Install a proxy
On the site machine, from the unpacked Gardience bundle (online or offline), as root:
./install/proxy.sh --master gardience.example.com --site denver --license /path/to/gardience-license.jsonThe proxy's one image (about 30 MB) is downloaded with your license and checked against the signed release, as the server's are. From the offline bundle, the image is already in the bundle and no license is needed.
| Option | Default | Meaning |
|---|---|---|
--master ADDRESS | (required) | The Gardience server, as the proxy reaches it. |
--license FILE | Your Gardience license, to download the proxy's image (not needed with the offline bundle). | |
--site NAME | (required) | Lowercase letters, digits and dashes. Machines enrolled for the site join the group site-NAME. |
--master-ports P,R | 4505,4506 | The server's Salt ports, if it was installed with --salt-ports. |
--listen-ports P,R | 4505,4506 | The ports the site's machines connect to. |
--listen ADDRESS | 0.0.0.0 | The address the proxy listens on. |
--dir DIR | /opt/gardience-proxy | Where the proxy's files go. |
The installer checks that the server answers on both ports before it changes anything, then starts the relay. It uses the same pinned, updated web server image as the Gardience server, read-only, with no data volume.
Manage it with /opt/gardience-proxy/proxy status | restart | logs | uninstall. status shows how many of the site's agents are connected.
Enroll the site's machines
In the console, open Machines > Add machines, and under Bring your Ansible inventory fill in Site (for example denver) and Site proxy (the proxy's host name, or host:4505,4506 if it listens on other ports). The playbook it generates points every agent at the proxy and tags it with the site. Run it against the site's inventory as usual; new machines join without a manual key approval while the enrollment is open.
Machines already managed directly can move behind a proxy by changing master: in their agent configuration to the proxy's address and restarting the agent; their keys stay valid.
Availability
A proxy is stateless: if it is lost, install a new one with the same address (or point DNS at a replacement) and the site's agents reconnect on their own. For a site that must not lose management during a proxy outage, run two proxies and give the agents both addresses with Salt's failover settings (master: [proxy-a, proxy-b], master_type: failover).
Tested
Every release check installs a proxy from the release bundle, enrolls an agent that can reach only the proxy, manages it through the server, restarts the proxy and checks that the agent comes back on its own.