Main contributors: Benoit Grégoire, datamile. Last modified: 2007-06-25

Gateway heartbeating (Ping Protocol)

Wifidog uses the ping protocol as a heartbeat mechanism to send current status information to the auth server. This enables central logging of the status for each node at the auth server.

The wifidog client uses a setting in the conf file to periodically start a thread ( ping_thread.c ) to send a status message via http to the auth server. The message format is


With the data gathered via system calls on the wifidog client.

"User-Agent: WiFiDog %s\r\n" 
"Host: %s\r\n" 

A typical HTTP request would be:

GET /ping/?gw_id=001217DA42D2&sys_uptime=742725&sys_memfree=2604&sys_load=0.03&wifidog_uptime=3861 HTTP/1.0
User-Agent: WiFiDog 1.1.3_beta6

To this the auth server is expected to respond with an http message containing the word "Pong".

Auth server authentication protocol

This page describes the messaging between the wifidog gateway and auth server to validate a user, and ongoing once the user is validated and permitted access to the internet.

Periodically the wifidog client will start a thread to report the status of each user connection. Currently this is used to reporting incoming/outgoing counters for each user, to show that the user is still connected, and to allow the auth server to trigger disconnects of users the should no longer have access.

The following message is sent for each connected user


Note: stage= counters or login, depending if this is a new client or not.

Even though the incoming and outgoing variables are present in all messages they are only valid for messages with a stage of *counters*. In all other cases incoming and outgoing are always set to 0.

In response the auth server will respond with a valid status, and a new user message, or an auth server error.

The format of the response should be:

Auth: <number from user status list>

The new user status can be:

0 - AUTH_DENIED - User firewall users are deleted and the user removed.
6 - AUTH_VALIDATION_FAILED - User email validation timeout has occured and user/firewall is deleted
1 - AUTH_ALLOWED - User was valid, add firewall rules if not present
5 - AUTH_VALIDATION - Permit user access to email to get validation email under default rules
-1 - AUTH_ERROR - An error occurred during the validation process

Note: auth server errors do not currently change firewall or user status.

Typical URLs would be:

GET /auth/?stage=counters&ip= HTTP/1.0
User-Agent: WiFiDog 1.1.3_beta6

Browser redirects by the gateway

The client browser is going to be redirected to another page in different circumstances:

On the initial request:

Upon capture, the client will be redirected to the following URL by the gateway:

  • login/?gw_address=%s&gw_port=%d&gw_id=%s&url=%s


After the initial request

Once the login request is processed and client has been redirected to the gateway (stage=login)

If server returned AUTH_DENIED: Note that you will normally never see that one in the standard auth server. The client won't be redirected back to the gateway.

  • gw_message.php?message=denied

If server returned AUTH_VALIDATION:

  • gw_message.php?message=activate

If server returned AUTH_ALLOWED: This is the portal redirect

  • portal/?gw_id=%s

If server returned AUTH_VALIDATION_FAILED: Note that you will normally never see that one in the standard auth server. The client won't be redirected back to the gateway.

  • gw_message.php?message=failed_validation

Browser redirects by the auth server

Upon successfull login, the client will be redirected to the gateway.  http://" . $gw_address . ":" . $gw_port . "/wifidog/auth?token=" . $token

Example URL

Browser-gateway communication (not technically part of the protocol)

Manually logging out:

 http://%s:%d/wifidog/auth?logout=1&token=%s", Example: