perfsonar development work

Author: zurawski
Date: 2007-09-18 14:44:05 -0400 (Tue, 18 Sep 2007)
New Revision: 273

Added:
   trunk/nmwg/doc/dLS/LSDiscovery.xml
   trunk/nmwg/doc/dLS/LSRing.xml
   trunk/nmwg/doc/dLS/LSToken-Join.xml
   trunk/nmwg/doc/dLS/LSToken-Leader.xml
   trunk/nmwg/doc/dLS/LSToken-Summary.xml
   trunk/nmwg/doc/dLS/LSToken-Token.xml
Removed:
   trunk/nmwg/doc/dLS/ex3.xml
   trunk/nmwg/doc/dLS/ex4.xml
Modified:
   trunk/nmwg/doc/dLS/dLS.xml
   trunk/nmwg/doc/dLS/ex1.xml
   trunk/nmwg/doc/dLS/ex2.xml
Log:
Adding in the algorithm details as well as several examples.

-jason



Added: trunk/nmwg/doc/dLS/LSDiscovery.xml

Added: trunk/nmwg/doc/dLS/LSRing.xml

Added: trunk/nmwg/doc/dLS/LSToken-Join.xml

Added: trunk/nmwg/doc/dLS/LSToken-Leader.xml

Added: trunk/nmwg/doc/dLS/LSToken-Summary.xml

Added: trunk/nmwg/doc/dLS/LSToken-Token.xml

Modified: trunk/nmwg/doc/dLS/dLS.xml
===================================================================
--- trunk/nmwg/doc/dLS/dLS.xml  2007-09-18 01:10:50 UTC (rev 272)
+++ trunk/nmwg/doc/dLS/dLS.xml  2007-09-18 18:44:05 UTC (rev 273)
@@ -56,22 +56,51 @@
         functionality that has been present in the system for some time.  The
         basic LS supports the storing and querying of perfSONAR Service
         information as well as metadata about data stored or gathered by a
-        particular pS service instance.  This document describes the support
+        particular pS service instance.  
+      </t>
+      
+       <figure anchor="ls-op">
+           <preamble>LS Operation</preamble>
+           <artwork>
+ _____                              _____
+|     |     Register Metadata      |     |
+| LS  | &lt;------------------------&gt; | MA  |
+|_____| &lt;---------                 |_____|
+                 |                  _____
+                 |                 |     |
+                 ----------------&gt; | TS  |
+            Query for Services     |_____|
+
+           </artwork>
+           <postamble>Services interacting with an LS</postamble>
+       </figure>      
+      
+      <t>  
+        This document describes the support
         necessary to extend this service to a distributed mode of operation. 
         There are a few key facets of this mode of operation:
       </t>
       
       <list style="symbols">
         <t>Summarization – to reduce the amount of information sent over the 
-           network, some form of data reduction must take place
+           network or to anonymize sensitive data, some form of data 
reduction
+           must take place.
         </t>
         <t>Scope – to enable a hierarchy of systems, some form of scoping 
-           must exist
+           must exist that forms logical communication and data exchange
+           channels.
         </t>
         <t>Search – information location is key and the way in which 
-           distributed search is accomplished must be described
+           distributed location and search is handled is the crux of this
+           service.
         </t>
-      </list>          
+      </list>    
+      
+      <t>
+        Additionally we present solutions to issues related to the operation
+        of this seemless service including bootstrapping and domain specific
+        concerns.  
+      </t>      
     </section>
 
 
@@ -85,60 +114,85 @@
            configuration, or other forms of bootstrapping may occur.  A 
service
            registers a metadata record about itself and full metadata (i.e.
            containing all information such as subject, eventType(s), and any 
-           parameters) about stored (or gathered) data. Such a record is
-           called Lookup Information (see <xref target="lookup-info" />). The
-           idea is to move the metadata from a local XML data store to a
-           specialized LS with additional searching capabilities.  While a
-           service instance may support limited searching, this is not
-           required as they should be focused on storing or gathering data 
and
-           leave the lookup functionality to the LS. Possible exceptions are
-           rapidly changing Metadata like the most recent timestamp and full
-           details of data stored in long-term archival MAs.
+           parameters, see <xref target="service-metadata" />) about stored
+           (or gathered) data. Such a record is called Lookup Information
+           (see <xref target="lookup-info" />). The idea is to move the
+           metadata from a local XML data store to a specialized LS with
+           additional searching capabilities.  While a service instance
+           may support limited searching, this is not required as they
+           should be focused on storing or gathering data and leave the
+           lookup functionality to the LS. Possible exceptions are rapidly
+           changing Metadata like the most recent timestamp and full details
+           of data stored in long-term archival MAs.
         </t>
 
 
 <t>
 <vspace blankLines="2" />
