This chapter describes lstcsh, an extended version of the tcsh command interpreter. The lstcsh interpreter provides transparent load sharing of user jobs.
This chapter is not a general description of the tcsh shell; only the load sharing features are described in detail.
lstcsh is a convenient way for you to take advantage of LSF. Your commands are sent transparently for execution on faster hosts to improve response time or you can run commands on remote hosts explicitly.
Resource requirements for specific commands can be configured using task lists; see `Configuring Resource Requirements' on page 53. Remote execution is transparent to the user; keyboard signals such as ctrl-z and ctrl-c are automatically sent to the remote task.
Interactive tasks, including lstcsh, are not supported on Windows NT.
If you normally use some other shell, you can start lstcsh from the command line. Make sure that the LSF commands are in your PATH environment variable and then enter lstcsh. If you have a .cshrc file in your home directory, lstcsh reads it to set variables and aliases. Use the exit command to get out of lstcsh.
If your system administrator allows, you can use LSF as your login shell. The /etc/shells file contains a list of all the shells you are allowed to use as your login shell. The chsh command can set your login shell to any of those shells. If the /etc/shells file does not exist, you cannot set your login shell to lstcsh.
For example, user3 can run the command:
% chsh user3 /usr/local/lsf/bin/lstcsh
The next time user3 logs in, the login shell will be lstcsh.
If you cannot set your login shell using chsh, you can use one of the standard system shells to start lstcsh when you log in. The easiest way is to use chsh to set /bin/sh to be your login shell and then edit the .profile file in your home directory to start lstcsh, as shown below.
SHELL=/usr/local/lsf/bin/lstcsh
export SHELL
exec $SHELL -l
Every time you enter a command, lstcsh looks in your task lists to determine whether the command can be executed on a remote host and to find the configured resource requirements for the command. See `Configuring Resource Requirements' on page 53 for more information about task lists.
If the command can be executed on a remote host, lstcsh calls the LIM to find the best available host. The first time a command is run on a remote host, a server shell is started on that host. The command is sent to the server shell, and the server shell starts the command on the remote host. All commands sent to the same host use the same server shell, so the start-up overhead is only incurred once.
If no host is found that meets the resource requirements of your command, it is run on the local host.
You can explicitly specify the eligibility of a command line for remote execution using the `@' character. It may be anywhere in the command line except in the first position (`@' as the first character on the line is used to set the value of shell variables).
Host redirection overrides the task lists, so you can force commands from your local task list to execute on a remote host or override the resource requirements for a command.
`@' 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 executed on the local host only. `@' followed by `/' and a resource requirement string 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.
% hostname @hostD
<< remote execution on hostD >>
hostD
% hostname @/type==alpha
<< remote execution on hostB >>
hostB
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.
You do not have to type in resource requirements for each command line you type if you put these task names into remote task list together with their resource requirements by running lsrtasks.
Job control in lstcsh is the same as in tcsh except for remote background jobs. lstcsh numbers shell jobs separately for each execution host.
The output of the built-in command jobs lists the background jobs together with their execution hosts. This break of transparency is intentional to provide you with more control over your background jobs.
% sleep 30 @hostD &
<< remote execution on hostD >>
[1] 27568
% sleep 40 @hostD &
<< remote execution on hostD >>
[2] 10280
% sleep 60 @hostB &
<< remote execution on hostB >>
[1] 3748
% jobs
<hostD>
[1] + Running sleep 30
[2] Running sleep 40
<hostB>
[1] + Running sleep 60
To bring a remote background job to the foreground, the host name must be specified together with `@', as in the following example:
% fg %2 @hostD
<< remote execution on hostD >>
sleep 40
lstcsh supports two built-in commands to control load sharing, lsmode and connect.
The lsmode command takes a number of arguments that control how lstcsh behaves. With no arguments, lsmode displays the current settings:
% lsmode
LSF 3.1
Copyright 1992-1997 Platform Computing Corporation
LSF enabled, local mode, LSF on, verbose, no_eligibility_verbose, notim ing.
The lsmode command reports that LSF is enabled if lstcsh was able to contact the LIM when it started up. If LSF is disabled, no load-sharing features are available.
lsmode [on | off]
Turns load sharing on or off. The default is on.lsmode [local | remote]Setslstcshto use local or remote mode. The default is local. Refer to `Modes of Operation' on page 154 for a description of local and remote modes.
lsmode [e | -e]Turns on (e) or off (-e) eligibility verbose mode. If eligibility verbose mode is on,lstcshshows whether the command is eligible for remote execution, and displays the resource requirement used if the command is eligible. The default is off.
lsmode [v | -v]Turns on (v) or off (-v) task placement verbose mode. If verbose mode is on,lstcshdisplays the name of the host where the command is run, if the command is not run on the local host. The default is on.
lsmode [t | -t]Turns on (t) or off (-t) wall clock timing. If timing is on, the actual response time of the command is printed. This time includes all remote execution overhead. The default is off.
lstcsh opens a connection to a remote host when the first command is executed remotely on that host. The same connection is used for all future remote executions on that host. The lstcsh connect command with no argument displays the connections that are currently open.
The connect host command creates a connection to the named host. By connecting to a host before any command is run, the response time is reduced for the first remote command sent to that host.
lstcsh has a limited number of ports available to connect to other hosts. By default each shell can only connect to 15 other hosts.
% connect
CONNECTED WITH SERVER SHELL
hostA +
% connect hostB
Connected to hostB
% connect
CONNECTED WITH SERVER SHELL
hostA +
hostB -
The server shell is a process created on the remote host to handle lstcsh jobs. The server shell is started when the first command is executed on the remote host. In the previous example, the connect command created a connection to host hostB, but the server shell has not started.
LSF maintains two task lists for each user, a local list and a remote list. Commands in the local list must be executed locally. Commands in the remote list can be executed remotely. If a command is in neither list, you can choose how lstcsh handles the command.
lstcsh has two modes of operation: local and remote. The local mode is the default mode. In local mode, a command line is eligible for remote execution only if all of the commands on the line are present in the remote task list, or if the `@' character is specified on the command line to force it to be eligible. In remote mode, a command line is considered eligible for remote execution, if none of the commands on the line is in the local task list.
Local mode is conservative and can fail to take advantage of the performance benefits and load-balancing advantages of LSF. Remote mode is aggressive and makes more extensive use of LSF. However, remote mode can cause inconvenience when lstcsh tries to send host-specific commands to other hosts.
Using the LSF commands lsltasks(1) and lsrtasks(1), you can inspect and change the memberships of the local and remote task lists. You can optionally associate resource requirements with each command in the remote list to help LSF find a suitable execution host for the command. If there are multiple eligible commands on a command line, their resource requirements are combined for host selection. See `Remote Task List File' on page 53 for more information on using task lists and resource requirements.
When a command is running in the foreground on a remote host, all keyboard input (type-ahead) is sent to the remote host. If the remote command does not read the input, it is lost. lstcsh has no way of knowing whether the remote command reads its standard input. The only way to provide any input to the command is to send everything available on the standard input to the remote command in case the remote command needs it. As a result, any type-ahead entered while a remote command is running in the foreground, and not read by the remote command, is lost.
The `@' character has a special meaning when it is preceded by white space. This means that the `@' must be escaped with a backslash `\' to run commands with arguments that start with `@', like finger. This is an example of using finger to get a list of users on another host:
% finger @other.domain
Normally the finger command tries to contact the named host. Under lstcsh, the `@' character is interpreted as a request for remote execution, so the shell tries to contact the RES on the host other.domain to remote execute the finger command. If this host is not in your LSF cluster, the command fails. When the `@' character is escaped, it is passed to finger unchanged and finger behaves as expected.
% finger \@hostB
You should write shell scripts in /bin/sh and use the lstools commands for load sharing. However, lstcsh can be used to write load-sharing shell scripts.
By default, an lstcsh script is executed as a normal tcsh script with load-sharing disabled. The lstcsh -L option tells the lstcsh that the script should be executed with load sharing enabled, so individual commands in the script may be executed on other hosts.
There are three different ways to run an lstcsh script with load sharing enabled: run lstcsh -L script, start an interactive lstcsh and use the source command to read the script in, or make the script executable and put `#! /usr/local/lsf/bin/lstcsh -L' as the first line of the script (assuming you install lstcsh in the /usr/local/lsf/bin directory).
A shell is a very complicated application by itself. lstcsh has certain limitations:
tcsh, you must compile tcsh with SHORT_STRINGS defined. This causes complications for characters flowing across machines.
fg command for remote jobs must use `@', as shown by examples in `Job Control' on page 152.
lstcsh is based on tcsh 6.03 (7 bit mode). It does not support the new features of the latest tcsh.