Project title: Internet Telephony (ITX): Directory Service

Author: Char Shing Wilson Ng

Directory service is one of the core components in the ITX system to provide IP-Telephony computing architecture to enable communication capable devices talking with each other. It is designed and implemented as a distributed database system, in which client API components (encapsulated in ITX-compliant applications) interact and cooperate with the database server component in a coordinate fashion to provide the illusion of a single centralized directory service. The database server component is implemented through extending the BIND implementation, which is already a robust and mature architecture. The client API component is platform-independent to support application interoperability. The client communicator (responsible for communication with the database server) is designed in a flexible way, so that any database server solution can be plugged in and interfaced with the communicator, in order to adapt to any system environment constraints. The directory service achieves: 1) scalability provided by the BIND hierarchical approach; 2) fault tolerant provided by primary-secondary server setup and log-based persistence scheme; 3) data replication provided by zone transfer between primary and secondary; 4) failure detection provided by an efficient resolver mechanism; 5) security and authentication provided by the client API component and the BIND server. Overall, the directory service provides availability and reliability guarantees. The satisfactory performance result is achieved by choosing this implementation choice.

Executive Summary *

Table of Contents *

Project Overview *

Design Problem *

Approach and solution *

Design and Implementation *

Results Analysis *

Appendix *

This joint project (ITX project) is to build a telephony network computing architecture layered over the telephone network and the Internet to enable communication capable devices of any kind (computers, telephones, handheld or mobile PCs, etc.) talking to each other. It allows voice data to be sent between one communication device (such as a telephone or a PC with speaker and microphone) and another communication device. The ITX platform handles all the complexity of the following operations:

• Call setup and teardown;
• Looking up destination user location;
• Negotiating and establishing connection between source and destination users;
• Setting up data channel(s) between source and destination devices;
• Voice acquisition, packetization, encoding, packet streaming, and error control;
• Voice reception, reconstruction, decoding, and playout, etc.

In addition, the ITX platform exposes a set of powerful application programming interface (API) by which ITX-compliant IP-Telephony applications can be developed. Application programmers are freed from the above complexity and only need to worry about their business logic at the application layer.

The following four core components in the ITX system are necessary to enable Internet Telephony:

• Signaling - Signaling component acts as a control layer to hide substantial complexity of dealing directly with the directory service and other peer-signaling component to provide seamless integration between different ITX applications. It provides services to the users such as registrations, call setup and establishment, and call termination. It also provides certain signaling events such as call invited, call accepted, call rejected, call busy, DTMF received, call hung up and call aborted. It is distributed in nature in that it resides in each ITX application without centralized control.
• Data - Data component provides the basic means of data communication on the network between ITX applications. It provides services to the user application level to capture audio data from various devices such as microphones and files, transfer audio data as packet over the Internet, playout audio data to various devices such as speakers, files, or network destination. Its APIs allows programmers to setup and customize their own devices and channels. It is also distributed in nature in which it resides in each ITX application without centralized control.
• Gateway - Gateway component is a specialized ITX application. It runs and controls the computer with the telephony hardware (i.e. the Dialogic card). It serves as a necessary bridge between the telephone network and the Internet. The Gateway allows a person to call a desktop ITX application from telephone and vice versa.
• Directory Service - Directory Service component provides a "phone book" lookup service for all registered users in the ITX network. It dynamically keeps track of each user's currently reachable locations, as well as preset and customized locations, so that they can be reached anywhere from the telephone network as well as from the Internet. Moreover, it also maintains information about ITX application, such as the Gateway, so that applications can find each other. It is made up of client component distributed in each ITX application to coordinate and exchange information with the directory server component.

In this ITX project, my responsibility is to design and implement one of the ITX core components: the Directory Service. The directory service is logically running as a centralized entity, but is physically distributed. It is made up of multiple client-server components that interact and cooperate with each other to provide the illusion of a single centralized directory service.

Among all core components, directory service sits at the central piece of the whole project. It consists the centralized database server that stores information about users in the ITX network and provides information retrieval, updates as well as various lookups. Each ITX application contains a directory service client component to interact and exchange information with the database server in a coordinated fashion.

