Learning SaltStack

Chapter 1. Diving In – Our First Salt Commands

Salt is more than just configuration management or remote execution. It is a powerful platform that not only gives you unique tools to manage your infrastructure, but also the power to create new tools to fit your infrastructure's unique needs. However, everything starts with the foundation of lightning-fast remote execution, so that's where we will start.

In this chapter, you will learn how to:

Install Salt
Configure the master and the minion
Connect the minion to the master
Run our first remote execution commands

This book assumes that you already have root access on a device with a common distribution of Linux installed. The machine used in the examples in this book is running Ubuntu 14.04, unless otherwise stated. Most examples should run on other major distributions, such as recent versions of Fedora, RHEL 6/7, or Arch Linux.

Installing Salt

The dependencies for running Salt at the time of writing are as follows:

Python 2 – Version 2.6 or greater (Salt is not Python 3-compatible)
Msgpack – python
YAML
Jinja2
MarkupSafe
ZeroMQ – Version 3.2.0 or greater
PyZMQ – Version 2.2.0 or greater
Tornado
PyCrypto
M2Crypto

The easiest way to ensure that the dependencies for Salt are met is to use system-specific package management systems, such as apt on Ubuntu systems, that will handle the dependency-resolution automatically. You can also use the Salt Bootstrap script to handle all of the system-specific commands for you. Salt Bootstrap is an open source project with the goal of creating a Bourne shell-compatible script that will install Salt on any compatible server. The project is managed and hosted by the SaltStack team. You can find more information at https://github.com/saltstack/salt-bootstrap.

We will explore each of these methods of installation in turn, on a few different platforms.

Installation with system packages (Ubuntu)

The latest release of Salt for Ubuntu is provided via the official SaltStack package repository at http://repo.saltstack.com.

First, you must add the official SaltStack GPG key so that the packages can be verified:

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

Now, you must open the file /etc/apt/sources.list and add the following line:

deb http://repo.saltstack.com/apt/ubuntu/14.04/amd64/latest trusty main

Save and close that file.

After you have added the repository, you must update the package management database, as follows:

# sudo apt-get update

You should then be able to install the Salt master and the Salt minion with the following command:

# sudo apt-get install salt-master salt-minion

Assuming there are no errors after running this command, you should be done! Salt is now installed on your machine.

Note that we have installed both the Salt master and the Salt minion. The term master refers to the central server—the server from which we will be controlling all of our other servers. The term minion refers to the servers connected to and controlled by a master.

Installation with system packages (CentOS 6)

The latest release of Salt for RedHat/CentOS systems is also provided via the official SaltStack package repository at http://repo.saltstack.com.

You can set up both the repository and the keys required with a single command:

# sudo rpm -ivh https://repo.saltstack.com/yum/redhat/salt-repo-2015.8.el6.noarch.rpm

Make sure that the caches are clean with the following command:

# sudo yum clean expire-cache

Then, install the Salt master and Salt minion with the following commands:

# sudo yum install salt-master
# sudo yum install salt-minion

Assuming that there are no errors after running this command, you should be done! Salt is now installed on your machine.

As with Ubuntu, we installed both the Salt master and the Salt minion. The term master refers to the central server—the server from which we will be controlling all of our other servers. The term minion refers to the servers connected to and controlled by a master.

Installation with system packages (Windows)

The latest release of Salt for Windows systems is also provided via official packages from SaltStack. However, because Windows doesn't currently have a built-in package manager, the process is more manual. You download the installer and then run it like you would install most other software on Windows.

Start by going to the Windows section of the SaltStack repo: http://repo.saltstack.com/#windows.

Here, you'll see links to the x86 and AMD64 versions of the Salt minion for Windows:

Installation with system packages (Windows)

For most setups, you'll want the 64-bit version, highlighted in the preceding image. When you download and run that file, you'll see the following screen:

Continue the installation process by clicking Next and agreeing to the license agreement.

You'll then be shown a configuration page:

Here, you can enter the hostname or IP address of your Salt master, so the minion knows where to connect. You'll also have the option of setting the ID of the minion. Set it to something that describes the purpose of the minion so that when you have many minions, you'll be able to tell each of them apart. Then, click Install.

Once the installation completes, you'll have the option of starting the minion. Leave this box checked and click Finish:

You are done! Salt is now installed on your machine.

Note that the Salt master is not supported on Windows machines, so we only installed the Salt minion on this machine.

Installing with Salt Bootstrap

