# 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')

    With extra keyword arguments for the command function to be run:

        ret = client.cmd('*', 'test.arg', ['arg1', 'arg2'], kwarg={ 'foo': 'bar'})

    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 kwarg -- A dictionary with keyword arguments for the function. 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 `Caller` 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

Current Salt release: 0.17.1

### Table Of Contents

- Python client API
  - LocalClient
  - Salt Caller
  - RunnerClient
  - WheelClient

#### Previous topic

salt.output.yaml_out

#### Next topic

Peer Communication

### Quick search

Enter search terms or a module, class or function name.

### Upcoming SaltStack Events

My conferences on Lanyrd