Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

toc-local

Introduction

RUSS provides some tools for working with a network/collection targets. A target may be a host or host+cgroup. The tools can be used on their own or in support of MPI.

rudial

The rudial (and friends) tools provide access to RUSS services via the command line/shell.

The dial call is central to RUSS. It is what connects a client to a server, after which, one or more I/O streams between them are set up for inter-process communication. Three I/O streams are standard and  connected to stdin, stdout, and stderr.

rudial takes an operation value such as execute, list, help and a service path which is a /-separated list of names specifying the service to use and how to get to it. The operation tells the service what to do: execute the service, list subservices, return help information for the service(s). rudial also takes an optional set of key=value attribute settings and an argument list. All items are passed as strings. The exit value of the service is returned by rudial.

Some convenience programs are provided to shorten the invocation: ruexecrulsruhelp.

Usage

No Format
RUDIAL(1)                                                    RUDIAL(1)
NAME
       rudial,  ruexec, ruhelp, ruls - Client-side tools for accessing
       russ servers

SYNOPSIS
       rudial [<option>] <op> <spath> [<arg> ...]
       ruexec [<option>] <spath> [<arg> ...]
       ruhelp [<option>] <spath> [<arg> ...]
       ruls [<option>] <spath> [<arg> ...]

DESCRIPTION
       These client-side tools are used to dial (connect  to)  a  russ
       serivce. When connected to a russ service, file descriptors are
       returned, corresponding to stdin, stdout, stderr  of  the  ser‐
       vice, and can be used as usual. (Note that the file descriptors
       returned depends on the service.)

       The standard exit code mechanism functions  as  usual  and,  in
       most cases, is returned by the service. Common exit codes are 0
       for success, 1 for error. When there is a problem with the dial
       step, and exit code of 126 or 127 may be returned.

       Options:
       -a|--attr <name=value>
              Pass a "name=value" string to the service.

       -b <bufsize>
              Set the buffer size for reading and writing operations.

       -t|--timeout <seconds>
              Allow  given  amount of time to dial before aborting and
              returning an error exit code.

       rudial is the generic form and takes a russ operation (<op>):
       execute
              Execute the service <spath>  on  behalf  of  the  client
              user.

       help   Return  help  for  the server or service associated with
              the <spath>.

       list   Return a list of services at the <spath>.

       The service path <spath> identifies a service as found  in  the
       service hierarchy of a russ server.

   Helper Programs
       To  reduce  verbosity  of the rudial call, some helper programs
       are provided.  All but ruls are direct replacements.

       ruexec is equivalent to "rudial execute".

       ruhelp is equivalent to "rudial help".

       ruls is equivalent to "rudial list" except when the <spath>  is
       a  local filesystem object (e.g., directory). In such a case, a
       modified directory listing is output. This is helpful when nav‐
       igating the filesystem and russ services.

SEE ALSO
       russ(7)

AUTHOR
       Written by John Marshall.

REPORTING BUGS
       Report bugs to: <...>.

COPYRIGHT
       Copyright © 2014 John Marshall.
       Unless  otherwise  indicated,  this software is available under
       the terms of the ls Apache License version 2.
russ 5.x                                                     RUDIAL(1)

Examples

To list the system services:

No Format
ruls +

Note:

  • + is shorthand for the RUSS_SERVICES_DIR

To list services of a server (e.g., the debug server):

No Format
ruls +/debug

To get help from the debug server:

No Format
ruhelp +/debug

To execute the daytime debug service:

No Format
ruexec +/debug/daytime

To pass input over stdin:

No Format
echo hello | ruexec +/debug/echo

To pass file input over stdin:

No Format
cat /etc/hostname | ruexec +/debug/echo

or by using the -i option:

No Format
ruexec -i /etc/hostname +/debug/echo

rurun

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

Usage

No Format
usage: rurun [options] <target> <arg> ...
       rurun [--pnet <addr>] --count

Launch a program on a pnet target. If a pnet server specified
(command line or environment variable), the local host will be used.

If --count is specified, then the number of pnet targets is printed.

