XRSH(1)XRSH(1)NAMExrsh - start an X program on a remote machine
SYNOPSISxrsh [ -help ] [ -version ] [ -l username ] [ -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 dis-
play its windows on the current server's screen by propa-
gating the $DISPLAY environment variable. If not speci-
fied, the default client is xterm. Xrsh automatically
selects rsh(1), remsh(1) or rcmd(1) to execute remote com-
mands, 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 authoriza-
tion 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 sit-
uations.
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.
X Version 11 Release 6 1
XRSH(1)XRSH(1)
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 impos-
sible 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 con-
trol) 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 ter-
minal. From then on it propagates the name of that
host to all remote hosts via the environment vari-
able $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 con-
trol or if you use another mechanism for access
control.
X Version 11 Release 6 2
XRSH(1)XRSH(1)
Finally, authtype "environment" automatically prop-
agates 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 com-
mand 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.
-pass envlist
Envlist is a quote delimited string naming an arbi-
trary 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".
X Version 11 Release 6 3
XRSH(1)XRSH(1)
XRSH_AUTH_TYPE
This environment variable can be used to specify
the default type of authorization or access con-
trol. The values it can be set to are the same as
the values for the argument -auth.
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).
EXAMPLESxrsh yoda
Start an xterm on the host yoda which displays on
the current X server. Use xhost for access con-
trol.
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
X Version 11 Release 6 4
XRSH(1)XRSH(1)
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 spe-
cific authorization and don't redirect stan-
dard/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 direc-
tory 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@bbn.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 ALSOxrlogin(1), rsh(1), xhost(1), xauth(1)AUTHOR
James J. Dempsey <jjd@bbn.com> with help and suggestions
from many people including gildea@expo.lcs.mit.edu,
dm@think.com, dgreen@cs.ucla.edu and rosen@cns.bu.edu,
<eero@whitechapel.media.mit.edu>, and <mar-
tin@whitechapel.media.mit.edu>.
X Version 11 Release 6 5