The cmd state module manages the enforcement of executed commands, this state can tell a command to run under certain circumstances.
The cmd state only has a single function, the run function
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 myscriptNote that if the cmd.wait state also specfies stateful: true it can then be watched by some other states as well.
cmd.wait is not restricted to watching only cmd states. For example it can also watch a git state for changes
# Watch for changes to a git repo and rebuild the project on updates
my-project:
git.latest:
- name: git@github.com/repo/foo
- target: /opt/foo
- rev: master
cmd.wait:
- name: make install
- cwd: /opt/foo
- watch:
- git: my-project
Execute a cmd function based on a watch call
Run a command if certain circumstances are met
Download a script from a remote source and execute it. The name can be the source or the source value can be defined.
Run the given command only if the watch statement calls it
Download a script from a remote source and execute it only if a watch statement calls it.