diff --git a/doc/PXEN310-0000_TN_PXPortal_Integration.md b/doc/PXEN310-0000_TN_PXPortal_Integration.md index d334864..8043fa2 100644 --- a/doc/PXEN310-0000_TN_PXPortal_Integration.md +++ b/doc/PXEN310-0000_TN_PXPortal_Integration.md @@ -19,25 +19,25 @@ Approval [ApprovalName] [Date] 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 alt Not Valid @@ -61,7 +61,7 @@ Nginx --> Box: Portal_Service response Box --> Device: Portal_Service response ``` -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 - 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'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 ## First Run -### 1. Clone ECA-captive repository +### Clone ECA-captive repository ```bash git clone ssh://gitolite@git.pxcom.aero:2221/ife/ECA-captive.git @@ -210,7 +210,7 @@ docker-compose up -d ## SSH Config -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. ![DHCP Edition](assets/dhcp_edit.png){ width=100% } \FloatBarrier + + diff --git a/doc/PXEN310-0000_TN_PXPortal_Integration.pdf b/doc/PXEN310-0000_TN_PXPortal_Integration.pdf index 05b94f9..e7bea46 100644 Binary files a/doc/PXEN310-0000_TN_PXPortal_Integration.pdf and b/doc/PXEN310-0000_TN_PXPortal_Integration.pdf differ