Agent: actuate - Configuration
  • 16 Apr 2024
  • 5 Minutes to read
  • Contributors
  • PDF

Agent: actuate - Configuration

  • PDF

Article summary

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= environment variable.


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.

parametertwamp-lighttwamp-controlecho udpecho icmpdesc
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
        }
      }
    }
  }
}

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



Was this article helpful?

Changing your password will log you out immediately. Use the new password to log back in.
First name must have atleast 2 characters. Numbers and special characters are not allowed.
Last name must have atleast 1 characters. Numbers and special characters are not allowed.
Enter a valid email
Enter a valid password
Your profile has been successfully updated.