Skip to main content

REST APIs for 22.2

Filtering and Aggregating Traffic

This Public Stable API method allows you to handle broadcast and multicast traffic better, save storage in the traffic database, and reduce the stress of the whole data pipeline.

Windows-heavy environments can have a large amount of broadcast or multicast traffic, which can be as much as 50% in syslog data and 30% in traffic data. Because some broadcast and multicast data might not be useful for writing policies, this API provides a function to filter out or aggregate the broadcast and multicast traffic that is not useful.

Note

This API is implemented in Supercluster.

Note

Only administrators and users with appropriate privileges can make filtering changes.

Traffic Collector API Methods

Use these methods to get, create, update, or delete a traffic collector.

Functionality

HTTP

URI

Get a traffic collector collection

GET

[api_version][org_href]/settings/traffic_collector

Get a specific collector instance

GET

[api_version][org_href]/settings/traffic_collector/:uuid

Create a traffic collector

POST

[api_version][org_href]/settings/traffic_collector

Update a specific traffic collector instance

PUT

[api_version][org_href]/settings/traffic_collector/:uuid

Delete a specific traffic collector instance

DELETE

[api_version][org_href]/settings/traffic_collector/:uuid

Parameters

Use the following required and optional parameters for the query.

Parameters

Description

Type

Required

org_id

Required for all methods: GET, POST, PUT, and DELETE

Integer

Yes

transmission

For the transmission type, choose broadcast, multicast or unicast

*unicast was also available in the release 21.5.20

String

action

Required for POST and optional for PUT.

Drop or aggregate the target traffic:

  • If you select "drop," the PCE drops all the traffic that matches the filters you supply. The data will be lost forever.

  • If you select "aggregate," the PCE performs aggregation on broadcast traffic and multicast traffic . If one broadcast or multicast traffic flow is received by multiple workloads, all reported flows on the same traffic are aggregated into one record in the traffic database, and the destination workload information will be lost.

  • PUT method will fail if you change the aggregator from “broadcast” to “multicast” because the default port and protocol will not pass the validation step.

String

target

(POST) The target object has the following properties:

  • dst_port: Optional

  • proto: Required

  • dst_ip: A single IP address or CIDR; optional

  • src_port: Allows users to filter traffic based on the source port.

If dst_port and dst_ip are not specified for the target session, traffic is dropped on "all ips" and "all ports" by default.

PUT method will fail If the traffic filter you want to modify has “ANY” in port or protocol field, and you want to modify other fields in this filter. The change will fail because the default port and protocol will not pass the validation step.

Object

Integer

Integer

String

No

Yes

No

traffic_collector_setting_id

traffic_collector setting UUID.

Required for PUT, GET (for a specific traffic collector), and DELETE

String

Examples for Traffic Collector

Broadcast Transmission and Drop Action

curl 'https://pce.my-company.com:8443/api/v2/orgs/1/settings/traffic_collector' -H 'Origin: https://pce.my-company.com:8443' -H 'Accept-Encoding: gzip,deflate, br' -H 'content-type: application/json' -H 'accept: application/json' -H 'Referer: https://pce.my-company.com:8443/' -i -u api_1dfe2432a7b314ee6:'21c10ea1a4ad38d76ef22977e8ac45bc10839c5cc6ebffd650eae4f95dc5b364'--data-binary '{"transmission": "broadcast","action": "drop","target":{"proto": 17,"dst_port": 20, "dst_ip":"10.255.255.255"}}' --compressed

Multicast Transmission and Aggregate Action

curl 'https://pce.my-company.com:8443/api/v2/orgs/1/settings/traffic_collector' -H 'Origin: https://pce.my-company.com:8443' -H 'Accept-Encoding: gzip, deflate, br' -H 'content-type: application/json' -H 'accept: application/json' -H 'Referer: https://pce.my-company.com:8443/' -i -u api_1dfe2432a7b314ee6:'21c10ea1a4ad38d76ef22977e8ac45bc10839c5cc6ebffd650eae4f95dc5b364'--data-binary '{"transmission": "multicast","action": "aggregate"} ' --compressed

Example Response

{
	"$schema": "http://json-schema.org/draft-04/schema#",
	"type": "object",
	"required": ["href", "transmission", "action"],
	"properties":{
		"href": {
			"description": "URI of the destination",
			"type": "string"
		},
		"transmission":{
			"description":"transmission type: broadcast/multicast",
			"type":"string",
			"enum":[
			"broadcast",
			"multicast"
			]
		},
		"target":{
			"type":"object",
			"required":[
			"proto"
			],
			"properties":{
			"dst_port":{
			"type":"integer"
			},
			"proto":{
			"type":"integer"
			},
			"dst_ip":{
			"type":"string",
			"description": "single ip address or CIDR"
			}
			}
		},
		"action":{
			"description":"drop or aggregate the target traffic",
			"type":"string",
			"enum":[
			"drop",
			"aggregate"
			]
			}
		}
	}