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]
Conditions for targetting minions upon to perform function
A function is some functionality provided by an execution module
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 '*'
salt '*'

Many ways to target

Targets can be explicitly specified in a list:

salt -L 'foo,bar,baz,quo'

Targets can be filtered by regular expression:

salt -E 'svc0[0-9]'

Grains of Salt

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

salt -G 'os:Ubuntu'

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'

Compound logical targets

Or Multiple target types can be combined in one command:

salt -C '[email protected]:Ubuntu and minion* or [email protected]*'

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

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
        - fpu
        - vme
        - de
        - pse
        - tsc
        - msr
        - pae

Return one or more specific grain informations:

svc01# salt-call grains.item ipv4 os_family

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

svc01# salt-call pkg.refresh_db
    ---------- trusty InRelease:
        True trusty/extra Translation-en:
        False trusty/extra amd64 Packages:

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

svc01# salt-call pkg.install nmap

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

cfg01# salt 'minion*' pillar.items

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.


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.

[email protected]:~# 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
[email protected]:~# salt-cp 'svc0[0-9].*' /root/test.file /root
{'svc01.saltstack.local': {'/root/test.file': True},
 'svc02.saltstack.local': {'/root/test.file': True}}