Installation and configuration

Getting Salt

On most systems, SaltStack can be installed by the package system or by the bootstrap script detailed later. Salt is supported and easily installed on following platforms:

  • Arch Linux
  • Debian / Ubuntu
  • Fedora
  • FreeBSD
  • Gentoo
  • OpenBSD
  • OS X
  • RHEL / CentOS / Scientific Linux / Amazon Linux / Oracle Linux
  • Solaris
  • SUSE
  • Windows

Package installation

To install Salt using the package repository, you can read more information at https://repo.saltstack.com/.

To install Salt on Ubuntu, run the following command to import the SaltStack repository key:

wget -O - https://repo.saltstack.com/apt/ubuntu/16.04/amd64/latest/SALTSTACK-GPG-KEY.pub | sudo apt-key add -

Add the following line to /etc/apt/sources.list and update the package list.

deb http://repo.saltstack.com/apt/ubuntu/16.04/amd64/latest xenial main

Run apt-get update.

Install the Salt master, minion, or syndic from the repository with the apt- get command. These each will install one daemon, but more than one package name may be given at a time:

apt-get install salt-master
apt-get install salt-minion
apt-get install salt-ssh
apt-get install salt-syndic
apt-get install salt-cloud

(Upgrade only) Restart all upgraded services, for example:

sudo systemctl restart salt-minion

bootstrap-salt script

The Salt Bootstrap script allows for a user to install the Salt Minion or Master on a variety of system distributions and versions. This shell script known as bootstrap-salt. The script runs through a series of checks to determine the operating system type and version. It then installs the Salt binaries using the appropriate methods.

The Salt Bootstrap script installs the minimum number of packages required to run Salt. This means that in the event you run the bootstrap to install via package, Git will not be installed. Installing the minimum number of packages helps ensure the script stays as lightweight as possible, assuming the user will install any other required packages after the Salt binaries are present on the system.

The script source is available on GitHub salt-bootstrap repository.

Using wget to install your distribution’s stable packages:

wget -O install_salt.sh https://bootstrap.saltstack.com
sudo sh install_salt.sh

Using curl to install latest git:

curl -L https://bootstrap.saltstack.com -o install_salt.sh
sudo sh install_salt.sh git develop

Install a specific version from git using wget:

wget -O install_salt.sh https://bootstrap.saltstack.com
sudo sh install_salt.sh -P git v0.16.4

Source installation

Clone the repository using:

git clone https://github.com/saltstack/salt

Create a new virtualenv:

virtualenv /srv/salt/vevn

source /srv/salt/vevn/bin/activate

Install Salt (and dependencies) into the virtualenv:

pip install M2Crypto    # Don't install on Debian/Ubuntu (see below)
pip install pyzmq PyYAML pycrypto msgpack-python jinja2 psutil
pip install -e ./salt   # the path to the salt git clone from above

Debian and Ubuntu systems have modified openssl libraries and mandate that a patched version of M2Crypto be installed. This means that M2Crypto needs to be installed via apt:

apt-get install python-m2crypto

This also means that pulling in the M2Crypto installed using apt requires using --system-site-packages when creating the virtualenv.

If you’re using a platform other than Debian or Ubuntu, and you are installing M2Crypto via pip instead of a system package, then you will also need the gcc compiler.

Upgrading Salt

When upgrading Salt, the master(s) should always be upgraded first. Backward compatibility for minions running newer versions of salt than their masters is not guaranteed. Backward compatibility between new masters and old minions is preserved whenever possible. Generally, the only exception to this policy is in case of a security vulnerability.

After upgrade restart all upgraded services:

systemctl restart salt-minion

Network configuration

The Salt master communicates with the minions using an AES-encrypted ZeroMQ connection. This document outlines suggested firewall rules for allowing incoming connections to the master.

Salt master network ports

These communications are done over TCP ports 4505 and 4506, which need to be accessible on the master only. Example iptables configuration:

-A INPUT -m state --state new -m tcp -p tcp --dport 4505 -j ACCEPT
-A INPUT -m state --state new -m tcp -p tcp --dport 4506 -j ACCEPT

Minion configuration

Salt minion’s configuration is located at /etc/salt/minion and can be extended by adding configuration fragments to /etc/salt/minion.d/ directory.

Basic minion configuration

Open salt minion config and set master pamameter (CONFIG_HOST) to localhost and id to the full hostname of the node.

echo "id: <NODE_FQDN>" >> /etc/salt/minion.d/minion.conf
echo "master: <CONFIG_HOST>" >> /etc/salt/minion.d/minion.conf
service salt-minion restart

Minion troubleshooting

The nmap utility can also be used to check if these ports are open:

nmap -sS -q -p 4505-4506 <CONFIG_HOST>

Starting Nmap 6.40 ( http://nmap.org ) at 2013-12-29 19:44 CST
Nmap scan report for <CONFIG_HOST>
Host is up (0.0032s latency).
PORT     STATE  SERVICE
4505/tcp open   unknown
4506/tcp open   unknown
MAC Address: 00:11:22:AA:BB:CC (unknown)

Nmap done: 1 IP address (1 host up) scanned in 1.12 seconds

Lab: Install Salt master on Ubuntu

Examine the downloaded file install_salt.sh to ensure that it contains what you expect (bash script).

Use curl to install stable packages on cfg01 node.

The Ubuntu image already contains repository with latest package to install the salt master.

cfg01# apt-get install salt-master

Set the Salt minion configuration on cfg01 node.

cfg01# echo "id: cfg01.saltstack.local" >> /etc/salt/minion.d/minion.conf
cfg01# echo "master: 127.0.0.1" >> /etc/salt/minion.d/minion.conf
cfg01# service salt-minion restart

Confirm Salt minion on Salt master on cfg01 node by salt-key command.

cfg01# salt-key -a cfg01.saltstack.local

The following keys are going to be accepted:
Unaccepted Keys:
cfg01.saltstack.local
Proceed? [n/Y]
Key for minion cfg01.saltstack.local accepted.

The connection can be checked by issuing a test ping command from the master to minion.

cfg01# salt cfg01.saltstack.local test.ping
cfg01.saltstack.local:
    True

Start Salt minion configuration for fake svc01 node.

cfg01# mkdir -p /etc/salt/svc01/minion.d
cfg01# cp /etc/salt/minion /etc/salt/svc01/minion
cfg01# echo -e "id: svc01.saltstack.local\nmaster: 127.0.0.1\ntcp_pub_port: 4512\ntcp_pull_port: 4513" >> /etc/salt/svc01/minion.d/minion.conf
cfg01# salt-minion -c /etc/salt/svc01

Start Salt minion configuration for fake svc02 node.

cfg01# mkdir -p /etc/salt/svc02/minion.d
cfg01# cp /etc/salt/minion /etc/salt/svc02/minion
cfg01# echo -e "id: svc02.saltstack.local\nmaster: 127.0.0.1\ntcp_pub_port: 4522\ntcp_pull_port: 4523" >> /etc/salt/svc02/minion.d/minion.conf
cfg01# salt-minion -c /etc/salt/svc02

The training lab setup is complete and we can proceed Salt excution modules.