lookup service

readme

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 general instructions. Specifics are available with the code download.


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 -- How often to contact gLS, 180 minute (3hr)
      • 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(3hr)
      • 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/hLS/TSQueryRequest.xml

    These four will test the major functions of this service. To test:

    1. Ensure the service is started, it helps if you have configured logging to use the "Screen" so you may 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, return logging to normal and restart service via the init system.

    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.

    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 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:

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

    yum update

    or

    apt-get dist-upgrade

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