Example: Building a Packet Capture query with VMX-Prism API

General information

VMX-Prism cannot be accessed directly but can be accessed via the Beeks Analytics REST API.

In the examples below, the following path variables are used:

<hostid>
This is the id of the host to run the query against, e.g., env1. You can also use all to run this against all environments in a multi-env environment.

To retrieve the list of available hosts, use

{{VMXURL}}/api/REST/v1/Config/Prism/Hosts

Retrieve a PCAP for a time-period without performing stack decode

Step 1. GET a list of available capture probes to query using:

{{VMXURL}}/api/REST/v1/Config/Prism/<hostId>/Probes

This will return the set of available capture probes on the <hostid> environment/s as JSON in the following structure:

{
  "captureProbes": [
    {
      "id": "myID",     <= captureProbe ID
      "pmuxId": "myID"  <= pmux ID of the captureProbe
    }
  ]
}

Step 2. POST retro job to retrieve PCAP:

{{VMXURL}}/api/REST/v1/Prism/<hostId>/Retro/

The following is an example set of input parameters as JSON. This example does not do any stack decoding.

{
  "name": "Postman_Test_Retro",   
  "output_format": "pcapns",
  "compression": "gzip",
  "time_range": ",now,10s",       <= time period for retrieving pcap
  "pcap_probes": [                <= capture probe/s retrieved in step 1
    "default:TEST2:mycap2"
  ],
  "output_pcap": "full",
  "output_protodump": "full",
  "stack_probes": {
    "pmux_id": "TEST2",
    "probes": []                  <= stack probe to decode (set blank)
  },
  "start_now": "true"             <= run job now
}

The output of running this retro API call successfully would be a single PCAP file that covers the chosen time period:

Postman_Test_Retro.pcap.gz

Retrieve a PCAP and stack decode for a time period

Step 1. GET a list of available PMUXs:

{{VMXURL}}/api/REST/v1/Config/Prism/<hostid>/Pmuxes

This will return a list of available PMUXs for the specified <hostid> in the following structure:

{
  "pmuxes": [
    {
      "id": "myID"
    }
  ]
}

Step 2. GET a list of stack probes for a PMUX:

{{VMXURL}}/api/REST/v1/Config/Prism/<hostid>/Pmuxes/<pmuxId>/StackProbes

This will return a list of available stack probes for the specified <hostid> and <pmuxId>in the following structure:

{
  "stackProbes": [
    {
      "id": "myID",       <= stackProbe ID
      "pmuxId": "myID"    <= pmux ID of the stackProbe
    }
  ]
}

Step 3. GET a list of available capture probes to query using:

{{VMXURL}}/api/REST/v1/Config/Prism/<hostId>/Probes

This will return the set of available capture probes on the <hostid> environment/s as JSON in the following structure:

{
  "captureProbes": [
    {
      "id": "myID",     <= captureProbe ID
      "pmuxId": "myID"  <= pmux ID of the captureProbe
    }
  ]
}

Step 4. POST retro job to retrieve PCAP and stack decode:

{{VMXURL}}/api/REST/v1/Prism/<hostId>/Retro/

The following is an example set of input parameters as JSON:

{
  "name": "Postman_Test_Retro",
  "output_format": "pcapns",
  "compression": "gzip",
  "time_range": ",now,10s",       <= time period for retrieving pcap
  "pcap_probes": [                <= capture probe/s retrieved in step 1
    "default:TEST2:mycap2",
  ],
  "timestamp": "packet_timestamp",
  "stats_interval": "1",
  "output_pcap": "full",
  "decode_config": {
    "output_format": "json",
    "stats_interval": "1"
  },
  "output_decode": "full",
  "output_protodump": "full",
  "stack_probes": {
    "pmux_id": "TEST2",         
    "probes": [                   <= stack probes to decode
      "net_stats",               
      "dec_stats"
    ]
  },
  "filter": "",                   <= empty BPF filter
  "start_now": "true"             <= run job now
}

The output of running this retro API call successfully would be a PCAP file and the associated stack decode files (JSON) covering the time period chosen.

Adding a Berkeley Packet Filter (v13 vs v14)

To retrieve a subset of the VLANs and traffic information in the retro JSON query above, add a Berkeley Packet Filter (BPF) to the query. The BPF VLAN settings were simplified in Version 14 of the REST API so check which version of the REST API you're using and follow the relevant instructions below:

REST API versions 13 and below

Specify the filter inside the submitted JSON as a single line similar to:

"filter": "vlan and tcp and src 10.101.1.33 and tcp port 9001 or vlan"

As you can see, this filter includes combines VLAN’s with traffic information, which can create complex BPF filters.

REST API version 14 +

In version 14 onwards, the VLAN and traffic information are separated out so that you can specify them in a JSON structure as separate entities. This allows for simpler BPF syntax in setups that require complex VLAN stacking or asymmetric VLAN tagging. See the Stack Packet Filter Configuration section of Beeks document BKDA013 Configuration Guide for VMX Capture.

An empty BPF filter might look something like the example below:

"filter": {
    "type": "BpfPacketFilterModuleWrapper",
    "module": {
      "parameters": {
        "bpf_expression": ""
      },
      "tables": {}
    }
  },

The Swagger API documentation covers some of the key Prism calls, but for a full list of the VMX-Prism API calls that a client might wish to use beyond the examples above, please contact your Beeks account representative.