WRTbwlog (v1.1)

Index

News
Description
System Requirements
Installation and Update
FAQ
Usage
Screenshots
License/Credits
Download
Addons/Themes
Changelog
Ideas for next versions (may or may not be implemented)

Description

WRTbwlog is a tool, that allows you to:

Monitor and display the total internet traffic of all wired and wireless clients connected to a Linksys WRT54G(S) router.
Monitor, which computers are using your wireless network.
Start custom scripts, if the traffic exceeds certain limits or if unauthorized clients are detected on the nework.
Easily upload, create, modify and delete files and NVRAM parameters on your WRT54G(S).
View loads of information about your WRT54G(S).
Scan the WLAN frequency range for other WLAN devices or interference.

The advantage of this tool, compared to the SNMP/Rflow monitoring functionality included in some third party firmwares like Alchemy, DD-WRT or Talisman is, that you don't need to have a separate computer running 24/7 just for logging the traffic data from your router. With WRTbwlog everything is calculated and saved on your router.

The disadvantage is, that you'll loose the saved logs when rebooting the router. But an optional backup functionality for the logs is also available.

If you like WRTbwlog and would like to make a donation, you can do so by using the Paypal button below. Thank you very much!

If you want to discuss with other WRTbwlog users about this tool, if you have any problems with WRTbwlog or if you just want to share your thoughts about WRTbwlog with the rest of the world, you can do this in the WRTbwlog thread at the wrt54g.com forums or in the most recent WRTbwlog release-thread at the linksysinfo.org forums.

System Requirements

Most functionality of WRTbwlog should work on all hardware revisions of the WRT54G(S) routers. I have tested it with the Sveasoft Alchemy 1.0 firmware and got reports, that it's also working with the Sveasoft Talisman firmware and DD-WRT firmware. I guess, it's also running on OpenWRT? (feedback appreciated)

It will not work with the default Linksys firmware, Sveasoft Satori or Hyperwrt, as these firmware versions do not include awk, which is required by WRTbwlog.

I'd highly recommended using Firefox or Mozilla for viewing the webinterface of WRTbwlog. Though I've not tested this, I guess that it will also work on other browsers like IE or Opera. With IE you might see some minor layout problems due to IE's inclomplete CSS2 support. A screen resolution of 1024x768 or higher is recommended.

Due to the slow CPU of the WRT54G(S) routers and due to the nature of Linux shell script, which most parts of this tool are written in, WRTbwlog can sometimes be a little bit slow. So sometimes it may take a few second to load some pages - especially the configuration-page and the traffic-page.

Installation and Update

Updating (If you are currently running v0.7 or above.)

Beginning with v0.7 WRTbwlog has a single-click update feature. You can find it at

http://192.168.1.1:8000/update.cgi

First time installation (or for manually reinstalling WRTbwlog after a reboot)

To install and run WRTbwlog on your WRT54G(S), login to the router with telnet or ssh and type the following commands:

cd /tmp
wget http://wrt54g.hetos.de/wrtbwlog.tgz
tar -xzf wrtbwlog.tgz
rm wrtbwlog.tgz
cd bwlog
./start.sh

The last command (start.sh) will take a few seconds to complete.

If you don't know how to use Telnet or SSH, please have a look at the great WRTbwlog setup guide from wrt54g.com. They even have screenshots from every step of the setup process.

Updating (only if your are currently running v0.6 or below!)

When updating from v0.6 or below to v0.7 or higher, login to the router with telnet or ssh and type the following commands:

