WISP-in-a-box Way Forward

This document remains very much a draft, but is the evolving specification for the WISP-in-a-box project

Overview

The entire WISP-in-a-box system consists of:

• A central dashboard, running on the gateway server, from which:
  • the network can be monitored and all node can be configured
  • pre-paid vouches can be administered
  • software running on the server (web & mail services, upstream connection QoS software, etc) can be administered
  • all functionality will work without upstream Internet access
• Mesh nodes which:
  • receive configuration updates from the central dashboard
  • run a captive portal that interacts with clients and authenticates against the gateway server
  • run intra-mesh QoS software
  • route themselves intelligently using BATMAN

Component Diagram

[[Image:|thumb|Illustration 1: WISP-in-a-box basic components]]The basic setup looks like this:

For the Village Telco project, many components are the same. There is some additional functionality that's desired, however, that can reside on top of the base WISP-in-a-box system. So the setup might look more like:

[[Image:|thumb|Illustration 2: Village Telco network, built on top of WISP-in-a-box mesh]]

This document is going to mainly focus on specifying the needs of the mesh & networking side of things, with an eye towards exactly how voice-related services will be integrated (but not an elaborate discussion of the technologies themselves).

Dashboard & Server

Existing Dashboard Projects

The OrangeMesh and Open-Mesh dashboards provide almost exactly the functionality we require. However, they have a number of problems:

• Both dashboards require the nodes to be running ROBIN firmware to receive configuration updates. ROBIN, as it is now, only runs on Atheros-based devices, not Broadcom devices (like the Linksys WRT). Some semi-serious hacking will be required to add support for Broadcom devices into ROBIN, since right now it assumes the use of the Atheros-only MadWifi drivers.
• With an eye towards localization & modularity, the OrangeMesh sources aren't quite what we'd like them to be.