This client-server framework allows a user on his/her ITX application, containing the directory service client component, to transparently locate other users in the ITX network by communicating with the directory server. The directory service layer is completely hidden from the ITX application layer, so that only the signaling layer is responsible for interfacing with the directory service on behalf of the user application. Alternatively, ITX application layer can directly access the functionality of the directory service by getting its handle through the signaling component.

Users of the directory service fall into a wide range. For example, the signaling component that resides in each ITX application directly interfaces with the directory service client component. Specialized server applications such as the gateway server, voice/email server, conferencing server are using directory service, so that they can be located by other user applications using the directory service as well.

Several distributed system properties need to be considered when designing the distributed directory service:

• Scalability - The directory service should be capable to scale to hundreds of thousands of clients without any performance degradation. In an ideal situation, performance should stay relatively independent to the size of clients. That means latency in receiving responses from the database server should not increase with the number of active clients.

• Fault Tolerant - The directory service should hardens server reliability and recovers transparently from server failure without client intervention. In a minimal setup there should be more than one directory database server running to provide this guarantee.

• Failure Detection/Recovery - The directory service should include mechanisms to detect any ad-normal state of the database server when it becomes unavailable because of a crash or network partition. Any failure should be detected as efficient as possible. Other backup database server should assume responsibility and permit the system to continue execution as if no failures have occurred.

• Data Persistent/Replication - The directory service should provide persistent mechanisms to server data. In addition, server data should be protected by replication on more than one server. Also, periodic logging to persistent storage can also be supported, so that there can be scheduled down time.

• Availability - The directory service should provide uninterrupted and continuous services to the clients. This property is achieved at least through Fault Tolerant, Data Persistent/Replication, and Failure Detection/Recovery.
• Authentication and Security - The directory service should include authentication and security mechanism to prevent unauthorized user (e.g. users who are not registered in the directory service) to gain access and cause damage to the system. Moreover, each registered user should only be permitted to manipulate his/her own personal profile.
• Reliability and Robustness to Failure - The directory service should give clients reliable service guarantee. The directory service should give clients confidence on the system to provide a good quality of service. Reliability and robustness to failure are superset of properties mentioned above.

On the other hand, the directory service provides the following application-specific features:

• Translation between identifiers - The main responsibility of the directory service is to support translation mechanisms between different identifiers. Identifiers include registered user name, user's extension number, email address, phone number, and host address.
• User profile customization support - The directory service supports features to allow user to manipulate and customize his/her personal profile stored in the database server. For example, user should be able to change his/her password. User should be able to specify certain location (home phone number for example) where and when he/she could be reached.
• DHCP handling - DHCP stands for Dynamic Host Configuration Protocol. If a host machine is using DHCP addressing, its IP address can be changed dynamically at different points in time. In this situation, if the directory service does not take DHCP in account, it can result in data inconsistency, in which case the DHCP host machine cannot be located by the directory service.

• Dealing with "roaming" location - The directory service should be able to detect if a user signals his/her presence from another location than expected, and his/her subsequent calls should be directed to the new location (location can be a different host machine or a phone).

• Administration management - The directory service should support a centralized management through an administrator. Some of the tasks of the administrator include the following:
• New user registration and extension distribution.
• User termination, logging data into persistent storage (for scheduled downtime)
• Database server monitoring (e.g. number of active clients, their current locations)
• Manual restart or stop of database server upon malfunction behavior
• Platform independence - The directory service should be developed to be platform independent. On the client side, the directory service client component should support application development on any machine platform such as Unix or Windows, so that application should be freed from any platform-dependent constraints.
• Flexible architecture - The directory service architecture should be designed in a flexible way, so that its design can be implemented to suit to the context of different business environment. For example, the database server can be designed to be implementation-independent, as long as the interface and the database schema are well defined. As a result, different database software solution can be integrated into the directory service.

The following three approaches have been considered in designing and implementing the directory service. After evaluating tradeoffs between using different approaches, I decided to choose DNS-based client-server approach. Evaluations on the three approaches are described as follows:

1. Building from the ground-up

Using this approach to design and implement the directory service results in disadvantages far out-weighting advantages. The advantage is that the implementation can be very flexible, without under the constraints of existing implemented component such as platform dependence, different language implementation, and lack of extensibility. However, implementing the distributed directory service from scratch, especially taking into account different distributed system properties mentioned above, can be a complicated and insurmountable task.

