<!--
@docType    INTEGRATION
@docKey     PXEN310-0000_TN_PXPORTAL_INTEGRATION
@title      pxen310-0000_tn_pxportal_integration
@version    1.0.0
@author     P.BARRY
@brief      The document describes how to deploy the PXCom captive portal for embbeded network.
@email      pacome.barry@pxcom.aero
@reference  PXEN310-0000_TN_PXPORTAL_INTEGRATION
@history
1.0.0   11/06/19   P.BARRY   First release
@validations
Author    P.BARRY   11/06/19    
Control    [ControlName]   [Date]    
Approval    [ApprovalName]   [Date]    
-->

# Introduction

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 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 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 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:

* 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"}
participant Device
participant Box
participant Dnsmasq
participant Nginx
participant Portal_Service

Device -> Box: connectivitycheck.google.com
Box -> Dnsmasq: Whois google.com
Dnsmasq --> Box: server's IP
Box -> Nginx: connectivitycheck.google.com
Nginx -> Portal_Service: Is a validated mac address
alt Not Valid
  Portal_Service --> Nginx: Code 302 - Redirect to http://[PortalPage]
else
  Portal_Service --> Nginx: Code 204
end
Nginx --> Box: Portal_Service response
Box --> Device: Portal_Service response
```

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
participant Portal_Service

Device -> Portal_Service: http://captive.eca.aero/validate
Portal_Service -> Portal_Service: Flag MAC as valid
Portal_Service --> Device: OK
```

\clearpage


## 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
address=/google.com/10.0.0.254
address=/.google.com/10.0.0.254
address=/gstatic.com/10.0.0.254
address=/.gstatic.com/10.0.0.254
address=/android.com/10.0.0.254
address=/.android.com/10.0.0.254
# IOS
address=/apple.com/10.0.0.254
address=/.apple.com/10.0.0.254
# BROWSER
address=/firefox.com/10.0.0.254
address=/.firefox.com/10.0.0.254
# LINUX
address=/ubuntu.com/10.0.0.254
address=/.ubuntu.com/10.0.0.254
address=/gnome.org/10.0.0.254
address=/.gnome.org/10.0.0.254
```

## PXPortal - Nginx

* handles all requests sent to captive portal API and forwards them to our pxportal service,
* and serves portal webpages on _http://portal.eca.aero/index.html_ and _http://portal.eca.aero/ready.html_


```bash
server {
  server_name captive.eca.aero
  *.apple.com
  *.gstatic.com
  *.firefox.com                                                                                               
  *.ubuntu.com                                                                                                
  *.google.com                                                                                                
  *.android.com                                                                                               
  *.gnome.org; 

  location / {
    proxy_pass http://pxportal_service:8889/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-Ip $remote_addr;
    proxy_buffering off;
  }
}

