TWAMP Functions¶
sth::emulation_twamp_config¶
Purpose¶
This function is a Spirent Extension created to configure, modify, or delete a TWAMP client/server on the specified device.
The Two-Way Active Measurement Protocol (TWAMP) uses the methodology and architecture of OWAMP [RFC4656] for the measurement of two-way or round-trip metrics, in addition to the one-way metrics of OWAMP. TWAMP employs time stamps applied at the echo destination (reflector) to enable greater accuracy . The TWAMP measurement architecture is typically two hosts with specific roles.
TWAMP Light, as defined in Appendix I of RFC 5357, which defines a light version of the TWAMP protocol, a stateless version of TWAMP where test parameters are predefined instead of negotiated.
Synopsis¶
Note
M indicates that the argument is Mandatory .
sth::emulation_twamp_config
[-mode {create | modify | delete} M]
[-handle <device_handle> M]
[-type {server | client}]
[-connection_retry_cnt <0-65535>]
[-connection_retry_interval <10-300>]
[-ipv6_if_type {global | linklocal}]
[-ip_version {ipv4 | ipv6}]
[-peer_ipv4_addr < a.b.c.d >]
[-peer_ipv6_addr <aaaa:bbbb:cccc:dddd:eeee:ffff:gggg:hhhh>]
[-scalability_mode {discard_test_session_statistics | normal}]
[-enable_light {true | false}]
[-udp6_checksum {true | false}]
[-use_partial_block_state {true | false}]
[-server_enable_light {true | false}]
[-server_udp6_checksum {true | false}]
[-server_use_partial_block_state {true | false}]
[-server_ipv6_if_type {global | linklocal}]
[-server_ip_version {ipv4 | ipv6}]
[-server_mode {unauthenticated}]
[-server_willing_to_participate {true | false}]
[-server_local_udp_port <integer>]
Arguments¶
-
-handle¶ Specifies the device handle on which the TWAMP client/server will be created. This argument is Mandatory .
-
-mode¶ Specifies the action to perform. Possible values are create, modify and delete. This argument is Mandatory . The modes are described below:
create Creates a TWAMP client/server on the provided device handle. Use -type to specify the type of TWAMP to be created. modify Modifies the configured TWAMP client/server delete Deletes the TWAMP client/server on the device specified by -handle
-
-type¶ Specifies the type of TWAMP to be configured. This argument is mandatory. Possible values are:
client TWAMP client server TWAMP server
-
-connection_retry_cnt¶ Specifies the number of times to attempt a connection before timing out. Possible values range from 0 to 65535. The default value is 100.
-
-connection_retry_interval¶ Specifies the number of seconds to wait between connection attempts. Possible values range from 10 to 300. The default value is 30.
-
-ipv6_if_type¶ Specifies the source IPv6 address type for the TWAMP client. Possible values are:
linklocal Link local IPv6 address from the emulated device global Global address from the emulated deviceThe default value is global.
-
-ip_version¶ Specifies the IP version of the TWAMP client. Possible values are ipv4 and ipv6. The default value is ipv4.
-
-peer_ipv4_addr¶ Specifies the IPv4 address of the peer (DUT port). The value must be in IPv4 format. The default value is 192.85.1.1.
-
-peer_ipv6_addr¶ Specifies the IPv6 address of the peer (DUT port). The value must be in IPv6 format. The default value is 2001::1.
-
-scalability_mode¶ Specifies the scalability mode. Possible values are described below:
Normal Includes test session result collection discard_test_session_statistics Discards test session result collection. This can reduce the demand on the processor for large-scale testing
The default value is normal.
-
-enable_light¶ Specifies whether to enable or disable the TWAMP Light. Possible values are true and false. The default value is false.
-
-udp6_checksum¶ Specifies whether to allow zero UDPv6 checksum. Possible values are true and false. The default value is false.
-
-use_partial_block_state¶ Specifies whether to use partial block state. Possible values are true and false. The default value is false.
-
-server_enable_light¶ Specifies whether to enable or disable the TWAMP Light server. Possible values are true and false. The default value is false.
-
-server_udp6_checksum¶ Specifies whether to allow zero UDPv6 checksum for the TWAMP server. Possible values are true and false. The default value is false.
-
-server_use_partial_block_state¶ Specifies whether to use partial block state for the TWAMP server. Possible values are true and false. The default value is false.
-
-server_ipv6_if_type¶ Specifies the source IPv6 address type for the TWAMP server. Possible values are:
linklocal Link local IPv6 address from the emulated device global Global address from the emulated deviceThe default value is global.
-
-server_ip_version¶ Specifies the IP version of the TWAMP server. Possible values are ipv4 and ipv6. The default value is ipv4.
-
-server_mode¶ Specifies the security mode. Currently Spirent HLTAPI only supports one mode. Possible value is unauthenticated. The default value is unauthenticated.
-
-server_willing_to_participate¶ Specifies the bit value in the modes field. Possible values are true and false. The default value is true.
-
-server_local_udp_port¶ Specifies the local UDP port or port list for the TWAMP server. The default value is 862.
Arguments Unsupported by Save as HLTAPI¶
This function is currently not supported by Save as HLTAPI.
Return Values¶
Depending on the specific language that HLTAPI uses, the function returns a keyed list/dictionary/hash (See Introduction for more information on return value formats) using the following keys (with corresponding data):
handle Handle of the TWAMP client when -type is client; handle of
the TWAMP server when -type is server
status Success (1) or failure (0) of the operation
log An error message (if the operation failed)
Description¶
The sth::emulation_twamp_config function creates, modifies, or deletes TWAMP
clients/servers on the specified device. Use the -mode argument to specify the
action to perform. (See the -mode argument description for information about the
actions.)
When you configure a TWAMP, use -handle to specify the device on which the TWAMP
client/server will be created. (The device handle value is contained in the keyed
list returned by the sth::emulation_device_config function.)
If the performed action fails, Spirent HLTAPI returns an error message.
Examples¶
To create a TWAMP client on device1:
set device_ret2 [sth::emulation_twamp_config\
-mode create\
-handle $devicehandle1\
-type client\
-connection_retry_cnt 200\
-ip_version ipv4\
-peer_ipv4_addr 192.85.1.1\
-scalability_mode normal \
-connection_retry_interval 40 \
]
To create a TWAMP server on device2:
set device_ret3 [sth::emulation_twamp_config\
-mode create\
-handle $devicehandle2\
-type server\
-server_ip_version ipv4 \
-server_mode unauthenticated \
-server_willing_to_participate true\
]
sth::emulation_twamp_session_config¶
Purpose¶
This function is a Spirent Extension created to configure, modify, or delete a TWAMP session on the specified TWAMP client
Synopsis¶
Note
M indicates that the argument is Mandatory .
sth::emulation_twamp_session_config
[-handle <device_handle | session_handle> M]
[-mode {create | modify | delete} M]
[-dscp <0-63>]
[-duration <0 - 4294967295>]
[-duration_mode {continuous | packets | seconds}]
[-frame_rate <1-1000>]
[-pck_cnt <0 - 4294967295>]
[-padding_len <27-9000>]
[-padding_pattern {random | user_defined}]
[-padding_user_defined_pattern <ANY>]
[-scalability_mode {discard_test_session_statistics | normal}]
[-session_name <string>]
[-session_dst_udp_port <1-65535>]
[-session_src_udp_port <1-65535>]
[-start_delay <0 - 4294967295>]
[-timeout <0 - 4294967295>]
[-ttl <1-255>]
Arguments¶
-
-handle¶ Specifies the device handle on which the TWAMP client is created when -mode is create. Specifies the session handle when -mode is modify or delete.
-
-mode¶ Specifies the action to perform. Possible values are create, modify, and delete. This argument is mandatory. The modes are described below:
create Creates TWAMP client session on the provided device handle modify Modifies the configurations for the TWAMP client session specified by -handle delete Deletes the TWAMP client session specified by -handle
-
-dscp¶ Specifies the Differentiated Service Code Point (DSCP) value. Possible values range from 0 to 63. The default value is 0.
-
-duration¶ Number of seconds to run the test session. This argument is only available when duration_mode is set to seconds. Possible values range from 0 to 4294967295. The default value is 60.
-
-duration_mode¶ Determines how the test duration is defined. Possible values are:
seconds Test duration by seconds packets Test duration by packets continuous Continuous mode
The default value is seconds.
-
-frame_rate¶ Specifies the rate at which to send TWAMP-Test packets, in frames per second. Possible values range from 1 to 1000. The default value is 10.
-
-pck_cnt¶ Specifies the number of packets to run the test session. This argument is only available when -duration_mode is set to packets. Possible values range from 0 to 4294967295. The default value is 100.
-
-padding_len¶ Specifies the number of octets to be appended to a normal OWAMP-Test packet. Possible values range from 27 to 9000. The default value is 128.
-
-padding_pattern¶ Specifies the type of data to be used for padding. Possible values are:
user_defined Specify a user-defined bit padding pattern random Use a random format for the padding patternThe default value is random.
-
-padding_user_defined_pattern¶ Specifies the bit pattern for filling the padding. This argument is only available when -padding_pattern is set to user_defined. The default value is 0x0000.
-
-scalability_mode¶ Specifies the scalability mode. Possible values are described below:
normal Includes test session result collection discard_test_session_statistics Discards test session result collection. This can reduce the demand on the processor for large-scale testing
The default value is normal.
-
-session_name¶ Specifies the text name for the test session
-
-session_dst_udp_port¶ Specifies the UDP port to which TWAMP-Test packets are sent by the Session-Reflector. Possible values range from 1 to 65535. The default value is 5450.
-
-session_src_udp_port¶ Specifies the UDP port from which TWAMP-Test packets are sent by the Session-Sender. Possible values range from 1 to 65535. The default value is 5450.
-
-start_delay¶ Specifies the number of seconds to wait between receiving an Accept-Session message and sending the first TWAMP-Test packet. Possible values range from 0 to 4294967295. The default value is 5.
-
-timeout¶ Specifies the number of seconds that the Session-Reflector waits after receiving a Stop-Sessions message. Possible values range from 0 to 4294967295. The default value is 5.
-
-ttl¶ Specifies the time to live in seconds. Possible values range from 1 to 255. The default value is 255.
Arguments Unsupported by Save as HLTAPI¶
This function is currently not supported by Save as HLTAPI.
Return Values¶
Depending on the specific language that HLTAPI uses, the function returns a keyed list/dictionary/hash (See Introduction for more information on return value formats) using the following keys (with corresponding data):
handle TWAMP client test session handle when mode is create
status Success (1) or failure (0) of the operation
log An error message (if the operation failed)
Description¶
The sth::emulation_twamp_config function creates, modifies, or deletes a TWAMP
session on the specified TWAMP client. Use the -mode argument to specify the
action to perform. (See the -mode argument description for information about the
actions.)
If the performed action fails, Spirent HLTAPI returns an error message. For example, if the user tries to configure a non-existing TWAMP session handle in the modify mode, an error message will be returned.
Examples¶
To create a session on the specified TWAMP client:
set device_ret4 [sth::emulation_twamp_session_config\
-mode create\
-handle $devicehandle1\
-dscp 2\
-duration 120\
-duration_mode seconds\
-frame_rate 50\
-pck_cnt 200\
-padding_len 140\
-session_dst_udp_port 5450\
-session_src_udp_port 5451\
-start_delay 6\
-timeout 60\
-ttl 254\
-padding_pattern random\
-scalability_mode normal\ ]
sth::emulation_twamp_control¶
Purpose¶
This function is a Spirent Extension created to control the specified TWAMP emulation
Synopsis¶
Note
M indicates that the argument is Mandatory .
sth::emulation_twamp_control
[-mode {start|stop|establish|request_twamp_sessions|
start_twamp_sessions|stop_twamp_sessions|pause_twamp_session_traffic|
resume_twamp_session_traffic} M]
[-handle <device_handle_list>
[-port_handle <port_handle_list>]
[-delay_time <0 - 4294967295>]
Arguments¶
-
-handle¶ Specifies a list of TWAMP client or server handles to be controlled. You must specify either -port_handle or -handle, but not both.
-
-port_handle¶ Specifies a list of ports on which the TWAMP devices will be controlled. You must specify either -port_handle or -handle, but not both.
-
-mode¶ Specifies the action to perform. This argument is Mandatory . Possible values are:
start Starts the TWAMP emulation. For a TWAMP server, sets the server to listen to incoming TCP connections from clients on port 862. For a TWAMP client, initializes a control connection to the server. After the connection is established, sends a Request-TW-Session message and a Start-Session message. stop Stops the TWAMP emulation. For a TWAMP server, closes the control connection to the client and stops listening for additional incoming connection requests. For a TWAMP client, stops all test sessions and closes the control connection to the server. establish Starts TWAMP emulation. For a TWAMP server, sets the server to listen to incoming TCP connections from clients on port 862. For a TWAMP client, initializes a control connection to the server. request_twamp_session Sends a Request-TW-Session message. Only valid for TWAMP clients. start_twamp_sessions Sends a Start-Session message followed by TWAMP-Test packets. Only valid for TWAMP clients. stop_twamp_sessions Sends a Stop-Sessions message and stops sending TWAMP-Test packets. Only valid for TWAMP clients. pause_twamp_session_traffic Stops sending TWAMP-Test packets to simulate a broken connection. Only valid for TWAMP clients. resume_twamp_session_traffic Resumes sending TWAMP-Test packets after pausing the TWAMP session traffic. Only valid for TWAMP clients.
-
-delay_time¶ - Specifies the number of seconds to wait before sending TWAMP-Test packets. This argument is only available when -mode is set to start_twamp_sessions. Possible values range from 0 to 4294967295. The default value is 0.
Return Values
Depending on the specific language that HLTAPI uses, the function returns a keyed list/dictionary/hash (See Introduction for more information on return value formats) using the following keys (with corresponding data):
status Success (1) or failure (0) of the operation
log An error message (if the operation failed)
Description¶
The sth::emulation_twamp_control function controls the TWAMP emulation. Use the
-mode argument to specify the action to perform. (See the -mode argument
description for information about the actions.)
When you specify an action, you must specify either -port handle or -handle, but not both. Spirent HLTAPI applies the specified action to all of the sessions associated with the specified port or device.
Examples¶
To start a TWAMP server:
set server start [sth::emulation_twamp_control\
-handle $devicehandle2\
-mode start\ ]
To start a TWAMP client:
set client start [sth::emulation_twamp_control\
-handle $devicehandle1\
-mode start\ ]
sth::emulation_twamp_stats¶
Purpose¶
This function is a Spirent Extension created to get specified TWAMP statistics
Synopsis¶
Note
M indicates that the argument is Mandatory .
sth::emulation_twamp_stats
[-mode {state summary|client server|test session|port_test_session|
aggregated_client|aggregated_server} M]
[-handle <device_handle>]
[-port_handle <port_handle>]
Arguments¶
-
-handle¶ Specifies the TWAMP client or server device from which the statistics will be returned. You must specify either -port_handle or -handle, but not both.
-
-port_handle¶ Specifies the port handle from which the statistics will be returned. You must specify either -port_handle or -handle, but not both.
-
-mode¶ The statistics mode for the configured TWAMP. This argument is mandatory. Possible values are:
client TWAMP client results server TWAMP server results test_session TWAMP test session results state_summary TWAMP state results aggregated_client TWAMP port aggregated client results aggregated_server TWAMP port aggregated server results port_test_session TWAMP port aggregated test session results
Return Values¶
Depending on the specific language that HLTAPI uses, the function returns a keyed list/dictionary/hash (See Introduction for more information on return value formats) using the following keys (with corresponding data):
status Success (1) or failure (0) of the operation
log An error message (if the operation failed)
When mode is test_session, the following keys will be returned:
avg_jitter Average jitter reported in microseconds
avg_latency Average latency reported in microseconds
avg_server_processing_time Average server processing time reported
in microseconds
max_latency Maximum latency reported in microseconds
max_server_processing_time Maximum server processing time reported
in microseconds
max_jitter Minimum jitter reported in microseconds
min_latency Minimum latency reported in microseconds
min_server_processing_time Minimum server processing time reported
in microseconds
min_jitter Minimum jitter reported in microseconds
When mode is server, the following keys will be returned:
rx_req_tw_sess_cnt Number of Request-TW-Session messages received
rx_start_sess_cnt Number of Start-Session messages received
rx_stop_sess_cnt Number of Stop-Session messages received
State State of the TWAMP server
IDLE The server is idle
STARTED The server is started
tx_accept_sess_cnt Number of Accept-Session messages sent
tx_failed_sess_cnt Number of Stop-Session messages sent
with a non-zero Accept value
tx_start_ack_cnt Number of Start-Ack messages sent
When mode is client, the following keys will be returned:
rx_accept_sess_cnt Number of Accept-Session messages received
rx_failed_sess_cnt Number of Stop-Session messages received with
a non-zero Accept value
rx_start_ack_cnt Number of Start-Ack messages received
state State of the TWAMP client
IDLE Idle
WAIT_FOR_RECONNECT Waiting for reconnection
CONNECT Connecting
ESTABLISHED Established
SESSIONS_REQUESTED Test sessions requested
tx_req_tw_sess_cnt Number of Request-TW-Session messages sent
tx_start_sess_cnt Number of Start-Session messages sent
tx_stop_sess_cnt Number of Stop-Session messages sent
When mode is state_summary, the following keys will be returned:
connect_cnt Number of TWAMP test sessions accepted
established_cnt Number of TWAMP test sessions in progress
idle_cnt Number of TWAMP control sessions that do not have
test sessions running
sess_requested_cnt Number of TWAMP test sessions requested
connections_down_cnt Number of TWAMP control sessions rejected
connections_up_cnt Number of TWAMP control sessions accepted
When mode is aggregated_server, the following keys will be returned:
rx_req_tw_sess_cnt Number of Request-TW-Session messages received
rx_start_sess_cnt Number of Start-Session messages received
rx_stop_sess_cnt Number of Stop-Session messages received
tx_accept_sess_cnt Number of Accept-Session messages sent
tx_failed_sess_cnt Number of Stop-Session messages sent
with a non-zero Accept value
tx_start_ack_cnt Number of Start-Ack messages sent
When mode is aggregated_client, the following keys will be returned:
rx_accept_sess_cnt Number of Accept-Session messages received
rx_failed_sess_cnt Number of Stop-Session messages received with a
non-zero Accept value
rx_start_ack_cnt Number of Start-Ack messages received
tx_req_tw_sess_cnt Number of Request-TW-Session messages sent
tx_start_sess_cnt Number of Start-Session messages sent
tx_stop_sess_cnt Number of Stop-Session messages sent
When mode is port_test_session, the following keys will be returned:
avg_jitter Average jitter reported in microseconds
avg_latency Average latency reported in microseconds
avg_server_processing_time
Average server processing time reported in microseconds
max_latency Maximum latency reported in microseconds
max_server_processing_time
Maximum server processing time reported in microseconds
max_jitter Maximum jitter reported in microseconds
min_latency Minimum latency reported in microseconds
min_server_processing_time
Minimum server processing time reported in microseconds
min_jitter Minimum jitter reported in microseconds
Description¶
The sth:: emulation_twamp_stats function retrieves statistics for the specified TWAMP devices. Use -mode to specify the scope of results that you want to retrieve.
This function returns the requested data and a status value (1 for success). If there is an error, the function returns the status value (0) and an error message.(See Return Values for a description of each key.)
Examples¶
To get server results when state is started:
while { $state != "STARTED" } {
set result_server_state [sth::emulation_twamp_stats\
-handle $devicehandle2\
-mode server\ ]
set state [keylget result_server_state $devicehandle2.state]
}
set result_server [sth::emulation_twamp_stats\
-handle $devicehandle2\
-mode server\ ]
Sample Output:
{host3 {{state STARTED} {tx_accept_sess_cnt 2} {rx_stop_sess_cnt 0}
{rx_start_sess_cnt 1} {rx_req_tw_sess_cnt 2} {tx_failed_sess_cnt 0}
{tx_start_ack_cnt 1}}} {status 1}