home *** CD-ROM | disk | FTP | other *** search
/ Chip 2001 August - Disc 2 / chip_20018102_hu.iso / linux / X-4.1.0 / doc / rstartd.txt < prev    next >
Text File  |  2001-06-27  |  10KB  |  230 lines
  1. rstartd - a sample implementation of an Remote Start rsh helper
  2. hjb 02/24/93
  3.  
  4. Copyright (c) 1993 Quarterdeck Office Systems
  5.  
  6. Permission to use, copy, modify, distribute, and sell this software and
  7. its documentation for any purpose is hereby granted without fee, provided
  8. that the above copyright notice appear in all copies and that both that
  9. copyright notice and this permission notice appear in supporting
  10. documentation, and that the name Quarterdeck Office Systems, Inc. not
  11. be used in advertising or publicity pertaining to distribution of this
  12. software without specific, written prior permission.
  13.  
  14. THIS SOFTWARE IS PROVIDED `AS-IS'.  QUARTERDECK OFFICE SYSTEMS, INC.,
  15. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING WITHOUT
  16. LIMITATION ALL IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
  17. PARTICULAR PURPOSE, OR NONINFRINGEMENT.  IN NO EVENT SHALL QUARTERDECK
  18. OFFICE SYSTEMS, INC., BE LIABLE FOR ANY DAMAGES WHATSOEVER, INCLUDING
  19. SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES, INCLUDING LOSS OF USE,
  20. DATA, OR PROFITS, EVEN IF ADVISED OF THE POSSIBILITY THEREOF, AND
  21. REGARDLESS OF WHETHER IN AN ACTION IN CONTRACT, TORT OR NEGLIGENCE, ARISING
  22. OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  23.  
  24. Rstartd is an implementation of an Extended rsh "helper" as defined in
  25. my "Remote Start protocol" document.
  26.  
  27. This document describes the peculiarities of rstartd and how it is
  28. configured.
  29.  
  30. Rstartd is by design highly configurable.  One would like things like
  31. configuration file locations to be fixed, so that users and administrators
  32. can find them without searching, but reality is that no two vendors will
  33. agree on where things should go, and nobody thinks the original location
  34. is "right".  Thus, rstartd allows one to relocate _all_ of its files and
  35. directories.
  36.  
  37. Rstartd has a hierarchy of configuration files which are executed in
  38. order when a request is made.  They are:
  39.  
  40.     global config
  41.     per-user ("local") config
  42.     global per-context config
  43.     per-user ("local") per-context config
  44.     config from request
  45.  
  46. As you might guess from the presence of "config from request", all of the
  47. config files are in the format of an rstart request.  Rstartd defines a few
  48. additional keywords with the INTERNAL- prefix for specifying its configuration.
  49.  
  50. Normally, a shell script is installed as "rstartd"; this script provides
  51. the name of the global configuration file to the "real" rstartd using
  52. its -c option.  If rstartd is directly, it defaults to
  53. /usr/lib/X11/rstart/config.
  54.  
  55. Rstartd starts by reading and executing the global config file.
  56. This file will normally specify the locations of the other configuration
  57. files and any systemwide defaults.
  58.  
  59. Rstartd will then read the user's local config file, default name
  60. $HOME/.rstart.
  61.  
  62. Rstartd will then start interpreting the request.
  63.  
  64. Presumably one of the first lines in the request will be a CONTEXT line.
  65. The context name is converted to lower case.
  66.  
  67. Rstartd will read the global config file for that context, default name
  68. /usr/lib/X11/rstart/contexts/<name>, if any.
  69.  
  70. It will then read the user's config file for that context, default name
  71. $HOME/.rstart.contexts/<name>, if any.
  72.  
  73. (If neither of these exists, rstartd aborts with a Failure message.)
  74.  
  75. Rstartd will finish interpreting the request, and execute the program
  76. specified.
  77.  
  78. This allows the system administrator and the user a large degree of control
  79. over the operation of rstartd.  The administrator has final say, because
  80. the global config file doesn't need to specify a per-user config file.
  81. If it does, however, the user can override anything from the global file,
  82. and can even completely replace the global context config files.
  83.  
  84. The config files have a somewhat more flexible format than requests do;
  85. they are allowed to contain blank lines and lines beginning with "#"
  86. are comments and ignored.  (#s in the middle of lines are data, not comment
  87. markers.)
  88.  
  89. Any commands run are provided a few useful pieces of information in
  90. environment variables.  The exact names are configurable, but the supplied
  91. defaults are:
  92.  
  93.     $RSTART_CONTEXT        the name of the context
  94.     $RSTART_GLOBAL_CONTEXTS    the global contexts directory
  95.     $RSTART_LOCAL_CONTEXTS    the local contexts directory
  96.     $RSTART_GLOBAL_COMMANDS    the global generic commands directory
  97.     $RSTART_LOCAL_COMMANDS    the local generic commands directory
  98.  
  99. $RSTART_{GLOBAL,LOCAL}_CONTEXTS should contain one special file, @List,
  100. which contains a list of the contexts in that directory in the format
  101. specified for ListContexts.  The supplied version of ListContexts will
  102. cat both the global and local copies of @List.
  103.  
  104. Generic commands are searched for in several places: (defaults)
  105.  
  106.     per-user per-context directory ($HOME/.rstart.commands/<context>)
  107.     global per-context directory (/usr/lib/X11/rstart/commands/<context>)
  108.     per-user all-contexts directory ($HOME/.rstart.commands)
  109.     global all-contexts directory (/usr/lib/X11/rstart/commands)
  110.  
  111. (Yes, this means you can't have an all-contexts generic command with the
  112. same name as a context.  It didn't seem like a big deal.)
  113.  
  114. Each of these directories should have a file called @List that gives
  115. the names and descriptions of the commands in that directory in the
  116. format specified for ListGenericCommands.
  117.  
  118. There are several "special" rstart keywords defined for rstartd configuration.
  119. Unless otherwise specified, there are no defaults; related features are
  120. disabled in this case.
  121.  
  122. INTERNAL-REGISTRIES
  123.     Gives a space-separated list of "MISC" registries that this system
  124.     understands.  (Registries other than this are accepted but generate
  125.     a Warning.)
  126.  
  127. INTERNAL-LOCAL-DEFAULT
  128.     Gives the name ($HOME relative) of the per-user config file.
  129.  
  130. INTERNAL-GLOBAL-CONTEXTS
  131.     Gives the name of the system-wide contexts directory.
  132.  
  133. INTERNAL-LOCAL-CONTEXTS
  134.     Gives the name ($HOME relative) of the per-user contexts directory.
  135.  
  136. INTERNAL-GLOBAL-COMMANDS
  137.     Gives the name of the system-wide generic commands directory.
  138.  
  139. INTERNAL-LOCAL-COMMANDS
  140.     Gives the name ($HOME relative) of the per-user generic commands
  141.     directory.
  142.  
  143. INTERNAL-VARIABLE-PREFIX
  144.     Gives the prefix for the configuration environment variables rstartd
  145.     passes to its kids.
  146.  
  147. INTERNAL-AUTH-PROGRAM authscheme program argv[0] argv[1] ...
  148.     Specifies the program to run to set up authentication for the
  149.     specified authentication scheme.  "program argv[0] ..." gives
  150.     the program to run and its arguments, in the same form as the
  151.     EXEC keyword.
  152.  
  153. INTERNAL-AUTH-INPUT authscheme
  154.     Specifies the data to be given to the authorization program as
  155.     its standard input.  Each argument is passed as a single line.
  156.     $n, where n is a number, is replaced by the n'th argument to the
  157.     "AUTH authscheme arg1 arg2 ..." line.
  158.  
  159. INTERNAL-PRINT
  160.     Prints its arguments as a Debug message.  Mostly for rstartd
  161.     debugging, but could be used to debug config files.
  162.  
  163.  
  164. Various Notes:
  165.  
  166. rstartd currently limits lines, both from config files and requests, to
  167. BUFSIZ bytes.
  168.  
  169. DETACH is implemented by redirecting file descriptors 0,1, and 2 to
  170. /dev/null and forking before executing the program.
  171.  
  172. CMD is implemented by invoking $SHELL (default /bin/sh) with "-c" and
  173. the specified command as arguments.
  174.  
  175. POSIX-UMASK is implemented in the obvious way.
  176.  
  177. The X authorization program is run in the same context as the target
  178. program - same environment variables, path, etc.  Long term this might
  179. be a problem.
  180.  
  181. In the X context, GENERIC-CMD Terminal runs xterm.
  182. In the OpenWindows context, GENERIC-CMD Terminal runs cmdtool.
  183.  
  184. In the X context, GENERIC-CMD LoadMonitor runs xload.
  185. In the OpenWindows context, GENERIC-CMD LoadMonitor runs perfmeter.
  186.  
  187. GENERIC-CMD ListContexts lists the contents of @List in both the
  188. system-wide and per-user contexts directories.  It is available in
  189. all contexts.
  190.  
  191. GENERIC-CMD ListGenericCommands lists the contents of @List in the
  192. system-wide and per-user commands directories, including the
  193. per-context subdirectories for the current context.  It is available
  194. in all contexts.
  195.  
  196. CONTEXT None is not implemented.
  197.  
  198. CONTEXT Default is really dull.
  199.  
  200. For installation ease, the "contexts" directory in the distribution contains
  201. a file "@Aliases" which lists a context name and aliases for that context.
  202. This file is used to make symlinks in the contexts and commands directories.
  203.  
  204. All MISC values are passed unmodified as environment variables.
  205.  
  206. One can mistreat rstartd in any number of ways, resulting in anything
  207. from stupid behavior to core dumps.  Other than by explicitly running
  208. programs I don't think it can write or delete any files, but there's
  209. no guarantee of that.  The important thing is that (a) it probably won't
  210. do anything REALLY stupid and (b) it runs with the user's permissions,
  211. so it can't do anything catastrophic.
  212.  
  213. @List files need not be complete; contexts or commands which are dull
  214. or which need not or should not be advertised need not be listed.
  215. In particular, per-user @List files should not list things which are in
  216. the system-wide @List files.  In the future, perhaps ListContexts and
  217. ListGenericCommands will automatically suppress lines from the
  218. system-wide files when there are per-user replacements for those lines.
  219.  
  220. Error handling is OK to weak.  In particular, no attempt is made to
  221. properly report errors on the exec itself.  (Perversely, exec errors
  222. could be reliably reported when detaching, but not when passing the
  223. stdin/out socket to the app.)
  224.  
  225. If compiled with -DODT1_DISPLAY_HACK, rstartd will work around a bug in
  226. SCO ODT version 1.  (1.1?)  (The bug is that the X clients are all compiled
  227. with a bad library that doesn't know how to look host names up using DNS.
  228. The fix is to look up a host name in $DISPLAY and substitute an IP address.)
  229. This is a trivial example of an incompatibility that rstart can hide.
  230.