Command Options¶
Summary
Options which actions and command conditions have in common. They define which command runs, how it runs and what counts as success.
Options¶
Options without a label apply to actions and command conditions. Actions only marks options which command conditions do not have.
| Option | Default | Description |
|---|---|---|
run |
required | Command to run. A command with several lines stops at the first failing line. |
name Actions only |
Action N of M |
Name of the action, used in log messages. |
shell |
powershell on Windows, sh on Linux and macOS |
One of sh, bash, cmd, powershell or pwsh. The shell has to be installed. |
working_directory |
directory of the policy file | Relative paths are resolved against the directory of the policy file. |
env |
none | Additional environment variables. Numbers and booleans are converted to strings. Names starting with POWERRULES_ are reserved. |
timeout |
60 |
Maximum run time in seconds. Afterwards, the command and its child processes are terminated. null or .inf disables the limit. |
success_exit_codes |
[0] |
Exit codes which count as success. |
stdout, stderr |
none | Expected output of the command. A different output counts as unsuccessful (see below). |
wait Actions only |
true |
false starts the command in the background. Cannot be combined with timeout, success_exit_codes, stdout or stderr. |
continue_on_error Actions only |
false |
Whether the remaining actions still run if this action fails. |
trusted_files |
none | Files (e.g. scripts) the command depends on. They are verified before every run. Relative paths are resolved against the directory of the policy file. |
Options of stdout and stderr:
| Option | Default | Description |
|---|---|---|
value |
required | Text or regular expression the output is compared with. |
match |
exact, case-sensitive | How the output is matched, see Match Types. |
Details¶
- The output is compared after leading and trailing whitespace was removed.
- The shell
cmdonly supports a single line. Chain commands with&&instead. trusted_filesare relative to the policy file, not toworking_directory. See Trust.
Actions vs. command conditions¶
| Situation | Action | Command condition |
|---|---|---|
| Unexpected exit code or output | The action fails and the remaining actions are skipped unless continue_on_error is set. |
The condition does not match. |
| Command cannot be started or times out | The action fails. | The evaluation stops. |
POWERRULES_RULE_NAME, POWERRULES_ACTION_NAME |
Set. | Not set. |
--dry-run |
Not executed. | Executed. |