-START_NOTE (Jason 9/17/07):
-It needs to be made more clear here which LS instances will be getting
-summary vs. which LS instances will be getting full metadata.  Martin
-or Jeff should clarify this.
+START_NOTE (Jason 9/18/07):
+<vspace blankLines="1" />
+Question 1)
+<vspace blankLines="1" />
 END_NOTE:
 <vspace blankLines="2" />
 </t>
 
         
-        <t>The LS that a service contacts to register becomes the “Home LS”
-           (HLS) of that particular service.  It is the responsibility of the
-           HLS to make summary data about the all of the pS services it 
knows 
-           of available to the larger enterprise and to draw relevant queries
-           to itself.  In order to make information available to the LS 
cloud, 
+        <t>The LS that a service contacts to register becomes the "Home LS"
+           (HLS, see <xref target="glossary" />) of that particular service.
+           It is the responsibility of the HLS to make summary data about the
+           all of the pS services it knows of available to the larger
+           enterprise and to draw relevant queries to itself.  In order to
+           make information available to the LS cloud, 
            the HLS will advertise this summary information to other LS
-           instances to propagate appropriate information.  The most natural
+           instances to propagate the appropriate information.  
+         </t>
+         
+       <figure anchor="hls-cloud">
+           <preamble>HLS Cloud</preamble>
+           <artwork>
+ _____                      _____ 
+|     |                    |     |
+| LS  | &lt;----------------- | LS  |
+|_____|   Communicate via  |_____|
+   |       token exchange     ^
+   |                          | Broadcast Summary info to
+   |          _____           | all peers when holding 
+   |         |     |          | the token
+   |-------&gt; | LS  | ---------|
+             |_____|
+
+           </artwork>
+           <postamble>HLS instances communicating via token.  The holder
+                      of the token will inform everyone of summary
+                      information.</postamble>
+       </figure>   
+         
+         <t>  
+           The most natural
            summarization is based on the topology of the network (like in 
            network routing).  Thus, a given HLS will perform topology-based 
            summarization and will include this information as well as 
eventType
-           information to other LSs in its “local scope”.  Likewise, more 
-           aggressive summarization will take place when the “local scope” 
-           registers into the “global scope”.  This is analogous to the 
-           aggregation that occurs in IGPs  (local scope) and EGPs (global 
+           information to other LSs in its "lower scope" (formerly known as
+           "local scope").  Likewise, more aggressive summarization can take
+           place when the "lower scope" registers into the "upper scope"
+           (formerly known as "global scope").  This is analogous to the
+           aggregation that occurs in IGPs  (lower scope) and EGPs (upper 
            scope).  
         </t>  
-      
 
+
 <t>
 <vspace blankLines="2" />
-START_NOTE (Jason 9/17/07):
-There is a lot of mention of XSLT in here.  Are we sticking with the 
-story that we still need to use XSLT or can we go with more niave methods
-(i.e. we will be doing the tree structure to match IP, etc., other things
-such as locations/Org Names/eventTypes doesn't need XSLT to be 
-summarized.)  This should also be cleared up by Martin
+START_NOTE (Jason 9/18/07):
+<vspace blankLines="1" />
+Question 2)
+<vspace blankLines="1" />
 END_NOTE:
 <vspace blankLines="2" />
 </t>
-
     
+    
         <t>Summarization will be performed using either Extensible Stylesheet
            Language Transformation (XSLT) documents or the XQuery language.  
Each
            of these approaches has pros and cons.  XQuery is supported by XML
@@ -151,9 +205,10 @@
 
 <t>
 <vspace blankLines="2" />
-START_NOTE (Jason 9/17/07):
-Has the story changed on additional summary levels?  It doesn't seem 
-necessary to me.
+START_NOTE (Jason 9/18/07):
+<vspace blankLines="1" />
+Question 3)
+<vspace blankLines="1" />
 END_NOTE:
 <vspace blankLines="2" />
 </t>
@@ -163,25 +218,15 @@
            the network topology currently used in metadata subjects as well 
as
            additional items such as eventTypes.  The output of this process
            becomes a "service summary" that represents a breadth of the 
original
-           input.  See <xref target="summary-ex" /> for a mock-up of the
+           input.  See <xref target="LSToken-Summary" /> for a mock-up of the
            summary output. Additional transformations, while aggressive, will
            strive to preserve as much information as possible to remain 
useful
            during the search procedures.  
         </t>  
 
