From The Commons
Jump to: navigation, search

AutoTunnel is a system for Authentication, Authorization, and Accounting on free networks. Its primary features include 802.1x security for both wireline and wireless access, Radius authorization and accounting facililities, and network ingress and egress control. It is designed to be federated, allowing participants in a free network to choose a gateway provider according to their own needs and available offerings. It eliminates the need to establish dedicated tunnel overlays for provisioning internet service in free networks, through the use of route translation, VLAN isolation, and policy routing. AutoTunnel has three primary components, which though strongly coupled, are theoretically modular: the access stack, authorization stack, and edge stack.


Access Components

The access stack consists in a patched version of the OpenWRT hostapd system, and hostapd configuration parsing script. Hostapd is an application written in C which is responsible for handling network authentication functions in Linux. While the mainline version of hostapd does have support for Radius authentication, such support is limited to basic 802.1x (WPA Enterprise) authentication.

Code for AutoTunnel WPAD/Hostapd can be found on | github

Vlan Assignment

While dynamic vlan assignment is possible in the stock version of hostapd, its implementation is incompatible with the qmp/bmx network architecture. In stock hostapd, vlans can only be crated and assigned on top of a fresh, purpose-specific bridge device. AutoTunnel extends hostapd's vlan creation facilities to enable programattic creation of vlans on top of existing bridge devices (such as br-lan, in the case of qmp). Such vlans can be created in response to user-specific attributes during the radius authentication process.

Extended Accounting

Stock hostapd also includes support for radius accounting, including bytes-in and bytes-out measurement of user traffic. AutoTunnel extends accounting support to include the ability to send a station's ip address to the accounting server once it has been assigned from the AP's local DHCP pool. In this way, address management remains distributed, but access and edge components are able to operate on layer 3 identifiers.

Policy Routing

At the core of AutoTunnel's functionality is the ability to create routing policies on a per-user or per-vlan basis based on instructions from a radius authentication server. In order to achieve this functionality, AutoTunnel leverages the abilities of the bmx6 routing protocol, iptables+ebtables physical device tagging, and iproute2 policy routing features. AutoTunnel makes use of the 'Framed Route' radius attribute to communicate the gateway that should be used by a partiular user in order to reach the internet. AutoTunnel extracts this information, and creates a bmx6 'tunnel out' directive, exporting the route to a vlan-specific routing table in the kernel. Because all AutoTunnel-created vlans are attached to the primary lan bridge device, ebtables must be used in conjunction with iptables to give an identifying mark to those packets that come in over a particular bridge port (vlan). Finally, iproute is used to examine identifying marks, and direct route lookups to the appropriate routing table.

Auth Componenets

There is a good degree of flexibility in the auth stack, but the reference implementation is built using FreeRadius2 running on top of Debian 7. AutoTunnel can be integrated into existing radius facilities. AT auth compoenents are comprised of radius site confiugration directives, radius domain proxy settings, and a radius exec module responsible for exporting user session state to the edge components.

Additionally, auth server network reachability is facilitated by round-robin dns naming. Operators may use whatever dns server they please, but the reference implementation of AutoTunnel uses PowerDNS.

Edge Componenets

While it would certainly be possible to extend AutoTunnel support to other routing platforms, it currently is designed to be used with pfSense, a routing-focused distribution of bsd. In partiulcar it leverages a modified version of the 'pfBlocker' module for pfSense 2.1. Based on user state information exported from the auth server, firewall policies are created to allow authenticated users to egress the free network and access peer networks. This is acheived by creating a default-drop policy on free network-facing interfaces, and dynamically adding authenticated users to a pass alias.


AutoTunnel is intended for use inside free and community networks that employ the bmx6 routing protocol. Its functionalities could be extended to support any routing protocol which allows for table-specific route export.


To understand how AutoTunnel works, let's take an example network, and run through some scenarios. Let's call our example network Free Network X (FNX for short). Inside of FNX, we have two competing gateway providers, Gateway Alliance and Gateway Brotherhood (GWA and GWB). FNX itself is a bmx6-routed network with distributed/diverse ownership. Participants may access any resouces inside FNX free of charge, including some community run low-performance web proxies, local media channels, and local mirrors of educational resources. Those who wish to access the wider internet without hinderance must contract with a gateway operator. Gateway customers are assigned usernames in the form of [email protected] -- for our case, let's imagine two different customers, [email protected] and [email protected]

While other schemes are certainly possible, the intended use-mode is one in which gateway operators actively coordinate their configurations. Each operator is assigned one or more vlans to use, in order to avoid vlan conflicts. Additionally, because route export is based on the name of the bmx gateway, gateway names must also be coordinated at the network level. While VLAN and gateway name coordination could be automated, they should scale decently even with manual coordination.

