###
###  NOTE: this document is also significantly out of date in terms of
###        options and specific UI-type things.  the elements relating
###        to globus/gara/kx509/etc remain unchanged.
###

this is a rough sketch of how a CITI PMP test works.  our usage model 
presupposes an end-user who wants to run a roughly hop-by-hop performance 
analysis of the network between her workstation and a specified target (and 
in an environment where a "reasonable number" of the local routers have a PMP 
attached to them).  the following are prerequisites and an overview of 
our anticipated performance test request/response loop, first in broad
strokes and then in closer detail on certain steps.

the user is assumed to have authenticated with their kerberos identity 
(e.g., `kinit`) and have run `kx509`.  it is also assumed that the user is 
running a libpkcs11-savvy browser (e.g., mozilla with libpkcs11.so). 

then, in order to initiate the network test, the user would visit a webpage 
and input their IP address, their netmask, a destination IP address, and its 
corresponding netmask (if known; inferring/discovering the netmasks is in-
progress).  the webserver is presumably running apache with mod_kct, 
mod_kx509, and a gara client (often $APACHE/bin/globus_client).  

note that not all of these steps are fully implemented yet.  [2/27/2004]

actually, all that (and more) is finished now.  [6/20/2004]
   in addition to being able to specify the test endpoints by giving two
   endhost machine's IP addresses, there is now the -r/--routers commandline
   option.  this flag signifies that the two specified IP addresses instead
   represent routers' NICs; this is useful, e.g., when a network admin would
   want to schedule a nightly performance test between a core router and his
   institution's ingress router and the notion of "anchoring" the test 
   endpoints by giving _endhost_ IP addresses is unnecessarily cumbersome
   (or, in some cases, impossible -- e.g., if no endhost machines are present
   on the subnet or VLAN that you want to test; maybe there are certain QoS
   filters that you really want to hit and only router-to-router traffic is
   carried on the subnet/VLAN in question).

	
the user's test parameters are parsed, compiled into an RSL, and given to a
script that sets up the pairwise PMP test(s).  the script first determines 
the "best" PMP from which to launch a traceroute test in order to discover an 
approximate hopwise path from the test initiator's computer to the test's
target machine.  the script runs the globus_client and uses it to connect to
that "first PMP" and invoke a remote traceroute.  when the data return, the
script (back on the webserver, remember) uses it to find routers between the
test source and destination.  the script consults an LDAP directory to find
all available PMPs along the path and runs pairwise iperf tests between 
available PMPs and returns the data to the webserver and the user.  note that
this process might take "awhile".  eventually, we'll hook a report generator
up to it and results will be nicely sorted and graphed.

that's the overview.  

the specifics of the globus_client (on the webserver) communicating with each
(remote) PMP's globus_gatekeeper are where the details lie.  the globus_client
collects the user's kx509 temporary credentials (courtesy of mod_ssl, mod_kct, 
mod_kx509, and other players on the webserver, KCA, and the client workstation) 
and compiles the test parameters and authentication data into an RSL, which is
shipped over to the remote globus_gatekeeper on a given PMP.  

that (remote) globus_gatekeeper performs an authentication check on the 
credentials it is passed and, if everything checks out okay, runs the
globus_gatekeeper_gara_service (also on the remote machine).  the GGGS (ugh) 
parses the RSL and handles the remote invocation reservations.  this schedules  
work for the GARA resource manager (`diffserv_manager`, also on the 
remote machine), which performs an authorization check based on the user's 
credentials and requested action (which, in the case of a performance test, is 
either `traceroute` or `iperf`).  this authorization check is either done using 
AFS PTS group memberships (with mod_pts and Keynote) or using PERMIS (a Java-based 
authorization service backed by an LDAP directory).

if the authorization check passes, reservations are made, the remote job is
run, and results are sent back through the GGGS to the webserver.  if a 2-node
job is being run (as is the case when two PMPs run an iperf test between them),
the webserver would place reservations at both the iperf client PMP and the 
iperf server PMP, and both PMPs would send results back to the webserver.  if
there are further pairwise iperf tests to run, the script (back on the
webserver) repeats these steps and returns the test data as they come back.

there are still many more things going on another level of detail down, but
they probably aren't relevant just now.

CITI/dmr (richterd@citi.umich.edu)
2/18/2004	original
4/4/2004 	corrections
6/22/2004	status update and corretctions