2. Web-based client-server approach

There are wide variety of software tools and components to support implementing this approach. The communication between the client and the server components is HTTP-based. Basically, on the client side, client communicates with the web-based database server by sending HTTP request and receiving HTTP response. Database server processes and translates the request into a series of database transactions to communicate with the local database storage. This is a common and typical approach to provide proprietary data services. However, this approach does not satisfy our requirement of ITX system for the following reasons. First, the latency characteristic of this approach cannot provide certain degree of real-time characteristic guarantee to our system requirement. For example, the signaling component needs to communicate with the directory service component to setup and establish calls. The directory service needs to guarantee efficient response time (low latency guarantee), so that user should not feel any difference in using our ITX system to make calls than using the telephone system. The latency of using the web-based client-server approach can be unpredictably high, which can undermine our overall system's performance to provide consistent real-time guarantee. Second, there is no single software solution to fulfill our system requirement of distributed system properties. The implementation of this approach requires an integration of different software products to work coherently as a single system. Complications arise to evaluate different proprietary software products to the same solutions, and to make decision on choosing the suitable set of integration to fit our requirement. Cost of system updates and maintenance is also comparatively high in terms of the number of proprietary solutions chosen for building our system.

3. DNS-based client-server approach

Domain Name System (DNS) is known to be the most successful distributed name service in the Internet. Its main responsibility is to provide name-to-address resolution for the entire Internet, which in other words provides translations between identifiers.

The DNS is distributed in hierarchical nature, instead of being centralized which is prone to central point of failure. It consists of distributed name servers, each being responsible for a sub-tree of name space partitioned into different domains. In other words, DNS is a distributed database system. It has robust and stable implementation architecture called BIND (which stands for Berkeley Internet Name Domain). BIND provides the following characteristics:

• Its distributed and hierarchical nature allows the system to scale to a large degree, to achieve load distribution across hierarchical domain name servers. When network grows, it is capable to spawn and delegate a new sub-domain name server under the existing hierarchy to handle the newly assigned name space, thereby achieving both scalability and load balancing features.
• DNS supports replication to avoid potential failure on a name server handling sub-domain, thereby providing fault tolerant and availability guarantees. Replication techniques include backup (or slave) polling and primary server update notification. Fault tolerant can be achieved by a configuration of multiple primary and backup name servers responsible for a sub-domain. DNS also supports an efficient automatic fail-over mechanism to detect faulty primary and switch over to backup server.
• DNS communicates with the application efficiently. For example, it is capable to handle over 1,200 non-blocking queries per second, and it supports fast lookup time in nanoseconds.
• Caching mechanism is also provided to minimize traffic and reduce name server load, especially recursive traffic to the root name servers; therefore, same subsequent queries can be responded in a shorter time by caching replies.

• Its existing implementation architecture (BIND) allows flexibility and extensibility to integrate arbitrary or application-specific records into the database. Its also has a standard API library, intended to support linking with applications using the name service and to support building organization's naming architecture.
• BIND also supports flexible and configurable security mechanism to provide different degree of security level according to different design policy and requirement.

BIND is freely distributed and is fully supported by the Internet Software Consortium. It is portable on many different operating system platforms such as Solaris, HPUX, Linux, Ultrix, SunOS, and Windows, etc. Backward compatibility is also supported across different release versions.

The chosen of this approach is based on the mature and robust implementation architecture which has been justified by the popular use in the Internet community, and also on the role and functionality of DNS which best fit into the design requirement of the directory service. Moreover, most of the distributed system properties such as fault tolerant, scalability, availability, and failure detection, etc. has been implemented and taken care of in BIND. BIND guarantees low latency behavior (very efficient response time), which is a very desirable feature to the directory service. Lastly, the entire software product is free and provided by one organization, which saves substantial amount of cost for updates and maintenance.

The design of the directory service is basically decomposed into 4 parts:

• Database schema

• Database server

• Client API

• Client communicator

This area consists of two stages. The first stage is mainly the design phase: to determine the kinds of data directory service needs to maintain, and organize the data into separate relational entities or tables. The second stage is the implementation phase: to integrate the design into the existing BIND implementation.