-
-<t>
-<vspace blankLines="2" />
-START_NOTE (Jason 9/17/07):
-Does this go?  Are all summarizations the same now?
-END_NOTE:
-<vspace blankLines="2" />
-</t>
-
-
         <t>In early discussions, we left the possibility open for multiple 
types
            of summarization for different types of services and data.  This 
is
-           still possbility.  There are arguments to simplify the types of
+           still possibility.  There are arguments to simplify the types of
            summarizations that can occur.   The first is that arbitrary
            summarizations will yield arbitrary XML data, making discovery
            queries more difficult to construct.  Thus it seems to be 
sufficient
@@ -191,11 +236,11 @@
         </t>  
       
         <t>We may target cases where various summarizations are possible, but
-           for now summarization on the basis of  topology seems sufficient. 
+           for now summarization on the basis of topology seems sufficient. 
         </t>  
       
         <t>A related question is that of policy.  In our discussions, we had 
the
-           intution that some domains would want to register less information
+           intuition that some domains would want to register less 
information
            than others.  One example is whether the actual IP addresses of 
MPs
            capable of launching active measurements.  These hosts, if
            compromised, can pose significant denial of service threat. 
@@ -207,14 +252,14 @@
       <!-- Scope Section -->
 
       <section anchor="scope" title="Scope"> 
-      
-        <t>The next question is how to form the local and global scopes.  
The 
-           simplest answer is that the local scope be formed based on the 
domain
+
+        <t>The next question is how to form the lower and upper scopes.  The 
+           simplest answer is that the lower scope be formed based on the 
domain
            name of the participating systems.  That would allow e.g.
            internet2.edu, geant2.net, and poznan.pl to potentially operate 
more
            than one LS instance inside their own domains (for performance and
            scalability.)  As LS instances come online they will invoke
-           bootstrapping procedures to find and join a locally scoped group
+           bootstrapping procedures to find and join a lower scoped group
            first.
         </t>  
       
@@ -230,42 +275,164 @@
            <eref 
target="http://eu.perfsonar.net";>http://eu.perfsonar.net</eref>).  
         </t>  
 
+        <t>
+          With the generalities of what a scope is taken care of, we now turn
+          our attention to central algorithms of the dLS:
+            <list style="symbols">
+              <t>Join Procedure</t>
+              <t>Token Passing</t>
+              <t>Summarization Notification</t>
+            </list>
+        </t>
+        
+        <t>
+          The algorithms will be presented in the light of the lower 
scoping, 
+          but will be used in the same manner for the upper scope as well.
+        </t>
 
-<t>
-<vspace blankLines="2" />
-START_NOTE (Jason 9/17/07):
-Jason is slated to clean up and add more to this section.
-END_NOTE:
-<vspace blankLines="2" />
-</t>
+        <section anchor="join" title="Join Procedure">
+          <t>
+            When an LS instance comes online it will have some bootstrapping
+            knowledge of potential peers (both inter and intra domain).  The
+            inter-domain knowledge is used first to establish a connection to
+            an already in progress ring, or perhaps to start a ring that may
+            not exist yet.  
+          </t>
+          
+          <t>
+            An LS will continuously search it's LSRing information (see 
+            <xref target="LSRing" />) until a successful response to an 
LSToken
+            message (with a 'join' eventType, see 
+            <xref target="LSToken-Join" />) is seen.  The LS will search 
though
+            the successful response to this message and update its LSRing 
with
+            the returned information.  This can mean updating the 
'contentSize'
+            and 'active' parameters as well as adding new LS instances.  
These
+            parameters are indicative of the LS's size (i.e. how many 
services
+            are registering with it) and 'live-ness' (i.e. were we 
successful in
+            contacting it recently).  
+          </t>
+          
+          <t>
+            After updating the LS will broadcast another LSToken message 
(with
+            a 'summary' eventType, see <xref target="LSToken-Summary" />) to 
all
+            of the 'active' LS instances from it's LSRing.  Again the 
responses
+            will be parsed to get any useful updated information.  Each of 
the
+            recipient LS instances will do the same, including adding this 
new
+            member to their own lists (as many of them will not know of it's
+            existence yet).  
+          </t>
+          
+          <t>
+            After this initial warm-up the LS will observe the rules of token
+            etiquette and remain silent until it is contacted with a token, 
or 
+            it has not seen one in a very long time.
+          </t>
+        </section>
 
