User Tools

Site Tools


middleware:devel:ed:name-arbiter

Name Arbiter Bean

Author Daniel Fisher
Date 2005/04/19
Updated By Catherine Winfrey
Date 2008/07/14

Requirements

Problem Statements

  • There exists no standard way to check namespaces to see if a given id has already been assigned.
  • There exists no standard way to reserve a name, within a namespace, for a small period of time while non-atomic transactions are taking place.

Functional Requirements

  1. Ability to check if a name exists in a specified namespace and, if so, which namespace
  2. Ability to group namespaces together to form a namespace group
  3. Ability to check if a name exists in a specified namespace group and, if so, which namespace(s)
  4. Ability to manage temporary reservations, to include
    • create a reservation in a namespace, if the name does not already exist in that namespace
      • in an individual namespace
      • in a namespace group
    • group created reservations
    • set the timeout for a reservation
    • delete a reservation from the namespace / namespace group in which it was created
    • delete a set of reservations that have added to one group of reservations
    • update a reservation
  5. Ability to manage permanent reservations, to include
    • create a reservation in an individual namespace
    • delete a reservation from the namespace in which it was created
    • update a reservation

Nonfunctional Requirements

  1. Must be implemented as a clustered stateless session bean.
  2. Methods must be exposed as web services.
  3. Service must be distributable across multiple load balanced nodes but share a common set of reservations
  4. Connections to service must be secure
  5. Services must be explicitly authorized to use the name arbiter
  6. System must have low latency response times, less than 500ms to check if a name exist, and less then 750ms to check if a name exist and then reserve it.
  7. Must be easy to extend to work with other namespaces

Implementation Details

Documentation

Author Cathy Winfrey
Date 2005/05/02
Last Updated 2008/07/14

Overview

Name Arbiter provides the functionality to check for the existence of a name in one of the configured namespaces / namespace groups. The matching algorithm is defined on a per namespace basis. Name Arbiter provides support for a set of temporary reservations in each namespace / namespace group. It also supports the creation of permanent (non-expiring) reservations in each individual namespace, which act as an extension to that namespace's collection of names.

As its name implies, the namespace group functionality allows a single query to be made to determine whether or not a name is available (not yet in use) in a set of namespaces. In the current configuration the pid namespace group is defined to query all namespaces in which the existence of a name blocks the use of that name as a new pid value.

The temporary reserve functionality allows creation, querying, updating, and deletion of temporary reservations. Each temporary reservation has an associated expiration time. If a temporary reservation is not removed explicitly by the service that created it, it will be removed automatically when the expiration time arrives. See Javadoc methods. When a name is reserved in a namespace group, in addition to returning an availability of 'false' when a query is made against the group, any availability query against a namespace included in that group will also return an availability of 'false'. It is important to note that a 'false' returned by an attempt to create a temporary reservation in a namespace / namespace group may simply be an indication that the name is already in use in that namespace / namespace group.

The permanent reserve functionality allows creation, querying, updating, and deletion of permanent reservations in an individual namespace. These permanent reservations extend the directory / database / collection of names contained in that individual namespace. This allows an availability of 'false' to be returned for a name which would not be found by a standard query in a given namespace. Example: create a permanent reservation for the name 'root' in the iPlanet (mail-server) namespace to prevent its use as an ED UUPid, even though no mail server account for that name exists. The method called to create a permanent reservation follows the same steps that the target namespace should use when creating a name directly in that namespace – create a temporary reservation and, only if this succeeds, create the permanent reservation. These steps are necessary because of the non-atomic nature of the transaction. Permanent reservations have a state, either active or inactive. Only active permanent reservations are included in availability checks unless the query method called by the client is one provided for support of queries for all or only inactive permanent reservations.

The Name Arbiter functionality is exposed through a clustered stateless session bean. Through the use of a Registry database table for storage of the temporary and permanent reservations, these reservations are instantly available across the cluster.

Usage Scenario

A VT pid creation program, which must not allow duplicate pids to be created, is an example of a client of Name Arbiter. The client program uses the Name Arbiter to make sure that the proposed pid value is available. A call to a Name Arbiter query method that checks current availability would seem like the correct action. However, due to the non-atomic nature of the transaction

  1. check availability (Name Arbiter function)
  2. create pid (client system function)

the possibility exists that the proposed pid value could be assigned by another program between a reported availability of 'true' and the creation of the pid account. Therefore the procedure should be

  1. create a temporary reservation for the proposed pid value (Name Arbiter function) – which will fail if the proposed value is not available
  2. create the pid (client system function)
  3. remove the temporary reservation (Name Arbiter function)

Configuration

