Main contributors: Benoit Grégoire, Philippe April, Alexandre Carmel-Veilleux

This page documents the design effort for designing version two of the wifidog protocol specification. While it will eventually turn into a structured specification, currently,

Wire protocol

Response format

It is desirable to have the following features in the wire protocol:

  • Compact representation (bandwidth is NOT cheap when serving a distributed network)
  • Human readable
  • Fast and small parsers available for C and PHP, and ideally multiple other languages
  • Suitable for sharing parser and format with the configuration file
  • Suitable for cleanly representing trees (like the list of auth servers)

After discussion, the representation will be JASON. For config comment, a verb will be reserved for comments, which will be systematically ignored.

Request format

It is beyond desirable to have to following with request format:

  • More than one operation per http request (for example, update statistics for more than one user)
  • Keep the http transport, as it allows us full NAT and transparent proxy resistance

Some of the requirements above do not lend itself well to a RESTFull Resource oriented architecture (ROA). However, keeping the current format (GET parameters) limit us, in practice, to a single list of tag-value pairs. Even if one could, in theory, put an action=whatever in the middle of the list and have the protocol decree that every following parameters (until the next action) is to be a parameter of that action, that would utterly confuse most web servers and frameworks.

acv: One other possibility is to borrow a page from the way PHP does URL-parsing. Setting the key part of the get request to a array representation would allow for fairly logical request bundling., I.e.:


acv: This format would remain human readable while being very simple to parse (free in PHP, trivial in other languages).

So POSTing the parameters may have to be considered, in which case the same format as the response should be used, for obvious reasons.

Functionnal Requirements

  • Allow some general configuration changes to be sent by the auth server.
  • Allow non web-based MAC auth > Philippe: Explain this?
  • Allow non connection based MAC auth
  • Allow per-connection firewall policies
  • Allow per-connection bandwidth management, not limited to set amounts
  • Allow global bandwidth management (might come in configuration)
  • Specify walled garden
  • Specify list of initially connected users
  • Many more....

Philippe: Ideas?

Philippe: Way to allow people on restart, or deny people on inactivity acv: People on restart needs to be pulled from auth server unless either of: (a) We have non-volatile storage that isn't too badly affected by write-wear; or (b) We have not rebooted and can read a file from ramdisk.



Basically there only for gateway heartbeating. A min delay between operations would be specified, and if this delay is reached before an actual operation has to be performed, a NOOP is sent.

Philippe: not required, we'll always send at LEAST the status. If no "command" is sent, it means NOOP :)



A proposed solution


I think we could have a Hash kind of structure like this:

 * protocol_version: 1 (start with this to identify protocol)
 * wifidog_version: ...
 * status:
   * uptime, etc.
 * connected_clients:
   * stats, etc.

and a sample reply (just ideas...)

    "protocol_version": 1,
    "config": {
        "login_url": "https://auth.server/login.php",
        "portal_url": "http://portal.server/",
        ... },
    "clients": [
        { "mac": "00aabbccdd22", "ip": "", ... },
        { "mac": "00aabbccdd22", "ip": "", ... },
        ... ]

Gateway and Auth-Server communication

Gateway : Verbes / ActionsAuth-Server
Init requestGateway configurations
MAC detectAuth response (accept/deny this MAC)
User auth requestUser connection configation (open/closed port, QOS)
Auth the auth server (key + protocol)Auth the gateway (key + protocol)


  • Splash page if auth-server=down (URL)
  • Splash page if internet=down (content)
  • Walled garden (Think about DNS timeout)
  • Static White/Black? list MAC
  • Global firewall / QOS configuration
  • Gzip optionnel, response only, through standard HTTP