Version 27 (modified by benoit, 15 years ago)


General FAQ

General questions about the Wifidog Captive Portal

Q: What is Wifidog ?

A: Wifidog is software used to create wireless hotspots. It is a next-generation alternative to  NoCat. For more details and history, visit the About WiFiDog page.

Q: Who develops Wifidog ?

A: The technical team of  Île Sans Fil started the Wifidog project. A few are still active, and others have joined from around the world.

Q: Who can use Wifidog ?

A: On the legal/licensing front, anyone can use Wifidog. It is free software released under the GPL license.

On the practical front, we would like the answer to also be "everyone", however this would not be the truth. The main target user base of Wifidog is network administrators, hotspot administrators and hackers who "know what they're doing". Odds are that an average end-user would not benefit from, or be able to correctly setup and continually administer a Wifidog installation.

If the software ever reaches a point of complete point-and-click ease that we feel average users can safely administer, we will update this document.

Q: Who currently uses Wifidog ?

A: Please go to the Community page

Q: What can it do ?

A: See the Features page for the feature list.

Q: What is it composed of ?

A: It is composed of 2 components:

  1. The client is a daemon process - this gets installed on every wireless router
  2. The auth server is a web application - this gets installed in a central location

Q: What are the main differences between it and NoCat ?

A: On the client side, it's smaller, has far fewer dependencies, and runs well on embedded devices. On the auth server side, it's more customizable, and is geared towards capitalizing the infrastructure for the purposes of building portals and communities.

Q: How does it work ?

A: The client daemon uses firewall rules to control traffic going through the router. When a new user tries to access a web site, the client will transparently re-direct them to the auth server where they can either log-in or sign-up. The client and the auth server then negotiate what to do with the client and either allow or deny them certain network access.

The client also talks to the auth server every X minutes to update it on vital statistics including uptime, load, traffic count per client, and to let it know it's still there.

Refer to the Wifidog Flow Diagram document for some more details.

Q: What does it run on ?

A: The client runs on any Linux machine that has a working netfilter+iptables installation. The auth server runs on any PHP-enabled web server.

Q: Does my system have to have a wireless card to use wifidog or just a wireless router?

A: You don't need a wireless card directly in the machine running the gateway (client). But every wireless (or wired) clients the gateway is to manage must be bridged at layer 2 to the ethernet interface wifidog is configured to gate (GatewayInterface?). In practice, it means that the wireless router must be used as a pure access point by connecting a LAN port (NOT the WAN port) to the interface on the machine running the gateway.

Q: Can I write my own client ?

A: Sure, but why ? We've done all the work. The client is written in C and is extremely lightweight so that it runs comfortably in embedded environments such as the Linksys WRT54G router.

The client is time-tested and is fairly stable. It is used extensively in Île Sans Fil's  deployed hotspots.

Q: Can I write my own auth server ?

A: Again, we've done all the work. However if you feel that our offering does not suite your needs and you wish to write your own server from scratch, you'll have to respect the same protocol the client uses for the whole system to work correctly.

Q: What does it look like ?

A: The client is a daemon process that runs in the background. It has no immediately viewable user interface as far as end-users are concerned. It does however offer a simple command-line and web-based interface for administrators to query it's status.

The auth server is a web application that can be customized via templates to look however you want it to look. To check out Île Sans Fil's auth server installation see

For a few screenshots visit Screenshots

Q: Where can I find help ?

A: Help is available through several real-time and non-realtime means listed at Contact / Support

If you need technical help with your WiFiDog installation, your message should include :

  • Your Wifidog client version (ipk or your own compiled version)
  • Configuration setup (wifidog.conf, please remove default config)
  • Wifidog debug output messages (command : wifidog -f -d 7).

Q: Can I use wifidog to run a splash-only hotspot (No authentication)?

A: Yes, just set each of your nodes "Splash only" (must be enabled in the network configuration page).

Q: Can I run the wifidog gateway alone (without a auth server)?