+        <section anchor="tokens" title="Token Passing">
+          <t>
+            The 'token' is a message (see <xref target="LSToken-Token" />) 
+            meant to be passed around an LSRing to the various members in 
some
+            order.  We will pass from smallest 'contentSize' to largest
+            (with appropriate wrap around), and at any given time an LS
+            instance will know where the next token message should go.  
+          </t>
+          
+          <t>
+            The token can be viewed as 'permission to talk' and permits the 
+            holder to send it's summary information to all available LS
+            instances (see <xref target="LSToken-Summary" />).  The responses
+            will be parsed to get any useful updated information.
+          </t>
+          
+          <t>
+            The holder of the token, after completing summarization, will 
wait
+            some pre-determined amount of time before sending the token to 
the
+            next LS instance.  LS instances should be sensitive (although 
not 
+            overly sensitive) to the progression of the token through the 
+            ring.  A token should expect to arrive in some interval equal to
+            the size of the ring times the waiting interval, with tolerance
+            above and below this value.  
+          </t>
+          
+          <t>
+            If the token has been 'dropped' along its path the next LS in 
line
+            will detect this and re-send it to not break the communication 
+            chain.  If for some reason a second token appears too quickly 
after
+            the previous token, any LS instance should see this dispose of 
the
+            duplicate message.
+          </t>
+        </section>
+        
+        <section anchor="summary-blast" title="Summarization Notification">
+          <t>
+            As discussed in the prior two sections there are two acceptable
+            instances to send your summary to the LSRing:
+            <list style="numbers">
+              <t>When first joining</t>
+              <t>When holding the token</t>
+            </list>
+          </t>
+          
+          <t>
+            In the first case we are explicitly entering ourselves into the
+            ring when we get our first message from a peer.  This ensures we
+            show up in the token rotation the next cycle.  The second case is
+            the routine exchange started when a token arrives from a peer.
+          </t>
+          
+          <t>
+            <xref target="LSToken-Summary" /> contains examples of the 
message
+            format for this exchange.  It is left up to the implementation 
when
+            the summarization occurs (i.e. at message send time, or also as a
+            periodic event).  
+          </t>
+          
+        </section>
 
-        <t>The global scope should consist of one representative from each 
of the
-           local scopes.  This representative could be manually configured, 
but
-           one of the design goals of the LS was to be largely 
self-configuring.
-           Thus, we will use a token-passing and leader election scheme to 
allow
-           this representative to be automatically selected.  For leader
-           election, a typical protocol should be used.  The basic mechanism 
of
-           leader election is that participants form a logical ring and 
initiate
-           an election.  An election can be initiated when a new machine 
joins,
-           at system start time, or when a host feels that the leader may 
have
-           failed based on failure to receive a periodic token.  When an 
election
-           is initiated, the initiating host sends an election message to its
-           counter-clockwise neighbor and changes its state to “ELECTING”.  
It
-           places its identifier inside the message.  The ulimate goal is for
-           the host with the highest identifier to be chosen.  When a host
-           receives an election message, it compares its identifier with that
-           in the message.  It forwards the higher of the identifiers.  When 
a
-           node receives a message with its own identifier, it knows that it 
has
-           been selected and the election terminates.
+        <t>
+           Building on the previous algorithms, we turn our attention to the
+           upper scope.  This logical ring should consist of one
+           representative from each of the lower scopes.  This representative
+           will be selected based on the 'contentSize' parameter, which as we
+           have discussed previously is a count of the number of metadata
+           elements the LS is responsible for.  
+        </t>
+        
+        <t>
+          The theory behind this choice of leader is that unladen LS 
instances
+          will not be as loaded processing requests and responses from 
clients
+          and other services, thus the choice to name them as leaders is
+          natural.  This also allows a domain to impose leadership on a
+          specific LS by having it not accept registrations for example, and 
+          only serving in the leader role.  
+        </t>
+        
+        <t>
+          All LS instances will have a complete view at any given time (and
+          updated over time) of the values of the 'contentSize' parameter for
+          all peer LS instances in an LSRing.  This ensures that the 'Leader'
+          and 'Vice-Leader' are always known.  Explicit election is therefore
+          not required, and succession can pass between the two executives
+          quickly.  
+        </t>
+        
+        <t>
+          The Leader and Vice-Leader LS instances should exchange messages
+          periodically to ensure that in the event of a failure the lower
+          level will still have a link to the upper level (see 
+          <xref target="LSToken-Leader" />).  A Vice-Leader will be 
monitoring 
+          the time between successive communications from the Leader to be 
sure
+          it has not failed.  In the event that it has, the 'Join' procedure
+          will start to the upper level to keep the hierarchy complete.
+        </t>
+ 
+        <t>The timeout mechanism(s) will need to be further specified.  It 
can
+           be computed as a function of the number of nodes in the ring.  
This
+           is the Target Token Rotation Time (TTRT).  There may be a future
+           point at which we need to think about ring splitting, but we
+           believe that this can be managed by further scope levels.
         </t>  
