Skip to content

Eval Remote

Sends a block of code to a target server and runs it there. Where Run a Remote Script gives you one command line, this gives you a whole script written in the editor, with no need to place a file on the target first.

The trade-off is that the form carries no error handling at all. Run a Remote Script lets you map return codes and output patterns onto job outcomes. This op has nothing of the sort, and a script that exits non-zero does not stop the job. Use that op whenever the outcome has to be checked, and keep this one for code you have to send in one piece, such as a PowerShell block or a multi-line shell function.

Code worker or Balix agent SSH or Clax agent evaluated directly in the agent's own language Shell is ignored written to a temp file on the target, then run as <Shell> /tmp/.... the temp file is left behind

Fields

Server

The server to run on. Required. Only resources that can hold an agent appear in the picker, and the picker holds one entry at a time. Choosing a second server silently replaces the first.

Variables are offered in the same list, and that is the only way to reach several targets from one op. A variable that expands to a comma-separated string is split, and the code runs on each server in turn, in the order the list gives them.

A server marked inactive logs a Server <name> is inactive. Skipped warning and is passed over. The rest of the list still runs. When every server in the list is inactive the op does nothing at all and the job carries on.

User

The account to run as. Left blank, the connection uses the user configured on the agent attached to the server resource. Whatever you type also appears in the user@host part of the log lines that bracket the run. This op prints the field as you left it rather than the user actually connected with, so a blank field gives you @myhost with nothing in front of the @ even though the run had a user.

Shell

The interpreter that runs your code. Required. The box offers powershell.exe -noprofile -noninteractive, cmd.exe, /bin/bash, /bin/sh and perl, and it is editable, so you can type any interpreter that exists on the target. Whatever you put here is prefixed to the path of the uploaded script, so it has to be a command the target can run.

There are two cases where the field is not used as written.

On agents that evaluate code themselves, it is ignored entirely and the code runs in that agent's own language. Worker agents run JavaScript, Balix agents run Perl. Pointing Shell at /bin/bash on such a server does not make the code shell script.

On Windows targets reached over SSH or Clax, only a value starting with powershell is honoured, and the script is saved with a .ps1 extension. Anything else, including cmd.exe, is dropped: the script is saved with a .bat extension and executed directly, so the code has to be valid batch.

Code

The script itself, in a full editor. It expands ${var} against the stash before being sent, so ${job_name} and anything an earlier op left behind can be read directly. A name the stash cannot resolve is left in the text literally as ${name} rather than becoming an empty string.

Unlike the command field on Run a Remote Script, this text is not expanded a second time against the target server's own attributes, so ${hostname} does not resolve here. Set it into a stash variable first if you need it.

On agents that do not evaluate code themselves, the script is written to a file in the target's temporary directory and run from there. That file is not cleaned up afterwards, so a rule that runs this op on every job slowly fills the target's temporary directory. Agents that evaluate code themselves leave nothing behind.

The field is not required and an empty one does not stop anything. On a target reached over SSH or Clax an empty script is still uploaded and run, which does nothing and reports success. On a worker agent, empty code is replaced by a ping that logs pong, which is a quick way to prove the agent is reachable.

Return codes and failure

This op almost never fails. A return code of 99 stops the job with Error during eval execution, which is the code the agent layer reports when the connection itself broke or timed out. Every other return code, including 1, is logged and ignored, and the job carries on to the next op. A worker agent that throws an error reports 2, so even a script that blew up on the target passes through quietly.

The one other way this op stops a job is on the way in. Getting the script onto a target reached over SSH is a file transfer, and a transfer that fails raises an error before the script ever runs.

That makes silent failure the normal case. If the outcome matters, either have the script exit 99 on error, or write a marker into its output and check it afterwards with Run a Remote Script and an Output pattern.

What appears in the job log

A RUNNING remote eval line before and a FINISHED remote eval line after, both carrying the user@host of the target. Both land at debug level, so they are invisible in a job log filtered to info and above. Between them, the script's output arrives as an output entry at info level and its return value as a return entry at debug level.

Worker agents can return job log messages of their own, in which case those are written into the job log at the levels the script chose instead of the plain output entry.

Set a Return Key on the op's Options tab to keep the script's return value in the stash. One server puts that value in on its own. Several servers put in a list, one entry per server that actually ran, in the order the list gave them. Inactive servers contribute nothing, so a run where every server was skipped leaves the key empty.

Combining with other ops

Put Ship File Remotely before this op when the script needs data files on the target, and Retrieve a remote file after it to bring anything it wrote back.

Because failures here are silent, pair it with a following Run a Remote Script that verifies the result, then branch with IF var condition THEN.

For code that should run on the Clarive server rather than on a target, use Server CODE or EVAL JavaScript.

Examples

Restart a Windows service and report what happened, using PowerShell.

Server   win_host
Shell    powershell.exe -noprofile -noninteractive
Code     $svc = "myapp"
         Restart-Service -Name $svc -Force
         Get-Service -Name $svc | Format-List Status, Name

Roll a log file and prune old copies on a set of Unix hosts, signalling failure with the one return code this op reacts to.

Server   ${prod_nodes}
User     appuser
Shell    /bin/bash
Code     set -e
         trap 'exit 99' ERR
         cd /var/log/myapp
         mv deploy.log deploy.${job_name}.log
         find . -name 'deploy.*.log' -mtime +30 -delete