7 RSVP Application Programming Interface

The Resource ReSerVation Protocol (RSVP) is an network layer protocol that enables Internet applications to request enhanced quality-of-service (QoS) for specific application data streams or flows, either simplex unicast or multicast. Applications will typically use the RSVP Application Programming Interface (RAPI) to request enhanced QoS when the default best effort delivery is not acceptable (for example, video and audio). The types of QoS applications may request are defined by Internet Integrated Services.

This chapter assumes you are familiar with the following:

IETF Integrated Services (RFC 1633)

RSVP protocol ( RFC 2205)

RSVP and Integrated Services (RFC 2210)

Controlled-Load Service ( RFC 2211)

The C programming language

This chapter provides the following information:

Overview of network quality of service

Information about the network QoS components

Information about the RSVP application programming interface (RAPI) routines

7.1 Network Quality of Service

As applications place ever increasing demands for bandwidth on the Internet network, increasing the network bandwidth is only a temporary solution. Newer real-time applications demand both increased bandwidth and low latency. Clearly, there must be a mechanism to manage bandwidth use in the network.

At present, an IP network with its Best Effort delivery service already performs a form of passive bandwidth management. If an outgoing queue is full, indicating high network traffic and congestion, the packets are quietly dropped. Some upper-level protocols can detect this data loss, others cannot.

Quality of service (QoS) is the phrase commonly associated with the concept of actively managing network bandwidth. In this scenario, all network elements (for example, hosts, applications, and routers) and all network protocol layers cooperate to ensure consistent traffic and service end-to-end in a network. Network bandwidth for real-time applications is reserved, while sufficient bandwidth remains for best-effort traffic.

7.2 Network Quality of Service Components

The major network quality of service components in this operating system are as follows:

Traffic Control

RSVP

RAPI

These components work together to provide network QoS. The following sections describe each of these components.

7.2.1 Traffic Control

On this operating system, the Traffic Control subsystem implements the Controlled-Load service as defined in RFC 2211. This service provides an application data flow with a QoS that approximates Best Effort delivery through unloaded network interfaces. The Traffic Control subsystem consists of the following components:

Admission control -- Verifies that the local system interface has the requested bandwidth and installs flows and filters.

Packet classifier -- Matches the outbound IP header with installed filters.

Packet rate enforcer -- Ensures that each output flow stays within its agreed upon boundaries.

iftcntl utility -- Manually sets up flows and views existing flows and filters.

Traffic control is supported on the Ethernet and FDDI interfaces.

7.2.2 RSVP

RSVP is an network signaling protocol that is defined in RFC 2205. It provides a mechanism to reserve bandwidth on the local system and through the network. On this operating system, RSVP is implemented in the form of the rsvpd daemon. This daemon is responsible for communicating with RSVP-enabled applications, sending RSVP messages, and receiving and processing RSVP messages. The rsvpd daemon uses the Traffic Control subsystem to install and modify flows and filters for a specific network interface.

7.2.3 RAPI

RAPI enables a local application that requires enhanced QoS to communicate with the rsvpd daemon. Using the RAPI routines, an application can make resource (bandwidth) reservations on the local system or advertise services to other nodes in the network, or both. This operating system implements RAPI as defined by the Resource ReSerVation Protocol API (RAPI) Technical Standard published by The Open Group. This technical standard is a companion document to this section. See Section 7.5 for a list of supported routines and their descriptions.

7.2.4 Interoperation of Components

In RSVP, there are following roles:

Senders (or data source) -- Defined by an IP source address and a source port

Receivers -- Defined by transport protocol, IP destination address, and destination port

An application can be both a sender and a receiver.

In a typical scenario, a remote host communicates with the local application and asks to receive data. When a local application wants to declare itself a data sender, the following events might occur:

The application initiates communication with the rsvpd daemon through the RAPI interface.

The application passes outgoing traffic or flow characteristics, such as upper and lower bandwidth limits, delay, and jitter, to rsvpd. These characteristics are known as a Tspec. An Adspec is also passed to the daemon.

The rsvpd daemon creates a PATH message that contains this information and passes it down to Traffic Control. The interaction between the rsvpd daemon and Traffic Control subsystem is invisible to the requesting application.

