Shell Command Action

The Shell Command action allows you to run a (single line) shell command. You can optionally capture the output of the command and store it in a variable. Non-zero exit codes from the shell/command are interpreted as errors and no output will be stored (null will be stored instead).

Some utilities produce non-zero shell exit codes under non-error conditions. For example, one Reactor user used a utility called ps4-waker that, when run with the "check" option, will check if a target PS4 is powered on or off. The utility outputs a JSON status response containing the target's state, but also uses an exit code of 0 when the target is on or 1 when off to make it easy to use the utility in other shell scripts. The non-zero response would, however, be interpreted by Reactor as a failure of the command. When using commands that behave in this way, you can check the Ignore shell/command exit code checkbox, and Reactor will ignore the exit code. You can also use a "wrapper" script to run the command and hide its real exit code (i.e. have the wrapper always exit 0 at the end).

Cautions

Reactor makes no attempt to identify or filter dangerous or harmful commands. All commands given are executed as given, and it is up to you to make sure they perform correctly and don't harm your system or network. Any command you give will be run with the permissions of the user running Reactor. If you are running Reactor in a docker container, this command will execute in the container (not in the host OS/shell).

The command given is run in-line, and all other processing of the parent reaction stops until the command returns. Avoid long-running tasks and tasks that may not exit without being killed (see Other Configuration) below.

If the command produces a large amount of output and you capture that output to a variable, it may cause a spike in memory usage that leads to a crash. Only use output capture when the output is known to be limited and constrained.

Disabled By Default

Because of security and system stability risks that may arise from improper use of this action (such as being able to run any system command, e.g. rm -rf /*), it is disabled by default (you can put it into reactions but they won't run when encountered and will cause an error alert in Status). To enable it, add allow_shell_action: true to the engine section of your reactor.yaml configuration file.

As a further guard against dangerous options, expression substitution in the command for this action is not permitted by default. If you want to use expression substitution, you have to enable it by adding allow_shell_action_substitution: true to the engine section of your reactor.yaml configuration file.

Other Configuration

In order to prevent shell commands from blocking reactions, by default a timeout of 30 seconds is enforced, and a command that runs longer is terminated with an error. This timeout can be modified by setting the value of shell_action_timeout (specify an integer number of milliseconds) in the engine subsection of reactor.yaml.

Shell output is limited to 1MB (1,048,576 bytes) by default. If the command attempts to produce more output, it is terminated with an error. This limit is configurable by setting shell_action_output_limit (specify an integer number of bytes) in the engine section of reactor.yaml. If you set this value too high, you may cause Reactor or your system to crash from memory exhaustion.

Updated: 2024-Aug-19