Stream Packet Captures with a WebSocket (Use Case)

In this example, we discuss the Juniper Mist use case of streaming device packet captures with a WebSocket.

As described in Stream Device Data with a WebSocket (Use Case), the WebSocket API enables client communication with an endpoint. You can use this method of communication for situations where you want to receive near-real time, event-driven data without having to refresh the web browser.

This use case outlines how you can use a WebSocket to stream packet captures (PCAPs). PCAPs capture data packets as they traverse the network, and serve as a powerful troubleshooting tool to help debug traffic issues, as well as broader networking issues.

While you have the ability to download PCAPs from the Mist portal, PCAPs that occurred in the past might only be beneficial in some troubleshooting scenarios. Streaming PCAPs with a WebSocket, on the other hand, enables you to monitor and analyze packets as they traverse the network, in near-real time. With Juniper Mist, you can analyze PCAPs for wired, wireless, and WAN connections.

To establish client communication with an endpoint, two things must occur:

A client must subscribe to a channel in order to request the data it wants to receive.
Then, the server streams the channel data to the client as events occur.

Using a WebSocket requires the following elements:

Authentication
HTTP header configuration
WebSocket Connection URL (wss://api-ws.mist.com/api-ws/v1/stream). Please verify your URL based on your geographical location. See WebSocket API Endpoint.

Note:

When reusing code blocks, replace placeholder values with actual values, such as your API token, organization ID, site ID, AP name, and so on.

Communicate with a MIST WebSocket Endpoint

To communicate with the Juniper Mist WebSocket endpoint, you use an application called Postman. Postman is a GUI API platform for building and using APIs. You can use Postman to carry out any API related tasks, including making WebSocket calls and streaming data.

For general information about getting started with Postman, see Use Postman to Make Your First API Call and Get Started in Postman.

To learn how to create a WebSocket request in Postman, see Create a WebSocket Request.

The following steps describe how you can connect to the Juniper Mist WebSocket:

In Postman, Select New > WebSocket.
Enter the WebSocket server URL wss://api-ws.mist.com/api-ws/v1/stream, then select Connect.
Follow the instructions outlined in Communicate with a MIST WebSocket Endpoint for information on how to connect and authenticate.
Once connected, select the Message heading in Postman.

This is where you tell Mist that you want to stream PCAPs. You must subscribe to the PCAPs stream to accomplish this. The following subscribe command requests PCAP data for the specified site:

Once this information is entered in the Messages field, select Send.

Postman presents your request with an Up Arrow and the Juniper Mist response with a Down Arrow.

The following example shows what you can expect to see in a response from Juniper Mist. Within a few seconds after you subscribe, you should start to see events streaming into the Messages pane in JSON format (default):

You can see the same output in the following formats by changing your selection from the drop-down menu above the Response pane in Postman:

Text
HTML
XML
Binary

You will continue to receive messages until you either disconnect or unsubscribe from the channel by sending a message.

Once you receive the data, you can do any number of things with it, such as:

Create a custom display or dashboard of events.
Archive the data long term.
Create custom monitoring and alerts.
Create more automation based on results.

For examples using other automation tools to communicate with a MIST WebSocket endpoint, such as Python, see Automation Tools.