bpsh

Name

bpsh, bprsh – Run a command on the indicated node(s).

Synopsis

bpsh [-h ] [-v ] [-a ] [-A] [-L] [-p] [-s] [-d] [-b num] [-n] [-N] [-I file, –stdin file] [-O file, –stdout file] [-E file, –stderr file] targetnodes command [command-args]

Description

This utility is part of the BProc package and is installed by default on Scyld ClusterWare systems. It is the basic mechanism for running programs on nodes, and it is patterned after the rsh and ssh commands.

The targetnodes can range from -1 (the master) to one less than the number of accessible nodes. bpsh will also accept a delimited list of nodes; use -a for all nodes that are “up” and -A for all nodes that are communicating (e.g., states “up”, “error” and “unavailable”).

bpsh forwards stdin, stdout and stderror for the remote processes, unless directed otherwise by -n or -N arguments. stdin will be duplicated for every process on each remote node selected. For a single remote process, the exit status of bpsh will be the exit status of that process. Non-normal exit status will also be captured and displayed. For multiple processes, bpsh exits with the highest exit status.

bpsh throttles the maximum number of command executions that are outstanding at any point in time as bpsh services the entire targetnodes list. The default fanout is 64, which can be overriden by the environment variable BPSH_FANOUT=<number>, which is currently capped at 128. The fanout when using the -s (serialize) option is fixed at 1.

The bprsh utility is a variant of bpsh. See the EXAMPLES.

Options

The following options are available to the bpsh program.

-h

Print the command usage message and exit. If -h is the first option, all other options will be ignored. If -h is not the first option, the other options will be parsed up to the -h option, but no action will be taken.

-v

Print the command version number and exit. If -v is the first option, all other options will be ignored. If -v is not the first option, the other options will be parsed up to the -v option, but no action will be taken.

-a

Specifies that the command will be run on all nodes in the “up” state.

-A num

Specifies that the command will be run on all nodes in either the “up”, “error”, and “unavailable” states. Note that non-root users may get “BProc move failed” errors, since they are only allowed to run on “up” nodes, regardless of other node permissions.

-L state

Line buffer output from nodes.

-p

Prefix the node number on each output line from the node that sent it.

-s

List sequentially all the output from each node.

-d

Print a divider line between the sequential output from each node.

-b num

Set the IO line buffer size to the number of bytes. The default is 4096.

-n

Get stdin from /dev/null. On any read from stdin, /dev/null will return EOF. This is useful for any program that you background or daemonize. Like rsh, bpsh will not exit immediately if stdin is left open and the program has not completed. bpsh assumes the program may want input from stdin.

-N

No IO forwarding.

-I file, --stdin file

Redirect standard input from the specified file on the remote node.

-O file, --stdout file

Redirect standard output to the specified file on the remote node.

-E file, --stderr file

Redirect standard error to the specified file on the remote node.

targetnodes

The node(s) on which to run the command.

command

The command/program to run.

command-args

The arguments for command.

Examples

Run the ls command on nodes -1, 0 and 2, and prefix the node number to each line. Note, due to the way getopt works, the master (node -1) cannot be first in the node list:

[user@cluster user] $ bpsh 0,-1,2 -p ls /tmp
  -1: f1.txt
  -1: foo.txt
  0: f3.txt
  2: newfoo.txt
  2: oops.txt

Run the uptime command on nodes in the “up” state:

[user@cluster user] $ bpsh -a -d uptime
  0 -----------------------------------------------------------------
    2:42pm  up 2 days, 23:51,  0 users
  1 -----------------------------------------------------------------
    2:41pm  up 3 days,  5:38,  0 users
  3 -----------------------------------------------------------------
    2:42pm  up 3 days,  5:38,  0 users

Run the same command with a fanout value override:

[user@cluster user] $ BPSH_FANOUT=128 bpsh -a -d uptime

Run a single instance of the uptime command on a node chosen by the scheduler, displaying the node number before the output.

[user@cluster user] $ bpsh -p 0-3 uptime
  0 2:42pm  up 2 days, 23:51,  0 users
  1 2:42pm  up 3 days,  5:38,  0 users
Node 2 is down
  3 2:42pm  up 3 days,  5:38,  0 users

Run a complex command that consists of multiple commands that displays all the “up” nodes that have been up for less than 24 hours. Note: the bpsh utility expects command to be a single command, so to execute multiple commands you must use bash -c with the desired command in quotes:

[user@cluster user] $ bpsh -sap bash -c "uptime | grep -v days"

Alternatively, bprsh accepts the more complex command as-is, just as rsh would do:

[user@cluster user] $ bprsh -sap "uptime | grep -v days"