From: Daniel Julin <dpj+@CS.CMU.EDU>
To: lli@CS.CMU.EDU
Cc: jms@CS.CMU.EDU
Subject: [Daniel Julin: Re: Multi-Server availability ]
Date: Fri, 11 Sep 92 14:56:22 -0400
Message-Id: <11413.716237782@dpj.mach.cs.cmu.edu>
Sender: dpj@DPJ.MACH.CS.CMU.EDU

I knew I had this somewhere!!!


-- Daniel --

------- Forwarded Messages

From: Daniel Julin <dpj+@cs.cmu.edu>
Subject: Re: Multi-Server availability 
Date: Thu, 26 Mar 92 14:59:20 EST


We are now making the multi-server sources available for perusal and
experimentation by interested parties. We do not have enough resources
to provide serious support, so you're pretty much on your own to play
with them. The UNIX emulation is not complete, but it is now good
enough to compile itself entirely, and to be used for extended
experimentation. The system is in need of a good performance tuning,
but it's good enough that you won't grow old watching it... It works
on i386/i486 under recent versions of the Mach 3.0 kernel.

You can arrange to set-up a SUP by sending mail to mach@cs.cmu.edu,
and requesting the "US" system. The distribution is similar to the one
used for other Mach project sources (kernel, UNIX single-server, POE,
etc.).  We do require a BSD source license for now, because we have
assembled a variety of servers from different sources, and we don't
have time to sort out the free from the non-free.

We don't yet have a complete set of documentation for this system
(other than the sources themselves). But here are a few useful
sources:
	- the overview paper in the November 1991 Mach USENIX
	  Symposium. This is now slightly out of date in terms of
	  status, but it is still accurate for a technical /
	  philosophical overview.
	- the mach3 mailing list (mach3@cs.cmu.edu,
	  mach3-request@cs.cmu.edu). Releases messages for all the
	  Mach project activities are posted there. The multi-server
	  ones are labelled "USxx". They tend to contain a lot of
	  technical information about whatever new features were added
	  with each release. They are archived in the file
	  "MERGE_HISTORY" at the base of the source tree.
	- a paper by Paulo Guedes and myself at the 2nd International
	  Workshop on Object-orientation in Operating Systems
	  (I-WOOOS2), describing the C++ approach for the
	  implementation.


If you have specific technical questions, please address them to me or
Mark Stevenson (jms@cs.cmu.edu).


Hope this helps,

- -- Daniel --

------- Message 2

Subject: US startup
- --------

The multi-server components must be installed in
/mach_servers/us/{bin,lib}, except for the emulation library, which
must be installed as /lib/bsd_all.lib in the file system that will
constitute the root of the emulated system.

/mach_servers/bin/config_server is the "primary server". It
establishes a basic name service and starts all the other servers.  It
is controlled by the files /mach_servers/rc.us and
/mach_servers/us/lib/prefix.config. The program
/mach_servers/us/bin/fsadmin is run as part of the startup sequence to
establish the initial root name space. It is controlled by the script
/mach_servers/us/lib/STARTUP.fsadmin.

The first emulated process is created by the program
/mach_servers/bin/emul_init, itself started from config_server.
emul_init creates a new address space, loads an emulation library from
the file server, connects it to all the appropriate servers
(including a connection to a specific TTY in the tty_server), and
starts the first user-level process by executing the exec() system
call (usually with /bin/csh or /bin/login).

Both config_server and the various other servers expect to operate in
a simplified UNIX environment, in order to read configuration files
and to exec() other servers. Currently, this environment can be
provided in one of two ways:
	- start config_server under the UNIX single-server emulator.
	  This is by far the preferred solution for debugging, since
	  there is then another working UNIX system from which to run
	  gdb and attach to the various servers. This also allows the
	  tty_server to access TTY's from the single-server, such as
	  xterm windows or telnet connections.
	- start config_server under the POE emulator. This avoids the
	  need for another heavy emulator, but the multi-server must
	  then "take over" the whole machine. If it crashes, you must
	  reboot. Debugging is hard. The only TTY's available are the
	  console and the hard-wired lines (not enough networking
	  support in US yet). 
In the future, I expect that config_server will be integrated into a
stripped-down version of POE, to provide a single-level startup
service.

	  
In practice, to start a multi-server under a UX emulation, follow the
procedure below:
(1) Once only:
(1.1) Copy a multi-server release area to /mach_servers/us
(1.2) Create a fresh UFS partition to be used as the root for the US
      system. We recommend using a partition not normally mounted
      under the UX system, to avoid problems if the UFS server
      crashes, and conflicts if bopth emulators try to write the same
      partition at once. Populate this partition with all the desired
      UNIX programs that are to run under the US emulation (/bin/csh,
      /bin/ls, etc.).
