run-remote--Execute a Script on Remote Systems

Reference Guide › AutoShell › AutoShell Core Reference › General AutoShell Commands › run-remote Command--Execute a Script on Remote Systems (Funclet)

run-remote Command--Execute a Script on Remote Systems (Funclet)

The run-remote command executes JavaScript code contained in a string or in a disk file on one or more remote systems. For remote execution to work, the remote target node must have the client AutoShell installed and be properly configured. Script files have to reside on the manager system and transfer to the target systems for execution. By default, script execution is asynchronous, meaning that local processing is continuing before the remote execution completes.

The command has the following syntax:

run-remote [script] [-file file] [-wait] [-with args,...] [-user username] 
[-pass password] [-key key phrase] [-port portnumber] on remoteTargets

The run-remote command returns an array of RemoteTarget objects representing the execution state of the script on the specified servers. Each element of this array corresponds by position to the remote node listed in the remoteTargets list. The RemoteTarget objects can verify several results, for example, if execution completes, if errors occur, or if the execution finishes successfully. If a remote node had been specified using an RemoteTarget object already, the array contains a reference to the original RemoteTarget object. If a target system is specified by a string, a new RemoteTarget object is created internally and assigned to the array.

script

(Optional) Specifies a string containing the JavaScript code to execute. The funclet either executes a script from a string or from a file. Thus the script and file arguments are mutually exclusive. Unquoted argument tokens are automatically stringified. Prevent automatic quoting for expressions by placing expression code in parenthesis.

Default: ""

-file file

(Optional) Specifies the absolute or relative path to the script file to execute. The funclet either executes a script from a string or from a file. Thus the script and file arguments are mutually exclusive. Unquoted argument tokens are automatically stringified. Prevent automatic quoting for expressions by placing expression code in parenthesis.

Default: ""

-wait

(Optional) By default run-remote will return after kicking off remote execution and remote processing is asynchronous. When the -wait option is specified, run-remote waits until all remote tasks either finish successfully or abort with an error.

-with args,...

(Optional) Specifies a comma-separated list of actual arguments to pass to the script. The script code can access these arguments using the standard JavaScript arguments array.

-user username

(Optional) Specifies the user name to use to log in to the remote node. A user name is required for password or public key authentication is used. If no user name is specified, the user name entered during AutoShell login is used. Unquoted argument tokens are automatically stringified. Prevent automatic quoting for expressions by placing expression code in parenthesis. The specified user name is only used for remote systems that are identified by hostname in the remoteTargets list. When specifying a host using RemoteTarget objects, each host has its individual user name set through the RemoteTarget object.

Default: $$User

-pass password

(Optional) Specifies password to use to log in to the remote node. If no password is specified, the password entered during AutoShell login is used. To enter a hidden password after issuing this command, specify PW_GET() with an optional prompt as argument. Unquoted argument tokens are automatically stringified. Prevent automatic quoting for expressions by placing expression code in parenthesis. The specified password is only used for remote systems that are identified by hostname in the remoteTargets list. When specifying a host using RemoteTarget objects, each host has its individual user name set through the RemoteTarget object.

Default: $$Pass

-key key

(Optional) Specifies an absolute or relative path to a file containing a private RSA key to use to log in to the remote node. If a private key and a password are specified, AutoShell attempts a public key logon first, and if that fails, a password logon. Unquoted argument tokens are automatically stringified. Prevent automatic quoting for expressions by placing expression code in parenthesis. This parameter is only required when creating an SSH session on the fly using public key authentication.

Default: ""

phrase

(Optional) Specifies the passphrase for a private key. If the key is not encrypted, the passphrase is not required. To enter a hidden password after issuing this command, specify PW_GET() with an optional prompt as argument. Unquoted argument tokens are automatically stringified. Prevent automatic quoting for expressions by placing expression code in parenthesis.

Default: ""

-port portnumber

(Optional) Specifies the port on which to connect to the target system. The specified port is only used for remote systems that are identified by hostname in the remoteTargets list. When specifying host using RemoteTarget objects, each host can have its individual port set through the RemoteTarget object.

Default: SSH standard port 22.

on remoteTargets

Specifies a comma-separated list of remote systems to run the specified script on. The target nodes can be identified in two ways: By hostname/address or by WinRemote objects. Specifying target systems by name or address while using WinRemote objects offers more flexibility to control the execution process, for example, different credentials for different hosts. WinRemote objects and strings with hostname/address can be mixed in the remote target list. Elements of the target list are not automatically stringified, so when using literal strings for hostnames they must be placed into quotes.

Examples

Evaluate a simple expression and wait until execution completed:

aRT = run-remote "1+2" on "ascli1" -wait
? "Error occurred:", aRT[0].errorOccurred()
? "Result:", get-remoteResult(aRT[0])

Evaluate a script from a file on two remote systems, wait until execution completed and display output ("Hello World!") and result (42):

s="? 'Hello World';42;"
// Create script file for illustration purpose only
// could also call:
// aRT=run-remote (s) on "ascli1", "ascil2"
memoWrit("hello.js", s);
aRT=run-remote -file hello.js on "ascli1", "ascli2"
for(i=0; i<aRT.length; i++)
{
    ? "Target:", aRT[i].getHostName()
    ? "Error occurred:", aRT[i].errorOccurred()
    ? "Output:", aRT[i].errorOccurred()
    ? "Result:", get-remoteResult(aRT[i])
}

Evaluate a script on two remote systems using RemoteTarget objects, specifying different credentials for the target systems:

rt1 = new RemoteTarget("ascli1", "alice", "casogood42");
rt2 = new RemoteTarget("ascli2", "bob", "!secret!7");
// Get OS version string from remote systems
aRT = run-remote "! ver" on rt1, rt2
// Perform wait ourselves
while(true)
{
    // If an error occurs hasCompleted() will
    // return true as well
    if(rt1.hasCompleted() && rt2.hasCompleted())
    break;
    sleep(500);
}
// We can either use the original RemoteTarget objects
// (see above) or the references in the returned array
// (below).
for(i=0; i<aRT.length; i++)
{
    ? "Target:", aRT[i].getHostName()
    ? "Error occurred:", aRT[i].errorOccurred()
    ? "Output:", aRT[i].errorOccurred()
}