clusrun
Applies To: Microsoft HPC Pack 2012, Microsoft HPC Pack 2012 R2
Runs the specified command on multiple nodes, and redirects the output of all instances of the specified command to the node on which you ran the clusrun command.
For examples of how to use this command, see Examples.
Syntax
clusrun [/all] [/env:<variable_and_value_list>] [/exclude:<node_list>]
[/interleaved] [{/job:<jobID> | /nodegroup:<node_group> |
/nodes:<node_list> | /task:<jobID>.<taskID>[.<subtaskID>] |
/template:<job_template_name> }] [{/nodestate:<node_state> |
/pausednodes | /readynodes}] [/outputdir:<directory>]
[/password:{<password>|*}] [/scheduler:<name>] [/sorted]
[/spooldir:<directory>] [/stdin:[<path>\]<file_name>]
[/task:<JobID>.<TaskId>[.<subtaskID>]]
[/user:[<domain>\]<user_name>]] [/workdir:<folder>]
<command> [<arguments>]
clusrun {/? | /help}
Parameters
Parameter |
Description |
|---|---|
/all |
Runs the command on all of the nodes in the HPC cluster. |
/env:<variable_and_value_list> |
Specifies a list of environment variables to set in the run-time environment of the command and the values to assign to those environment variables. The list should have a format of <variable_name1>=<value1> [;<variable_name2>=<value2>...]. Alternatively, you can set multiple environment variables by including multiple /env parameters, each with a different argument with a format of <variable_name>=<value>. To unset an environment variable, do not specify a value. For example, ″<variable_to_unset_name>=″. |
/exclude:<node_list> |
Specifies a list of one of more nodes on which you do not want the command to run, by using the format <node1_name>[,<node2_name>...]. You can use the /exclude parameter in combination with other parameters that specify multiple nodes indirectly to eliminate specific nodes. For example, if your HPC cluster includes nodes named computenode1, computenode2, and computenode3, you can use the /exclude:computenode2 and /nodes:compute* options together to specify that the command should run on computenode1 and computenode3. |
/interleaved |
Displays the output of the command from the different nodes as a single list in which each line is labeled with the name of the node that produced the line of output, and in which lines of output from different nodes can be interleaved. |
/job:<jobID> |
Specifies the identifier for a job that has a state of Running, Finished, Failed, or Canceled and which was allocated the nodes on which you want to run the command. If you specify the /job parameter, clusrun runs the command on the same nodes that the HPC Job Scheduler Service allocated to the specified job. The job must be a job for which nodes were allocated previously. You cannot specify the /job parameter if you also specify the /nodegroup, /nodes, /task, or /template parameter. |
/nodegroup:<node_group> |
Specifies the node group that contains the nodes on which you want to run the command. You cannot specify the /nodegroup parameter if you also specify the /job, /nodes, /task, or /template parameter. |
/nodes:<node_list> |
Specifies a list of one of more nodes on which you want to run the command by using the format <node1_name>[,<node2_name>...]. You can use an asterisk (*) as a wildcard character. For example, if you specify /node:compnode1*, the command runs on all nodes that have a name that starts with compnode1, such as compnode10, compnode15, compnode126, and compnode1158. You cannot specify the /nodes parameter if you also specify the /job, /nodegroup, /task, or /template parameter. Note The node name cannot be longer than 12 characters. |
/task:<jobID>.<taskID>[.<subtaskID>] |
Specifies the identifier for a task or subtask that has a state of Running, Finished, Failed, or Canceled and which was allocated the nodes on which you want to run the command. If you specify the /task parameter, clusrun runs the command on the same nodes that the HPC Job Scheduler Service allocated to the specified task or subtask. The task or subtask must be a task or subtask for which nodes were allocated previously. For parametric tasks, you must specify a subtask rather than a task. You cannot specify the /task parameter if you also specify the /job, /nodegroup, /nodes, or /template parameter. |
/template:<job_template_name> |
Specifies the name of the job template that specifies a node group that contains the nodes on which you want to run the command. The maximum length for the name of a job template is 80 characters. You cannot specify the /template parameter if you also specify the /job, /nodegroup, /nodes, or /task parameter. |
/nodestate:<node_state> |
Runs the command on all nodes that are in the specified state. The valid states are Online, Offline, and Draining. You cannot specify the /nodestate parameter if you also specify the /pausednodes or /readynodes parameter. |
/pausednodes |
Deprecated. Use the /nodestate:offline parameter instead. |
/readynodes |
Deprecated. Use the /nodestate:online parameter instead. |
/outputdir:<directory> |
Specifies the directory on the local computer that you use to run the clusrun command in which you want to save the output of the command that you ran with the clusrun command. This directory must already exist, or an error occurs. The clusrun command creates a subdirectory of this directory with the name that is the same as the job identifier that the HPC Job Scheduler Service assigns to the instance of the clusrun command. The clusrun command saves a file for each node that was specified. This file contains the output of the specified command on that node, with a file name that matches the name of the node with no extension. You can use a text editor program such as Notepad to view the contents of these files. |
/password:{<password>|*} |
Specifies the password for the account under which the command should run. If you specify the /user parameter but not the /password parameter or if you specify an asterisk (*) for the password, the clusrun command prompts you for the password and whether to store the password. |
/scheduler:<name> |
Specifies the host name or IP address of the head node for the cluster that contains the nodes to which you want to run the command. The value must be a valid computer name or IP address. If you do not specify the /scheduler parameter, this command uses the scheduler on the head node that the CCP_SCHEDULER environment variable specifies. |
/sorted |
Displays the output from the different nodes that ran the command after the command finishes on all nodes. The output for each node appears in a separate section that has a heading that indicates the node that produced the output. The sections are sorted in alphabetical order by the name of the nodes. |
/spooldir:<directory> |
Deprecated. Use the /outputdir parameter instead. |
/stdin:[<path>\]<file_name> |
Specifies the name for the file from which the command should receive standard input. This includes the full path or the path that is relative to the working directory for the file if the command should not receive standard input from a file in the working directory. If you specify a file or path that does not exist on a node on which the command runs, the command fails on that node. The maximum length of the value for this parameter is 160 characters. |
/user:[<domain>\]<user_name>] |
Specifies the user name, and optionally the domain of the account under which the command should run. If you do not specify this parameter, the command runs under the account that is used to run the clusrun command. |
/workdir:<folder> |
Specifies the working directory under which the command should run. The default value is %USERPROFILE%. The maximum length of the value for this parameter is 160 characters. |
<command> [<parameters>] |
Specifies the command line for the command that you want to run, including the command or application name and any necessary parameters. The clusrun command uses the cmd command to run this command on each of the nodes as follows: cmd.exe /c <command> [<parameters>] You cannot run Message Passing Interface (MPI) applications by using the clusrun command. |
/? |
Displays Help at the command prompt. |
/help |
Displays Help at the command prompt. |
Remarks
You can run the clusrun command on any client node in the cluster that is accessed directly or remotely. Client nodes include the head node and any compute nodes on which the client utilities are installed. The output from the nodes that run the command is redirected to the client node, and it includes the standard output and standard error streams in addition to run-time error messages from the operating system.
If you interrupt or stop the clusrun command, the instances of the remote command also stop.
You must be a cluster administrator to run the clusrun command.
The clusrun command runs the specified command immediately on the relevant nodes, regardless of whether the nodes are already running a scheduled task. Because the command that is specified in the clusrun command runs immediately, the clusrun command can cause scheduled tasks that are already running to fail, particularly latency-sensitive MPI programs.
A command that you run with clusrun may be unable to access shared folders on the computer from which you issued the clusrun command. This access issue can occur under the following circumstances:
A firewall prevents the command from accessing the shared folder.
IPsec or domain policy prevents the clusrun command from communicating through network address translation (NAT).
If you log on to a compute node and cannot access a shared folder on the client computer, the command that you run with the clusrun command will not have access to that shared folder.
To grant access to the shared folder through the firewall, create a firewall exception on the client computer for the File and Printer Sharing feature.
When specifying a path or command that needs to be enclosed in quotation marks (") because it includes spaces, be careful if the path or command also includes backslashes (\), because a backslash that immediate precedes a quotation mark acts as an escape character. To prevent the backslash from acting as an escape character, use two backslashes. For example, use "C:\Program Files\\" instead of "C:\Program Files\".
Examples
To list the contents of the %USERPROFILE% directory on all of the nodes in the cluster, use the following command:
clusrun /all dir
To run the echo hello command on all nodes that have names that start with compute, except computenode1, use the following command:
clusrun /nodes:compute* /exclude:computenode1 echo hello
To run the systeminfo command on all online nodes that the HPC Job Scheduler Service allocated to the job with a job identifier of 12, use the following command:
clusrun /job:12 /nodestate:online systeminfo