 - 07/27/00 - updated the protocol with the new syntax to include the Release
   numbers, sequence numbers and the optional dns stuff.

 - 05/19/00 - modified some messages in Section III to incorporate XboneNode
   Class=<> line in messages. Also added another <name>=<value> pair for 
   sequence numbers in the XboneControl group.

 - 05/08/00 - added two new messages for DeAllocate all (Request & Reply). 
   Still need to think whether UserID and AuthType needs to be included in 
   any message from OM to the RD.

 - 05/03/00 - new section contains the messages that need to be modifed and 
   the messages that need to be added for separating the IP Allocation module 
    & support for optional DNS. Some new syntax has been added.

 - 04/24/00 - verified the actual messages that are being passed around 
   unless otherwise indicated.


Access Control Checks
---------------------

Access control for Xbone overlay creation and modification is governed
by two fields in the Resource Daemon (RD) node configuration file.
Those are the UserAuth and AccessLevel fields.  Both fields apply to
individual access control list (ACL) entries.

For overlay creation and modification messages received, the RD
performs a basic access control check.  The RD takes from that message
the UserId field in the XboneSecurity line.  The UserId field is a
string (often a user's email address).  That string is then pattern
matched against the UserAuth field in each of the node's ACL entries.
Thus, UserId=<snagle@isi.edu> would match UserAuth=<\*.isi.edu>.

There may be more than one ACL element that matches.  However, only
the first one encountered is used.  Thus, when defining the node
configuration file, the ACL should be organized from most-specific to
least-specific pattern order.


Node Resource Checks
--------------------

XboneNode lines, in messages sent by the Overlay Manager (OM) to a
Resource Daemon (RD), consist of a series of <name>=<value> pairs that
describe requested resources.  Each XboneNode line lists the complete
set of resources that the OM desires be present in a host node.  If an
OM is looking for host nodes with differing sets of resources, it will
specify more than one XboneNode line in the message that it multicasts
to RDs.

The RD will attempt to completely satisfy with its own node resources
the requested set of resources from each XboneNode line in sequence.
If the RD cannot satisfy any such resource set, the node resource
check will fail.  Otherwise, the RD will find a requested set of
resources that it can satisfy and the node resource check will succeed.

There are currently two classes of <name>=<value> resources.

The first class is <name>=<string>.  The <name> and <string> in the
XboneNode line must match a corresponding <name>=<string> assertion in
the RD's node database.  The match here between <name>s is precise,
while the <string> portion from the XboneNode line must pattern match
corresponding <string> in the node database.

Thus, if the line: XboneNode Class="host" was a requested resource in
a RD's node database.  Assume that the node database had the entry:
Class="host+router".  The <name> Class is clearly present in the node
database.  Since "host" pattern matches with the string "host+router",
the requested resource does exist at this node.

The second class is InterfaceCount=<count>.  In this case the RD
ensures that at least <count> uncommitted tunnel interfaces remain
available at this node and that this number would not exceed the
maximum allocation of tunnels for the ACL with which the request is
associated.


============================================================================
Section I :- Syntax of X-Bone API
----------------------------------------------------------------------------

An Xbone message consists of zero or more of the Xbone
description/command lines discussed below, followed by
the an "end of command" line (i.e. XboneEOC).

Includes new <name>=<value> pairs required for the new features as described
in Section III.

Xbone
  Version=<int>
  Release=<int> or <string of numbers separated by spaces enclosed in quotes>
  Seq=<int>

XboneControl
  Command={ResourceDiscovery, CreateOverlay, DNSUpdate, ListOverlay,
           OverlayStatus, ModifyOverlay, DestroyOverlay, DestroyAll,
	   IPv4_Allocation, IPv4_Deallocation}
  Transaction={Request, Reply}

XboneOverlay
  Name=<string>
  SearchRadius=<int>
  DNS={1,0}
  
XboneNetwork
  Topology={star, ring, linear, spanning, ...}
  IPsecAuthentication={none,md5-hmac,undef}
  IPsecEncryption={none,des-cbc,undef}
  Application={none,...}
  DiameterMax=<int>				# not used
  Bandwidth=<spec>				# not used
  BandwidthReservation={1,0}			# not used

XboneCreator
  Name="User Name"
  Email=user@site.org


XboneNode
  Class={host, router, ipv4_allocd, host+router}    
  OS={FreeBSD, Solaris, Linux, ...}    
  {RIP, RED, IPv6, other}			# not used              
  OverlayCount=<int>                   		# not used
  NodeCount=<int>
  InterfaceCount=<int>
  ID=mul.isi.edu                
  MaxOverlayCount=<int>				# not used    
  Status={in,out}               
  IPaddr=<local addres>
  CurrentOverlayCount=<int>     		# not used
  MaxTunnelCount=<int>          		# not used
  CurrentTunnelCount=<int>      		# not used

XboneTunnel			
  LocalAddr=<ipaddr>
  RemoteAddr=<ipaddr>		
  Status={up,down}

XboneMonitor            			# none used.
  Frequency=<spec>
  Type={status, info, warning, error, etc ...}
  ReportLogFile=/etc/xbone.log
  ReportEmail=user@foo.org
  ReportPage=310-822-1511,114
  ReportDaemon=<host>:<port>

XboneSecurity                
  UserId=hacker              
  AuthType={pgp, none, x509, ipaddr}

XboneReturn
  Code=<int>
  Msg=<string>

XboneNodeCommand   route {add,delete} <parms>
XboneNodeCommand   tunnel {add, delete} <parms>
XboneNodeCommand   tunnel killall
XboneNodeCommand   dns {add,delete} <parms>
XboneNodeCommand   overlay delete <name>
XboneNodeCommand   overlay killall
XboneNodeCommand   ping

XboneEOC


============================================================================
Section II :-	Actual messages being sent around.
----------------------------------------------------------------------------

[1.1] CreateOverlay from GUI to Overlay Mangager

   Xbone Version=1.0
   XboneControl Command=CreateOverlay Transaction=Request 
   XboneOverlay Name=overlay.xbone.net SearchRadius=3 DNS=1
   XboneNetwork Topology=star \
		IPsecAuthentication=undef \
		IPsecEncryption=undef \
		Application=none
   XboneCreator Name="Joe Touch" Email=touch@isi.edu
   XboneSecurity UserId=touch@isi.edu AuthType=x509
   XboneNode Class=host   NodeCount=9 OS=freebsd
   XboneNode Class=router NodeCount=9 OS=freebsd
   XboneEOC

[1.2] ResourceDiscovery from Overlay Manager to Resource Daemon

   Xbone Version=1.0 Release="1.2 1.1" Seq=935723
   XboneControl Command=ResourceDiscovery Transaction=Request
   XboneOverlay Name=overlay.xbone.net
   XboneNetwork Topology=star \
		IPsecAuthentication=undef \
		IPsecEncryption=undef \
		Application=none
   XboneCreator Name="Joe Touch" Email=touch@isi.edu
   XboneSecurity UserId=touch@isi.edu AuthType=x509
   XboneNode Class=host   InterfaceCount=9 OS=freebsd	 
   XboneNode Class=router InterfaceCount=9 OS=freebsd		
   XboneEOC							

[1.3] ResourceDiscovery from Resource Daemon to Overlay Manager

   Xbone Version=1.0 Release=1.2 Seq=935723
   XboneNode Class=host OS=freebsd \
	     InterfaceCount=9999 ID=mul.isi.edu \
             IPaddr=128.9.160.99 
   XboneEOC

[1.4] DNSUpdate from OverlayManager to DNS RDs

   Xbone Version=1.0
   XboneControl Command=DNSUpdate Transaction=Request
   XboneOverlay Name=overlay.xbone.net
   XboneNetwork Topology=star \
		IPsecEncryption=undef \
		IPsecAuthentication=undef \
		Application=undef 
   XboneCreator Name="Joe Touch" Email=touch@isi.edu
   XboneSecurity UserId=touch@isi.edu AuthType=x509
   XboneNodeCommand dns add host1.overlay.xbone.net 198.32.6.1
   XboneNodeCommand dns add host2.overlay.xbone.net 198.32.6.2
   XboneNodeCommand dns commit
   XboneEOC

[1.5 DNSUpdate from DNS RDs to Overlay Manager

   Xbone Version=1.0
   XboneControl Command=DNSUpdate Transaction=Reply
   XboneOverlay Name=overlay.xbone.net
   XboneReturn Code=0 Msg=""
   XboneEOC

[1.6] CreateOverlay from Overlay Manager to Resource Daemon

   Xbone Version=1.0 Release=1.2
   XboneControl Command=CreateOverlay Transaction=Request
   XboneOverlay Name=overlay.xbone.net
   XboneNetwork Topology=star \
		IPsecEncryuption=undef \
		IPsecAuthentication=undef \
		Application=none 
   XboneCreator Name="Joe Touch" Email=touch@isi.edu
   XboneSecurity UserId=touch@isi.edu AuthType=x509
   XboneNode Class=host OS=freebsd ID=mul.isi.edu IPaddr=128.9.160.99 
   XboneNodeCommand tunnel add 192.168.1.2 192.168.1.1 \
			0xfffffffc 128.9.160.75 128.9.160.102
   XboneNodeCommand tunnel add 192.168.0.2 192.168.0.1 \
			0xfffffffc 192.168.1.2 192.168.1.1
   XboneNodeCommand route add -net 192.168.0.0 \
			-netmask 255.255.255.224 192.168.0.1
   XboneEOC

[1.7] CreateOverlay from Resource Daemon to Overlay Manager

   Xbone Version=1.0 Release=1.2
   XboneControl Command=CreateOverlay Transaction=Reply
   XboneOverlay Name=overlay.xbone.net
   XboneReturn  Code=0 Msg="Error would go here"
   XboneEOC

[1.8] CreateOverlay from Overlay Manager to GUI

   Xbone Version=1.0
   XboneControl Command=CreateOverlay Transaction=Reply
   XboneOverlay Name=overlay.xbone.net SearchRadius=3
   XboneNetwork Topology=star
   XboneCreator Name="Joe Touch" Email=touch@isi.edu
   XboneSecurity UserID=touch@isi.edu AuthType=x509
   XboneNode InterfaceCount=1000 OS=freebsd Status=in \
	      IPaddr=128.9.160.102 ID=amc.isi.edu Class=host
   XboneNode InterfaceCount=1000 OS=freebsd Status=in \
	      IPaddr=128.9.160.75 ID=hbo.isi.edu Class=host
   XboneNode InterfaceCount=1000 OS=freebsd Status=in \
	      IPaddr=128.9.160.110 ID=rum.isi.edu Class=router
   XboneReturn  Msg="Error msg would go here."            #only used if error
   XboneEOC

---------------------------------------------------------------------------

[2.1] ListOverlays from GUI to Overlay Manager

   Xbone Version=1.0
   XboneControl Command=ListOverlays Transaction=Request
   XboneSecurity UserId=touch@isi.edu AuthType=x509
   XboneEOC

[2.2] ListOverlays from Overlay Manager to GUI

   Xbone Version=1.0
   XboneControl Command=ListOverlays Transaction=Reply
   XboneOverlay Name=overlay.xbone.net			# only if overlays
   XboneOverlay Name=overlay1.xbone.net			# exist
   XboneEOC

---------------------------------------------------------------------------

[3.1] DestroyOverlay from GUI to Overlay Manager

   Xbone Version=1.0
   XboneControl Command=DestroyOverlay Transaction=Request
   XboneOverlay Name=overlay.xbone.net.
   XboneSecurity UserId=touch@isi.edu AuthType=x509
   XboneEOC

[3.2] DestroyOverlay from Overlay Manager to Resource Daemon

   Xbone Version=1.0 Release=1.2
   XboneControl Command=DestroyOverlay Transaction=Request
   XboneOverlay Name=overlay.xbone.net
   XboneSecurity UserId=touch@isi.edu AuthType=x509
   XboneNode ID=amc.isi.edu
   XboneNodeCommand overlay delete overlay.xbone.net
   XboneEOC

[3.3] DestroyOverlay from Resource Daemon to Overlay Manager

   Xbone Version=1.0 Release=1.2
   XboneControl Command=DestroyOverlay Transaction=Reply
   XboneOverlay Name=overlay.xbone.net
   XboneReturn Code=0 Msg=""
   XboneEOC

[3.4] DNSUpdate message from OM to primary DNS RD's during Destroy Overlay

   Xbone Version=1.0
   XboneControl Command=DNSUpdate Transaction=Request
   XboneOverlay Name=overlay.xbone.net
   XboneSecurity UserId=touch@isi.edu AuthType=x509
   XboneNodeCommand dns delete overlay.xbone.net
   XboneNodeCommand dns commit
   XboneEOC

[3.5] DNSUpdate reply from primary DNS RD's to OM during Destroy Overlay

   Xbone Version=1.0
   XboneControl Command=DNSUpdate Transaction=Reply 
   XboneOverlay Name=overlay.xbone.net
   XboneReturn Code=0 Msg=""
   XboneEOC

[3.6] DNSUpdate message from OM to secondary DNS RD's during Destroy Overlay

   Xbone Version=1.0
   XboneControl Command=DNSUpdate Transaction=Request
   XboneOverlay Name=overlay.xbone.net
   XboneSecurity UserId=touch@isi.edu AuthType=x509
   XboneNodeCommand dns commit
   XboneEOC

[3.7] DNSUpdate reply from secondary DNS RD's to OM during Destroy Overlay

   Xbone Version=1.0
   XboneControl Command=DNSUpdate Transaction=Reply 
   XboneOverlay Name=overlay.xbone.net
   XboneReturn Code=0 Msg=""
   XboneEOC

[3.8] DestroyOverlay from Overlay Manager to GUI

   Xbone Version=1.0
   XboneControl Command=DestroyOverlay Transaction=Reply
   XboneReturn Msg="Overlay overlay.xbone.net removed"
   XboneEOC

---------------------------------------------------------------------

[4.1] OverlayStatus from GUI to Overlay Manager
 
   Xbone Version=1.0
   XboneControl Command=OverlayStatus Transaction=Request
   XboneOverlay Name=overlay.xbone.net SearchRadius=0
   XboneSecurity UserId=touch@isi.edu AuthType=x509
   XboneEOC

[4.2] OverlayStatus from Overlay Manager to Resource Daemons

   Xbone Version=1.0 Release=1.2
   XboneControl Command=OverlayStatus Transaction=Request
   XboneOverlay Name=overlay.xbone.net
   XboneSecurity UserId=touch@isi.edu AuthType=x509
   XboneNode ID=amc.isi.edu
   XboneNodeCommand ping
   XboneEOC

[4.3] OverlayStatus from Resource Daemons to Overlay Manager

   Xbone Version=1.0 Release=1.2
   XboneControl Command=OverlayStatus Transaction=Reply
   XboneOverlay Name=overlay.xbone.net
   XboneSecurity UserId=touch@isi.edu AuthType=x509
   XboneNode Class=host OS=freebsd InterfaceCount=998 \
	     ID=amc.isi.edu IPaddr=128.9.160.102 Status=in 
   XboneTunnel LocalAddr=192.168.1.1 RemoteAddr=192.168.1.2 Status=up
   XboneTunnel LocalAddr=192.168.0.1 RemoteAddr=192.168.0.2 Status=up
   XboneReturn Code=0 Msg=""
   XboneEOC

[4.4] OverlayStatus from Overlay Manager to GUI

   Xbone Version=1.0
   XboneControl Command=OverlayStatus Transaction=Reply
   XboneOverlay Name=overlay.xbone.net
   XboneSecurity UserId=touch@isi.edu AuthType=x509
   XboneCreator Email=touch@isi.edu Name="Joe Touch"
   XboneNetwork Application=none IPsecAuthentication=undef \
		Topology=linear IPsecEncryption=undef
   XboneNode Class=host OS=freebsd InterfaceCount=998 ID=amc.isi.edu \
	     IPaddr=128.9.160.102 Status=in 
   XboneTunnel LocalAddr=192.168.1.1 RemoteAddr=192.168.1.2 Status=up
   XboneTunnel LocalAddr=192.168.0.1 RemoteAddr=192.168.0.2 Status=up
   XboneNode Class=host OS=freebsd InterfaceCount=998 ID=hbo.isi.edu \
	     IPaddr=128.9.160.75 Status=in 
   XboneTunnel LocalAddr=192.168.1.2 RemoteAddr=192.168.1.1 Status=up
   XboneTunnel LocalAddr=192.168.0.2 RemoteAddr=192.168.0.1 Status=up
   XboneEOC

---------------------------------------------------------------------------

[5.1] DestroyAll from GUI to OverlayManager

   Xbone Version=1.0
   XboneControl Command=DestroyAll Transaction=Request
   XboneSecurity UserId=touch@isi.edu AuthType=x509
   XboneEOC

[5.2] DestroyAll from OverlayManager to RD's (multicast)

   Xbone Version=1.0 Release=1.2 Seq=964716151
   XboneControl Command=DestroyAll Transaction=Request
   XboneSecurity UserId=sheth@isi.edu AuthType=x509
   XboneNodeCommand overlay killall
   XboneEOC

[5.4] DestroyAll from OM to primary DNS RD

   Xbone Version=1.0
   XboneControl Command=DNSUpdate Transaction=Request
   XboneSecurity UserId=sheth@isi.edu AuthType=x509
   XboneNodeCommand dns delete xbone.net	
   XboneNodeCommand dns commit			
   XboneEOC					

[5.5] DestroyAll reply from primary DNS RD to OM

   Xbone Version=1.0 Release=1.2
   XboneControl Command=DNSUpdate Transaction=Reply
   XboneOverlay Name=***UNKNOWN***
   XboneReturn Code=0 Msg=""
   XboneEOC

[5.6] DestroyAll from OM to secondary DNS RD

   Xbone Version=1.0
   XboneControl Command=DNSUpdate Transaction=Request 
   XboneSecurity UserId=sheth@isi.edu AuthType=x509    
   XboneNodeCommand dns commit			       
   XboneEOC					       

[5.7] DestroyAll reply from secondary DNS RD to OM

   Xbone Version=1.0 Release=1.2
   XboneControl Command=DNSUpdate Transaction=Reply
   XboneOverlay Name=***UNKNOWN***
   XboneReturn Code=0 Msg=""
   XboneEOC

[5.8] DestroyAll from OverlayManager to GUI

   Xbone Version=1.0
   XboneControl Command=DestroyAll Transaction=Reply
   XboneReturn Code=0 Msg=""
   XboneEOC

---------------------------------------------------------------------------

[6.2] ListOverlays from process to its own ResourceDaemon:

   XboneControl Command=ListOverlays Transaction=Request
   XboneSecurity UserId=banerjea@isi.edu AuthType=x509
   XboneEOC

[6.3] ListOverlays Reply from ResourceDaemon to that process:

   XboneControl Command=ListOverlays Transaction=Reply
   XboneOverlay Name=t-ovl.xbone.net
   XboneOverlay Name=a-ovl.xbone.net
   XboneOverlay Name=b-ovl.xbone.net
   XboneEOC


============================================================================
Section III :-	Work in progress .....
----------------------------------------------------------------------------


These are the messages that have to be added/changed for 1) separating the IP 
allocation module, 2) including the XboneNode Class=<> in all messages to the 
RD's. Need to think more on these.

