run-winRemote--Execute a Command on Multiple Remote Windows Systems

Reference Guide › AutoShell › AutoShell Core Reference › General AutoShell Commands › run-winRemote Command--Execute a Command on Multiple Remote Windows Systems (Funclet)

run-winRemote Command--Execute a Command on Multiple Remote Windows Systems (Funclet)

The run-winRemote command executes a command on one or multiple remote Windows systems. The command comes in two flavors:

Single-target version
Multi-target version

The single-target version redirects input and output to the calling AutoShell.

The multi-target version of run-winRemote is asynchronous. See the sample code on how to retrieve results.

The command has the following syntax:

(1) run-winRemote -host hostname [-cmd cmd] [-user username] [-pass password] [-workDir workDir]

(2) run-winRemote [-cmd cmd] [-user username] [-pass password] [-workDir workDir] on remoteTargets

The single targeted version of run-winRemote returns the result code of the executed command.

The multi-target version returns an array of WinRemote objects. Each element of this array corresponds by position to the remote Windows node listed in the remoteTargets list. The WinRemote objects can verify several results, for example, if the execution completes, if errors occur, or if the execution finishes successfully. If a remote node is specified using an WinRemote object, 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.

-host hostname

(Optional) Specifies the name of the remote Windows host. Unquoted argument tokens are automatically stringified. Prevent automatic quoting for expressions by placing expression code in parenthesis.

-cmd cmd

(Optional) Specifies the command to execute on the remote Windows system. 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: cmd

-user username

(Optional) Specifies the user name to log on to the remote Windows system. The user must have rights to connect to the $ADMIN share. 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.

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.

Default: $$Pass

-workDir workdir

Specifies the actual working directory.

Default: ""

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

To run cmd.exe (the command shell) on host1:

run-winRemote -host host1 -cmd cmd.exe

To run mybatch.bat on host1 and host 2 and verify the results of host2

x = run-winRemote -cmd mybatch.bat -localpath c:\installations\myinstall.exe on "host1", "host2";
? x[1].hasCompleted();
? x[1].result();
? x[1].output();