Prototype: execresult(command, shell, output)

Return type: string

The return value is cached.

Description: Execute command and return output (both stdout and stderr) as string.

If the command is not found, the result will be the empty string.

The shell argument decides whether a shell will be used to encapsulate the command. This is necessary in order to combine commands with pipes etc, but remember that each command requires a new process that reads in files beyond CFEngine's control. Thus using a shell is both a performance hog and a potential security issue.

The optional output argument allows you to select which output will be included, betweeen stdout, stderr, or both. The default is both.

Arguments:

  • command: string - Fully qualified command path - in the range: .+
  • shell: - Shell encapsulation option - one of
    • noshell
    • useshell
    • powershell
  • output: - Which output to return; stdout or stderr - one of
    • both
    • stdout
    • stderr

Example:

Prepare:

code
rm -rf /tmp/testhere
mkdir -p /tmp/testhere
touch /tmp/testhere/a
touch /tmp/testhere/b
touch /tmp/testhere/c
touch /tmp/testhere/d
touch /tmp/testhere/e
echo "#!/usr/bin/env sh" >/tmp/testhere/echo-stdout-and-stderr
echo "echo stderr >&2" >>/tmp/testhere/echo-stdout-and-stderr
echo "echo stdout" >>/tmp/testhere/echo-stdout-and-stderr
chmod +x /tmp/testhere/echo-stdout-and-stderr

Policy:

code
body common control
{
      bundlesequence  => { "example" };
}

bundle agent example
{
  vars:
      "my_result"
        string => execresult("/bin/ls /tmp/testhere", noshell);

      "my_result_with_stdout_and_stderr"
        string => execresult("/tmp/testhere/echo-stdout-and-stderr", noshell);

      "my_result_with_stdout"
        string => execresult("/tmp/testhere/echo-stdout-and-stderr 2>/dev/null", useshell);

      "my_result_with_stderr"
        string => execresult("/tmp/testhere/echo-stdout-and-stderr 1>/dev/null", useshell);

  reports:
      "/bin/ls /tmp/testhere returned '$(my_result)'";
      "my_result_with_stdout_and_stderr == '$(my_result_with_stdout_and_stderr)'";
      "my_result_with_stdout == '$(my_result_with_stdout)'";
      "my_result_with_stderr == '$(my_result_with_stderr)'";

}

Output:

code
R: /bin/ls /tmp/testhere returned 'a
b
c
d
e
echo-stdout-and-stderr'
R: my_result_with_stdout_and_stderr == 'stderr
stdout'
R: my_result_with_stdout == 'stdout'
R: my_result_with_stderr == 'stderr'

Notes: you should never use this function to execute commands that make changes to the system, or perform lengthy computations. Such an operation is beyond CFEngine's ability to guarantee convergence, and on multiple passes and during syntax verification these function calls are executed, resulting in system changes that are covert. Calls to execresult should be for discovery and information extraction only. Effectively calls to this function will be also repeatedly executed by cf-promises when it does syntax checking, which is highly undesirable if the command is expensive. Consider using commands promises instead, which have locking and are not evaluated by cf-promises.

See also: returnszero(), execresult_as_data().

History:

  • 3.0.5 Newlines no longer replaced with spaces in stored output.
  • 3.17.0 Introduced optional parameter output added allowing selection of stderr, stdout or both.