[1.x] ResourceDiscovery from IP Allocation RD to Overlay Manager
# Should there be a Release field here?

   Xbone Version=1.0 Release=1.2 Seq=3248335
   XboneControl Command=ResourceDiscovery Transaction=Reply
   XboneNode Class=ipv4_allocd ID=mul.isi.edu \
             IPaddr=128.9.160.99 
   XboneEOC

[1.x] Actual request for IP addresses from the OM to the RD
# Should there be a Release field here?

   Xbone Version=1.0 Release=1.2
   XboneControl Command=IPv4_Allocation Transaction=Request
   XboneNode Class=ipv4_allocd
   XboneOverlay Name=overlay.xbone.net TunnelCount=9
   XboneEOC

[1.x] Reply from the IP Alloc RD to OM 
# Should there be a Release field here?

   Xbone Version=1.0 Release=1.2
   XboneControl Command=IPv4_Allocation Transaction=Reply
   XboneOverlay Name=overlay.xbone.net NetAddress=0.0.0.0 \
		Netmask=255.255.255.224	LinkMask=0xfffffffc 
   XboneEOC

[3.2] DestroyOverlay from Overlay Manager to Resource Daemon

   Xbone Version=1.0 Release=1.2
   XboneControl Command=DestroyOverlay Transaction=Request
   XboneOverlay Name=overlay.xbone.net
   XboneSecurity UserId=touch@isi.edu AuthType=x509
   XboneNode Class=host ID=amc.isi.edu
   XboneNodeCommand overlay delete overlay.xbone.net
   XboneEOC

