Configure and Use Salt SSH to Manage Your Linodes
Updated by Linode Contributed by Sergey Bulavintsev
Introduction to Salt SSH
Salt SSH allows you to execute Salt commands, or states, without installing a salt-minion package.
During execution, Salt SSH will copy necessary files to the target system’s
/tmp folder with SSH, then execute commands, and finally clean up Salt temporary files.
Please note: Because it uses SSH, Salt SSH is slower than standard Salt with ZeroMQ.
Before You Begin
This guide assumes that you’re using an rpm-based system (CentOS, RedHat, Oracle Enterprise Linux) .
Make sure that you have the
salt-sshpackages installed on your master. Check if these packages are installed:
$rpm -q salt $rpm -q salt-ssh
NoteFor detailed instruction on how to set up SaltStack repo, please refer to the Salt Stack Installation Guide
Your minions must have Python installed. Without Python installed on minions, you will only be able to run Salt SSH in raw mode. In raw mode, a raw shell command cannot use execution modules or apply Salt states. If you’re running a modern version of CentOS/RedHat, you already have Python installed on your systems
You must have at least one master server and one minion (client).
Set Up Salt Roster File
The Roster file contains target system information, connection details and credentials. The Default location for the Roster file is:
NoteThe Roster file is configured on the master server.
/etc/salt/rosterwith an editor. Define the client systems, by adding the following lines to the file:
This is an example of minimal host definition
linode1: host: <IPADDRESS OR HOSTNAME> user: <username> passwd: <password>
NoteThe Roster file stores data in YAML format. Do not add unnecessary spaces to the config file.
If you have a public key stored on the minion, and a private key on the master system, you can configure access to a minion using a private key. For public key authentication, add the following lines to the Roster file:
#This is an example of minimal host definition using private key: linode1: host: <IPADDRESS OR HOSTNAME> user: <username> priv: /<username_home_folder>/.ssh/id_rsa
NoteUsing SSH keys is the safest way to access your minions because passwords are not being stored in plain text.
To set up connection to a minion as a regular user, you have to configure a few files. In this case Salt will leverage privileges via sudo. In order to use sudo, set
sudo: Truein the
host definitionsection of the Roster file. By default sudo will only work when the real user is logged in over TTY. You can overcome this in two ways:
a. Disable the TTY check by commenting a line in the sudoers file on your minion:
# Defaults requiretty
b. Force TTY allocation by setting the
tty: Trueoption in your Roster file:
linode1: host: <IPADDRESS OR HOSTNAME> user: <username> passwd: <password> sudo: True tty: True
NotePermissions leverage via sudo works only if the NOPASSWD option is set up for the user that is connecting to the minion in
/etc/sudoers. More information on Roster files can be found in the Roster files documentation.
Check that the master server has access to the client using the
[root@master ~]# salt-ssh linode1 test.ping
The output should be:
NoteIf SSH keys weren’t deployed, you may receive the
The host key needs to be accepted, to auto accept run salt-ssh with the -i flag:message. In this case just run
salt-sshwith -i flag. This key will let Salt automatically accept a minion’s public key. This has to be done only once, during the initial SSH keys exchange.
Remote Command Execution via Salt SSH
You can execute any command on your minions via the
[root@master ~]# salt-ssh linode1 cmd.run "du -sh /root" linode1: 15M /root
Salt SSH supports globbing and PCRE regular expressions. For example, if you would like to execute command on all minions, whose names contain “linode”:
[root@master ~]# salt-ssh "linode*" cmd.run 'uname -r' linode1: 3.10.0-229.1.2.el7.x86_64 linode2: 2.6.32-573.3.1.el6.x86_64
NoteSalt SSH executes commands concurrently, the default-maximum is 25 simultaneous connections.
It is possible to use any execution module with Salt SSH. With execution modules, you can install packages, control services, gather system information, and much more.
[root@master ~]# salt-ssh linode1 pkg.install iftop linode1: ---------- iftop: ---------- new: 1.0-0.14.pre4.el7 old: [root@master ~]# salt-ssh linode1 service.restart httpd linode1: True [root@master ~]# salt-ssh linode1 disk.percent /var linode1: 22%
NoteA full list of execution modules is available at Execution modules documentation.
Install Salt-Minion Remotely via Salt SSH
An interesting use case for Salt SSH is automating the installation of
salt-minion using a simple Salt state.
Create the directory which will contain your state:
[root@master ~]# mkdir /srv/salt/install_salt_minion
/srv/salt/install_salt_minion/init.slsfile and declare your state:
1 2 3 4 5 6 7 8 91011121314151617181920212223242526272829303132333435
# This is a state which will install salt-minion on your hosts using Salt SSH # It will install the SaltStack repo, install salt-minion from that repo, enable and start the salt-minion service and # declare master in /etc/salt/minion file salt-minion: # Install SaltStack repo for RHEL/Centos systems pkgrepo.managed: - name: salt-latest - humanname: SaltStack Latest Release Channel for RHEL/Centos $releasever - baseurl: https://repo.saltstack.com/yum/redhat/$releasever/$basearch/latest - gpgkey: https://repo.saltstack.com/yum/redhat/$releasever/$basearch/latest/SALTSTACK-GPG-KEY.pub - gpgcheck: 1 - enabled: 1 # Install the salt-minion package and all its dependencies. pkg: - installed # Require that SaltStack repo is set up before installing salt-minion. - require: - pkgrepo: salt-latest # Start and enable the salt-minion daemon. service: - running - enable: True # Require that the salt-minion package is installed before starting daemon - require: - pkg: salt-minion # Restart salt-minion daemon if /etc/salt/minion file is changed - watch: - file: /etc/salt/minion # Configure Salt master in conf file /etc/salt/minion: file.managed: # File will contain only one line - contents: - master: <IPADDRESS OR HOSTNAME>
To apply this state, run the following command:
[root@master salt]# salt-ssh linode2 state.apply install_salt_minion
Check that minion’s key is pending for acceptance by using the
[root@master salt]# salt-key -l un Unaccepted Keys: linode2
To complete the minion’s configuration, accept its public key:
[root@master salt]# salt-key -a linode2
Once the minion key is accepted, the minion is fully configured and ready for command execution.
This guide is published under a CC BY-ND 4.0 license.