This container now includes functionality provided previously by both the “PingProxy” and “PingProxy Driver” containers, bringing real-world connectivity monitoring and alerting to VNS3.

The PingAPI process, A RESTful API for querying real-time connectivity (backwards-compatible with the one previously found in the PingProxy container), is available in this container. Create an API token to retrieve real-time connectivity status to your own in-house monitoring solution.

The PingMonitor process automatically reaches out to each host in a user-configurable list to verify connectivity. A message is logged if a user-defined failure threshold is crossed, and a VNS3 Alert can optionally be sent. This replaces functionality previously provided by the PingProxy Driver container.

The PingAPI and PingMonitor processes may be used independently; they are included together in this container only for convenience.

What does it need?

You will need a VNS3 controller on which to run this container. Any resources you wish to monitor must be reachable from that container. In some cases this may require environment-specific firewall rules, routes, or other configuration.

Deploying

The Linux-based (Ubuntu 20.04) PingProxy Container Image is accessible at the following URL; this does not need to be downloaded to your local machine.
https://vns3-containers-read-all.s3.amazonaws.com/PingMonitor/PingMonitor_v2_rc1.tar.gz

This is a read-only Amazon S3 storage location. Only Cohesive Networks can update or modify files stored in this location.

This URL can be used directly in a VNS3 Controller via the Web UI or API to import the container image for use in that controller. (General screenshot walkthrough and help available in the VNS3 Plugin Configuration Guide.)

Uploading via the VNS3 Web UI

From the Container —> Images menu item, choose Upload Image.

Provide a name for the image and a short description if you wish.
Note: Because this container produces logs, we recommend using the word “logger” in the image name. This will allow PingProxy containers launched from this image to access and save logs to the shared log location /mnt/logs/, where they can be consumed by other containers.

Enter the PingProxy Container Image file URL:
https://vns3-containers-read-all.s3.amazonaws.com/PingMonitor/PingMonitor_v2_rc1.tar.gz

Click Upload.

Allocating a Container

When the Image has imported, the word Ready will appear in the Status Column.

To launch a container from the image, choose Allocate from the Action menu.

Name your container, provide a description (optional), and enter/usr/bin/supervisord as the Command.

You can allow VNS3 to auto-assign a container network IP, but it is recommended that you choose one manually. Note this address for the next step.

Note: if you wish to configure the container using environment variables at launch time, please see the Environment Variables portion of the Configuration section below.

Click Allocate to create the container.

Firewall Rules

The PingProxy Container requires some firewall rules to be added to the VNS3 controller. The rules below are examples and should in some cases be made more specific for security reasons. You may need additional or different rules depending on your environment. Feel free to reach out to our support team if you need assistance.

Anywhere it appears, replace <container ip> with the container IP you noted in the previous step.

# Allow PingMonitor container to reach monitored hosts
# Repeat these rules for each monitored host, or use a comma-separated list
FORWARD_CUST -s <container ip> -d <monitored host ip> -j ACCEPT
POSTROUTING_CUST -s <container ip> -d <monitored host ip> -j SNAT --to <relevant NAT address>

# State-aware rule to allow responses packets to PingProxy container
FORWARD_CUST -d <container ip> -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT

# Optional - only needed if using PingProxy API
# Port forward tcp5555 to the PingMonitor container for PingAPI
PREROUTING_CUST -p tcp --dport 5555 -j DNAT --to <container ip>:5002
FORWARD_CUST -s 0.0.0.0/0 -d <container ip> -p tcp --dport 5002 -j ACCEPT
FORWARD_CUST -s <container ip> -p tcp --sport 5002 -j ACCEPT

# Optional - only needed if utilizing VNS3 Alerts functionality
# Allow tcp8000 from PingMonitor for VNS3 API access
INPUT_CUST -s <container ip> -p tcp --dport 8000 -j ACCEPT
OUTPUT_CUST -d <container ip> -p tcp --sport 8000 -j ACCEPT

Configuring the Container

This version of the PingProxy container is configurable at launch time with Environment Variables, or after launch using Plugin Manager in VNS3 version 5.x and newer.

SSH is no longer supported as a configuration mechanism; if you are using a version of VNS3 older than 5.x, you must either upgrade or use the original (version 1) PingProxy and PingProxy Driver containers.

Environment Variables

Environment variables can be used to configure PingMonitor during container allocation. They cannot be configured on an already-created container.
Environment Variables are configured as a comma-separated list of key=“value” pairs.

PingProxy Driver accepts the following variables:

monitoredhosts (required) accepts a semicolon-separated list of hosts, each with whitespace-separated interval and threshold values and optionally a description string.
vns3apitoken (optional) accepts a VNS3 API token. This should be a renewing token with a sufficiently long lifetime such that it will never expire under normal use.
vns3addr (optional) accepts an IP address at which your alerting VNS3 controller is reachable. This parameter should not be necessary unless you have a complex or non-standard configuration.
livenessmsg (optional) accepts an integer number of seconds, after which time if no other message has been logged, an informational message to confirm correct ongoing operation will be logged.

Here are three sets of example variables; one without Alerts, one with, and one which also sends a liveness message every 24 hours:

monitoredhosts="1.1.1.1 2 3;google.com:443 30 20%/100 google_homepage"

monitoredhosts="1.1.1.1 2 3;google.com:443 30 20%/100 google_homepage", vns3apitoken="tokentokentoken"

monitoredhosts="1.1.1.1 2 3;google.com:443 30 20%/100 google_homepage", vns3apitoken="tokentokentoken", vns3addr="198.51.100.1", livenessmsg="86400"

In all examples above, PingMonitor will:

Ping 1.1.1.1 every 2 seconds, logging a message if 3 successive ping replies are missed
Telnet to google.com on port 443 every 30 seconds, logging a message if 20% of the previous 100 telnets fail.

Additional hosts may be added to this list, and the list may be expanded/edited later via Plugin Manager.

Plugin Manager

Once the PingProxy container is running and Firewall rules have been created, you can use VNS3 Plugin Manager to configure the PingMonitor and/or PingAPI functions.

On the Container —> Containers page, choose Manager from the container’s Action menu.

Edit the “Monitored Hosts” text file with your configuration; an example is included in the container and displayed on the page:

If you wish to receive VNS3 Alerts, enter your VNS3 API token and other relevant “Pingmonitor configuration” as well:

After saving your configuration, restart the pingmonitor process; find this function under “Processes” —> “Process manager” on the main Plugin Manager page:

Operation

PingProxy API

The PingProxy API server has three endpoints:

POST /ping

-- Accepts ‘application/json’ data

-- Requires a JSON key “hostname” with a value of either a resolvable hostname or an IP address

-- Optionally accepts a JSON key “timeout” with a value of an integer number of seconds

POST /telnet

-- Accepts ‘application/json’ data

-- In addition to “hostname”, requires a JSON key “port” which accepts a number from 1-65535

-- Optionally accepts a JSON key “timeout” with a value of an integer number of seconds

/GET status/<task id>

-- Accepts a URL variable in the form of a “taskid” returned by an earlier call to /ping or /telnet

-- Returns the exact same data as the original POST call to /ping or /telnet

API calls must be authenticated using a token provided by the “gen_api_token” command available in Plugin Manager:

Here are a few examples using the GNU utility curl:

$ curl -k -X POST https://35.183.124.246:5555/ping -H 'Authorization: Token tlC18rl6drO8QSVD8ztJsJ3DeL0laJP7' -H 'Content-Type: application/json' -d '{"hostname": "1.1.1.1"}'
{"taskid": 973442914445, "result": 0}

$ curl -k -X POST https://35.183.124.246:5555/ping -H 'Authorization: Token tlC18rl6drO8QSVD8ztJsJ3DeL0laJP7' -H 'Content-Type: application/json' -d '{"hostname": "55.55.55.55"}'
{"taskid": 427473951616, "result": 1}

$ curl -k -X POST https://35.183.124.246:5555/ping -H 'Authorization: Token tlC18rl6drO8QSVD8ztJsJ3DeL0laJP7' -H 'Content-Type: application/json' -d '{"hostname": "1.1.1.1", "timeout": "1"}'
{"taskid": 114068932322, "result": 0}

$ curl -k -X POST https://35.183.124.246:5555/ping -H 'Authorization: Token tlC18rl6drO8QSVD8ztJsJ3DeL0laJP7' -H 'Content-Type: application/json' -d '{"hostname": "cohesive.net", "timeout": "1"}'
{"taskid": 196388527694, "result": 1}

$ curl -k -X POST https://35.183.124.246:5555/telnet -H 'Authorization: Token tlC18rl6drO8QSVD8ztJsJ3DeL0laJP7' -H 'Content-Type: application/json' -d '{"hostname": "1.1.1.1", "port": "443"}'
{"taskid": 704737742570, "result": 0}

$ curl -k -X POST https://35.183.124.246:5555/telnet -H 'Authorization: Token tlC18rl6drO8QSVD8ztJsJ3DeL0laJP7' -H 'Content-Type: application/json' -d '{"hostname": "cohesive.net", "port": "3389", "timeout": "1"}'
{"taskid": 899968438289, "result": 1}

PingMonitor

Once configured with a list of monitored hosts and an interval/threshold for each, the pingmonitor process can be restarted to begin monitoring.

Logs are saved to /mnt/logs/plugins/pingproxy/pingmonitor.log, viewable on the Plugin Manager page. This file is also accessible to other logger containers, which can be used to consume and parse container logs.
If configured for Alerts, all log messages will also be sent as system_general VNS3 alerts.

Export a Container Image

In the event that your VNS3 controller needs to be replaced or upgraded, you will need a copy of your configured PingProxy Container. We recommend creating and downloading an image of your configured container as part of the deployment process:

From the Containers page in the VNS3 web UI, select Action > Save as Image for your new PingProxy Container. Once that process is complete, you’ll be brought to the Images page. Select Action > Export on the new image, and provide a name.

Once Exporting is complete, you will have the option to download the image locally.

Updated on 19 Jan 2020