The command-line¶

Salt allows for commands to be executed across a swath of remote systems in parallel. This means that remote systems can be both controlled and queried with ease.

Command structure¶

Commands are performed on the minions via the salt command. Salt command calls are comprised of three main components:

salt '<target>' <function> [arguments]

Target: Conditions for targetting minions upon to perform function
Function: A function is some functionality provided by an execution module
Arguments: Space-delimited arguments to the function

Targeting minions¶

SaltStack provides a powerful targeting system to help you find and filter systems based on static and custom data. The default filter is a glob on the minion id. For example:

salt '*' test.ping
salt '*.example.org' test.ping

Many ways to target¶

Targets can be explicitly specified in a list:

salt -L 'foo,bar,baz,quo' test.ping

Targets can be filtered by regular expression:

salt -E 'svc0[0-9]' test.ping

Grains of Salt¶

Targets can be based on Salt minion system information using the Grains system:

salt -G 'os:Ubuntu' test.ping

Because grains can be set by users that have access to the minion configuration files on the local system, grains are considered less secure than other identifiers in Salt. Use caution when targeting sensitive operations or setting pillar values based on grain data.

When possible, you should target sensitive operations and data using the Minion ID. If the Minion ID of a system changes, the Salt Minion’s public key must be re-accepted by an administrator on the Salt Master, making it less vulnerable to impersonation attacks.

Pillars of Salt¶

Targets can be explicitly specified by pillar:

salt -I 'somekey:specialvalue' test.ping

Compound logical targets¶

Or Multiple target types can be combined in one command:

salt -C 'G@os:Ubuntu and minion* or S@192.168.50.*' test.ping

Don’t worry too much about every targeting methods just yet. Just be confident that the targeting mechanism has enough flexibility to find the systems that you want to manage. Hopefully you’ve got a good understanding of how execution modules are used from the command line, and how to filter Salt minions using targets.

Changing output formats¶

You can set in Salt master or minion configuration:

state_verbose: False

The output to one line per state use following configuration:

state_output: terse

Or use it directly in command-line. The output is one line per state with more detailed error messages:

salt --state-output=mixed '*' test.version

Batch size¶

The -b (or --batch-size) option allows commands to be executed on only a specified number of minions at a time. Both percentages and numbers are supported.

salt '*' -b 10 test.ping

salt -G 'os:RedHat' --batch-size 25% apache.signal restart

Calling modules locally on a minion¶

The salt-call command is used to run module functions locally on a minion instead of executing them from the master. Salt-call is used to run a Standalone minion, and was originally created for troubleshooting.

salt-call <function> [arguments]

The Salt master is contacted to retrieve state files and other resources during execution unless the --local option is specified. salt-call commands execute from the current user’s shell context, while salt commands execute from the system’s default context.

Lab: Calling Salt functions¶

The salt-call command is used to run module functions locally on a minion. Try execute following execution modules.

Return all of the minion’s grains:

svc01# salt-call grains.items
local:
    ----------
    SSDs:
    biosreleasedate:
        04/01/2014
    biosversion:
        1.7.5-20150310_111955-batsu
    cpu_flags:
        - fpu
        - vme
        - de
        - pse
        - tsc
        - msr
        - pae
...

Return one or more specific grain informations:

svc01# salt-call grains.item ipv4 os_family
local:
    ----------
    ipv4:
        - 127.0.0.1
        - 172.10.10.100
    os_family:
        Debian

Updates the apt database to latest packages based upon repositories on Debian systems.

svc01# salt-call pkg.refresh_db
local:
    ----------
    http://apt.tcpcloud.eu trusty InRelease:
        True
    http://apt.tcpcloud.eu trusty/extra Translation-en:
        False
    http://apt.tcpcloud.eu trusty/extra amd64 Packages:

Install the passed package, add refresh=True to update the dpkg database.

svc01# salt-call pkg.install nmap
local:
    ----------
    ndiff:
        ----------
        new:
            1
        old:
    nmap:
        ----------
        new:
            6.40-0.2ubuntu1
        old:

The pillar.items call the master for a fresh pillar and generates the pillar data on the fly.

cfg01# salt 'minion*' pillar.items
svc01.saltstack.local:
----------
svc02.saltstack.local:
----------

Lab: Running standalone states¶

By default the file_client is set to remote so that the minion gathers file server and pillar data from the salt master. When setting the file_client option to local the minion is configured to not gather this data from the master.

file_client: local

Configuration which resided in the master configuration (e.g. /etc/salt/master) should be moved to the minion configuration since the minion does not read the master configuration.

Note

When running Salt in masterless mode, do not run the salt-minion daemon. Otherwise, it will attempt to connect to a master and fail. The salt-call command stands on its own and does not need the salt-minion daemon.

Run the webserver state on the cfg01 node.

root@cfg01:~# salt-call --local state.sls webserver
[INFO    ] Loading fresh modules for state activity
[INFO    ] Fetching file from saltenv 'base', ** skipped ** latest already in cache u'salt://webserver.sls'
[INFO    ] Running state [apache] at time 14:57:03.723333
[INFO    ] Executing state pkg.installed for apache
[INFO    ] Executing command ['dpkg-query', '--showformat', '${Status} ${Package} ${Version} ${Architecture}\n', '-W'] in directory '/root'
[INFO    ] Executing command 'apt-get -q update' in directory '/root'

Lab: File management¶

Salt comes with a simple file server suitable for distributing files to the Salt minions. The file server is a stateless ZeroMQ server that is built into the Salt master.

In this exercise, a file will be copied from master to all Linux minions.

cfg01# echo "test" > /root/test.file
root@cfg01:~# salt-cp 'svc0[0-9].*' /root/test.file /root
{'svc01.saltstack.local': {'/root/test.file': True},
 'svc02.saltstack.local': {'/root/test.file': True}}