Information about manual installation on other major Linux distributions can be found online at http://docs.saltstack.com. However, in most cases, it is easier and more straightforward to use the Salt Bootstrap script. In-depth documentation can be found on the project page at https://github.com/saltstack/salt-bootstrap; however, the tool is actually quite easy to use, as follows:

# curl -L https://bootstrap.saltstack.com -o install_salt.sh
# sudo sh install_salt.sh -h

We won't include the help text for Salt Bootstrap here as it would take up too much space. However, it should be noted that, by default, Salt Bootstrap will only install the Salt minion. We want both the Salt minion and the Salt master, which can be accomplished by passing in the -M flag. We also want to pass in the -P flag to allow bootstrap to install Tornado using pip:

# sudo sh install_salt.sh -M -P

The preceding command will result in a fully functional installation of Salt on your machine! The supported operating system list is extensive, as shown in the salt-bootstrap documentation at https://github.com/saltstack/salt-bootstrap.

Note

The version of Salt used for the examples in this book is the 2015.8 release. Here is the full version information:

# sudo salt --versions-report
Salt Version:
           Salt: 2015.8.5

Dependency Versions:
         Jinja2: 2.7.2
       M2Crypto: Not Installed
           Mako: 0.9.1
         PyYAML: 3.10
          PyZMQ: 14.0.1
         Python: 2.7.6 (default, Mar 22 2014, 22:59:56)
           RAET: Not Installed
        Tornado: 4.2.1
            ZMQ: 4.0.4
           cffi: Not Installed
       cherrypy: Not Installed
       dateutil: 1.5
          gitdb: 0.5.4
      gitpython: 0.3.2 RC1
          ioflo: Not Installed
        libgit2: Not Installed
        libnacl: Not Installed
   msgpack-pure: Not Installed
 msgpack-python: 0.3.0
   mysql-python: 1.2.3
      pycparser: Not Installed
       pycrypto: 2.6.1
         pygit2: Not Installed
   python-gnupg: Not Installed
          smmap: 0.8.2
        timelib: Not Installed

System Versions:
           dist: Ubuntu 14.04 trusty
        machine: x86_64
        release: 3.13.0-46-generic
         system: Ubuntu 14.04 trusty

It's probable that the version of Salt you installed is a newer release and might have slightly different output. However, the examples should still all work in the latest version of Salt.

Configuring Salt

Now that we have the master and the minion installed on our machine, we must do a couple of pieces of configuration in order to allow them to talk to each other. From here on out, we're back to using a single Ubuntu 14.04 machine with both master and minion installed on the machine.

Firewall configuration

Since minions connect to masters, the only firewall configuration that must be done is on the master. By default, ports 4505 and 4506 must be able to accept incoming connections on the master. The default install of Ubuntu 14.04, used for these examples, actually requires no out-of-the-box firewall configuration to be able to run Salt; the ports required are already open. However, many distributions of Linux come with much more restrictive default firewall settings. The most common firewall software in use on Linux systems is iptables.

Tip

Note that you might also have to change firewall settings on your network hardware if there is network filtering in place outside the software on the machine on which you're working.

Firewall configuration is a topic that deserves its own book. However, our needs for the configuration of Salt are fairly simple. First, you must find the set of rules currently in effect for your system. This varies from system to system; for example, the file is located in /etc/sysconfig/iptables on RedHat distributions, while it is located at /etc/iptables/iptables.rules in Arch Linux.

Once you find that file, add the following lines to that file, but be sure to do it above the line that says DROP:

-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

For more information about configuring on your operating system of choice so that your Salt minion can connect successfully to your Salt master, see the Salt documentation at http://docs.saltstack.com/en/latest/topics/tutorials/firewall.html.

Salt minion configuration

Out of the box, the Salt minion is configured to connect to a master at the location salt. The reason for this default is that, if DNS is configured correctly such that salt resolves to the master's IP address, no further configuration is needed. The minion will connect successfully to the master.

However, in our example, we do not have any DNS configuration in place, so we must configure it ourselves.

The minion and master configuration files are located in the /etc/salt/ directory.

Tip

The /etc/salt/ directory should be created as part of the installation of Salt, assuming that you followed the preceding directions. If it does not exist for some reason, please create the directory and create two files, minion and master, within the directory.

Open the /etc/salt/minion file with your text editor of choice (remember to use the sudo command!). We will be making a couple of changes to this file.

First, find the commented-out line for the configuration option master. It should look like this:

#master:    salt

Uncomment that line and change salt to localhost (as we have this minion connected to the local master). It should look like this:

master: localhost

If you cannot find the appropriate line in the file, just add the line shown previously to the top of the file.

