Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

The WAS mainly consists of two software components: (1) the WiFiMon Agent and (2) the WiFiMon GUI.

(1) WiFiMon Agent

The WiFiMon Agent is responsible for performing the following actions: 

...

WiFiMon Agent can operate in a non-secure manner (non-secure WiFiMon Agent) when the crowdsourced and deterministic measurements are streamed over HTTP or in a secure manner (Secure WiFiMon Agent) if measurements are streamed over HTTPS.

(2) WiFiMon GUI

The WiFiMon GUI provides a graphical representation of the measurement results and various anayses as described above.

WAS Installation and Configuration Guide

This guide given below presents the commands required to install the WAS in a Debian-based distribution (Debian, Ubuntu, etc.). Other distributions may also be considered by adjusting the included commands appropriately. Our installation was tested in Ubuntu 20.04 LTS.

Prerequisites for the WiFiMon Analysis Station (WAS) Installation

To install WiFiMon Analysis Station (WAS) successfully, the following software components are required:

  • WiFiMon Agent package (version 1.4.01)
  • PostgreSQL (tested on version 12.7)
  • Java 11
  • Elasticsearch (tested on version 7.13.2)
  • Kibana (tested on version 7.13.2)
  • Logstash (required in case of correlation with RADIUS and DHCP Logs, tested on version 7.13.2)

...

  • 5044: for Logstash
  • 5432: for PostgreSQL
  • 5601: for Kibana
  • 8441: for WiFiMon GUI
  • 8443: for WiFiMon Secure Agent
  • 9000: for WiFiMon Non-secure Agent (optional)
  • 9200: for communication with Elasticsearch

1. Overview of the WiFiMon Analysis Station (WAS) Installation

A summary of the mandatory steps for the installation (detailed in the linked sections below):

There are also some optional steps:

Anchor
PostgreSQL
PostgreSQL
2. PostgreSQL

Installing PostgreSQL from a package manager requires using the following commands:

...

After the installation of PostgreSQL, the database and tables required by WiFiMon should be created.  Detailed instructions are included in the following subsections.

Anchor
database
database
2.1. Database and User Creation

The following code block includes the appropriate SQL commands required to create (i) a database that will store information related to Subnets and Access Points monitored by WiFiMon as well as accounts of users that can access the WiFiMon GUI and (ii) a user that will be able to access this database. The following commands create the (i) database "wifimon_database" and (ii) the user "wifimon_user" with password "wifimonpass". We strongly suggest that these example names are changed in production environments.

...

The following subsections include the commands that are necessary for the creation of the required tables.

2.2. Creation of "subnets" Table

WiFiMon measures the performance of WiFi networks by embedding JavaScript code in frequently visited websites. Performance tests are triggered when End Users visit these websites and, in particular, after a web page is loaded so that browsing experience is not impacted by WiFiMon. Notably, these websites are not only visited by End Users residing in the monitored Subnets, but also from End Users outside them. Thus, alleviating the WAS from processing excessive traffic requires that performance tests consider measurements originating only from the WiFi networks that are monitored. To that end, a list of the registered Subnets from which End User measurements are processed by the WAS are maintained in "subnets" table. The creation of this table is detailed in the following code block.

Code Block
languagesql
CREATE TABLE subnets (
subnet text,
subnet_id serial PRIMARY KEY );

2.3. Creation of "accesspoints" Table

Table "accesspoints" is used to store information related to the Access Points monitored by WiFiMon. This information includes the latitude and longitude of Access Points, the building and floor in which they are installed and additional notes about them. This information is later used to depict performance results of End User measurements per Access Point. The creation of the "accespoints" table is detailed in the following code block.

Code Block
languagesql
CREATE TABLE accesspoints (
apid serial PRIMARY KEY,
mac text NOT NULL,
latitude text,
longitude text,
building text,
floor text,
notes text);

2.4. Creation of "users" Table

Table "users" is used to store information related to WiFiMon Users. WiFiMon GUI can be accessed by two types of WiFiMon Users: ADMIN and USER. ADMIN has full privileges to the WiFiMon GUI. An ADMIN is capable of adding/removing registered Subnets and Access Points as well as adding/removing WiFiMon Users. In contrast, a USER can navigate through the WiFiMon GUI dashboards, but is incapable of performing administration actions. The creation of the "users" table is detailed in the following code block.

Code Block
languagesql
CREATE TABLE users (
id serial PRIMARY KEY,
email text NOT NULL,
password_hash text NOT NULL,
role text NOT NULL);

2.5. Creation of "options" Table

Table "options" stores information related to privacy settings, e.g. hiding/showing End User specific data in the WiFiMon GUI. Correlation options are also included in this table. The creation of the "options" table is detailed in the following code block.

...

Exiting the database is possible using the command "\q" within the terminal-based front-end of PostgreSQL.

Setting Privileges in PostgreSQL

Setting SELECT, INSERT, DELETE, UPDATE privileges for the database user, e.g. "wifimon_user" requires the following commands issued within the terminal-based front-end of PostgreSQL:

...

Exiting the database is possible using the command "\q" within the terminal-based front-end of PostgreSQL.

Create an admin account to login

An initial ADMIN WiFiMon User should be created for accessing the WiFiMon GUI. Within the terminal-based front-end of PostgreSQL, an ADMIN WiFiMon User is created using the commands in the following code block after connection to the WiFiMon database. Notably, passwords are stored hashed within the database.

...

This account can be later deleted from the WiFiMon GUI (after step 5). However, an ADMIN account should always be present in order to access the WiFiMon GUI and manage the WiFiMon Users, Access Points and Subnets. We strongly suggest that the password is changed from the WiFiMon GUI when the installation is complete (step 5).

Anchor
java
java
3. Java Installation

