# salt.runners.state

Execute orchestration functions

salt.runners.state.event(tagmatch='*', count=-1, quiet=False, sock_dir=None, pretty=False, node='master')

  Watch Salt's event bus and block until the given tag is matched

  Added in version 2014.7.0.

  Changed in version 2019.2.0: `tagmatch` can now be either a glob or regular expression.

  This is useful for utilizing Salt's event bus from shell scripts or for taking simple actions directly from the CLI.

  Enable debug logging to see ignored events.

  Parameters:

    - tagmatch -- the event is written to stdout for each tag that matches this glob or regular expression.

    - count -- this number is decremented for each event that matches the `tagmatch` parameter; pass `-1` to listen forever.

    - quiet -- do not print to stdout; just block

    - sock_dir -- path to the Salt master's event socket file.

    - pretty -- Output the JSON all on a single line if `False` (useful for shell tools); pretty-print the JSON output if `True`.

    - node -- Watch the minion-side or master-side event bus. .. versionadded:: 2016.3.0

  CLI Examples:

      # Reboot a minion and run highstate when it comes back online
      salt 'jerry' system.reboot && \\
          salt-run state.event 'salt/minion/jerry/start' count=1 quiet=True && \\
          salt 'jerry' state.highstate

      # Reboot multiple minions and run highstate when all are back online
      salt -L 'kevin,stewart,dave' system.reboot && \\
          salt-run state.event 'salt/minion/*/start' count=3 quiet=True && \\
          salt -L 'kevin,stewart,dave' state.highstate

      # Watch the event bus forever in a shell while-loop.
      salt-run state.event | while read -r tag data; do
          echo $tag
          echo $data | jq --color-output .
      done

  See also

  See tests/eventlisten.sh for an example of usage within a shell script.

salt.runners.state.orch(mods, saltenv='base', test=None, exclude=None, pillar=None, pillarenv=None, pillar_enc=None, orchestration_jid=None)

  This function is an alias of `orchestrate`.

  Added in version 0.17.0.

  Execute a state run from the master, used as a powerful orchestration system.

  See also

  More Orchestrate documentation

  - Full Orchestrate Tutorial

  - `Docs for the master-side state module`

  CLI Examples:

      salt-run state.orchestrate webserver
      salt-run state.orchestrate webserver saltenv=dev test=True
      salt-run state.orchestrate webserver saltenv=dev pillarenv=aws

  Changed in version 2014.1.1: Runner renamed from `state.sls` to `state.orchestrate`

  Changed in version 2014.7.0: Runner uses the pillar variable

  Changed in version 2017.5.0: Runner uses the pillar_enc variable that allows renderers to render the pillar. This is usable when supplying the contents of a file as pillar, and the file contains gpg-encrypted entries.

  See also

  GPG renderer documentation

  CLI Examples:

      salt-run state.orchestrate webserver pillar_enc=gpg pillar="$(cat somefile.json)"

salt.runners.state.orch_show_sls(mods, saltenv='base', test=None, queue=False, pillar=None, pillarenv=None, pillar_enc=None)

  This function is an alias of `orchestrate_show_sls`.

  Display the state data from a specific sls, or list of sls files, after being render using the master minion.

  Note, the master minion adds a "_master" suffix to its minion id.

  See also

  The state.show_sls module function

  CLI Example:

      salt-run state.orch_show_sls my-orch-formula.my-orch-state 'pillar={ nodegroup: ng1 }'

