idnits 2.17.1 draft-lindell-rsvp-scrapi-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-23) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. ** The document is more than 15 pages and seems to lack a Table of Contents. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Abstract section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 342 instances of lines with control characters in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (August 7, 1998) is 9391 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. '2' Summary: 11 errors (**), 0 flaws (~~), 1 warning (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 INTERNET-DRAFT Bob Lindell 3 Expiration: February 1999 ISI 4 File: draft-lindell-rsvp-scrapi-00.txt 6 SCRAPI - A Simple "Bare Bones" API for RSVP 8 Version 1 10 August 7, 1998 12 Status of this Memo 14 This document is an Internet-Draft. Internet-Drafts are 15 working documents of the Internet Engineering Task Force 16 (IETF), its areas, and its working groups. Note that other 17 groups may also distribute working documents as Internet- 18 Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six 21 months and may be updated, replaced, or obsoleted by other 22 documents at any time. It is inappropriate to use Internet- 23 Drafts as reference material or to cite them other than as 24 "work in progress." 26 To view the entire list of current Internet-Drafts, please 27 check the "1id-abstracts.txt" listing contained in the 28 Internet-Drafts Shadow Directories on ftp.is.co.za (Africa), 29 ftp.nordu.net (Northern Europe), ftp.nis.garr.it (Southern 30 Europe), munnari.oz.au (Pacific Rim), ftp.ietf.org (US East 31 Coast), or ftp.isi.edu (US West Coast). 33 Abstract 35 This document describes SCRAPI, a simple 'bare bones' API for 36 RSVP. The goal of this API is to produce an interface which 37 simplifies the augmentation of applications with RSVP support. 39 1. Introduction 41 This document describes SCRAPI, a simple "Bare Bones" API for RSVP [1]. 42 The goal of this API is produce an interface which simplifies the 43 augmentation of applications with RSVP support. The main features of 44 SCRAPI are: 46 o Allow the addition of RSVP support to applications by adding a 47 few lines of code. 49 o Provide a portable interface which can be used with any 50 vendor's RAPI implementation. 52 o Avoid the introduction of RSVP specific data types and 53 definitions. 55 o Support IPv4 and IPv6 in a transparent manner. 57 SCRAPI is layered on top of RAPI [2], an existing RSVP API, to provide 58 portability across vendor implementations. Currently, SCRAPI has been 59 tested only with the ISI implementation of RAPI. 61 There are three main routines included in this API, one which is used by 62 the sender side, one to be used at the receiving end, and a routine to 63 finalize the entire API at the end of execution. This simple API should 64 be easy to insert into networking applications which require RSVP 65 support. 67 The remaining routines in the API are utility functions to ease the 68 development of an interface which supports IPv4 and IPv6. The objective 69 is to provide enough functionality so that applications would not need 70 to code explicitly for either IPv4 or IPv6, or use messy compilation 71 conditionals to develop an interface to support both address families. 72 As an example, a single data type for addresses is provided that is 73 large enough to hold addresses from either address family. In 74 addition, parsing an address string or performing a host name resolution 75 for both address families is provided. 77 To provide simplicity, event upcalls to the application do not exist in 78 SCRAPI. For this reason, it would be difficult to use SCRAPI for 79 applications which negotiate QoS with the network. Applications 80 requiring this type of functionality should use the standard RAPI 81 interface. 83 2. Functional Description 85 Applications which use SCRAPI get a simplied service model. The average 86 bandwidth specified by the sender is currently translated into the 87 integrated services controlled load [4] or guaranteed service [3] with 88 the given average bandwidth. The peak bandwidth and token bucket depth 89 are set to twice the average bandwidth. Minimum policed unit and 90 maximum packet size are set to 64 bytes and the largest MTU of all IP 91 interfaces on the host. 93 Sender and receiver side API calls can block, if requested, until a 94 reservation request has completed. The notion of completion can be 95 difficult to define for multicast flows. We will define completion in 96 the content of SCRAPI calls to refer to either partial or full 97 completion of the reservation request. 99 A sender sources PATH messages using the Tspec described above. If 100 blocking is requested with a non-zero timeout value, the sender blocks 101 until the receipt of a single RESV event from any sender. If the 102 specified flow is unicast, the call blocks until the reservation has 103 completed. If the flow is multicast, then at least one receiver has a 104 reservation in place when the call unblocks. 106 A receiver waits for a PATH event from the sender, and if requested, 107 makes a reservation in response using the sender's Tspec and Adspec for 108 guaranteed service. For guaranteed service, the slack term is set to 109 zero. If blocking is requested, the receiver blocks until the receipt 110 of a CONFIRM event. For a multicast flow, a CONFIRM event can be a 111 unreliable indication that a reservation has been successful. 113 If any RSVP errors occur during a blocking sender or receiver API call, 114 the call will unblock and return an error code. 116 A state diagram of the SCRAPI reservation API, for a given data flow, is 117 shown in Figure 1. A data flow, or RSVP session, is defined as a unique 118 destination address, port and protocol number. 120 SCRAPI provides a simple error status reporting on a per flow basis. 121 Status can be in a "red", "yellow", or "green" state. The red state 122 indicates that either the flow does not exist or is currently in an 123 error state. Yellow state indicates that the reservation requests are 124 pending, whereas green indicates that at least one request has 125 completed. 127 In the next section, the SCRAPI application programming interface is 128 defined. In subsequent sections, usage examples are offered as 129 templates for programmers who are attempting to embed SCRAPI calls into 130 existing applications. 132 +---------+ 133 +----------| Closed |----------+ 134 scrapi_sender +---------+ scrapi_receiver 135 | | 136 scrapi_sender | | scrapi_receiver 137 +----+ | | +----+ 138 | V V V V | 139 | +---------+ +---------+ | 140 +---| | | |---+ 141 | Send | | Rcv | 142 +-------| |<-----+ +----->| |-------+ 143 | +---------+ | | +---------+ | 144 | | | | | | 145 | |scrapi_receiver(0) | | | 146 | | | | | | 147 | | | scrapi_sender(0)| | 148 | | | | | | 149 | scrapi_receiver | | scrapi_sender | 150 | | +---------+ | | 151 | +--------->| |<---------+ | 152 | | SendRcv | | 153 | scrapi_sender or +---| | | 154 | scrapi_receiver | +---------+ | 155 | | ^ | | 156 | +----+ | | 157 | | | 158 scrapi_release scrapi_release scrapi_release 159 scrapi_sender(0) | scrapi_receiver(0) 160 | V | 161 | +--------+ | 162 +----------------------->| Closed |<----------------------+ 163 +--------+ 165 Figure 1: SCRAPI API State Diagram 167 3. Application Programming Interface Definition 168 3.1. Reservation API Description 170 Function Name: scrapi_sender 172 Syntax: int scrapi_sender( 174 const struct sockaddr *destination, 175 int protocol, 176 const struct sockaddr *source, 177 scrapi_service service, 178 double bw, 179 int ttl, 180 unsigned long msecs 182 ); 184 Description: SCRAPI call for a data sender. The destination address 185 and protocol number of the data flow are supplied as the 186 first two arguments. The source address of the data flow 187 can be specified, or set to NULL to choose the system 188 default. The service parameter specifies the service, 189 currently either Controlled Load or Guaranteed. The bw 190 parameter is the average bandwidth of the flow in 191 bytes/sec. The ttl of the packets can be specified or 192 set to 0 to choose the system default. If msecs is 193 greater than 0, the call to scrapi_sender blocks msecs 194 milliseconds to receive a reservation event from at least 195 one recipient. The call will also unblock prematurely if 196 any errors are detected during this period. This 197 function can be called repeatedly by an application to 198 modify any parameters associated with this data flow 199 (same destination and protocol values). A value of 0 for 200 the bw parameter unregisters the data flow. 202 Return Values: TRUE if successful, FALSE otherwise. Unsuccessful 203 operations set scrapi_errno to an appropriate error code. 205 Also See: scrapi_errno, scrapi_get_status 206 Function Name: scrapi_receiver 208 Syntax: int scrapi_receiver( 210 const struct sockaddr *destination, 211 int protocol, 212 const struct sockaddr *source, 213 int reserve, 214 scrapi_style style, 215 unsigned long msecs 217 ); 219 Description: SCRAPI call for a data receiver. The destination address 220 and protocol number of the data flow are supplied as the 221 first two arguments. The source address of the data flow 222 can be specified or can be set to NULL to choose any 223 source. In addition, the source address can be specified 224 with a port number of 0 to match a source address 225 regardless of port number. The reserve parameter should 226 be set to TRUE or FALSE to turn on and off a reservation 227 for that data flow respectively. The style parameter 228 specifies whether the reservation is shared among 229 multiple senders. If msecs is greater than 0, the call 230 to scrapi_receiver blocks msecs milliseconds to receive a 231 reservation confirmation event. The call will also 232 unblock prematurely if any errors are detected during 233 this period. This function can be called repeatedly by 234 an application to modify any parameters associated with 235 this data flow (same destination and protocol values). 237 Return Values: TRUE if successful, FALSE otherwise. Unsuccessful 238 operations set scrapi_errno to an appropriate error code. 240 Also See: scrapi_errno, scrapi_get_status 241 Function Name: scrapi_close 243 Syntax: int scrapi_close( 245 const struct sockaddr *destination, 246 int protocol 248 ); 250 Description: SCRAPI call to close either a sender or receiver flow. 251 If the destination address is set to NULL, all flows will 252 be closed and the protocol parameter value will be 253 ignored. 255 Return Values: TRUE if successful, FALSE otherwise. Unsuccessful 256 operations set scrapi_errno to an appropriate error code. 258 Enum Name: scrapi_service 260 1. scrapi_service_cl 262 2. scrapi_service_gs 264 Description: Enumerated types for specificing the desired service. 265 Currently, Integrated Services Controlled Load and 266 Guaranteed are supported. 268 Enum Name: scrapi_style 270 1. scrapi_style_shared 272 2. scrapi_style_distinct 274 Description: Enumerated types for specificing the reservation style. 275 Currently, shared (wildcard) and distinct styles are 276 supported. 278 Enum Name: scrapi_status 280 1. scrapi_status_red 282 2. scrapi_status_yellow 284 3. scrapi_status_green 286 Description: Enumerated types for status condition of a flow. The 287 meaning of these values is described in the 288 scrapi_status() function description. 290 3.2. Asynchronous Event Loop API Description 292 Function Name: scrapi_getfd 294 Syntax: int scrapi_getfd( 296 const struct sockaddr *destination, 297 int protocol 299 ); 301 Description: SCRAPI call to get the API file descriptor to use in a 302 subsequent select() call. 304 Return Values: A file descriptor value if successful, -1 otherwise. 306 Function Name: scrapi_dispatch 308 Syntax: int scrapi_dispatch(); 310 Description: SCRAPI call to poll the API for new events. 312 Return Values: TRUE if successful, FALSE if RSVP support is no longer 313 available. 315 3.3. Error Handling API Description 316 Function Name: scrapi_get_status 318 Syntax: scrapi_status scrapi_get_status( 320 const struct sockaddr *destination, 321 int protocol 323 ); 325 Description: SCRAPI call to get the status of a flow. If the status 326 is red, either the flow was never defined or the flow is 327 currently in an error state. A yellow status indicates 328 that the flow is valid but no reservation operation(s) at 329 the sender or receiver end has completed successfully. 330 Once a single operation on either the sender or receiver 331 end has completed successfully, the flow has a green 332 status. 334 Return Values: scrapi_stat_red, scrapi_stat_yellow, or 335 scrapi_stat_green. 337 Variable Name: scrapi_errno 339 Syntax: extern int scrapi_errno; 341 Description: Set to the return value of the last RAPI call made within 342 the SCRAPI library. 344 Also See: scrapi_errlist 346 Function Name: scrapi_perror 348 Syntax: void scrapi_perror( 350 const char *string 352 ); 354 Description: SCRAPI call to print an error message analogous to the 355 perror() library call. 357 Function Name: scrapi_errlist 359 Syntax: const char * scrapi_errlist( 361 int errno 363 ); 365 Description: SCRAPI call to get an error message string for a given 366 errno. 368 Return Values: An error message string. 370 Function Name: scrapi_stderr 372 Syntax: void scrapi_stderr( 374 FILE *file 376 ); 378 Description: Set the file pointer to be used by the SCRAPI library for 379 standard error. If it is set to NULL, no messages are 380 printed. The default value is stderr. 382 Function Name: scrapi_debug 384 Syntax: void scrapi_debug( 386 FILE *file 388 ); 390 Description: Set the file pointer to be used by the SCRAPI library for 391 debugging information. If it is set to NULL, no messages 392 are printed. Debug messages include the logging of all 393 asynchronous RSVP events. The default value is NULL. 395 3.4. Address Manipulation API Description 396 Macro Name: SOCKADDR 398 Description: A struct sockaddr data type that is large enough for both 399 IPv4 and IPv6 addresses. 401 Function Name: scrapi_sockaddr_multicast 403 Syntax: int scrapi_sockaddr_multicast( 405 const struct sockaddr *address 407 ); 409 Description: Determine if an address is multicast or unicast. 411 Return Values: TRUE if multicast, FALSE otherwise. 413 Function Name: scrapi_sockaddr_parse 415 Syntax: int scrapi_sockaddr_parse( 417 struct sockaddr *address 418 const char *name, 419 unsigned short port 421 ); 423 Description: Perform a host name lookup or parse an address and 424 initialize a struct sockaddr structure. 426 Return Values: TRUE if parsed, FALSE otherwise. 428 Function Name: scrapi_sockaddr_print 430 Syntax: const char * scrapi_sockaddr_print( 432 const struct sockaddr *address 434 ); 436 Description: Pretty print an address. 438 Return Values: A valid string if printable, NULL otherwise. 440 Function Name: scrapi_sockaddr_get_port 442 Syntax: unsigned short scrapi_sockaddr_get_port( 444 const struct sockaddr *address 446 ); 448 Description: Get the port number. 450 Return Values: The port number if successful, 0 otherwise. 452 Function Name: scrapi_sockaddr_set_port 454 Syntax: int scrapi_sockaddr_set_port( 456 struct sockaddr *address, 457 unsigned short port 459 ); 461 Description: Set the port number. 463 Return Values: TRUE if successful, FALSE otherwise. 465 Function Name: scrapi_sockaddr_any 467 Syntax: int scrapi_sockaddr_any( 469 struct sockaddr *address, 470 int family 472 ); 474 Description: Initialize a struct sockaddr to the wildcard address and 475 port number for the given address family. 477 Return Values: TRUE if successful, FALSE otherwise. 479 4. Application Code Templates 481 This section provides examples, presented as code templates, to aid 482 programmers in augmenting networking applications with SCRAPI calls. 484 One example contains two simplex applications which attempt to wait for 485 a reservation to be put in place before sending data on the network. 486 The other example is a full duplex multimedia type application which 487 sends and receives data without waiting for completion of the 488 reservation. 490 4.1. Unicast Performance Measurement Application 492 The following example was derived from a network performance tool. It 493 attempts to put in place a unicast reservation before measuring network 494 performance. Waiting is accomplished using the timeout option in the 495 sender and receiver calls. 497 4.1.1. Sender Application 499 This sender application opens a TCP connection to the "receive-hostname" 500 on port 1111 and attempts to reserve 1000 bytes/sec of average 501 bandwidth. After waiting at most 10 seconds for a reservation to be put 502 in place, this application streams data to the receiver to measure 503 network performance and then closes the connection. 505 #include 507 void 508 main(int argc, char *argv[]) 509 { 510 int timeout = 10000; /* wait for at most 10 seconds */ 511 double bw = 1000; /* Average bandwidth 1Kbytes/sec */ 512 struct SOCKADDR destination; 513 char *hostname = "receive-hostname"; 514 unsigned short port = 1111; 516 /* translate host name or address */ 517 if (!scrapi_sockaddr_parse((struct sockaddr *) &destination, 518 hostname,htons(port))) { 519 fprintf(stderr,"Could not parse host address"); 520 exit(1); 521 } 523 /* make an RSVP based reservation */ 524 if (!scrapi_sender((struct sockaddr *) &destination,IPPROTO_TCP, 525 NULL,scrapi_service_cl,bw,0,timeout)) 526 scrapi_perror("RSVP unable to reserve bandwidth"); 528 /* run test */ 529 scrapi_close(NULL,0); 530 } 532 4.1.2. Receiver Application 534 This receiver application accepts a TCP connection and attempts to make 535 a reservation. After waiting at most 10 seconds for a reservation to be 536 put in place, this application consumes data from the sender to measure 537 network performance and then closes the connection. 539 #include 540 #include 542 void 543 main(int argc, char *argv[]) 544 { 545 int fd,len,timeout = 10000; /* wait for at most 10 seconds */ 546 struct SOCKADDR destination; 548 /* open, bind, and listen for connection */ 549 /* fd = accept(...); */ 550 len = sizeof(destination); 551 if (getsockname(fd,(struct sockaddr *) &destination,&len) == -1) { 552 perror("getsockname"); 553 exit(1); 554 } 556 /* make an RSVP based reservation */ 557 if (!scrapi_receiver((struct sockaddr *) &destination,IPPROTO_TCP, 558 NULL,1,scrapi_style_distinct,timeout)) 559 scrapi_perror("RSVP unable to reserve bandwidth"); 561 /* run test */ 562 scrapi_close(NULL,0); 563 } 565 4.2. Multicast Multimedia Application 567 This example highlights the inclusion of the SCRAPI API into a Tcl/Tk 568 event loop of a multimedia application. This is a full duplex 569 application that is sending and receiving data on the same address. 570 This application does not wait for completion status from the 571 reservation calls. 573 #include 574 #include 575 #include 577 void 578 callback(ClientData data, int mask) 579 { 580 if (!scrapi_dispatch()) 581 Tk_DeleteFileHandler(data); 582 } 584 void 585 main(int argc, char *argv[]) 586 { 587 int fd; 588 struct SOCKADDR destination; 589 double bw = 1000; /* Average bandwidth 1Kbytes/sec */ 590 char *hostname = "receive-hostname"; 591 unsigned short port = 1111; 593 /* translate host name or address */ 594 if (!scrapi_sockaddr_parse((struct sockaddr *) &destination, 595 hostname,htons(port))) { 596 fprintf(stderr,"Could not parse host address"); 597 exit(1); 598 } 600 /* make an RSVP based reservation */ 601 if (!scrapi_sender((struct sockaddr *) &destination,IPPROTO_UDP, 602 NULL,scrapi_service_cl,bw,0,0)) 603 scrapi_perror("RSVP unable to reserve bandwidth"); 604 if (!scrapi_receiver((struct sockaddr *) &destination,IPPROTO_UDP, 605 NULL,1,scrapi_style_distinct,0)) 606 scrapi_perror("RSVP unable to reserve bandwidth"); 607 fd = scrapi_getfd((struct sockaddr *) &destination,IPPROTO_UDP); 608 Tk_CreateFileHandler((ClientData) fd,TK_READABLE,callback, 609 (ClientData) fd); 611 /* send data */ 612 scrapi_close(NULL,0); 613 } 615 5. Conclusion 616 The SCRAPI interface provides a simple method to add RSVP support to 617 many network applications. It supports both IPv4 and IPv6 and attempts 618 to simplify user developed code to support both address families. 619 Coding examples are provided to give additional guidance on the usage of 620 this API. 622 6. Security Considerations 624 Security considerations are not discussed in this memo. 626 7. Acknowledgements 628 The author would like to thank Steve Berson for helping to define this 629 API. 631 8. References 633 [1] Braden, R., Ed., et. al., Resource Reservation Protocol (RSVP) - 634 Version 1 Functional Specification, RFC 2205, September 1997. 636 [2] Braden, R., Hoffman, D., RAPI -- An RSVP Application Programming 637 Interface Version 5, Work In Progress, November 1997. 639 [3] Shenker, S., Partridge, C., Guerin, R., Specification of Guaranteed 640 Quality of Service, RFC 2212, September 1997. 642 [4] Wroclawski, J., Specification of the Controlled Load Quality of 643 Service, RFC 2211, September 1997. 645 9. Author's Address 647 Bob Lindell 648 USC Information Sciences Institute 649 4676 Admiralty Way 650 Marina del Rey, CA 90292 651 Table of Contents 653 1. Introduction ................................................... 2 654 2. Functional Description ......................................... 3 655 3. Application Programming Interface Definition ................... 4 656 3.1. Reservation API Description .................................. 5 657 3.2. Asynchronous Event Loop API Description ...................... 8 658 3.3. Error Handling API Description ............................... 8 659 3.4. Address Manipulation API Description ......................... 10 660 4. Application Code Templates ..................................... 12 661 4.1. Unicast Performance Measurement Application .................. 13 662 4.1.1. Sender Application ......................................... 13 663 4.1.2. Receiver Application ....................................... 14 664 4.2. Multicast Multimedia Application ............................. 15 665 5. Conclusion ..................................................... 16 666 6. Security Considerations ........................................ 17 667 7. Acknowledgements ............................................... 17 668 8. References ..................................................... 17 669 9. Author's Address ............................................... 17