Options:
-a|--attr <name>=<value>
	Provide attribute/environment variable settings. A
	comma-separated list of environment variable names in
	$RURUN_ENV are also passed.
--debug
	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".
--pnet <addr>
	Use a given pnet address. Defaults to $RURUN_PNET_ADDR.
--relay <name>
	Use a given relay service. Defaults to ${RURUN_RELAY} or
	"ssh".
--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_PNET_TARGETSFILE}.
-t|--timeout <seconds>
	Allow a given amount of time to connect before aborting.
	Defaults to ${RURUN_TIMEOUT} if set.

Environment Variables

...

RURUN_SHELL

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.

Examples

To run on a target (id 0):

No Format
rurun 0 hostname

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

Code Block
languagebash
titlemyshell
#! /bin/ksh
export HI=joe
exec /bin/ksh -c "$@"

The default behavior:

No Format
$ export HI=jim
$ rurun 0 'echo $HI'
jim

Using the alternate shell:

No Format
$ export RURUN_SHELL=myshell
$ rurun 0 'echo $HI'
joe

rumpirun

rumpirun is a RUSS-specific wrapper for the underlying mpirun program as provided by OpenMPI or MPICH. Most all arguments provided to rumpirun are passed to the underlying mpirun without change to be processed it. rumpirun uses rurun to launch MPI programs onto the targets.

Environment Variables

Many of the rumpirun-specific environment variables correspond to those of rurun.

...

Usage

See respective MPI implementations for usage.

MPICH

The following environment variables are set by rumpirun:

  • HYDRA_BOOTSTRAP
  • HYDRA_BOOTSTRAP_EXE
  • HYDRA_LAUNCHER
  • HYDRA_LAUNCHER_EXEC
  • HYDRA_HOST_FILE
  • HYDRA_LAUNCHER_AUTOFORK

and the following options:

  • -disable-hostname-propagation - forces hostname determinated to be done at the target

OpenMPI

The following environment variables are automatically set by rumpirun:

  • OMPI_MCA_orte_default_hostfile
  • OMPI_MCA_orte_rsh_agent
  • OMPI_plm_rsh_disable_qrsh

RUMPIRUN_SHELL

See RURUN_SHELL for details. RUMPIRUN_SHELL allows setting up on the target prior to launching the task.

Examples

To run an MPI job (e.g., mpihello):

No Format
rumpirun mpihello

Notes:

  • depends on the underlying mpirun for determining number of tasks

To run MPI job with 4 tasks:

No Format
rumpirun -n 4 mpihello

Notes:

  • -n (and its synonym -np) is understood by openmpi and mpich implementations

Pass some environment variables (PATHXYZ):

No Format
export RUMPIRUN_ENV="${RUMPIRUN_ENV} PATH XYZ"

Notes:

  • the named environment variables will be passed independently of mpirun (for both openmpi and mpich)
  • the named environment variables are available before the MPI helper (e.g., orted for openmpi) are even started

ruservice

RUSS servers that are made available on the system are managed using the ruservice tool.

ruservice is used to start, stop, restart, and get the status of system RUSS servers. System configurations are stored in /etc/russ/conf. Running server have a pid file at /var/run/russ/pid and socket files at /var/run/russ/services (also identified as RUSS_SERVICES_DIR).

With the introduction of RUSS v6, management of system servers has changed.

All system server configuration files must be directly under /etc/russ/conf; no subdirectories. Configuration files associated with a particular server implementation/package must be named as <name>.conf or <name>.<subname>.conf. The latter form is useful when multiple instance of the same server are needed but for different uses. This naming scheme allows packages to easily identify and target configurations that depend on the server software.

As before, a system server is exposed via a socket file under the RUSS_SERVICES_DIR. But a system server may also be exposed as a configuration file in the same RUSS_SERVICE_DIR location. A server with a file of either kind (socket or configuration) under RUSS_SERVICES_DIR is said to be "running".

The first line of configuration files is used to mark it as a RUSS configuration file:

Code Block
#russ [<directive>] [...]

and provide some additional information/directives that may be used, e.g., by ruservice.

So, when ruservice is called to start a server, it examines the first line of the configuration file in /etc/russ/conf. If it contains "service:socket" as:

Code Block
#russ service=socket

the standard approach is used: start a server with a socket file. This is required for servers that must run as a user different than the user connecting to the server; a server that needs to perform operations as root on behalf of the connecting user must always use a server actively listening on a socket file. A socket file server is also useful when the fastest turnaround time (connect, perform service, close) is required.

If the configuration file contains "service=conffile" as:

Code Block
#russ service=conffile

a slightly modified/augmented copy of the configuration file is copied to the RUSS_SERVICES_DIR. This approach is suitable for servers that will run as the connecting user. In effect, when the dial function in the RUSS library is called and finds a configuration file instead of a socket file, it will dynamically start a server which will then be connected to. Because the server is actually started by the connecting user, this is suitable only for servers that must run as the connecting user. Since a new server must be started each time, there is a small performance penalty. The benefit is that less system servers need to actually be running as processes.

ruservice uses ruspawn to start socket file servers instead of rustart. The benefit of ruspawn is automatic cleanup of the socket file when the server exits/is killed.

Usage

No Format
usage: ruservice <confname> {start|stop|restart|status|list}
       ruservice list|status
       ruservice -h|--help|help

Manage system configured RUSS servers. Configurations must be in
	/etc/russ/conf
The server address will be set to the configuration name (and
override any main:addr setting in the original configuration).

Where:
<confname>	Configuration name (not including .conf). confname of
		"." means all configuration names.

Examples

Restart all servesr:

No Format
ruservice . restart

Get status of all servers:

No Format
ruservice . status

Restart (RUSS) ssh server:

No Format
ruservice ssh restart

Notes:

  • applies to configuration file at /etc/russ/conf/ssh.conf

Restart collection of servers under fspc:

No Format
ruservice fspc restart

Notes:

  • applies to configuration files/etc/russ/conf/fspc.conf and /etc/russ/conf/fspc.*.conf

Restart a single instance of a collection of servers:

No Format
ruservice fspc.local restart

ruspawn

Spawn a server using configuration settings provided in a file and/or as arguments.

When a server is spawned, a reaper process is also started which is responsible for removing the associated socket file. A normal kill signal sent to either the server or reaper process will result in a cleanup.

Usage

No Format
usage: ruspawn (-f <path>|-c <name>=<value>) [...] [-- ...]

Spawn a russ server. Using the configuration, a socket file is
created and the listener socket is passed to the server. The path
the socket file is output to stdout.

ruspawn is different from rustart in the following ways. If
main:addr (the socket file path) is not specified, a path is
dynamically chosen and used to set main:addr. A reaper process is
started to automatically cleanup the socket file when the server
exits. If the server or the repear are signaled, they both will be
terminated and the socket file cleaned up.

ruspawn is the preferred way to start a server.

Where:
-c <name>=<value>
	Set configuration attribute.
-f <path>
	Load configuration file.
-- ...	Arguments to pass to the server program.

Examples

To spawn a personal instance of the debug server (assuming /etc/russ/conf/debug.conf):

No Format
ruspawn -f /etc/russ/conf/debug.conf -c main:addr=/tmp/mydebug

Notes:

  • debug.conf is used as the starting point
  • main:addr is overridden with /tmp/mydebug

Use ruspawn to automatically select a path for the socket file:

No Format
ruspawn -f /etc/russ/conf/debug.conf -c main:addr=

Notes:

  • main:addr is set to empty to clear the setting
  • an empty main:addr or non-existent main:addr setting tells ruspawn to automatically select a socket file path

Connect to the daytime service:

No Format
ruexec /tmp/.russ-30262-Sw5KCO/daytime

Show the processes created:

No Format
jdm      30263  1542  0 09:22 pts/43   00:00:00 rureap 30264 /tmp/.russ-30262-Sw5KCO
jdm      30264 30263  0 09:22 pts/43   00:00:00 ruspawn -f /etc/russ/conf/debug.conf -c main addr  -c main addr /tmp/.russ-30262-Sw5KCO

Stop the server:

...

Children Display