PVX for Developers

For developers, it is possible to programmatically generate and retrieve the result pages as HTML or PDF.

Getting data

To request a page, you will use the same URL that you would in a Web browser. Filters are implemented in the URL in the form of GET parameters: http://DOMAIN/PATH?filter.field1=value1&filter.field2=value2

If the capture_begin or capture_end filters are omitted, the engine will instead request data for the last hour.

The URL can be parameterized to ask the engine to render the output either as stripped-down HTML, or as PDF. This is done by prepending, respectively, /++skin++simplehtml/ and /++skin++pdf/ to the path part of the URL: http://DOMAIN/++skin++pdf/PATH?filter.field1=value1&filter.field2=value2

NB: This is the same kind of URL you get when you click the ‘Export as PDF’ button in the user interface.

Authentication

PVX normally uses its own authentication forms, which you see whenever you log into the user interface with a Web browser. This authentication system uses cookie-based sessions to keep you logged in, which can be inconvenient to support programmatically.

PVX, therefore, provides support for session-less access with the Basic HTTP Authentication mechanism. Command-line download clients like curl or wget support it natively.

There are two ways to switch PVX over to session-less Basic HTTP Authentication:

1. Your download client may support it automatically. curl does. wget does if you pass the --auth-no-challenge command-line option. In this case, pass your login and password in the normal way supported by your client, and PVX will automatically authenticate your request using Basic HTTP Authentication.
2. Your download client may require the server itself to initiate the Basic HTTP Authentication process. For instance, wget does so when you omit the --auth-no-challenge option. If so, you can instruct PVX to initiate the process by appending &auth=force-http to the query string part of the URLs.

Note

Basic HTTP Authentication does not protect your credentials from snooping. You may thus want to use https:// URLs instead of http://.

Scripting examples

In the first example, we will retrieve the Top Servers page as a stripped-down HTML, filtering for the SSH application using the command-line with wget:

## Using the --auth-no-challenge option:
wget --user=admin --password=admin --auth-no-challenge 'http://PVX/++skin++simplehtml/nevrax/network/ipstats_dst.html?filter.capture_begin=2013-01-31+14:50&filter.capture_end=2013-01-31+15:50&filter.serviceid=ssh'

## Using the *auth* query string parameter:
wget --user=admin --password=admin 'http://PVX/++skin++simplehtml/nevrax/network/ipstats_dst.html?filter.capture_begin=2013-01-31+14:50&filter.capture_end=2013-01-31+15:50&filter.serviceid=ssh&auth=force-http'

In the next example, we will retrieve the Bandwidth Chart page as a PDF using the command-line with curl:

## curl will automatically initiate Basic HTTP Authentication when you pass credentials with the '-u' option:
curl -u admin:admin 'http://PVX/++skin++pdf/nevrax/network/bw_chart_page.html?filter.capture_begin=2013-01-31+14%3A51&filter.capture_end=2013-01-31+15%3A51&filter.serviceid=ssh' -o bandw_chart.pdf

If HTTPS is used to keep your credentials concealed, your client may need an option to skip the server certificate check. Here is an example with wget:

## Same wget query as above, using HTTPS, and a terser way to pass credentials:
wget --no-check-certificate 'https://admin:admin/PVX/++skin++simplehtml/nevrax/network/ipstats_dst.html?filter.capture_begin=2013-01-31+14:50&filter.capture_end=2013-01-31+15:50&filter.serviceid=ssh&auth=force-http'

Programming example

You can also create a program to retrieve result pages from PVX. Here is a simple example in python2:

import urllib
import urllib2

def get_spv_data(url, user, passw):

    ## create authentication
    auth = urllib2.HTTPPasswordMgrWithDefaultRealm()
    auth.add_password(None, url, user, passw)
    urllib2.install_opener(urllib2.build_opener(urllib2.HTTPBasicAuthHandler(auth)))

    ## request
    req = urllib2.Request(url)
    f = urllib2.urlopen(req)
    return f.read()


def create_url(domain, page, filters={}, as_pdf=True):
    filter_args = {('filter.%s' % k): v for k, v in filters.iteritems()}
    filter_args = urllib.urlencode(filter_args)
    if as_pdf:
        skin = '++skin++pdf/'
    else:
        skin = '++skin++simplehtml/'
    return 'http://%s/%s%s?%s&auth=force-http' % (domain, skin, page, filter_args)


## set up the query
domain = 'myspv-domain'
page = 'nevrax/network/bw_chart_page.html'
filters = {'capture_begin': '2013-01-31 14:50',
           'capture_end':   '2013-01-31 15:50',
           'serviceid':     'ssh',
           }
user = 'admin'
passw = 'admin'

url = create_url(domain, page, filters, as_pdf=True)
result = get_spv_data(url, user, passw)
open("output.pdf", "w").write(result)