Version 5 (modified by acv, 14 years ago)


Main contributors: Benoit Grégoire, Philippe April Last modified: 2008-03-21

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

That pretty much leaves only two options: YAML and XML, with YAML matching them more closely.

Philippe: experienced with JSON, and it's great (great parser/generator for C). See doc/developer/WiFiDog_V2

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)
  • 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:
  * loginurl: https://.....
  * portalurl: http://...
  * timers:...
  * global bandwidth settings
 * clients_that_should_be_allowed:
  * { mac: xxxxxxxxx, ip: xxxxxxxx, bandwidth settings},
  * { mac: yyyyyyyyy, ip: yyyyyyyy, bandwidth settings}