# salt.states.saltmod

## Control the Salt command interface

This state is intended for use from the Salt Master. It provides access to sending commands down to minions as well as access to executing master-side modules. These state functions wrap Salt's Python API.

> Added in version 2016.11.0.

> Support for masterless minions was added to the `salt.state` function, so they can run orchestration sls files. This is particularly useful when the rendering of a state is dependent on the execution of another state. Orchestration will render and execute each orchestration block independently, while honoring requisites to ensure the states are applied in the correct order.

See also

More Orchestrate documentation

- Full Orchestrate Tutorial

- `The Orchestrate runner`

salt.states.saltmod.function(name, tgt, ssh=False, tgt_type='glob', ret='', ret_config=None, ret_kwargs=None, expect_minions=False, fail_minions=None, fail_function=None, arg=None, kwarg=None, timeout=None, batch=None, subset=None, failhard=None, **kwargs)

  Execute a single module function on a remote minion via salt or salt-ssh

  name

    The name of the function to run, aka cmd.run or pkg.install

  tgt

    The target specification, aka '*' for all minions

  tgt_type

    The target type, defaults to `glob`

  arg

    The list of arguments to pass into the function

  kwarg

    The dict (not a list) of keyword arguments to pass into the function

  ret

    Optionally set a single or a list of returners to use

  ret_config

    Use an alternative returner configuration

  ret_kwargs

    Override individual returner configuration items

  expect_minions

    An optional boolean for failing if some minions do not respond

  fail_minions

    An optional list of targeted minions where failure is an option

  fail_function

    An optional string that points to a salt module that returns True or False based on the returned data dict for individual minions

  ssh

    Set to True to use the ssh client instead of the standard salt client

  roster

    In the event of using salt-ssh, a roster system can be set

    Added in version 3005.

  batch

    Execute the command in batches. E.g.: `10%`.

  subset

    Number of minions from the targeted set to randomly use

    Added in version 2017.7.0.

  failhard

    pass failhard down to the executing state

    Added in version 2019.2.2.

salt.states.saltmod.parallel_runners(name, runners, **kwargs)

  Executes multiple runner modules on the master in parallel.

  Added in version 2018.3.0.

  A separate thread is spawned for each runner. This state is intended to be used with the orchestrate runner in place of the `saltmod.runner` state when different tasks should be run in parallel. In general, Salt states are not safe when used concurrently, so ensure that they are used in a safe way (e.g. by only targeting separate minions in parallel tasks).

  name:

    name identifying this state. The name is provided as part of the output, but not used for anything else.

  runners:

    list of runners that should be run in parallel. Each element of the list has to be a dictionary. This dictionary's name entry stores the name of the runner function that shall be invoked. The optional kwarg entry stores a dictionary of named arguments that are passed to the runner function.

      parallel-state:
         salt.parallel_runners:
           - runners:
               my_runner_1:
                 - name: state.orchestrate
                 - kwarg:
                     mods: orchestrate_state_1
               my_runner_2:
                 - name: state.orchestrate
                 - kwarg:
                     mods: orchestrate_state_2

salt.states.saltmod.runner(name, **kwargs)

  Execute a runner module on the master

  Added in version 2014.7.0.

  name

    The name of the function to run

  kwargs

    Any keyword arguments to pass to the runner function

      run-manage-up:
       salt.runner:
         - name: manage.up

salt.states.saltmod.state(name, tgt, ssh=False, tgt_type='glob', ret='', ret_config=None, ret_kwargs=None, highstate=None, sls=None, top=None, saltenv=None, test=None, pillar=None, pillarenv=None, expect_minions=True, exclude=None, fail_minions=None, allow_fail=0, concurrent=False, timeout=None, batch=None, queue=False, subset=None, orchestration_jid=None, failhard=None, **kwargs)

  Invoke a state run on a given target

  name

    An arbitrary name used to track the state execution

  tgt

    The target specification for the state run.

    Added in version 2016.11.0.

    Masterless support: When running on a masterless minion, the `tgt` is ignored and will always be the local minion.

  tgt_type

    The target type to resolve, defaults to `glob`

  ret

    Optionally set a single or a list of returners to use

  ret_config

    Use an alternative returner configuration

  ret_kwargs

    Override individual returner configuration items

  highstate

    Defaults to None, if set to True the target systems will ignore any sls references specified in the sls option and call state.highstate on the targeted minions

  top

    Should be the name of a top file. If set state.top is called with this top file instead of state.sls.

  sls

    A group of sls files to execute. This can be defined as a single string containing a single sls file, or a list of sls files

  test

    Pass `test=true` or `test=false` through to the state function. This can be used to override a test mode set in the minion's config file. If left as the default of None and the 'test' mode is supplied on the command line, that value is passed instead.

  pillar

    Pass the `pillar` kwarg through to the state function

  pillarenv

    The pillar environment to grab pillars from

    Added in version 2017.7.0.

  saltenv

    The default salt environment to pull sls files from

  ssh

    Set to True to use the ssh client instead of the standard salt client

  roster

    In the event of using salt-ssh, a roster system can be set

  expect_minions

    An optional boolean for failing if some minions do not respond

  fail_minions

    An optional list of targeted minions where failure is an option

  allow_fail

    Pass in the number of minions to allow for failure before setting the result of the execution to False

  exclude

    Pass exclude kwarg to state

  concurrent

    Allow multiple state runs to occur at once.

    WARNING: This flag is potentially dangerous. It is designed for use when multiple state runs can safely be run at the same Do not use this flag for performance optimization.

  queue

    Pass `queue=true` through to the state function

  batch

    Execute the command in batches. E.g.: `10%`.

    Added in version 2016.3.0.

  subset

    Number of minions from the targeted set to randomly use

    Added in version 2017.7.0.

  failhard

    pass failhard down to the executing state

    Added in version 2019.2.2.

  Examples:

  Run a list of sls files via `state.sls` on target minions:

      webservers:
        salt.state:
          - tgt: 'web*'
          - sls:
            - apache
            - django
            - core
          - saltenv: prod

  Run sls file via `state.sls` on target minions with exclude:

      docker:
        salt.state:
          - tgt: 'docker*'
          - sls: docker
          - exclude: docker.swarm
          - saltenv: prod

  Run a full `state.highstate` on target mininons.

      databases:
        salt.state:
          - tgt: role:database
          - tgt_type: grain
          - highstate: True

salt.states.saltmod.wait_for_event(name, id_list, event_id='id', timeout=300, node='master')

  Watch Salt's event bus and block until a condition is met

  Added in version 2014.7.0.

  name

    An event tag to watch for; supports Reactor-style globbing.

  id_list

    A list of event identifiers to watch for -- usually the minion ID. Each time an event tag is matched the event data is inspected for `event_id`, if found it is removed from `id_list`. When `id_list` is empty this function returns success.

  event_idid

    The name of a key in the event data. Default is `id` for the minion ID, another common value is `name` for use with orchestrating salt-cloud events.

  timeout300

    The maximum time in seconds to wait before failing.

  The following example blocks until all the listed minions complete a restart and reconnect to the Salt master:

      reboot_all_minions:
        salt.function:
          - name: system.reboot
          - tgt: '*'

      wait_for_reboots:
        salt.wait_for_event:
          - name: salt/minion/*/start
          - id_list:
            - jerry
            - stuart
            - dave
            - phil
            - kevin
            - mike
          - require:
            - salt: reboot_all_minions

salt.states.saltmod.wheel(name, **kwargs)

  Execute a wheel module on the master

  Added in version 2014.7.0.

  name

    The name of the function to run

  kwargs

    Any keyword arguments to pass to the wheel function

      accept_minion_key:
        salt.wheel:
          - name: key.accept
          - match: frank