You should also manually configure the minion ID so that you can more easily follow along with the examples in this text. Find the ID line:

#id:

Uncomment it and set it to myminion:

id: myminion

Again, if you cannot find the appropriate line in the file, just add the line shown previously to the top of the file.

Save and close the file.

Note

Without a manually specified minion ID, the minion will try to intelligently guess what its minion ID should be at startup. For most systems, this will mean that the minion ID will be set to the Fully Qualified Domain Name (FQDN) for the system.

Starting the Salt master and Salt minion

Now we need to start (or restart) our Salt master and Salt minion. Assuming that you're following along on Ubuntu (which I recommend), you can use the following commands:

# sudo service salt-minion restart
# sudo service salt-master restart

Packages in other supported distributions ship with init scripts for Salt. Use whichever service system is available to you to start or restart the Salt minion and Salt master.

Accepting the minion key on the master

There is one last step remaining before we can run our first Salt commands. We must tell the master that it can trust the minion. To help us with this, Salt comes with the salt-key command to help us manage minion keys:

# sudo salt-key
Accepted Keys:
Denied Keys:
Unaccepted Keys:
myminion
Rejected Keys:

Tip

Note that our minion, myminion, is listed in the Unaccepted Keys section. This means that the minion has contacted the master and the master has cached that minion's public key, and is waiting for further instructions as to whether to accept the minion or not.

If your minion is not showing up in the output of salt-key, it's possible that the minion cannot reach the master on ports 4505 and 4506. Please refer to the Firewall configuration section described previously for more information.

Troubleshooting information can also be found in the Salt documentation at http://docs.saltstack.com/en/latest/topics/troubleshooting/.

We can inspect the key's fingerprint to ensure that it matches our minion's key, as follows:

# sudo salt-key -f myminion
Unaccepted Keys:
myminion:  a8:1f:b0:c2:ab:9d:27:13:60:c9:81:b1:11:a3:68:e1

We can use the salt-call command to run a command on the minion to obtain the minion's key, as follows:

# sudo salt-call --local key.finger
local:    a8:1f:b0:c2:ab:9d:27:13:60:c9:81:b1:11:a3:68:e1

Since the fingerprints match, we can accept the key on the master, as follows:

# sudo salt-key -a myminion
The following keys are going to be accepted:
Unaccepted Keys:
myminion
Proceed? [n/Y] Y
Key for minion myminion accepted.

We can check that the minion key was accepted, as follows:

# sudo salt-key
Accepted Keys:
myminion
Denied Keys:
Unaccepted Keys:
Rejected Keys:

Success! We are ready to run our first Salt command!

A game of ping pong

Here's our first command:

# sudo salt '*' test.ping
myminion:
    True

Was that a bit underwhelming?

Don't worry. We're going to get to the more impressive stuff soon enough. The command we just ran was a remote execution command. Basically, we sent a message to all (one) of our minions and told them to run a function from one of the execution modules that is built into Salt. In this case, we just told our minion to return True. It's a good way to check which of our minions are alive. We will explore the various parts of this command in more detail in the next chapter.

The test module actually has a few other useful functions. To find out about them, we're actually going to use another module, sys, as follows:

# sudo salt 'myminion' sys.list_functions test
myminion:
    - test.arg
    - test.arg_repr
    - test.arg_type
    - test.collatz
    - test.conf_test
    - test.cross_test
    - test.echo
    - test.exception
    - test.fib
    - test.get_opts
    - test.kwarg
    - test.not_loaded
    - test.opts_pkg
    - test.outputter
    - test.ping
    - test.provider
    - test.providers
    - test.rand_sleep
    - test.rand_str
    - test.retcode
    - test.sleep
    - test.stack
    - test.tty
    - test.version
    - test.versions_information
    - test.versions_report

Let's try one of the other functions on the list, maybe test.fib:

# sudo salt '*' test.fib
myminion:
    Passed invalid arguments to test.fib: fib() takes exactly 1 argument (0 given)

Well, that didn't work. To find out more information about a function, including examples of how to use it, we can use the sys.doc function, as follows:

# sudo salt '*' sys.doc test.fib
test.fib:

    Return a Fibonacci sequence up to the passed number, and the
    timeit took to compute in seconds. Used for performance tests

    CLI Example:

    salt '*' test.fib 3

Note

In recent versions of salt, the docs for a function are returned along with the error by default. However, sys.doc is still useful for discovering docs even without errors, which is why this example is still relevant.

Aha! We need to give it a number to which it should calculate the fibonacci sequence, as follows:

