Up

gdomap documentation

Authors

Richard Frith-Macdonald (richard@brainstorm.co.uk)

Copyright: (C) 1998 Free Software Foundation, Inc.

Contents -

  1. gdomap
  2. Usage Scenario
  3. How it Works and Why
  4. Communications Protocol
  5. Notes for Packagers

gdomap

The gdomap daemon is used by GNUstep programs to look up distributed objects of processes running across the network (and between different user accounts on a single machine). The deamon is NOT used for lookup where two processes belonging to the same user are using a host-local connection.

If you are packaging GNUstep for inclusion in a software distribution you may want to skip to the final section of this document.

Usually the gdomap daemon is started at system boot time and binds itself to port 538. (See the GNUstep Build Guide for a sample startup script.) It expects to receive fixed-size request packets for registering, deregistering, and looking up distributed objects servers. The response packets vary in length depending on the type and content of the information requested. In addition, limited support for federation is provided by a rudimentary gdomap-gdomap communications protocol.

What follows is a description of gdomap from a developer perspective. For information pertinent for users, such as how to configure and start up gdomap, please see the man page for more information ("man 8 gdomap").

The name server is intended to work with both the UDP and the TCP protocols. It is intended that the TCP interface be used by GNUstep programs, while the UDP interface is intended primarily for communication between name servers on different machines.

Usage Scenario

A complete distributed-objects "conversation" between a client and a server looks like the outline below. The gdomap daemon only plays a role in the "pre-" and "post-" phases. Everything else is conducted "peer-to-peer" between the two GNUstep processes.

Pre-conversation
  1. Server registers an object as being available as the 'root object' on a particular port with a specific name.
  2. Client looks up a port by name.
Conversation
  1. Client connects to the port and asks for the root object.
  2. Server returns proxy to root object.
  3. Client then proceeds to send messages to the object.
  4. Server sends message responses except where methods are declared 'oneway'.
  5. The server may also send messages to the client and have the client send responses.
  6. Eventually, the client or the server disconnects by invalidating port or connection or just exiting.
Post-conversation
On shutdown, the server unregisters the service name and port it used.

How it Works and Why

The fixed size of a request packet was chosen for maximum ease and speed of implementation of a non-blocking name server. The server knows how much it needs to read and can therefore usually do a read as a single operation since it doesn't have to read a little, figure out request length, allocate a buffer, and read the rest.

The server name length (bytes) is specified - no assumptions should be made about whether the name contains nul characters or indeed about the name at all. This is future-proofing.

Why UDP as well as TCP? The OpenStep specification says that a connection may be established to any host on the local network which supplys a named service if the host name is specified as '*'.

This means that the application must poll to see if it can find a server with the name it wants. The polling could take a huge amount of time!

To make this all easier - the server is capable of supplying a list of those hosts on the local network which it knows to have (or have had) a name server running on them.

The application then need only poll those name servers to find the service it wants.

However - to give the application a list of hosts, the name server must have got the information from somewhere. To gather the information the server has to poll the machines on the net which would take ages using TCP since attempts to talk to machines which are down or do not exist will take a while to time out.

To make things speedy, the server sends out GDO_PROBE requests on UDP to all the machines on the net when it starts up. Each machine which has a name server notes that the new name server has started up and sends back a GDOPREPLY packet so that the new name server will know about it.

Things are never perfect though - if a name server dies, the other name servers won't know, and will continue to tell applications that it is there.

Port type codes - these are used to say what the port is for so that clients can look up only the names that are relevant to them. This is to permit the name server to be used for multiple communications protocols (at the moment, tcp or udp) and for different systems (distributed objects or others). This guarantees that if one app is using DO over UDP, its services will not be found by an app which is using DO over TCP.

Communications Protocol

The communications protocol is identical for both TCP and UDP and consists of a simple request-response sequence.

Each request is a single message consisting of -

  1. a single byte request type
  2. a single byte giving name length,
  3. a single byte specifying the type of port being registered or looked up, or a nul byte for probe operations.
  4. a single nul byte.
  5. a four byte port number in network byte order must be present for register operations, otherwise this is zero.
  6. a service name of 0 to GDO_NAME_MAX_LEN bytes (or two IP addresses in network byte order and an optional list of additional addresses for probe operations)
  7. 0 to GDO_NAME_MAX_LEN nul bytes padding the service name to its full size.
  8. a terminating nul byte.

The total is always sent in a packet with everything after the service name (except the final byte) cleared to nul bytes.

Each response consists of at least 4 bytes and depends on the corresponding Request Type and where it came from as follows -

GDO_LOOKUP
Looks up the server name and returns its port number. Response is the port number in network byte order, or zero if the named server was not registered.
GDO_REGISTER
Registers the given server name with a port number. This service is only available to processes on the same host as the name server. Response is the port number in network byte order, or zero if the named server was already registered.
GDO_UNREG
Un-register the server name and return old port number. If the server name is of length zero, and the port is non-zero then all names for the port are unregistered. This service is only available to a process on the same host as this name server. Response is the old port number in network byte order, or zero if the name could not be un-registered. If multiple names were unregistered the response is the port for those names.
GDO_SERVERS
Return a list of the known servers on the local net. Response is an unsigned long (in network byte order) saying how many servers the name server knows about, followed by a list of their IP addresses in network byte order. NB. This response may not be possible over UDP as the response length may exceed the maximum UDP packet size.
GDO_NAMES
Return a list of registered names known to the server. Response is an unsigned long (in network byte order) saying how many bytes of data are to follow, followed by a list of the names each preceeded by the name length (a single byte) and port type (a byte). NB. This response may not be possible over UDP as the response length may exceed the maximum UDP packet size.

The following are used for communications between name servers -

GDO_PROBE
Requests a response Passes two IP addresses in the name field - first the address of the sender, next that of the recipient. The packet may (optionally) include a variable number of addresses (as specified by the name length minus the size of the two addresses), each of which is an internet address on which the sender is also listening. For a request from a name server via UDP there is no response, but a GDO_REPLY request is sent. For a request from a non-name-server, or a TCP connect, the response is the port number of this server in network byte order.
GDO_PREPLY
Replies to a GDO_PROBE via UDP from a name server. The format of the message is as for GDO_PROBE. No response is sent.

Notes for Packagers

The gdomap process is a system daemon used to coordinate services between different machines. As such it should be started (as root) at system boot time (if inter-host messaging is desired), and you need to write the appropriate startup scripts for your system and put them in place when the package is installed.
Alternatively you may install gdomap setuid to run as root, and GNUstep programs will launch it on demand ... but this is not recommended as it provides lass control than when you write a proper startup script.

The default operation of gdomap is to probe the hosts on the local network to find other machines with copies of gdomap running, so that all the machines on the network can be kept informed of the seervices provided by GNUstep servers.
This probing may be considered unfriendly by other users of the LAN, so it is usually better to provide a configuration file specifying the IP addresses of machines to be probed, and start up gdomap at boot time with the command line option to tell it to read the file.


Up