Skip to end of metadata
Go to start of metadata



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)

-a|--attr <name>=<value>
    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.
--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. Defaults to
-N <ntasks>
    Run <ntasks> using <targetspec> settings, possibly multiple times.
    If <ntasks> is less that the number of targets in <targetspec>,
    stop at <ntasks>. Implies -c.
--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 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.

Environment Variables

rurun :

RURUN_ENVoptionalComma-separated list of environment variable names to pass to the target.
RURUN_EXEC_METHODoptionalOne of noshell, 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 noshell.
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.

Task Environment

RURUN_NTASKSTotal number of tasks run.
RURUN_REALTARGETIDTarget id/index from the targetspec, with id wrapped at target count.
RURUN_TARGETIDTarget id/index from the targetspec.
RURUN_TARGETGIDTarget group id/index from the targetspec. Indexed for each comma-separated group.
RURUN_TARGETCOUNTCount of targets in the targetsfile/targetslist.
RURUN_TASKIDTask id, index starting at 0.



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


rurun 0: hostname


  • 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:

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".
  • 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:

rurun -n 8 : hostname


  • 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:

rurun -N 8 : hostname


  • Implies --wrap.
  • The targets from targetspec are used 8 times. Similar to "mpirun -np <ntasks>".

mpirun Launcher

rurun can be used as an alternative launcher to mpirun (to launch non-MPI programs).

Instead of:

mpirun -np 4 hostname


rurun -N 4 : hostname

Instead of:

mpirun -n 16 hostname


rurun -N 16 : hostname