What Is salt-ssh?
salt-ssh runs Salt commands over SSH on machines that have no Salt minion. It copies a small 'thin' Salt package to the target, runs the function, returns the result and cleans up (or keeps a cache for speed).
| Use salt-ssh when | Use minions when |
|---|---|
| You cannot install an agent (appliances, locked-down hosts, a first-time bootstrap) | You manage many servers and want speed |
| You manage a few servers occasionally | You want events, reactor, beacons and the schedule |
| You want to install the minion itself | You need targets to talk to the master constantly |
Install
The Roster File
A roster lists the machines and how to connect. The default file is /etc/salt/roster.
Run Commands
Where Are the State Files?
salt-ssh reads states and pillar from the machine where you run it, using the same file_roots and pillar_roots. The master daemon does not need to run. A laptop with Salt installed can configure servers.
A Project Folder With Its Own Config (Recommended)
Targeting With salt-ssh
Targeting is limited to the roster: globs, lists (-L), regex (-E), and grains (-G) after the first connection. Pillar and nodegroup targeting need minions. A simple solution is to put roles in the roster grains: section.
Dynamic Rosters
| Roster | Source |
|---|---|
flat (default) | The YAML file above |
scan | Scan a network range |
cloud | Machines made by Salt Cloud |
ansible | Read an Ansible inventory |
terraform | Read Terraform state (needs the roster module) |
clustershell, range, sshconfig | Other sources, including ~/.ssh/config |
Bootstrap a Minion With salt-ssh
Limits and Tips
- Slower than minions for many targets: one SSH connection per host. Use
--max-procsor-csettings for parallelism - No events, beacons or reactor on targets
- Needs Python 3 on the target for the thin package, unless you use the
-rraw mode or the relenv-based thin variants of newer versions (check docs for your version) - Pillar is rendered on the machine running
salt-ssh, so secrets must be available there - Use SSH keys and
sudowith the least privilege, and do not put passwords in the roster file
| Problem | Fix |
|---|---|
Permission denied | Check user, key, sudo: True and sudoers rule (NOPASSWD for the deploy user) |
Host key verification failed | Add the host key to known_hosts, or -i in labs only |
python3: command not found on the target | Install Python 3, or use the raw -r mode |
| Old results / odd state | Clear the thin cache: salt-ssh '*' -W or --wipe; salt-ssh --refresh-cache |
| Debug | salt-ssh -l debug 'web1' test.ping |
Practice Tasks
- Create a roster with two machines and run
test.ping - Apply a small state with
salt-sshand withtest=True - Make a project folder with a
Saltfileand run it from a laptop - Use salt-ssh to install the minion on a new VM and accept its key on a master
- Write down three situations where you would pick salt-ssh over a minion
Conclusion
salt-ssh gives agentless Salt over SSH with a roster file. It is perfect for small jobs, locked-down hosts and bootstrapping minions, while minions are faster and unlock events, reactor and beacons.