(1.3) Copy bsd_all.lib to /lib/bsd_all.lib in the US root partition.
(1.4) Copy /mach_servers/us/bin/rc.us to /mach_servers/rc.us, and edit
      that file to point the UFS server(s) to the appropriate disk
      partition(s).
(1.5) Edit /mach_servers/lib/prefix.config and
      /mach_servers/lib/STARTUP.fsadmin to match the set of disk
      partitions to be used in the US environment.
(1.6) Create a file /etc/NETWORKS.US to give startup information for
      the x-kernel protocol server. The format of this file is
	a.b.c.d on xx
      where "a.b.c.d" is the IP address to be used as the local address
      by the protocol server, and "xx" is the name of the network device
      as known to the device_open() kernel call ("pc0" for a PC586 on
      most i386/i486 machines). If you omit /etc/NETWORKS.US, the
      system will look in /etc/NETWORKS, which is used by the standard
      CMU/Mach systems. Note that the x-kernel protocol server may not
      share an IP address with another UNIX emulator or a 2.6 kernel.


(2) Each time you start:
(2.1) Open a new telnet or xterm window to the machine that is to run
      the US system. Let the TTY for that window be /dev/ttyxx.
(2.2) Put /dev/ttyxx to sleep in the UX emulation, by executing "sleep
      1000000".
(2.3) cd /mach_servers/us/bin
(2.4) Execute config_server to start the whole system. The command
      line specifies the initial program to run under the
      config_server after all the servers are started. This program is
      usually emul_init. The arguments to emul_init specify the TTY to
      use and the initial UNIX program to execute. For example:
      "./config_server ./emul_init -t/dev/ttyxx_htg /bin/csh >& /tmp/LOG &"
      will start a csh connected to "/dev/ttyxx_htg", which
      corresponds to the UX TTY "/dev/ttyxx" as seen from the US
      tty_server. Instead of emul_init, other programs may be started,
      for example a sub-shell or xterm, from which the servers are
      accessible, and from which fsadmin or emul_init itself can in
      turn be started.
(2.5) Wait a few minutes for the system to come up, watching the
      output in /tmp/LOG if desired.
(2.6) A shell prompt will appear in the /dev/ttyxx window. This is the
      US emulated system. If starting with /bin/csh, the environment
      (PATH, USER, HOME, etc.) is initially empty. Set it up
      accordingly.

(3) To kill the US system:
(3.1) Kill config_server from the UX system.
(3.2) If the other servers do not die also, kill them individually.


------- Message 3

Subject: US source tree
- --------

Here is the organization for the source tree for the US system (as of
US47):

./include, ./local_include: include files internal to the US system,
	shared between various components. Originally, ./include was
	supposed to contain the only files needed to interface an
	emulation library to the rest of the system, while
	./local_include contained everything else. This distinction
	has never worked well in practice.

./mach_include_sa: a frozen copy of the Mach kernel include files.
	Periodically regenerated from the real kernel sources.

./sa_include: a few files that override the files in
	./mach_include_sa, to correct problems and defects.

./unix_include: a frozen copy of UNIX include files, that define the
	UNIX system that we are emulating.

./lib/c++: support functions for the GNU C++ compiler

./lib/mach3: a collection of libraries for basic functions needed by
	most Mach programs. Roughly equivalent to a combination of
	libmach.a and libc.a from the common release areas. Will
	someday be superseded by a standard common library for all
	Mach applications.

./lib/threads: modified version of the cthreads library, for use
	inside the US emulation library

./lib/us++: main repository for classes and common functions in the
	whole US system. Should be largely generic, and not dependent
	on UNIX semantics. Used to be called ./lib/us, but was renamed
	when we converted to C++.

./lib/ux: support classes and functions for the implementation of
	UNIX-like emulation libraries.

./lib/emul: the UNIX BSD emulation library.

./lib/emul/emul_init_prog: the emul_init program that starts the first
	emulated process.

./server/as: authentication server

./server/config: configuration/startup server (config_server, see note
	on startup)

./server/diag: diagnostics server, to keep track of error messages and
	debugging logs

./server/name: general-purpose root name server

./server/nfs: NFS client (not in use currently)

./server/pipenet: server providing local pipes and UNIX-domain
	sockets.

./server/tm: process management server (task_master)

./server/tty: TTY server

./server/ufs: UFS server (UNIX filesystems on local disk)

./pkg/malloc: a malloc tracer (not in use currently)

./pkg/netmsg: Mach Network Message Server for remote Mach IPC (not in
	use currently) 

./pkg/sunrpc: SUN RPC facility for the NFS server (not in use
	currently)

./pkg/xkernel: network server based on the x-kernel from the
	University of Arizona. Provides UDP sockets. TCP sockets are
	planned but not operational.

./utils: utility scripts and programs

./MERGE_HISTORY: a file containing a copy of every release message
	from the history of the US system. Contains many explanations
	of how things work.

./doc, ./man: some documentation, mostly obsolete.


------- End of Forwarded Messages