The following three major categories of data were identified to be stored in the directory database:

• Administrative data - data managed by administrator. E.g. extension numbers
• User security data - password, access level
• User profile data - email address, extension number, custom message
• User location data - roaming location, dynamic location, default location, custom location

The following describes different relational entities (tables) to organize the above data categories:

• Extension Distribution entity

• User entity

• Security entity

• Roaming Location entity

• Dynamic Location List entity

• Default Location List entity

• Custom Location ID List and Custom Location entities

124. For the Custom Location entity, each entry contains four fields: location ID, start time, end time, and location. An entry is searched by the custom location ID. An example of 2 entries associated with a location ID is shown below.

To integrate the entities defined above into the existing BIND, we need to understand the existing mechanisms provided by BIND to create database storage (For the details on the BIND implementation, please refers to the book, "DNS and BIND" by Paul Albitz and Cricket Liu). An extensive amount of time was spent on the book and related sources (such as the BIND web page and mailing list) to understand how BIND works. Basically, each entity is designed to be managed and serialized under different zones (a zone can be analogous to an entity name). Each zone is defined in a separate database file. DNS resource record is the storage format and syntax used in the database file.

The following zones were defined for each entity defined above:

• Seven zones are defined for the Extension Distribution entity:

• "extdistrib1.itx.cnrg." - 1-digit extension number
• "extdistrib2.itx.cnrg." - 2-digit extension number
• "extdistrib3.itx.cnrg." - 3-digit extension number
• "extdistrib4.itx.cnrg." - 4-digit extension number
• "extdistrib5.itx.cnrg." - 5-digit extension number
• "extdistrib6.itx.cnrg." - 6-digit extension number
• "extdistrib7.itx.cnrg." - 7-digit extension number

• Two zones are defined for the User entity:
• "ext.to.user."
• "userid.to.ext."
• Zone "userid.to.sec." is defined for the Security entity.
• Zone "ext.to.roamloc." is defined for the Roaming Location entity.
• Zone "ext.to.dynamicloclist." is defined for the Dynamic Location List entity.
• Zone "ext.to.defaultloclist." is defined for the Default Location List entity.
• Zone "ext.to.customloclist." is defined for the Custom Location ID List entity.
• Zone "custom.loc." is defined for the Custom Location entity.

One database file is created for each zone. Below shows the content of a database file for the zone "ext.to.user" (the explanation for the rest of the database files can be found in the appendix section):

• Content of a database file, db.ext2user:

1. ; Serial

1. ; Retry after 1 hour

As mentioned before, the format and syntax used to write the database file is defined by DNS resource record. From the above database file, there are three different resource records defined:

• NS resource record - It is a name server (NS) resource record. It means there is currently one server, sim1.cs.cornell.edu, responsible for the zone, "ext.to.user.". The server is on the host sim1. This is necessary for each database file.

• SOA resource record - It is the start of authority (SOA) resource record. It means that this name server running on host sim1 is the best source of information for the data in the zone, "ext.to.user.". The second name (itx.cs.cornell.edu) after SOA is the mail address of the person in charge in the data (replace the first "." with an "@"). The five fields within the parentheses of the SOA record are used by secondary servers for zone transfer (data replication). This is again necessary for each database file.
• TXT resource record - It is the text (TXT) resource record. It is used to store one or more character strings, and is the one chosen to store data for the directory service. The format of the value of the string is defined differently in each zone. For example, the format of an entry in the above zone, "ext.to.user." is defined as follows:

For details of the definition of resource records, please refers to the book, "DNS and BIND" by Paul Albitz and Cricket Liu.

To run the database server for the directory service, the BIND source code needs to be downloaded and installed. The details on download, installation, and running are fully explained in the appendix section.

After the installation, before the database server starts running, three pre-existing files are needed:

• db.127.0.0 - It is a database file to cover the loopback network (which is the special, pre-assigned address that a host use to direct traffic to themselves). The content looks similar as what was explained before in the database schema section:

0.0.127.in-addr.arpa. IN NS sim1.cs.cornell.edu.