[3.4] DNSUpdate message from OM to DNS RD's during Destroy Overlay

   Xbone Version=1.0
   XboneControl Command=DNSUpdate Transaction=Request
   XboneOverlay Name=overlay.xbone.net
   XboneNode Class=dns
   XboneSecurity UserId=touch@isi.edu AuthType=x509
   XboneNodeCommand dns delete overlay.xbone.net
   XboneNodeCommand dns commit
   XboneEOC

[3.x] Request for IP Deallocation from OM to IP Alloc RD
# Should there be a Release field here?

   Xbone Version=1.0 Release=1.2
   XboneControl Command=IPv4_Deallocation Transaction=Request
   XboneNode Class=ipv4_allocd
   XboneOverlay Name=overlay.xbone.net NetAddress=192.168.0.32
   XboneEOC

[3.x] Reply from IP RD to OM
# Should there be a Release field here?

   Xbone Version=1.0 Release=1.2
   XboneControl Command=IPv4_Deallocation Transaction=Reply
   XboneOverlay Name=overlay.xbone.net
   XboneReturn Code=0 Msg=""
   XboneEOC

[4.2] OverlayStatus from Overlay Manager to Resource Daemons

   Xbone Version=1.0 Release=1.2
   XboneControl Command=OverlayStatus Transaction=Request
   XboneOverlay Name=overlay.xbone.net
   XboneSecurity UserId=touch@isi.edu AuthType=x509
   XboneNode Class=host ID=amc.isi.edu
   XboneNodeCommand ping
   XboneEOC

