Soracom Peek

SIM Usage

You can capture IP traffic to and from an individual Air for Cellular device directly from the SIM Management section of the User Console. Before starting a new packet capture session, ensure that your device is connected to a network and the subscriber status appears as Online.

Once you have confirmed that your IoT SIM is online, you can begin capturing packets.

You can also capture all packets that pass through a Virtual Private Gateway. This allows you to capture traffic coming from or going to multiple SIMs. For more information, refer to the VPG Usage documentation.

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.

  1. Login to the User Console. From the Menu, open the SIM Management screen.

  2. From the list of subscribers, click the for the SIM you want to capture packets from.

  3. Click the Actions menu, then select Packet Capture.

    https://console.soracom.io

    Packet Capture

  4. The SIM Details dialog will appear. In the Packet capture tab, click the Start capturing button:

    Start a packet capture session

  5. Enter the settings for the session:

    Packet capture session settings

    • 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 tab, click the icon to reload the packet capture session status.

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 was stopped or has finished, and Peek is preparing the pcap file. —
Stopped The packet capture session was stopped, and the packet capture file is ready for download —
Done The packet capture session has finished, and the packet capture file is ready for download. —
Failed Failed to create a packet capture session. —

Stopping a Packet Capture Session

If you need to stop a packet capture session before it has finished, you can do so by clicking the Stop button next to the packet capture session. Any packets captured before the session is stopped will be retained, and you will still be able to download the packet capture file containing any packets captured.

Downloading a Packet Capture File

Once a packet capture session status is Stopped or Done, you can download the packet capture file. Click the Get link button next to the packet capture session that you want to download.

Download packet capture file

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 SIM ID handy.

When using Peek programmatically for an individual SIM, you must use its SIM ID. Using the IMSI of the SIM is not supported.

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 createSimPacketCaptureSession 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/sims/<SIM-ID>/packet_capture_sessions

You can use the listSimPacketCaptureSessions 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/sims/<SIM-ID>/packet_capture_sessions

If you want to stop an ongoing packet capture session, use the stopSimPacketCaptureSession API, passing in the packet capture sessionId:

curl -X POST \
>  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
>  -H 'X-Soracom-Token: <MY-TOKEN>' \
>  https://g.api.soracom.io/v1/sims/<SIM-ID>/packet_capture_sessions/<SESSION-ID>/stop

Once a packet capture session has finished, use the packet capture sessionId with the getSimPacketCaptureSession 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/sims/<SIM-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 deleteSimPacketCaptureSession API

curl -X DELETE \
>  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
>  -H 'X-Soracom-Token: <MY-TOKEN>' \
>  https://g.api.soracom.io/v1/sims/<SIM-ID>/packet_capture_sessions/<SESSION-ID>

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 sims create-packet-capture-session --sim-id <SIM-ID> --duration 600 --prefix "my-packet-capture" --coverage-type g

To check the status of a packet capture session, use this command:

soracom sims list-packet-capture-sessions --sim-id <SIM-ID> --coverage-type g

To stop an ongoing packet capture session, use this command:

soracom sims stop-packet-capture-session --sim-id <SIM-ID> --session-id <SESSION-ID> --coverage-type g

Once a packet capture session has finished, use the following command to generate a download link for the packet capture file:

soracom sims get-packet-capture-session --sim-id <SIM-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:

soracom sims delete-packet-capture-session --sim-id <SIM-ID> --session-id <SESSION-ID> --coverage-type g