RSTARTD(1)                                                          RSTARTD(1)


       rstartd - a sample implementation of a Remote Start rsh helper



       rstartd.real [-c configfilename]


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


       -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 config-
               uration  of  the  location  of  the  configuration  file.    If
               rstartd.real  is  started  without  the  -c  option,  it  reads
               <XRoot>/lib/X11/rstart/config, where <XRoot> refers to the root
               of the X11 install tree.


       It  is critical to successful interoperation of the Remote Start proto-
       col 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.


       Rstartd is by design highly configurable.  One would like  things  like
       configuration file locations to be fixed, so that users and administra-
       tors can find them without searching, but reality is that no  two  ven-
       dors will agree on where things should go, and nobody thinks the origi-
       nal 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  speci-
       fying 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

       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
       <XRoot>/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

       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 sup-
       plied defaults are:

            $RSTART_CONTEXT          the name of the 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 (<XRoot>/lib/X11/rstart/commands/<context>)
            per-user all-contexts directory ($HOME/.rstart.commands)
            global all-contexts directory (<XRoot>/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.


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

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

       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 com-
               mands directory.

               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.


       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  OpenWin-
       dows context, GENERIC-CMD LoadMonitor runs perfmeter.

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

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

       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 com-
       piled 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 substi-
       tute an IP address.)  This is a trivial example of  an  incompatibility
       that rstart can hide.


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


       Jordan Brown, Quarterdeck Office Systems

X Version 11                      Release 6.6                       RSTARTD(1)

Man(1) output converted with man2html