salt.states.cmd

### Navigation

- index
- modules |
- next |
- previous |
- « SaltStack.org |
- Documentation home
- Full list of builtin state modules »

# salt.states.cmd

## Execution of arbitrary commands.

The cmd state module manages the enforcement of executed commands, this state can tell a command to run under certain circumstances.

### Available Functions

The cmd state only has a single function, the `run` function

run

  Execute a command given certain conditions

  A simple example:

      date > /tmp/salt-run:
      cmd:
          - run

Only run if another execution returns successfully, in this case truncate syslog if there is no disk space:

    > /var/log/messages:
      cmd.run:
        - unless: echo 'foo' > /tmp/.test

Note that when executing a command or script, the state(ie, changed or not) of the command is unknown to Salt's state system. Therefore, by default, the `cmd` state assumes that any command execution results in a changed state.

This means that if a `cmd` state is watched by another state then the state that's watching will always be executed due to the changed state in the `cmd` state.

Many state functions in this module now also accept a `stateful` argument. If `stateful` is specified to be true then it is assumed that the command or script will determine its own state and communicate it back by following a simple protocol described below:

> If there's nothing in the stdout of the command, then assume no changes. Otherwise, the stdout must be either in JSON or its last non-empty line must be a string of key=value pairs delimited by spaces(no spaces on the sides of `=`).

> If it's JSON then it must be a JSON object(ie, {}). If it's key=value pairs then quoting may be used to include spaces. (Python's shlex module is used to parse the key=value string)

> Two special keys or attributes are recognized in the output:

>     changed: bool (ie, 'yes', 'no', 'true', 'false', case-insensitive)
>     comment: str  (ie, any string)

> So, only if 'changed' is true then assume the command execution has changed the state, and any other key values or attributes in the output will be set as part of the changes.

> If there's a comment then it will be used as the comment of the state.

> Here's an example of how one might write a shell script for use with a stateful command:

>     #!/bin/bash
>     #
>     echo "Working hard..."

>     # writing the state line
>     echo  # an empty line here so the next line will be the last.
>     echo "changed=yes comment="something's changed!" whatever=123"

> And an example salt file using this module:

>     Run myscript:
>       cmd.run:
>         - name: /path/to/myscript
>         - cwd: /
>         - stateful: true

>     Run only if myscript changed something:
>       cmd.wait:
>         - name: echo hello
>         - cwd: /
>         - watch:
>           - cmd: Run myscript

> Note that if the `cmd.wait` state also specfies `stateful: true` it can then be watched by some other states as well.

`salt.states.cmd.` `mod_watch`(name, **kwargs)

  Execute a cmd function based on a watch call

`salt.states.cmd.` `run`(name, onlyif=None, unless=None, cwd='/root', user=None, group=None, shell=None, env=(), stateful=False, **kwargs)

  Run a command if certain circumstances are met

  name
    The command to execute, remember that the command will execute with the path and permissions of the salt-minion.
  onlyif
    A command to run as a check, run the named command only if the command passed to the `onlyif` option returns true
  unless
    A command to run as a check, only run the named command if the command passed to the `unless` option returns false
  cwd
    The current working directory to execute the command in, defaults to /root
  user
    The user name to run the command as
  group
    The group context to run the command as
  shell
    The shell to use for execution, defaults to the shell grain
  stateful
    The command being executed is expected to return data about executing a state

`salt.states.cmd.` `script`(name, source=None, template=None, onlyif=None, unless=None, cwd='/root', user=None, group=None, shell=None, env=None, stateful=False, **kwargs)

  Download a script from a remote source and execute it. The name can be the source or the source value can be defined.

  name
    The command to execute, remember that the command will execute with the path and permissions of the salt-minion.
  onlyif
    A command to run as a check, run the named command only if the command passed to the `onlyif` option returns true
  unless
    A command to run as a check, only run the named command if the command passed to the `unless` option returns false
  cwd
    The current working directory to execute the command in, defaults to /root
  user
    The user name to run the command as
  group
    The group context to run the command as
  shell
    The shell to use for execution, defaults to the shell grain
  stateful
    The command being executed is expected to return data about executing a state

`salt.states.cmd.` `wait`(name, onlyif=None, unless=None, cwd='/root', user=None, group=None, shell=None, stateful=False, **kwargs)

  Run the given command only if the watch statement calls it

  name
    The command to execute, remember that the command will execute with the path and permissions of the salt-minion.
  onlyif
    A command to run as a check, run the named command only if the command passed to the `onlyif` option returns true
  unless
    A command to run as a check, only run the named command if the command passed to the `unless` option returns false
  cwd
    The current working directory to execute the command in, defaults to /root
  user
    The user name to run the command as
  group
    The group context to run the command as
  shell
    The shell to use for execution, defaults to /bin/sh

`salt.states.cmd.` `wait_script`(name, source=None, template=None, onlyif=None, unless=None, cwd='/root', user=None, group=None, shell=None, env=None, stateful=False, **kwargs)

  Download a script from a remote source and execute it only if a watch statement calls it.

  name
    The command to execute, remember that the command will execute with the path and permissions of the salt-minion.
  onlyif
    A command to run as a check, run the named command only if the command passed to the `onlyif` option returns true
  unless
    A command to run as a check, only run the named command if the command passed to the `unless` option returns false
  cwd
    The current working directory to execute the command in, defaults to /root
  user
    The user name to run the command as
  group
    The group context to run the command as
  shell
    The shell to use for execution, defaults to the shell grain

## Comments

comments powered by Disqus

### Navigation

- index
- modules |
- next |
- previous |
- « SaltStack.org |
- Documentation home
- Full list of builtin state modules »