An individual namespace is used by Name Arbiter when the following steps have been performed:

  1. provide a Java class that concretely extends the AbstractIndividualNamespace class
    • primarily implement the isNameStoredDB method to query this namespace
    • if needed, provide a properties file for data needed by this handler class such as connection information
  2. provide a Java class that concretely extends the AbstractPermReserveHandler class
  3. add an entry for this namespace to the ArbitratedNamespace class
  4. add a data source description for this namespace to the ArbitratredDataSource class
  5. place required configuration entries for this namespace in the namearbiter-config.xml file.

A group namespace is used by Name Arbiter when it is configured in the namearbiter-config.xml file.

Current Configuration

namearbiter-config.xml as of 14 July 2008:

<?xml version="1.0" encoding="utf-8"?>
 
<na:namearbiter
      xmlns:na="http://www.middleware.vt.edu/schema/namearbiter"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://www.middleware.vt.edu/schema/namearbiter namespace-config.xsd">
 
  <namespaces>
    <namespace name="email-address" casesensitivity="false">
      <handler>edu.vt.middleware.namearbiter.namespaces.EmailNamespace</handler>
      <permhandler>edu.vt.middleware.namearbiter.namespaces.DefaultPermReserveHandler</permhandler>
    </namespace>
    <namespace name="uupid" casesensitivity="false">
      <handler>edu.vt.middleware.namearbiter.namespaces.UUPIDNamespace</handler>
      <permhandler>edu.vt.middleware.namearbiter.namespaces.DefaultPermReserveHandler</permhandler>
    </namespace>
    <namespace name="email-alias" casesensitivity="false">
      <handler>edu.vt.middleware.namearbiter.namespaces.EmailAliasNamespace</handler>
      <permhandler>edu.vt.middleware.namearbiter.namespaces.DefaultPermReserveHandler</permhandler>
    </namespace>
    <namespace name="mail-server" casesensitivity="false">
      <handler>edu.vt.middleware.namearbiter.namespaces.EmailAliasNamespace</handler>
      <permhandler>edu.vt.middleware.namearbiter.namespaces.DefaultPermReserveHandler</permhandler>
    </namespace>
    <namespace name="departmental-pid" casesensitivity="false">
      <handler>edu.vt.middleware.namearbiter.namespaces.MailServerNamespace</handler>
      <permhandler>edu.vt.middleware.namearbiter.namespaces.DefaultPermReserveHandler</permhandler>
    </namespace>
    <namespace name="dpid-email-address" casesensitivity="false">
      <handler>edu.vt.middleware.namearbiter.namespaces.DpidEmailNamespace</handler>
      <permhandler>edu.vt.middleware.namearbiter.namespaces.DefaultPermReserveHandler</permhandler>
    </namespace>
    <namespace name="dpid-email-alias" casesensitivity="false">
      <handler>edu.vt.middleware.namearbiter.namespaces.DpidEmailAliasNamespace</handler>
      <permhandler>edu.vt.middleware.namearbiter.namespaces.DefaultPermReserveHandler</permhandler>
    </namespace>
    <namespace name="active-directory" casesensitivity="false">
      <handler>edu.vt.middleware.namearbiter.namespaces.ActiveDirecotryNamespace</handler>
      <permhandler>edu.vt.middleware.namearbiter.namespaces.DefaultPermReserveHandler</permhandler>
    </namespace>
  </namespaces>
 
  <groups>
    <group name="email"/>
    <group name="pid"/>
  </groups>
 
  <group-membership>
    <group name="email">
       <namespace name="email-address"/>
       <namespace name="email-alias"/>
       <namespace name="mail-server"/>
       <namespace name="dpid-email-address"/>
       <namespace name="dpid-email-alias"/>
    </group>
    <group name="pid">
       <namespace name="uupid"/>
       <group name="email"/>
       <group name="active-directory"/>
       <namespace name="departmental-pid"/>
    </group>
  </group-membership>
 
<arbiter>
    <reserve-handler>edu.vt.middleware.namearbiter.NATempReservedNames</reserve-handler>
  </arbiter>
 
</na:namearbiter>

Details

Each individual namespace is defined by including a <namespace> element in this file within the element <namespaces></namespaces>. The structure of the namespace element is:

  <namespace name="...." case-sensitivity="...">
    <handler>Java class that handles queries against this namespace</handler>
    <permhandler>Java class that handles permanent reservations for this namespace</permhandler>
  </namespace>

The value specified in the name attribute must match the type name in the associated ArbitratedNamespace entry. This ArbitratedNamespace entry is provided by the client system when calling a Name Arbiter method as the means to specify the namespace for the requested processing. The handler is the Java class that implements the AbstractIndividualNamespace class. This handler class implements the query functionality for the actual data store that contains the names of this namespace, not including the temporary and permanent reservations. Any configuration-type information needed by this handler that is not hard-coded in the handler itself must be provided in, and accessed by the handler from, a properties file. Typically a properties file is used for

  1. sensitive information such as connection credentials, which should be encrypted
  2. information that differs by deployment environment (dev / pprd / prod)

Each individual namespace contains a case sensitivity property in the namespace element. This case sensitivity is used for the names in this namespace's data store as well as for its temporary and permanent reservations. Attempting to include individual namespaces with different case sensitivity values in the same group namespace is an error and will cause that group namespace always to return an availability of 'false' until the misconfiguration is corrected.

A single temporary reserve handler is used by all configured individual namespaces and namespace groups. It is configured in the element

  <arbiter>
    <reserve-handler>Java class that handles temporary reservations</reserve-handler>
  <arbiter>

This class should use a methodology that makes the reservations instantly available across the cluster. Currently a Registry database table is used.

If namespace groups are needed, they are configured using two elements – groups and group-membership. The groups element simply lists the groups being defined, using the structure:

  <groups>
    <group name="..."/>
    <group name="..."/>
  </groups>

As with the namespace name attribute, the value specified in the name attribute must match the type name in the associated ArbitratedNamespace entry. This ArbitratedNamespace entry is provided by the client system when calling a Name Arbiter method as the means to specify the namespace for the requested processing. For each listed group, the group membership(s) are defined using the structure:

  <group name="pid">
     <namespace name="uupid"/>
     <namespace name="departmental-pid"/>
     <group name="email"/>
     <namespace name="active-directory"/>
  </group>

within the <group-membership></group-membership> element. Each namespace element included in the group membership must have a name attribute value that exactly matches, including case, the value in a defined namespace element. Similarly, each group element included in the group membership must have a name attribute value that exactly matches the value in a defined groups element.

Checking name availability in a namespace group is performed against each individual member of that group in the order in which they are listed in the group element of the group-membership – until either the name is found to be in use or all group members have been checked. Some efficiency is gained by ordering the entries by the probability of a match being found.

Existing namespace details

email-address

The handler class for this namespace, EmailNamespace.java, queries the Registry for a matching primary VT email address. Therefore, the name submitted to Name Arbiter is adjusted by appending the string '@vt.edu' before the query is executed.

uupid

The handler class for this namespace, UUPIDNamespace.java, queries the Registry for a matching VT Uupid.

email-alias

The handler class for this namespace, EmailAliasNamespace.java, queries the Registry for a matching email alias. Since an alias is an email address, the name submitted to Name Arbiter is adjusted by appending the string '@vt.edu' before the query is executed.

mail-server

The handler class for this namespace, MailServerNamespace.java, queries the VT main mail server for matches. The Middleware ldap libraries are used to connect to the ldap directory of this mail server to perform the query, in clear text. Three fields are checked:

  • uid
  • cn
  • mailAlternateAddress

Since mailAlternateAddress is an email address, the name submitted to Name Arbiter is adjusted by appending the string '@*' before the query is executed, but the adjustment is needed only for the mailAlternateAddress part of the ldap filter constructed for the ldap query. When this namespace is queried because of its inclusion in the email namespace group, it typically will duplicate the checks done against other namespaces uupid, email-address, and email-alias. However, this check is required because a few locally-defined accounts do exist in the mail server directory.

The details for this namespace are configured in the namearbiter.mail.ldap.properties file.

active-directory

The handler class for this namespace, ActiveDirectoryNamespace.java, queries the VT main Windows Active Directory (Hokies) for matches. The Middleware ldap libraries are used to connect to the ldap directory of this Active Directory server to perform the query, using a SSL connection. Three fields are checked:

  • name
  • cn
  • samAccountName

As with the mail-server namespace, when this namespace is queried because of its inclusion in the pid namespace group, it often duplicates the checks done against other namespaces including uupid and departmental-pid. However, this check is required because many accounts exist only in Active Directory.

The details for this namespace are configured in the namearbiter.ad.ldap.properties file. In addition, the SSL key for the SSL connection to Active Directory must be included in the na.truststore file.

departmental-pid

The handler class for this namespace, DepartmentalPIDNamespace.java, queries the Registry for a matching VT Departmental Pid account Uupid.

dpid-email-address

The handler class for this namespace, DpidEmailNamespace.java, queries the Registry for a matching primary VT Departmental Pid account email address. Therefore, the name submitted to Name Arbiter is adjusted by appending the string '@vt.edu' before the query is executed.

dpid-email-alias

The handler class for this namespace, DpidEmailAliasNamespace.java, queries the Registry for a matching Departmental Pid account email alias. Since an alias is an email address, the name submitted to Name Arbiter is adjusted by appending the string '@vt.edu' before the query is executed.

Comments

middleware/devel/ed/name-arbiter.txt · Last modified: 2015/06/01 12:02 (external edit)