[5.2] DestroyAll from OverlayManager to ResourceDaemon

   Xbone Version=1.0 Release=1.2
   XboneControl Command=DestroyAll Transaction=Request
   XboneSecurity UserId=touch@isi.edu AuthType=x509
   XboneNode Class=host ID=ifc.isi.edu
   XboneNodeCommand overlay killall
   XboneEOC

[5.4c] DestroyAll from OM to primary DNS RD

   Xbone Version=1.0
   XboneControl Command=DNSUpdate Transaction=Request
   XboneNode Class=dns
   XboneSecurity UserId=sheth@isi.edu AuthType=x509
   XboneNodeCommand dns delete xbone.net	
   XboneNodeCommand dns commit			
   XboneEOC					

[5.4d] Destroy All from OM to secondary DNS RD

   Xbone Version=1.0
   XboneControl Command=DestroyAll Transaction=Request 
   XboneNode Class=dns
   XboneSecurity UserId=sheth@isi.edu AuthType=x509    
   XboneNodeCommand dns commit			       
   XboneEOC					       

[5.x] Request for IP Deallocate All
# Should there be a Release field here?
 
   Xbone Version=1.0 Release=1.2
   XboneControl Command=IPv4_DeallocateAll Transaction=Request
   XboneNode Class=ipv4_allocd
   XboneEOC

[5.x] Reply from IP RD to OM on Deallocate all message.
# Should there be a Release field here?

   Xbone Version=1.0 Release=1.2
   XboneControl Command=IPv4_DeallocateAll Transaction=Reply
   XboneReturn Code=0 Msg=""
   XboneEOC










