NAME

       rstartd - a sample implementation of a Remote Start rsh helper

SYNOPSIS

       rstartd

       rstartd.real [-c configfilename]

DESCRIPTION

       Rstartd  is  an  implementation  of  a  Remote  Start "helper" as defined in "A Flexible Remote Execution
       Protocol Based on rsh".

       This document describes the peculiarities of rstartd and how it is configured.

OPTIONS

       -c configfilename
               This option specifies the "global" configuration file that rstartd is to read.  Normally, rstartd
               is  a  shell script that invokes rstartd.real with the -c switch, allowing local configuration of
               the location of the configuration file.  If rstartd.real is started without  the  -c  option,  it
               reads /etc/X11/rstart/config.

INSTALLATION

       It  is  critical to successful interoperation of the Remote Start protocol that rstartd be installed in a
       directory which is in the "default" search path, so that default rsh requests and the ilk will be able to
       find it.

CONFIGURATION AND OPERATION

       Rstartd  is by design highly configurable.  One would like things like configuration file locations to be
       fixed, so that users and administrators can find them without searching,  but  reality  is  that  no  two
       vendors  will agree on where things should go, and nobody thinks the original location is "right".  Thus,
       rstartd allows one to relocate all of its files and directories.

       Rstartd has a hierarchy of configuration files which are executed in order when a request is made.   They
       are:
       global config
       per-user ("local") config
       global per-context config
       per-user ("local") per-context config
       config from request
       As  you might guess from the presence of "config from request", all of the config files are in the format
       of an rstart request.  Rstartd defines a few additional keywords with the INTERNAL- prefix for specifying
       its configuration.

       Rstartd  starts  by  reading  and  executing the global config file.  This file will normally specify the
       locations of the other configuration files and any systemwide defaults.

       Rstartd will then read the user's local config file, default name $HOME/.rstart.

       Rstartd will then start interpreting the request.

       Presumably one of the first lines in the request will be a CONTEXT line.  The context name  is  converted
       to lower case.

       Rstartd     will    read    the    global    config    file    for    that    context,    default    name
       /usr/lib/X11/rstart/contexts/<name>, if any.

       It will then read the user's config file for that context, default name $HOME/.rstart.contexts/<name>, if
       any.

       (If neither of these exists, rstartd aborts with a Failure message.)

       Rstartd will finish interpreting the request, and execute the program specified.

       This  allows  the  system  administrator  and  the  user  a large degree of control over the operation of
       rstartd.  The administrator has final say, because the global config file doesn't need to specify a  per-
       user config file.  If it does, however, the user can override anything from the global file, and can even
       completely replace the global context config files.

       The config files have a somewhat more flexible format than requests do; they are allowed to contain blank
       lines  and  lines  beginning with "#" are comments and ignored.  (#s in the middle of lines are data, not
       comment markers.)

       Any commands run are provided a few useful pieces of information in  environment  variables.   The  exact
       names are configurable, but the supplied defaults are:

       $RSTART_CONTEXT
       $RSTART_GLOBAL_CONTEXTS   the global contexts directory
       $RSTART_LOCAL_CONTEXTS    the local contexts directory
       $RSTART_GLOBAL_COMMANDS   the global generic commands directory
       $RSTART_LOCAL_COMMANDS    the local generic commands directory

       $RSTART_{GLOBAL,LOCAL}_CONTEXTS  should  contain  one  special  file, @List, which contains a list of the
       contexts in  that  directory  in  the  format  specified  for  ListContexts.   The  supplied  version  of
       ListContexts will cat both the global and local copies of @List.

       Generic commands are searched for in several places: (defaults)
       per-user per-context directory ($HOME/.rstart.commands/<context>)
       global per-context directory (/usr/lib/X11/rstart/commands/<context>)
       per-user all-contexts directory ($HOME/.rstart.commands)
       global all-contexts directory (/usr/lib/X11/rstart/commands)
       (Yes,  this  means  you  can't  have an all-contexts generic command with the same name as a context.  It
       didn't seem like a big deal.)

       Each of these directories should have a file called @List that gives the names and  descriptions  of  the
       commands in that directory in the format specified for ListGenericCommands.

CONFIGURATION KEYWORDS

       There  are  several  "special"  rstart  keywords  defined  for  rstartd  configuration.  Unless otherwise
       specified, there are no defaults; related features are disabled in this case.

       INTERNAL-REGISTRIES name ...
               Gives a space-separated list of "MISC" registries  that  this  system  understands.   (Registries
               other than this are accepted but generate a Warning.)

       INTERNAL-LOCAL-DEFAULT relative_filename
               Gives the name ($HOME relative) of the per-user config file.

       INTERNAL-GLOBAL-CONTEXTS absolute_directory_name
               Gives the name of the system-wide contexts directory.

       INTERNAL-LOCAL-CONTEXTS relative_directory_name
               Gives the name ($HOME relative) of the per-user contexts directory.

       INTERNAL-GLOBAL-COMMANDS absolute_directory_name
               Gives the name of the system-wide generic commands directory.

       INTERNAL-LOCAL-COMMANDS relative_directory_name
               Gives the name ($HOME relative) of the per-user generic commands directory.

       INTERNAL-VARIABLE-PREFIX prefix
               Gives the prefix for the configuration environment variables rstartd passes to its kids.

       INTERNAL-AUTH-PROGRAM authscheme program argv[0] argv[1] ...
               Specifies  the  program  to run to set up authentication for the specified authentication scheme.
               "program argv[0] ..." gives the program to run and its arguments, in the same form  as  the  EXEC
               keyword.

       INTERNAL-AUTH-INPUT authscheme
               Specifies the data to be given to the authorization program as its standard input.  Each argument
               is passed as a single line.  $n, where n is a number, is replaced by the  n'th  argument  to  the
               "AUTH authscheme arg1 arg2 ..." line.

       INTERNAL-PRINT arbitrary text
               Prints  its  arguments  as  a  Debug message.  Mostly for rstartd debugging, but could be used to
               debug config files.

NOTES

       When using the C shell, or any other shell which runs a script every  time  the  shell  is  started,  the
       script may get run several times.  In the worst case, the script may get run three times:
       By rsh, to run rstartd
       By rstartd, to run the specified command
       By the command, eg xterm
       rstartd currently limits lines, both from config files and requests, to BUFSIZ bytes.

       DETACH  is  implemented  by  redirecting  file  descriptors  0,1,  and  2 to /dev/null and forking before
       executing the program.

       CMD is implemented by invoking $SHELL (default /bin/sh) with "-c" and the specified command as arguments.

       POSIX-UMASK is implemented in the obvious way.

       The authorization programs are run in  the  same  context  as  the  target  program  -  same  environment
       variables, path, etc.  Long term this might be a problem.

       In the X context, GENERIC-CMD Terminal runs xterm.  In the OpenWindows context, GENERIC-CMD Terminal runs
       cmdtool.

       In the  X  context,  GENERIC-CMD  LoadMonitor  runs  xload.   In  the  OpenWindows  context,  GENERIC-CMD
       LoadMonitor runs perfmeter.

       GENERIC-CMD  ListContexts  lists  the  contents  of  @List  in both the system-wide and per-user contexts
       directories.  It is available in all contexts.

       GENERIC-CMD ListGenericCommands lists the contents of @List in  the  system-wide  and  per-user  commands
       directories,  including  the  per-context subdirectories for the current context.  It is available in all
       contexts.

       CONTEXT None is not implemented.

       CONTEXT Default is really dull.

       For installation ease, the "contexts" directory in the distribution  contains  a  file  "@Aliases"  which
       lists  a  context  name and aliases for that context.  This file is used to make symlinks in the contexts
       and commands directories.

       All MISC values are passed unmodified as environment variables.

       One can mistreat rstartd in any number of ways, resulting in anything from stupid behavior to core dumps.
       Other  than by explicitly running programs I don't think it can write or delete any files, but there's no
       guarantee of that.  The important thing is that (a) it probably won't do anything REALLY stupid  and  (b)
       it runs with the user's permissions, so it can't do anything catastrophic.

       @List  files need not be complete; contexts or commands which are dull or which need not or should not be
       advertised need not be listed.  In particular, per-user @List files should not list things which  are  in
       the  system-wide  @List  files.   In  the  future,  perhaps  ListContexts  and  ListGenericCommands  will
       automatically suppress lines from the system-wide files when there are per-user  replacements  for  those
       lines.

       Error  handling  is  OK to weak.  In particular, no attempt is made to properly report errors on the exec
       itself.  (Perversely, exec errors could be reliably reported when detaching, but  not  when  passing  the
       stdin/out socket to the app.)

       If  compiled with -DODT1_DISPLAY_HACK, rstartd will work around a bug in SCO ODT version 1.  (1.1?)  (The
       bug is that the X clients are all compiled with a bad library that doesn't know how to look host names up
       using  DNS.   The  fix  is  to  look up a host name in $DISPLAY and substitute an IP address.)  This is a
       trivial example of an incompatibility that rstart can hide.

SEE ALSO

       rstart(1), rsh(1), A Flexible Remote Execution Protocol Based on rsh

AUTHOR

       Jordan Brown, Quarterdeck Office Systems