Gargoyle: completely open source and easy to use

Those who want to install alternative firmware on their router generally pick OpenWrt, DD-WRT, or Tomato, but Eric Bishop found their web interfaces to be too focused on power users. So he started tinkering with OpenWrt and built a new web interface on top of it. That became Gargoyle, which had its first stable release in July 2009. The project is meant for average users and focuses a lot on usability, but that doesn't mean it's short of features.

Eric started Gargoyle because there really wasn't an open source router firmware replacement that was easy to use. Gargoyle is a web front-end to OpenWrt, which makes it comparable to other projects like X-Wrt and LuCI (OpenWrt's new web interface). The latter two projects, though, want to provide maximum functionality in their web interface. According to Eric, they are designed to be easy for developers to improve, which means that it's easier to add new features. As a result, both X-Wrt and LuCI tend to be quite feature-rich, but aren't necessarily very easy for the typical end user to figure out:

Tomato and DD-WRT provide the source code to their web interfaces, but the license prohibits the distribution of modified versions without the author's permission and thus both projects don't qualify as open source. In contrast, the Gargoyle web interface is completely open source: it's released under the terms of the GPLv2, with a clarification that permits adapting the web interface to configure proprietary back-end software, provided that all modifications to the web interface portion remain covered by the GPL. The rationale behind this clarification is that it makes Gargoyle more attractive for companies to use in their hardware.

Installation

Gargoyle is based on the most recent Kamikaze (development) release of the OpenWrt firmware. It is even possible to install Gargoyle as a set of packages on top of an existing OpenWrt installation (with a simple opkg install gargoyle command after adding the Gargoyle repository to /etc/opkg.conf). But the project's web site also has some images for routers that have Broadcom or Atheros chipsets and use the MIPS architecture, which includes many popular routers. Full details about which routers are supported can be found on the OpenWrt wiki. If the router is supported by OpenWrt but Gargoyle doesn't have an image for its architecture, you have to build the image yourself. Installation instructions for some popular routers such as the Linksys WRT54G family and the Asus WL500G Premium are fairly straightforward, typically just involving the router's reset button, a computer with an Ethernet cable, and tftp to upload the firmware image. Interested users can choose to download Gargoyle's stable branch (currently 1.2.5) or the experimental branch (currently 1.3.8).

After a successful installation, the user connects to the router with an Ethernet cable, after which the router's web interface is accessible at http://192.168.1.1 or https://192.168.1.1 with a default administrator password. Gargoyle also allows SSH access by default for "root" with the same default password. After the first login into the web interface, the user is asked to change the root password, which is a smart move. The next page gives the user the choice between configuring the router as a gateway (if it's connected to a DSL or cable modem) or as a wireless bridge/repeater. Below this are the WAN and LAN options, and at the bottom the user configures the wireless network for things like the SSID, encryption type, and password/key. After that, the Ethernet cable is no longer needed.

Bandwidth quotas and graphs

The available settings are divided into three menus in a sidebar at the left of the page: Status, Connection, Firewall, System, and Logout. The base settings that the user entered after installation are found under "Connection->Basic", but other submenus of the Connection menu provide ways to configure DHCP, dynamic DNS, and routing. The Firewall menu name is a bit of a misnomer, as it is more about all settings involved with ports and restrictions. For example, this is the place where port forwarding and Quality of Service (QoS) are set up, as well as bandwidth quotas.

The latter is an especially interesting and unique feature that is not often found in open source router firmware: it allows the user to restrict specific computers to download or upload a specified amount of data. The settings are very flexible: administrators can choose to restrict the quotas only on specific days or hours and they can configure how often (hourly, daily, weekly, monthly) along with the hour at which the volume restrictions are reset. In the latest experimental branch, administrators can also throttle bandwidth when a device's bandwidth quota is reached, allowing a lower level of service in that case instead of blocking all network access. There's another interesting submenu, Restrictions, that goes further and can restrict all network access for specific time periods or block specific ports, protocols, or website URIs. All in all, these features are intuitive to use and perfect to restrict your children's devices for example.

