IMF-GEC10-QSR: release_notes.txt

File release_notes.txt, 7.1 KB (added by Rudra Dutta, 8 years ago)

Developer Release Notes

Line 
1PERFSONAR IMFRealTime Service
2
30. Installation
4Please read INSTALL. This package is based on Perfsonar's Skeleton service. The orignial README and INSTALL files are renamed as README.original and INSTALL.original for reference. However when you read the original README and INSTALL, keep in mind that the default directories are changed to fit our needs. Briefly, the following directories and files are created after installation:
5        /var/log/perfsonar/imfrealtime.log (defined in daemon_logger.conf for logging)
6        /var/lib/perfsonar/imfrealtime/ (defined in daemon.conf for local store and data)
7        /opt/perfsonar_ps/imfrealtime/ (default directory for installation)
8
9Note that the installation scripts only support RedHat based Linux because it requires something like chkconfig. However it should be simple to port them to other distributions. In addition to the Perl modules and LibXML2 required by Perfsonar, the IMFRealTime service requires mh (measurement handler) Perl module installed. mh follows standard Perl installation procedures.
10
111. General Description
12
131.1 Perfsonar concept
14This service aims at integrating the real-time network measurement developed by GENI-IMF into the Perfsonar architecture. A normal Perfsonar package such as PerfsonarBUOY usually implements two services: Measurement Point (MP) service and Measurement Archive (MA) service. The MP service uses user-provided configuration file to perform pre-scheduled measurement. The measurement data are collected by a collector process forked by the MP and sent to a MA. The MA service, essentially a database, provides interfaces to Perfsonar users following Perfsonar's XML schema.
15
161.2 IMFRealTime Architecture
17The IMFRealTime service is different from a normal Perfsonar service (MA or MP) in the sense that it implements a bit of both. It uses the mh Perl module and expands Perfsonar's configuration file to provide the MP service. However, instead of sending the results to an MA, the collected data are saved locally. The main reason behind this solution is that we want to avoid the delay introduced by adding an extra layer of database between the users and the MP. Consequently, the IMFRealTime service also needs to provide a user interface for real-time user queries in the absence of a standard Perfsonar MA.
18
192. Implementation Details
20
212.1 Startup script
22Perfsonar IMFRealTime package provides a script called imf_realtime to start the service. As a regular startup script, it provides the start/stop/restart/status options. We enhance it by adding the test and debug options.
23#imf_realtime test
24will always return a hard-coded number (-55.55) for any queries on port power instead of the real port power retrieved from a device. This feature is useful for troubleshooting because it rules out possible network device configuration problems.  As another option,
25#imf_realtime debug
26allows you to run the service in debug mode.
27
282.2 daemon.conf file
29The startup script invokes daemon.pl. For instance, the command may look like:
30#daemon.pl --config=/opt/perfsonar_ps/imfrealtime/etc/daemon.conf --pidfile=imfrealtime.pid --piddir=/var/run --logger=/opt/perfsonar_ps/imfrealtime/etc/daemon_logger.conf --user=perfsonar --group=perfsonar
31Among other things required by regular Perfsonar services, daemon.conf describes the endpoint, i.e., how users can access this service and how the measurements will be made. For example, the following element is used to describe the measurements:
32
33                        <equipment>
34                                        hostport        3082   
35                                        hostname        os.unc.ben
36                                        device  Polatis
37                                        username                                                root
38                                        password                                                root
39                                        montype PORTPOWER
40                                        <range>
41                                                        portrange       1..4,7
42                                        </range>
43                        </equipment>
44
45This element is mostly self-explanatory, however, it's worth noting that the portrange (i.e., the ports that we want to measure) leverages Perl Regular Expression so you can easily specify multiple ports. In the above example, we want to measure the power of the Polatis optical switch's port 1, 2, 3, 4 and 7. Also note that the hostport/username/password describe device's configuration so that users do not need to store them locally and provide them in each query. 
46
472.3 daemon.pl file
48Reading daemon.pl file helps understand the whole structure of the IMFRealTime service. Briefly, daemon.pl forks a psService process for each service defined in daemon.conf. The process listens to the defined port and handles requests from users. For each service, if the results are collectable, daemon.pl forks a collection process for it. For the IMFRealTime service, all the collection process does is to run IMFRealTime::makeMeasurement() when the timer collection_interval defined in daemon.conf expires. IMFRealTime::makeMeasurement uses the mh Perl module to retrieve measurement data from devices defined in daemon.conf and save the result into a data file, which is also defined in daemon.conf. Note that to provide users the latest measurement data as quickly as possible, SysV IPC is used to notify the latest measurement data to the psService process every time a new measurement is made. This way, when a query asking for real-time measurement data arrives, the answer is obtained from memory instead of the local data file.
49
502.4 XML schema
51bin/client.pl provides a quick way to test the service. For example you can use the following command to retrieve measurement data from the service:
52#./bin/client.pl http://localhost:9989/perfSONAR_PS/services/IMFRealTimeMP etc/requests/MeasurementRequest.xml.
53In this example, the first parameter (http://localhost:9989/perfSONAR_PS/services/IMFRealTime) is the endpoint defined in daemon.conf. The second parameter is a file to be sent to the service via SOAP. It follows Perfsonar's XML schema and is shown as follows:
54
55<?xml version="1.0" encoding="UTF-8"?>
56<nmwg:message xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"
57     xmlns:ber="http://ggf.org/ns/nmwg/characteristic/BER/2.0"
58     xmlns:power="http://ggf.org/ns/nmwg/characteristic/POWER/2.0"
59     xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/"
60     xmlns:layer0="http://ggf.org/ns/nmwg/topology/layer0/2.0/"
61     xmlns:unis="http://ogf.org/schema/network/topology/unis/20100528/"
62     type="MeasurementRequest"
63     id="MeasurementRequestMessage1">
64
65  <nmwg:metadata id="m-1" xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/" >
66        <power:subject>
67                <nmwgt:interface xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/">
68                        <nmwgt:node>
69                                <nmwgt:device>POLATIS</nmwgt:device>
70                                <nmwgt:montype>POWER</nmwgt:montype>
71                                <nmwgt:hostName>os.renci.ben</nmwgt:hostName>
72                                <nmwgt:hostPort>3082</nmwgt:hostPort>
73                 <layer0:port>
74                         <layer0:opticalPort>2</layer0:opticalPort>
75                 </layer0:port>
76                        </nmwgt:node>
77                </nmwgt:interface>
78        </power:subject>
79        <nmwg:eventType>http://ggf.org/ns/nmwg/characteristic/POWER/2.0</nmwg:eventType>
80
81  </nmwg:metadata>     
82<!--
83<nmwg:data id="data1" metadataIdRef="metadata1" xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/" />
84-->
85
86  <nmwg:data xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/" id="d-1" metadataIdRef="m-1"/>
87</nmwg:message>
88
89In the above example, the client queries the power of the Polatis optical switch's port 2.