Enroll Linux machines

To manage a Linux machine, Gardience needs the Salt agent on it, pointed at the Salt master and approved. There are two ways to get there:

• The enrollment playbook for many machines at once. You run it with the Ansible you already use, and machines join without a manual key approval while the enrollment is open.
• The one-line installer for one machine at a time. You then approve its key in the console.

Supported distributions: RHEL, Oracle Linux, Rocky, Ubuntu, Debian, SUSE and Amazon Linux (every verified release is listed in the requirements and on the compatibility matrix). Both ways install Salt 3008.3 and pin it, so OS patching never upgrades the agent.

Add machines over SSH (coming from Ansible)#

The quickest way to bring an existing Ansible estate across. Under Machines > Add machines, in Add machines over SSH, paste:

• Inventory: your Ansible inventory, INI or YAML, or simply one host name or address per line. Groups and their nesting come across: each machine is tagged with its groups and they appear under Machines > Groups.
• SSH user and the private SSH key you already use with Ansible. Linux hosts need sudo; if sudo asks for a password, give it under Sudo password. Windows hosts use the connection your inventory sets (WinRM, PSRP or SSH).

Gardience opens a two-hour enrollment, runs its own enrollment playbook (the same one you can download below) from its isolated playbook runner, and shows each host's result. Machines that got the agent join on their own, already accepted. Up to 500 hosts at a time.

What it never does:

• Store the key or the sudo password. They exist only in the runner's private folder for that one job and are deleted when it ends; they are not written to Gardience's data, settings or logs. The audit log records who ran the job and how many hosts got the agent.
• Run your inventory's code. Only Gardience's own playbook runs. An inventory is refused before anything starts if it uses templates ({{ }}), a ProxyCommand or other SSH arguments, a local connection, a key file path, or host ranges like web[01:10] (list the hosts instead).

Only admins can add machines this way. To keep the key on your own controller instead, use the playbook below with the Ansible you already run.

Option 1: enroll with the Ansible playbook#

You need the admin role, and an Ansible control machine with plain ansible-core (no collections are needed). Gardience never sees your SSH keys or passwords.

To enroll an inventory:

1. In the console, open Machines > Add machines.
2. Under Bring your Ansible inventory, give the enrollment a label and choose how long it stays open (4 hours, 24 hours or 3 days).
3. Select Create enrollment playbook. The browser downloads gardience-enroll.yml.

4. Run it against your inventory:

   Copy

   ansible-playbook -i YOUR_INVENTORY gardience-enroll.yml

   Linux hosts need sudo (Ansible become). The playbook is safe to run again: it only changes what differs.

Machines appear under Fleet as they join. Their Ansible groups appear under Machines > Groups after the next scan, which runs every 5 minutes.

The playbook holds an enrollment token that lets machines join without approval. Treat it like a password, and close the enrollment when you are done. See Enrollment tokens.

What the playbook does on a Linux host#

A host counts as Windows when its ansible_connection is winrm or psrp, or its ansible_shell_type is powershell. Every other host gets the Linux steps.

Option 2: install on one machine and approve its key#

To add one machine:

1. In the console, open Machines > Add machines and copy the Linux commands. They are filled in with this server's address, the pinned Salt version and the installer checksum.

2. Run them on the machine as a user with sudo. They:

   • download the Salt bootstrap script and stop if its SHA-256 checksum does not match,
   • install Salt 3008.3 with the master address set and the agent ID set to the short host name (hostname -s),
   • pin the agent version with dnf versionlock or apt-mark hold.
3. Back on Machines > Add machines, find the machine under Waiting for approval and select Approve. Select Reject for a machine you do not recognize. The list refreshes every 8 seconds.

Approving and rejecting keys needs a role that can manage keys in Salt (the admin role). Other roles see "Your role cannot manage node keys." Each approval and rejection is written to the audit log.

On distributions without dnf or apt-mark, pin the Salt packages with your own package manager.

End-of-life releases (Debian 11)#

Salt's bootstrap script refuses releases past their end of life, which includes Debian 11 since its long-term support ended on 31 August 2026. On those machines both enrollment ways install the same pinned agent from Salt's own package repository instead: they download Salt's repository signing key, stop if its SHA-256 checksum does not match the one built into Gardience, add the repository and install salt-minion and salt-common at the pinned version. Nothing changes on a machine where the agent is already installed. Gardience manages these machines normally; plan the operating system upgrade anyway, since the release no longer gets security fixes.

If the server uses non-default Salt ports (--salt-ports), the one-line commands do not set them. Add publish_port and master_port to the agent config before you start the agent.

Check the key before you approve it#

An approved key lets that machine receive commands, so you may want to compare fingerprints first. On the machine:

sudo salt-call --local key.finger

On an all-in-one Gardience server, from the install folder:

cd /opt/gardience
sudo docker compose exec salt-master salt-key -f MACHINE_ID

The two fingerprints must match.

What the agent config contains#

The enrollment playbook writes /etc/salt/minion.d/gardience.conf. With default settings it looks like this:

master: gardience.example.com
id: "web-01"
autosign_grains:
  - gardience_enroll
grains:
  gardience_groups: ["linux", "web"]

Extra settings appear in some installs:

With the one-line installer, the bootstrap script writes the master address itself. When the server has a warm standby, the commands also write /etc/salt/minion.d/failover.conf with both servers and the failover settings. When --fleet-size is over 1000, they write /etc/salt/minion.d/gardience-fleet.conf with the reconnect settings.

The enrollment token grain#

/etc/salt/grains holds the line gardience_enroll: <token>. Once the node is accepted, Gardience removes this grain from it at the next scan, because anyone who can read grains could otherwise see the token.

After a machine joins#

When a new agent connects, Gardience pushes its Salt modules, grains and pillar to it within seconds. The node then shows on Overview > Dashboard after the next scan. To see its asset facts on Machines > Inventory, select Collect now there.

Related#

• Enroll Windows machines
• Enrollment tokens
• Groups and patch rings
• Requirements