Where Gargoyle really shines in comparison to other open source router firmware are the graphs in the Status menu. The submenu "Bandwidth Usage" shows graphs of the bandwidth usage over the WAN interface — by default for the last 15 minutes, but the granularity of the view can be changed to 6 hours, 24 hours, 30 days, or a year. Moreover, it's also possible to show the bandwidth usage of up to three individual hosts in the same graph. At the bottom of the page, the same information is shown in tabular form and there's even a button to download the data as a CSV file, ready to be processed by other tools. Another interesting submenu of the Status menu is "B/W Distribution", which shows the relative use of the bandwidth by all network clients in a pie chart. The granularity of the time period can be changed for that chart as well.

The fact that Gargoyle is based on OpenWrt has the advantage that most of the tips and tutorials for OpenWrt also work on Gargoyle. So you don't have to sacrifice functionality for usability. If the web interface doesn't expose a specific function, just log in as root via SSH, install the needed packages, and run the right commands. There are around 1500 packages available to install using the opkg package manager.

Development

Gargoyle isn't that well-known, so it shouldn't be a surprise that it doesn't have that many developers. Other than Eric, there is just one person who has been consistently contributing to the project: Paul Bixel. He is primarily interested in the QoS functionality in Gargoyle, and Eric is excited about Paul's main contribution:

The active congestion controller makes the QoS feature, which divides the available bandwidth between different classes of traffic, more flexible. The problem with QoS is that in order to allocate, for example, 25 percent of available bandwidth to HTTP traffic, the user needs to know how much bandwidth is available. According to Eric, all QoS schemes — including those in Tomato, DD-WRT, and OpenWrt/LuCI — have a setting where users need to enter the total amount of bandwidth that's going to be divided between the different classes of traffic. If ISPs provided a constant minimum amount of bandwidth to their customers this wouldn't be so bad — you would just enter whatever that amount is and move on. However, the amount of available bandwidth is usually not constant. Depending on how busy the ISP is at a given time, bandwidth available to an end user can fluctuate dramatically. The active congestion controller addresses this issue, Eric explains:

Both Gargoyle's QoS functionality and the active congestion controller are not just web interface front ends but features with code deep in the OpenWrt/Gargoyle stack. These changes have not been sent upstream, but, as all of the code is GPL, anyone could add it to OpenWrt. However, the active congestion controller depends on the Gargoyle QoS strategy, which differs substantially from OpenWrt, so this feature cannot be used in OpenWrt without also adopting Gargoyle's QoS code.

Besides Eric and Paul, there are a bunch of people who have made smaller contributions, such as Artur Wronowsky, who implemented Wake-on-LAN functionality which will come out in the next release, and Cezary Jackiewicz who translated the entire interface into Polish. Unfortunately, the latter is in the form of a huge patch that only supports Polish, but Eric wants to implement proper internationalization support in the experimental 1.5 branch some time after the stable 1.4 branch has been created.

According to Eric, the best way to contribute to Gargoyle is to clone his github mirror of Gargoyle, commit your fix, and send him a pull request: "That makes it really easy for me to review changes, and merge them into the main repository."

There isn't really a concrete roadmap for the project, but Eric explains we'll see a new 1.4 stable branch within the next month or two:

In the longer term, Eric has been meaning to implement a captive portal, a technique that forces clients on the network to see a web page with authentication before they are able to use the network normally:

Conclusion

Your author has been using Gargoyle on his router at home for over a year and he is rather surprised that Gargoyle is not as well-known as other router firmware. Indeed, it has a unique combination of properties: it's completely open source, it's easy to use for casual users, it offers pretty graphs, it has a flexible bandwidth quotas system, and the active congestion controller that is being worked on seems like a nice piece of technology. Granted, the development team is small, but they have a clear vision. Moreover, it's all based on OpenWrt, so there's a plethora of packages and documentation available.