search

devhawala / dodo

Xerox Network Services (XNS) implemented in Java
Other
13 stars 1 forks source link

readme

Dodo Services - XNS with Java

Dodo Services implement Xerox Network Services (XNS) protocols in Java, providing XNS services to existing emulated or real Xerox client machines.

Currently the following XNS services are provided by Dodo:

(although in most cases the implementation is incomplete regarding the specification, the services provide a working and useful subset for working "as usual" with XDE resp. StarOS, ViewPoint or GlobalView resp. Interlisp-D.

In fact, Dodo is not a single Java program, but a set of programs creating a simple virtual network infrastructure, a kind of XNS-over-TCP/IP. This virtual network allows different programs to inter-connect, among them the Dodo server proper, a gateway to a (real) network device and of course the Xerox client machines wanting to access the server component (see section Topology).

As for the maybe exotic name: although Dodo is not based on the Mesa-architecture but an almost pure Java implementation, the name had to start with the letter D to be in line with the Xerox tradition; on the other hand, it seemed appropriate to be something that no longer exists or is not noticeably present in the world; so the extinct species of a flight incapable bird came in mind: the Dodo.

Functionality

The Dodo system implements large parts of the Xerox Network Services protocol stack in Java, providing the functionality to build higher-level things like XNS file or print services.

In the XNS levels terminology, the Dodo system supports resp. implements the following protocols:

The network configuration of a Dodo server instance and the services provided can be configured through a property file specified when starting the Dodo program.

Topology

The following network example from the "old days" can be used for discussing the Dodo components:

example real network to be emulated

The client part of the network features several workstation generations from 8010 Star and 6085 with XDE workstations (both could also run ViewPoint or Interlisp) to a PC running GlobalView.
The server part of the network has the most common XNS backends like the required Clearinghouse/Authentication Service (also hosting a Mail Service) as well as the usual File and Print Services. Interactive access to "foreign systems" like mainframes or mid-range systems is provided through an External Communication Server with its companion CIU (Communication Interface Unit).

In a more contemporary environment of emulated Xerox machines, the original Star 8010 workstation could be subtituted by the Darkstar emulator, the Dwarf emulator could replace the PC with GlobalView.
But the are still functioning Xerox workstations that may require XNS services, so the 6085 machine will be assumed to be such a machine.

The above network could be reproduced as follows with the XNS emulation provided by the Dodo components:

possible emulated equivalent network

Besides the XNS client systems, at least 2 components need to run as independent programs for using Dodo services:

Besides programs (emulators and Dodo server) connecting directly to the NetHub, other XNS clients can also use the Dodo XNS services through the NetHubGateway: this is a NetHub client program that connects to a local PCap network device, implementing a gateway for XNS packets between a (more or less) real network and NetHub, allowing to attach emulators or potentially real machines that do not directly implement the NetHub protocol.

Two additional program components of Dodo services can be used if required:

Additional unsupported examples programs show the usage of the Dodo XNS-API for client and server applications, see example-programs.

Invocation and usage

Prerequisites

The following prerequisites must be installed and possibly configured to run Dodo services:

The current binaries for the Dodo services can be found in the file dist.zip, which can be unpacked to the directory dist. This directory contains the jar-file with the Dodo programs (dodoserver-and-nethub.jar) with the programs described in the following sections, as well as sample .cmd files for the Windows platform, expecting to be invoked in the dist directory.
For using the NetHubGateway, the jnetpcap.jar should be copied there, unless the script run-nethubgateway.cmd is adapted to match the location of this jar-file. The matching native libray for jNetPCap must be on the PATH for being found at runtime.

NetHub

The main-class for NetHub backbone for the virtual network is:

dev.hawala.hub.NetHub

and is started with:

java -cp dodoserver-and-nethub.jar dev.hawala.hub.NetHub

The sample Windows batch file is: run-nethub.cmd.

This program has not command line parameters and listens on port 3333 for connections from XNS client systems.

Dodo server

The main-class for the Dodo server is:

dev.hawala.xns.DodoServer

and is started with:

java -cp dodoserver-and-nethub.jar dev.hawala.xns.DodoServer

The sample Windows batch file is: run-dodoserver.cmd

This program uses 2 types of files to configure the functionality provided to the XNS network:

Dodo server command line parameters

The Dodo server program can be invoked without command line parameters, which will use the following default configuration file names:

This program accepts the following optional parameters:

A sample configuration file dodo.properties is available in the directory dist.

Dodo server configuration file

The following parameters can be specified in the configuration file for defining the basic communication parameters and the XNS services to be provided:

The following parameters can be specified in the configuration file to control the communication at the packet level:

Dodo server machine ids file

The symbolic name for both a Dodo server and client machine processor-id is defined in the machine ids file with a single line as follows:

name = XX-XX-XX-XX-XX-XX

The symbolic name can be used in configuration files for Dodo and the clearinghouse database files at any place where a machine or processor id is expected. If an undefined machine name is used in a configuration file, a dummy processor id is used for that name, allowing to continue loading the configuration file(s) and possibly collect further undefined symbolic machine names, but the server is not started after processing all configuration files and the undefined machine names are listed to stdout.

(as usual empty lines and lines with # as the first non-blank character are ignored)

For a client machine, the above definition line is the anchor for adding configuration parameters specifically for this machine, overriding the default defined for the Dodo server. Following the definition line, the parameters for this machine are given one per line introduced with a +, for example:

#
# slow down for a Darkstar machine running a Pilot-OS (XDE, StarOS or ViewPoint)
#
darkstar-1 = 10-00-AA-10-00-11
+ authSkipTimestampChecks = true
+ spp.resendDelay = 60
+ spp.sendingTimeGap = 60
+ pup.hostAddress = 131#5#

The following configuration parameters can be specified for a machine in a machine ids file to override the global settings:

(other global configuration parameters are ignored)

Additionally, the PUP address - consisting of the PUP network number (high byte) and the PUP host number (low byte) - for a machine can be specified with:

+ pup.hostAddress = <net>#<adr>#

where <net> is the octal PUP network number and <adr> is the octal PUP host number to be delivered by the NStoPupHostLookup service.

If several client machines need the same parameter overrides, it is not necessary to duplicate the parameters, instead it is possible to copy the settings from another machine with a line:
&nbsp;&nbsp;:like other-machine
and possibly add specific parameters for overriding values taken from the other-machine (overrides must come after the like: line).

For example:

#
# the second Darkstar machine
#
darkstar-2 = 10-00-AA-10-00-12
:like darkstar-1
+ pup.hostAddress = 131#42#

NetHubGateway

The main class for the NetHubGateway is:

dev.hawala.hub.NetHubGateway

and is started with:

java -cp dodoserver-and-nethub.jar;jnetpcap.jar dev.hawala.hub.NetHubGateway [options]

The sample Windows batch file is: run-nethubgateway.cmd

This program has the following optional parameters:

Parameter Default Description
(1st arg) localhost host where the NetHub runs, =selects the default
(2nd arg) 3333 port for the NetHub on the NetHub host, =selects the default
(3rd arg) MS LoopBack Driver PCap name of the network device to gateway, =selects the default
-ld Log packet coming from the network device
-ldd Log packet coming from the network device with packet content
-lh Log packet coming from the NetHub
-lhd Log packet coming from the NetHub with packet content
-p print the list of PCap device names on the local machine instead of running the gateway
-h print the command line help and stop

NetSpy

The main-class for NetSpy is:

dev.hawala.hub.NetSpy

and is started with:

java -cp dodoserver-and-nethub.jar dev.hawala.hub.NetSpy [pcap-logfile]

The sample Windows batch file is: run-netspy.cmd

This program always connects to port 3333 on localhost.

If the optional commandline parameter is given, it specifies the target filename where to additionally log all packets in the LibPCap format. This output file can be used for further offline analysis.
For example creating such a dump and writing the content can for example be done with:

java -cp dodoserver-and-nethub.jar dev.hawala.hub.NetSpy netspy-pcap.dump
tcpdump -ttttnn -r netspy-pcap.dump

FsUtil

The FsUtil program allows to list the contents of a Dodo file service volume and to copy files between the local file system and a file service volume. FsUtil accesses manipulates the volume directly on the local file system, so no XNS login is required.

The main-class for FsUtil is:

dev.hawala.xns.FsUtil

and is started with:

java -cp dodoserver-and-nethub.jar dev.hawala.xns.FsUtil parameters

The sample Windows batch file is: fsutil.cmd

FsUtil has the following command line options:

The volume argument specifies the directory for the file service volume in the local file system.

The path-to-folder argument specifies the folder in the volume to work with and must be given from the volume root, i.e. starting with the file drawer name. The folder or file versions (e.g. folder-name;1) are optional and need only to be specified for items having a different version than 1.

FsUtil has the following subcommands:

Remark: as only one program at a time can work with a volume directory to prevent data loss in the Dodo file service volume, FsUtil can only be used if no Dodo server instance is running a file service on the volume.

Examples:

List the files in folder test/vp-documents of the file service volume directory ../dodo-services/vol-fs1:

fsutil ../dodo-services/vol-fs1 test/vp-documents ls

Import all files in the local directoy old-docs into the folder test/vp-documents of the file service volume directory ../dodo-services/vol-fs1, creating a new subfolder old-docs:

fsutil ../dodo-services/vol-fs1 test/vp-documents import old-docs

Export all files in the folder test/vp-documents/archive including all subfolders of the same volume to the current directory:

fsutil ../dodo-services/vol-fs1 test/vp-documents/archive export -r

Environments known to work

Dodo was successfully tested in several environments with different emulators, with "successful" meaning that it was at least possible to log on to the Xerox operating system and optionally to verify that Clearinghouse entries can be searched resp. queried, e.g. under XDE using the Maintain.bcd program or by navigating the network directory under GlobalView (see the examples section in the clearinghouse configuration document. For Printing and Filing services the client OS typical operations (XDE: print.bcd, FileTool with Retrieve!, Store! Remote-Delete!, GVWin: printing documents, copy/move/props on remote files, documents and folders) are routinely tested.

The following environments were tested with Dodo server and nethub, using the default Clearinghouse database found in dist.zip:

Bibliography

Development history

License

Dodo is released under the BSD license, see the file License.txt.

Disclaimer

All product names, trademarks and registered trademarks mentioned herein and in the source files for the Dodo programs are the property of their respective owners.