A: No, that is not what wifidog is designed for. You can try NoCatSplash, which was designed for this purpose.

Q: Does wifidog support RADIUS, WISPr or WPA

A: See doc/developer/WiFiDogRadiusWISPr

Gateway FAQ

Questions about the Wifidog gateway

Q: What are the requirements to run the gateway ?

A: The gateway requires the following:

  1. The  linux operating system
  2.  Netfilter compiled into the linux kernel
  3. The  iptables package

Also optionally for bandwidth throttling:

  1. The  iproute2 package, specifically the tc binary

Q: How do I install it ?

A: See the gateway installation instructions

Q: How do I install it on the Linksys WRT54G family of routers ?

A: See the specific WRT54G gateway installation instructions

Q: I can logon, but when I click the start button I am sent back to the logon screen !

A: Make sure that the ipt_mac.o kernel module is loaded. This is an optional part of the iptables packages and it is not always enabled by default. On most Linux distributions, kernel modules are configured in "/etc/modules.conf" or "/etc/modules".

Auth-Server FAQ

Questions about the Wifidog Auth-Server

Q: What are the requirements to run the Auth Server ?


  • A web server : Apache, IIS...
  • The PHP 5 module for you web server
  • PostgreSQL >= 7.4

Depending on the features you need to enable, you'll need :

  • The PHP DOM extension for the RSS support
  • PEAR Radius for RADIUS authentication support
  •  Phlick API for Flickr content ( Content management system )

Q: Can I use MySQL instead of PostgreSQL ?

A: No. The decision has been made, MySql? will not be supported. The burden of supporting both and maintaining quality would be huge; this isn't your simple web app or CMS. If you want to know more, there are long threads in the mailing list archive.

Q: The CMS is too complex, I simply want to put some HTML code on the portal page !

A: We are aware that we will need to provide a better documentation. Although, the answer to this specific question is quite easy. You would simply need to use a "TrivialLangstring?" content and drop some HTML code in the textfield and ties this content to the portal page.

Q: Can I extract the hotspot status data in XML format ?

A: Yes, the hotspots status list can be exported to a XML. In fact, the Google Maps mashup part of Wifidog relies on this feature.  Île Sans Fil is also using it to create a specially formatted display on its main website using  an XSL stylesheet.

Q: My auth server used to be fast, but now it's slower and slower, even under no load

A: You have to:

  1. Run VACUUM ANALYZE often from a script (it's a very cheap, non-locking operation, and considering wifidog's very write-heavy SQL mix, running it every hour isn't excessive).
  2. Make sure the above script works.
  3. If you see your auth server getting progressively slower, run VACUUM FULL ANALYZE once, and GO TO STEP 2.

Explanation: If you run VACUUM ANALYZE regularily (every night or every hour) you shouldn't need VACUUM FULL ANALYZE. However, if you haven't run VACUUM ANALYZE for a long time, you have to run VACUUM FULL ANALYZE once.

What happens is that without VACUUMing the connection and node tables grows and grows (because they are written to frequently, and postgres being a true ACID database, keep past versions of tuples to insure read consistency). Simply vacuuming doesn't reclaim the space used by old tuples, it just makes them available for reuse. If you haven't run VACUUM in a long time, you probably have millions of free tuples that you would, never, ever use up in a single day. VACUUM FULL ANALYZE fixes that. You must also run VACUUM once every two billions transactions in order to avoid causing the transaction id (XID) counter to wraparound -- for more information, see the PostgreSQL docs on  routine database maintenance.

An alternative to running periodic VACUUMs is to enable the  autovacuum daemon in recent versions of PostgreSQL: then PostgreSQL will automatically vacuum the database when it would be appropriate.

Q: There are error messages displayed on the portal pages

A: Check out Common error messages displayed on the auth server.

Q: French & Japanese characters are corrupted on the portal pages

A: Make sure config.php has the proper locale settings (see the comments in config.php) You may also need to specify Apache's default charset by adding this line in your httpd.conf:

AddDefaultCharset UTF-8