Python client API

Salt is written to be completely API centric, Salt minions and master can be built directly into third party applications as a communication layer. The Salt client API is very straightforward.

A number of client command methods are available depending on the exact behavior desired.

LocalClient

class salt.client.LocalClient(c_path='/etc/salt/master', mopts=None)

LocalClient is the same interface used by the salt command-line tool on the Salt Master. LocalClient is used to send a command to Salt minions to execute execution modules and return the results to the Salt Master.

Importing and using LocalClient must be done on the same machine as the Salt Master and it must be done using the same user that the Salt Master is running as (unless external_auth is configured and authentication credentials are included in the execution.

cmd(tgt, fun, arg=(), timeout=None, expr_form='glob', ret='', kwarg=None, **kwargs)

The cmd method will execute and wait for the timeout period for all minions to reply, then it will return all minion data at once.

Usage:

import salt.client
client = salt.client.LocalClient()
ret = client.cmd('*', 'cmd.run', ['whoami'])

With authentication:

# Master config
...
external_auth:
  pam:
    fred:
      - test.*
...
ret = client.cmd('*', 'test.ping', [], username='fred', password='pw', eauth='pam')

Compound command usage:

ret = client.cmd('*', ['grains.items', 'cmd.run'], [[], ['whoami']])
Parameters:
  • tgt (string or list) -- Which minions to target for the execution. Default is shell glob. Modified by the expr_form option.
  • fun (string or list of strings) --

    The module and function to call on the specified minions of the form module.function. For example test.ping or grains.items.

    Compound commands
    Multiple functions may be called in a single publish by passing a list of commands. This can dramatically lower overhead and speed up the application communicating with Salt.

    This requires that the arg param is a list of lists. The fun list and the arg list must correlate by index meaning a function that does not take arguments must still have a corresponding empty list at the expected index.

  • arg (list or list-of-lists) -- A list of arguments to pass to the remote function. If the function takes no arguments arg may be omitted except when executing a compound command.
  • timeout -- Seconds to wait after the last minion returns but before all minions return.
  • expr_form --

    The type of tgt. Allowed values:

    • glob - Bash glob completion - Default
    • pcre - Perl style regular expression
    • list - Python list of hosts
    • grain - Match based on a grain comparison
    • grain_pcre - Grain comparison with a regex
    • pillar - Pillar data comparison
    • nodegroup - Match on nodegroup
    • range - Use a Range server for matching
    • compound - Pass a compound match string
  • ret -- The returner to use. The value passed can be single returner, or a comma delimited list of returners to call in order on the minions
  • kwargs --

    Optional keyword arguments.

    Authentication credentials may be passed when using external_auth.

    • eauth - the external_auth backend
    • username and password
    • token
Returns:

A dictionary with the result of the execution, keyed by minion ID. A compound command will return a sub-dictionary keyed by function name.

cmd_async(tgt, fun, arg=(), expr_form='glob', ret='', kwarg=None, **kwargs)

Execute a command and get back the jid, don't wait for anything

The function signature is the same as cmd() with the following exceptions.

Returns:A job ID
cmd_cli(tgt, fun, arg=(), timeout=None, expr_form='glob', ret='', verbose=False, kwarg=None, **kwargs)

Used by the salt CLI. This method returns minion returns as the come back and attempts to block until all minions return.

The function signature is the same as cmd() with the following exceptions.

Parameters:verbose -- Print extra information about the running command
Returns:A generator
cmd_iter(tgt, fun, arg=(), timeout=None, expr_form='glob', ret='', kwarg=None, **kwargs)

Yields the individual minion returns as they come in

The function signature is the same as cmd() with the following exceptions.

cmd_iter_no_block(tgt, fun, arg=(), timeout=None, expr_form='glob', ret='', kwarg=None, **kwargs)

Blocks while waiting for individual minions to return.

The function signature is the same as cmd() with the following exceptions.

Returns:None until the next minion returns. This allows for actions to be injected in between minion returns.

Salt Caller

class salt.client.Caller(c_path='/etc/salt/minion')

Caller is the same interface used by the salt-call command-line tool on the Salt Minion.

Importing and using LocalClient must be done on the same machine as a Salt Minion and it must be done using the same user that the Salt Minion is running as.

Usage:

import salt.client
caller = salt.client.Caller()
caller.function('test.ping')

# Or call objects directly
caller.sminion.functions['cmd.run']('ls -l')
function(fun, *args, **kwargs)

Call a single salt function

RunnerClient

class salt.runner.RunnerClient(opts)

RunnerClient is the same interface used by the salt-run command-line tool on the Salt Master. It executes runner modules which run on the Salt Master.

Importing and using RunnerClient must be done on the same machine as the Salt Master and it must be done using the same user that the Salt Master is running as.

cmd(fun, arg, kwarg=None)

Execute a runner with the given arguments

low(fun, low)

Pass in the runner function name and the low data structure

WheelClient

class salt.wheel.Wheel(opts)

WheelClient is an interface to Salt's wheel modules. Wheel modules interact with various parts of the Salt Master.

Importing and using WheelClient must be done on the same machine as the Salt Master and it must be done using the same user that the Salt Master is running as.

call_func(fun, **kwargs)

Execute a master control function

master_call(**kwargs)

Send a function call to a wheel module through the master network interface Expects that one of the kwargs is key 'fun' whose value is the namestring of the function to call