Gateway Locator via SLP
Agung Suyono
Columbia University
New York, NY, 10027
As1682@columbia.edu
Abstract
This document describes an API for locating gateways via SLP. This API allows the user to query the gateways to SLP server by querying SLP URL format or Internet Telephony. Additional feature is this API supports for getting the best match URL according to the filter queried by the user. Another feature is this API support for multi-threading environment.
1. Introduction
An SLP system has three entities: User Agent (UA), Service Agent (SA), and Directory Agent (DA). Without DA, a UA need to query the required information from all SAs via multicast
[1]. With DA, SAs register their services to DA via unicast, and UAs will query those informations to DA via unicast.
In this work, we provide an API to UA to support a SLP URL format and Internet Telephony. Another feature we have implemented is this API support for getting best matching URL and can be used for multi-threading environment.
The organization of the report is as follow:
1. Introduction
2. Related Work
3. Architecture
4. Program Documentation
5. Measurement
6. Task List
7. Reference
2. Related Work
An SLP as described in [2] has been implemented by Caldera System, Inc as an open source, and its source code is available for download in www.openslp.org. The package is already support for User Agent, Directory Agent, as well as Server Agent. The differences our work from their work is we provide an API that has a capability to support SLP URL and Internet Telephony. To do this, we utilized the package library from their implementation.
SLP URL format for the SLP, as described in [3], encodes an SLP search query into a URL string to facilitate integration to the systems that use an URL as an interface. In our work, we are parsing this SLP URL format to the format that is recognized by OpenSLP library from www.openslp.org.
Selection and Sort Extension for SLP, as described in [4], allows a UA to request the URL in the service reply to be bounded to the specified maximum number, or be sorted according to the specified sort key list. We implemented some of the feature in [4] that has a direct impact for searching Internet Telephony gateways, and enhance the implementation so that it conform effectively with the API to support best match filter.
3. Architecture
3.1 Data Structure
We define two main data structure to store the information queried by the user and to return the result of the query to the user. We define this data structure in such a way to make the API as re-entrant to support multi-threading environment, without making it as a thread-specific application.
The parser_t structure is used to store the user query as well as the result of parsed-query. NULL value will be returned by each member of this structure after parsing if that member is not available.
typedef struct parser {
/* SLP URL as in draft-zhao-slp-url-00.txt */
char *slp_url;
/* "slp://" [domain-name] "/" query-desc */
char *domain_name; /* hostname from section 5 of RFC 1738 */
char *query_desc;
char *queryid;
/* "SrvRqst" / "SrvTypeRqst" / "AttrRqst" */
char *scope;
/* scope-list from section 6.4.1 of RFC 2608 */
char *filter;
/* srvfilter / srvtypefilter / attrfilter */
char *srvfilter; /* "type=" servicetype [";pred=" predicate]
[";spi=" spistr] */
char *servicetype; /* service type defined in section 4 of RFC 2608 */
char *predicate; /* predicate from section 8.1 of RFC 2608 */
char *spistr;
/* SPI defined in section 9.2 of RFC 2608 */
char *srvtypefilter; /* "na=" nalenstr */
char *nalenstr;
/* "0" / "-1" / nastr */
char *nastr;
/* naming-auth from section 2.1 of RFC 2609 [5] */
char *attrfilter; /* "url=" url [";tag=" taglist] [";spi=" spistr] */
char *url;
/* URL defined in section 4 of RFC 2608 */
char *taglist;
/* tag-list from section 10.3 of RFC 2608 */
char *extlist;
/* extension / extension ";" extlist */
char *extension; /* attrext / selectext / sortext */
char *attrext;
/* "ext=attr" */
char *selectext; /* "ext=select;" upper-bound */
char *upper_bound; /* intval from section 5 of RFC 2608 */
char *sortext;
/* "ext=sort;" sort-order ";" sort-key-list */
/* TELP NUMBER */
char *telp_number; /* Telp. Number */
char *country_code;
char *area_code;
} parser_t;
The gwloc_t structure stores all information as well as the result of the query for a specific user. This structure has to be defined before the user make a query.
typedef struct gwloc {
parser_t parser;
/* To hold the parsed-query */
char **Output;
/* Generic result from OpenSLP Library */
int numOutput;
/* Generic number of result from OpenSLP Library */
int *Lifetime;
/* SA lifetimes */
char **Srv;
/* Server URL used by SrvRqst and */
/* Phone number query */
char **Attr;
/* Attributes, used by AttrRqst */
char **SrvType;
/* Service provided by DA, used by SrvTypeRqst */
int Srvsize;
/* Size of Srv */
int Attrsize;
/* Size of Attr */
int SrvTypesize;
/* Size of SrvType */
int mult_factor;
/* multiplier factor, to keep track */
/* the dynamic memory alloc */
} gwloc_t;
3.2 Modules
Parser Module
This module parses the queried message to the format that is recognized by OpenSLP library. This module mainly doing two tasks: parsing SLP URL format and Telephone number. The result of parsing is then stored in parser_t data type that is unique for each user.
Best Match Filter Module
This module implements some feature in [4]. This module only supports matching filter based on numerical value and does not support based on string. This is because Internet Telephony gateway using numerical value to determine whether that gateway is good or not, such as ASR or cost. So we defined a grammar to conform to this purpose as follow:
best_match_filter = attr "=" value / attr "=" value "," best_match_filter
attr = attr-tag from section 5 of RFC 2608
value = "l" / "L"
value = "h" / "H"
value = 1*DIGIT
value = "l" / "L" is to query the lowest value,
value = "h" / "H" is to query the highest value, and
value = 1*DIGIT is to query the value with the most closed distance to the reference value. If multiple filter combination is requested, the priority for selection criteria is from left to right.
Example:
best_match_filter = iptel-gw-cost-list=h,total-capacity=l,remaining-capacity=300
In this example, iptel-gw-cost-list will have a higher priority than total-capacity and remaining-capacity, and total-capacity will have a higher priority than remaining-capacity.
We also didn't implement sorting to search the best one as suggested by [4]. We consider that it will take more time if we sort the gateways (as the result of SLP query) and only pick a few gateways (one or two) among them. Instead, we would prefer to use an iterative loop and iterate the URL one by one. The rough pseudo code of this algorithm may look like this:
AvailableURL[]; // List potential URLs contains best match criteria
BestURL = ""; //variable to store the result of the best server
BestValue= AvailableSrv[0].Value; //variable to store the best match selection criteria
for (i= 1; i < TotalAvailableURL; i++) {
// the higher the speed, the better the server
if (AvailableSrv[i].Value > BestValue) {
BestURL = AvailableSrv[i].SrvName;
BestValue = AvailableSrv[i].Value;
}
}
Note that in the implementation of this API, we also consider in the case in which more than one BestValue, i.e., there are multiple BestValue with the same value. To combat this case, we make BestURL as an array that can hold more than one URL.
By using this method, we can greatly reduce the number of URLs for the second filter. If for example in the first filter the there are two URL with the best matching among 20 URLs, the second filter will just do a selection from two URL only as a result from the first filter.
SLPTool Module
This module passes the parsed query to the OpenSLP library. This module also does some string manipulation for the parsed-query in addition to Parser Module so that it match with the grammar used in Best Match Filter Module and OpenSLP library. There are three main functions that utilized from OpenSLP library: SLPFindSrvs(), SLPFindSrvTypes(), and SLPFindAttrs(). This function also parses the output of those functions to eliminate unnecessary output and form in a user intended format.
In SLP URL, users are allowed to enter the predicate according to LDAPv3 format [6]. However, some of the characters for LDAPv3 filter are reserved for URL
[5] representation. For example, we cannot use <, >, or = in URL instead of %3c, %3e, %3d respectively. This module converts those URL representation to an appropriate LDAPv3 format [6] recognized by SLPFindSrvs() filter.
By using OpenSLP function, we never know in advance how many output will be retuned by the functions. In this module, we overcome this by allocating dynamically the variable used to hold the result of the query.
Gateway Locator Module
This module provides an API to the user. This module calls functions from the other modules, and the result of this caller is being represented to the most modest way to the user.
3.3. Diagram
The interoperability among the modules may be represented in the following diagram.
.
+---------------------+ +---+ .
+->| Best Match Filter | | G | .
| +---------------------+ | a | .
|
/|\ | t | .
|
| | e | .
| +--------+ +---------+ | w | .
| | Parser | | OpenSLP | | a |<---> User
| +--------+ +---------+ | y | .
| |
| | | .
| \|/
\|/ | L | .
| +---------------------+ | o | .
+->| SLPTool
|<->| c | .
+---------------------+ +---+ .
.
User input his/her query through the API provided by Gateway Locator module. Gateway Locator passes this query to SLPTool module. This module utilize Parser Module and OpenSLP library. If query contains best match filter, SLPTool passes this filter query to Best Match Filter module, which is utilize also the OpenSLP library. The result of this module is returned back to SLPTool, which is then returned back to Gateway Locator to the user.
3.4 API Format
The detail explanation of the API is in the Programmer Guide (make a link!!). The basic task that the user has to do for doing query is:
1. Input the query using Query() function.
2. Get the size of the query using GetSize() function.
3. Based on the size of the query, user allocate a memory to get the query result using GetResult() function.
3.5 Thread-Safe
To satisfy a thread-safe requirement, we make re-entrant all the parameter for a specific user. This parameter is held in gwloc_t data structure. However, We have to use Mutual Exclusion (mutex) feature since OpenSLP using callback to return the result of the query, and we can not passing our argument through the callback. To minimize the delay because of queue using mutex, we made three kind of mutexes, each for SLPFindSrvs(), SLPFindSrvTypes(), and SLPFindAttrs() function from OpenSLP library. Each mutexes will act independently according the query type of the user.
4. Program Documentation
System Requirements
Installation Instructions
Operation
Useful Enhancement
Acknowledgements
4.1 System Requirements
The system running the API described in this documentation has to install an OpenSLP library, which its package is available in www.openslp.org. The OpenSLP version that is used in this project is 1.0.7. Directory Agent (DA) server implemented by OpenSLP is only running under root id, because it will install daemons and library. However, some people may want to use this package for testing purpose and does not have a privilege to become a root user. We will describe the detail modification to make OpenSLP run not under root id.
In the file slp_message.h under openslp-x.x.x/common, modify the value of port number SLP_RESERVED_PORT from 427 to some port number above 1000.
In the file libslp.h under openslp-x.x.x/libslp, modify the value indicating the location of conf file LIBSLP_CONFFILE and spi file LIBSLP_SPIFILE, from "/etc/slp.conf" and "/etc/slp.spi" respectively, to your local directory.
In the file slpd_cmdline.c under openslp-x.x.x/slpd, modify \etc location in ETCDIR and \var location in VARDIR to the new etc and var location that you have privilege on that location. If necessary, command out the "#if !defined(ETCDIR)" and "#if !defined(VARDIR)" lines.
In the file slpd_main.c under openslp-x.x.x/slpd, commend out the "if" block under "Make sure we are root".
4.2 Installation Instructions
Make sure that you make a dynamic link using ln -s command to openslp-x.x.x/libslp and openslp-x.x.x/common if you are installing openslp-x.x.x not under the root id (because only root who can install the package containing share library). Below is the command line we are using in our environment that will be very different to your environment:
ln -s $HOME/openslp-1.0.7/libslp/ libslp
ln -s $HOME/openslp-1.0.7/common/ common
Unpack the package using:
gunzip -c gwloc.tar.gz | tar -xvf -
Go to gwloc directory, and run:
make demo1 to compile stand alone demo application
make demo2srv to compile server side thread demo application
make demo2cli to compile client side thread demo application
Please not that you may need to modify the Makefile to satisfy with your environtment.
4.3 Operation
Please see the programmer guide.
4.4 Useful Enhancement
The speed of best match filter query will be greatly enhanced if OpenSLP library support an Attribute List Extension.
4.5 Acknowledgements
We would like to thank to Weibin Zao, Henning Schulzrinne, and Naoya Seta (my colleague in EE department) for their valuable comments and suggestions.
5. Measurement
Among those modules mentioned above, Parser, SLPTool, and Gateway Locator modules behaves as what intended. However, for Best Match Filter module, the more URL match with the filter, the more delay the user will get. This is because OpenSLP 1.0.x does not support Attribute List Extension RFC 3059
[8]. However, it is slated for implementation in OpenSLP 1.2.x as is stated at
http://openslp.org/roadmap.html. According to
[8], if attribute list extension is not available, the requestor has to send an attribute request for each URL it obtains in the Service Reply message in order to obtain the attributes for these URLs. By this limitation, one of the ways that the Best Match Filter module can do is to get the all-available URLs using LDAPv2 filter according to the specific telephone number's prefix (usually area code and country code), and then for each URL, get its attributes according to the attribute matching queried by the user. The Best Match Filter then allocate a memory for an array to hold this matching result, and use this array to manipulate to get the best one(s).
6. Task List
Weibin Zao describes [1], [3], and [4], and we (Agung Suyono) provide an API to support Internet Telephony.
7. References
[1] Zao, W., Schulzrinne, H., "Locating Internet
Telephony via SLP", Internet Draft, October 2001
[2] Guttman, E., Perkins, C., Veizades, J. and M. Day,
"Service Location Protocol, Version 2", RFC 2608, June 1999.
[3] Zao, W., Schulzrinne, H., "The SLP URL Format",
Internet Draft, February 2002
[4] Zao, W., Schulzrinne, H., Bisdikian, C., Jerome, W.
"Selection and Sort Extension for SLP", Internet Draft, March 2002
[5] Berners-Lee, T., Masinter, L., McCahill, M. "Uniform Resource Locators
(URL)", RFC 1738, December 1994
[6] Howes, T. "The String Representation of LDAP Search
Filters", RFC 2254, December 1997
[7] Stevens, W.R., "UNIX Network Programming",
Prentice Hall, 1998
[8] Guttman, E., "Attribute List Extension for the Service Location
Protocol", RFC 3059, February 2001