rurun runs a program on one or more targets which are identified by an index to a list of targets. Targets may be provided on the command line or a targets file.
rurun uses the pnet server which is started automatically if required, or an existing instance if specified.
usage: rurun [options] <targetspec> <arg> ...
rurun [--pnet <addr>] --count
Launch a program on one or more targets. If multiple targets are
specified, the last non-0 exit value will be returned; otherwise an
exit value of 0 is returned.
Targets are specified in a file. See --targets.
If --count is specified, then the number of targets is printed.
targetspec is a comma separated list of one or more of:
* value (e.g., 10)
* start:end (e.g., 0:3 which is equivalent to 0,1,2)
* start:end:step (e.g., 0:4:2 which is equivalent to 0,2); if start
is greater than end, step must be negative (e.g., 3:0:-1 is
equivalent to 3,2,1)
Provide attribute/environment variable settings. A
comma-separated list of environment variable names in
$RURUN_ENV are also passed.
-c Run all tasks concurrently. Overrides -n.
Enable debugging. Or set RURUN_DEBUG=1.
Environment to launch with:
simple - without shell
shell - shell with basic environment
login - shell with login environment
Defaults to $RURUN_EXEC_METHOD or "shell".
Set number of concurrently running tasks. Defaults to
$RURUN_NRUNNING_MAX or "1".
Run <ntasks> using <targetspec> settings, possibly multiple times.
If <ntasks> is less that the number of targets in <targetspec>,
stop at <ntasks>. Implies -c.
Use a given pnet address. Defaults to $RURUN_PNET_ADDR.
Use a given relay service. Defaults to $RURUN_RELAY or
Alternative shell to run on target. The arguments are passed
to it for execution. Forces "--exec simple".
Use targets file. Defaults $RURUN_TARGETSFILE.
Allow a given amount of time to connect before aborting.
Defaults to $RURUN_TIMEOUT or "30000".
Indexes in the <targetspec> which are outside of the count are
wrapped back to zero (effectively, modulo <count>). Negative
indexes are wrapped, too.
|optional||Comma-separated list of environment variable names to pass to the target.|
|optional||One of |
login. Default is
|required*||pnet server address used to connect to targets.|
|optional||Relay service to use to connect to targets when |
RURUN_PNET_ADDR points to a directory or file. Default is
|optional||Alternative shell to run on target. Forces exec method |
|required*||Targets file used by pnet server (was |
RURUN_PNET_TARGETSFILE, which remain as a fallback).
|optional||Timeout for connecting to the target.|
|* One of |
RURUN_TARGETSFILE must be set. If
RURUN_TARGETSFILE is set, a pnet server will be started automatically.
|Total number of tasks run.|
|Target id/index from the targetspec, with id wrapped at target count.|
|Target id/index from the targetspec.|
|Target group id/index from the targetspec. Indexed for each comma-separated group.|
|Count of targets in the targetsfile/targetslist.|
|Task id, index starting at 0.|
To run on a target (id 0):
To use an alternate shell (e.g.,
myshell), we start with the
exec /bin/ksh -c "$@"
The default behavior:
$ export HI=jim
$ rurun 0 'echo $HI'
Using the alternate shell:
$ export RURUN_SHELL=myshell
$ rurun 0 'echo $HI'
Given a basic targets file:
To run on each of the targets:
- A targetspec of ":" is similar to the Python range indexing format./
- For a 4 entry targets file, ":" is shorthand for, and equivalent to, "0:", "0:4".
- A targetspec of "0,1,2,3" runs on the same targets, but specifies 4 target groups not 1.
To run on every second target:
- The "2" fills the step field of <start>:<end+1>:<step>
- For a 4 entry targets file, "::2" is equivalent to "0::2".
- A targetspec of "0,2" runs on the same targets, but specifies 2 target groups not 1.
To run across the 4 targets as if there were 16:
rurun --wrap 0:16 hostname
--wrap causes target indexes to be modulo the number of target entries.
- Indexes can be outside the range based on the target file (i.e., 4 entries).
To run concurrently on up to 8 targets:
- If the targetspec is less than 8, the count of targetspec limits.
- If the targetspec is greater than 8, then only 8 run concurrently at at one time.
To run concurrently on 8 targets:
- The targets from targetspec are used 8 times. Similar to "
mpirun -np <ntasks>".
rurun can be used as an alternative launcher to
mpirun (to launch non-MPI programs).