A captive portal is a web page accessed with a web browser that is displayed to newly connected users of a Wi-Fi network before they are granted broader access to network resources.
To determinate if a captive portal has to be display and ask to passenger an action, a phone (Android or iOS) calls some APIs. When this API sends:
To determinate if a captive portal has to be display and ask to passenger for an action, a device (personnal computer, phone or tablet of both Android and iOS) calls some APIs. When this API sends:
* 204 HTTP Code: device has connectivity nothing to do.
* 302 HTTP Code: device maybe have connectivity but passenger has to signin.
* 302 HTTP Code: device may have connectivity but passenger has to signin.
* _No answer_: device don't have connectivity but device doesn't known what to do
The goal of PXPortal is to simulate captive portal APIs from different constructors by answering required HTTP codes.
__WARNING__
The behavior describes here is experimental. Such as every phone constructor implements its own API or internal mechanism, this solution cannot work on all phones (for example some Samsung, ...). The list of captive API will be updated over time.
The behavior describes here is based on experimentation as devices do not properly disclose their logic. As each phone constructor implements its own API or internal mechanism, this solution may not work on all phones (for example the behavior of last Samsung release is different). The list of captive API will be updated over time.
# PXPortal
PXPortal is composed of three services:
* nginx: a web server which can also be used as a reverse proxy, load balancer, mail proxy and HTTP cache
* dnsmasq: provides Domain Name System (DNS) forwarder, Dynamic Host Configuration Protocol (DHCP) server, router advertisement and network boot features for small computer networks, created as free software
* portal_service: internal PXCom service to simuate captive portal API
* nginx: a web server which can also be used as a reverse proxy, load balancer, mail proxy and HTTP cache
```{#plantuml title="Device without internet but pxportal enabled"}
@ -49,7 +49,7 @@ participant Portal_Service
Device -> Box: connectivitycheck.google.com
Box -> Dnsmasq: Whois google.com
Dnsmasq --> Box: server
Dnsmasq --> Box: server's IP
Box -> Nginx: connectivitycheck.google.com
Nginx -> Portal_Service: Is a validated mac address
To have a validated mac address, a passenger has to accept terms of use on portal webpage. On this action, a request is sent to portal_service which will save in memory the mac address as a valid one. Next time, passenger will be considered as a valid user and no new signin notification will be shown.
To have a valid mac address, a passenger has to accept terms of use on portal webpage. On this action, a request is sent to portal_service which will save in memory the mac address as a valid one. Next time, passenger will be considered as a valid user and no new signin notification will be shown.
```{#plantuml title="Device without internet but pxportal enabled"}
participant Device
@ -75,13 +75,13 @@ Portal_Service --> Device: OK
\clearpage
## PXPortal - Dnsmasq
## PXPortal - DNSmasq
* redirects all captive portal API to the box. With the following configuration, PXPortal can handles Android and iOS phones and some linux.
* _(optional)_ can provide a DHCP server (not used here)
```bash
#ANDROID
#ANDROID
address=/google.com/10.0.0.254
address=/.google.com/10.0.0.254
address=/gstatic.com/10.0.0.254
@ -132,11 +132,11 @@ server {
}
```
## PXPortal - Portal_Service
## PXPortal - PortalService
* is a server HTTP based on NodeJs and ExpressJs
* simulates captive portal APIs
* saves validated mac addresses on _/validate_ call. It's saved in memory that's mean, it's cleared on one service restart
* saves validated mac addresses on _/validate_ call. It's saved in memory that means, it is cleared on a service restart
* performs an ARP command to find mac address from IP client
@ -153,7 +153,7 @@ Before continuing, be sure [docker](https://docs.docker.com/install/linux/docker
Such as portal_service requires MAC addresses thanks to ARP command. But from one docker context, the command has to execute from the host in order to get MAC addresses from IP clients. This is _how to do this_ in few steps
Such as portal_service requires MAC addresses thanks to ARP command. But from a docker context, the command has to execute from the host in order to get MAC addresses from IP clients. This is _how to do this_ in few steps
### 1. Generate a docker SSH Public key
@ -219,14 +219,15 @@ Such as portal_service requires MAC addresses thanks to ARP command. But from on
# Launch portal_service shell
docker exec -it pxportal_service sh
###On portal_service shell
###On portal_service shell
# Generate a SSH key to be able to send ARP command from docker to host
ssh-keygen
# Display and copy ssh public key
cat /root/.ssh/id_rsa.pub
### Exit portal_shell
# Edit HOST ssh authorized_keys and paste previous ssh public key of portal_service
### Exit portal_shell
# Edit HOST ssh authorized_keys
# and paste previous ssh public key of portal_service
vi ~/.ssh/authorized_keys
```
@ -237,26 +238,27 @@ vi ~/.ssh/authorized_keys
# Launch portal_service shell
docker exec -it pxportal_service sh
###On portal_service shell
###On portal_service shell
# Show all network interfaces available
ifconfig
# Keep in memory the inet addr of eth0
# HOST IP address from docker should be this IP address by remplacing last number by 1
# HOST IP address from docker should be this IP address
# by remplacing last number by 1
# EX: 172.20.0.2 => 172.20.0.1 = HOST_IP
# Check your ssh public key is set correctly and update known_hosts on first SSH connection
# Check your ssh public key is set correctly
# and update known_hosts on first SSH connection
ssh [HOST_NAME]@[HOST_IP]
# EX ssh elta@172.20.0.1
#Check ARP command can be run
#Check ARP command can be run
ssh [HOST_NAME]@[HOST_IP] arp -n
#A list of IP with matching MAC will be appeared
#If not, try again from the beginning
#A list of IP with matching MAC will be appeared
#If not, try again from the beginning
```
### 3. Update docker-compose.yml ARP_CMD
Update the environment variable __ARP_CMD__ in _your docker-compose.yml_ with the right HOST_NAME and HOST_IP found in step 2.
```bash
# Go into ECA-captive folder
cd ECA-captive
@ -417,3 +419,5 @@ By default, PXPortal uses Cisco DHCP.