killall assoc.sh
killall backup.sh
killall billvol.sh
killall bwlog.sh
killall bwsum.sh
killall mini_httpd
rm /tmp/bwlog/*

cd /tmp
wget http://wrt54g.hetos.de/wrtbwlog.tgz
tar -xzf wrtbwlog.tgz
rm wrtbwlog.tgz
cd bwlog
./start.sh

The last command (start.sh) will take a few seconds to complete.

Usage

Traffic Statistics

To connect to the WRTbwlog traffic statistics page, use the url

http://192.168.1.1:8000/traffic.cgi

(Replace 192.168.1.1 in the url with the actual IP of your router.)

Here you can see the total internet traffic of your router for the current month, billing period or year. With the 'Previous' and 'Next' buttons you can display the traffic of previous months or billing periods. By pressing the 'Details' button, you can see the traffic for each day of the month, billing period or year.

You can also create custom URLs to directly open the different views of the traffic screen. Example:

http://192.168.1.1:8000/traffic.cgi?details=n&mode=b&y=05&m=06&d=24

The first parameter (details) can have the values 'y' for detailed view, or 'n' for no details. The second parameter (mode) can have the values 'y' for year, 'm' for month and 'b' for billing period. If you want to view the data of a special year, month or billing period, you can assign values to the remaining three parameters y (year), m (month) and d (day). Otherwise just omit these parameters.

In the billing period mode, you'll also see a graph, some statistics and a traffic prediction for this billing period. This additional information is especially useful, if you have traffic-cap on your internet connection. You can enter the traffic limits on the configuration page. The values for the traffic prediction are only correct, if there are logs for all days, from the beginning of the current billing period, until now. So if you are starting to use WRTbwlo in the middle of a billing period, you'll have to wait for the next billing period, to get a correct traffic prediction.Of course the normal traffic display is not affected by this.

The traffic logs are usually growing by 20-25 Bytes per day, which is less than 10 kB per year.

And finally pressing the 'Current speed' button will give you a popup window, displaying the current download/upload speed. This speed display is not very accurate and it's only updated every 5 seconds form performance reasons. But it's better than nothing. :-)

Router Status

To connect to the WRTbwlog router status page, use the url

http://192.168.1.1:8000/status.cgi

(Replace 192.168.1.1 in the url with the actual IP of your router.)

This page displays some information about the internals and the status of your router. Among other things this includes imformation about memory usage, CPU usage, running processes, network interfaces, routing table, arp table and wireless connections.

There is also a textbox on this page, which can be used to enter Linux shell commands, which are executed if you press the "Run/Refresh" button. The output of the executed command is displayed at the bottom of the page. This is not meant as a replacement for shell access. For more extended tasks, by all means use SSH or Telnet. But it can come in quite handy, if you quickly want to run a command based in the information seen on the status page (like killing a process).

Wireless Access Log

To connect to the WRTbwlog wireless access log page, use the url

http://192.168.1.1:8000/wlanlog.cgi

(Replace 192.168.1.1 in the url with the actual IP of your router.)

On this page you can see the output of a sentry-script, which will write every 30 seconds the time and date, and the MAC address, IP, hostname and RSSI value of all connected wireless clients to a log, if the number of connected clients changes. As most people won't need this feature, this script is not being started by default. You can enable this script at the configuration page.

If you are planning to run this script over a longer period of time, please keep an eye on the free memory of your WRT54G(S). Depending on the number of wireless clients in your WLAN and the number of connects per day, the size of this log can grow quite fast! On an average network with 2 clients about 1 KB per day.

Wireless Scan

To connect to the WRTbwlog wlan scan page, use the url

http://192.168.1.1:8000/wlanscan.cgi

(Replace 192.168.1.1 in the url with the actual IP of your router.)

On this page you can start a frequency analaysis of the frequencies relevant for WLAN (~2,4 GHz). This is a special scanning mode already included in the Broadcomm driver for the WLAN chip in your WRT54G(S). For example you can use this to check, which WLAN channels are "polluted" how much by other activities in this band (for example by microwave ovens, wireless A/V transmitters, baby monitors, garage door openers...). If you need more information about the single types of measurements available (basic/beacon, cca, rpi), please have a look at this page.

This scan will most likely not work on all hardware revisions of the WRT54G or WRT54GS routers. If your router or Broadcomm driver version is not capable of doing this type of scan, you will only see a bunch of error messages, when starting the scan. For me it's working on a WRT54GS v1.1 with Alchemy 1.0. But I have received a report, that it seems not to work on a WRT54G v1.1.

This radio frequency analysis will take approximately 5 minutes to complete (if all channels 1-14 are scanned), so please be patient. During this time your WLAN will be unavailable! If you try to interrupt this scan by closing the webpage, it will still continue running on your router. So you'll have to wait ~5 minutes, before your WLAN is available again or before you can start a new scan.

Editor

To connect to the Editor page, use the url

http://192.168.1.1:8000/editor.cgi

(Replace 192.168.1.1 in the url with the actual IP of your router.)

On this page all changes will be applied immediately and can't be undone, once you have pressed a button!

Here you can create, modify and delete files and NVRAM parameter on your WRT54G(S). First enter the name of a file or the name of a NVRAM parameter in the textfield labled 'Name of File/NVRAM parameter'. Then you can press a button to apply the according operation to this file. The contents of the file/NVRAM parameter will be shown in the big textbox if you select one of the 'Load' commands. And before creating and saving a new file or NVRAM parameter, it might be a good idea to enter some text there. :-)

You can also enter a path to a directory (e.g. /tmp ) in the 'Name of File/NVRAM parameter' box and press the 'List directory' button to show the contents of this directory. When searching for NVRAM parameter, you'll also see a display like "size: 19047 bytes (13721 left)" above the big textbox. This indicates, how much NVRAM space (wich is quite small) is left.

If you enter nothing in the 'Name of File/NVRAM parameter' box, the 'Find NRAM parameters' button will give you a list of all NVRAM parameters. But you can also search for substrings. For example searching for "pppoe" will give you a list of all NVRAM parameters conatining the string "pppoe".

Deleting or modifying the wrong NVRAM parameters could seriously screw up your router and your firmware configuration!

At the bottom of this page there is a button, which allows you uploading files to your router. All uploaded files are stored in the directory /tmp. Please keep in mind, that there is not so much free memory on these devices. So don't upload big files or too many files. You cannot upload files, that are bigger than 8 MB.

Export to Speadsheet

To connect to the WRTbwlog Spreadsheet Export page, use the url

http://192.168.1.1:8000/export.cgi

(Replace 192.168.1.1 in the url with the actual IP of your router.)

WRTbwlog has the ability to create a spreadsheet from all trafficlogs, that can be downloaded from the router. Just open the abovementioned page and the spreadsheet will be automatically build. The spreadsheet is in SYLK format, which can be read by almost all spreadsheet applications like Openoffice Calc, Microsoft Excel, Mesa, MarinerCalc, Gnumeric, KSpread.

Most of these applications are even able to directly open the spreadsheet from the router. For example in Openoppfie Calc, just go to the URL box at the top left corner of the application, copy and paste the URL from the export page and you are done.

Single-Click Update

To connect to the WRTbwlog Update page, use the url

http://192.168.1.1:8000/update.cgi

(Replace 192.168.1.1 in the url with the actual IP of your router.)

On this page you can see, if there is a new version of WRTbwlog available. To update WRTbwlog to the new version, just click the "Update WRTbwlog now" button. And DON'T change the value in the textfield next to this button!

Here you can also download additional themes to your WRT54G. Just copy the full URL of a theme into the textbox labled 'URL of a theme' and press the 'Install Theme' button. To activate the new theme, select it on the configuration page, press 'Save' and switch to another WRTbwlog page.

Additional themes can be found at http://www.hetos.de/bwlog_addons.html

Configuration

To connect to the WRTbwlog configuration page, use the url

http://192.168.1.1:8000/config.cgi

(Replace 192.168.1.1 in the url with the actual IP of your router.)

On this page you can set some WRTbwlog configuration options.

Option	Explanation
General
Reboot	This will immediately reboot the router, without asking for further confirmation! All data stored on the ramdisk will be lost!
Update server	If you want to do version checking and updating WRTbwlog from your own server, this is the place to add the appropriate URL.
mini_httpd port	The port, WRTbwlog's mini_httpd server is running at.
Username	Username for htaccess authentication.
Password DES hash	DES-hash of htaccess password.
Debug mode	Not used at the moment.
Layout	Select one of the predefined layouts and color schemes. If you want to create your own custom layout, just make a copy of one of the .css files in the /tmp/bwlog directory, give it another name and change the CSS options in this file. Your new layout will automatically appear in the dropdown list after reloading the configuration page. If you are not familiar with CSS, you can find more information at http://www.w3schools.com/css/default.asp.
Traffic Statistics
Clear traffic statistics	This will reset all traffic logs and related data files without asking for further confirmation!
Traffic logging active	Set to 1 to activate and to 0 to deactivate all traffic logging functionality.
First day of billing period	The first day of your ISP's billing period.
1 MB = ? Byte:	Usually 1048576 Bytes (1024*1024) are considered being 1 MB and that's what the traffic calculations of most ISPs are based on. Some ISPs however are using 1 MB = 1000000 Bytes in their calculations (guess why). In this textbox you can adjust, how many Bytes WRTbwlog should consider being 1 MB.
D/U Speed adjustment factor	This applies to the little popup window, that will appear, if you press the 'Current speed' button on the 'Traffic' page. The Display of the down/upload speed is not very accurate and may be off a few percent (bash script limitation). Depending on the speed of your internet connection, you may want to change this value to get a more accurate measurement. For my 1024/128 connection the default value 1100 seems to be ok. If the displayed download speed is higher than the actual download speed, increase this value and if it's too low, lower the value.
D/U Speed update interval	This applies to the little popup window, that will appear, if you press the 'Current speed' button on the 'Traffic' page. Here you can select, how often the down/upload speed display will be updated. By default it's being refreshed every 5 seconds. I strongly recommend not to make it update more often, because this could cause a considerable CPU load.
Interface to log	If you want to have WRTbwlog logging a different interface than VLAN1 (WAN), you can change this here. Note, that Alchemy (and presumably all Alchemy based firmware flavours) have a bug, that on all interfaces except VLAN1, the down/up byte count is not updated correctly. So when monitoring other interfaces than VLAN1 you might not get the expected result. Perhaps this is related to the different ethernet controller in the new hardware revisions of the WRT54G(S) with missing VLAN functionality. So it might work correctly with all interfaces on WRT54G 2.0 and WRT54GS 1.0 devices. (Feedback appreciated).
Reset Trigger	The actions you can specify below, will only executed once per biling period, if the traffic is exceeding one of the defined thresholds. Once this has happened, you can reset the trigger with this button, so that these actions can be executed again in the current billing period.
Traffic Sentry
Traffic Sentry active	Set to 1 to activate and to 0 to deactivate the Traffic sentry.
First Traffic limit	The threshold, at which action 1 will be executed.
Custom script on limit 1	The custom script that will be executed once, if threshold 1 is reached. Enter the full path to this script and not only the script name!
Second Traffic limit	The threshold, at which action 2 will be executed.
Custom script on limit 2	The custom script that will be executed once, if threshold 2 is reached.Enter the full path to this script and not only the script name!
WLAN Logs
Clear WLAN logs	This will reset all WLAN logs and related data files without asking for further confirmation!
WLAN logging active	Set to 1 to activate and to 0 to deactivate all WLAN logging functionality.
Authorized hostnames on WLAN	A list of hostnames, that are authorized to join the WLAN. Unauthorized hostnames are not being blocked from joining the WLAN, but instead a custom script is being executed as explained below, if an unauhtorized hostnames is being detected. The single hostnames in this textbox have to be seperated by commas! If this textbox is empty, all hostnames are authorized to join the WLAN.
Authorized MACs on WLAN	A list of MAC adresses, that are authorized to join the WLAN. Unauthorized MAC addresses are not being blocked from joining the WLAN, but instead a custom script is being executed as explained below, if an unauhtorized MAC address is being detected. Don't confuse this feature with the MAC address blocking, that can be found in the WRT54G's webinterface at 'Wireless -> MAC Filter', as this is something completely different. The single MAC adresses in this textbox have to be seperated by commas and all letters in the MAC addresses have to be capital letters! If this textbox is empty, all MAC addresses are authorized to join the WLAN.
Custom script on other hostname/MAC	The name (including the full path) of the custom script, that is being started each time an unauthorized MAC address or hostname is being detected in the WLAN. Please do only enter the path/name of a script here and no other commands! And do not enter any fixed commandline parameters, that should be passed to the script. Because WRTbwlog will automatically pass the string "hostname" or "mac" as the first, and the hostname or MAC address as the second commandline parameter to the script. Therefore in your script you can refer to this hostname or MAC address by using the parameter $2. Please keep in mind, that MAC addresses of network adapters can easily be changed. So this features will only be useful, if the MAC Filter in the WRT54G's webinterface is not activated. Because if it's activated, a possible intruder will certainly use one of your own MAC addresses to gain access to the WLAN. In this case the hostname list might be the better choice for executing onwn commands.
Backup	For further details please have a look at the backup tutorial in the FAQ.
Backup active	Set to 1 to activate and to 0 to deactivate all Backup functionality.
Backup interval	Specify, how many seconds should pass between two backups. Don't set this interval too short when using the flash partition, as frequent write access will wear out the flash. I think 900-1800 seconds are ok when using flash for backup.
Backup destination	If set to FTP, the backup of the logs will go to an FTP server, with the configuration as specified below. If set to FLASH, the backup will be copied to the flash partition, or any other filesystem path as specified in the 'Backup path' box.
Backup path	If the option above is set to FLASH, you can enter here, where exactly the backups should be copied to. This must be a full path with a slash at the beginning and a slash at the end (e.g. /tmp/ ).
FTP server	The IP/URL of the FTP server you want to use.
FTP user	A FTP user on this FTP server. this user need full privileges to delete, create, modify and read files.
FTP password	The password of this user on the FTP server.
FTP rootdirectory	The directory on this FTP server, where you want to use to store the backup.

Screenshots (v0.9/v1.0)

Screenshot - Traffic Statistics page

Screenshot - Router Status page

Screenshot - Wireless Access Log page

Screenshot - Wireless Scan page

Screenshot - Editor page

Screenshot - Spreadsheet Export page

Screenshot - Update page

Screenshot - Configuration page

License/Credits

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License (except the parts explicitly mentioned below) as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

I'm using the following software as part of WRTbwlog:

mini_httpd

Mini_httpd is a small HTTP server devloped by Jef Poskanzer/ACME Labs.
The Homepage of mini_httpd and the sourcecode can be found at http://www.acme.com/software/mini_httpd/.
Mini_httpd is published under the ACME Labs Freeware License.

Haserl

Haserl is a small cgi wrapper that enables shell scripts to be embedded into html documents.
The Homepage of haserl and the sourcecode can be found at http://haserl.sourceforge.net/.
Haserl is published under the GNU General Public License.

Parts of the bwlog.sh script include code from a script originally posted by Epsylon3 and modified by xadas at the Sveasoft forums.

A copy of the GNU General Public License can be found here. Or you can get one from the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.