-
-        <t>The timeout mechanism needs to be specified.  It can be computed 
as a
-           function of the number of nodes in the ring.  This is the Target 
Token
-           Rotation Time (TTRT).  There may be a future point at which we 
need to
-           think about ring splitting, but we believe that this can be 
managed by
-           further scope levels.
-        </t>  
       
         <t>Scopes are named based on URIs.  The top-level domain provides a
            natural basis for the formation of these URIs.  These URIs may be
@@ -273,7 +440,7 @@
            need a mechanism to provide another level of hierarchy above the
            domain level and below the root, but that is left for future work.
            Note: I would like to see this be something like: 
-           <eref 
target="http://lsls.perfsonar.net/global/internet2.edu/";>http://lsls.perfsonar.net/global/internet2.edu/</eref>.
 
+           <eref 
target="http://lsls.perfsonar.net/master/internet2.edu/";>http://lsls.perfsonar.net/master/internet2.edu/</eref>.
 
            Actual syntax doesn’t matter that much but I would like the
            following components: 
            
@@ -281,7 +448,7 @@
              <t>well-known hostname to get the current root.hints from
                 (lsls)</t> 
              <t>a place holder for where we can break the scope between
-                organization and global (global)</t> 
+                organization and upper levels (master)</t> 
              <t>a zero-conf default name for the organization
                 (internet2.edu)</t> 
              <t>A way to sub-divide the organization (everything after
@@ -296,26 +463,24 @@
     
       <section anchor="search" title="Search">
       
-      
+
 <t>
 <vspace blankLines="2" />
-START_NOTE (Jason 9/17/07):
-I still thing we should stick with one here, and only alude to the fact that 
it
-may be done another way.  Adding too much in (especially if its not going to 
be
-implemented) is too complex.
+START_NOTE (Jason 9/18/07):
+<vspace blankLines="1" />
+Question 4)
+<vspace blankLines="1" />
 END_NOTE:
 <vspace blankLines="2" />
-</t>      
+</t>
       
-      
         <t>The search operation is obviously critical to the Lookup Service's
-           function.  It is envisioned that searching will take two major 
forms,
-           iterative and recursive, analogous to those used in DNS.  This 
design
-           will focus exclusively on iterative initially as the only method 
in
-           the first versions of the mLS. (Although we may comment on 
sections
-           that will need to be enhanced to deal with recursive queries.) The
-           key act when searching is to find what eventTypes exist for a
-           particular topology element or set of topology elements.
+           function.  It is envisioned that searching could take one of two 
+           major forms, iterative and recursive, analogous to those used in 
+           DNS.  This design will focus exclusively on iterative initially 
as 
+           the only method in the first versions of the dLS. The key act 
when 
+           searching is to find what eventTypes exist for a particular
+           topology element or set of topology elements.
         </t>  
 
         <t>As outlined above, the full data that services register to an LS 
is
@@ -329,17 +494,6 @@
            down into two distinct phases -- Discovery and Metadata Query.    
  
         </t>  
 
-
-<t>
-<vspace blankLines="2" />
-START_NOTE (Jason 9/17/07):
-will need some examples of this.  Has the alg changed at all since this was
-first written?
-END_NOTE:
-<vspace blankLines="2" />
-</t>
-
-
            <section anchor="discovery" title="Discovery Phase">
              <t>The Discovery Phase is used to locate the set of 
Authoritative LS 
                 (or  LSes) for a given Subject/eventType tuple.  This 
requires a 
@@ -347,7 +501,8 @@
                 is not described yet, but which must consist of the 3-tuple 
of
                 Subject Summary, eventType and Authoritative LS.)  Either a 
specific
                 API call and a pre-prepared query, or some automatic 
mechanism, must
-                map the desired query into a query of the Discovery infoset. 
 
+                map the desired query into a query of the Discovery infoset 
(see 
+                <xref target="LSToken-Discovery" />).
              </t>
              
              <section anchor="discovery-alg" title="Discovery Algorithm">
@@ -369,15 +524,15 @@
                            infoset that matches the query.</t>
                
                         <t>Referral: This is returned when there is no match 
other
-                           than a “global wildcard”
+                           than a "global wildcard"
                          
                            <list style="numbers">              
                              <t>If this LS is not participating in the 
highest
-                                (global) scope, then it returns the leader 
of its
+                                (upper) scope, then it returns the leader of 
its
                                 current scope (or a direct referral to an 
instance
                                 of the next-higher scope.)  This is 
