The pyping2 wiki

Welcome to the pyping2 wiki. Use the side bar on the right to navigate.

Contents

1. Intro
2. Quickstart
3. Dependencies
4. Using pyping2
5. Reporting
6. Example script
7. Version standards

1. Intro

Pyping2 is a Python library for testing network infrastructure. To assit with portability, there is an accompanying Docker image which is based on Debian. If you have all the dependencies installed on your host machine, you can run pyping2 on your host, but the image takes care of all of this for you.

Check out the Docker page to see how you can run tests in a few commands!

2. Quickstart: single line and script flows

Here's how you would use pyping2 in a single line flow:

    python -m pyping2 [your csv of URLs] [optional: name of your network interface]

Note:

• you will need root access for this.
• if you do not specify network interface, pyping2 defaults to eth0

An overview of a script workflow:

    import pyping2
    interface = "eth0"
    domains = ["www.pingtest.com", "www.cnn.com"]
    a = pyping2.Targets(domains, interface)
    a.tcpdump_start()
    a.tests()
    a.report()
    a.tcpdump_stop()

At this point, a CSV of test results and pcaps will be written to a timestamped directory under pyping2_results/.

3. Dependencies

To use the library, there are dependencies for GNU/Linux and Python. Check the Dockerfile on github or on DockerHub for more information.

4. Using pyping2

Import library and instantiate pyping2 object

Import the library and create an object by passing a list of URLs and timeout (optional, defaults to 10 seconds).

    import pyping2
    a = pyping2.targets(["www.pingtest.com", "www.cnn.com"])

Dependency check

At any time check the dependencies on your system with the check() module:

    a.check()

Again, if you are working in a container based on the pyping2 image, you will have no problem.

Summary

At any time show a summary of the pyping2 object with the show() module:

    a.show()
    #Target: www.someURL.com
    #Host Local IP: 10.0.1.2
    #External IP: 8.8.8.8

tcpdump

The library also captures packets on the network interface of your choice:

    a.tcpdump_start()

Stop capture after all tests:

    a.tcpdump_stop()

pcap will write to a timestamped location under pyping2_results.

Tests

To run tests, call the following:

    a.tests()

At the moment, this runs lft on the targets.

5. Reporting

After the test completed, you can generate a report results_lft.csv timestamped under pyping2_results:

    a.report()

6. Example script

Here's what an example script would look like (taken from example.py):

    #! /usr/bin/python

    import pyping2

    domains = ["www.pingtest.com", "www.cnn.com", "www.amazon.com"]
    interface = "eth0"

    a = pyping2.Targets(domains, interface)
    a.tcpdump_start()
    a.tests()
    a.report()
    a.tcpdump_stop()

Call your script with python yourscript.py

7. Version standards

This repo is automatically built in Docker, image versions correspond to repo version tags. This is the standard used:

version x.z.y where:

    x: major revision
    y: minor revision
    z: any hot fixes

Examples:

• Major revision: public release
• Minor revision: test releases: adding new methods, adding source libraries in Dockerfile, e.g. RUN curl -X GET [URL]
• Hotfix: any changes that need to be pushed prior to a minor revision.