| 1 | | [[PageOutline]] |
| 2 | | |
| 3 | | = How to configure Plastic Slices monitoring on an OpenFlow FOAM AM = |
| 4 | | |
| 5 | | == Introduction == |
| 6 | | |
| 7 | | This page explains how to configure an !OpenFlow FOAM server for [wiki:PlasticSlices/MonitoringRecommendations central GENI operational monitoring]. This page was written for |
| 8 | | {{{ |
| 9 | | tango-monitor-foam_0.4-2 |
| 10 | | }}} |
| 11 | | and may not work well with earlier versions. We have tested the FOAM utilities on Ubuntu 10.04 only, but expect they will also work on CentOS. If you are running a different OS and it is not obvious how to translate the instructions, please contact GPO infra. |
| 12 | | |
| 13 | | == Upgrading from previous versions == |
| 14 | | |
| 15 | | Version 0.4 of tango-monitor-foam introduces a script for reporting metadata about your site to the GMOC database. In addition, version 0.3 introduced a config file. If you are currently running a previous version of `tango-monitor-foam`, you need to do the following steps of this update: |
| 16 | | * [#II.Installthemonitoringsoftware II. Upgrade the monitoring software itself] |
| 17 | | * [#III.Createrequireddirectoriesandfiles III. Create required directories and files: Step 1 (add a config file for monitoring)] |
| 18 | | * [#IV.Reportsitemetadata IV. Report site metadata] |
| 19 | | * [#V.Testthescript V. Test the new script and make sure it still works] |
| 20 | | |
| 21 | | If you are installing `tango-monitor-foam` for the first time or upgrading from a version earlier than 0.2, read all sections to see which steps you need to take. |
| 22 | | |
| 23 | | == Variables == |
| 24 | | |
| 25 | | * `<cronuser>`: The user as which to run the FOAM monitoring. The scripts can run as root, or as a non-root user of your choice. (At GPO, we use the `ganglia` user.) |
| 26 | | * You need several pieces of identifying information for your site: |
| 27 | | * `<submission_user>`: a one-word phrase describing your site, which is your username for data submission to GMOC (see step I) (e.g. `ExoGENI-BBN`) |
| 28 | | * `<organization>`: a one-word name for the organization which runs your FOAM (e.g. `ExoGENI`) |
| 29 | | * `<pop>`: a one-word name for the physical location where your FOAM sits (e.g. `gpolab`) |
| 30 | | When you setup your config file in step III, you will also need a few pieces of metadata about your organization and POP. |
| 31 | | |
| 32 | | == Steps to configure FOAM monitoring == |
| 33 | | |
| 34 | | === I. Prepare to submit authenticated monitoring data to GMOC === |
| 35 | | |
| 36 | | You need to do these steps if you are installing monitoring for the first time. |
| 37 | | |
| 38 | | 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 resources managed by a given set of people 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.''' |
| 39 | | |
| 40 | | 2. Store your site password in a file which FOAM monitoring can use: |
| 41 | | {{{ |
| 42 | | sudo touch /usr/local/etc/monitoring_passwd |
| 43 | | sudo chown <cronuser> /usr/local/etc/monitoring_passwd |
| 44 | | sudo chmod 600 /usr/local/etc/monitoring_passwd |
| 45 | | sudo vi /usr/local/etc/monitoring_passwd |
| 46 | | }}} |
| 47 | | Add exactly one line to this file, containing the monitoring password you want to use for the user `<submission_user>`. |
| 48 | | |
| 49 | | 3. Register site credentials: IF you have not yet registered your site to submit data to GMOC, follow the instructions at [wiki:GENIMetaOps/SiteCredentials]. |
| 50 | | |
| 51 | | === II. Install the monitoring software === |
| 52 | | |
| 53 | | Do these steps every time you install or upgrade the monitoring software. |
| 54 | | |
| 55 | | ==== If you are installing on Ubuntu ==== |
| 56 | | |
| 57 | | 1. Download the `tango-monitor-foam_0.4-2_all.deb` package file from [http://software.geni.net/local-sw/], and copy it onto your FOAM host, e.g. into `~/tango-monitor-foam_0.4-2_all.deb`. |
| 58 | | |
| 59 | | 2. Use dpkg to install the local package. This may fail due to dependencies and say it is leaving the package "unconfigured". Therefore, invoke apt-get to fix any missing dependencies: |
| 60 | | {{{ |
| 61 | | sudo dpkg -i ~/tango-monitor-foam_0.4-2_all.deb |
| 62 | | sudo apt-get -f install |
| 63 | | }}} |
| 64 | | |
| 65 | | ==== If you are installing on CentOS ==== |
| 66 | | |
| 67 | | 1. Download the `tango-monitor-foam-0.4-2.noarch.rpm` package file from [http://software.geni.net/local-sw/], and copy it onto your FOAM host, e.g. into `~/tango-monitor-foam-0.4-2.noarch.rpm`. |
| 68 | | |
| 69 | | 2. Use yum localinstall to install the local package. This will install the provided file, using your standard yum repositories to find any dependencies: |
| 70 | | {{{ |
| 71 | | sudo yum --nogpgcheck localinstall ~/tango-monitor-foam-0.4-2.noarch.rpm |
| 72 | | }}} |
| 73 | | |
| 74 | | === III. Create required directories and files === |
| 75 | | |
| 76 | | * `<submission_user>`: a one-word phrase describing your site, which is your username for data submission to GMOC (see step I) (e.g. `ExoGENI-BBN`) |
| 77 | | * `<organization>`: a one-word name for the organization which runs your FOAM (e.g. `ExoGENI`) |
| 78 | | * `<pop>`: a one-word name for the physical location where your FOAM sits (e.g. `gpolab`) |
| 79 | | |
| 80 | | Step 1 needs to be done the first time you upgrade from `tango-monitor-foam-0.2` or earlier. All three steps need to be done the first time you install tango-monitor-foam. |
| 81 | | |
| 82 | | 1. Populate the gmoc_monitoring configuration file: |
| 83 | | * Create the config file (the file does not contain sensitive information, and may safely be left world-readable): |
| 84 | | {{{ |
| 85 | | /usr/local/etc/gmoc_monitoring.conf |
| 86 | | }}} |
| 87 | | * Edit the file and make sure to populate all variables (N.B. use single quotes to surround any value containing whitespace): |
| 88 | | {{{ |
| 89 | | $ cat /usr/local/etc/gmoc_monitoring.conf |
| 90 | | |
| 91 | | # GMOC short name which is your username for authenticated monitoring data submission |
| 92 | | SITENAME=<submission_user> |
| 93 | | |
| 94 | | # GMOC short name of organization which manages your aggregate (may be the same as SITENAME if appropriate) |
| 95 | | ORGNAME=<organization> |
| 96 | | |
| 97 | | # GMOC short name of "POP"/lab where your aggregate is located (may be the same as SITENAME if appropriate) |
| 98 | | POPNAME=<pop> |
| 99 | | |
| 100 | | # Primary contact for the organization |
| 101 | | ORG_PRIMARY_CONTACT_EMAIL=<primary e-mail address for your site, may be an individual address or a group address> |
| 102 | | ORG_PRIMARY_CONTACT_FIRSTNAME=<a first name associated with that e-mail address> |
| 103 | | ORG_PRIMARY_CONTACT_LASTNAME=<a last name associated with that e-mail address> |
| 104 | | |
| 105 | | # The street address of your POP |
| 106 | | POPORG_ADDR_STREET='<street address of your POP>' |
| 107 | | POPORG_ADDR_CITY=<city where your POP is located> |
| 108 | | POPORG_ADDR_STATE=<state abbreviation of your POP> |
| 109 | | POPORG_ADDR_POSTCODE=<postal code of your POP> |
| 110 | | |
| 111 | | # Some arbitrary name for the street address of your POP |
| 112 | | POPORG_LOCATION_NAME=<short name of address, should not contain whitespace, e.g. 10_Moulton_St> |
| 113 | | |
| 114 | | # Relational data submission URL |
| 115 | | GMOC_REL_URL=https://gmoc-db.grnoc.iu.edu/xchange/webservice.pl |
| 116 | | |
| 117 | | # Measurement data submission URL |
| 118 | | GMOC_MEAS_URL=https://gmoc-db.grnoc.iu.edu/measurement_drop/recv_api.pl |
| 119 | | }}} |
| 120 | | |
| 121 | | 2. Create required directories: |
| 122 | | {{{ |
| 123 | | sudo mkdir -p /var/cache/fvmetrics/monitoring |
| 124 | | sudo chown <cronuser> /var/cache/fvmetrics/monitoring |
| 125 | | |
| 126 | | sudo mkdir -p /var/spool/rrds/REPORT |
| 127 | | sudo chown -R <cronuser> /var/spool/rrds |
| 128 | | }}} |
| 129 | | |
| 130 | | 3. The `metric_foam` script requires a FOAM password file, which it expects to find in: |
| 131 | | {{{ |
| 132 | | /opt/foam/etc/foampasswd |
| 133 | | }}} |
| 134 | | This file should contain the admin password for FOAM. (This is the password you use with `foamctl` to run FOAM commands.) |
| 135 | | |
| 136 | | === IV. Report site metadata === |
| 137 | | |
| 138 | | Use a reporting script to add your site metadata to GMOC's database: |
| 139 | | {{{ |
| 140 | | sudo -u <cronuser> /usr/bin/report_site_metadata |
| 141 | | }}} |
| 142 | | This should exit successfully with no output. If any output is reported, contact GMOC or GPO for debugging. |
| 143 | | |
| 144 | | ''Note: if you change any of the variables in your configuration file later, you will need to run `report_site_metadata` again, to get the changes into GMOC's database.'' |
| 145 | | |
| 146 | | === V. Test the script === |
| 147 | | |
| 148 | | Run the monitoring and submission scripts by hand to make sure they work. |
| 149 | | |
| 150 | | 1. Check the time on your FOAM host, and make sure it is accurate. The 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. |
| 151 | | |
| 152 | | 2. Run the metric gathering script by hand to make sure it works: |
| 153 | | {{{ |
| 154 | | sudo -u <cronuser> /usr/bin/metric_foam |
| 155 | | }}} |
| 156 | | * This should produce no output |
| 157 | | * After this runs, a number of RRD files should be created in `/var/spool/rrds/metrics` |
| 158 | | |
| 159 | | 3. Run the data reporting script by hand to make sure it works: |
| 160 | | {{{ |
| 161 | | sudo -u <cronuser> /usr/bin/report_data_to_gmoc |
| 162 | | }}} |
| 163 | | * This should produce no output |
| 164 | | * You should be able to browse to [http://gmoc-db.grnoc.iu.edu/api-demo/], view data by Location, select your site, and find an entry for your node. |
| 165 | | |
| 166 | | === VI. Install the scripts to run from cron === |
| 167 | | |
| 168 | | This only needs to be done the first time you install the monitoring software. |
| 169 | | |
| 170 | | Add the two scripts to cron: modify the `<cronuser>` crontab: |
| 171 | | {{{ |
| 172 | | sudo -u <cronuser> crontab -e |
| 173 | | }}} |
| 174 | | and add the new lines: |
| 175 | | {{{ |
| 176 | | */1 * * * * /usr/bin/metric_foam |
| 177 | | */5 * * * * /usr/bin/report_data_to_gmoc |
| 178 | | }}} |
| 179 | | ''N.B. If you have cron jobs already installed which contain parameters after these commands, you can update them or leave them as is. The CLI parameters are now ignored.'' |
| | 1 | This document has moved. Please see [wiki:TangoGeniMonitoring/FoamConfiguration] for up-to-date instructions on configuring FOAM monitoring. |
