XRSH(1) 						      General Commands Manual							   XRSH(1)

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 automati-
       cally 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  fac-
       tors.  If X is unavailable on the remote host or the local terminal emulator has better features, use xrlogin.  In general, the author rec-
       ommends 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 compat-
       ible 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-xter-
	      minal", "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 com-
	      mand), 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 mecha-
	      nism 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  hav-
	      ing 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 XAUTHOR-
	      ITY".  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 "environ-
	      ment".

       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>.

X Version 11							     Release 6								   XRSH(1)