Installing & Validating YAMon v4.0
You can now help to improve YAMon via GitHub
Link to the setup/install script... latest installer script (v4.0.7). If you're a glutton for punishment and want to do everything `handraulicly`, go to the manual install page. I strongly recommend that you follow the steps on this page instead.
Before getting started, take a moment to update your router firmware to the current/latest version. Old (aka out-of-date) firmware versions may encounter problems (e.g., missing features upon which YAMon depends, etc.). Updating to a recent build often (miraculously) makes those issues go away... see `Updating your firmware`.
Once your firmware has been updated, proceed with the steps below.
Installation Steps:
The instructions below presume that you have a properly formatted USB drive attached to your router (see `How should I format my USB drive?`) and mounted to `/opt`. You can choose another mount point (e.g., /mnt/) but will have to change paths as appropriate.
If you have any questions about this or need help configuring USB, see `Do I need a USB drive connected to my router?` and/or configuring USB for `DD-WRT` or `OpenWrt`
- connect to your router using WinSCP or equivalent and then
- open a PuTTY or equivalent Terminal application window.
The text in italics below are the commands that you should run in the PuTTY window. Many of those steps can also be completed directly in WinSCP. - download the latest installer script (v4.0.7) to your PC and expand the zip file
- alternatively, you can download the installer directly to your router using the commands
wget 'http://usage-monitoring.com/current/YAMon4/Setup/install.sh' -qO /tmp/install.sh - if necessary, create a directory named 'opt` (depending on your firmware, you can use a different name/location but the steps below presume you used `opt`)
mkdir /opt - confirm that you have write permissions in `/opt/`
ls -laL "/opt" | grep ' .$'You should see something like:
drwxr-xr-x 7 root root 1024 Jan 3 12:07
If you are missing a `w` in the third character of the output above - e.g., `dr-xr-xr-x` , you do *not* have write permission in that folder and cannot continue the steps below until you've fix this issue. See your firmware admin GUI to properly mount a USB drive. If your router does not have a USB port, then you've got a completely different problem... see `Do I need a USB drive connected to my router?` (Spoiler alert, the answer is still yes.)
- copy `install.sh` to `/opt/`.
If you saved the installer to you PC, it is easiest to copy the file using WinSCP.
If you downloaded the installer directly to your router, run the command
cp /tmp/install.sh /opt/ - give `install.sh` execute permission
chmod +x /opt/install.sh - run `install.sh`
/opt/install.sh
A stickler might point out that you could also run the installer directly from /tmp... While this is correct, I still recommend copying the installer to a non-volatile memory location so that you can more easily update your files in the future (/tmp/ gets erased when your router reboot). - answer the prompts in the install and setup scripts... for starters, I suggest that you pick the `basic` install options rather than `advanced`. You can always run install.sh (or setup.sh) again to tweak your settings or manually edit the file.
If you want a fresh restart (after running an earlier version of YAMon v4), run
/opt/YAMon4/clear-iptables.sh
(maybe run it twice... the second time, you should see a lot of `nothing to clear` entries) - The final prompt in the setup script will ask you if you want to start YAMon... say `yes`!
Steps to Validate your Installation:
The installer now includes a file named `validate.sh` which will perform all of the steps listed below (and more)... I recommend that you use it instead.
See the below for all of the validation tests in a single block of code. You can copy and paste that text directly into a PuTTY window and it'll save the results to a text file in /tmp/yamon. If you encounter problems, that file is another piece of evidence you can send to me to help debug the issue.
The steps below presume that you are checking the folder contents in PuTTY. You could also open and view the contents of the directories using WinSCP.
To check that things have been created properly in the web root:
ls -la /www
You should see (ignore the YAMon3 entries):
root@turris:~# ls -la /www ... lrwxrwxrwx 1 root root 8 Aug 7 2019 user -> /tmp/www ... lrwxrwxrwx 1 root root 8 Apr 8 2018 yamon -> /tmp/www ... --> DD-WRT users will see the symlink: user -> /tmp/www entry --> Turris/OpenWrt should see the symlink: yamon -> /tmp/www entry
There's currently a bug (v4.0.6 and lower) for Turris/OpenWrt users: the `yamon` symlink above is not being created and the reports open with a page not found error.
You can manually create the symlink by opening a PuTTY window and running:
ln -s /tmp/www /www/yamon
To check that things have been created properly in the web root:
ls -la /tmp/www
You should see (ignore the YAMon3 entries):
lrwxrwxrwx 1 root root 19 Jan 1 17:50 css -> /opt/YAMon4/www/css lrwxrwxrwx 1 root root 16 Dec 4 13:54 data3 -> /opt/YAMon3/data lrwxrwxrwx 1 root root 16 Jan 1 17:50 data4 -> /opt/YAMon4/data lrwxrwxrwx 1 root root 22 Jan 1 17:50 images -> /opt/YAMon4/www/images lrwxrwxrwx 1 root root 29 Jan 1 17:50 index.html -> /opt/YAMon4/www/yamon4.0.html drwxr-xr-x 2 root root 160 Jan 2 13:54 js lrwxrwxrwx 1 root root 16 Jan 1 17:50 logs -> /opt/YAMon4/logs lrwxrwxrwx 1 root root 29 Dec 27 13:15 old.html -> /opt/YAMon3/www/yamon3.4.html (NB - I manually create the old.html symlink so that I can compare my v4 results with YAMon3)
Check that the files were created correctly in the JavaScript directory:
ls -la /tmp/www/js/
You should see these entries:
-rwxr-xr-x 1 root root 316 Jan 1 17:50 config4.0.js -rwxr-xr-x 1 root root 13703 Jan 3 21:55 live_data4.js (NB - If you are also running YAMon3, there will be several more files in this directory)
Check that the files were created correctly in the YAMon working directory:
ls -la /tmp/yamon/
You should see
-rw-r--r-- 1 root root 632 Jan 2 13:56 ac-rules.txt -rw-r--r-- 1 root root 30812 Jan 3 21:56 hourly_2020-01-03.js -rwxr-xr-x 1 root root 17445 Jan 3 21:56 lastseen.js -rw-r--r-- 1 root root 7846 Jan 2 13:56 mac-ip.txt -rw-r--r-- 1 root root 22694 Jan 3 21:56 raw-traffic-2020-01-03-21.txt -rw-r--r-- 1 root root 2 Jan 2 13:56 updates.txt -rw-r--r-- 1 root root 206237 Jan 3 21:56 yamon.log
And finally, check that the symlinks were created correctly in the logs directory:
ls -la /opt/YAMon4/logs/
You should see (your day-log.html file should point to the current date)
lrwxrwxrwx 1 root root 32 Jan 4 00:00 day-log.html -> /opt/YAMon4/logs/2020-01-04.html lrwxrwxrwx 1 root root 20 Jan 1 17:50 latest-log.html -> /tmp/yamon/yamon.log
To check that the cron jobs have been created properly:
- In DD-WRT, enter
cat /tmp/cron.d/yamon_jobs - In OpenWrt/Lede & Turris, enter
crontab -l - You should see
#YAMon jobs: (updated 2020-01-01) 0 0 5 * * /opt/YAMon4/new-billing-interval.sh 59 * * * * /opt/YAMon4/end-of-hour.sh 59 23 * * * /opt/YAMon4/end-of-day.sh 0 0 * * * /opt/YAMon4/new-day.sh 0 2 * * * /opt/YAMon4/in-unlimited.sh start 0 8 * * * /opt/YAMon4/in-unlimited.sh end 0 * * * * /opt/YAMon4/new-hour.sh * * * * * /opt/YAMon4/update-live-data.sh 4-56/4 * * * * /opt/YAMon4/update-reports.sh #Access Restriction Rules (updated 2020-01-02 13:56:03) 30 20 * 1,2,3,4,5,6,9,10,11,12 1,2,3,4,7 /opt/YAMon4/block.sh 'Unknown,Visitors,xyz' DROP '' 'School nights' 00 07 * 1,2,3,4,5,6,9,10,11,12 2,3,4,5,1 /opt/YAMon4/block.sh 'Unknown,Visitors,xyz' RETURN '' 'School nights' 30 21 * 1,2,3,4,5,6,9,10,11,12 5,6 /opt/YAMon4/block.sh 'Unknown,Visitors,xyz' DROP '' 'Weekends Nights' 30 07 * 1,2,3,4,5,6,9,10,11,12 6,0 /opt/YAMon4/block.sh 'Unknown,Visitors,xyz' RETURN '' 'Weekends Nights' 30 08 * * * /opt/YAMon4/block.sh 'Unknown,xyz' DROP '' 'Block Test' 00 09 * * * /opt/YAMon4/block.sh 'Unknown,xyz' RETURN '' 'Block Test'NB - In DD-WRT, `root` will appear in all of the cron job entries (but is not required for OpenWrt/Turris)
The `in-unlimited` entries will only appear if _unlimited_usage='1' in your config.file.
The Access Restriction Rules entries will appear only if you've already defined some.
Copy and paste the text below into a PuTTY Window to run all of the validations at once:
The installer now includes a file named `validate.sh` which will perform all of the steps listed below (and more)... I recommend that you use it instead.
Last but not least, to check that the YAMon v4 entries were added to your router's startup commands...
> in DD-WRT, open the admin GUI and go to the Administration-->Commands tab (http://192.168.1.1/Diagnostics.asp)
> in OpenWrt/Turris Omnia, open the LuCI interface and choose Startup under the System menu (https://192.168.1.1/cgi-bin/luci/admin/system/startup)
In both, you should see the following entry:
/opt/YAMon4/start.sh 'reboot' .
If any of the files above are missing, please re-run install.sh and check these validation steps again before contacting Al (TIA)
Steps to Validate your Reports:
Open the reports in browser
> in DD-WRT, open http://192.168.1.1/user/index.html
> in OpenWrt/Turris Omnia, open http://192.168.1.1/yamon/
Do they load properly?
If no, please look in the Browser Console window for errors in `yamon4.0.js` or `util4.0.js`. If you find any, send me a screenshot of the console window. To activate the browser console window, type
If the reports open properly, click the `Log` icon at the right end of the tab icons. The logs are now HTML files so they can be viewed directly in the browswer! More importantly, after only 6 years of working on YAMon, I finally figured out how to get the bash error messages incorporated right into the logs... so you/I can see where and when the errors occured in bold red text.
If you do see any errors in your logs, please review them and then send the logs, screenshots and/or any relevant info to me at install@usage-monitoring.com.
One Last Check:
Reboot your router and then check that all of the files and folders get recreated properly in the validation step above.
Limitations
AFAIK, most aspects of the reports are working properly but there are still a few small things that I have to get fixed
Please send questions/comments to questions@usage-monitoring.com... If you do encounter issues, make my life simpler by including the log files, screenshots, etc., etc.
Thanks in advance for your assistance
Al