Traffic Control determines if there is sufficient bandwidth on the local adapter for the reservation. If there is, Traffic Control transmits the message. The transmission can be to a unicast address or multicast address.

At each RSVP-enabled router, Traffic Control updates the PATH message with the previous source address (next hop upstream to the sender), modifies the Adspec depending on the QoS control services present on the node, and transmits the message downstream to its destination.

At the receiver, rsvpd passes the Tspec and Adspec to the receiver application through RAPI.

The preceding list is provided to show a summary of the steps that can occur. Additional steps might be required.

When an local application wants to make a reservation request (declare itself as a receiver), the following events might occur:

The application initiates communication with the rsvpd daemon through the RAPI interface.

The application passes the traffic expected by the receiver (Tspec), the QoS level required (Rspec), and transport protocol and port number for the packets (filter spec) to rsvpd. The Rspec and Tspec are considered the flow descriptor or flowspec.
The Rspec is also used to control the packet scheduling mechanism in the router or host. The filter spec also controls packet classification to determine which senders' data packets receive the corresponding QoS.

The rsvpd daemon creates a RESV message that contains this information and passes it down to Traffic Control. The interaction between the rsvpd daemon and Traffic Control subsystem is invisible to the requesting application.

Traffic Control determines if there is sufficient bandwidth on the local adapter for the reservation. If there is, Traffic Control transmits the message upstream using the source address in the PATH message.

At each RSVP-enabled router, Traffic Control authenticates the reservation request and allocates the necessary resources as requested in the Tspecs and the Flowspec. If the authorization fails or if there are insufficient resources available, the router sends an RSVP error back to the receiver.

At the last RSVP-enabled router, if the request is accepted, the router sends an RSVP confirmation message back to the receiver.

At each RSVP session data sender, RSVP passes the merged Flowspec object to the application. This informs the sender of the request and describes the properties of the data path.

If the sender agrees with the RSVP reservation parameters, it acknowledges the reservation via RSVP and proceeds to send data to receiver over a separate data connection.

The preceding list is provided to show a summary of the steps that can occur. Additional steps might be required.

The detailed manner in which reservations from different receivers are shared in the Internet is controlled by a reservation parameter known as the reservation style. See RFC 2205 for information on the different reservation styles.

7.3 Traffic Control

The Traffic Control subsystem performs the following tasks:

Implements an admission control mechanism that maintains interface parameters, such as the device's peak output rate, the percentage of bandwidth that can be reserved for the Controlled-Load service, and the maximum number of concurrent flows.

Ensures that applications do not pace data at a rate faster than the flowspec.

Interfaces with the rsvpd daemon and the iftcntl command to install and remove flows and filters

Matches all outgoing packet headers with any existing filter specs to determine on which output queue to place the packets

See iftcntl(8) for more information. See the Network Administration guide for information on enabling traffic control on the system.

7.4 RSVP

RSVP assigns QoS to specific IP data flows or sessions, which can be either multipoint-to-multipoint or point-to-point. An RSVP session is defined by a particular transport protocol, IP destination address, and destination port. In order to receive data packets for a particular multicast session, a host must have joined the corresponding IP multicast group. A given session may have multiple senders and if the destination is a multicast address, multiple receivers.

The following sections describe the operating system's RSVP components and the operation of the rsvpd daemon.

7.4.1 Components of RSVP

The operating system's RSVP components are as follows:

/usr/sbin/rsvpd -- RSVP daemon

/usr/sbin/rsvpstat -- A program that displays resource reservation status

/usr/shlib/librsvp.so -- RSVP library

/usr/include/rapi_lib.h -- RAPI definitions

/usr/include/rapi_err.h -- RSVP and RAPI error definitions

7.4.2 rsvpd Daemon

The rsvpd daemon performs the following functions:

Listens on a raw IP socket for an incoming RSVP messages

Communicates with applications on the local host through the RSVP Application Programming Interface (RAPI)

Interfaces with the operating system's Traffic Control subsystem

When rsvpd receives an RSVP message from the network, it validates it against the local interface database and handles any authentication or protocol errors. If the request is valid, the rsvpd daemon then does the following:

Keeps track of RSVP sessions and flows

Handles resource reservations against flows

Passes RSVP messages to the local application, if registered with rsvpd

