			              perfSONAR Topology Service

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

About:
------

The perfSONAR-PS Topology Service helps facilitate sharing of network topology.
Networks deploy the service and register an XML representation of their network
topology with it. Interested clients can then query the service to discover the
data they are interested in.

The perfSONAR-PS Topology Service relies on an XML database, Oracle XML DB, to
store the topology information. Clients can then use standard XPath and XQuery
queries to perform arbitrary queries against the topologies. 

Installation:
-------------

Please read the INSTALL file for instructions
  
Configuration:
--------------

The Topology Service comes pre-configured, allowing for for immediate testing.

There are several files that may be adjusted manually to configure this service
for a specific use case:

  - etc/daemon.conf: 
  
    Contains information that identifies the service uniquely and allows it to
    run in a given environment.  There are several options that should be
    changed:  
   
      external_address         - The address where clients can access this service from
      site_name                - The name of the organization deploying the service
      site_location            - The city/state/country where the service is located
      ls_instace               - The Lookup Service to register with

    There are also several options that may be changed for a configuration:

      port                     - Port the service listens on
      endpoint                 - Endpoint to contact the service
      ls_registration_interval - Length of time (minutes) between contacting LS 
	  read_only                - Whether remote clients can register topologies
      db_environment           - The directory to store the database in
      db_file                  - The filename for the Topology service
      enable_registration      - Turn on or off LS registration
    
    The rest of the items are normally not to be adjusted.

  - etc/daemon_logger.conf:

    Contains information related to logging, there are three modes:
    
      Log::Dispatch::Screen     - Log messages to screen (useful for debugging)
      Log::Dispatch::Syslog     - Log messages to syslog facility
      Log::Dispatch::FileRotate - Log messages to specified file

    In the file, there are example instances of each of the above, with the
    Screen and Syslog sections commented out.
    
Starting/Stopping:
------------------

The service comes with init scripts that may be used to start and stop
operation:

If installed via RPM, the service can be started or stopped with:

  /etc/init.d/topology_service start
  /etc/init.d/topology_service stop
  /etc/init.d/topology_service restart

The service can also be run in a manual fashion (useful for debugging):

  perl bin/daemon.pl --verbose --conf=etc/daemon.conf
  
Testing:
--------

The service comes with a client application and several test messages that can
be used to test functionality.  There are sample messages provided that can be
used to test the service:

  etc/requests/EchoRequest.xml
  etc/requests/TSQueryRequest.xml

These requests will test the major components of the service. To test:

  1) Ensure the service is started, it helps if you have run it using debug
     mode.  This is to monitor the service's activities.

  2) Run the client:
  
     perl bin/client.pl URL FILENAME
  
  3) Compare the results of the test with the comments in each file.  Note there
     may be some differences (e.g. id values, key values).  
     
  4) If everything looks OK, restart service with the init scripts.

Loading Topology:
-----------------
  OSCARS DCN Software:
  --------------------
  The OSCARS DCN service can be configured to automatically add there topology
  to a topology service.

  Manually:
  ---------
  To manually load a topology into a topology service, you must first create an
  XML topology file. After creating the XML file, there is an included script
  that lets you load the topology into the database. 

    1) Create a XML representation of your topology

    2) Run the load script:
       perl scripts/load_topology  --db_dir=/path/to/db/directory --db_filename=topology.dbxml topology.xml

	3) If no errors are printed to the screen, you should now be able to try
	   the requests in the Testing section and see the topology data.

Removing Elements:
------------------
  There is an included script to remove topology elements from the topology
  service. It takes the database information along with a list of topology
  element identifiers for elements to remove. It then removes those elements
  from the database.

    perl scripts/remove_elements --db_dir=/path/to/db/directory --db_filename=topology.dbxml --elements=IDENTIFIER[,IDENTIFIER,...]

  If no errors are printed to the screen, those elements will have been removed
  from the topology database.

Topology Descriptions:
----------------------
  The accepted topologies are somewhat flexible to be able to handle the DCN
  schema, as well as other schemas users might want to develop. There are 7
  broad elements that the service understands: domains, nodes, ports, links,
  paths and networks. These elements are structured hierarchically with
  domains, paths and networks at the top-level. Inside of domains can exist
  nodes, links, paths and networks. Ports exist inside nodes, and links can
  exist inside of ports. 

  Every element in the hierarchy has an “id” attribute. The ID takes the value
  of a Uniform Resource Name (URN) that contains not only an ID for the element
  defining it, but also its parent elements. This type of identifier is referred
  to as a fully-qualified identifier.  These IDs always begin with the prefix
  “urn:ogf:network:”. This prefix is followed by a colondelimited list of
  identifiers appropriate for that hierarchical level. For example, a
  fully-qualified port ID contains a domain ID, a node ID, and the port ID. The
  hierarchical level of each portion is indicated by either a
  “domain=”,"network=","path=",”node=”, “port=”, or “link=” prefix. Examples of
  different fully-qualified link ID types from the example topology files that
  come with the software are shown below:

  domain ID: urn:ogf:network:domain=blue.pod.lan
  node ID: urn:ogf:network:domain=blue.pod.lan:node=vlsr1
  port ID: urn:ogf:network:domain=blue.pod.lan:node=vlsr1:port=3
  link ID: urn:ogf:network:domain=blue.pod.lan:node=vlsr1:port=3:link=11.2.1.2

  When topology is added to the service, it is normalized into a hierarchy that
  matches that of the identifiers. This is done to ensure that it is feasible
  to construct queries no matter how the data was added to the service.

  Every topology sent to or received from the server will be wrapped in a
  <topology> element. This element is simply a wrapper containing one or more
  topological elements.

  The above restrictions are the only restrictions placed on the elements. If
  users want to add their own attributes to the various elements or otherwise
  extend the schema, the Topology Service will store and make available that
  data, as long as it matches the above schema.

  An example of this schema can be seen in the file "doc/example_topology.xml".
  The topology is the DCN topology of the Internet2 network as used by OSCARS.


Maintenance:
------------

Subscribe to the user mailing lists if you are seeking help on some problem
related to this software.  Announcements regarding availability of new releases
will also be sent to these locations

  perfSONAR-PS Users Group - https://mail.internet2.edu/wws/info/psps-users
  perfSONAR-PS Announcements - https://mail.internet2.edu/wws/info/psps-announce

  Performance Node Users - https://mail.internet2.edu/wws/info/performance-node-users
  Performance Node Announcements - https://mail.internet2.edu/wws/info/performance-node-announce

Also if you are using package management software and have installed the
Internet2 software repository, a typical upgrade should download new releases:

  yum update

Finally, check the following websites for news of software releases:

  http://software.internet2.edu
  http://www.internet2.edu/performance

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

Fri Apr  3 12:54:06 EDT 2009

