PingProxy

Container Details

Getting Started with VNS3 Plugin System

The PingProxy Container is deployed to VNS3 as a plugin using the container system.

Please be familiar with the VNS3 Plugin Configuration Guide.

What does it do?

The PingProxy container runs a basic RESTful API server. It has two endpoints, /ping and /telnet, which accept a hostname (and port, in the case of telnet) as JSON data and return an integer result.

This is useful for monitoring OSI layer 3 connectivity between resources in an environment that is not routable from your monitoring application due to network placement or other limitations.

For example, you can leverage serverless technologies such as AWS Lambda or Azure Logic Apps to query this container’s API to provide intelligent alerting should an IPsec tunnel stop passing traffic, an overlay client disconnect, or an application stop accepting connections.

NOTE: For this initial release, we have used a very basic webserver which may encounter performance issues if you make a large number of API calls in a short period of time. Please let us know if you encounter any issues with the operation of this container.

What does it need?

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

The PingProxy setup script inside the container requires no user input; when run from the command line, it will provide an API token to be used for authentication and then restart the API server to invalidate old tokens.

Deploying

Getting the Container Image

The Linux-based (Ubuntu 18.04) PingProxy Container Image is accessible at the following URL:
https://vns3-containers-read-all.s3.amazonaws.com/PingProxy/pingapi.export.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 Container Image file URL:
https://vns3-containers-read-all.s3.amazonaws.com/PingProxy/pingapi.export.tar.gz

Click Upload.

Uploading the Container Image to the VNS3 Plugin System

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.

Allocating a Container from the Image

After selecting Allocate from the Actions menu, name your container, provide a description, and /usr/bin/supervisord as the Command to start the container.

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.

Launching the PingProxy Plugin

PingProxy Container Firewall Rules

The PingProxy Container requires at least the following firewall rules be added to the VNS3 controller. These rules are an example and in some cases should be made more specific for security reasons. You may need additional 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.

# Port forward tcp44 to the PingProxy container for SSH
PREROUTING_CUST -i eth0 -p tcp --dport 44 -j DNAT --to <container ip>:22
# Port forward tcp5002 to the PingProxy container for API access
PREROUTING_CUST -i eth0 -p tcp --dport 5002 -j DNAT --to <container ip>:5002
# Allow SSH and tcp5002 to and from the PingProxy container
FORWARD_CUST -s <container ip> -j ACCEPT
FORWARD_CUST -d <container ip> -j ACCEPT

PingProxy Container Firewall Rules

Configuring the 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

Configuring the PingProxy Container

SSH into the container and run ~$ ./setup.sh.

The script will generate a new API token, update the necessary configurations, and start/restart the API server as needed.

Using PingProxy

The PingProxy API server has three endpoints:

  • POST /ping

– Accepts ‘application/json’ data

– Requires a JSON key “hostname”, with a value of a valid, resolvable hostname or an IP address

  • POST /telnet

– Accepts ‘application/json’ data

– Requires a JSON key “port” as well as “hostname”

  • /GET status/<task id>

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

– Will return the exact same data as the original call to /ping or /telnet

All API calls must be authenticated using the token provided by the setup.sh script.

Here are a few examples using the GNU utility curl:

$ curl -k -X POST -H 'Authorization: Token b5HflTIdl5ZjbXXZ7FopFaeGlrRj1cY0' -H 'Content-Type: application/json' https://35.182.8.111:5002/ping -d '{"hostname": "172.31.3.253"}'
{"taskid": 527626642399, "result": 0}

$ curl -k -X POST -H 'Authorization: Token b5HflTIdl5ZjbXXZ7FopFaeGlrRj1cY0' -H 'Content-Type: application/json' https://35.182.8.111:5002/telnet -d '{"hostname": "172.31.3.253", "port": "8000"}'
{"taskid": 789093591679, "result": 0}

$ curl -k -X POST -H 'Authorization: Token b5HflTIdl5ZjbXXZ7FopFaeGlrRj1cY0' -H 'Content-Type: application/json' https://35.182.8.111:5002/ping -d '{"hostname": "5.5.5.5"}'
{"taskid": 777376080224, "result": 1}

$ curl -k -X POST -H 'Authorization: Token eaJoXPw36Hl6ZaoIiD6ks0yL8v2KAynZ' -H 'Content-Type: application/json' https://35.182.8.111:5002/telnet -d '{"hostname": "google.com", "port": "444"}'
{"taskid": 364721333185, "result": 1}

$ curl -k -X GET -H 'Authorization: Token eaJoXPw36Hl6ZaoIiD6ks0yL8v2KAynZ' https://35.182.8.111:5002/status/527626642399
{"taskid": 527626642399, "result": 0}

$ curl -k -X GET -H 'Authorization: Token eaJoXPw36Hl6ZaoIiD6ks0yL8v2KAynZ' https://35.182.8.111:5002/status/364721333185
{"taskid": 364721333185, "result": 1}

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 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.