Tech, Gadgets, Photography, Social Media and Poor Spelling

Captive Portal Using PHP and iptables Firewall on Linux

Captive Portal Using PHP and iptables Firewall on Linux

This experiment will show you, how to build a simple captive portal using PHP and iptables on Linux Ubuntu.

Most linux commands used in this experiment are suitable for Debian based Linux (just like what I use in this experiment, Ubuntu Linux). Some of them may have slight differences to be implemented on any other non-Debian-based Linux distros such as Centos, RHEL, or OpenSUSE.

Warning! I’m not responsible for any damages to your computer and/or your computer network configuration that caused by following this experiment. Do this AT YOUR OWN RISK! Use this article as educational and/or experimental purpose only. This articles is not intended for production use nor public use. But if you found any information in this article is useful, I will be very grateful.

First, here the basic concepts on how the captive portal works:

  1. Every user which is connected to the wireless hotspot are connected to the internet through a gateway.
  2. The gateway itself acts as a router and a firewall (and probably also acts as a portal webserver just like in this experiment).
  3. Every HTTP data packet destined to the internet from unauthenticated users are “marked” with a special code by the firewall so it can be intercepted (redirected) to the portal webserver.
  4. Portal webserver serves an authentication web page to the user transparently and identify the computer used by them.
  5. The user accept/authenticates themself with the webserver so their computer identity (in this case their network interface MAC address) are being entered into firewall’s whitelist.
  6. As long as user’s network interfaces are inside the firewall’s whitelist, packets sent from them are not marked for intercepting. The packets are then forwarded by the router to the internet without being intercepted again to the web portal.

In this experiment I uses:

  • An Ubuntu 10.10 x86 Desktop Linux box. I prefer GUI while experimenting rather than a single workspace on Ubuntu Server.
  • Dual Core Intel CPU with 2GB of RAM.
  • Two network interfaces, one for the main internet connection, and one for the public accessible hotspot. Yes, you need at least two network interfaces to do this experiment.
  • The software itself for building the captive portal:
    • iptables, the common firewall
    • Apache2 web server, with PHP5 installed
    • MySQL server, for managing user credentials (for authenticative portal)
    • dhcp3-server as DHCP server and bind9 as DNS server, so users don’t have to configure their computer  network configuration manually when they are connected to the hotspot. But I will not explain about how to configure these servers further.
    • Plus, I uses Panada PHP Framework to make web portal development much easier.

In this point forward, if you’re following to practices this articles I assumes that you already have an ubuntu box installed and ready to use and all the required packages as well.

1. Build a linux box router

Configuring the network interfaces

I have two network interfaces, eth0 and eth1. eth0 is connected to the internet, and eth1 is connected to the hotspot access point LAN. I have this configuration on /etc/network/interfaces file:

# file: /etc/network/interfaces auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp

auto eth1
iface eth1 inet static

The eth0 is connected to the internet and it’s IP address is assigned by DHCP by the network. You may have to configure it manually if it’s IP address is not assigned by DHCP. However the network interface (eth1) which is connected to the hotspot LAN has IP address on network. This will be going to be the portal IP Address and acts as user’s gateway IP address.

You may edit the /etc/network/interfaces file by using nano or vi from command line as root. Change your network configuration to match your network settings, save the file and restart the networking services by issuing the following command to apply changes:

$ sudo /etc/init.d/networking restart

Enable IP forwarding (routing) on Linux Ubuntu so every packets from the hotspot are forwarded to the internet

Enable the IPv4 packet forwarding by uncommenting the following line on /etc/sysctl.conffile

# Uncomment the next line to enable packet forwarding for IPv4
Masquerade any incoming packet on the firewall, using the following command:
$ sudo iptables -A POSTROUTING -t nat -o eth0 -j MASQUERADE 

