lstcsh - load sharing tcsh, supported by LSF (Load Sharing Facility)
lstcsh [ -bcdefimnstvVxXL ] [ argument ... ]
lstcsh is an enhanced version of tcsh(1) . tcsh is itself an enhanced version of the Berkeley UNIX C-shell, csh(1) . lstcsh behaves exactly like tcsh, except that it includes a load sharing capability with transparent remote job execution, built on top of LSF. If a command line is considered eligible for remote execution, LSF will select a suitable host - typically a powerful and/or lightly loaded host that can execute the command line correctly - and send the command line to that host. Because lstcsh is based on LSF, read the LSF User's Guide before using lstcsh.
lstcsh provides a high degree of network transparency. Command lines executed on remote hosts behave the same as they do on the local host. The remote execution environment is designed to mirror the local one as closely as possible by using the same values for environment variables, terminal setup, current working directory, file creation mask, and so on. Each modification to the local set of environment variables is automatically reflected on remote hosts. Note that shell variables, the nice value, and resource limits are not automatically propagated to remote hosts.
lstcsh accepts all the options used by tcsh. See tcsh(1) for the meaning of specific options. lstcsh provides an additional option -L, which tells the lstcsh that the script must be executed with load sharing enabled. By default, a lstcsh script is executed as a normal tcsh script with load sharing disabled. There are three ways to run a lstcsh script with load sharing enabled: to execute the script with the -L option, to use the built-in command source to execute a script, and to put «#!/local/bin/lstcsh -L» as the first line of the script (assuming you install lstcsh in /local/bin). Using `@' or lsmode (see below) in a script will not enable load sharing if the script has not been executed using one of these three ways.
LSF maintains two task lists for each user, a local list and a remote list. A task is either a UNIX command or a user-created executable program. Tasks in the local list must be executed locally. Tasks in the remote list can be executed remotely. For those tasks in neither list, their treatment by lstcsh depends on its current mode of operation. lstcsh has two different modes of operation: local and remote. The local mode is the default mode. In the local mode of operation, a command line is eligible for remote execution if all of the tasks on the line are present in the remote task list, or if the metacharacter `@' is specified on the command line to force it to be eligible. In the remote mode of operation, a command line is considered eligible for remote execution if none of the tasks on the line is specified in the local task list. The local mode of operation is conservative, and can fail to take advantage of the performance benefits and load balancing advantages of LSF. The remote mode of operation is aggressive, and promotes an extensive use of LSF.
Using the LSF commands lsltasks(1) and lsrtasks(1) , you can inspect and change the memberships of the local and remote task lists. Moreover, you can optionally associate resource requirements with each task in the remote list to help LSF find a suitable execution host for the task. If there are multiple eligible tasks on a command line, their resource requirements are combined for host selection. See the LSF User's Guide for more information on resource requirements.
You can explicitly specify the eligibility of a command line for remote execution using the metacharacter `@'. It may be anywhere in the command line except in the first position (which is then used to set the value of shell variables). `@' followed by nothing means that the command line is eligible for remote execution. `@' followed by a host name forces the command line to be executed on that host. `@' followed by the reserved word ``local'' forces the command line to be noneligible for remote execution (and therefore executed on the local host). `@' followed by `/' and optional resource requirement characters means that the command is eligible for remote execution, and that the given resource requirements must be used instead of those in the remote task list. For ease of use, the host names and the reserved word ``local'' following `@' can all be abbreviated as long as they do not cause ambiguity. Similarly, when specifying resource requirements following the `@', it is necessary to use `/' only if the first requirement characters specified are also the first characters of a host name.
Job control in lstcsh is exactly the same as in tcsh except for remote
background jobs. lstcsh numbers background jobs separately for each of the
hosts that are used to execute them. The output of the built-in command
jobs lists the background jobs together with their execution hosts. This
break of transparency is intentional in order to provide you with more control
over your background jobs. To bring a remote background job to the
foreground, the host name must be specified together with `@', as in the
following example:
fg %2 @orange
In addition to the builtin commands in tcsh, lstcsh provides the following additional built-in commands:
lsmode [ {on | off} ] [ {local | remote} ] [ [-]v ] [ [-]e ] [ [-]t ] lsmode controls the operation modes of the lstcsh. If used without an argument, it lists the current modes of the lstcsh. The meaning of the options for lsmode are:
[-]e Turn the eligibility verbose mode on or off (if preceded by `-'). When this mode is on, you are informed of each command line's eligibility for remote execution. The default is off.
[-]v Turn the task placement verbose mode on or off (if preceded by `-'). When this mode is on, you are informed each time a command line is sent to a remote host for execution. The default is on.
[-]t Turn the timing facility on or off (if preceded by `-'). The timing facility displays (after the execution of a job) the total elapsed time in seconds of the job, that is, the total real clock time elapsed from the time you submit the command to the time the prompt comes back. This is an impartial way of comparing the response time of jobs submitted locally or remotely, because all the load sharing overhead is included in the elapsed time displayed. (The csh time built-in does not include the remote execution overhead). The default is off.
on/off
turn load sharing on and off. When turned off, you can send a
command line to a remote host only if forced eligibility (@) is
specified. The default is on.
local | remote
set the operation mode to local or remote. The default is local.
See ``TWO MODES OF OPERATION''.
connect [ host_name ... ]
Establish connections with remote hosts specified by the user.
Without any argument, connect lists all the remote hosts to which a
lstcsh connection has been established. A plus sign (`+') with a
remote host indicates that a server-shell has also been started on it.
lsrtasks [+|- task_name/res_req ...]
Display or update the user's remote task list. This command has the
same function as the external command lsrtasks(1)
, except that the
modified remote task list takes effect immediately for the current
lstcsh. See lsrtasks(1)
for more details.
lsltasks [+|- task_name ...]
Display or update the user's local task list. This command has the
same function as the external command lsltaks(1)
, except that the
modified local task list takes effect immediately for the current
lstcsh. See lsltasks(1)
for more details.
There are three optional configuration files that are of interest to lstcsh users: .shrc, .hostrc, and .lsftask. .shrc and .hostrc are used by lstcsh alone, whereas .lsftask is used by LSF to determine general task eligibility.
~/.shrc
when you want an execution environment on remote hosts that is different
from that on the local host. This file is sourced automatically
on a remote host when a connection is established. For example,
if the remote host is of different type, you may need to run a version
of the executable for that particular host type, therefore it may be
necessary to set a different path on the remote host.
~/.hostrc
contains a list of host names to which the user wants to be connected
(asynchronously in the background) at lstcsh startup time. This saves
the time spent in establishing the connections dynamically during executions
of shell commands. Once a connection is set up, you can execute
further remote commands on those connected hosts with very little
overhead.
~/.lsftask
contains the lists of remote and local tasks that you want to be added
to the respective system default lists. Each line of this file is of
the form ``task/resreq'', where task is the name of a task, and resreq
is a string specifying the resource requirements of this task. If
resreq is not specified, the command is executed on machines of the
same type as the local host.
Type-ahead for the next command is discarded when a job is executing in the foreground on a remote host.
It is not possible to provide input data to load sharing shell scripts (that is, shell scripts whose content is load shared).
csh(1) , tcsh(1) , lsrtasks(1) , lsltasks(1) , lseligible(1) , lsinfo(1) , lsload(1)