0.0.127.in-addr.arpa. IN SOA sim1.cs.cornell.edu. itx.cs.cornell.edu. (

1.0.0.127.in-addr.arpa. IN PTR localhost.

• db.cache - It is a database file for locating name servers for the root domain. Its content must be retrieved via ftp from the Internet site ftp.rs.internic.net\domain.

• named.conf - It is a configuration file for BIND server. It is a mechanism by which the database server reads all the database files. It basically lists all the zones administered by the server. The content looks like the following:

// BIND configuration file for the primary server

options {

};

zone "extdistrib1.itx.cnrg" in {

};

zone "extdistrib2.itx.cnrg" in {

type master;

file "db.extdistrib2";

};

…

…

zone "ext.to.user" in {

type master;

file "db.ext2user";

};

…

…

zone "0.0.127.in-addr.arpa" in {

type master;

file "db.127.0.0";

};

zone "." in {

type hint;

file "db.cache";

};

The above setup is for the primary database servers. For the setup of the secondary database servers, the only database files needed are the three pre-existing files described above. No database files described in the database schema section needs to be created for the secondary database servers because they will take care of data synchronization and replication by loading the database data over the network from the primary database servers (a mechanism called zone transfer). One difference between the primary and the secondary database servers are their named.conf files. For the secondary name server, the content of the named.conf files looks like the following:

// BIND configuration file for the secondary server

options {

};

zone "extdistrib1.itx.cnrg" in {

};

zone "extdistrib2.itx.cnrg" in {

type slave;

file "db.extdistrib2";

};

…

…

zone "ext.to.user" in {

type slave;

file "db.ext2user";

masters {128.84.223.58; };

};

…

…

zone "0.0.127.in-addr.arpa" in {

type master;

file "db.127.0.0";

};

zone "." in {

type hint;

file "db.cache";

};

The above configuration file tells the database server that it is secondary for the zone in which the slave keyword is signified, and it should track its update against the primary server on the host 128.84.223.58. For robustness, the configuration file for the secondary database server can specify up to ten database servers for zone transfer.

The client API is implemented in JAVA, which enables fast application development cycle and portability across multiple platforms. The client API basically exposes necessary interface(s) at the application level. The main interface exposed is the DirectoryService class, along with other supporting classes, described below:

• DirectoryService Class - This is the main class to provide clients an interface to use the directory service. To use the directory service, the user needs to authenticate himself/herself by calling the DirectoryService.declareIdentity method. Upon authentication successful, the user can lookup his/her user information (e.g. extension number, access level, custom message, etc.), manipulate his/her locations information (e.g. default and customized location), change his/her password, lookup all registered users in the ITX network, and reach them by their extension number or userID.

• Location Class - This class provides an abstraction of where the application or system is located. It has three properties:
• Type - It can be either telephone, or Internet, or user.
• Value - It can be in the form of either <host>:<port>, or <area code>-<phone number>, or <user ID>
• Label - name representation of the location.

• LocationList Class - This class represents a list of locations.

• CustomLocation Class - This class represents a list of locations with user-specified time interval. It basically extends LocationList class.

• UserID Class - This class provides an abstraction to a user ID.

• Password Class - This class provides an encapsulation to store user's password information.

• Digits Class - This class provides an abstraction to digits. It is used to store extension number.

• UserProperty Class - This class stores information on userID, extension, roaming location (if any), and custom message.

• ArrayRecords Class - This class is used to hold returned entries returned from the directory database server.

• CustomLocationRecord Class - This class is used to hold customLocationID-customLocation pair retrieved from the directory server.

In addition, different exception classes are defined to handle unexpected things happened in the directory service client API during the course of running ITX application. They are all inherited from Java Exception class.

All classes described above are packaged in the cnrg.itx.ds API library. Other supporting classes are defined in the package but are not exposed outside to the application level. For complete details of all the classes and methods defined in the cnrg.itx.ds package, please refer to the appendix section.

BIND implementation provides resolver, which is a set of library routines that are linked into client programs (such as telnet, ftp, nslookup, etc.) to access the server. The resolver basically handles:

• Querying a BIND server

• Interpreting replies from the server (which are responses that could result in resource record entries or error)

• Returning the query results to the requesting program

Therefore, the client communicator needs to incorporate the resolver library, which are implemented in C. A DSComm JAVA interface is defined to interface between the client API and the resolver library. The DSComm interface provides necessary methods to the client API to perform query and update to the directory database server (The DSComm interface is defined in the cnrg.itx.ds package that is fully explained in the appendix section). Those methods are native methods allowed to be implemented in low-level languages like C/C++. The implementation of native methods is compiled (with the resolver library) into a dynamically linked library (DLL) called DSComm.dll to be loaded and referenced via the DSComm interface.

The client communicator is also designed to be flexible in its implementation. In other words, its design can be implemented to use different database solutions (other than BIND) such as MS Access, MS SQL database, and Oracle database, etc., in order to suit to the context of different business constraints. The reason to support this flexibility is to consider the fact that BIND server needs to start in super-user mode, which creates inflexibility in installing and running BIND. By overriding DSComm interface methods in a DSComm-derived class, users provide their implementation in the overridden methods of the DSComm-derived class to communicate with other database servers.

This area is the most challenging task compared with other three areas. First, a fair amount of time was spent on understanding and hacking the BIND query and update code since there is not enough documentation to explain query and update related data structure defined in the resolver library. Second, blending Java and C code together introduces interesting garbage collection issue because Java run-time system is managing garbage collection on behalf of the programmer, but C is not. Therefore, in DSComm.dll which reference Java classes, Java run-time garbage collection mechanism needs to be turned off and handled explicitly in the DLL. Third, although BIND has been ported to different platforms, the latest BIND resolver version ported to Windows turned out to be not up-to-dated (which is BIND 4.9.7), and the database server is running BIND 8.1.2, Even it is backward compatibility (meaning BIND 4.x resolver still can communicate with BIND 8.x server), BIND 4.9.7 lacks dynamic update functionality (query and update routines) which is only supported from BIND 8.x versions onwards. Therefore, a fair amount of the dynamic update codes need to be ported over from Unix-version BIND 8.1.2 resolver library to BIND 4.9.7 resolver library.

The performance of the implementation of the directory service was evaluated based on the requirements set forth in the design problem section:

• Scalability - The scalability supported by the BIND implementation is satisfactory. Simulation is performed by having multiple clients to perform continuous queries into the directory server. The response time varies insignificantly as the BIND implementation guarantees nanosecond query response time and handling high query traffic (over 1,200) per second. Moreover, domains can be hierarchically structured in the same way as DNS. Since our ITX network services within Cornell Community in which the user population is not large, scalability performance is not a significant issue.
• Fault Tolerant - Currently, fault tolerant is provided by having two servers running, one being primary and one secondary. The secondary server periodically carries out zone transfer. This is the minimum setup and the result is satisfactory as the BIND implementation is very robust and mature. BIND can support multiple server setup to harden this guarantee. Fault tolerant on data is achieved through log-based persistence scheme as this is the only guarantee to data integrity across server crashes.
• Failure Detection/Recovery - The failure detection mechanism is very responsive and satisfactory. I intended to stop the service of the primary directory server, and only run the secondary directory server to observe any latency difference in its response to clients. It turned out that the latency to detect the primary server faulty is unnoticeable, as the response time from the secondary server is almost no difference than that from the primary server. Unfortunately, there is no automatic recovery mechanism in place in the BIND implementation. Manual restart needs to be performed on the crashed primary server.
• Data Persistence/Replication - The data persistence is supported by means of log-based persistence mechanism. Periodic serialization from logged files to the database file system is performed. Replication is achieved by means of zone transfer. Currently, zone transfer is carried out on all domains at the same periodic intervals, which can potentially create contention with the regular service time. Although no performance degradation is noticed during zone transfer, further realistic measurement needs to be carried out to justify the observation. Alternatively, depending on the frequency of access to each domain data, each can be prioritized to have different zone transfer schedule to distribute server load and reduce contention during regular service time.
• Availability - This property is achieved at a satisfactory level via fault tolerant, data persistent/replication, and failure detection/recovery.

• Authentication and Security - Authentication and security mechanisms are both guaranteed at the client API layer and the directory server layer. A user needs to authenticate himself/herself by calling the DirectoryService.declareIdentity method. If he/she is not registered in the ITX system, exception will be thrown, and he/she is not allowed to access the directory service. After successful authentication, he/she is assigned user access level, meaning only his/her user profile is manipulated; he/she is limited only to lookup other user's extension number and reachable location(s). Administrator is assigned super-user access level to monitor user activities. Our current implementation proves to be adequate considering the degree of data sensitivity.

• Reliability and Robustness to Failure - Overall, the directory service provides a confidence degree of reliability and robustness to failure to clients.
• Translation between identifiers - our directory service provides several identifier translation. For example, any registered user in the ITX network can be located by his/her extension or registered name. Given an extension number, the corresponding registered user name can be provided, and vice versa. Also, given an extension number or a registered user name, the corresponding location (such as phone number, and host address) can be provided.
• User profile customization support - Currently, the directory service provides the following services via the client API: 1) changing password; 2) changing custom message; 3) changing default location list; 4) changing custom location list. Those are adequate at this stage.
• DHCP handling - Dealing with DHCP is potentially challenging, since we cannot find an existing DHCP network to perform the testing. However, we have a simple way to deal with this issue. The host location can be stored in the form of host name instead of its IP address that we currently use at this point. For example, instead of storing the IP address, 128.84.218.84, its corresponding host name, yodel.cs.cornell.edu, is stored into the database. Since the host name is static, if its IP address is being changed, host name is still the same and can be used to do lookup to its current IP address. We did not incorporate this approach because we encountered problem on our DNS to perform name-to-address translation.
• Dealing with "roaming" location - We successfully dealt with this issue. Since users need to log on to our ITX network via their applications, once they are logged on successfully, their location is automatically registered into the directory database as roaming location, (any previous roaming location is put into dynamic location list). Therefore, they can be subsequently reachable on this new roaming location.
• Administration management - We provided necessary management via the administrator.
• We have a client utility for the administrator to register new user into the directory database and distribute extensions to new users.
• Similarly, existing user can be terminated by the administrator using the client utility. BIND also support mechanism for administrator to manually issue command to serialize logged data into persistence storage for any schedule downtime.
• We have a utility program to continuously monitor the number of clients in the ITX network and their current roaming location. Another big issue in the directory database is the cleanup of dynamic locations. Since dynamic locations can be staled or invalid (because of crashes in application which leave its location associated with the user in the directory database), cleanup needs to be performed on the database. To resolve this issue, instead of having a centralized program running to clean up dynamic location of all users, a distributed cleanup is performed by each user being responsible for cleaning up his/her invalid dynamic locations, and yet it is still transparent to the user. A cleanup thread is started automatically when an ITX application starts up. This thread runs through the dynamic location list once to find out and remove any invalid locations and then exit. Signaling component sitting on the application needs to periodically advertise its existence of location in case its location was mistakenly removed because of transient network partition.
• We provided a number of scripts to locate, stop, and restart the directory servers. We do not support auto restart of the directory server when machine reboots, but the restart script can be easily incorporated into the .init file of the machine.
• Platform independent - Our client API is platform independent since it is developed in JAVA. BIND implementation has been ported over to different platforms. Therefore, different client communicator component needs to be distributed for Unix and Windows platform. They all have the same features and behavior.
• flexible architecture - Our directory service supports different database solution to be plugged into the system as long as the database schema stays consistent with our design. This is a very desirable feature as we realized that BIND server needs to be started in super-user mode, which creates inflexibility to users. Our version will modify the BIND implementation, so that it can start in normal user mode.

