Version 3 (modified by benoitg, 13 years ago)

Partially reformat the FAQ

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.

Q: Who makes Wifidog ?

A: The technical team of  Île Sans Fil created and maintains Wifidog.

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 windows 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: 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 our auth server at the time of this writing is not as polished as the client. Feel free to make it better or write your own from scratch. If you go with the later option 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 looks like zen, chi, the ether, zilch. It has no user interface.

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  https://auth.ilesansfil.org

Q: Where can I find help ?

A: If you've read the documentation, browsed the FAQ, tested a configuration setup (try your best) and you're still experiencing issues with your setup. You can find help by posting your question to the Wifidog mailling listexternal link (make sure you search through the mailing list archiveexternal link before you do so).

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).

Client FAQ

Questions about the Wifidog client (not embedded)

Q: What do I need ?

A:

  1. Basic proficiency in a Linux environment
  2. A Linux OS with netfilter compiled into the kernel
  3. The iptables package
  4. The GNU C compiler (gcc). Other compilers may work, but we have not tested and will not support them.
  5. The latest Wifidog tarball which can be obtained from  SourceForge

Q: Pre-installation

A: This is where a lot of people run into problems, so let's state this in bold:

MAKE SURE EVERYTHING WORKS FIRST BEFORE INTRODUCING Wifidog INTO THE ENVIRONMENT

That especially means:

  • The router must boot properly
  • The router must bring up the interfaces properly
  • The router must set up the routes properly
  • The router must connect to the internet properly
  • DNS settings must be set or obtained properly. DNS must work.
  • DHCP settings (client, server or both) must be set or obtained properly.
  • If using NAT, the router must setup NAT/masquerading rules with iptables properly
  • Clients on the desired (WIFI) network must be able to bind, associate, lease and connect the internet properly
  • All the above must happen automatically when the router starts or gets rebooted

Do NOT proceed with installing Wifidog until you've satisfied the above. It will not work otherwise and you will waste lots of time.

Q: Installation

A: Wifidog, like many open source projects, is distributed with standard autotools utilities to make installation easy. Unpack the tarball, then follow the standard:

./configure
make
make install

Q: Configuration

A: Edit /etc/wifidog.conf and follow the instructions in the file. Things should be self-explanatory.

Q: Running Wifidog for the first time

A: Run Wifidog with the following switches:

wifidog -f -d 7
  -f means to run in foreground (do not become a background daemon)
  -d 7 increases debug output level to the maximum

Q: Testing

A: As a client on the WiFi network (or whatever interface is configured as the LAN interface in /etc/wifidog.conf), open a web browser and try to browse to your favourite web site.

Monitor the output of the running Wifidog to see what it's doing.

Client on a Linksys WRT54G FAQ

Due to the lightness of the Wifidog client it is often installed inside the linksys WRT54G. There are some profound issues that arise with this setup that it warrants its own section in this FAQ.

Q: What do I need ?

A: You will need to have basic/full proficiency in a Linux environment

You need to re-flash your router with a hacker-friendly firmware called  OpenWRT. Follow the  user guide on the OpenWRT site to get this part done.

Do not proceed until you've completed the above. We also recommend you spend some time familiarizing yourself with your new router's OS before introducing Wifidog into that environment. This especially includes the nvram settings, network interfaces and existing interface bridges.

Q: Pre-installation

A: The same rules apply as the pre-installation in a non-WRT54G environment above. Do not proceed until you've satisfied them. In summary: Make sure EVERYTHING works first.

Auth-Server FAQ

Questions about the Wifidog Auth-Server

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

A:

  • 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 in lieu of PostgreSQL ?

A: No, but we are looking for a developper committed to maintain the SQL code and port it to MySQL. Since MySQL is less feature rich than PostgreSQL we might have some trouble implementing some advanced stats / BLOB queries ...

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 ANALYSE often from a script (it's a very cheap, non locking operation, and considering wifidog's very write heavy SQL mix, runing it every hour isn't excessive).
  2. Make sure the above script works.
  3. If you see you auth server getting progressively slower, run VACUUM FULL ANALYSE once, and GO TO STEP 2.

Explanation: If you run VACUUM ANALYSE regularily (every night or every hour) you shouldn't need VACUUM FULL ANALYSE. However, if you haven't run VACUUM ANALYSE 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.