Interface Specification for Network

Overview

The Network interface defines the interface to the network plugin. The network plugin allows KPs to make measurements of network service, using the ping and traceroute facilities. It also performs name resolution.

This document does not describe the behavior of ping and traceroute in great detail. The plugin reimplementats the standard ping and traceroute UNIX utilities. For more information, see the man pages or W. Richard Stevens, TCP/IP Illustrated, Volume 1: The Protocols, Reading, Mass.: Addison-Wesley, 1994.

Types

The interface defines the following basic types:

Time = optional integer

The Latency and Route objects use this type to report measurements. The time is represented as an integer number of milliseconds or NULL when an error occurs for the sample.

RouteTime = record ...

The Route object reports the path between two hosts as a list of RouteTimes. The RouteTime record has fields, host and delays. The host field is a string representing the IP address of a host. The delays field is a list of type Time elements representing the round trip time to that host.

HostInfo = record ...

The HostInfo record represents the struct hostent returned by the gethostbyaddr() system call. The name field contains the canonical name of the host. The aliases field is a list of other names for the host. The addresses field is a list of IP addresses (as strings) for the host.

Exceptions

The interface defines the following exceptions:

HostNotFound

The specified host name could not be resolved.

KernelNotFound

The specified KSS kernel could not be found in the KOE namespace.

Error

An unspecified network error occured.

Objects

The interface defines the following object types; their methods are described in the next section:

Latency

This object measures the round-trip time to a host (measured from the current host). The network plugin registers this object with the name 'ping'.

Route

This object determines the path to a remote host (from the current host). There is no guarantee that any two packets will take the same path or that packets returning from the remote host will take the same path as outbound backets. The network plugin registers this object with the name 'traceroute'.

NameService

This object converts between IP addresses and host names. The network plugin registers this object with the name 'dns'.

Latency Objects

A Latency object has the following method:

Ping (host : string, samples : integer) : list of Time

Report the round-trip time between the current host and the specified host. The return value of will contain samples samples (up to a maximum of 16 samples). The host can be specified as either a host name or an IP address; if the host name cannot be resolved, a HostNotFound exception is raised. If a system error occurs, the generic Network.Error exception is raised. (Many kinds of non-fatal network errors can occur; they are reported as NULLs in the return list.)

Route Objects

A Route object has the following method:

TraceRoute (host : string, samples : integer) : list of RouteTime

Return a list of the gateways between the current host and the specified host. Each entry in the list contains timing information for samples samples (up to a maximum of 4). The host can be specified as either a host name or an IP address; if the host name cannot be resolved, a HostNotFound exception is raised. If a system error occurs, the generic Network.Error exception is raised. (Many kinds of non-fatal network errors can occur; they are reported as NULLs in the return list.)

NameService Objects

A NameService object has the following methods:

GetKernelHost (kernel : string) : string

Return the IP address of the KSS kernel. Effectively, it maps from the KOE's distributed namespace into the DNS namespace. Raise KernelNotFound if kernel can't be found in the "/kos" Context. Raise HostNotFound if an internal error occurs.

GetHostAddress (host : string) : string

Return the IP address of host. Raise HostNotFound if the name could not be resolved.

GetHostInfo (host : string) : HostInfo

Return a HostInfo record describing the canonical name, aliases, and IP address of host, which can be a host name or an IP adddress. Raise HostNotFound if the host could not be resolved.