Collect packet captures (PCAPs)
After a packet capture is requested and the capture is collected, the output is contained within one or more files in PCAP file format. Before starting a full
type packet capture, you must first follow instructions for configuring a bucket.
Send a packet capture request
Currently, when a packet capture is requested, packets flowing at Cloudflare’s global network through the Magic Transit system are captured. The default API field for this is "system": "magic-transit"
, both for the request and response.
Packet capture limits
Sample and full
time_limit
: The minimum value is1
seconds and maximum value is300
seconds.packet_limit
: The minimum value is1
packet and maximum value is10000
packets.
Full
byte_limit
: The minimum value is1
byte and maximum value is1000000000
bytes.
- Log in to your Cloudflare dashboard, and select you account.
- Select Magic Transit or Magic WAN.
- In Captures, select Start a capture.
- Select the Captures tab > Start a capture.
- Choose the type of capture you want to perform, and select Next.
- Fill out the required fields to begin the capture and then select Start.
The main Packet captures page displays a list of captures.
The PCAPs API needs both system
and type
to be specified to start a capture. A PCAP’s system
is the product or logical subsystem where packets are captured, and a PCAP’s type
is how the captured packets are built into a PCAP file.
Currently, you can only send one collect request per minute for sample PCAPs, and you can only have one running or pending full PCAP at a time. For full PCAP requests, refer to the required parameters listed at Create full PCAP requests. Note that full packet captures require two more parameters than sample packets. The full PCAP request endpoint also contains optional fields you can use to limit the amount of packets captured. Both full and sample packet requests contain an optional Leave While the collection is in progress, the response returns the To create a sample PCAP request, send a JSON body with the required parameter listed at Create sample PCAP request. Leave The response is a JSON body that contains the details of the job running to build the packet capture. The response contains a unique identifier for the packet capture request along with the details sent in the request.Full PCAP
filter_v1
parameter you can use to filter packets by IPv4 Source address, for example. For a full list of the filter options, refer to the parameter lists above.filter_v1
empty to collect all packets without any filtering.Full PCAP example request
status
field as pending
. You must wait for the PCAP collection to complete before downloading the file. When the PCAP is ready to download, the status changes to success
.Full PCAP example response
Sample PCAP
filter_v1
to collect all packets without any filtering.Sample PCAP example request
Sample PCAP example response
Check packet capture status
- Log in to your Cloudflare dashboard, and select you account.
- Select Magic Transit or Magic WAN.
- In Packet captures, select Start a capture.
- Select the Captures tab.
To check the status of a running job, send a request to the endpoint and specify the PCAP identifier. The PCAP identifier is received in the response of a collect request as shown in the previous step.
curl https://api.cloudflare.com/client/v4/accounts/{account_id}/pcaps/{pcap_id} \
--header 'Content-Type: application/json' \
--header 'X-Auth-Email: <YOUR_EMAIL>' \
--header 'X-Auth-Key: <API_KEY>'
The response will be similar to the one received when requesting a PCAP collection.
Sample PCAP example result{ "result": { "id": "6d1f0aac13cd40e3900d29f5dd0e8a2b", "submitted": "2021-12-20T17:29:20.641845Z", "filter_v1": { "source_address": "1.2.3.4", "source_port": 123, "destination_address": "5.6.7.8", "destination_port": 80, "protocol": 6 }, "time_limit": 120, "status": "success", "packets_remaining": 0, "type": "simple", "system": "magic-transit" }, "success": true, "errors": [], "messages": []
}
The capture status displays one of the following options:
- Complete: The capture request is done and ready for download.
- In progress: The capture request was captured but still processing.
- Failure: The capture failed. If this occurs, verify your ownership information.
Download packet captures
After your request finishes processing, you can download your packet captures.
- Log in to your Cloudflare dashboard, and select you account.
- Select Magic Transit or Magic WAN.
- In Packet captures, select Start a capture.
- Select the Captures tab.
- Locate your packet capture you want to download, and select Download.
Packet captures are available to download when the Status displays Success.
For more information on how to process multiple saved capture files into a single output file, refer to Wireshark’s mergecap documentation.
Full PCAPs
To obtain full PCAPs, download the files from the bucket specified in destination_conf
after the PCAP’s status is success
. You may find multiple files named pcap_<pcap_id>.pcap
per capture as captures can occur across multiple machines.
Sample PCAPs
Once the sample PCAP collection is complete, you can download the PCAP by specifying the PCAP identifier used earlier.
curl https://api.cloudflare.com/client/v4/accounts/{account_id}/pcaps/{pcap_id}/download \
--header 'Content-Type: application/json' \
--header 'X-Auth-Email: <YOUR_EMAIL>' \
--header 'X-Auth-Key: <API_KEY>' \
--output download.pcap
List packet captures
- Log in to your Cloudflare dashboard, and select you account.
- Select Magic Transit or Magic WAN.
- In Packet captures, select Start a capture.
- Select the Captures tab.
The list of packet captures associated with your account displays.
To view a list of sent requests, use the following command:
List request examplecurl https://api.cloudflare.com/client/v4/accounts/{account_id}/pcaps \
--header 'Content-Type: application/json' \
--header 'X-Auth-Email: <YOUR_EMAIL>' \
--header 'X-Auth-Key: <API_KEY>'
The response returns an array that includes up to 50 sent requests, which includes completed and ongoing requests.
List response example{ "result": [ { "id": "43adab5adeca4dab9c51f4b7f70f2ec3", "submitted": "2021-12-15T03:04:09.277394Z", "filter_v1": {}, "time_limit": 120, "status": "success", "packets_remaining": 0, "type": "simple", "system": "magic-transit" } ], "success": true, "errors": [], "messages": []
}