Interlisp.maiko/docs/Using-Dodo-networking-with-Maiko.md

Using Dodo-networking with Maiko

The Dodo XNS services provide an emulation for a usable subset of the Xerox 8000 Network Services from the 1980-ies. Dodo uses its own virtual network infrastructure - the Dodo Nethub - for avoiding the problems involved with implementing the transmission of XNS protocol packets over (real or virtual) network adapters of the diverse contemporary operating systems.

The Dodo Nethub provides a simple virtual network, a kind of XNS-over-TCP/IP, where clients and servers connect with TCP/IP to the central Nethub program, which relays all packets ingoing from one connection to the other connections.

The following sections describe the support for Dodo-networking added to Maiko. The Dodo Nethub support was implemented and tested with Linux on the x86_64 architecture. However as only standard system calls for TCP/IP were used, adapting to other platforms if necessary should be possible.

This extension allows Medley 3.51 running in a Maiko VM to use the XNS services Clearinghouse, Filing and Printing provided by Dodo (using the Mail service may also be possible, but this was not verified so far)

Building Maiko with Dodo-networking support

As long as Dodo-networking support is not merged into the master-branch of the primary Maiko repository, this networking option is only available in this clone of the original Maiko repository in the branch dodo-nethub-support.
(however: this branch should already be checked out if this file is present)

The Dodo-networking support is enabled by defining MAIKO_ENABLE_NETHUB when compiling Maiko. This can be done in the Makefile for the relevant platform (file bin/makefile-platform) for example in the line where the compiler-command variable is defined.

This is already done in the Makefile for the Linux-x86_64-X platform (file bin/makefile-linux.x86_64-x), where the compiler-command defined as follows:

CC = clang -m64 $(CLANG_CFLAGS) -DMAIKO_ENABLE_NETHUB

After a complete (re-)build, this Maiko VM optionally allows to connect to a Dodo Nethub and through this to use Dodo XNS services.

Running Maiko with Dodo-networking

With Dodo-networking support compiled in, Maiko (i.e. the program ldex) accepts the following additional commandline options:

• -nh-host dodo-host
  the name or IP-address of the host where the Dodo Nethub program runs; no connection to Dodo services will be opened if this option is not specified
  Default: (none)

• -nh-port port-number
  the port which the Dodo Nethub is listening to at dodo-host
  Default: 3333

• -nh-mac machine-id
  the machine-id (aka. MAC-address) that this Maiko VM instance will use in the Dodo network; the machine-id must be given as 48 bit hexadecimal value with a dash as byte-separator, i.e. in the format XX-XX-XX-XX-XX-XX (with XX the hexcode for a single byte)
  Default: CA-FF-EE-12-34-56

• -nh-loglevel log-level
  the detail level of logging to stdout, one of:
  0: log only main events (connect, disconnect or the like)
  1: log network events each with a single line
  2: detailled log of network events
  Default: 0

So by default Maiko will not connect to a Dodo nethub and behave like a "standard" version without networking support.
To use Dodo XNS services, the option -nh-host must be given to specify the location of the Dodo nethub. In the simplest (and probably most usual) case where Dodo is run on the same machine as Maiko/Medley, the value for option -nh-host will be localhost, so adding the option -nh-host localhost when starting the Medley Lisp system will allow to use the XNS services of a Dodo system running locally.

Specifying the machine-id is optional unless more than one Maiko/Medley instances are to use Dodo XNS services concurrently: in this case, each Maiko VM must use a unique machine-id, so at most one Maiko VM may omit the -nh-mac option.
However, each machine-id used by the Maiko VMs should have an entry in the machine.cfg file of the Dodo installation, cloning or copying the low-level SPP-configuration of the maiko-Lisp-One example entry in the machine.cfg of the Dodo dist.zip distribution.