server {
	server_name portal.eca.aero;
	root /data/webapp/portal;
}
```

## PXPortal - Portal Service

* 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 means, it is cleared on a service restart
* performs an ARP command to find mac address from IP client


\clearpage

# Deployment

PXPortal can be deployed with a docker-compose.

Before continuing, be sure [docker](https://docs.docker.com/install/linux/docker-ce/ubuntu/) and [docker-compose](https://docs.docker.com/compose/install/) are installed on your machine.


## First Run

### Clone ECA-captive repository

```bash
git clone ssh://gitolite@git.pxcom.aero:2221/ife/ECA-captive.git
```

This repository contains:

* __docker-compose.yml__: docker config of three PXPortal services
* __conf__: dnsmasq and Nginx configuration
* __webapp__: sources of portal webpage
* __setup.sh__: script to setup PXPortal


```{#plantuml title="ECA-captive tree"}
@startsalt
{
{T
+ECA-captive/
++ conf
+++ conf.d
++++ portal.conf
+++ dnsmasq.conf
+++ nginx.conf
++ docker-compose.yml
++ webapp
++ setup.sh
}
}
@endsalt
```

### 2. Running PXPortal for the first time

```bash
# Go into ECA-captive folder
cd ECA-captive
# Start all services in daemon mode
./setup.sh
```


### 3. Update PXPortal 

_(if updates are available)_

```bash
# Go into ECA-captive folder
cd ECA-captive
# Pull latest updated dockers
docker-compose pull
# Restart dockers
docker-compose up -d
```

\clearpage

## startup.sh

__startup.sh__ allows to:

* start PXPortal and perform some sanity checks
* setup ssh config and update environment varianles used by _docker-compose.yml_ file in order to execute arp commands from docker to host. (Required by portal_service to get MAC addresses from IP clients)
* check portal APIs are alive

\clearpage

```bash
#/bin/sh

check_ping () {
  echo "[-] ping $1"
  echo $1 | xargs ping -c 1 > /dev/null
  if [ "$?" -ne "0" ]
  then
    exit
  fi
}

check_wget () {
  echo "[-] wget $1"
  echo $1 | xargs wget -q -O out > /dev/null
  if [ "$?" -ne "0" ]
  then
    exit
  fi
}

check_docker () {
  local IS_RUN=$(docker ps | grep $1 | wc -l | xargs echo -n)
  if [ "$IS_RUN" -ne "1" ]
  then
    echo "/!\ Docker $1 is not running"
    echo "    Run following command for more details"
    echo "    docker-compose up"
    exit
  fi
}

faildMsg () {
  if [ "$1" -ne "0" ]
  then
    echo "---"
    echo "/!\ Setup Failed"
    echo "    $2"
    exit
  fi
}

getGateway () {
  local NETWORK_MODE=`docker inspect -f "{{ .HostConfig.NetworkMode }}" $1`
  docker inspect -f "{{ .NetworkSettings.Networks.$NETWORK_MODE.Gateway }}" $1
}

echo "[>] Starting PXPortal"
docker-compose up -d
sleep 1
check_docker pxportal_nginx
check_docker pxportal_dnsmasq
check_docker pxportal_service
echo "Gateway pxportal_service: $(getGateway pxportal_service)"
echo "Gateway pxportal_dnsmasq: $(getGateway pxportal_dnsmasq)"
echo "Gateway pxportal_nginx  : $(getGateway pxportal_nginx)"

echo "[>] Checking ssh keys"
docker exec pxportal_service cat /root/.ssh/id_rsa.pub > /dev/null
if [ "$?" -ne "0" ]
then
  echo "[>] generating ssh keys"
  docker exec pxportal_service ssh-keygen -N "" -f /root/.ssh/id_rsa
fi

SSH_PUB=$(docker exec pxportal_service cat /root/.ssh/id_rsa.pub)
HAS_SSH=$(cat ~/.ssh/authorized_keys | grep "$SSH_PUB" | wc -l | xargs echo -n)
if [ "$HAS_SSH" -eq "0" ]
then
  echo "[>] Copying public key into host authorized_keys"
  echo $SSH_PUB >> ~/.ssh/authorized_keys
fi

echo "[>] Try ARP command from docker"
GATEWAY=$(getGateway pxportal_service)
ARP_CMD_OPT='"StrictHostKeyChecking no"'
ARP_CMD="ssh -o $ARP_CMD_OPT $USER@$GATEWAY arp -n"

echo $ARP_CMD | xargs docker exec pxportal_service
faildMsg $? "Failed to exec arp command from docker | check ssh config"

echo "[>] Updating .env"
echo "# Updated at $(date)" > .env
echo "ARP_CMD=$ARP_CMD" >> .env

echo "[>] Restarting PXPortal"
docker-compose up -d

mkdir -p /tmp/pxportal-tst
cd /tmp/pxportal-tst

echo "[>] Checking all"
check_ping "google.com"
check_ping "apple.com"
check_ping "portal.eca.aero"
check_ping "captive.eca.aero"

check_wget "test.google.com"
check_wget "test.google.com/validate"

echo "---"
echo "[!] Setup done with success"
```

\clearpage

## Primary Nginx Config

The ECA-portal Nginx is configured as a slave reverse proxy. That's why it is not used the 80 by default.

But to be able to handle captive portal API, the primary nginx running on port 80 should redirect all unknown URLS to portal nginx. This is an example of configuration to add into a primary nginx configuration:


```bash
....
server {                                                                                                        
    listen 80 default_server;                                                                                   
    server_name _;                                                                                              
                                                                                                                
    location / {                                                                                                 
      proxy_set_header Host $host;                                                                               
      proxy_set_header X-Real-IP $remote_addr;                                                                   
      proxy_set_header X-Forwarded-For $remote_addr;                                                             
      proxy_set_header X-Forwarded-Host $remote_addr;                                                            
      proxy_pass http://172.19.0.1:8031;
  }                                                                                                             
                                                                                                                
  access_log      captive-pxportal-access.log;                                                                  
  error_log       captive-pxportal-error.log;                                                                   
}
....
```


\clearpage

## docker-compose.yml

```yaml
version: '2'

services:
  nginx:
    image: nginx:alpine
    container_name: pxportal_nginx
    networks:
      - pxportal
    ports:
      - "8031:80"
    volumes:
      - ./webapp:/data/webapp
      - ./conf/nginx.conf:/etc/nginx/nginx.conf
      - ./conf/conf.d:/etc/nginx/conf.d/

  dnsmasq:
    image: andyshinn/dnsmasq
    container_name: pxportal_dnsmasq
    ports:
      - "53:53/tcp"
      - "53:53/udp"
    cap_add:
      - NET_ADMIN
    volumes:
      - ./conf/dnsmasq.conf:/etc/dnsmasq.conf
    depends_on:
      - pxportal

  pxportal:
    container_name: pxportal_service
    image: registry.preprod.pxcom.aero/pxcom-servers/pxportal-srv:latest
    volumes:
      - ./webapp:/usr/app/webapp
      - ssh:/root/.ssh
    networks:
      - pxportal
    environment:
      - REDIRECT_TO=http://portal.eca.aero/index.html
      - ARP_CMD=${ARP_CMD}
    ports:
      - "8889:8889"

volumes:
  ssh:

networks:
  pxportal:
    driver: bridge
```

\clearpage

## Cisco configuration

### Wlan

#### Wlan - Home

Go to __Wireless Settings / WLANs__ page to create or configure a WLAN for passengers.

![Wlan Home](assets/wlan_home.png){ width=100% }
\FloatBarrier

#### Wlan - General

* __Profile Name__: [Name of passengers WIFI]
* __SSID__: [Name of passengers WIFI]

![Wlan Edition - General](assets/wlan_edit_general.png){ width=100% }

\clearpage

#### Wlan - WLAN Security

Such as CISCO captive portal forces a HTTPS page and requires to check SSL certificates from external network, PXPortal doesn't use it and provides its own captive portal. That's why __Guest Network__ is disabled and the WIFI network is opened.

* __Guest Network__: _disabled_
* __Security type__: _Open_

![Wlan Edition - WLAN Security](assets/wlan_edit_security.png){ width=100% }
\FloatBarrier


#### Wlan - VLAN & Firwall

_Default configuration_

![Wlan Edition - VLAN & Firewall](assets/wlan_edit_vlan_firewall.png){ width=100% }
\FloatBarrier

\clearpage

#### Wlan - Traffic Shaping

_Default configuration_

![Wlan Edition - Traffic Shaping](assets/wlan_edit_traffic.png){ width=100% }
\FloatBarrier

\clearpage

### DHCP

By default, PXPortal uses Cisco DHCP.

### General

* __Pool Status__: Enabled
* __Network / Mask__: 10.0.0.0 / 255.255.255.0
* __Start IP__: 10.0.0.11
* __End IP__: 10.0.0.249
* __Gateway IP__: 10.0.0.254
* __Domain Name__: eca.aero
* __Name servers__: User Defined / 10.0.0.254

![DHCP Edition](assets/dhcp_edit.png){ width=100% }
\FloatBarrier