[[PageOutline]] = How to configure Plastic Slices monitoring on a MyPLC server = == Introduction == This page explains how to configure a MyPLC server for the [wiki:PlasticSlices/MonitoringRecommendations Plastic Slices central monitoring configuration]. This page was written for {{{ tango-monitor-myplc-0.6-1 }}} which is the latest version of the monitoring utilities for a MyPLC server running Fedora 8 or Fedora 12. It may not work well with older versions. == Upgrading from an earlier version == Version 0.6 of tango-monitor-myplc introduces a new dependency and a config file. If you are currently running version 0.5 of `tango-monitor-myplc`, you need to do the following steps of this update: * [#II.Installsoftwaredependencies II. Install software dependencies] * [#III.Installthemonitoringsoftware III. Upgrade the monitoring software itself] * [#IV.Createrequireddirectoriesandfiles IV. Create required directories and files: Step 1 (add a config file for monitoring)] * [#V.Testthescript V. Test the new script and make sure it still works] If you are installing `tango-monitor-myplc` for the first time or upgrading from an earlier version, read all sections to see which steps you need to take. == Variables == * ``: The user as which to run the monitoring on MyPLC. The scripts can run as root, or as a non-root user of your choice. (At GPO, we use the `ganglia` user.) * ``: 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. * ``: The fully-qualified domain name as which your MyPLC should report data. == Steps to configure MyPLC monitoring == === I. Prepare to submit authenticated monitoring data to GMOC === You need to do these steps if you are installing monitoring for the first time, or if you are upgrading from version 0.1. 1. IF you have not yet registered your site to submit data to GMOC, generate a password for automated monitoring data submission to use. All site resources use the same credential; you only need to do this step once for your entire site. '''Note: the password you use for your site registration is a new password generated for the purpose of submitting monitoring data. Do not reuse any existing passwords from your site.''' 2. Store your site password in a file which MyPLC monitoring can use: {{{ sudo touch /usr/local/etc/monitoring_passwd sudo chown /usr/local/etc/monitoring_passwd sudo chmod 600 /usr/local/etc/monitoring_passwd sudo vi /usr/local/etc/monitoring_passwd }}} Add exactly one line to this file, containing your site monitoring password. 3. Register site credentials: IF you have not yet registered your site to submit data to GMOC, follow the instructions at [wiki:GENIMetaOps/SiteCredentials]. === II. Install software dependencies === Install `GMOC::ExchangeAPI-0.0.2` by hand (packaged versions of this module are coming soon). 1. Download the tarball onto the node (e.g. into your home directory): {{{ wget http://gmoc-db.grnoc.iu.edu/sources/perl-libs/GMOC-ExchangeAPI-0.0.2.tar.gz }}} 2. Unpack the module into `/usr/local/lib`: {{{ cd /usr/local/lib sudo /bin/tar xvzf ~/GMOC-ExchangeAPI-0.0.2.tar.gz GMOC-ExchangeAPI-0.0.2/lib/GMOC --strip-components=2 }}} 3. Verify that this created and populated `/usr/local/lib/GMOC` with the `ExchangeAPI` module files: {{{ $ ls /usr/local/lib/GMOC/ ExchangeAPI/ ExchangeAPI.pm ExchangeAPI.pod }}} === III. Install the monitoring software === Do all of these steps every time you install or upgrade the monitoring software. 1. Download the `tango-monitor-myplc-0.6-1.noarch.rpm` file from [http://software.geni.net/local-sw/], and copy it onto your MyPLC host, e.g. into `~/tango-monitor-myplc-0.6-1.noarch.rpm`. 2. Use yum localinstall to install the RPM and any necessary dependencies: {{{ sudo yum --nogpgcheck localinstall ~/tango-monitor-myplc-0.6-1.noarch.rpm }}} === IV. Create required directories and files === Step 1 needs to be done the first time you upgrade from `tango-monitor-myplc-0.5` or earlier. All three steps need to be done the first time you install tango-monitor-myplc. 1. Populate the gmoc_monitoring configuration file: * Create the config file (the file does not contain sensitive information, and may safely be left world-readable): {{{ /usr/local/etc/gmoc_monitoring.conf }}} * Edit the file and make sure it contains the variables `SITENAME`, `ORGNAME`, and `POPNAME`. ''(N.B. If you are upgrading from a previous version, all three of these variables should contain the `` value you used in the past)'': {{{ $ cat /usr/local/etc/gmoc_monitoring.conf # GMOC short name which is your username for authenticated monitoring data submission SITENAME= # GMOC short name of organization which manages your aggregate (may be the same as SITENAME) ORGNAME= # GMOC short name of "POP"/lab where your aggregate is located (may be the same as SITENAME) POPNAME= # Fully-qualified domain name of your host (Note: if your MyPLC's # primary site is configured with an FQDN within PLC, that value will # override this one. If you're not sure, it is harmless to set this.) HOSTNAME= }}} 2. Create required directories: {{{ sudo mkdir -p /var/spool/rrds/REPORT sudo chown -R /var/spool/rrds }}} === V. Test the script === Run the monitoring and submission scripts by hand to make sure they work. 1. Check the time on your MyPLC server, 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. 2. Run the metric-gathering script by hand to make sure it works: {{{ sudo -u /usr/bin/metric_myplc }}} * This should produce no output * After this runs, a number of RRD files should be created in `/var/spool/rrds/metrics` 3. Run the data reporting script by hand to make sure it works: {{{ sudo -u /usr/bin/report_data_to_gmoc }}} * 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 an entry for your aggregate. === V. Install the scripts to run from cron === This only needs to be done the first time you install the monitoring software. Add the two scripts to cron: modify the `` crontab: {{{ sudo -u crontab -e }}} and add the new lines: {{{ */1 * * * * /usr/bin/metric_myplc */5 * * * * /usr/bin/report_data_to_gmoc }}}