effectively a
-                                wildcard match saying “I don’t know the 
answer, but
-                                I know who might.” This is how the Metadata
+                                wildcard match saying "I don’t know the 
answer, but
+                                I know who might." This is how the Metadata
                                 registered to an LS in another scope 
(domain) is
                                 found.
                              </t>
@@ -395,7 +550,7 @@
                                 found that match. An LS instance will have 
summary
                                 information from other domains when it is
                                 participating in a higher-level scope (such 
as
-                                global).</t>
+                                upper).</t>
                
                              <t>Note: this is where recursive searches would 
be added
                                 into the discovery phase. The trail up the 
scope
@@ -428,19 +583,7 @@
              in the range of our discovery query, we can pose Metadata 
Queries
              to each of them. The results will be failure or success.  
           </t>
-          <t>Note: If recursion is added to the discovery phase, it would 
also
-             be possible to add recursion to the Metadata query phase. The LS
-             could query the other LS instances. (However, this is likely to
-             cause more problems for AA because it opens up the possibility 
of
-             caching metadata, not just summary data.) Future optimizations
-             may allow the inclusion of both queries in a single message 
linked
-             by chaining.  
-          </t>
-          <t>MG: Right, AA may be a problem. But another problem may be 
bigger
-             traffic. I'd let the client decide if to stop or go on after
-             getting a list of remote (than HLS) locations of requested
-             Lookup Information. 
-               </t>
+
              </section>
            
       </section>  
@@ -461,7 +604,7 @@
       </t>
 
       <t>We will maintain a service that maintains a list of currently known 
-         LS instances. These known instances should preferably be at the 
global
+         LS instances. These known instances should preferably be at the 
upper
          scope. All clients can cache this list. The service will be accessed
          via a well-known hostname, and could be requested via UDP messages.
          (We can also use TCP here for some sorts of anycast.)
@@ -477,13 +620,11 @@
 
       <t>The above discovery algorithm is used to find an LS within a given
          scope. Therefore, the only piece of information an LS should need to
-         be preconfigured with is the scope it belongs to. And as stated 
above,
-         that can be assumed to be “global:organization-dns-name”. Note: Need
+         be pre-configured with is the scope it belongs to. And as stated 
above,
+         that can be assumed to be "global:organization-dns-name". Note: Need
          to define the specific syntax above.
       </t>
 
-      <t>Also multicast is possible!  
-      </t>
 
     </section>
     
@@ -507,8 +648,8 @@
 
            <section anchor="lookup-info" title="Lookup Information">
              <t>Example Lookup Information of Measurement Archive. Metadata 
