unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



rstartd(1X)							  rstartd(1X)
X11R6									X11R6



NAME

  rstartd - a sample implementation of a Remote	Start rsh helper

SYNOPSIS

  rstartd, rstartd.real	[-c configfilename]

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 <&lt;XRoot>&gt;/lib/X11/rstart/config, where <&lt;XRoot>&gt; refers to the
      root of the X11 install tree.

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

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	con-
  figuration 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 direc-
  tories.

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

  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
  <&lt;XRoot>&gt;/lib/X11/rstart/contexts/<&lt;name>&gt;, if any.

  It will then read the	user's config file for that context, default name
  $HOME/.rstart.contexts/<&lt;name>&gt;, 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 does not 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		   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 cannot have an all-contexts generic command with	the
  same name as a context.  It did not 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 configura-
  tion.	 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 direc-
      tory.

  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  nth 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, for example, 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 pro-
  gram -- same environment variables, path, and	so forth.  Long	term this
  might	be a problem.

  In the X context, GENERIC-CMD	Terminal runs xterm. In	the OpenWindows	con-
  text,	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 subdirec-
  tories 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 con-
  tains	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
  do not think it can write or delete any files, but there's no	guarantee of
  that.	 The important thing is	that (a) it probably will not do anything
  REALLY stupid	and (b)	it runs	with the user's	permissions, so	it cannot 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 particu-
  lar, per-user	@List files should not list things which are in	the system-
  wide @List files.  In	the future, perhaps ListContexts and ListGenericCom-
  mands	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 prop-
  erly 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 does not 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(1X), rsh(1), A	Flexible Remote	Execution Protocol Based on rsh



AUTHOR

  Jordan Brown,	Quarterdeck Office Systems