Routes RSVP packets with a destination address that does not match any interface on the local host to the next hop

See rsvpd(8) for information on daemon options. See the Network Administration guide for information on starting and stopping the rsvpd daemon.

7.5 RSVP Application Programming Interface

The RSVP Application Programming Interface (RAPI) enables an application to establish communications with the rsvpd daemon and to declare itself a data receiver or data sender, or both.

The application consists of the following:

A main function written by the developer

The RSVP Library routines that perform the RSVP protocol work

A function written by the developer to process RSVP callbacks

The following sections describe the supported routines and the steps a developer needs to perform in order to write an RSVP-capable application.

7.5.1 Supported Routines

RAPI consists of the following:

Client library services -- Routines that implement communication between the application program and the rsvpd daemon

RAPI formatting routines -- Optional routines for convenience in formatting RAPI objects.

Table 7-1 lists the supported client library services routines and their descriptions. See each routine's reference page for complete description of the routine, its syntax, and its parameters.

Table 7-1: Client Library Services Routines

Routine	Description
`rapi_session`(3)	Creates a RAPI session locally.
`rapi_reserve`(3)	Makes, modifies, or deletes a resource reservation for a session.
`rapi_sender`(3)	Defines, redefines, or deletes a sender's data flow parameters.
`rapi_strerror`(3)	Maps a RAPI error code to an error message string.
`rapi_version`(3)	Returns the RAPI version number being used on the operating system.
`rapi_release`(3)	Closes a RAPI session and deletes all resource reservations.
`rapi_dispatch`(3)	Dispatches a RAPI event.
`rapi_getfd`(3)	Obtains the file descriptor associated with a RAPI session.
`rapi_event_rtn_t`(3)	A user-written routine that receives incoming, asynchronous RSVP events.

RSVP requests contain objects that describe the type of QoS. The RAPI formatting routines enable applications to display the contents of RAPI objects. Table 7-2 lists the supported RAPI formatting routines and their descriptions. See each routine's reference page for complete description of the routine, its syntax, and its parameters.

Table 7-2: RAPI Formatting Routines

Routine	Description
`rapi_fmt_adspec`(3)	Formats a given RAPI Adspec into a buffer of given address and length.
`rapi_fmt_filtspec`(3)	Formats a given RAPI filter spec into a buffer of given address and length.
`rapi_fmt_flowspec`(3)	Formats a given RAPI flowspec into a buffer of given address and length.
`rapi_fmt_tspec`(3)	Formats a given RAPI Tspec into a buffer of given address and length.

See the Resource ReSerVation Protocol API (RAPI) Technical Standard published by The Open Group for information on RAPI objects, protocol operations, and RAPI return values.

7.5.2 Writing a RAPI-Enabled Application

As an application developer, you are usually presented with a UNIX application and have to implement an RSVP interface.

The following steps explain this process:

Include the rapi.h header file. This file defines all data structures, constants, and function prototyes required for applications to use RAPI.

Code the RAPI calls.
Write the code that calls RAPI to initialize communications with the rsvpd daemon.
Write a callback routine with which to receive RSVP events.

Execute and test your application.

7.5.2.1 Linking Your Application

After you compile your application, you link it with either the librsvp.so shareable library or the librsvp.so static library. This library contains the protocol implementation (RAPI) that enables communication between the application and the rsvpd daemon.

7.5.3 Debugging RAPI Applications

To assist in testing and debugging your applications, you might want to run rsvpd with the -d flag. This forces the daemon to write error messages and debugging output to the /var/rsvp/rsvpd_dbg.log file.

You can also run rsvpstat to verify if connections are getting through or whether reservations are being honored. To monitor active RSVP sessions on the local system, enter the following command:

# /usr/sbin/rsvpstat

By default, the rsvpstat command displays a list of all RSVP sessions, sender and receiver, active on this system. Information includes the session number, destination address, IP protocol, port number, and the number of PATH and RESV states for the session.

To display sender information, including the contents of the actual PATH message from the sender, enter the following command:


# /usr/sbin/rsvpstat -Sv

To display receiver information, including the contents of the actual RESV message from the receiver, enter the following command:


# /usr/sbin/rsvpstat -Rv

See rsvpstat(8) for more information.