[ Previous | Next | Contents | Glossary | Home | Search ]
AIX Version 4.3 Communications Programming Concepts

RPC Port Mapper Program

Client programs must find the port numbers of the server programs that they intend to use. Network transports do not provide such a service; they merely provide process-to-process message transfer across a network. A message typically contains a transport address consisting of a network number, a host number, and a port number.

A port is a logical communications channel in a host. A server process receives messages from the network by waiting on a port. How a process waits on a port varies from one operating system to another, but all systems provide mechanisms that suspend processes until a message arrives at a port. Therefore, messages are sent to the ports at which receiving processes wait for messages.

Ports allow message receivers to be specified in a way that is independent of the conventions of the receiving operating system. The port mapper protocol defines a network service that permits clients to look up the port number of any remote program supported by the server. Since the port mapper program can be implemented on any transport that provides the equivalent of ports, it works for all clients, all servers, and all networks.

The port mapper program maps Remote Procedure Call (RPC) program and version numbers to transport-specific port numbers. The port mapper program makes dynamic binding of remote programs possible. This is desirable because the range of reserved port numbers is small and the number of potential remote programs large. When running only the port mapper on a reserved port, the port numbers of other remote programs can be determined by querying the port mapper.

The port mapper also aids in broadcast RPC. A given RPC program usually has different port number bindings on different machines, so there is no way to directly broadcast to all of these programs. The port mapper, however, has a fixed port number. To broadcast to a given program, the client sends its message to the port mapper located at the broadcast address. Each port mapper that picks up the broadcast then calls the local service specified by the client. When the port mapper receives a reply from the local service, it sends the reply back to the client.

Registering Ports

Every port mapper on every host is associated with port number 111. The port mapper is the only network service that must have a dedicated port. Other network services can be assigned port numbers either statically or dynamically, as long as the services register their ports with their host's port mapper. Typically, a server program based on an RPC library gets a port number at run time by calling an RPC library procedure.

Note: A service on a host can be associated with a different port every time its server program is started. For example, a given network service can be associated with port number 256 on one server and port number 885 on another.

The delegation of port-to-remote program mapping to a port mapper also automates port number administration. Statically mapping ports and remote programs in a file duplicated on each client requires updating all mapping files whenever a new remote program is introduced to a network. The alternative solution, placing the port-to-program mappings in a shared Network File System (NFS) file, would be too centralized. If the file server were to go down in this case, the entire network would also.

The port-to-program mappings, which are maintained by the port mapper server, are called a portmap. The port mapper is started automatically whenever a machine is booted. Both the server programs and the client programs call port mapper procedures. As part of its initialization, a server program calls its host's port mapper to create a portmap entry. Whereas server programs call port mapper programs to update portmap entries, clients call port mapper programs to query portmap entries. To find a remote program's port, a client sends an RPC call message to a server's port mapper. If the remote program is supported on the server, the port mapper returns the relevant port number in an RPC reply message. The client program can then send RPC call messages to the remote program's port. A client program can minimize port mapper calls by caching the port numbers of recently called remote programs.

Note: The port mapper provides an inherently useful service because a portmap is a set of associations between registrants and ports.

Port Mapper Protocol

The following is the port mapper protocol specification in RPC language:

const PMAP_PORT = 111;     /* port mapper port number     */

The mapping of program (prog), version (vers), and protocol (prot) to the port number (port) is shown by the following structure:

struct mapping {
     unsigned int prog;
     unsigned int vers;
     unsigned int prot;
     unsigned int port;
};

The values supported for the prot parameter are:

const IPPROTO_TCP = 6;      /* protocol number for TCP/IP     */
const IPPROTO_UDP = 17;     /* protocol number for UDP        */

The list of mappings takes the following structure:

struct *pmaplist {
     mapping map;
     pmaplist next;
};

The structure for arguments to the callit parameter follows:

struct call_args {
     unsigned int prog;
     unsigned int vers;
     unsigned int proc;
     opaque args<>;
};

The results of the callit parameter have the following structure:

struct call_result {
     unsigned int port;
     opaque res<>;
};

The structure for port mapper procedures follows:

program PMAP_PROG {
     version PMAP_VERS {
          void
          PMAPPROC_NULL(void)          = 0;
     bool
     PMAPPROC_SET(mapping)             = 1;
     bool
     PMAPPROC_UNSET(mapping)           = 2;
     unsigned int
     PMAPPROC_GETPORT(mapping)         = 3;
     pmaplist
     PMAPPROC_DUMP(void)               = 4;
          call_result
          PMAPPROC_CALLIT(call_args)   = 5;
     } = 2;
} = 100000;

Port Mapper Procedures

The port mapper program currently supports two protocols: User Datagram Protocol (UDP) and Transmission Control Protocol/Internet Protocol (TCP/IP). The port mapper is contacted by port number 111 on both protocols.

A description of the port mapper procedures follows.

PMAPPROC_NULL This procedure does no work. By convention, procedure 0 of any protocol takes no parameters and returns no results.
PMAPPROC_SET When a program first becomes available on a machine, it registers itself with the port mapper program on that machine. The program passes its program number (prog), version number (vers), transport protocol number (prot), and the port (port) on which it awaits service request. The procedure returns a Boolean response whose value is either True if the procedure successfully established the mapping, or False if otherwise. The procedure does not establish a mapping if the values for the prog, vers, and prot parameters indicate a mapping already exists.
PMAPPROC_UNSET When a program becomes unavailable, it should unregister itself with the port mapper program on the same machine. The parameters and results have meanings identical to those of the PMAPPROC_SET procedure. The protocol and port number fields of the argument are ignored.
PMAPPROC_GETPORT Given a program number (prog), version number (vers), and transport protocol number (prot), this procedure returns the port number on which the program is awaiting call requests. A port value of zero means the program has not been registered. The port parameter of the argument is then ignored.
PMAPPROC_DUMP This procedure enumerates all entries in the port mapper database. The procedure takes no parameters and returns a list of prog, vers, prot, and port values.
PMAPPROC_CALLIT This procedure allows a caller to call another remote procedure on the same machine without knowing the remote procedure's port number. It supports broadcasts to arbitrary remote programs through the well-known port mapper port. The prog, vers, and proc parameters, and the bytes of the args parameter of an RPC call represent the program number, version number, procedure number, and arguments, respectively. The PMAPPROC_CALLIT procedure sends a response only if the procedure is successfully run. The port mapper communicates with the remote program using UDP only. The procedure returns the remote program's port number, and the bytes of results are the results of the remote procedure.

[ Previous | Next | Contents | Glossary | Home | Search ]