###################
Captive Portal
###################

Captive portals are primarily used in open wireless networks where the users are shown a welcome message informing them of the conditions of access (allowed ports, liability, etc.).

Access to the Internet over open Wi-Fi is prohibited until the user exchanges personal data by filling out a web-based registration form in a web browser.


There are 3 softwares which provide Captive Portal capabilities

	#. WifiDog
	#. NoDogSplash
	#. Coova-Chilli


WifiDog
########

WifiDog consists of 2 parts :

	#. Gateway (Client Daemon)
	#. Auth Server

Gateway (Client Daemon)
	It runs on embedded hardware, e.g. the hotspot itself. It is responsible for redirecting the user to the auth server for authentication.

Auth Server
	It is a simple server designed in php & mysql which is responsible for authentication of the user.

WifiDog Gateway is flexible enough to work with many auth servers as long as they use the WifiDog Protocols.

List of Auth Servers which work with WifiDog are:

#. wifidog-auth-laravel - https://github.com/wifidog/wifidog-auth-laravel
#. wifidog-auth - https://github.com/wifidog/wifidog-auth
#. AuthPuppy - https://www.openhub.net/p/authpuppy 

*********************
WifiDog Installation
*********************

Installing Gateway ( Client Daemon )
-------------------------------------

What do I need ?
~~~~~~~~~~~~~~~~

A GNU/Linux OS with netfilter compiled into the kernel
The iptables package
The GNU C compiler (gcc).
The latest Wifidog tarball which can be obtained from 
* SourceForge -https://sourceforge.net/projects/wifidog/
* GitHub - https://github.com/wifidog/wifidog-gateway

Pre-installation
~~~~~~~~~~~~~~~~~

This is where a lot of people run into problems.

*MAKE SURE EVERYTHING GIVEN BELOW WORKS FIRST BEFORE INTRODUCING Wifidog INTO THE ENVIRONMENT*


#. 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.
#. The ipt_mac.o kernel module must be loaded.
#. 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 all the above conditions. It will not work otherwise and you will waste lots of time.

Installation
~~~~~~~~~~~~~
Follow these command for installation :

.. code-block:: shell
   :linenos:

	$ git clone https://github.com/wifidog/wifidog-gateway.git
	$ cd wifidog-gateway
	$ ./autogen.sh
	$ make
	$ sudo make install

Configuration
~~~~~~~~~~~~~~

The WifiDog will get installed in /usr/local directory
To configure WifiDog run these commands

.. code-block:: shell
   :linenos:

	$ sudo mkdir -p /usr/local/etc
	$ cp -dpRv wifidog.conf /usr/local/etc/
	$ touch /usr/local/etc/wifidog.conf
	$ cat <<EOF > /usr/local/etc/wifidog.conf 
	# WiFiDog Configuration file
	GatewayInterface wlan0

	AuthServer {
	    Hostname authpuppy.lan
	    SSLAvailable no
	    Path /
	}


	FirewallRuleSet global {

	    FirewallRule block tcp port 25

	    ## Use the following if you don't want clients to be able to access machines on
	    ## the private LAN that gives internet access to wifidog.  Note that this is not
	    ## client isolation;  The laptops will still be able to talk to one another, as
	    ## well as to any machine bridged to the wifi of the router.
	    FirewallRule block to 192.168.0.0/16
	    FirewallRule block to 172.16.0.0/12
	    FirewallRule block to 10.0.0.0/8

	    FirewallRule allow tcp to iotiot.in

	    ## Use the following if you are having problems with Apple iOS 7 clients.
	    ## See #7 and #14 at https://github.com/wifidog/wifidog-gateway/issues/
	    #FirewallRule allow tcp to apple.com
	    #FirewallRule allow tcp to icloud.com

	}

	FirewallRuleSet validating-users {
	    FirewallRule allow to 0.0.0.0/0
	}

	FirewallRuleSet known-users {
	    FirewallRule allow to 0.0.0.0/0
	}

	FirewallRuleSet unknown-users {
	    FirewallRule allow udp port 53
	    FirewallRule allow tcp port 53
	    FirewallRule allow udp port 67
	    FirewallRule allow tcp port 67
	}

	# Rule Set: locked-users
	#
	# Not currently used
	FirewallRuleSet locked-users {
	    FirewallRule block to 0.0.0.0/0
	}
	EOF

Open and edit configuration as per requirement.

Change configuration 

GatewayInterface br-lan

to 

GatewayInterface wlan0 (i.e interface which is connected to the internet)

Testing 
~~~~~~~~
It will not work if auth server is not installed. 
Install auth server first.

Run Command 

.. code-block:: shell
   :linenos:

	$ wifidog -f -d 7


Then connect to the network as a client and try to browse google 
Captive Portal should open up.


Installing Auth Server ( AuthPuppy )
------------------------------------

What do I need ?
~~~~~~~~~~~~~~~~

#. PHP
#. Lighttpd or Apache or Ngnix or any good webserver
#. Mysql

Pre-installation
~~~~~~~~~~~~~~~~~
Install required packages using opkg

.. code-block:: shell
   :linenos:

   $ sudo opkg install lighttpd php mysql5


Installation
~~~~~~~~~~~~~
Follow these command for installation :

.. code-block:: shell
   :linenos:

	$ wget https://launchpad.net/authpuppy/trunk/1.0.0-stable/+download/authpuppy-1.0.0-stable.tgz
	$ tar -xvzf authpuppy-1.0.0-stable.tgz
	$ cp -dpRv authpuppy /www/pages/
	$ sudo chown -R www-data:www-data /www/pages/authpuppy

Lighttpd Configuration
~~~~~~~~~~~~~~~~~~~~~~~~

Create Virtual host for authpuppy

.. code-block:: shell
   :linenos:

	$ touch /etc/lighttpd.d/authpuppy.conf
	$ cat <<EOF > /etc/lighttpd.d/authpuppy.conf
	$HTTP["host"] =~ "(^|www\.)authpuppy\.lan$" {
		server.document-root = "/www/pages/authpuppy/web"
		server.error-handler-404 = "/index.php"
	}
	EOF
	$ echo "127.0.0.1 authpuppy.lan" | sudo tee -a /etc/hosts


Mysql Configuration 
~~~~~~~~~~~~~~~~~~~~
Create a MSQL User & Database for authpuppy

.. code-block:: shell
   :linenos:

   $ sudo systemctl restart mysqld
   $ mysql -u root
   mysql > GRANT ALL PRIVILEGES ON *.* TO 'authpuppy'@'localhost' IDENTIFIED BY 'put-your-password-here';
   mysql > \q
   $ mysql -u authpuppy -p
   # Enter the mysql password
   mysql > CREATE DATABASE authpuppy-db;

This will create

#. User with username = authpuppy
#. User with password = put-your-password-here
#. Database with name = authpuppy-db