# sudo salt '*' test.fib 30
myminion:
    |_
      - 0
      - 1
      - 1
      - 2
      - 3
      - 5
      - 8
      - 13
      - 21
    - 1.09672546387e-05

As it turns out, the fibonacci sequence is not very hard for computers to calculate quickly.

Tip

Note that you can actually use sys.doc to retrieve the documentation for a whole module's worth of functions at a time, as follows:

# sudo salt '*' sys.doc test

I didn't include the output as it is lengthy.

The sys module is going to be one of the most useful modules in your quest to learn Salt. Keep it handy and turn to it any time you want to learn more about something you're working with. Remember that the sys module can target itself. The following code shows you how to use the sys module:

# sudo salt '*' sys.list_functions sys
myminion:
    - sys.argspec
    - sys.doc
    - sys.list_functions
    - sys.list_modules
    - sys.list_renderers
    - sys.list_returner_functions
    - sys.list_returners
    - sys.list_runner_functions
    - sys.list_runners
    - sys.list_state_functions
    - sys.list_state_modules
    - sys.reload_modules
    - sys.renderer_doc
    - sys.returner_argspec
    - sys.returner_doc
    - sys.runner_argspec
    - sys.runner_doc
    - sys.state_argspec
    - sys.state_doc

We are going to discuss remote execution and the execution modules in much greater detail in the next chapter.

Masterless Salt

In this chapter, we've taken the time to set up Salt in a master-minion relationship. This will allow us to take advantage of all the power of Salt and scale to multiple minions easily later on. However, Salt is also designed so that a minion can run without a master.

We'll run through a few examples of how to run commands on a minion. This will also be useful even when we do have a master because if we're logged into a minion for some reason and want to run a command while we're there, we can do so using these same concepts.

To start, we'll leave our master running. The command used to run commands on the minion is salt-call, and it can take any of the same execution module functions that we used with the salt command, as follows:

# sudo salt-call test.ping
local:
    True

Note that it doesn't display our minion's ID because we're just running it locally:

# sudo salt-call test.fib 10
local:
    |_
      - 0
      - 1
      - 1
      - 2
      - 3
      - 5
      - 8
    - 5.00679016113e-06
# sudo salt-call sys.doc test.ping
local:
    ----------
    test.ping:

            Used to make sure the minion is up and responding. Not
            an ICMP ping.

            Returns ``True``.

            CLI Example:

                salt '*' test.ping

Now, let's stop our master and try again:

# sudo service salt-master stop
# sudo salt-call test.ping
Failed sign in

The example shown previously will take a fairly long time to terminate. Basically, salt-call is trying to establish a connection with the master just in case it needs to copy files from the master or other similar operations.

In order for salt-call to operate properly without a master, we need to tell it that there's no master. We do this with the --local flag, as follows:

# sudo salt-call --local test.ping
local:
    True

Success! You can now operate a Salt minion without a master!

Tip

Start your master again before moving on to the next chapter of this book:

# sudo service salt-master start

CKH Aug 30, 2016

This is a well-written book with plenty of great examples! I discovered as I was reading and exploring the Salt ecosystem that the author is one of the leading contributors for Salt on GitHub, forums, etc. and it shows; Myers is in his element (pun intended) and the book reflects that.I read some other O'Reilly book before reading this one and understood Salt far better after reading this one. Myers takes you through core Salt functions from getting started with the Salt execution engine through States, the Salt Pillar, using Jinja, the Event system and Reactor. He also covers Salt Cloud, security & best practices and contributing to the project.My one request for the next edition is coverage of Beacons.

Amazon Verified review

Brian Adriance Sep 01, 2017

Very good introduction to SaltStack. It has a few extra good tidbits that i did not find in the docs (maybe it was there, just buried) or in the tutorial. I ended up getting my entire team to read this book as well.

nazareno Oct 12, 2017

It's rather basic, I am using it as a sort of reference. I was expecting to find something new in the new edition but it wasn't the case.

Mr Bill Feb 09, 2020

This is a good beginner book, but it's too short to complete its goal of getting you rolling with SaltStack. It needs to be about double the length, with more details and examples. It's enough to teach you what you don't know, and then you need to google it from there. I don't regret buying this book, but I did need to follow this one up with Mastering SaltStack.

trudesea Nov 13, 2017

Was disappointed that 90% of the material in this book is available in the online documentation and tutorials.. Hoped that there would be some fresh information or different points of view on how to do things, but most info looks like a copy/paste from the freely available docs/tutorials.