pcaps

Creates, updates, deletes, gets or lists a pcaps resource.

Overview

Name	pcaps
Type	Resource
Id	cloudflare.magic_transit.pcaps

Fields

The following fields are returned by SELECT queries:

list

List packet capture requests response.

Name	Datatype	Description
id	string	The ID for the packet capture. (example: 66802ca5668e47a2b82c2e6746e45037)
colo_name	string	The name of the data center used for the packet capture. This can be a specific colo (ord02) or a multi-colo name (ORD). This field only applies to full packet captures. (example: ord02)
byte_limit	number	The maximum number of bytes to capture. This field only applies to full packet captures.
destination_conf	string	The full URI for the bucket. This field only applies to full packet captures. (example: s3://pcaps-bucket?region=us-east-1)
error_message	string	An error message that describes why the packet capture failed. This field only applies to full packet captures. (example: No packets matched the filter in the time limit given. Please modify the filter or try again.)
filter_v1	object	The packet capture filter. When this field is empty, all packets are captured.
offset_time	string (date-time)	The RFC 3339 offset timestamp from which to query backwards for packets. Must be within the last 24h. When this field is empty, defaults to time of request. (example: 2020-01-01T08:00:00Z)
packets_captured	integer	The number of packets captured.
status	string	The status of the packet capture request. (unknown, success, pending, running, conversion_pending, conversion_running, complete, failed) (example: success)
stop_requested	string (date-time)	The RFC 3339 timestamp when stopping the packet capture was requested. This field only applies to full packet captures.
submitted	string	The RFC 3339 timestamp when the packet capture was created. (example: 2020-01-01T08:00:00Z)
system	string	The system used to collect packet captures. (magic-transit) (example: magic-transit)
time_limit	number	The packet capture duration in seconds.
type	string	The type of packet capture. Simple captures sampled packets, and full captures entire payloads and non-sampled packets. (simple, full) (example: simple)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
list	select	account_id		Lists all packet capture requests for an account.
create	insert	account_id, system, time_limit, type		Create new PCAP request for account.
create_ownership	exec	account_id, destination_conf		Adds an AWS or GCP bucket to use with full packet captures.
stop	exec	pcap_id, account_id		Stop full PCAP.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
account_id	string	The Cloudflare account ID.
pcap_id	string

SELECT examples

list

Lists all packet capture requests for an account.

SELECT
id,
colo_name,
byte_limit,
destination_conf,
error_message,
filter_v1,
offset_time,
packets_captured,
status,
stop_requested,
submitted,
system,
time_limit,
type
FROM cloudflare.magic_transit.pcaps
WHERE account_id = '{{ account_id }}' -- required
;

INSERT examples

create

Create new PCAP request for account.

INSERT INTO cloudflare.magic_transit.pcaps (
filter_v1,
offset_time,
packet_limit,
system,
time_limit,
type,
byte_limit,
colo_name,
destination_conf,
account_id
)
SELECT 
'{{ filter_v1 }}',
'{{ offset_time }}',
{{ packet_limit }},
'{{ system }}' /* required */,
{{ time_limit }} /* required */,
'{{ type }}' /* required */,
{{ byte_limit }},
'{{ colo_name }}',
'{{ destination_conf }}',
'{{ account_id }}'
RETURNING
errors,
messages,
result,
success
;

Manifest

# Description fields are for documentation purposes
- name: pcaps
props:
  - name: account_id
    value: "{{ account_id }}"
    description: Required parameter for the pcaps resource.
  - name: filter_v1
    description: |
      The packet capture filter. When this field is empty, all packets are captured.
    value:
      destination_address: "{{ destination_address }}"
      destination_port: {{ destination_port }}
      protocol: {{ protocol }}
      source_address: "{{ source_address }}"
      source_port: {{ source_port }}
  - name: offset_time
    value: "{{ offset_time }}"
    description: |
      The RFC 3339 offset timestamp from which to query backwards for packets. Must be within the last 24h. When this field is empty, defaults to time of request.
  - name: packet_limit
    value: {{ packet_limit }}
    description: |
      The limit of packets contained in a packet capture.
  - name: system
    value: "{{ system }}"
    description: |
      The system used to collect packet captures.
    valid_values: ['magic-transit']
  - name: time_limit
    value: {{ time_limit }}
    description: |
      The packet capture duration in seconds.
  - name: type
    value: "{{ type }}"
    description: |
      The type of packet capture. `Simple` captures sampled packets, and `full` captures entire payloads and non-sampled packets.
    valid_values: ['simple', 'full']
  - name: byte_limit
    value: {{ byte_limit }}
    description: |
      The maximum number of bytes to capture. This field only applies to `full` packet captures.
  - name: colo_name
    value: "{{ colo_name }}"
    description: |
      The name of the data center used for the packet capture. This can be a specific colo (ord02) or a multi-colo name (ORD). This field only applies to `full` packet captures.
  - name: destination_conf
    value: "{{ destination_conf }}"
    description: |
      The full URI for the bucket. This field only applies to `full` packet captures.

Lifecycle Methods

create_ownership

Adds an AWS or GCP bucket to use with full packet captures.

EXEC cloudflare.magic_transit.pcaps.create_ownership 
@account_id='{{ account_id }}' --required 
@@json=
'{
"destination_conf": "{{ destination_conf }}"
}'
;

stop

Stop full PCAP.

EXEC cloudflare.magic_transit.pcaps.stop 
@pcap_id='{{ pcap_id }}' --required, 
@account_id='{{ account_id }}' --required
;