User: Password:
Subscribe / Log in / New account


Gargoyle: completely open source and easy to use

December 22, 2010

This article was contributed by Koen Vervloesem

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.

[Gargoyle bandwidth graph]

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:

Number of features versus usability tends to be a trade-off. For a lot of advanced users the greater difficulty of configuration isn't a problem and X-Wrt or LuCI are exactly what they want. However, there are a lot of users that find these web interfaces very frustrating. I started Gargoyle to provide an open source, easy to use alternative for people who don't want to spend a lot of time figuring out how everything works.

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.


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 or 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.

[Gargoyle bandwidth distribution]

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.


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:

Along with many smaller contributions, Paul wrote a new Active Congestion Controller to dynamically detect when the available bandwidth provided by your ISP changes, and alter the QoS rules accordingly. While this utility is still somewhat experimental, this is a really phenomenal piece of work: no other firmware has anything like it.

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:

What the active congestion controller does is detect whether or not congestion is occurring (meaning that the bandwidth being used has reached the maximum available), and then dynamically alter the QoS settings to reflect the amount of available bandwidth. Thus when more bandwidth is available from the ISP it can be made available to the hosts in the network, and when less bandwidth is available the QoS rules will still work.

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:

We have added support for a huge number of newer Atheros (ar71xx) wireless N routers in 1.3 and I want to create a stable branch with support for this hardware as soon as possible. So rather than focusing on adding new features the biggest concern right now is finding and eliminating any remaining bugs in the experimental (1.3) branch.

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:

While this has a high priority, it's going to take a significant amount of time to do right, and so far a lot of minor bug fixes and improvements have meant that I haven't found a large block of time to devote to implementing this.


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.

Comments (7 posted)

Brief items

Distribution quote of the week

It's not for lack of a loving community — Mandriva's community had some die-hard fans that stuck by the distro through thin and thinner. (Let's face it — it's never really gotten to "thick," for the Mandriva business.) But the development layoffs this year were too much, and the community finally decided to say "fork it."
-- Joe "Zonker" Brockmeier (by way of Linux Magazine)

Comments (none posted)

Introducing the "Debian's Automated Code Analysis" (DACA) project

Raphael Geissert has announced a new project to do automated code analysis on programs in the Debian archive. So far, two tools are being used: cppcheck and checkbashisms, but more are planned to be added. Geissert is looking for volunteers to fix bugs that are found, check the test output for false positives and other problems, join the project to evaluate additional tools and set up infrastructure to run them, and donate hardware for running the tests. "Most of the tools are CPU-bound, limiting considerably the number of tools and time it takes to check the whole Debian archive. For example, with the typical sid repository update (i.e. not during the freeze and with a working ftp- master) it is impossible for the server running cppcheck to keep up with all the changes."

Full Story (comments: 36)

Openwall GNU/*/Linux 3.0 is released

Openwall GNU/*/Linux has released version 3.0, which marks roughly ten years that the project has been active. New features include x86-64 support, a RHEL-5.5-like 2.6 kernel, OpenVZ container-based virtualization, and more. "Openwall GNU/*/Linux (or Owl for short) is a small security-enhanced Linux distribution for servers, appliances, and virtual appliances. Owl live CDs with remote SSH access are also good for recovering or installing systems (whether with Owl or not). Another secondary use is for operating systems and/or computer security courses, which benefit from the simple structure of Owl and from our inclusion of the complete build environment."

Comments (2 posted)

Distribution News


Appointment to the Fedora Board

Jared Smith has announced that David Nalley has accepted a seat on the Fedora Board. "I've known David for a number of years, and have do doubt that he will do a fantastic job. He's proven himself as an outstanding Fedora Ambassador and mentor, and shown his ability to be effective and tactful in his communications. He has also shown tremendous dedication and loyalty to the Fedora community."

Full Story (comments: none)

SUSE Linux and openSUSE

Board Meeting Summary 15 December 2010

Bryen Yunashko has a summary of the December 15 meeting of the openSUSE Board. Topics include Introduction of new openSUSE Board Chairman - Alan Clark, Foundation Creation, and Membership Approval Concerns.

Comments (none posted)

Ubuntu family

Canonical announces Ubuntu Developer Day

Canonical has announced that Ubuntu Developer Day will take place in Bangalore, India on January 27, 2011.

Full Story (comments: none)

Newsletters and articles of interest

Distribution newsletters

Comments (none posted)

Jolicloud: Cloud enabled and not just for netbooks (Linux Journal)

Linux Journal has a review of a preview release of the forthcoming Jolicloud 1.1 version. "Netbooks are the obvious target of this distribution, and by default, it's setup as a browser for website and cloud based applications. However, it's easy to expand, and I think this could be a distribution with a lot of uses. It's possible to add applications, and it can also be installed on any hardware that standard Ubuntu can including desktop PCs. Even better, as well as focussing on convenience, it's easy to use, meaning that it might be a good platform for people who aren't very good at using computers."

Comments (none posted)

My Five Favorite Not-Usual Linux Distros (Linux Planet)

Carla Schroder reveals her favorite distributions over on Linux Planet. "Arch is my new favorite no-frills Linux. Arch is well-maintained, and the one big feature that sets it apart from all other Linuxes is the Arch Linux Wiki. This is the best-documented Linux distro of all. Rather than wasting energy continually re-inventing poorly-designed GUI interfaces in place of good howtos, Arch relies on sensible design and good documentation. It is sleek, clean, and efficient, and thanks to good design and documentation it is easy to learn. It fits any role well-- desktop, server, router, and I like it as an audio production platform. It makes the most out of modest hardware, and supports a full range of audio applications."

Comments (none posted)

A Tinkerers Top 5 Distributions of 2010 (All Things Linux Blog)

Here's another "top 5" list featuring Arch, Salix, Slackware, Debian, and Unity Linux. "The Unity project, not to confuse with the desktop environment, has had their first full release in July 2010 and have recently updated with a second point release. I like small distributions that provide a minimal base for a custom install, and Unity excells at that. It has been designed with explicitly this aim in mind, while providing users with the Goodies that is the Mandriva set of tools, known as, or better combined in, the Mandriva Control Center."

Comments (none posted)

Page editor: Rebecca Sobol
Next page: Development>>

Copyright © 2010, Eklektix, Inc.
Comments and public postings are copyrighted by their creators.
Linux is a registered trademark of Linus Torvalds