block
-                contains basic service information and data elements 
collects full
-                (or summarized? -TBD?) information about stored or gathered 
data.</t>
+                contains basic service information and data elements 
containing
+                the metadata from the MA.</t>
              <t>
                <artwork>
                        <![CDATA[
@@ -518,28 +659,73 @@
              </t>
            </section> 
            
+           <section anchor="LSRing" title="LS Ring File Structure">
+             <t>Structure of the 'lower' and 'upper' LSRing files.</t>
+             <t>
+               <artwork>
+                       <![CDATA[
+                   <inline file="LSRing.xml"/>
+                 ]]>
+               </artwork>
+             </t>
+           </section>      
 
-           <section anchor="summary-ex" title="Summary Examples">
-             <t>Summary Input</t>
+           <section anchor="LSToken-Join" title="LS Joining Message for 
Joining a Ring">
+             <t>Structure of the LSToken messages focused on joining a 
ring.</t>
              <t>
                <artwork>
                        <![CDATA[
-                   <inline file="ex3.xml"/>
+                   <inline file="LSToken-Join.xml"/>
                  ]]>
                </artwork>
              </t>
-              
-             <t>Summary Output</t>
+           </section>   
+           
+           <section anchor="LSToken-Token" title="LS Token Message">
+             <t>Structure of the LSToken messages serving as the passable 
'token'.</t>
              <t>
                <artwork>
                        <![CDATA[
-                   <inline file="ex4.xml"/>
+                   <inline file="LSToken-Token.xml"/>
                  ]]>
                </artwork>
              </t>
            </section> 
            
+           <section anchor="LSToken-Summary" title="LS Summary Message">
+             <t>Structure of the LSToken messages focused on exchanging 
summary information.</t>
+             <t>
+               <artwork>
+                       <![CDATA[
+                   <inline file="LSToken-Summary.xml"/>
+                 ]]>
+               </artwork>
+             </t>
+           </section>      
 
+           <section anchor="LSToken-Leader" title="LS Leader Message">
+             <t>Structure of the LSToken messages dealing with when a Leader 
needs to inform the Vice-Leader
+                of the summaries from above.</t>
+             <t>
+               <artwork>
+                       <![CDATA[
+                   <inline file="LSToken-Leader.xml"/>
+                 ]]>
+               </artwork>
+             </t>
+           </section>      
+
+           <section anchor="LSToken-Discovery" title="LS Discovery Message">
+             <t>Structure of the LSDiscovery Message used to locate 
info-sets.</t>
+             <t>
+               <artwork>
+                       <![CDATA[
+                   <inline file="LSToken-Discovery.xml"/>
+                 ]]>
+               </artwork>
+             </t>
+           </section>     
+
            <section anchor="Message Types" title="Message Types">
         <list style="numbers"> 
           <t>Discovery – The Discovery request will contain a subject of the
@@ -559,6 +745,22 @@
             </list>
           </t>
         
+          <t>Token – Token messages will be used to exchange information
+             between LS instances.  The can be specialized (by eventType)
+             to handle different tasks such as Joining, exchanging summary
+             information, or used for leader communication.  
+            <list style="numbers">     
+              <t>LSTokenRequest</t>
+              <t>LSTokenResponse
+                <list style="numbers"> 
+                  <t>Success</t>
+                  <t>Refer</t>
+                  <t>Failure</t>
+                </list>              
+              </t>
+            </list>
+          </t>           
+
           <t>Other...
             <list style="numbers">     
               <t>LS...Request</t>
@@ -570,7 +772,7 @@
                 </list>              
               </t>
             </list>
-          </t>          
+          </t>       
         
         </list>
            </section> 
@@ -591,7 +793,7 @@
     <section anchor="apdx" title="Appendices">
 
 
-           <section title="Glossary">
+           <section anchor="glossary" title="Glossary">
              <list style="symbols">
 
           <t>Service –  A Service is an application that communicates with
@@ -619,6 +821,12 @@
 
           <t>Home LS (HLS) – The Home LS of a Service is the LS where the
              Service registers its Lookup Information</t>
+             
+          <t>Upper (Global) Scope – The scoping paradigm meant to indicate
+             intra-domain relationships.</t>
+
+          <t>Lower (Local) Scope – The scoping paradigm meant to indicate
+             inter-domain relationships.</t>
            
              </list>
            </section>

Modified: trunk/nmwg/doc/dLS/ex1.xml
===================================================================
--- trunk/nmwg/doc/dLS/ex1.xml  2007-09-18 01:10:50 UTC (rev 272)
+++ trunk/nmwg/doc/dLS/ex1.xml  2007-09-18 18:44:05 UTC (rev 273)
@@ -1,29 +1,31 @@
-<nmwg:metadata id="17155427">
-  <netutil:subject id="17062918">
-    <nmwgt:interface>
+<nmwg:metadata id="metadata.17155427" 
+               xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";>
+  <netutil:subject id="subject.17062918" 
+                   
xmlns:netutil="http://ggf.org/ns/nmwg/characteristic/utilization/2.0/";>
+    <nmwgt:interface xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/";>
       <nmwgt:hostName>Gallup's.fr</nmwgt:hostName>
       <nmwgt:ifName>ge-1/1/0</nmwgt:ifName>
       <nmwgt:ifDescription>Gallup's description: 
ge-1/1/0</nmwgt:ifDescription>
       <nmwgt:ifAddress type="ipv4">229.148.7.224</nmwgt:ifAddress>
       <nmwgt:direction>in</nmwgt:direction>
-      <nmwgt:authRealm>RemoveMe!!! authRealm NOT USED</nmwgt:authRealm>
       <nmwgt:capacity>250000000</nmwgt:capacity>
     </nmwgt:interface>
   </netutil:subject>
-  <nmwg:eventType>utilization</nmwg:eventType>
+  
<nmwg:eventType>http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:eventType>
 </nmwg:metadata>
   
-<nmwg:metadata id="171558">
-  <netutil:subject id="17062918">
-    <nmwgt:interface>
+<nmwg:metadata id="metadata.171558" 
+               xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";>
+  <netutil:subject id="subject.17062919" 
+                   
xmlns:netutil="http://ggf.org/ns/nmwg/characteristic/utilization/2.0/";>
+    <nmwgt:interface xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/";>
       <nmwgt:hostName>Gallup's.fr</nmwgt:hostName>
       <nmwgt:ifName>ge-1/1/0</nmwgt:ifName>
       <nmwgt:ifDescription>Gallup's description: 
ge-1/1/0</nmwgt:ifDescription>
       <nmwgt:ifAddress type="ipv4">229.148.7.224</nmwgt:ifAddress>
       <nmwgt:direction>out</nmwgt:direction>
-      <nmwgt:authRealm>RemoveMe!!! authRealm NOT USED</nmwgt:authRealm>
       <nmwgt:capacity>250000000</nmwgt:capacity>
     </nmwgt:interface>
   </netutil:subject>
-  <nmwg:eventType>utilization</nmwg:eventType>
+  
<nmwg:eventType>http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:eventType>
 </nmwg:metadata>

Modified: trunk/nmwg/doc/dLS/ex2.xml
===================================================================
--- trunk/nmwg/doc/dLS/ex2.xml  2007-09-18 01:10:50 UTC (rev 272)
+++ trunk/nmwg/doc/dLS/ex2.xml  2007-09-18 18:44:05 UTC (rev 273)
@@ -1,5 +1,5 @@
 <nmwg:metadata 
id="http://shower.fr:8080/axis/services/MeasurementArchiveService";>
-  <perfsonar:subject id="subj.15977808">
+  <perfsonar:subject id="subject.15977808">
     <psservice:service id="229.148.249.60.16283379">
       <psservice:serviceName>Java RRD MA</psservice:serviceName>
       
<psservice:accessPoint>http://shower.fr:8080/axis/services/MeasurementArchiveService</psservice:accessPoint>
@@ -11,37 +11,39 @@
 
 <nmwg:data 
id="http://shower.fr:8080/axis/services/MeasurementArchiveService/1177595435/0";
 
            
metadataIdRef="http://shower.fr:8080/axis/services/MeasurementArchiveService";>
-  <nmwg:metadata id="17155427">
-    <netutil:subject id="17062918">
-      <nmwgt:interface>
+  <nmwg:metadata id="metadata.17155427" 
+                 xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";>
+   <netutil:subject id="subject.17062918" 
+                     
xmlns:netutil="http://ggf.org/ns/nmwg/characteristic/utilization/2.0/";>
+      <nmwgt:interface xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/";>
         <nmwgt:hostName>Gallup's.fr</nmwgt:hostName>
         <nmwgt:ifName>ge-1/1/0</nmwgt:ifName>
         <nmwgt:ifDescription>Gallup's description: 
ge-1/1/0</nmwgt:ifDescription>
         <nmwgt:ifAddress type="ipv4">229.148.7.224</nmwgt:ifAddress>
         <nmwgt:direction>in</nmwgt:direction>
-        <nmwgt:authRealm>RemoveMe!!! authRealm NOT USED</nmwgt:authRealm>
         <nmwgt:capacity>250000000</nmwgt:capacity>
       </nmwgt:interface>
     </netutil:subject>
-    <nmwg:eventType>utilization</nmwg:eventType>
+    
<nmwg:eventType>http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:eventType>
   </nmwg:metadata>
 </nmwg:data>
 
 <nmwg:data 
id="http://shower.fr:8080/axis/services/MeasurementArchiveService/1177595435/1";
 
            
metadataIdRef="http://shower.fr:8080/axis/services/MeasurementArchiveService";>
-  <nmwg:metadata id="17155428">
-    <netutil:subject id="17062918">
-      <nmwgt:interface>
+  <nmwg:metadata id="metadata.171558" 
+                 xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";>
+    <netutil:subject id="subject.17062919" 
+                     
xmlns:netutil="http://ggf.org/ns/nmwg/characteristic/utilization/2.0/";>
+      <nmwgt:interface xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/";>
         <nmwgt:hostName>Gallup's.fr</nmwgt:hostName>
         <nmwgt:ifName>ge-1/1/0</nmwgt:ifName>
         <nmwgt:ifDescription>Gallup's description: 
ge-1/1/0</nmwgt:ifDescription>
         <nmwgt:ifAddress type="ipv4">229.148.7.224</nmwgt:ifAddress>
         <nmwgt:direction>out</nmwgt:direction>
-        <nmwgt:authRealm>RemoveMe!!! authRealm NOT USED</nmwgt:authRealm>
         <nmwgt:capacity>250000000</nmwgt:capacity>
       </nmwgt:interface>
     </netutil:subject>
-    <nmwg:eventType>utilization</nmwg:eventType>
+    
<nmwg:eventType>http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:eventType>
   </nmwg:metadata>
 </nmwg:data>  
 

Deleted: trunk/nmwg/doc/dLS/ex3.xml

Deleted: trunk/nmwg/doc/dLS/ex4.xml