Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

Starting and Stopping a Tunnel Flow Data Collection

 

Use the Cloud Analytics Engine CA API tunnel data resource to start or stop generating application flow path analytics data over a tunnel.

GET start/tunnel Resource

Use the GET start/tunnel CA API to instruct CA to generate probes and start collecting information from the network about an overlay tunnel flow. You can also use this API call to modify the specified data collection parameters for a tunnel flow that is already active. This is an asynchronous API.

Request Parameters:

  • Table 1 describes the GET start/tunnel request parameters, which include tuple values identifying the tunnel flow, and optional parameters specifying what to collect from the available tunnel flow data options.

Table 1: GET start/tunnel Resource Parameters

Flow Resource Parameters

Description

src

(String) VTEP Source IPv4 address.

dst

(String) VTEP endpoint Ipv4 address.

sport

(Numeric) Source port corresponding to the protocol type for the encapsulated application flow.

vnid

(Numeric) VXLAN network identifier.

appsrc

(String) Source IP address of the application communicating via the tunnel VTEP.

appdst

(String) Destination IP address of the application corresponding to appsrc.

appsmac

(String) Application source MAC address.

appdmac

(String) Application destination MAC address.

sfreq

(Numeric) Sampling frequency for collecting network data (in seconds).

Optional parameter. Default value is 1 second.

nhops

(Numeric) Number of network hops from which to collect analytics data. Data is gathered across all hops until the destination (<=255) if this parameter is not specified.

Optional parameter. Default value is 255.

ntry

(Numeric) Number of tries to attempt in case of a timeout on a given hop. If this parameter is not specified, only a single attempt is made to gather data for the hop.

Optional parameter. Default value is 1 (no retries).

timeout

(Numeric) Timeout (in ms) to wait for the device at a given hop to respond. If the device does not respond back within the timeout, any delayed response is ignored by CA.

Optional parameter. Default value is 30000 ms (30 seconds).

chksum

(Boolean) Enable (“true”) or disable (“false”) checksum computation.

Optional parameter. Default value is “true” or enabled.

bw-ingress

(Boolean) If specified as “true”, measure flow bandwidth at each hop ingress.

Optional parameter. Default value is “false” or do not include bandwidth measurements.

mirror_type

(String) Install mirroring of the indicated type for this flow. Supported mirror type values: “ERSPAN”.

Optional parameter. Default if not specified is no mirror installation.

mirror_dir

(String) Mirror direction. Supported values: “ingress”.

Optional parameter with no default value. If mirror_type is specified, this parameter must also be specified.

mirror_analyzer

(String) Mirror analyzer IP address.

Optional parameter with no default value. If mirror_type is specified, this parameter must also be specified.

Return Codes:

  • EOK—Request was serviced.

  • EAGAIN—Exceeding pending updates for the same tunnel flow. This might happen when the same flow is modified, or there is a previous stop request pending on this tunnel flow.

  • EFAIL—Invalid parameters were provided.

  • E_UNAUTHORIZED—Tunnel flow was initiated by a different client and cannot be started or modified by the originator of this request.

Response Data:

  • None

See Compute Agent Tunnel Data Resource Usage Example for a simple example of a request to start a tunnel flow with required parameters identifying the tunnel flow, the same parameters used subsequently to get collected data from that tunnel flow, and the same parameters used again to stop the flow.

You can also see the following GET data/tunnel example that shows starting an overlay tunnel flow data collection in a KVM topology, and the response data that is returned:

GET stop/tunnel Resource

Use the GET stop/tunnel CA API to instruct CA to stop collecting information from the network about a tunnel flow. This is an asynchronous API.

Request Parameters:

  • The GET stop/tunnel request parameters are the following tuple values that identify the overlay tunnel:

    • src: (String) VTEP source IPv4 address.

    • dst: (String) VTEP endpoint IPv4 address.

    • vnid: (Numeric) VXLAN network identifier.

    • sport: (Numeric) Source port corresponding to the protocol type for the encapsulated application flow.

    • appsrc: (String) Application source IP address communicating on the given tunnel’s VTEP.

    • appdst: (String) Application destination IP address corresponding to appsrc.

Return Codes:

  • EOK—Request was serviced.

  • EFAIL—Invalid parameters were provided.

  • E_UNAUTHORIZED—Tunnel flow was initiated by a different client and cannot be stopped by the originator of this request.

  • E_AoF—No such tunnel flow.

Response Data:

  • None

See Compute Agent Tunnel Data Resource Usage Example for a simple example of a request to stop a tunnel flow data collection, using the same parameters as the GET start/tunnel request that started the tunnel flow.

Compute Agent Tunnel Data Resource Usage Example

The following is a simple example showing a sequence of tunnel data resource CA API web requests to a CA server (IP address 10.94.201.11, port 8080) to start a tunnel flow data collection, retrieve collected data from that tunnel flow, and stop the tunnel flow data collection. The minimum required elements of the tunnel identifier tuple are provided for each request. All requests use the GET method.

  • Start tunnel flow data collection (GET start/tunnel):

    http://10.94.201.11:8080/start/tunnel?src=10.1.1.1&sport=4567&vnid=5&dst=10.1.7.1&

    appdst=10.1.2.5&appmac=44:1e:a1:02:25:c0&dport=9000&appsrc=10.1.2.3&appsmac=9c:8e:99:12:88:2e

  • Request collected tunnel data (GET data/tunnel):

    http://10.94.201.11:8080/data/tunnel?src=10.1.1.1&sport=4567&vnid=5&dst=10.1.7.1&

    appdst=10.1.2.5&appsrc=10.1.2.3

  • Stop tunnel flow data collection (GET stop/tunnel):

    http://10.94.201.11:8080/stop/tunnel?src=10.1.1.1&sport=4567&vnid=5&dst=10.1.7.1&

    appdst=10.1.2.5&appsrc=10.1.2.3