At this point, any other computer connected to the hotspot (eth1) which is using your computer as gateway ( are able to connect to the internet through your computer internet connection (eth0).

2. Build a (captive) portal

Capturing user IP and MAC address

a “splash” page is used for capturing the user IP and MAC address and display the page to user when they were redirected to this page by the portal system.

Here’s an example on how to capture user’s IP and MAC address using PHP:

<?php // capture their IP address $ip = $_SERVER['REMOTE_ADDR']; // this is the path to the arp command used to get user MAC address // from it's IP address in linux environment. $arp = "/usr/sbin/arp"; // execute the arp command to get their mac address $mac = shell_exec("sudo $arp -an " . $ip); preg_match('/..:..:..:..:..:../',$mac , $matches); $mac = @$matches[0]; // if MAC Address couldn't be identified. if( $mac === NULL) { echo "Access Denied."; exit; } ?> 

From the example above, user’s IP and MAC address are stored in variables $ip and $mac respectively. For getting their MAC address, we uses ‘sudo /usr/sbin/arp -an’ command. Please note that for this command to work, the linux user ‘www-data’ (default user for Apache webserver daemon’) must be in the sudoers file.

Add www-data as sudoers in linux box

First, you have to be root to add user as sudoers. Execute this command:

$ sudo visudo

Then add the following line at the bottom of the file, so that www-data user can execute arp command without entering a password

www-data ALL=NOPASSWD: /usr/sbin/arp

Save the file.

Create a simple HTML form for user to submit (and agree the portal Terms of Service if any).

Here’s an example of the form in PHP:

<form method="post" action="process.php"> <input type="hidden" name="mac" value="<?php echo $mac; ?>" /> <input type="hidden" name="ip" value="<?php echo $ip; ?>" /> <input type="submit" value="OK" style="padding:10px 20px;" /> </form>

User’s IP and MAC address are embedded in the form as hidden field for further processing in the firewall. Save the file with name index.php in the document root directory of your web portal. So now it’s accessible from a web browser. Try http://localhost or your linux box web browser to test the portal page as we will redirect user to this address.

Redirecting every “unknown user” HTTP traffic to the “splash” portal

I uses a similiar logic as explained by Andy Bev in his wiki but with some little differences. Here’s the command on how to redirect every HTTP traffic to portal using iptables. PLease note that you have to be root in order to be able to modify the iptables table.

1. Create a new chain named ‘internet’ in mangle table with this command

sudo iptables -t mangle -N internet

2. Send all HTTP traffic from eth1 to the newly created chain for further processing

sudo iptables -t mangle -A PREROUTING -i eth1 -p tcp -m tcp --dport 80 -j internet

3. Mark all traffic from internet chain with 99

sudo iptables -t mangle -A internet -j MARK --set-mark 99

4. Redirect all marked traffic to the portal 

sudo iptables -t nat -A PREROUTING -i eth1 -p tcp -m mark --mark 99 -m tcp --dport 80 -j DNAT --to-destination

OK from now on, every HTTP request from eth1 will be redirected to the portal page.

Bypass firewall redirection rules when users submit themself from the splash page

When user click the submit button from the portal splash page, their IP and MAC address will be submitted to the process.php file. In this file their MAC address will be “entered” into iptables firewall so that they won’t be redirected to the portal splash page anymore. The logic is, executing the following command from PHP (process.php) so that the redirection logic in the firewall will be bypassed:

sudo iptables -t mangle -I internet 1 -m mac --mac-source USER-MAC-ADDRESS-HERE -j RETURN

And remove their “redirection” connection track. How? From Andy Bev wiki, we can do that with a simple script.
Create an executable file /usr/bin/rmtrack and put the following code inside

/usr/sbin/conntrack -L  |grep $1  |grep ESTAB  |grep 'dport=80'  |awk  "{ system("conntrack -D --orig-src $1 --orig-dst "  substr($6,5) " -p tcp --orig-port-src " substr($7,7) "  --orig-port-dst 80"); }"

Change the file permission to 755 or 700 for better safety with the following command:

$ chmod 755 /usr/bin/rmtrack

With those rmtrack, we can remove user’s connection track with the following command

$ sudo rmtrack USER_IP_ADDRESS

Here’s an example of process.php file:

<?php if( isset( $POST['ip'] ) && isset ( $_POST['mac'] ) ) { $ip = $_POST['ip']; $mac = $_POST['mac']; exec("sudo iptables -I internet 1 -t mangle -m mac --mac-source $mac -j RETURN"); exec("sudo rmtrack " . $ip); sleep(1); // allowing rmtrack to be executed // OK, redirection bypassed. // Show the logged in message or directly redirect to other website echo "User logged in."; exit; } else { echo "Access Denied"; exit; } ?>

Don’t forget to add the following line to the sudoers file so that the iptables and rmtrack command can be executed by the web server:

www-data ALL=NOPASSWD: /sbin/iptables www-data ALL=NOPASSWD: /usr/bin/rmtrack [0-9]*.[0-9]*.[0-9]*.[0-9]*

After the user had been logged in, they won’t be redirected to the portal again because of the iptables bypassing rules command. That’s it! Congratulations, A (very simple) captive portal using PHP and iptables has been successfully created.

How to remove the user from the iptables bypassing rules so that they have to be authenticated again?

Here’s on how to do it. Delete user’s bypassing iptables rules with the following command:

sudo iptables -D internet -t mangle -m mac --mac-source USER_MAC_ADDRESS -j RETURN

and remove their connection track (again):

sudo rmtrack USER_IP_ADDRESS

if you know user’s IP address, both command can be easily done by a simple PHP script below:

<?php // get the user IP address from the query string $ip = $_GET['ip']; // this is the path to the arp command used to get user MAC address // from it's IP address in linux environment. $arp = "/usr/sbin/arp"; // execute the arp command to get their mac address $mac = shell_exec("sudo $arp -an " . $ip); preg_match('/..:..:..:..:..:../',$mac , $matches); $mac = @$matches[0]; // if MAC Address couldn't be identified. if( $mac === NULL) { echo "Error: Can't retrieve user's MAC address."; exit; } // Delete it from iptables bypassing rules entry. while( $chain = shell_exec("sudo iptables -t mangle -L | grep ".strtoupper($mac) ) !== NULL ) { exec("sudo iptables -D internet -t mangle -m mac --mac-source ".strtoupper($mac)." -j RETURN"); } // Why in this while loop? // Users may have been logged through the portal several times. // So they may have chances to have multiple bypassing rules entry in iptables firewall. // remove their connection track. exec("sudo rmtrack " . $ip); // remove their connection track if any echo "Kickin' successful."; ?>

Save it to a file named kick.php in your web server document root. Get into your web browser and put the following URL to the address bar to kick someone from the iptables bypassing rules:

And you’re DONE!

Feel free to modify the code to suit your requirements or asks something you don’t understand in making this (very simple) captive portal. I’ll try to answer and explain if I able to.

9 comments on “Captive Portal Using PHP and iptables Firewall on Linux

  1. Peter B.
    October 16, 2012

    If you use visudo and add www-data with /usr/bin/arp, you don’t need “sudo” before the “/usr/sbin/arp -an” in the splash php. If you add “sudo”, the command doesn’t give any result.

  2. peter89x
    October 16, 2012

    I had to say thanks, because I use this tutorial – and I have to say, it works nice! 🙂 I modified your code according to my project, and it’s still great.
    So – thank you! 🙂

    • projectzme
      October 16, 2012

      I’m just happy someone read something I put together.

  3. peter89x
    October 16, 2012

    Well, I find something more.
    In the rmtrack-part, inside the awk’s quotation marks, you have to put a \ symbol before every quotation mark and string symbol (except $1).
    So, in the proper way the awk-stuff looks like this:
    awk “{ system(\”conntrack -D –orig-src $1 –orig-dst \” substr(\$6,5) \” -p tcp –orig-port-src \” substr(\$7,7) \” –orig-port-dst 80\”); }”

  4. Ninad
    February 18, 2013

    After Successful authentication or ip-mac registration how do i redirect user to it’s original url. I am using iptables & php.

    • projectzme
      February 18, 2013

      If the ip tables are setup correctly then any registered device should forward to the original URL.

  5. Jonas
    April 2, 2013

    In wich way do I have to modify this, if I want to let other other services (like SSL) pass thought the captive portal? So I mean everything is blocked until the user enters his credentials and not only port 80?

    • projectzme
      April 2, 2013

      There is a line specifying port 80 on the instructions which reads

      sudo iptables -t mangle -A PREROUTING -i eth1 -p tcp -m tcp –dport 80

      The dport (destination port) is being set to port 80

      You could set dport to 443 for https or 22 for ssh

      So do 1 to 4 again but this time maybe step one call the chain secure, step two dport 443, step 3 tag with 97 and complete with the new information step 4

      Does that makes sense?

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s


This entry was posted on March 19, 2012 by in link and tagged , , , , , .
%d bloggers like this: