Skip to end of metadata
Go to start of metadata

Some features with >= v6.8.



rurun runs a program on a target identified by an index to a targets file. rurun uses the pnet server which is started automatically if required.


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)

-a|--attr <name>=<value>
	Provide attribute/environment variable settings. A
	comma-separated list of environment variable names in
	$RURUN_ENV are also passed.
	Enable debugging. Or set RURUN_DEBUG=1.
--exec simple|shell|login
	Environment to launch with:
	simple - without shell
	shell - shell with basic environment
	login - shell with login environment
	Defaults to $RURUN_EXEC_METHOD or "shell".
-n <maxtasks>
	Set number of concurrently running tasks. Default is 1.
--pnet <addr>
	Use a given pnet address. Defaults to $RURUN_PNET_ADDR.
--relay <name>
	Use a given relay service. Defaults to ${RURUN_RELAY} or
--shell <path>
	Alternative shell to run on target. The arguments are passed
	to it for execution. Forces "--exec simple".
--targetsfile <path>
	Use targets file. Defaults ${RURUN_TARGETSFILE}.
-t|--timeout <seconds>
	Allow a given amount of time to connect before aborting.
	Defaults to ${RURUN_TIMEOUT} if set.
--wrap	Indexes in the <targetspec> which are outside of the count are
	wrapped back to zero (effectively, modulo <count>). Negative
	indexes are wrapped, too.

Environment Variables

RURUN_ENVoptionalComma-separated list of environment variable names to pass to the target.
RURUN_EXEC_METHODoptionalOne of simple, shell, login. Default is shell.
RURUN_PNET_ADDRrequired*pnet server address used to connect to targets.
RURUN_RELAYoptionalRelay service to use to connect to targets when RURUN_PNET_ADDR points to a directory or file. Default is ssh.
RURUN_SHELLoptionalAlternative shell to run on target. Forces exec method simple.
RURUN_TARGETSFILErequired*Targets file used by pnet server (was RURUN_PNET_TARGETSFILE, which remain as a fallback).
RURUN_TIMEOUToptionalTimeout for connecting to the target.
* One of RURUN_PNET_ADDR or RURUN_TARGETSFILE must be set. If RURUN_TARGETSFILE is set, a pnet server will be started automatically.


When rurun launches programs onto targets, there are some settings that can only be determined and set on the target. The RURUN_SHELL settings tells rurun which program to use instead of the shell. The program specified in RURUN_SHELL is expected to launch the program passed to rurun.


To run on a target (id 0):

rurun 0 hostname

To use an alternate shell (e.g., myshell), we start with the myshell implementation:

#! /bin/ksh
export HI=joe
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:

rurun : hostname


  • the targetspec is ":", which is similar to the Python range indexing format
  • for a 4 entry targets file, ":" is shorthand for, and equivalent to, "0:", "0:4", and "0,1,2,3"

To run on every second target:

rurun ::2 hostname


  • the "2" fills the step field of <start>:<end+1>:<step>
  • for a 4 entry targets file, "::2" is equivalent to "0::2", and "0,2"

To run concurrently across 4 targets:

rurun -n 4 : hostname

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)
  • for a 4 entry targets file, "0:16" is equivalent to "0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15" modulo 4: "0,1,2,3,0,1,2,3,0,1,2,3,0,1,2,3"

As an alternative to mpirun as a launcher (to launch non-MPI programs). Instead of:

mpirun -n 4 hostname


rurun -n 4 hostname

Instead of:

mpirun -n 16 hostname


rurun --wrap -n 16 0:16 hostname