The ITX joint project page is located at the following web page: http://www.cs.cornell.edu/cnrg/telephony/JavaDocs/

• db.extdistrib1 file for the domain "extdistrib1.itx.cnrg."

• db.extdistrib2 file for the domain "extdistrib2.itx.cnrg."

• db.extdistrib3 file for the domain "extdistrib3.itx.cnrg."

• db.extdistrib4 file for the domain "extdistrib4.itx.cnrg."

• db.extdistrib5 file for the domain "extdistrib5.itx.cnrg."

• db.extdistrib6 file for the domain "extdistrib6.itx.cnrg."

• db.extdistrib7 file for the domain "extdistrib7.itx.cnrg."

• db.userid2sec file for the domain "userid.to.sec."

• db.ext2user file for the domain "ext.to.user."

• db.userid2ext file for the domain "userid.to.ext."

• db.ext2roamloc file for the domain "ext.to.roamloc."

• db.ext2dynamicloclist file for the domain "ext.to.dynamicloclist."

• db.ext2defaultloclist file for the domain "ext.to.defaultloclist."

• db.ext2customloclist file for the domain "ext.to.customloclist."

• db.customloc file for the domain "custom.loc."

Below shows an installation procedure for the BIND server running on a Solaris machine:

Pre-requisites:

1. Make sure you have gcc compiler installed on your host. (the following procedure shown uses gcc version 2.7.2.3)
2. Make sure you have yacc (or byacc) and lex installed.

