connectivity-test

contest

Assesses the connectivity between a host, Internet, and AWS services.

Current version: 1.0.0

Lead Maintainer: Halim Qarroum

Table of contents

• Installation
• Features
• Description
• Usage
• See also

Install

npm install --global connectivity-test

Features

• Verifies Internet availability on the current host.
• Detects potential captive portals blocking access to the network.
• Assesses connectivity to AWS IoT API and the AWS IoT Core message broker.
• Integrated with Speedtest to measure the current Internet throughput.

Description

The contest (or connectivity-tester) command-line tool is a Node.js application that is useful if you are connected to an unfamiliar network you do not control, and want to assess the connectivity options you have to the Internet and AWS services as well.

It also implements a captive portal detection which are common on public networks.

Usage

Once the connectivity-test package has been installed, you can run it using the following command in your terminal :

contest

This will start the test plan associated with the different network connectivity tests which contest has been developed to assess.

Note that the MQTT test will fail since you did not yet configured contest to take AWS IoT certificates into consideration (see next section).

Configuring MQTT access

In order to allow contest to test an MQTT connection to the AWS IoT Core message broker, you need to generate a valid device certificate chain using the AWS Console. As such, you need to have the following files at your disposal for the MQTT test to succeed :

• The device certificate (.cert.pem extension).
• The device private key (.key extension).
• The AWS Root CA .pem file.

Make sure that you associate to your certificate(s) the rights to iot:Connect to the MQTT broker, iot:Receive and iot:Publish on the connectivity/tester topic.

Once you have downloaded these files on your filesystem, you need to ensure that you know the AWS IoT endpoint associated with your account and desired region.

To do so, you can run the following command which will invoke the aws-cli :

aws iot describe-endpoint

To retrieve your AWS IoT endpoint, you can also open the AWS IoT console in your browser, and click on the Settings option on the bottom left-hand corner of the side-menu.

At this point, you have all the elements to provide contest with all the information required to establish a connection to AWS IoT. To pass all these information to the command-line tool, you can use the following example :

contest --aws:iot:keyPath=path/to/private.key --aws:iot:certPath=path/to/certificate.pem --aws:iot:caPath=path/to/root-ca.pem --aws:iot:host=aws-iot-endpoint

Testing AWS IoT with ALPN extensions

AWS has recently announced support for the ALPN TLS extension on its IoT service which allows MQTT clients to connect to the AWS IoT Core message broker on the 443 instead of the standard 8883 port.

The contest command-line tool activates automatically these ALPN extensions if you specify the port 443 in the command line options :

contest --aws:iot:port=443

Update the AWS region

When contest assess the connectivity against AWS services, it will use by default the eu-central-1 region. If you wish to change the region, you can pass the following option on the command-line tool :

contest --aws:global:region=us-east-1

Note that all AWS services are not available in every regions tested by contest, in this case a meaningful error will be raised on that particular service during the tests if it is not implemented in the region you have selected.

See also

• The aws-cli command-line tool.