Internet Draft Roberto Mameli Expiration: August 2000 CoRiTeL File: draft-mameli-issll-cops-api-00.txt The CCAPI (COPS Client Application Programming Interface) February 22, 2000 Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2000). All Rights Reserved. Abstract This document focuses on the Admission Control functionality performed by the Edge Router in the IntServ/DiffServ interworking scenario described in [COPS-ISDS]. More precisely it describes the interaction between the RSVP and the COPS protocols in the Edge Router and Mameli Expires August 2000 1 The CCAPI (COPS Client Application Programming Interface) Feb-00 introduces an API (Application Programming Interface) aimed at allowing the intercommunication between them. Anyway, the API described here is designed as a flexible interface, and should be able to support communication between a generic application and the COPS Client Type described in [COPS-ODRA]. Table of Contents Abstract........................................................1 Table of Contents...............................................2 Glossary........................................................2 1. Introduction ................................................2 2. CCAPI generalities ..........................................3 3. CCAPI Description ...........................................5 4. Upcall mechanism ............................................8 5. Definition of CCAPI objects .................................10 6. References ..................................................11 7. Author Information and Acknowledgements .....................12 Glossary API Application Programming Interface BB Bandwidth Broker CCAPI COPS Client Application Programming Interface COPS Common Open Policy Service DSCP Differentiated Services Code Point ER Edge Router IPC Inter Process Communication PDP Policy Decision Point. PEP Policy Enforcement Point. QoS Quality of Service RSVP ReSerVation Protocol SLS Service Level Specification 1. Introduction One of the possible scenarios for end-to-end QoS provisioning relies on a proper combination of both the Integrated Services (IntServ) ([INTSERV] and [RFC2210]) and the Differentiated Services (DiffServ) ([2BIT] and [DSARCH]) architectures. The description of such a model is beyond the scope of this document; a detailed explanation can be found in [INTDIF] and in [COPS-ISDS]. However it is worth observing that the router placed at the boundary between the IntServ stub domain and the Mameli Expires August 2000 2 The CCAPI (COPS Client Application Programming Interface) Feb-00 DiffServ core, i.e. the Edge Router (ER), provides several interworking functionality (described in details in the references above). One of the most important functionality managed by the ER is related to admission control. The original DiffServ architecture provides a sort of implicit admission control, in the form of SLS negotiated between neighboring domains. The introduction of end-to-end signaling by means of the RSVP protocol allows explicit admission control on micro-flow basis, as explained in details in [INTDIF]. Note, however, that the are at least two ways to perform Admission Control in the Edge Router. In fact, it can be realized either in a distributed way by means of information locally available, or in a centralized way by querying an Admission Control Server. As stated in [COPS-ISDS], the first approach is easier to implement, but it is nevertheless characterized by inaccuracy, since each ER does not have an overall knowledge of the network resource utilization. Moreover, in some situations (failures, etc.), consistency among information stored in different ERs could not be assured. For this reason [COPS-ISDS] focuses on the second solution. However, in such a scenario the communication between the ER and the centralized server must happen according to a proper protocol. COPS represents a possible choice, since it is a simple and extensible protocol; [COPS-ODRA] proposes an extension suited at the purpose. Besides the COPS extension, needed for the communication between the centralized server and the Edge Router, another communication interface should be defined. In fact, the Edge Router supports both the COPS-ODRA PEP and the RSVP daemon. As explained in [COPS-ISDS], the entire mechanism requires proper interaction between them; for example the reception of a RSVP RESV message by the ingress ER should trigger an admission control query towards the server (PDP/BB). This observation leads to the definition of a new interface between the COPS-ODRA client and the RSVP daemon within the Edge Router. This document describes an API that can be used at the purpose. This API, called CCAPI (COPS Client API), is based on a client library statically linked with the RSVP daemon. The latter can trigger queries to the PDP/BB server when needed and can receive responses from it either synchronously or asynchronously, as explained in the following paragraph. Note, however, that the CCAPI is designed in a flexible way, in order to be usable with applications other than RSVP, that could need to interact with the COPS-ODRA PEP for whatever reason. For this reason in the remaining part of the document we will use the term _CCAPI client_ to refer to such an application, thus avoiding to mention explicitly RSVP, even if it obviously represents the natural choice. 2. CCAPI generalities Mameli Expires August 2000 3 The CCAPI (COPS Client Application Programming Interface) Feb-00 As stated above, the CCAPI is realized by means of a client library statically linked with the CCAPI client. The procedures implemented in the CCAPI library use a proper inter-process communication (IPC) mechanism to interact with the COPS client, which in turn relies on the COPS protocol to communicate with the server. The situation is depicted in the following figure: +---------------------------------------------+ | Edge +----------+ +----------+ | +----------+ | Device | CCAPI | |COPS-ODRA |_______________|COPS-ODRA | | | Client | | Client | | COPS | Server | | +----------+ +----------+ | +----------+ | User Level || || | |=================||=============||===========| | Kernel Level |---------------| IPC | | ----------------- Mechanism | +---------------------------------------------+ Note that there is no need to standardize the inter-process communication mechanism, since it could vary due to several reasons, such as Operating System characteristics. The CCAPI proposed here does not assume anything about it, even if the actual implementation relies on the Linux socket mechanism. The definition of the interface specifies only the visible part of it, i.e. the set of routines made available to the CCAPI client. They are listed and explained in the following. The API can be used to manage events both in a synchronous and in an asynchronous way. In the first case the CCAPI client triggers a query to the PDP/BB and blocks indefinitely waiting for a response. This is the easiest way to use the CCAPI, but it could lead to undesirable behavior in the case of no response from the server. Let us consider as an example the case of an admission control request from RSVP; if the server does not respond for whatever reason, the daemon would wait indefinitely. This is obviously undesirable, since normal processing of other requests should not be blocked by a pending request (e.g. timeout of installed PATH and RESV states would expire, and so on). For this reason the CCAPI has been designed to manage events asynchronously, by means of an _upcall_ or _callback_ mechanism. In this way the CCAPI client triggers the request from the PEP to the PDP/BB without waiting for response. When a response from the PDP/BB is available, the PEP notifies the CCAPI client (e.g. the RSVP daemon) that, in turn, manages it by calling a proper callback routine. A synchronous error in a CCAPI library routine returns an appropriate error code. Asynchronous errors are delivered to the application via the CCAPI upcall routine. Text messages for synchronous and asynchronous error codes can be found in the file cops_err.h. Mameli Expires August 2000 4 The CCAPI (COPS Client Application Programming Interface) Feb-00 3. CCAPI Description This paragraph reports a brief description of the sequence of operations needed by the CCAPI client and lists all the CCAPI calls along with their explanation. 3.1. CCAPI Outline The CCAPI client must include cops_api.h and cops_err.h and must be linked with cops_api.c. It begins by opening the session to the COPS- ODRA PEP via the cops_api_open_session() call; when it issues this call it can optionally specify a pointer to an appropriate callback routine (if any). The session associates the CCAPI Client with the PEP, meaning that the latter cannot have more sessions opened at the same time. If this is the need, several PEP processes should be instantiated together on the same Edge Router, and each of them should have a single session opened towards the CCAPI client. After the cops_api_open_session() call, the CCAPI client can ask for resource request, release and/or modify by means of the bandwidth_request(), bandwidth_release() and bandwidth_modify() calls, with proper parameters. In order to get a response the cops_api_dispatch() call can be used. In the _blocking_ case, the cops_api_dispatch() can be preceded by a select() system call, in order to wait indefinitely for an event; when such an event occurs, the select is unblocked and the cops_api_dispatch() can be used to obtain the response. No callback routine is needed in this case. In contrast, in the _non blocking_ case, a proper callback routine is specified in the cops_api_open_session(). The cops_api_dispatch() is periodically called inside the CCAPI client main loop, and it polls the PEP to see if a response has arrived; if so, the callback routine is executed. The latter receives also an optional argument that can be specified when opening the session through the cops_api_open_session() call. Whatever the mechanism we choose, _blocking_ or _non blocking_, at the end of all the operations the session can be closed via the cops_api_release_session() call. In the following a brief description of all the CCAPI calls is reported. 3.2. CCAPI calls 3.2.1. cops_api_open_session() The cops_api_open_session() call is used to open a session with the COPS-ODRA PEP. It returns a cops_api_error (i.e. an unsigned int), which could be any of the following values: COPS_API_OK - session opened without problems Mameli Expires August 2000 5 The CCAPI (COPS Client Application Programming Interface) Feb-00 COPS_API_NOCOPS _ COPS-ODRA PEP is not running on the ER COPS_API_OPEN - session already opened The definition of the function is the following: cops_api_error cops_api_open_session ( cops_event_rtn event_rtn, void *event_rtn_arg) The parameters are: event_rtn - is a pointer to the callback function specified by the CCAPI client. It could be NULL if the latter is not interested in managing asynchronous events by the upcall mechanism. event_rtn_arg - is a pointer to an optional parameter that is passed to the callback routine whenever it is called. 3.2.2. cops_api_getfd() It may be used by the CCAPI client to retrieve a file descriptor; this, in turn, could be used in a select() call immediately before the dispatch(), so as to realize a blocking mechanism. The function is specified as follows: int cops_api_getfd() It doesn't require parameters and returns the file descriptor, or _1 if the session has not been opened before. 3.2.3. cops_api_release_session() The cops_api_release_session() is used to close the session with the COPS-ODRA PEP. It returns a cops_api_error of the following types: COPS_API_OK - session closed without problems COPS_API_CLOSE - session already closed COPS_API_SYSERR _ system error The function prototype is: cops_api_error cops_api_release_session () No parameters are requested. 3.2.4. bandwidth_request() Mameli Expires August 2000 6 The CCAPI (COPS Client Application Programming Interface) Feb-00 The bandwidth_request() library call is used by the CCAPI client in order to instruct the PEP to query the PDP/BB for bandwidth request; referring to RSVP as an example, this could happen whenever a new flow is admitted at the ingress Edge Router. The function prototype is the following: cops_api_error bandwidth_request ( cops_req *request) It takes in input a pointer to a cops_req structure, that contains information about the request. The definition of the cops_req structure is reported in paragraph 5. Note that it also contains a request identifier, that is used in the _non-blocking_ case to associate requests made by the CCAPI client to responses provided by the PEP. In fact, in such a case, the CCAPI client can issue several requests to the PEP, and a way to relate them to corresponding responses is obviously needed. The library call can return one of the following values: COPS_API_OK - request successfully delivered to the PEP COPS_API_INVREQ _ invalid request; session not in place COPS_API_INVRID _ invalid request identifier (already in use) COPS_API_TOOMF - excessive number of pending requests COPS_API_SYSERR _ system error 3.2.5. bandwidth_release() This is the complementary function to the previous one. The CCAPI client uses it in order to instruct the PEP to communicate bandwidth release to the PDP/BB. If the CCAPI client is represented by RSVP, bandwidth_release() is called when a reservation is released, e.g. upon the reception of a RESV TEAR message by the ingress Edge Router. cops_api_error bandwidth_release ( cops_req *request) The parameters and the return values of this function are the same of the bandwidth_request(). 3.2.6. bandwidth_modify() The bandwidth_modify() call has been introduced with reference to the situation where the CCAPI client is represented by RSVP. It can be used to change dynamically a reservation without first releasing resources and then allocating them again. In this way there are two advantages: first of all the reservation is changed with a single message. Moreover, in the case of rejection of the new request, the old one remains in place. The function is defined as follows: cops_api_error bandwidth_modify ( cops_req *request) Mameli Expires August 2000 7 The CCAPI (COPS Client Application Programming Interface) Feb-00 The parameter is a pointer to a cops_req structure; differently from the case of bandwidth_request() and bandwidth_release() this request now contains a pair of bandwidth values, instead of a single one. The return values are the same of bandwidth_request(). 3.2.7. cops_api_dispatch() Applications use the cops_api_dispatch() library call to receive notifications of COPS events, e.g. responses to their queries. The function prototype is the following: cops_api_error cops_api_dispatch ( cops_resp *response) The cops_api_dispatch() polls the PEP for a response and retrieves it for the CCAPI client. The parameter is a pointer to a cops_resp structure; if not NULL, it is eventually filled with the response. If the latter is not available the object referenced by this parameter is left unchanged. Moreover the callback function specified in the cops_api_open_session() (if any) is called. An explanation of the upcall mechanism can be found in paragraph 4. Note however that the cops_api_dispatch() is a non blocking call; if a response is not available, it immediately returns control to the calling function. Possible return values of cops_api_dispatch() are: COPS_API_OK - dispatch successfully executed COPS_API_NOCOPS - COPS-ODRA PEP is not running on the ER COPS_API_INVREQ _ invalid request; session not in place COPS_API_SYSERR _ system error 3.2.8. cops_api_version() The cops_api_version() call returns the version number of the CCAPI in the form major*100+minor. Current version is 1.00. 4. Upcall mechanism An upcall is invoked by cops_api_dispatch(), which executes the procedure specified by the event_rtn parameter of the cops_api_open_session() call (if specified). The upcall function has the following synopsis: int ccapi_callback ( cops_resp *response, void *arg) Mameli Expires August 2000 8 The CCAPI (COPS Client Application Programming Interface) Feb-00 It receives from cops_api_dispatch() the response just arrived and the user specified parameter (represented by the event_rtn_arg parameter in the cops_api_open_session() call). Based on these parameters it executes an application specified routine. There are basically two types of events that can trigger an upcall: - DECISION EVENT: this event notifies the CCAPI client about a response from the PDP/BB, which could be either positive (i.e. request accepted) or negative (i.e. the request was rejected for some reason, e.g. bandwidth unavailability or unsupported service). - ERROR EVENT: it is used to signal error events directly recognized by the PEP, e.g. invalid request or excessive number or pending requests. The type of event is contained in the response that is passed to the ccapi_callback() (see paragraph 5). It also contains a code that specifies the particular reason for that event. Possible codes for both DECISION EVENTS and ERROR EVENTS are contained in tables 1 and 2 below: +-------------+---------------------------------------------+ | Code | Reason that triggered the event | +-------------+---------------------------------------------+ | COPS_OK | Request accepted | | COPS_NOBW | Unavailable resources | | COPS_NODSCP | Unsupported service | | COPS_NOIED | Invalid Ingress Edge Device Address | | COPS_NOEED | Invalid Egress Edge Device Address | +-------------+---------------------------------------------+ Table 1: Codes for DECISION EVENTS (PDP/BB responses) +-----------------+------------------------------------------+ | Code | Reason that triggered the event | +-----------------+------------------------------------------+ | COPS_API_OK | Operation successfully completed | | COPS_API_INVRID | Invalid Request Identifier | | COPS_API_INVREQ | Invalid Request or Session not in place | | COPS_API_NOCOPS | COPS Client (PEP) not running on the ER | | COPS_API_OPEN | Session already opened | | COPS_API_CLOSE | Session already closed | | COPS_API_TOOMF | Excessive number of requests | | COPS_API_SYSERR | System Error | +-----------------+------------------------------------------+ Table 2: Codes for ERROR EVENTS Mameli Expires August 2000 9 The CCAPI (COPS Client Application Programming Interface) Feb-00 5. Definition of CCAPI objects This appendix defines the main CCAPI objects, reported below along with a brief explanation. - cops_req object typedef struct Cops_Req { unsigned int request_ID; unsigned int request_type; struct in_addr IED_addr,EED_addr; unsigned int dscp[2]; unsigned int msr_interval[2]; unsigned int token_size[2]; } cops_req; This object is used by the CCAPI Client to specify information that the PEP will insert in the COPS REQ message when querying the PDP/BB. The fields have the following meaning: - request_ID: request identifier. Each pair request/response is characterized by a unique request identifier, which is used to correlate the response with the corresponding request. The same request_ID cannot be contemporarily used for issuing different requests, otherwise COPS_API_INVRID is returned. - request_type: type of request. The following list reports the possible values for this parameter. Each of these values must be used when the corresponding library routine on the right is called: BW_REQUEST _ bandwidth_request() BW_RELEASE _ bandwidth_release() BW_MODIFY _ bandwidth_modify() CCAPI_CLOSE _ cops_api_release_session() - IED_addr: IP address of the ingress Edge Device - EED_addr: IP address of the egress Edge Device - dscp[]: two-element vector. In the case of bandwidth_request() and bandwidth_release() calls, the first element contains the DSCP of the requested service, while the second is unspecified. In the case of bandwidth_modify() the two elements contains respectively the old and the new value for the DSCP. - token_size[], msr_interval[]: a pair of two element vectors. The corresponding bandwidth is given by the ratio: token_size[n]/msr_interval[n] n=0,1 In the case of bandwidth_request() and Mameli Expires August 2000 10 The CCAPI (COPS Client Application Programming Interface) Feb-00 bandwidth_release() only the first two elements are meaningful; they contains the bandwidth to be requested/released. In the case of bandwidth_modify() the values token_size[0]/msr_interval[0] and token_size[1]/msr_interval[1] contains respectively the old and the new value for the bandwidth. - cops_resp object typedef struct Cops_Resp { unsigned int request_ID; cops_event_type resp_type; cops_error resp_errcode; } cops_resp; This object contains the responses received by the CCAPI Client. The fields have the following meaning: - request_ID: is the same value contained in the request. It is returned by the PEP to the CCAPI Client in order to associate the response to the corresponding request. -resp_type: specifies the type of response. Two types are currently supported: DECISION_EVENT ERROR_EVENT The difference is explained in the previous paragraph. -resp_errcode: depending on resp_type, it gives detailed information about the event that triggered the response. Possible values are reported in table 1 and table 2. 6. References [INTSERV] R. Braden, D. Clark, S. Shenker, "Integrated Services in the Internet Architecture: an Overview", IETF RFC 1633, June 1994 [RFC2210] J. Wroclawski, "The Use of RSVP with Integrated Services", IETF RFC 2210, September 1997 [RFC2205] R. Braden, L. Zhang, S. Berson, S. Herzog, S. Jamin, "Resource ReSerVation Protocol (RSVP) - Version 1 Functional Specification ", IETF RFC 2205, September 1997 Mameli Expires August 2000 11 The CCAPI (COPS Client Application Programming Interface) Feb-00 [2BIT] K. Nichols, V. Jacobson, L. Zhang "A Two-bit Differentiated Services Architecture for the Internet", IETF RFC 2638, July 1999 [DSARCH] S. Blake, D. Black, M. Carlson, E. Davies, Z. Wang, W. Weiss, "An Architecture for Differentiated Services", IETF RFC 2475, December 1998 [INTDIF] Y. Bernet, R. Yavatkar, P. Ford, F. Baker, L. Zhang, M. Speer, R. Braden, J. Wrocklaski, E. Felstaine, "A Framework for Integrated Services Operation Over DiffServ Networks", IETF <draft-ietf-issll-diffserv-rsvp-03.txt>, September 1999, Work in Progress [IWQOS99] O. Schelen, A. Nilsson, J. Norrgard, S. Pink, "Performance of QoS Agents for Provisioning Network Resources", Proceedings of IFIP Seventh Internation Workshop on QoS (IWQoS'99), London, UK, June 1999 [COPS] D. Durham, Ed., J. Boyle, R. Cohen, S. Herzog, R. Rajan, A. Sastry "The COPS (Common Open Policy Service) Protocol", IETF RFC 2748, January 2000 [COPS-ODRA] S. Salsano, "COPS Usage for Outsourcing Diffserv Resource Allocation", <draft-salsano-issll-cops-odra-00.txt>, February 2000, Work in Progress [COPS-ISDS] S. Salsano, R. Mameli, "Integrated services over DiffServ network using COPS-ODRA", <draft-mameli-issll-is-ds-cops- 00.txt>, February 2000, Work in Progress 7. Author Information and Acknowledgements The author would like to thank Stefano Salsano, Eleonora Manconi and Luca Dell'Uomo for their support and their contribution in the prototype implementation. Roberto Mameli CoRiTeL consortium Via di Tor Vergata 135 00133 _ Roma (Italy) Phone: +39 06 20410038 EMail: mameli@coritel.it Mameli Expires August 2000 12