├── LICENSE ├── README.md └── iperfsensor.sh /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2015 rkagerer 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | 23 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | iperfsensor for PRTG 2 | ==================== 3 | 4 | [![License](http://img.shields.io/badge/license-MIT-lightgrey.svg?style=flat 5 | )](http://mit-license.org) 6 | [![GitHub release](https://img.shields.io/github/release/rkagerer/iperfsensor.svg)](https://github.com/rkagerer/iperfsensor/blob/master/iperfsensor.sh) 7 | 8 | This script runs [iPerf][1] to measure bandwidth between two nodes of a network, and reports the results in a format 9 | compatible with PRTG's [SSH Script Advanced][2] sensor. 10 | 11 | It has minimal dependancies and even works on a router flashed with the open-source [Tomato][3] firmware. 12 | 13 | ![Gauges](http://i.imgur.com/h8ybAzj.png) 14 | 15 | ### Prerequisites 16 | 17 | 1. Ensure iPerf is installed on at least two hosts in your network. If you only have one, you might try testing against 18 | a [public server][4]. For Tomato, [install Entware][5] first then run `opkg install iperf`. 19 | 20 | 2. Ensure the neccessary firewall ports are open (default is 5001). 21 | 22 | 3. Test iPerf manually to check connectivity. 23 | 24 | 4. Ensure the machine which is your iPerf client: 25 | 26 | - has SSH is running, and that PRTG probe can connect to it 27 | - is set up in PRTG as a device 28 | 29 | Note your PRTG probe does not need connectivity to the computer that will act as the iPerf server. Also if you have 30 | several SSH-based PRTG sensors sampling a Tomato router at high frequency, you may need to relax the SSH connection 31 | rate throttling (under *Administration* | *Admin Access* | *Admin Restrictions* | *Limit Connection Attempts*). 32 | 33 | ### Installation 34 | 35 | 1. Place iperfsensor.sh on the computer that will act as the client, e.g.: 36 | 37 | ```sh 38 | mkdir -p /var/prtg/scriptsxml 39 | cd /var/prtg/scriptsxml 40 | wget -O iperfsensor.sh http://cdn.rawgit.com/rkagerer/iperfsensor/1.0.4/iperfsensor.sh 41 | chmod +x iperfsensor.sh 42 | ``` 43 | 44 | 2. Add an *SSH Script Advanced* sensor in PRTG, and pick _iperfsensor.sh_. 45 | 46 | 3. Under _Parameters_, enter the parameters to be passed to iPerf, just as if you were running it from the command line. 47 | e.g.: 48 | 49 | ``` 50 | -c iperf.scottlinux.com -p 5201 51 | ``` 52 | 53 | 4. _Shell Timeout_ should be longer than *twice* your iPerf test duration. This is because both an up and down test 54 | is performed. By default, each test lasts 10 seconds, but you can change this using the `-t` parameter. 55 | 56 | ### Bandwidth Disclaimer 57 | 58 | Automated iPerf testing can eat up a lot of bandwidth. The best way to use this tool is between two internal nodes of 59 | your network (e.g. to monitor a point to point Wifi link). If you use it across a WAN link, be sure you have sufficient 60 | bandwidth and budget for the traffic that will be generated! 61 | 62 | Also keep in mind that other, parallel traffic loads on your network will affect the results. 63 | 64 | ### Changelog 65 | 66 | - v1.0.4 (2015-Sep-21): 67 | - Fix one of the URL's in comments 68 | - Escape special XML characters in error text reported to PRTG 69 | - v1.0.3 (2015-Sep-20): Clean up 70 | - v1.0.2 (2015-Sep-20): Improvement to report errors back to PRTG 71 | - v1.0.1 (2015-Sep-20): Initial release 72 | 73 | ### Bling 74 | 75 | ![Gauges](http://i.imgur.com/6txm9dZ.png) 76 | 77 | ![Grids](http://i.imgur.com/Bm2fX2Z.png) 78 | 79 | [1]: https://github.com/esnet/iperf 80 | [2]: https://www.paessler.com/manuals/prtg/ssh_script_advanced_sensor 81 | [3]: http://tomato.groov.pl/ 82 | [4]: https://www.google.com/search?q=public+iperf+servers 83 | [5]: https://gist.github.com/dferg/833aade513965d78b43d 84 | -------------------------------------------------------------------------------- /iperfsensor.sh: -------------------------------------------------------------------------------- 1 | # iperfsensor v1.0.4 (2015-Sep-21) 2 | # iPerf sensor for PRTG 3 | # Author: rkagerer 4 | # For the latest version, see https://github.com/rkagerer/iperfsensor/ 5 | # 6 | # This script is intended to run with minimal dependancies, where only a limited subset 7 | # of Linux commands are supported. 8 | 9 | # Run iPerf using parameters passed in, but override a few we require: 10 | # "-f m" to format Transfer volume in MBytes and Bandwidth in MBits/sec 11 | # "-P 1" since parsing logic hasn't yet been implemented for parallel tests 12 | # "-r" since we're expecting to parse results of a test in both directions 13 | # "2>&1" redirect stderr to stdout to prevent errors from contaminating the xml output 14 | # Warning: There is no input sanitization, so be mindful of what you pass in. 15 | output=$(iperf $* -f m -P 1 -r 2>&1) 16 | error=$? 17 | 18 | # Parse iPerf output. First find lines with the word MBytes, then (treating space as 19 | # delimiters) return the fourth-from-last and second-from-last fields (which are 20 | # Transfer and Bandwidth, respectively). This yields two pairs of values. 21 | results=$(echo -e "$output" | grep "MBytes" | awk '{ print $(NF-3), $(NF-1) }') 22 | # Take those values and convert to bytes, which are needed when using PRTG "SpeedNet" units. 23 | # bc isn't installed by default on Tomato, so use awk for floating point arithmetic. 24 | # printf is used to avoid scientific notation that may otherwise arise. 25 | down=$(echo $results | awk '{printf "%.0f", $2 * 125000}') 26 | up=$( echo $results | awk '{printf "%.0f", $4 * 125000}') 27 | #amt=$( echo $results | awk '{printf "%.2f", ($1+$3) * 1048576}') 28 | amt=$( echo $results | awk '{printf "%.2f", ($1+$3)}') # leave in MB for convenience 29 | 30 | # See https://prtg.paessler.com/api.htm?username=demo&password=demodemo&tabid=7 for more info. 31 | # Be sure to return a valid response even when no parameters are passed in or errors occur. 32 | # PRTG gets finicky and reports unintuitive errors if it doesn't like what it sees in here, 33 | # even for minor things like unacceptable combinations of tags. If you do something wrong 34 | # wrong here, the "Preparing Sensor Settigns" dialog may hang, and you'll get timeout errors 35 | # on the sensor, until you fix the problem or remove the sensor. 36 | echo "" 37 | echo " " 38 | echo " Download" 39 | echo " $down" 40 | echo " 1" 41 | echo " SpeedNet" 42 | echo " MegaBit" 43 | echo " 2" 44 | echo " 1" 45 | echo " 50" 46 | echo " Downloads from office to Bales are below 50 Mbit/s (6.25 MB/sec)" 47 | echo " " 48 | echo " " 49 | echo " Upload" 50 | echo " $up" 51 | echo " 1" 52 | echo " SpeedNet" 53 | echo " MegaBit" 54 | echo " 2" 55 | echo " 1" 56 | echo " 50" 57 | echo " Uploads from Bales to Office are below 50 Mbit/s (6.25 MB/sec)" 58 | echo " " 59 | echo " " 60 | echo " Transferred" 61 | echo " $amt" 62 | echo " 1" 63 | #echo " BytesBandwidth" 64 | echo " Custom" 65 | echo " MB" 66 | #echo " MegaByte" 67 | echo " 1" 68 | echo " 1" 69 | echo " " 70 | echo " " 71 | # if iPerf failed, send its raw output to PRTG to help with debugging 72 | if [ $error -ne 0 ]; then 73 | # Escape any special XML characters 74 | # Adapted from http://daemonforums.org/showthread.php?t=4054 and http://stackoverflow.com/a/1252191/589059 75 | # For a quick test, try running "./iperfsensor.sh --help" 76 | # Note the final sed pipe for linebreaks doesn't seem to work; PRTG ignores the CR / LF characters 77 | echo -e "$output" | sed -e 's~&~\&~g' -e 's~<~\<~g' -e 's~>~\>~g' # | sed -e ':a;N;$!ba;s~\n~\ \ \n~g' 78 | fi 79 | echo " " 80 | echo " $error" 81 | echo "" 82 | --------------------------------------------------------------------------------