Yet Another Monitor (version 2.0.4) Last updated: Apr 4, 2014 This script records and reports on the web usage (downloads and uploads) for all of the devices on your network. You can further roll these totals up by abitrary groups. Data is aggregated by hour, day and month (within your ISP billing interval). Usage history allows you to view and compare results across billing intervals. Further, you can optionally include upload/download figures from your ISP to view how your results recorded at the router compare with theirs. ----------------------------------------- CONFIGURING YOUR ROUTER ----------------------------------------- These instructions presume that a) you've already upgraded the firmware on your router to an appropriate version of DD-WR... unfortunately, I have only limited experience installing and configuring DD-WRT so if you're having trouble here, I cannot help much. b) you have a permanent storage location for the data files created by the script. It is easiest if you are able to plug a USB drive right into your router (personally, I have a 8GB USB Flash drive added to my Linksys E3000 router) but before you can do this, you may need to install Optware (or equivalent) on top of your DD-WRT firmware. If your router does not have a USB port, do not despair - you can configure your router to mount a drive from somewhere on your network and use that instead (it means that you'll have to deviate somewhat from the default installation steps describe below but it will work!). [Aside]The installation instructions for Optware can be found at https://www.dd-wrt.ca/wiki/index.php/OTRW2_%28Optware_the_right_way_Take_2%29 but the Prequisites on that page emphatically state that Optware only runs on the Broadcom chipset. If your router has the Atheros chipset, follow the process as describe here: http://dd-wrt.ca/phpBB2/viewtopic.php?t=86912&highlight=optware (NB - I've not had to do the Atheros bit yet because I have an Broadcom router) If you're not sure what chipset your router has, take a look at the Supported Devices list (available at http://www.dd-wrt.com/wiki/index.php/Supported_Devices) [/Aside] c) you are familiar with the tools necessary to update files and run commands on your router. Personally, I use `winSCP` for copying/moving files (http://winscp.net) and `Putty`for running commands on the router (http://www.putty.org/). If I have to edit the files, I use Notepad++ (http://notepad-plus-plus.org/)... ***NOTE*** If you are updating from a previous version of YAMon, backup your current config.file (note, I didn't say please... just do it... OK?) Over time I have added/modified the parameters in config.file... make sure that your settings are consistent with those in the `default config.file` included with this archive. Yamon.sh creates a small `config.js` file that contains the key reporting values from your `config.file`. When you launch the reports, the values in `config.js` are compared with what you've previously set (and saved in LocalStorage)... if there are any discrepancies, an alert will be raised. BASIC INSTALLATION STEPS FOR VERSION 2.0.0 ***NOTE*** for the initial v2.0 release (on the assumption that you'll be running v1 & v2 in parallel), I recommend that you put the script into a diff directory... for the purposes of this document, I'm using `/opt/YAMon2` - eventually I may migrate back to the `YAMon` directory but just to be safe I recommend a separate one for the time being. 1. Copy the contents of the Setup folder to your router (in my case, `/opt/YAMon2/Setup`) 2. Review the parameters in `default config.file` to make sure that they're consistent with your setup... in particular, make sure that the value of `_ispBillingDay` is equal to the date on which your ISP resets your monthly totals. If you do not have an ISP, set this value to 1 (or any other number between 1 & 31). Make any necessary changes and then save the file as `config.file` 3. Make sure that `yamon2.sh`, `yamon.startup`, and `yamon.shutdown` all have execute permissions 4. [optional] If you've been running YAMon v1 (and have several months of accumulated data), the `convert.sh script will convert your hourly and monthly data files from the v1 format to the v2 format. The h2m.sh script will (re)generate your v2 monthly usage files from the v2 hourly usage files. NB - both of these scripts will add a considerably load to your router (for the time that they are running) 5. If you do not have the files mentioned above, don't worry, the script will automatically create them for you. 6. You can manually launch the script by running `/opt/YAMon2/Setup/yamon2.startup` Note that I've added a `sleep 10` statement in this script... at least one user found that their log/data files were being created with date `1970...` if this delay was not included. 7. ***NEW*** You terminate the script by running `/opt/YAMon2/Setup/yamon2.sh --stop` 8. To ensure that things properly start and stop when/if your router restarts, you must copy the `yamon.startup` and `yamon.shutdown` to your router's Administration-->Commands tab and save them as Startup and Shutdown scripts 9. The `yamon2.sh` script automatically copies all of the necessary report files to your `tmp/www` directory and also the contents of the `data` directory to `tmp/www/data`. If your yamon.startup script copied the files previously, you should remove those statements from your old `yamon.startup` script. Yamon.sh also automatically creates directories for logs and daily backups (whether or not you've enabled these items) ***NEW*** `yamon2.html` references .js and .css files on my personal domain - alcaughey.com. I have done this so that I can add functionality and fix bugs without requiring you to constantly replace these files ***NEW*** `yamon.sh` backs-up the contents of your www directory to /opt/YAMon2/wwwBU when you stop the script 10. Note that debug logging is enabled by default in `config.file` (see `_enableLogging`... set this value to 0 to disable logging). Another alternative is to leave _enableLogging=1 and change the loglevel value to 2 (so that just serious error conditions are included in the log); set the value to 0 to get very detailed information in the logs (but be aware that these files get big fast!). 11. Similarly, the script will make daily backups of your files if `_doDailyBU` is set to 1; change the value to 0 to disable this option. Note you can edit config.file at any time. It is not necessary to stop and restart the script when you do this; the script will detect and incorporate your changes on the fly. I think that's about it on the router side of things. ----------------------------------------- CONFIGURING YOUR WEB REPORTS ----------------------------------------- There's not much that you have to do here. The script will automatically copy all necessary files to `/tmp/www`. You access the reports at http:///user/yamon2.html - e.g., http://192.168.1.1/user/yamon2.html When you open the web reports for the first time, you will get an intro screen that asks you to confirm that a number of the settings in the reports are consistent with those you've set in `config.file`. Change the values as necessary (or accept the defaults) and click the green checkmark to save the setting. When all of the checkmarks have been cleared, the page will automatically reload and you'll see the reports. (NB - you'll have to repeat this confirmation step if you view the reports from a different device or browser.) The reports will raise an alert if the values in config.js (a summary of the key reporting value in config.file) differ from what you have saved in localStorage. ------------------------------------------ OTHER INFO ------------------------------------------ The YAMon v2 script creates three primary data files which are typically stored in /YAMon/data 1. `users.js` - contains information relating to the device - its IP and mac addresses, its name and the group (or owner) to which it belongs: ud_a({"mac":"11:22:33:44:55:66","ip":"192.168.1.1","owner":"Al","name":"iPhone","colour":"","added":"2014-02-10 22:05:03","updated":"2014-03-02 13:33:30"}) You can manually edit this file (using vi or notepad++, etc.) to customize the entries *** - in particular the device name, owner and colour fields. The optional colour parameter, if set, it will use the specified colour for that device in all applicable graphs in the Web reports. The value must be either one of the 140 `named` HTML colours or a valid hexidecimal colour value (see http://www.w3schools.com/html/html_colornames.asp) New lines will be added to the file as soon as they are detected on the network. If the IP address changes, the updated field will be changed. Apostrophes (but not double quotes) are permitted in the name and group fields *** see `Known Issues` below for issues relating to some Windows text editors Here's a command that might help you to 'kickstart' the customization of your `users.file`... it will print mac & IP address for all of the static leases on your router: nvram get static_leases | sed -e 's/[[:blank:]]/ \n/g' -e 's/\=/ /g' | awk {'print $1","$3",Unknown,"$2'} 2. Monthly Usage file The file name is set to the year, month, reset_date - e.g., `2014-03-05-mac_data.js`. Each device will have a row for each day that it is active on the network - e.g., dt({"mac":"11:22:33:44:55:66","day":"05","down":95116718,"up":12979815,"ul_do":0,"ul_up":0}) The down & up fields represent the total traffic in bytes. The ul_do & us_up will only appear if you have set `_unlimited_usage=1` in your config.file The file is updated automatically just after midnight every day and a new file is created automatically every billing interval (e.g., at midnight on the day before the reset date). You should not have to edit this file. 3. Hourly Usage file The file name is set to the year, month, date - e.g., `2014-03-26-hourly_data.js`. As above each device will have a row for each hourly interval that it is active on the network - e.g., hu({"mac":"11:22:33:44:55:66","hour":"02","down":42610,"up":57730,"ul_do":42610,"ul_up":57730}) The down & up fields represent the total traffic in bytes. The ul_do & us_up will only appear if you have set `_unlimited_usage=1` in your config.file The hourly file is updated as per the values of _updatefreq and _publishInterval in config.file. A new hourly usage file is created automatically at midnight every day. ----------------------------------------- KNOWN ISSUES: ----------------------------------------- If you edit any of the configuration files (config.file, users.js, etc.), you *MUST* leave an blank line at the bottom of the file. The Privoxy extension will almost certainly interfere with data collection by YAMon... it appears that it either adds iptables or UPnP rules that intercept traffic usage data before YAMon sees it. Unfortunately, ATM I do not know of any way to get around this. Also, at least one user has reported that you should not use WordPad to edit the files (especially your `config.file` but I expect that the same problems would occur with the startup and shutdown scripts)... apparently it adds additional end of line characters that really mess things up when you try to run the script. If you edit any of the files on your windows box, please make sure that you're using an editor that does not change the end-of-line characters to windows format `CRLF` characters (WordPad will do this to you and some other editors if they're not configured properly). If you find that you're getting and error message that the file "yamon.startup" was not found, this is likely what has happened... to check, open the file in notepad++ and navigate to View >> Show symbols >> Show end of line. If you see CRLF at the end of each line, that is windows format. In Notepad++, to change EOL back to unix format navigate to Edit >> EOL conversion >> UNIX/OSX format. Your EOL should now show LF. [Thanks to Canadian Geek, bpsmicro and spanman for tracking this down and identifying the root cause.] ------------------------------------------ DONATIONS ------------------------------------------ In YAMon 1.0.15, I added a donate button to the report UI (on the right side between the summary and data sections). To be honest, this wasn't really my idea... someone in the DD_WRT forum asked if I'd accept donations and a number of other people chimed in suggesting it was a good idea. So I added a link to PayPal that will allow you to contribute what you feel is appropriate to the development of these reports. Thank you in advance if you choose to donate. If you do, I'll send the really simple instructions on how to eliminate the button (you can probably find it in the code yourself if you find it really annoying). THANK YOU ***VERY*** MUCH TO EVERYONE WHO HAS CONTRIBUTED! ------------------------------------------ IN CONCLUSION ------------------------------------------ If you have any difficulties, please let me know and I'll do my best to help figure things out. Or, post a comment on the DD-WRT forum... there's lots of smart folks there. Your feedback is appreciated. Thanks! Al Caughey al@caughey.ca