- Print
- PDF
This article provides the configuration basics for Sensor agent: actuate.
Overview
Skylight sensor: agent actuate implements support for these performance monitoring sessions:
- RFC5357 Two-way active measurement protocol.
- RFC862 UDP Echo
- RFC792 ICMP Echo
Monitored metrics include methods to assess network one-way and two-way latency (delay), jitter, delay variation, packet loss and several QoS metrics.
The IETF RFC5357 defines a standard mode, here called TWAMP-control and a simplified mode, here called TWAMP-light. Skylight sensor: agent supports TWAMP-light and TWAMP-control in unauthenticated and unencrypted mode.
CAUTION: Using TWAMP-control with the default Docker-bridge NAT/PAT function may cause issues with third party reflectors. If using TWAMP-control behind NAT, you should set the TWAMP control sender IP address field in the configuration to the "outside" IP address of your NAT.
For example, if you run a server with IP address 10.11.12.13 and start up an actuate container with docker on this host, the docker may get IP address 172.1.2.3 inside the container. To successfully use TWAMP-control from this agent, set the TWAMP control sender IP address parameter to "10.11.12.13".
A different solution is to launch the actuate container in host networking mode, and declare the host interface with the AGENTSOURCEINTERFACE=
Agent Actuate Configuration
This section assumes that an actuate agent has already been defined, deployed and registered in the orchestration system through the APIs. See Agent installation guidelines if this has not yet been done.
Configuration Parameters on Agent Level
Each actuate agent holds a number of configuration parameters that relate to the agent itself, and not the monitoring sessions it performs. These configuration parameters do not normally change during the lifetime of an agent, but are static settings like agent name, its unique agentId, which RoadRunner gateway it uses for metrics streaming, and any other agent-wide configuration parameters.
The set of agent level parameters for actuate are:
agentId
This is a UUID string uniquely identifying this agent.
dataGateway
This is a set of two parameters defining the FQDN or IP address of the roadrunner through which the agent will send result data metrics.
Note that this could be a different roadrunner instance than the one used for management, however normally this should be the same roadrunner IP/FQDN, where management uses port 55777/tcp and data metrics streaming using port 55888/tcp.
identification
Under the identification node, the agentName is set, and in the future more details like location, geo-coordinates, etc. will be supported.
reflector
Under the reflector node, there is a list of enable/disable parameters for the TWAMP and UDP echo reflectors for IPv4 and IPv6.
Below is an example showing the GET and response for configuration of agent with ID 0a805c6e-6266-fake-a8e4-afb94a124cd2
GET https://my.tenant.io/api/orchestrate/v3/agents/configuration/0a805c6e-6266-fake-a8e4-afb94a124cd2
RESPONSE
{
"data": {
"attributes": {
"_rev": "1-44ab571a7f7a5f300f94bf82d1bed065",
"agentId": "0a805c6e-6266-fake-a8e4-afb94a124cd2",
"dataGateway": {
"port": 55888,
"server": "192.168.0.222"
},
"identification": {
"agentName": "my-cool-twamp-agent"
},
"reflector": {
"reflectors": [
{
"reflectorType": "twampIpv4",
"enable": true
}
]
}
},
"id": "0a805c6e-6266-fake-a8e4-afb94a124cd2",
"type": "agentConfigs"
}
}
As seen above, the agent configuration contains a revision field _rev in the beginning that is used for configuration consistency. To update an agent's configuration, the _rev string sent in the update query needs to match what the _rev is currently set to. That is, to update an agent's configuration, you should first GET the configuration to find the current _rev string. Then, use that string in the PUT query to apply the changes.
Changing Parameters on Agent Level
The API describes the PUT for changes on an agent's configuration here: API Update agent configuration
Below is an example changing the agent name, and disabling the IPv4 TWAMP reflector on agent with agentId=0a805c6e-6266-fake-a8e4-afb94a124cd2
Remember to first do a GET for the agent configuration to fetch the current _rev revision value and use that in the PUT query to update the configuration.
PUT
{
"data": {
"type": "agentConfigs",
"attributes": {
"_rev": "1-44ab571a7f7a5f300f94bf82d1bed065",
"agentId": "0a805c6e-6266-43a4-a8e4-afb94a124cd2",
"identification": {
"agentName": "my-even-cooler-agent"
},
"reflector": {
"reflectors": [
{
"reflectorType": "twampIpv4",
"enable": false
}
]
}
}
}
}
Actuate Agent Session Configuration
Session section in the API
The following parameters are configurable for an actuate session.
parameter | twamp-light | twamp-control | echo udp | echo icmp | desc |
---|---|---|---|---|---|
senderAddr | 🗸 | 🗸 | 🗸 | 🗸 | Optional - sender IPv4, IPv6 address or FQDN, defaults to docker internal IP |
senderPort | 🗸 | 🗸 | 🗸 | ✘ | Optional - sender port number, default generated by agent |
senderPayloadSize | 🗸 | 🗸 | 🗸 | 🗸 | Optional - payload size in bytes, default 82 |
senderRate | 🗸 | 🗸 | 🗸 | 🗸 | Optional - packet rate in PPS, default 10 |
senderDscp | 🗸 | 🗸 | 🗸 | 🗸 | Optional - sender DSCP value, default 0 (CS0) |
senderTtl | 🗸 | 🗸 | 🗸 | 🗸 | Optional - sender TTL value, default 255 |
senderVprio | 🗸 | 🗸 | 🗸 | 🗸 | Optional - sender VLAN prio, default 0 |
reflectorAddr | 🗸 | 🗸 | 🗸 | 🗸 | Mandatory - reflector IPv4, IPv6 address or FQDN |
reflectorPort | 🗸 | 🗸 | 🗸 | ✘ | Mandatory (except for ICMP) - reflector port number, default 862 |
reportInterval | 🗸 | 🗸 | 🗸 | 🗸 | Optional - Reporting interval in seconds, default 30 |
controlAddr | ✘ | 🗸 | ✘ | ✘ | Optional - TWAMP control server IPv4, IPv6 address or FQDN |
controlPort | ✘ | 🗸 | ✘ | ✘ | Optional - TWAMP control server port number, default 862 |
controlDscp | ✘ | 🗸 | ✘ | ✘ | Optional - TWAMP control connection DSCP value, default 0 (CS0) |
controlVprio | ✘ | 🗸 | ✘ | ✘ | Optional - TWAMP control connection VLAN prio, default 0 |
controlLegacy | ✘ | 🗸 | ✘ | ✘ | Optional - TWAMP control legacy mode, default false |
Add / delete throughput sessions to an agent
The orchestration can multiple session configurations for each agent, in release 23.12 the recommendation is to not run more than 500 simultaneously to stay within the reference CPU&RAM values. To add and delete sessions, use the POST and DELETE API calls
To add a session -
POST to {{tenant-server}}/api/orchestrate/v3/agents/session
With the configuration in the BODY.
The example below is for TWAMP-light, providing only the minimum required session configuration parameters
{
"data": {
"type": "agentSessions",
"attributes": {
"agentId": "{{agentId}}",
"session": {
"sessionId": "{{sessionId}}",
"sessionName": "my TWAMP session example 😀",
"sessionType": "twamp-stateful",
"enable": true,
"period": "continuous",
"twamp": {
"reflectorAddr": "192.168.12.254",
"reflectorPort": 50862
}
}
}
}
}
Related Documentation and References
throughput - test configuration
Agent: trace- Configuration
Agent: transfer - Configuration
© 2024 Cisco and/or its affiliates. All rights reserved.
For more information about trademarks, please visit: Cisco trademarks
For more information about legal terms, please visit: Cisco legal terms
For legal information about Accedian Skylight products, please visit: Accedian legal terms and tradmarks