Because of these limitations, we may not want to use the OrangeMesh/Open-Mesh dashboard. We still want to imitate the same basic style of system, however, while adding some functionality to meet the additional needs of our dashboard (e.g. ability to administer vouchers and server services, things that the OrangeMesh/Open-Mesh dashboards don't cover).

Our Approach

We will start essentially from scratch on the dashboard, with the OrangeMesh dashboard as an example to work off of and borrow heavily from.

The dashboard we will design will be highly modular, with a high-level menu in which the user can select a module to work with. A module might be an existing software component or a new one we've written. In the case of Network Status and Network Configuration, we can use the Orangemesh-Openmesh/ROBIN setup as a reference, and where appropriate can adapt their code to suit our needs. Other tools to borrow from include Zeroshell for network QoS configuration. Essential modules include:

• Server Administration -- brings up Webmin
  • This will not only allow us to configure the server, but also execute arbitrary commands on all the mesh nodes using Webmin's cluster functionality. We will strip down a version of Webmin to run on the client nodes and use Webmin's cluster modules on the server to communicate with them.
• Vouchers -- brings up phpMyPrepaid, our data billing control system
  • phpMyPrepaid additionally controls the CoovaChilli instances running on all routers, including the ability to restrict or permit free access to the rest of the mesh network
  • We need to also design in some way of dumping the user usage data that FreeRADIUS stores so that Michael Jenkins can do usage studies on it. The local user needs to be able to easily dump this data and send it back to the CSIR for study.
• Network Status -- new custom dashboard component with following features:

• A semi-detailed list of all the nodes in the mesh, including:
  • the node's IP and MAC addresses
  • the node's current status (simple up or down)
  • when they were last heard from (when an update from that node was last received)
  • how many hops and/or what route the node currently has to the gateway
• Basic network usage statistics, data taken from RADIUS:
  • Total bandwidth going out of the gateway in the last X amount of time
  • Heaviest users of the network to monitor abuse (further information on individual users is available already in phpMyPrepaid)
• Ability to test network throughput, either through:
  • Simple interface to run iperf between any two nodes, or:
  • Visual display of metrics & signal strengths of every link, data reported from clients' BATMAN daemons and network tools

• Backbone Network Configuration -- new custom dashboard component with following features (note this is designed to be minimal for ease of use):
  • Change SSID of mesh backhaul
  • Change channel of mesh backhaul
  • Other features? Open to discussion.
• QoS Network Configuration – new custom dashboard component for adjusting QoS settings both:
  • On the server, for outgoing traffic going to the upstream connection
  • On the various nodes in the mesh, for intra-mesh network bandwidth management.
• AP-only node configuration – new custom dashboard component that configures node that are only AP's, not part of the mesh. Configures:
  • SSID of AP
  • Channel of AP
  • Any kind of WPA authentication a user might want to run on the AP

Possible other voice-related modules include Asterisk and A2billing pages.

The dashboard will send out all configuration updates using a standardized API; any mesh node in the network will have to run a client implementing this API that receives configuration messages from the dashboard and makes the necessary changes to files on its system. The API will be just as modular as the dashboard, so if a user wants to only implement certain features (say, add billing to an existing network) she would only need to implement a client for the platform her nodes are running (or, ideally, there will already be a client for that platform). Through the dashboard the user could then disable the unwanted modules. The dashboard will only send out updates for the components that are enabled, and the client will only modify configuration files for the components it receives.

All of the components of the larger dashboard will be skinned in a unified CSS style, with the potential for branding built in.

Mesh Nodes

The mesh nodes themselves will run OpenWRT. Node software includes:

• Batman for routing
• CoovaChilli as a local captive portal
• Intra-mesh QoS software, configurable from the dashboard. Uncertain as to what tools exactly to use here, however borrowing from Zeroshell it may be possible to simply use netfilter/iptables & l7-filter. Using an existing tool here would be very nice, as this is a complex task.
• A client daemon modeled on the ROBIN scripts that receives updates from the dashboard and sends any necessary information back to the dashboard. The client daemon will have to be co-developed with the dashboard.
• Stripped-down Webmin server component so we can run remote Webmin commands on the node through the server's Webmin installation.
• In addition to configuration through the dashboard, we will include a minimal web interface for configuring each individual node. This interface will run on the nodes, and can be a stripped-down version of X-WRT's webif^2 or FFLuCI. It would be useful if the interface could be designed such that it would run on any device regardless of that device's platform. This may be easy to do with existing abstractions in OpenWRT, but an alternative method would be for this interface to change the configuration of the local node via the update API, which is guaranteed to be fully abstracted, and let the update client for that device take care of making the actual changes.

AP-only Nodes

The mesh nodes will use their radios exclusively for the mesh backhaul. Clients can be attached directly to the Ethernet ports of these nodes, however it may be useful to have wireless client access as well. In this case, a second device can be attached to the mesh node to act as an access point. These devices can also be Linksys WRTs or similar. They will be bridged to the DHCP server of the captive portal running on the mesh node, and so need no special functionality.

• If central configuration isn't desirable then any device that can operate as a pure AP without a DHCP server will do (the Linksys stock firmware, for instance).
• If configuration via the dashboard is desired, then the nodes will run OpenWRT and a barebones dashboard client that allows for configuration of the AP's SSID, etc.

Task Breakdown

Once the specification is agreed upon work can begin. At that time further task breakdowns may be useful, but at a high level the expectation currently is as follows (refer to above for details on what individual software piece entail):

1. Dashboard & first client development: Meraka
   1. Further examination of ROBIN to see which parts of it can be modified for our purposes
   2. Adaptation of Webmin's cluster tools for use on the mesh
   3. Update API design & specification
   4. Dashboard framework design and implementation
   5. Mesh update client framework design and implementation
   6. Dashboard module implementation
      1. Network Monitoring
      2. Network Configuration – basics (Channel, SSID, etc)
      3. Network Configuration – QoS settings
      4. Network Configuration – AP-only settings
      5. Adapt phpMyPrepaid's CoovaChilli configuration to send out updates via standardized API rather than only changing local configuration file.
   7. Co-development with dashboard modules: mesh client update modules for each dashboard component, designed initially for the WRT but as portable as possible (for most modules portability should be trivial, as the software on the node the update client is configuring will be the same).
   8. CSS skinning for all dashboard components (including pre-existing ones such as Webmin and phpMyPrepaid).

Notes: These need to be done relatively sequentially, however once the dashboard and mesh client frameworks are in place different modules can be developed in parallel.

1. Minimal interface development for starter devices (at least the WRT, Mesh Potato, and Ubiquity nodes): Inveneo
2. Porting of mesh client to Ubiquity and Mesh Potato (most modules should be identical, but basic network configuration settings may be device-specific): Inveneo