salt.runners.state.orchestrate(mods, saltenv='base', test=None, exclude=None, pillar=None, pillarenv=None, pillar_enc=None, orchestration_jid=None)

  Added in version 0.17.0.

  Execute a state run from the master, used as a powerful orchestration system.

  See also

  More Orchestrate documentation

  - Full Orchestrate Tutorial

  - `Docs for the master-side state module`

  CLI Examples:

      salt-run state.orchestrate webserver
      salt-run state.orchestrate webserver saltenv=dev test=True
      salt-run state.orchestrate webserver saltenv=dev pillarenv=aws

  Changed in version 2014.1.1: Runner renamed from `state.sls` to `state.orchestrate`

  Changed in version 2014.7.0: Runner uses the pillar variable

  Changed in version 2017.5.0: Runner uses the pillar_enc variable that allows renderers to render the pillar. This is usable when supplying the contents of a file as pillar, and the file contains gpg-encrypted entries.

  See also

  GPG renderer documentation

  CLI Examples:

      salt-run state.orchestrate webserver pillar_enc=gpg pillar="$(cat somefile.json)"

salt.runners.state.orchestrate_high(data, test=None, queue=False, pillar=None, **kwargs)

  Execute a single state orchestration routine

  Added in version 2015.5.0.

  CLI Example:

      salt-run state.orchestrate_high '{
          stage_one:
              {salt.state: [{tgt: "db*"}, {sls: postgres_setup}]},
          stage_two:
              {salt.state: [{tgt: "web*"}, {sls: apache_setup}, {
                  require: [{salt: stage_one}],
              }]},
          }'

salt.runners.state.orchestrate_show_sls(mods, saltenv='base', test=None, queue=False, pillar=None, pillarenv=None, pillar_enc=None)

  Display the state data from a specific sls, or list of sls files, after being render using the master minion.

  Note, the master minion adds a "_master" suffix to its minion id.

  See also

  The state.show_sls module function

  CLI Example:

      salt-run state.orch_show_sls my-orch-formula.my-orch-state 'pillar={ nodegroup: ng1 }'

salt.runners.state.orchestrate_single(fun, name, test=None, queue=False, pillar=None, **kwargs)

  Execute a single state orchestration routine

  Added in version 2015.5.0.

  CLI Example:

      salt-run state.orchestrate_single fun=salt.wheel name=key.list_all

salt.runners.state.pause(jid, state_id=None, duration=None)

  Set up a state id pause, this instructs a running state to pause at a given state id. This needs to pass in the jid of the running state and can optionally pass in a duration in seconds.

salt.runners.state.resume(jid, state_id=None)

  Remove a pause from a jid, allowing it to continue

salt.runners.state.rm_pause(jid, state_id=None)

  This function is an alias of `resume`.

  Remove a pause from a jid, allowing it to continue

salt.runners.state.set_pause(jid, state_id=None, duration=None)

  This function is an alias of `pause`.

  Set up a state id pause, this instructs a running state to pause at a given state id. This needs to pass in the jid of the running state and can optionally pass in a duration in seconds.

salt.runners.state.sls(mods, saltenv='base', test=None, exclude=None, pillar=None, pillarenv=None, pillar_enc=None, orchestration_jid=None)

  This function is an alias of `orchestrate`.

  Added in version 0.17.0.

  Execute a state run from the master, used as a powerful orchestration system.

  See also

  More Orchestrate documentation

  - Full Orchestrate Tutorial

  - `Docs for the master-side state module`

  CLI Examples:

      salt-run state.orchestrate webserver
      salt-run state.orchestrate webserver saltenv=dev test=True
      salt-run state.orchestrate webserver saltenv=dev pillarenv=aws

  Changed in version 2014.1.1: Runner renamed from `state.sls` to `state.orchestrate`

  Changed in version 2014.7.0: Runner uses the pillar variable

  Changed in version 2017.5.0: Runner uses the pillar_enc variable that allows renderers to render the pillar. This is usable when supplying the contents of a file as pillar, and the file contains gpg-encrypted entries.

  See also

  GPG renderer documentation

  CLI Examples:

      salt-run state.orchestrate webserver pillar_enc=gpg pillar="$(cat somefile.json)"

salt.runners.state.soft_kill(jid, state_id=None)

  Set up a state run to die before executing the given state id, this instructs a running state to safely exit at a given state id. This needs to pass in the jid of the running state. If a state_id is not passed then the jid referenced will be safely exited at the beginning of the next state run.