Appendix E portmap Utility

The rpcbind utility replaces the portmap utility available in previous releases of the Solaris environment. This appendix is included to help you understand the history of port and network address resolution using the portmap utility.

Solaris RPC-based services use portmap as a system registration service. It manages a table of correspondences between ports (logical communications channels) and the services registered at them. It provides a standard way for a client to look up the TCP/IP or UDP/IP port number of an RPC program supported by the server.

System Registration Overview

For client programs to find distributed services on a network, they need a way to look up the network addresses of server programs. Network transport (protocol) services do not provide this function. Their task is to provide process-to-process message transfer across a network, that is, a message is sent to a transport-specific network address. A network address is a logical communications channel. By listening on a specific network address, a process receives messages from the network.

The way a process waits on a network address varies from one operating system to the next, but all provide mechanisms by which a process can synchronize its activity with arriving messages. Messages are not sent across networks to receiving processes, but rather to the network address at which receiving processes pick them up.

Network addresses are valuable because they allow message receivers to be specified in a way that is independent of the conventions of the receiving operating system. TI-RPC, being transport independent, makes no assumptions about the structure of a network address. It uses a universal address. This universal address is specified as a null-terminated string of characters. Such a universal address is translated into a local transport address by a routine specific to the transport provider.

The rpcbind protocol defines a network service that provides a standard way for clients to look up the network address of any remote program supported by a server. Because this protocol can be implemented on any transport, it provides a single solution to a general problem that works for all clients, all servers, and all networks.

portmap Protocol

The portmap program maps RPC program and version numbers to transport-specific port numbers. This program makes dynamic binding of remote programs possible.

Figure E–1 Typical Portmap Sequence (For TCP/IP Only)

The figure illustrates the following process:

1. The server registers with portmap.

2. The client gets the server's port from portmap.

3. The client calls the server.

The range of reserved port numbers is small and the number of potential remote programs is very large. By running only the port mapper on a well-known port, the port numbers of other remote programs can be ascertained by querying the port mapper. In Figure E–1, a, 111, b, and c represent port numbers, and 111 is the assigned port-mapper port number.

The port mapper also aids in broadcast RPC. A given RPC program usually has different port number bindings on different machines, so no direct broadcasts are possible to all of these programs. The port mapper, however, does have a fixed port number. So, to broadcast to a given program, the client sends its message to the port mapper located at the broadcast address. Each port mapper that receives the broadcast then calls the local service specified by the client. When portmap gets the reply from the local service, it returns the reply to the client. The portmap protocol specification is shown in the following code example.

Example E–1 portmap Protocol Specification (in RPC Language)

const PMAP_PORT = 111;       /* portmapper port number */
 /*
  * A mapping of (program, version, protocol) to port number
  */
 struct pmap {
 	rpcprog_t prog;
 	rpcvers_t vers;
 	rpcprot_t prot;
 	rpcport_t port;
 };
 /*
  * Supported values for the "prot" field
  */
 const IPPROTO_TCP = 6; /* protocol number for TCP/IP */
 const IPPROTO_UDP = 17; /* protocol number for UDP/IP */
 /*
  * A list of mappings
  */
 struct pmaplist {
 	pmap map;
 	pmaplist *next;
 };
 /*
  * Arguments to callit
  */
 struct call_args {
 	rpcprog_t prog;
 rpcvers_t vers;
 rpcproc_t proc;
 	opaque args<>;
 };
 /*
 * Results of callit
 */
 struct call_result {
 	rpcport_t port;
 	opaque res<>;
 };
 /*
 * Port mapper procedures
 */
 program PMAP_PROG {
 	version PMAP_VERS {
 		void
 		PMAPPROC_NULL(void) = 0;
 		bool
 		PMAPPROC_SET(pmap) = 1;
 		bool
 		PMAPPROC_UNSET(pmap) = 2;
 		unsigned int
 		PMAPPROC_GETPORT(pmap) = 3;
 		pmaplist
 		PMAPPROC_DUMP(void) = 4;
 		call_result
 		PMAPPROC_CALLIT(call_args) = 5;
 	} = 2;
 } = 100000;

portmap Operation

portmap currently supports two protocols (UDP/IP and TCP/IP). portmap is contacted by talking to it on assigned port number 111 (SUNRPC (5)) on either of these protocols. The following sections describe each of the port-mapper procedures.

PMAPPROC_NULL

This procedure does no work. By convention, procedure zero 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 local port map program. The program passes its program number prog, version number vers, transport protocol number prot, and the port port on which it receives service requests. The procedure refuses to establish a mapping if one already exists for the specified port and it is bound. If the mapping exists and the port is not bound, portmap unregisters the port and performs the requested mapping. The PMAPPROC_SET procedure returns TRUE if the procedure successfully established the mapping and FALSE otherwise. See also the pmap_set() function in the rpc_soc(3NSL) man page.

PMAPPROC_UNSET

When a program becomes unavailable, it should unregister itself with the port-mapper program on the same machine. The parameters and results of PMAPPROC_UNSET have meanings identical to those of PMAPPROC_SET. The protocol and port number fields of the argument are ignored. See also the pmap_unset() function in the rpc_soc(3NSL) man page.

PMAPPROC_GETPORT

Given a program number prog, version number vers, and transport protocol number prot, the PMAPPROC_GETPORT procedure returns the port number on which the program is awaiting call requests. A port value of zeroes means the program has not been registered. The port field of the argument is ignored. See also the pmap_getport() function in the rpc_soc(3NSL) man page.

PMAPPROC_DUMP

The PMAPPROC_DUMP procedure enumerates all entries in the port mapper's database. The procedure takes no parameters and returns a list of program, version, protocol, and port values. See also the pmap_getmaps() function in the rpc_soc(3NSL) man page.

PMAPPROC_CALLIT

The PMAPPROC_CALLIT procedure enables 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 by using the well-known port mapper's port. The parameters prog, vers, proc, and the bytes of args are the program number, version number, procedure number, and parameters of the remote procedure. See also the pmap_rmtcall() function in the rpc_soc(3NSL) man page.

This procedure only sends a response if the procedure was successfully executed and is silent (no response) otherwise. It also returns the remote program's port number, and the bytes of results are the results of the remote procedure.

The port mapper communicates with the remote program using UDP/IP only.