Salt SSH is very easy to use, simply set up a basic roster file of the
systems to connect to and run
salt-ssh commands in a similar way as
Salt ssh is considered production ready in version 2014.7.0
Python is required on the remote system (unless using the
-r option to
send raw ssh commands). The python version requirement is the same as that
for a standard Salt installation.
On many systems, the
salt-ssh executable will be in its own package, usually named
The Salt SSH system does not supersede the standard Salt communication systems, it simply offers an SSH-based alternative that does not require ZeroMQ and a remote agent. Be aware that since all communication with Salt SSH is executed via SSH it is substantially slower than standard Salt with ZeroMQ.
At the moment fileserver operations must be wrapped to ensure that the
relevant files are delivered with the
The state module is an exception, which compiles the state run on the
master, and in the process finds all the references to
salt:// paths and
copies those files down in the same tarball as the state run.
However, needed fileserver wrappers are still under development.
The roster system in Salt allows for remote minions to be easily defined.
See the SSH roster docs for more details.
Simply create the roster file, the default location is /etc/salt/roster:
This is a very basic roster file where a Salt ID is being assigned to an IP address. A more elaborate roster can be created:
host: 192.168.42.1 # The IP addr or DNS hostname
user: fred # Remote executions will be executed as user fred
passwd: foobarbaz # The password to use for login, if omitted, keys are used
sudo: True # Whether to sudo to root, not enabled by default
sudo works only if NOPASSWD is set for user in /etc/sudoers:
fred ALL=(ALL) NOPASSWD: ALL
By default, salt-ssh will generate key pairs for ssh, the default path will be
/etc/salt/pki/master/ssh/salt-ssh.rsa. The key generation happens when you run
salt-ssh for the first time.
You can use ssh-copy-id, (the OpenSSH key deployment tool) to deploy keys to your servers.
ssh-copy-id -i /etc/salt/pki/master/ssh/salt-ssh.rsa.pub email@example.com
One could also create a simple shell script, named salt-ssh-copy-id.sh as follows:
if [ -z $1 ]; then
echo $0 firstname.lastname@example.org
ssh-copy-id -i /etc/salt/pki/master/ssh/salt-ssh.rsa.pub $1
Be certain to chmod +x salt-ssh-copy-id.sh.
Once keys are successfully deployed, salt-ssh can be used to control them.
Alternatively ssh agent forwarding can be used by setting the priv to agent-forwarding.
salt-ssh on target hosts without Python 3
salt-ssh command requires at least python 3, which is not
installed by default on some target hosts. An easy workaround in this
situation is to use the
-r option to run a raw shell command that
salt-ssh centos-5-minion -r 'yum -y install epel-release ; yum -y install python26'
salt-ssh on systems with Python 3.x
Salt, before the 2017.7.0 release, does not support Python 3.x which is the
default on for example the popular 16.04 LTS release of Ubuntu. An easy
workaround for this scenario is to use the
-r option similar to the
salt-ssh ubuntu-1604-minion -r 'apt update ; apt install -y python-minimal'
salt-ssh command can be easily executed in the same way as a salt
salt-ssh '*' test.version
salt-ssh follow the same syntax as the
The standard salt functions are available! The output is the same as
and many of the same flags are available. Please see
Salt SSH reference for all of the available options.
salt-ssh runs Salt execution modules on the remote system,
salt-ssh can also execute raw shell commands:
salt-ssh '*' -r 'ifconfig'
The Salt State system can also be used with
salt-ssh. The state system
abstracts the same interface to the user in
salt-ssh as it does when using
salt. The intent is that Salt Formulas defined for standard
salt will work seamlessly with
salt-ssh and vice-versa.
The standard Salt States walkthroughs function by simply replacing
Due to the fact that the targeting approach differs in salt-ssh, only glob and regex targets are supported as of this writing, the remaining target systems still need to be implemented.
By default, Grains are settable through
default, these grains will not be persisted across reboots.
See the "thin_dir" setting in Roster documentation for more details.
Salt SSH takes its configuration from a master configuration file. Normally, this
file is in
/etc/salt/master. If one wishes to use a customized configuration file,
-c option to Salt SSH facilitates passing in a directory to look inside for a
configuration file named
New in version 2015.5.1.
Minion config options can be defined globally using the master configuration
ssh_minion_opts. It can also be defined on a per-minion basis with
minion_opts entry in the roster.
By default, Salt read all the configuration from /etc/salt/. If you are running
Salt SSH with a regular user you have to modify some paths or you will get
"Permission denied" messages. You have to modify two parameters:
cachedir. Those should point to a full path writable for the user.
It's recommended not to modify /etc/salt for this purpose. Create a private copy
of /etc/salt for the user and run the command with
If you are commonly passing in CLI options to
salt-ssh, you can create
Saltfile to automatically use these options. This is common if you're
managing several different salt projects on the same server.
So you can
cd into a directory that has a
Saltfile with the following
Instead of having to call
salt-ssh --config-dir=path/to/config/dir --max-procs=30 --wipe \* test.version you
salt-ssh \* test.version.
Boolean-style options should be specified in their YAML representation.
The option keys specified must match the destination attributes for the
options specified in the parser
salt.utils.parsers.SaltSSHOptionParser. For example, in the
case of the
--wipe command line option, its
dest is configured to
ssh_wipe and thus this is what should be configured in the
Saltfile. Using the names of flags for this option, being
w: True, will not work.
For the Saltfile to be automatically detected it needs to be named Saltfile with a capital S and be readable by the user running salt-ssh.
At last you can create
will automatically load it by default.
Salt's ability to allow users to have custom grains and custom modules is also applicable to using salt-ssh. This is done through first packing the custom grains into the thin tarball before it is deployed on the system.
For this to happen, the
config file must be explicit enough to indicate
where the custom grains are located on the machine like so:
It's better to be explicit rather than implicit in this situation. This will allow urls all under salt:// to be resolved such as salt://_grains/custom_grain.py.
One can confirm this action by executing a properly setup salt-ssh minion with salt-ssh minion grains.items. During this process, a saltutil.sync_all is ran to discover the thin tarball and then consumed. Output similar to this indicates a successful sync with custom grains.
This is especially important when using a custom file_roots that differ from /etc/salt/.
Please see https://docs.saltproject.io/en/latest/topics/grains/ for more information on grains and custom grains.
One common approach for debugging
salt-ssh is to simply use the tarball that salt
ships to the remote machine and call
To determine the location of
salt-call, simply run
salt-ssh with the
flag and look for a line containing the string,
SALT_ARGV. This contains the
salt-ssh attempted to execute.
It is recommended that one modify this command a bit by removing the
--output json to get a better idea of what's going on the target system.
The 3001 release removed python 2 support in Salt. Even though this python 2 support is being dropped we have provided multiple ways to work around this with Salt-SSH. You can use the following options: