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.