Skip to content
This repository


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
100644 64 lines (51 sloc) 3.133 kb
6b8aff9b »
2012-06-01 adding some docs
2 # How it works
4 pfSense has a captive portal service that will capture all packets
5 unless you are authorized. It will capture any HTTP requests and
6 redirect you to a special page served by pfSense (see
7 pfsense/portal.php). However, this page simply uses pfSense functions to
8 map your requesting IP to a MAC address. Then it takes this MAC address
9 and the URL you were trying to go to, base64 encodes them, and passes
10 that information to an App Engine app via redirect.
12 The App Engine app serves a page that lets members login for full
13 access, or lets guests get a daypass or use the guest network. This app
14 keeps this state for pfSense to check if you are authorized.
16 The way pfSense finds out if you are authorized is using a RADIUS
17 server. This is the only workable option pfSense gives us. So we have a
18 "fake" RADIUS server running on pfSense (see pfsense/ that
19 takes authorization packets and checks with the App Engine app if that
20 MAC is authorized. It keeps a local cache and has a fail over mechanism,
21 but otherwise it's just a bridge to let us do authorization with the App
22 Engine app that has that state.
24 The App Engine app has some tricky logic that is worth pointing out.
25 When you login as a member, it will authorize against Google Apps. This
26 may return a captcha challenge, which we have to pass on to the user. If
27 they successfully login, we create a Login record and a
28 MacAddressMapping. Recall, the MAC address was passed in from the
29 pfSense captive portal PHP page. The app actually stores this in a
30 cookie for easy access later.
32 Now that there is a MacAddressMapping (and there can only be a limited
33 number of mappings per member), when the RADIUS bridge asks if a MAC
34 address is authorized, we lookup the MacAddressMapping, make sure the
35 member is not suspended, then authorize by returning 200 and some
36 configuration that's passed back to pfSense (namely bandwidth
37 limitations).
39 The app handles guest logins slightly differently. When you connect as a
40 guest, daypass or not, we do not use a MacAddressMapping, but a simple
41 memcache key using the MAC address as the key. This makes it easy to
42 expire and keeps member mappings separate from guest mappings. When a
43 guest purchases a day pass, we set the value to signify they are a
44 day pass user. Otherwise, we signify they are just a guest.
46 So when the RADIUS bridge asks the app if a MAC is authorized, it will
47 first check memcache to see if they are a guest or day pass holder
48 before checking for member MacAddressMappings. It will return
49 appropriately depending on which they are, including their bandwidth
50 limitations.
52 # Debugging
54 ## Resetting your device
56 If you logged in as a guest, you can just go to the root path (/) of the
57 App Engine app and it will clear your cookie and its memcache record of
58 you. If you are logged in as a member, you will have to use the App
59 Engine admin to delete the MacAddressMapping record.
61 In either case, you will also have to remove a record from pfSense under
62 Status > Captive Portal. Then you should be reset. You have to delete
63 both the record in App Engine and pfSense for reset to happen correctly.
Something went wrong with that request. Please try again.