Salt SSH: Agentless Management with Roster Files, Targeting and Thin Packages

SaltStack 20 min min read Updated: Nov 17, 2026 Intermediate
Salt SSH: Agentless Management with Roster Files, Targeting and Thin Packages
Intermediate Topic 3 of 3

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 whenUse 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 occasionallyYou want events, reactor, beacons and the schedule
You want to install the minion itselfYou need targets to talk to the master constantly

Install

bash sudo dnf install -y salt-ssh # or: sudo apt-get install -y salt-ssh salt-ssh --versio

The Roster File

A roster lists the machines and how to connect. The default file is /etc/salt/roster.

yaml # /etc/salt/roster web1: host: 192.168.56.11 user: deploy sudo: True # run Salt as root with sudo priv: /home/deploy/.ssh/id_ed25519 port: 22 web2: host: 192.168.56.12 user: deploy sudo: True priv: /home/deploy/.ssh/id_ed25519 db1: host: 192.168.56.20 user: deploy sudo: True passwd: use-key-instead # avoid passwords; prefer keys timeout: 30 minion_opts: # settings for the thin minion environment: production grains: roles: [db]

Run Commands

bash salt-ssh '*' test.ping salt-ssh 'web*' cmd.run 'uptime' salt-ssh -i 'web1' pkg.install nginx # -i: ignore host key checks (labs) salt-ssh 'web*' grains.items salt-ssh -r 'web1' 'systemctl status sshd' # -r: raw ssh command, no Salt needed on the target salt-ssh 'web*' state.apply nginx salt-ssh 'web*' state.apply nginx test=True salt-ssh 'web*' state.highstate

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.

yaml # /etc/salt/master (read by salt-ssh as well) file_roots: base: - /srv/salt pillar_roots: base: - /srv/pillar ssh_log_file: /var/log/salt/ssh

A Project Folder With Its Own Config (Recommended)

text project/ Saltfile # tells salt-ssh where to find config etc/master # config for this project roster # machines salt/ # states top.sls nginx/init.sls pillar/ top.sls
yaml # project/Saltfile salt-ssh: config_dir: etc max_procs: 30 wipe_ssh: True # project/etc/master root_dir: /home/alice/project file_roots: base: - /home/alice/project/salt pillar_roots: base: - /home/alice/project/pillar ssh_roster: /home/alice/project/roster
bash cd project salt-ssh '*' test.ping salt-ssh 'web*' state.apply nginx

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

RosterSource
flat (default)The YAML file above
scanScan a network range
cloudMachines made by Salt Cloud
ansibleRead an Ansible inventory
terraformRead Terraform state (needs the roster module)
clustershell, range, sshconfigOther sources, including ~/.ssh/config
bash salt-ssh --roster ansible --roster-file ./inventory.ini '*' test.ping salt-ssh --roster scan '192.168.56.0/24' test.ping

Bootstrap a Minion With salt-ssh

yaml # /srv/salt/salt_minion/init.sls: install and configure a minion using salt-ssh salt-minion: pkg.installed: [] /etc/salt/minion.d/master.conf: file.managed: - contents: | master: salt-master id: {{ grains['id'] }} - require: - pkg: salt-minion salt-minion-service: service.running: - name: salt-minion - enable: True - watch: - file: /etc/salt/minion.d/master.conf
bash salt-ssh 'new*' state.apply salt_minion # needs the Salt package repository to be configured on the target sudo salt-key -L # new keys appear on the master

Limits and Tips

  • Slower than minions for many targets: one SSH connection per host. Use --max-procs or -c settings for parallelism
  • No events, beacons or reactor on targets
  • Needs Python 3 on the target for the thin package, unless you use the -r raw 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 sudo with the least privilege, and do not put passwords in the roster file
ProblemFix
Permission deniedCheck user, key, sudo: True and sudoers rule (NOPASSWD for the deploy user)
Host key verification failedAdd the host key to known_hosts, or -i in labs only
python3: command not found on the targetInstall Python 3, or use the raw -r mode
Old results / odd stateClear the thin cache: salt-ssh '*' -W or --wipe; salt-ssh --refresh-cache
Debugsalt-ssh -l debug 'web1' test.ping

Practice Tasks

  1. Create a roster with two machines and run test.ping
  2. Apply a small state with salt-ssh and with test=True
  3. Make a project folder with a Saltfile and run it from a laptop
  4. Use salt-ssh to install the minion on a new VM and accept its key on a master
  5. 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.

Quick Summary: roster; sudo: True; salt-ssh '*' state.apply; Saltfile project; slower than minions; no events.

Get Newsletter

Subscibe to our newsletter and we will notify you about the newest updates on Edugators