For our purposes, we'll make a few assumptions: while GWA has been assigned VLAN 10 and their internet-bound traffic flows througha router named 'qmp-gwa', GWB has been assigned VLAN 20, and their internet-bound traffic flows through a router named 'qmp-gwb'.

Use cases

The Marina

Now, let's take the case of the Marina. A router at the Marina is connected to FNX via a point-to-point microwave link. A qmp mesh node is installed on the pier, and a qmp access point is installed in the Marina's public cafe. Skippers are encouraged to install a mesh node on their boat, so that they can have internet access onboard while they are in port. In addition to residents, visitors to the Marina are told that they will have internet access in the cafe.

Device Provisioned Access

Upon hearing about the new network, Angel, who keeps her houseboat, Esmeralda, in the Marina, decides that she will install a qmp node on the ship. She purcases a Ubiquiti Nanostation Loco or similar device, and flashes it with the FreedomNode/FNX firmware, which uses the qmp system including AutoTunnel. After installing the device, she is connected to FNX, but cannot access the internet. When she does try to access the internet, her traffic flows to whichever edge router the bmx6 protocols deems most expedient. A NAT rule on the chosen edge router redirects her the FNX splash page, which explains the architecture and philosphy of the network, and links to an index of gateway operators from whom she might be able to purchase internet access. The contents of the splash page are determined by the network council of FNX, and a mirror of the splash page is hosted by each AutoTunnel-compliant gateway provider.

Angel likes the offering from Gateway Alliance, a cooperative of nodes owners, and clicks on the 'join' link. She is redirected to GWA's enrollment server, where she creates an account, provides payment details, and agrees to GWA's terms of service. She then navigates to the administrative interface of the node installed aboard The Esmeralda, and configures GWA as her gateway provider, entering credentials obtained during the enrollment process. A configuration is generated which will automatically authenticate against GWA's auth server using the provided credentials. Because the node aboard The Esmeralda is serving as an access point and performing NAT, the gateway sees all Esmeralda LAN traffic as coming from the router. When the node aboard The Esmeralda authenticates, the auth server of GWA informs GWA's edge router that traffic originating from The Esmeralda's IP address should be allowed to pass through to the internet. Angel can have whatever security settings (WPA2, etc) that she wants on the WLAN, or leave it open -- all traffic will be dropped into VLAN 10, routed to GWA's edge server, and treated as belonging to The Esmeralda (and Angel) by GWA. The node aboard Esmeralda sends periodic accounting updates to the GWA radius server, which include aggregate internet-bound bytes transmitted and received. GWA does not log any other data. At the end of each month Angel gets a bill for whatever internet traffic she and her guests aboard the houseboat have generated.

User Provisioned Access

Bart, who also keeps a boat in the Marina, doesn't necessarily want to install a node on his boat, Hesia, but would definitely like access in the Marina's Cafe, where he tends to spend his afternoons computing and drinking. The Marina owners, when installing the cafe access point, configured it for AutoTunnel public access - it runs two virtual access points: one that is open, and one that is secured using 802.1x and WPA-Enterprise. All traffic on the open network is seen as unauthenticated by all AT-compliant gateway providers. When Bart join the open network in the cafe, and tries to go to his favorite site, he is redirected to the FNX splash page, where he chooses to enroll with Gateway Brotherhood. After completing the enrollment process, he is provided credentials that he can use to join the 802.1x secured network. When he attempts to do so, an auth request is sent by the cafe access point either to the nearest auth server directly, or to '' -- which any AT-compliant dns server will resolve in a round-robin manner to a randomly selected AT-compliant auth server on the network. The auth request, which contains the username '[email protected]' is examined by the selected auth server. If the auth server does not belong to GWB, it will proxy the request to Once determines that bart's credentials are correct, it sends an access-accept message to the access point in the cafe, specifying that Bart should be placed in VLAN 20, and that all internet-bound traffic from VLAN 20 should be directed to qmp-gwb, which will forward it to GWB's edge router. Packets that come in over VLAN 20 are marked with a '20', a default route via qmp-gwb is placed in routing table 20 on the access point, and a routing rule is created that say that if no specific route to the destination exists, then traffic marked with a 20 should be sent to qmp-gwb. The access point in the cafe send periodic accounting update to the the radius server of GWB, indicating Bart's aggregate internet use. GWB tracks this usage, and sends Bart a bill at the end of the month.

Angel, from the use case above, can make use of the access point in the cafe. She has only to enter the same credentials which she configured on the node aboard the Esmeralda into the 802.1x prompt, and will inform the access point that she should be placed in VLAN 10, and that her internet traffic should be sent to qmp-gwa.

Guest Access