WiFiMon currently supports Java 11. The required commands are the following:

...

Code Block
source /etc/environment

Anchor
elasticsearch
elasticsearch
4. Elasticsearch and Kibana

Installing Elasticsearch 7.13.2 and Kibana 7.13.2, requires executing the following commands:

...

Code Block
wget https://artifacts.elastic.co/downloads/kibana/kibana-7.13.2-amd64.deb
sudo dpkg -i kibana-7.13.2-amd64.deb

Anchor
elasticsearch_configure
elasticsearch_configure
Elasticsearch Configuration

In the configuration file of Elasticsearch (/etc/elasticsearch/elasticsearch.yml), the following lines should be inserted/changed. Notably, bold parts must be adjusted to the particular configuration of the reader. In the following, we configure Elasticsearch to be publicly accessible:

cluster.name: elasticsearch
node.name: ${HOSTNAME}

node.master: true
node.voting_only: false
node.data: true
node.ingest: true
node.ml: false
cluster.remote.connect: false
path.data: /var/lib/elasticsearch
path.logs: /var/log/elasticsearch
network.host: INSERT the Fully Qualified Domain Name (WAS_FQDN) to which the server listens
discovery.seed_hosts: ["WAS_FQDN"]
cluster.initial_master_nodes: ${HOSTNAME}
xpack.ml.enabled: false
xpack.security.enabled: false

...

Notably, "cluster.initial_master_nodes" must be commented out after the first initialization of the Elasticsearch cluster. The above configuration assumes that the setup includes a single Elasticsearch node. Configuration for more advanced setups is available in the following WiFiMon guide "Streaming Logs Into ELK Cluster".

Anchor
kibana_configure
kibana_configure
Kibana Configuration

After installing Kibana, the following configurations are required in the Kibana configuration file (/etc/kibana/kibana.yml). The following changes should be made in the corresponding sections/fields of the configuration file. Notably, bold parts must be adjusted to the particular configuration of the reader.

server.port: 5601
server.host: "WAS_FQDN"
server.name: “wifimon"wifimon-kibana”kibana"
elasticsearch.hosts: [“http"http://WAS_FQDN:9200”9200"]

server.ssl.enabled: false

...

Verifying that kibana is running is possible via: netstat -tlnpu (port 5601)

Anchor
wifimon
wifimon
5. WiFiMon Installation

Installing WiFiMon requires the following commands:

Code Block
wget http://83.97.95.167/manual/wifimon-agent-1.4.01.deb
sudo apt-get update
sudo apt-get install -y gdebi
sudo gdebi wifimon-agent-1.4.01.deb

Afterwards, the following files will show up in /usr/lib/wifimon/ directory:

  • elasticsearch.sh: Script to create Elasticsearch indices

  • kibana-import.ndjson: JSON file to be imported in Kibana to create the necessary visualizations and dashboards

  • start.sh: Script for starting WiFiMon GUI and Agent

  • secure-processor-1.4.01.war: This incorporates both the WiFiMon Secure and Non-Secure Agent

  • ui-1.4.01.war: This incorporates the WiFiMon GUI

  • config: Directory with configuration files. Their parameters must be filled in.

  • keystore: Directory where the Java Keystore should be stored in order to run WiFiMon Agent and GUI on HTTPS

...

Starting the WiFiMon Secure Agent and WiFiMon GUI requires the following command:

Code Block
./start.sh

Anchor
compile
compile
6. WiFiMon Code Compilation

Note: This step is only required if the WiFiMon Code is modified by the reader to include new features.

...

Code Block
cp agent/wifimon-assembly/target/wifimon-agent-bin/secure-processor-1.4.01.war /usr/lib/wifimon/secure-processor-1.4.01.war
cp agent/wifimon-assembly/target/wifimon-agent-bin/ui-1.4.01.war /usr/lib/wifimon/ui-1.4.01.war

Anchor
letsencrypt
letsencrypt
7. Configuration of the WiFiMon Secure Agent

Configuration of the WiFiMon Secure Agent will be demonstrated using a Let’s encrypt certificate. Readers are free to use whatever certificate they prefer.

...

WiFiMon is now configured to use HTTPS for WiFiMon GUI and Agent.

Anchor
xpack
xpack
8. Configuring ELK Stack Security (X-Pack)

In the sequel, we will secure the ELK stack using the X-Pack Elastic Stack extension and self-signed certificates. This section follows the complementary guide "Streaming Logs Into ELK Cluster" that is included in the WiFiMon documentation and mainly focuses on what configuration is needed regarding interfacing X-Pack with the WiFiMon code and the Secure Process and UI property files. Notably, the complementary guide "Streaming Logs Into ELK Cluster" details more advanced setups, e.g. multi-node clusters. However, in this section we focus on explaining the configuration required for a single-node setup.

...

In /etc/kibana/kibana.yml, the following details should be added and Kibana should be restarted:

elasticsearch.hosts: ["https://WAS_FQDN:9200"]
elasticsearch.ssl.certificateAuthorities: [ "/etc/kibana/certs/ca.crt” crt" ]
elasticsearch.ssl.verificationMode: full

...

xpack.security.enabled=true
ssl.certificate.type=keystore
ssl.http.user.username=elastic
ssl.http.user.password=[elastic built-in user password]
ssl.http.keystore.filepath=/usr/lib/wifimon/keystore/keystore.jks
ssl.http.keystore.password=[keystore.jks password]
ssl.http.truststore.filepath=/usr/lib/wifimon/keystore/truststore.jks
ssl.http.truststore.password=[truststore.jks password]
ssl.http.key.password=[elasticsearch.key password]

Anchor
links
links
9. The WiFiMon GUI

The installation is now complete. The WiFiMon GUI can be accessed at: https://WAS_FQDN:8441/login (see Figure 1)

...