Steps:

For example, assuming you are installing the BIND on the path, /usr/u/aaa:

1. Get the bind-8.1.2.tar.gz from the bind site(http://www.isc.org/bind.html)

• "gunzip" and then "tar -xvf" the bind-8.1.2.tar.gz

• NOTE: A "src" directory will be created for all the untar files

1. Create a bind directory for installation:

• cd to "src" directory

• type at prompt: make DST=/usr/u/aaa/bind SRC=`pwd` links

• Note: need full absolute path

1. Do "make clean" in the bind directory
2. (Optional) If you only have yacc (instead of byacc), edit the Makefile.set in bind/SRC/port/solaris:

• edit Makefile.set in bind/SRC/port/solaris:
• change YACC pointing to yacc -d (instead of pointing to byacc -d)

• NOTE: remove the file ".settings" in the bind directory (if exists)

1. Do "make depend" in the bind directory
2. Do "make" in the bind directory
3. (Optional) If you don't want your resulting libraries and executables installed under the root directory, you can specify different destination path. For example, if you want the resulting libraries and executables installed under the path, /usr/u/aaa, you can do:

• add to bind/SRC/port/solaris/Makefile.set the following line:'DESTDIR=/usr/u/aaa'

• NOTE: remove the file ".settings" in the bind directory (if exists)

1. Do "make install" in the bind directory

• NOTE: after it's done, a "usr" directory (along with sub-directories, files) is created under /usr/u/aaa)
• NOTE: the BIND executable, "named", resides in /usr/u/aaa/usr/sbin/named.

1. Make sure you have your database and configuration files set up before running BIND (please refers to the document for setting up the database for BIND). At least three pre-existing files need to be created: db.127.0.0, db.cache, and named.conf.
2. To run server, type named at the command prompt. Please look at the man page for possible options to the command.

(Details of this section can also be found at the web page: http://www.cs.cornell.edu/cnrg/telephony/JavaDocs/ds.html)

public class DirectoryService extends java.lang.Object

This class provides clients an interface to communicate with the directory server.

public class DSComm extends java.lang.Object

This class is an inteface to the java native methods talking to the directory server. User should not directly call any methods of this class. Alternatively, if user prefers to provide his/her directory database server, he/she can define DSComm-derived class and the directory server.

public class Location extends java.lang.Object implements java.io.Serializable

This class provides a abstraction of where the application or system is located.

public class LocationList extends java.lang.Object

This class represents a list of locations.

public class CustomLocation extends LocationList

This class represents a list of locations with user-specified time interval

public class UserID extends java.lang.Object implements java.io.Serializable

This class provides an abstraction to identify a user uniquely

public class Password extends java.lang.Object

This class provides an encapsulation to store user's password information.

public class Digits extends java.lang.Object implements java.io.Serializable

This class provides an abstraction to digits

public class UserProperty extends java.lang.Object

This class stores information on userID, extension, roaming location (if any), and custom message.

public class ArrayRecords extends java.lang.Object

This class is used to hold returned record entries from the directory database

public class CustomLocationRecord extends java.lang.Object

This class is used to hold customLocationID-customLocation pair retrieved from the directory server.

public class DirectoryServiceException extends cnrg.itx.ITXException

This base class represents an exception thrown by the directory service.

public class AccessDeniedException extends DirectoryServiceException

This class represents an access-denied exception thrown by the directory service.

public class AuthenticationException extends DirectoryServiceException

This class represents an authentication exception thrown by the directory service.

public class RecordAlreadyExistsException extends DirectoryServiceException

This class represents a record-already-exists exception thrown by the directory service.

public class RecordNotFoundException extends DirectoryServiceException

This class represents a record-not-found exception thrown by the directory service.