How to use salt-ssh

How to use salt-ssh


Saltstack is well known for its event based master/agent architecture, but you can also use salt agentless by using salt-ssh. At Sunayu we use salt-ssh to quickly update machines that do not have a salt agent running. Learn more about salt by reviewing the salt documentation.



To complete this tutorial you will need two Centos 7 systems. In our example we use the following two machines:

  • c71 – The host were we will run the salt-ssh commands from
  • c72 – The host we will configure via salt-ssh


Step 1 – Install salt-ssh

While you do not need an agent installed on the system you wish to manage with salt-ssh, you do need to install salt-ssh where you plan to run the commands from. Let’s install salt-ssh using salt’s bootstrap script.

curl -o -L
sudo sh

This will configure yum with saltstacks repo and install the salt minion. Now that we have the salt yum repo we can install salt-ssh

sudo yum -y install salt-ssh

Step 2 – Configure salt-ssh config

Let’s make a directory for all of our salt-ssh files:

mkdir saltssh
cd saltssh

Now let’s make our master configuration file: vi master

log_level: info
root_dir: .
cachedir: cache
ssh_log_file: logs/master
pki_dir: pki
  - pillar
  - states

Now let’s make the directories we configured above.

mkdir cache logs pki pillar states

Your directory should now look like this:

[[email protected] saltssh]$ ls
cache  logs  master  pillar  pki  states

Step 2 – Create our roster file

A roster file is how we tell salt-ssh which nodes to ssh to. Let’s create ours: vi roster

  host: c72
  user: centos
  passwd: 'reallygoodpassword'
  sudo: true

Step 3 – Test connectivity

Now that we have our directory configured and roster file setup we can test connectivity to our node!

[[email protected] saltssh]$ salt-ssh -i -c . 'c72'


  • The -i tells salt-ssh to ignore host keys
  • The -c . tells salt-ssh to only look in our current directory for configuration. This picks up the master config file and uses all of the local directories.


Step 4 – Run a state

Now that we have our node configured with salt-ssh we can run salt states to configure this machine. Let’s add our machine (c71) to its hosts file. First, let’s create a hosts.sls file inside the states directory: vi states/hosts.sls

add c71 to host file:
    - name: c71
    - ip:

Your file structure should look like this:

[[email protected] saltssh]$ find .

Now let’s run the state using salt-ssh!

[[email protected] saltssh]$ salt-ssh -i -c . 'c72' state.apply hosts
          ID: add c71 to host file
    Function: host.present
        Name: c71
      Result: True
     Comment: Added host c71 (
     Started: 22:24:56.403528
    Duration: 1.409 ms

Summary for c72
Succeeded: 1 (changed=1)
Failed:    0
Total states run:     1
Total run time:   1.409 ms

You can now go into host c72 and verify that c71 has been added to its /etc/hosts file.

[[email protected] ~]# cat /etc/hosts | grep c71            c71



In this tutorial we covered how to setup a self contained salt-ssh directory and run a simple state using salt-ssh. For more detailed use of salt-ssh please check the official docs.