This page details how to create and publish a central configuration that can be consumed by multiple perfSONAR hosts to build their regular testing configuration. The steps to do so can be broken down as follows and are covered in the remainder of this document:
If you are building the configuration file on a perfSONAR Toolkit host you may skip this step as your host has everything it needs. Otherwise, you will need to install the tool used to convert the configuration you build to its final format. You can install this tool via yum.
You will need to point your system at the Internet2 yum repository as detailed at their software site.
You may install the package with the following commands:
yum install perfsonar-meshconfig-jsonbuilder
apt-get install perfsonar-meshconfig-jsonbuilder
You need to build a configuration file using your favorite text editor. The syntax of the file is in Apache configuration format. For a full list of options see Mesh Configuration (.conf) file. It is also helpful to look at a few examples:
Let’s take a quick look at a simple example:
description Example Mesh Config <administrator> name John Smith email firstname.lastname@example.org </administrator> <organization> description Acme Examples, Inc <site> <host> description Acme East address east-bwctl.acme.local address east-owamp.acme.local </host> </site> <site> <host> description Acme West address west-bwctl.acme.local address west-owamp.acme.local </host> </site> </organization> <test_spec bwctl_test> type perfsonarbuoy/bwctl # Perform a bwctl test (i.e. achievable bandwidth) tool bwctl/iperf3 # Use 'iperf' to do the bandwidh test protocol tcp # Run a TCP bandwidth test interval 21600 # Run the test every 6 hours duration 20 # Perform a 20 second test force_bidirectional 1 # do bidirectional test random_start_percentage 10 # randomize start time omit_interval 5 # ignore first few seconds of test </test_spec> <test_spec owamp_test> type perfsonarbuoy/owamp # Perform a constant low-bandwidth OWAMP test packet_interval 0.1 # Send 10 packets every second (i.e. pause 0.1 seconds between each packet) loss_threshold 10 # Wait no more than 10 seconds for a response session_count 10800 # Refresh the test every half hour (once every 18000 packets) sample_count 600 # Send results back every 60 seconds (once every 600 packets) packet_padding 0 # The size of the packets (not including the IP/UDP headers) bucket_width 0.0001 # The granularity of the measurements force_bidirectional 1 # do bidirectional test </test_spec> <group acme_bwctl_group> type mesh member east-bwctl.acme.local member west-bwctl.acme.local </group> <group acme_owamp_group> type mesh member east-owamp.acme.local member west-owamp.acme.local </group> <test> description Example Throughput Testing group acme_bwctl_group test_spec bwctl_test </test> <test> description Example OWAMP Testing group acme_owamp_group test_spec owamp_test </test>
Let’s take a closer look at each section:
That’s the basic idea and considerable variation can be seen in these files. As indicated earlier the best resource is to look at the provided examples and the syntax guide for more details.
This is an important file! You should create back-ups if possible or consider putting it in some type of source control repository (git, subversion, etc). Losing this file after putting effort into building a large test configuration can be very frustrating, so avoid that pitfall if you can.
Once you have created your configuration file, you will need to convert it to a JSON format. This format is the one understood by the perfSONAR client software reading it, but is not so easily generated by a human with a text editor (hence the conversion step). You will need to run the command build_json and give it the location of the configuration file to be converted and the file to output the JSON. The example below accepts the configuration file example.conf as input and outputs to /var/www/html/example.json:
/usr/lib/perfsonar/bin/build_json -o /var/www/example.json example.conf
Replace the output path with values appropriate to your setup. If it throws any errors it may be because of a syntax error so go back and review your file carefully. After the command successfully runs you should have a file to publish.
Once you have a JSON file you simply need to copy it to a web server. A few other things to consider when publishing your file: