PingProxy Driver
Container Details
Getting Started with VNS3 Plugin System
PingProxy Driver is deployed to VNS3 as a plugin using the container system.
Please be familiar with the VNS3 Plugin Configuration Guide.
What does it do?
PingProxy Driver brings real-world connectivity monitoring and alerting to VNS3. Utilizing Cohesive’s PingProxy plugin as a backend for connectivity testing, PingProxy Driver creates logs and optionally sends alerts via VNS3 to Slack, PagerDuty, WebEx Teams, and more.
Please be familiar with the PingProxy plugin before getting started with PingProxy Driver.
What does it need?
You will need a VNS3 controller on which to run this plugin, as well as an existing PingProxy container.
PingProxy Driver must be able to reach your PingProxy container on tcp port 5002, and your PingProxy container must be able to reach the resource(s) to which you wish to monitor connectivity. In some cases this may require environment-specific firewall rules, routes, or other configuration.
If you plan to use VNS3’s Alerts functionality, you will also need an Alert configured in VNS3 to fire on the “system_general” event and a refreshing VNS3 API Token with a sufficiently long life such that it will not expire.
Deploying
Getting the Container Image
The Linux-based (Ubuntu 18.04) PingProxy Driver Container Image is accessible at the
following URL:
https://vns3-containers-read-all.s3.amazonaws.com/PingProxy+Driver/PingProxyDriver_20200923.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.
Enter the PingProxy Driver Container Image file URL: https://vns3-containers-read-all.s3.amazonaws.com/PingProxy+Driver/ppdriver_20200825.tar.gz
Click Upload.
Allocating a Container
When the Image has imported, it will say Ready in the Status Column.
To launch a container from the image, choose Allocate from the Action menu.
After selecting Allocate from the Actions menu, name your container, provide a description, and /usr/bin/supervisord as the Command to start the container.
If you are using VNS3 v4.8.2 or newer, you can provide environment variables to the container to configure it without having to SSH into it. These are discussed in the next section.
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.
PingProxy Driver Environment Variables
As an alternative to SSH configuration using the setup script, environment variables can be used to configure the PacketLoss Container in VNS3 v4.8.2 and newer. They should be provided as a comma-separated list of key=“value” pairs.
PingProxy Driver accepts the following variables:
- pingproxyhost (required) takes the IP of your PingProxy container.
- pingproxyport (required) takes the tcp port where your PingProxy container’s API is reachable. Usually this is 5002, unless you have a more complex or non-standard setup.
- pingproxytoken (required) takes the API key generated by the PingProxy container’s setup.sh script.
- monitoredhosts (required) accepts a semicolon-separated list of hosts along with space-separated interval and threshold values as well as an optional description.
- 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.
Here are a few sets of example variables; one without Alerts, one with, and one using a different VNS3 controller for Alerts.
pingproxyhost="198.51.100.10", pingproxyport="5002", pingproxytoken="tokentokentoken", monitoredhosts="1.1.1.1 2 3;google.com:443 30 4 google_homepage"
pingproxyhost="198.51.100.10", pingproxyport="5002", pingproxytoken="tokentokentoken", monitoredhosts="1.1.1.1 2 3;google.com:443 30 4 google_homepage", vns3apitoken="tokentokentoken"
pingproxyhost="198.51.100.10", pingproxyport="5002", pingproxytoken="tokentokentoken", monitoredhosts="1.1.1.1 2 3;google.com:443 30 4 google_homepage", vns3apitoken="tokentokentoken", vns3addr="198.51.100.1"
In all examples above, PingProxy Driver will use the PingProxy API to ping 1.1.1.1 every two seconds, logging a message if three successive ping replies are missed. It will also use PingProxy API to telnet to google.com on port 443 every 30 seconds, logging a message if four successive telnets fail. Additional hosts may be added to this list.
PingProxy Driver Firewall Rules
The following firewall rules are required at minimum; you may need to adapt, replace, or add additional rules depending on your environment.
# Port forward tcp44 to the PingProxy Driver container for SSH
PREROUTING_CUST -i eth0 -p tcp --dport 55 -j DNAT --to <ppdriver container ip>:22
# Allow tcp8000 from PingProxy Driver for VNS3 Alerts
INPUT_CUST -s <ppdriver container ip> -p tcp --dport 8000 -j ACCEPT
OUTPUT_CUST -d <ppdriver container ip> -p tcp --sport 8000 -j ACCEPT
# Allow tcp5002 to the PingProxy container from PingProxy Driver
FORWARD_CUST -s <ppdriver container ip> -d <pingproxy container ip> -p tcp --dport 5002 -j ACCEPT
FORWARD_CUST -s <pingproxy container ip> -d <ppdriver container ip> -p tcp --sport 5002 -j ACCEPT
Configuring the PingProxy Driver Container
Setting up the Container
After allocating the container and applying the necessary firewall rules to VNS3, you can SSH into the container on port 44.
The username is container_admin, and the default password is container_admin_123!
We recommend that you change this password immediately: .
~$ sudo passwd container_admin
If you did not configure using environment variables, SSH into the container and run ~$ ./setup.sh.
The setup script will prompt for all required information, write configuration files, and start all required services.
Using PingProxy Driver
The PingProxy Driver plugin creates its log file at /mnt/logs/plugins/pingproxydriver/ppdriver.log.
If the PingProxy Driver container image name contained the word “logger” at the time the plugin was launched, this location is shared with the VNS3 host and other “logger” containers. You can use this functionality to offload and/or process logs in whatever way and using whatever software works best for you and your environment.
If Alerts are configured, all log messages will also be sent as the data field of an Alert.
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 Driver Container. We recommend creating and downloading an image of your container as part of the deployment process:
From the Containers page in the VNS3 web UI, select Action > Save as Image for your PingProxy Driver 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.