[[PageOutline]]

= How to configure Plastic Slices monitoring on an OpenFlow !FlowVisor =

== Introduction ==

This page explains how to configure an !OpenFlow !FlowVisor node for the [wiki:PlasticSlices/MonitoringRecommendations Plastic Slices central monitoring configuration].  Before following these instructions, please ask GPO infra for a copy of the tarball
{{{
plastic-slices-monitor-flowvisor-0.4.tar.gz
}}}
which is the latest version of the monitoring utilities for a !FlowVisor.  We have tested the !FlowVisor utilities on Ubuntu 10.04 only.  If you are running a different OS and it is not obvious how to translate the instructions, please contact GPO infra.

== Variables ==

 * `<cronuser>`: The user as which to run the FV monitoring.  The scripts can run as root, or as a non-root user of your choice.  (At GPO, we use the `ganglia` user.)
 * `<site>`: a one-word phrase describing your site, probably the name of your university or lab (e.g. `stanford`, `gpolab`).  Use the same value for all hosts your site is monitoring.
 * `<fqdn>`: The fully-qualified domain name as which your FV should report data.  ''IF this is not the same as the output of `uname -n` on your node, pay attention to step 5 below.''

== Steps ==

 1. Copy the tarball over to your FV host, e.g. into `~/plastic-slices-monitor-flowvisor-0.4.tar.gz`.

 2. Unpack the tarball in `/`:
{{{
cd /
sudo tar xvzf ~/plastic-slices-monitor-flowvisor-0.4.tar.gz
}}}
 This should create the following files:
{{{
/usr/local/bin/build_gmoc_conf
/usr/local/bin/measurement_sender
/usr/local/bin/metric_flowvisor
/usr/local/bin/report_data_to_gmoc
/usr/local/lib/flowvisor_metrics.py
/usr/local/lib/rrd_metric.py
}}}

 3. Install required packages:
{{{
sudo apt-get install python-rrdtool librrds-perl libfile-find-rule-perl libwww-perl libxml-writer-perl
}}}
 The monitoring scripts use these packages to:
   * Manage RRD files
   * Write the XML-based API format for the GMOC database
   * Send the formatted data to GMOC via HTTP
 
 4. Create required directories:
{{{
sudo mkdir -p /var/cache/fvmetrics/monitoring
sudo chown <cronuser> /var/cache/fvmetrics/monitoring

sudo mkdir -p /var/spool/rrds/$(uname -n) 
sudo mkdir -p /var/spool/rrds/REPORT
sudo chown -R <cronuser> /var/spool/rrds
}}}

 5. IF `uname -n` does not report your node's FQDN for whatever reason, create a symlink so that reporting and reading scripts can find your RRD files:
{{{
cd /var/spool/rrds
sudo ln -s $(uname -n) <fqdn>
}}}

 6. The `metric_flowvisor` script requires a flowvisor password file, which it expects to find in:
{{{
FVPASSWD_FILE = '/etc/flowvisor/fvpasswd'
}}}
 This file should contain the password for the flowvisor root slice.  (This is the password you use with command-line tools such as `fvctl` or `fvconfig` to configure a flowvisor, or which you entered in the "Setup !FlowVisor" dialog in the Expedient OIM when you setup your flowvisor.)

 7. Check the time on your flowvisor host, and make sure it is accurate. The timeseries data reporting format relies on clock accuracy, so your nodes must be running ntpd (or ntpdate regularly out of cron) in order for monitoring to work.

 8. Run the metric gathering script by hand to make sure it works:
{{{
sudo -u <cronuser> /usr/local/bin/metric_flowvisor
}}}
   * This should produce no output
   * After this runs, a number of RRD files should be created in `/var/spool/rrds/$(uname -n)`

 9. Run the data reporting script by hand to make sure it works:
{{{
sudo -u <cronuser> /usr/local/bin/report_data_to_gmoc <site> <fqdn>
}}}
   * This should produce no output
   * You should be able to browse to [http://gmoc-dev.grnoc.iu.edu/api-demo/data/], view data by Location, select your site, and find a new entry for `<fqdn>`.
 10. Add the two scripts to cron: modify the `<cronuser>` crontab:
{{{
sudo -u <cronuser> crontab -e
}}}
 and add the new lines:
{{{
*/1 * * * * /usr/local/bin/metric_flowvisor
*/5 * * * * /usr/local/bin/report_data_to_gmoc <site> <fqdn>
}}}