<html><body>
<h2><a name="White_Pages_Replication"></a> White Pages Replication </h2>
<p>
This page describes Cougaar's support for replicated White Pages (WP)
naming servers, and how to configure Cougaar to enable replicated
servers.
</p><p>
</p><h3><a name="Design"></a> Design </h3>
<p>A Cougaar "society" is defined as all Cougaar nodes that share the
same set of naming service servers. This shared namespace allows the
agents to lookup each other's Message Transport Service (MTS) addresses
and send messages to one another.
</p><p>An agent's WP entry contains that agent's MTS protocol-specific
endpoint address, the agents location, and other information. This data
can be seen using the "/wp" servlet. Here's an example: </p><table border="1" cellpadding="0" cellspacing="0"> <tbody><tr><th maxcols="0" align="center" bgcolor="#6b7f93" valign="top"> Name </th><th maxcols="0" align="center" bgcolor="#6b7f93" valign="top"> Type </th><th maxcols="0" align="center" bgcolor="#6b7f93" valign="top"> URI </th><th maxcols="0" align="center" bgcolor="#6b7f93" valign="top"> <i>note</i> </th></tr>
<tr ><td bgcolor="#ffffff" valign="top"> MyAgent </td><td bgcolor="#ffffff" valign="top"> version </td><td bgcolor="#ffffff" valign="top"> version://1234/1234 </td><td bgcolor="#ffffff" valign="top"> <i>Timestamp of when the agent was started and last moved.</i> </td></tr>
<tr ><td bgcolor="#edf4f9" valign="top"> MyAgent </td><td bgcolor="#edf4f9" valign="top"> topology </td><td bgcolor="#edf4f9" valign="top"> node://foo.com/MyNode </td><td bgcolor="#edf4f9" valign="top"> <i>Which host and node the agent is on</i> </td></tr>
<tr ><td bgcolor="#ffffff" valign="top"> MyAgent </td><td bgcolor="#ffffff" valign="top"> server </td><td bgcolor="#ffffff" valign="top"> server:///true </td><td bgcolor="#ffffff" valign="top"> <i>Is this agent a WP server?</i> </td></tr>
<tr ><td bgcolor="#edf4f9" valign="top"> MyAgent </td><td bgcolor="#edf4f9" valign="top"> http </td><td bgcolor="#edf4f9" valign="top"> http://foo.com:8800 </td><td bgcolor="#edf4f9" valign="top"> <i>Browser URL for servlet requests</i> </td></tr>
<tr ><td bgcolor="#ffffff" valign="top"> MyAgent </td><td bgcolor="#ffffff" valign="top"> -RMI </td><td bgcolor="#ffffff" valign="top"> rmi://123.45.67.89:9876/org.cougaar.mts.base.MTImpl_Stub/1_-2ca_-80_0/01 </td><td bgcolor="#ffffff" valign="top"> <i>MTS RMI link address. By convention, MTS entries start with a "-"</i> </td></tr>
</tbody></table>
<p>
Cougaar's naming service supports multiple, replicated WP servers. A client node can query any WP server to<br>
1) <strong>lookup</strong> a remote agent's messaging addresses, and<br>
2) <strong>bind</strong> its local agents in the shared namespace.<br>
</p><p>
Nodes are responsible for selecting any WP server from the set of
configured servers and periodically renewing its bind leases with any
WP server. A WP server forwards all bind messages to all other WP
servers, allowing every server to keep a complete table of all WP
entries.
</p><p>
</p><center>
<img src="replicated_wp_figure1.png" alt="replicated_wp_figure1.png" height="459" width="338"><br>
(<i>figure from <a href="http://doc.cougaar.org/" target="_top">http://doc.cougaar.org</a> KIMAS 2005 paper "Scalability Aspects of Agent-based Naming Services"</i>)
</center>
<p>
</p><h3><a name="Configuration"></a> Configuration </h3>
<p>
The naming service is configured using "-D" system properties.
</p><p>
Specify each server using:<br>
<code>-Dorg.cougaar.name.server.WP-<i>number</i>=<i>agent</i>@<i>host</i>:<i>port</i></code><br>
E.g.<br>
<code>-Dorg.cougaar.name.server.WP-123=MyNamingFoo@bar.com:9876</code>
</p><p>The "123" numbers don't matter, so long as the -Ds for each JVM
don't conflict. I.e., Java keeps a "set" of the -Ds by key-to-value.
</p><p>
The backwards-compatible:<br>
<code>-Dorg.cougaar.name.server=<i>agent</i>@<i>host</i>:<i>port</i></code><br>
is equivalent to:<br>
<code>-Dorg.cougaar.name.server.WP-1=<i>agent</i>@<i>host</i>:<i>port</i></code>
</p><p>
On a node that's running a name server agent (ie. one of the above "agent@" agents), all the
WP -Ds must be set. That's required for the inter-server replication to work.
</p><p>
On any other node, you can optionally only set a subset of the -Ds, to restrict which WPs that node is allowed to use.
</p><p>
</p><h3><a name="Example_Configuration"></a> Example Configuration </h3>
<p>
Here's an example configuration, where: </p><ul>
<li> Node "A" on host "ahost" runs wp server "firstWP"
</li> <li> Node "B" on host "bhost" runs wp server "secondWP"
</li> <li> Node "C" is a wp client
</li></ul>
<p>
If "C" is allowed to use any WP, then the same "-D" system properties can be used on all nodes:
</p><pre> <runtime>
<vm_parameter name="-Dorg.cougaar.name.server.WP-1" value="firstWP@ahost:8888"/>
<vm_parameter name="-Dorg.cougaar.name.server.WP-2" value="secondWP@bhost:8888"/>
...
<runtime>
</pre>
<p>If, as an example, "C" is only allowed to use the "secondWP", then
each node will have a different list of "-D" system properties:
</p><pre> <runtime>
<node name="A">
<i><!-- nodes containing a WP server are required to list all WP -Ds --></i>
<vm_parameter name="-Dorg.cougaar.name.server.WP-1" value="firstWP@ahost:8888"/>
<vm_parameter name="-Dorg.cougaar.name.server.WP-2" value="secondWP@bhost:8888"/>
...
</node>
<node name="B">
<vm_parameter name="-Dorg.cougaar.name.server.WP-1" value="firstWP@ahost:8888"/>
<vm_parameter name="-Dorg.cougaar.name.server.WP-2" value="secondWP@bhost:8888"/>
...
</node>
<node name="C">
<i><!-- a node that is only a WP client can list any/all of the WP servers --></i>
<vm_parameter name="-Dorg.cougaar.name.server.WP-2" value="secondWP@bhost:8888"/>
...
</node>
</runtime>
</pre>
<p>
Here's the society XML file, which specifies the agents and their components:
</p><pre> <society>
<node name="A">
<agent name="firstWP">
<i><!-- required server component --></i>
<component class='org.cougaar.core.wp.server.Server'/>
</agent>
...
</node>
<node name="B">
<agent name="firstWP">
<i><!-- required server component --></i>
<component class='org.cougaar.core.wp.server.Server'/>
</agent>
...
</node>
<node name="C">
...
</node>
</society>
</pre>
<p>
</body></html>