Soracom Peek
Usage
In order to capture IP traffic to and from your Air for Cellular device, you must first create a Type-E or Type-F Virtual Private Gateway (VPG) and attach the Air SIM to the VPG. If your Air SIM device was online while attaching it to a VPG, you must also delete the ongoing session, or disconnect and reconnect, in order for the SIM to reconnect using the VPG.
Once you have prepared the VPG and Air SIM, you can begin capturing packets.
Creating a Packet Capture Session
Creating a packet capture session will incur fees. Refer to the Pricing & Fee Schedule for more information.
You can create a packet capture session from the User Console.
-
Login to the User Console. From the Menu, open the VPG screen.
-
From the list of VPGs, click the name of the VPG you want to capture packets from to open its settings page.
-
Click the Packet capture sessions tab.
-
Click the Start capturing button:
-
Enter the settings for the session:
- Prefix - A custom string to identify this specific packet capture session.
- Duration - How long the packet capture session should last, in seconds.
The Prefix used for a packet capture session can only consist of numbers, letters, underscores, and hyphens, and must be 100 characters or less.
Then click the Start capturing button.
Once you create a packet capture session, Peek will begin initializing the session. The status will be displayed in the list of packet capture sessions.
Checking a Packet Capture Session Status
From the packet capture session tab, click the icon to reload the packet capture session status.
Each packet capture session will have one of the following statuses:
Status | Meaning | Packets Captured? |
---|---|---|
Requested | A packet capture session was initiated. | — |
Accepted | The packet capture session is being prepared. | — |
Capturing | The packet capture session is in progress. | Yes |
Post Processing | The packet capture session has finished, and Peek is preparing the pcap file. |
— |
Done | The packet file is ready for download. | — |
Failed | Failed to create a packet capture session. | — |
Downloading a Packet Capture File
Once a packet capture session status is Done, you can download the packet capture file. Click the Get link button next to the packet capture session that you want to download.
A secure, temporary download link will be generated. Click the link again in order to begin downloadin the pcap
file.
Deleting a Packet Capture File
Although the packet capture session will be deleted automatically after 7 days, you can also manually delete the session if necessary. Click the icon next to a packet capture session to delete it.
Programmatic Usage
You can also start and view packet caputre sessions, as well as download and delete the capture results using the Soracom API and Soracom CLI. You will need to have the VPG ID handy.
Soracom API
To access the Soracom API, first use the auth API to obtain an API Key and Token. Refer to the API Reference Guide for instructions on how to use the API Key and Token in API requests.
Then, use the createPacketCaptureSession API to start a new packet capture session:
curl -X POST \
> -H 'X-Soracom-API-Key: <MY-API-KEY>' \
> -H 'X-Soracom-Token: <MY-TOKEN>' \
> -d '{
> "duration": "600",
> "prefix": "my-capture"
> }'/
> https://g.api.soracom.io/v1/virtual_private_gateways/<VPG-ID>/packet_capture_sessions
You can use the listPacketCaptureSessions API to check the status of your packet capture session:
curl -X GET \
> -H 'X-Soracom-API-Key: <MY-API-KEY>' \
> -H 'X-Soracom-Token: <MY-TOKEN>' \
> https://g.api.soracom.io/v1/virtual_private_gateways/<VPG-ID>/packet_capture_sessions
Once a packet capture session has finished, use the packet capture sessionId
with the
getPacketCaptureSession
API to generate a download link for the packet capture file:
curl -X GET \
> -H 'X-Soracom-API-Key: <MY-API-KEY>' \
> -H 'X-Soracom-Token: <MY-TOKEN>' \
> https://g.api.soracom.io/v1/virtual_private_gateways/<VPG-ID>/packet_capture_sessions/<SESSION-ID>
This API will return a JSON response which contains a link to the pcap
file. You can use this link to download the file directly.
Finally, to delete a packet capture session, use the deletePacketCaptureSession API
Soracom CLI
To use the Soracom CLI, you must first configure it to authenticate with your account information, authorization key, or SAM user credentials.
Then, run the following command to initiate a packet capture session:
soracom vpg create-packet-capture-session --vpg-id <VPG-ID> --duration 600 --prefix "my-packet-capture" --coverage-type g
To check the status of a packet capture session, use this command:
Once a packet capture session has finished, use the following command to generate a download link for the packet capture file:
soracom vpg get-packet-capture-session --vpg-id <VPG-ID> --session-id <SESSION-ID> --raw-output --coverage-type g
This command will return a link to the pcap
file. You can use this link to download the file directly.
Finally, to delete a packet capture session, use the following command: