Provided by: xrsh_5.92-8_all 
NAME
xrsh - start an X program on a remote machine
SYNOPSIS
xrsh [ -help ] [ -version ] [ -l username ] [ -e rshprog ] [ -auth authtype ] [ -screen
screen-# ] [ -pass envlist ] [ -debug ] [ -debug2 ] remote-host [ X-command [ arguments
... ] ]
DESCRIPTION
Xrsh runs the given X command on a remote host. It sets up the environment for that
command such that it will display its windows on the current server's screen by
propagating the $DISPLAY environment variable. If not specified, the default client is
xterm. Xrsh automatically selects ssh(1), rsh(1), remsh(1) or rcmd(1) to execute remote
commands, depending on what is available the O/S environment.
Xrsh automatically handles authentication so that the remote client will be allowed to
open windows on the server. It does this in several different ways depending on the value
of the $XRSH_AUTH_TYPE environment variable or the -auth argument.
By default, xrsh will use xhost to enable the remote client to open a server connection.
It can also be told to use xauth to merge local keys into a remote authorization file.
Or it can pass the $XAUTHORITY environment variable to the remote host in order to share a
common NFS mounted authority file. It can also be directed to do nothing in the case
where no explicit authorization is necessary.
Users who just want a remote terminal window might look at xrsh's sister command,
xrlogin(1). Xrlogin uses a locally running xterm to open an rlogin connection to a remote
host. The decision on whether to use "xrsh host xterm" or "xrlogin host" should be based
on several factors. If X is unavailable on the remote host or the local terminal emulator
has better features, use xrlogin. In general, the author recommends using xrsh over
xrlogin in most situations.
If the command to execute on the remote host is an xterm, xrsh automatically passes the
-name argument to xterm with a value of "xterm-hostname" where hostname is the name of the
remote host. This allows the user to specify resources in their server's resource manager
which are specific to xterms from a given host. For example, this feature can be used to
make all xterm windows from a given remote host be the same color or use a specific font
or start up in a specific place on the screen. Xrlogin passes the same string so they are
compatible in this regard. This feature can be overridden by specifying your own -name
argument on the xterm command line.
If the command to execute on the remote host is an xterm, xrsh specifies that the default
title for the new xterm will be "xterm@hostname" where hostname is the name of the remote
host. This can also be overridden by specifying your own -title argument on the xterm
command line.
Xrsh is very careful not to leave any extra processes on either the local or remote
machine waiting around for the client to exit. In some remote environments (particularly
some Sys V implementations of csh and rsh), this is impossible and xrsh should be run as a
background command.
OPTIONS
Note that xrsh options precede the given X command and its arguments.
-auth authtype
Choose what type of X authorization (or access control) is going to be used.
Authtype can be one of "xhost", "xauth", "xhost-xterminal", "environment", or
"none". The default is xhost, but the default can be set by setting the value of
the environment variable $XRSH_AUTH_TYPE.
If xhost is specified and the X server is running on the local machine, xhost will
be run locally to enable the remote host to open an X connection. If the server is
on a third host (not the one where xrsh is running and not the one where you wish
to run the command), rsh will be used to run xhost on the server host to authorize
the host where the command will be run.
If xauth is specified, then xrsh will merge the entries for the server from the
local $XAUTHORITY file into that of the remote host using rsh.
The authtype xhost-xterminal is intended for use by people using X terminals. If
xhost-xterminal is used, then the first time xrsh is run, it runs xhost locally to
enable the remote host for access. This should work since (theoretically) the
first time it is run is on the XDMCP host for the X terminal. From then on it
propagates the name of that host to all remote hosts via the environment variable
$XHOST. In subsequent invocations from remote hosts, xrsh uses rsh to connect to
the host $XHOST and run xhost to enable new remote hosts.
Authtype "none" does no explicit work for access control. Use this if you don't
enable access control or if you use another mechanism for access control.
Finally, authtype "environment" automatically propagates the environment variable
$XAUTHORITY to remote hosts, assuming that it is an NFS mounted location that can
be accessed from all hosts.
-debug Normally xrsh redirects standard input and standard output to /dev/null in an
effort to cause unneeded rshd and shell processes to exit. As a result, the user
can't usually see any errors that might occur (like a "Permission denied." from
rsh). If you are having trouble getting xrsh to work with a remote host, try
giving the -debug switch to see if any errors are being generated.
-debug2
This switch causes xrsh to turn on the -x option in the shell so that the user can
see every shell command executed by xrsh. Only use this script if you are
debugging the xrsh code itself.
-help Print out the argument list to standard output.
-l username
Use the -l switch to specify a different user name to use for logging in via rsh on
the remote host.
-e rshprog
The -e switch can be used to set a different remote shell program, e.g. ssh. The
default is remsh or rsh, depending on your system. This flag overrides $XRSH_RSH.
-pass envlist
Envlist is a quote delimited string naming an arbitrary set of environment
variables to pass on to the shell environment on the remote host. If one wanted to
set $XRSH_AUTH_TYPE and $XAUTHORITY to the remote host, one could use: -pass
"XRSH_AUTH_TYPE XAUTHORITY". A default set of environment variables to pass may be
set using the environment variable $XRSH_ENVS_TO_PASS.
-screen screen-#
Specify a different screen on the server on which to display the remote client.
-version
Print out version information and exit.
ENVIRONMENT
The environment variables XRSH_AUTH_TYPE and XRSH_ENVS_TO_PASS which can be used to set
switch defaults are overridden if the equivalent switch is specified as well.
XAUTHORITY
The $XAUTHORITY environment variable is passed to the remote host if the authtype
specified by -auth or $XRSH_AUTH_TYPE is "environment".
XRSH_AUTH_TYPE
This environment variable can be used to specify the default type of authorization
or access control. The values it can be set to are the same as the values for the
argument -auth.
XRSH_RSH
This variable can redefine the remote shell program to use, e.g. ssh.
XRSH_RSH_ERRORS
If the environment variable XRSH_RSH_ERRORS is set to the name of a file, any rsh
errors will appear in that file on the remote host. If that variable is unset,
error messages will be thrown away unless the -debug switch is given. (Note: don't
use ~ in the filename because it will expand to ~ on the local host, but try to put
the errors in that file on the remote host.)
XRSH_ENVS_TO_PASS
COMMON PROBLEMS
Make sure your PATH environment variable on the remote host is set in your .cshrc or
.bashrc so that rsh programs have access to it. (/bin/sh and /bin/ksh users have a hard
time time here since their shells don't execute any init files under rsh. You can use the
XRSH_ENVS_TO_PASS environment variable to pass the PATH environment variable to the remote
host. Optionally, you can type a full path to xrsh in that case. (E.g. xrsh remote-
host /usr/bin/X11/xterm))
Make sure your PATH environment variable on the remote host includes the directory
containing the X programs. This is often /usr/bin/X11 or /usr/local/bin/X11.
Make sure you have rsh configured to work on the remote host. You can test this by
typing: rsh remote-host echo '$PATH' This will prove that rsh works and show you the PATH
that will be used on the remote host. If you get "Permission denied." you probably need
to update your ~/.rhosts file on the remote host. See rlogin(1).
EXAMPLES
xrsh yoda
Start an xterm on the host yoda which displays on the current X server. Use xhost
for access control.
xrsh -auth xauth underdog emacs
Start an emacs on the host underdog. Merge xauth authorization entries for this
server into the authority file on the remote host.
xrsh -l mjd -auth none -pass XRSH_AUTH_TYPE -debug tigger xterm -fn 5x7
Start an xterm on the host tigger in a very small font, propagate the environment
variable $XRSH_AUTH_TYPE to the remote host, login to the remote host using the id
"mjd", don't do any specific authorization and don't redirect standard/error output
to /dev/null so I can see any errors.
BUGS
If the values of the environment variables specified in -pass or $XRSH_ENVS_TO_PASS
contain quote characters, xrsh will have difficulty.
If the remote host can't resolve the hostname of the server host (through /etc/hosts, DNS
or NIS), the remote client will not be able to open a connection to the server.
System V users may need to make the first line of the script begin with colon (:).
If you think you have found a bug, the first thing you should do is to check on ftp.x.org
in the contrib directory using anonymous FTP to see if there is a new version of xrsh
there that already fixes the bug. If not, send email to "jjd@jjd.com" and be sure to have
the token xrsh somewhere in the Subject: line. Be sure to report the operating system
type and version at both ends of the xrsh connection and a description of the command you
are using and what authentication mode you are using.
SEE ALSO
xrlogin(1), rsh(1), xhost(1), xauth(1)
AUTHOR
James J. Dempsey <jjd@jjd.com> with help and suggestions from many people including
gildea@intouchsys.com, dm@bbn.com, dgreen@cs.ucla.edu and rosen@cns.bu.edu,
<eero@whitechapel.media.mit.edu>, and <martin@whitechapel.media.mit.edu>.