IGMP Functions¶
sth::emulation_igmp_config¶
Purpose¶
Creates, modifies, or deletes Internet Group Management Protocol (IGMP) host(s) for the specified Spirent HLTAPI port or handle.
The Internet Group Management Protocol (IGMP) is a communications protocol that manages the membership of Internet Protocol multicast groups.
Use IGMP to dynamically register individual hosts in a multicast group on a particular LAN. Hosts identify which multicast groups they belong to by sending IGMP messages to their local router. Under IGMP, routers listen to IGMP messages and send out queries to discover which groups are active on a particular subnet. When all hosts leave a group, the router no longer forwards packets for that group.
Synopsis¶
Note
- M indicates that the argument is Mandatory .
- S indicates the argument is for
scalingscenarios.
sth::emulation_igmp_config
[-mode {create|modify|delete|disable_all|activate} M]
[-port_handle <port_handle>]
[-handle <session_handle>|<IGMP_host_handle>]
[-count <1-65535> ]
[-enable_router_alert {true|false}]
[-enable_df {true|false}]
[-filter_mode {include | exclude}]
[-filter_ip_addr <a.b.c.d>]
[-force_single_join {true|false}]
[-force_robust_join {true|false}]
[-force_leave {true|false}]
[-general_query <1>]
[-group_query <1>]
[-igmp_version {v1|v2|v3}]
[-insert_checksum_errors {true|false}]
[-insert_length_errors {true|false}]
[-intf_ip_addr <a.b.c.d>]
[-intf_ip_addr_step <a.b.c.d>]
[-intf_prefix_len <1-32>]
[-ip_router_alert {0|1}]
[-source_mac <aa:bb:cc:dd:ee:ff>]
[-source_mac_step <aa:bb:cc:dd:ee:ff>]
[-msg_interval <0-4294967295>]
[-max_burst <NUMERIC>]
[-vlan_sub_filter <inner|outer>]
[-calculate_latency {0|1}]
[-calculate_latency_delay <1-3600>]
[-neighbor_intf_ip_addr <a.b.c.d>]
[-neighbor_intf_ip_addr_step <a.b.c.d>]
[-older_version_timeout <0-4294967295>]
[-qinq_incr_mode {inner|outer|both}]
[-robustness <2-255>]
[-suppress_report 1]
[-tos <0-255>]
[-tos_type {tos|diffserv}]
[-pack_reports {true|false}]
[-vlan_cfi {0|1}]
[-vlan_outer_cfi {0 | 1}]
[-vlan_id <0-4095> ]
[-vlan_id_count <1-4096>]
[-vlan_id_mode {fixed|increment}]
[-vlan_id_step <0-32767>]
[-vlan_user_priority <0-7>]
[-vlan_id_outer <0-4095>]
[-vlan_id_outer_mode {fixed|increment}]
[-vlan_id_outer_count <1-4096>]
[-vlan_id_outer_step <0-32767>]
[-vlan_outer_user_priority <0-7>]
[-expand {true|false} S]
[-router_alert {true|false}]
[-mcast_group_count <1-32000>]
[-ignore_memberships {true|false}]
[-device_group_mapping {many_to_many|one_to_one|round_robin}]
[-mcast_ipv4_addr <IPV4>]
[-filtered_sources {none|existing|custom}]
[-src_count <1-4294967295>]
[-src_step <0-4294967295>]
[-src_ipv4_addr <a.b.c.d>]
[-src_ipv4_prefix <1-32>]
[-source_filters {true | false}]
[-source_list <device_list or host_list>]
[-incr_src_ipv4_addr_per_device <a.b.c.d>]
Arguments¶
-
-count¶ Defines the number of IGMP hosts to create on the interface. Possible values are 1 to 65535. The default is 1.
-
-filter_mode¶ Specifies an explicit set of sources from which the multicast group is interested in receiving data (configures IGMPv3 Include Filter mode). Possible values are:
include - Data from the specified sources are filtered and forwarded to the hosts by the multicast router. exclude - Data from the specified sources are filtered and not forwarded to the hosts by the multicast router.The default is include.
-
-enable_df¶ Spirent Extension (for Spirent HLTAPI only).
Enables or disables the Don’t Fragment (DF) bit in the IPv4 header
Values: true, false
Default: false
-
-enable_router_alert¶ Spirent Extension (for Spirent HLTAPI only).
Enables or disables the router alert option in the IPV4 header
Values: true, false
Default: false
-
-filter_ip_addr¶ Configure the filtered IP address. The value must be in IPv4 format. The default value is 192.0.1.0.
-
-force_single_join¶ Spirent Extension (for Spirent HLTAPI only).
Determines whether to force the IGMP hosts to send a single Join report per group
Values: true, false
Default: false
-
-force_robust_join¶ Spirent Extension (for Spirent HLTAPI only).
Determines whether to transmit a second report when an IGMPv1/IGMPv2 host joins a multicast group and transmits an initial unsolicited membership report for that group
Values: true, false
Default: false
-
-force_leave¶ Spirent Extension (for Spirent HLTAPI only).
Determines whether all hosts are required to send Leave reports when leaving the multicast group. When it is enabled, a Leave message will be sent even if the host is not the last host to report membership.
Values: true, false
Default: false
-
-general_query¶ Always enabled. Valid value is 1 (true). When -general_query is set to 1, Spirent HLTAPI responds to only general queries received on the interface.
-
-group_query¶ Always enabled. Valid value is 1 (true). When -group_query is set to 1, Spirent HLTAPI responds to only group-specific (and source/group) queries received on the interface.
-
-handle¶ The handle of the IGMP host configured on the port to use. You must specify -handle when -mode is set to “modify” or “delete”. When you use -mode create, it is Mandatory that you specify -port_handle or -handle, but not both. If you define -port_handle and -mode create, Spirent HLTAPI creates an IGMP device on the given port. If you specify -handle and -mode create, Spirent HLTAPI enables IGMP over the provided PPPoX or L2TP session.
You can use -handle when -mode is set to “create” for IGMPoPPPoX or IGMPoL2TP. When specifying a PPPoX/L2TP handle, the PPPoX/L2TP options specified in the
sth::l2tp_configfunction are used instead of the following sth::emulation_igmp_config arguments:-intf_ip_addr -intf_ip_addr_step -intf_prefix_len -neighbor_intf_ip_addr -neighbor_intf_ip_addr_step -vlan_cfi -vlan_id -vlan_id_mode -vlan_id_step -vlan_user_priority -vlan_id_count -vlan_id_outer -vlan_id_outer_count -vlan_id_outer_step -vlan_outer_user_priority -vlan_outer_tpid
The following example specifies a PPPoX handle:
sth::emulation_igmp_config \ -mode create \ -handle $pppoxHandle \ -older_version_timeout 400 \ -robustness 2 \ -unsolicited_report_interval 100
The following example enables IGMP protocol on an existing L2TP host:
sth::emulation_igmp_config \ -mode create \ -handle $l2tpHandle \ -older_version_timeout 400 \ -robustness 2 \ -unsolicited_report_interval 100
-
-igmp_version¶ Specifies the multicasting protocol used to manage multicast group memberships. Possible values are:
v1 - The second version of IGMP (supercedes IGMPv0), specified in RFC 1112. v2 - IGMP version specified in RFC 2236. Improved IGMP version that adds "leave" messages, shortening the amount of time :mandatory:`Mandatory` for a router to determine that no stations are in a particular group. This version includes the ability for the receivers to gracefully exit from a multicast group. v3 - Specified in RFC 3376, this major revision of the IGMP protocol adds the ability to specify the source(s) to which a receiver is willing to listen. Sources can be stipulated with "include" filters in the "join" and "report" messages, or sources can be specifically rejected with "exclude" filters.
-
-insert_checksum_errors¶ Spirent Extension (for Spirent HLTAPI only).
Determines whether to insert checksum errors into all IGMP control packets
Values: true, false
Default: false
-
-insert_length_errors¶ Spirent Extension (for Spirent HLTAPI only).
Determines whether to insert length errors into all IGMP control packets
Values: true, false
Default: false
-
-intf_ip_addr¶ Specifies the first IPv4 address in the group. The default for IPv4 is 192.85.1.3.
-
-intf_ip_addr_step¶ Specifies the difference between interface IP addresses of consecutive hosts when multiple IGMP hosts are created. The default increment is 1 (for example, 0.0.0.1). This argument is only applicable in create mode.
-
-intf_prefix_len¶ Specifies the address prefix length on the emulated host, Possible values for IPv4 addresses range from 1 to 32; the default is 24,
-
-ip_router_alert¶ Alerts transit routers to examine the contents of an IP packet more closely. When -ip_router_alert is set to 1, Spirent HLTAPI enables the IP router alert option. This argument is always enabled (1 or true) in Spirent HLTAPI whenever hosts send to routers. The IP router alert option is useful for new protocols that are addressed to a destination but require relatively complex processing in routers along the path. (See RFC 2113 for more information.)
-
-source_mac¶ Specifies the starting MAC address in the address pool. The value must be in MAC format. The default value is 00:10:94:00:00:01.
-
-source_mac_step¶ Specifies the increment to use when generating the next MAC address. The default value is 00:00:00:00:00:01.
-
-mode¶ Specifies the action to perform. Possible values are create, modify, and delete, This argument is Mandatory . The modes are described below:
create - Starts emulating IGMP hosts on the specified port or handle. modify - Changes the configuration parameters for the IGMP hosts identified by either the -port_handle or -handle argument. delete - Stops the IGMP emulation locally without attempting to clear the bound addresses from the IGMP server. In addition, all IGMP group sessions information on the port is cleared and the connection is restarted. disable_all - Disables all the IGMP sessions on the specific port. If -port_handle is not specified, all IGMP sessions under all ports will be disabled. activate - Used for ``Scaling`` scenarios. 1. Enables IGMP devices and configures IGMP parameters for the devices created via the sth::emulation_device_config function. This mode requires the value of param_handle as the input to the -handle option. Use this mode for ``Scaling`` scenarios. Refer to -count and -expand options under the ``sth::emulation_igmp_config`` function for more information. For this mode, only the following set of options are valid:: igmp_version router_alert device_group_mapping mcast_ipv4_addr ignore_memberships mcast_group_count filter_mode filtered_sources src_count src_step src_ipv4_addr src_ipv4_prefix 2. Creates devices and enables IGMP protocol. Requires -port_handle and -block_mode options. For this mode, the following options are required/supported along with the options specified above:: -count -block_mode -block_name_index -name -vlan_id -vlan_outer_id -vlan_user_pri -vlan_id_count -vlan_id_repeatmode -vlan_outer_id_count -vlan_outer_user_pri -vlan_outer_id_repeatmode -router_id -router_id_step -router_id_ipv6 -router_id_ipv6_step -intf_ip_addr -intf_ip_addr_step -intf_prefix_len -gateway_ip_addr -gateway_ip_addr_step -mac_addr -mac_addr_step -mac_addr_step_per_port -mac_addr_step_per_vlan -ip_step_per_port -ip_step_per_vlan -source_filters -source_list -incr_src_ipv4_addr_per_device .. note:: Please refer to the emulation_device_config documentation.
-
-msg_interval¶ Maximum output rate of IGMP message packets generated per millisecond. Set this value to 0 to send messages as fast as possible. Possible values range from 0 to 4294967295. The default is 0.
-
-max_burst¶ A value of 0 specifies the maximum possible burst size.
Default: 0
-
-vlan_sub_filter¶ Specifies whether to filter on the Outer or Inner VLAN tag when calculating latency for devices with a PPPoE and stacked VLAN encapsulation. Possible values are:
inner - Specifies that the analyzer filter will be programmed to use the Inner VLAN ID. outer - Specifies that the analyzer filter will be programmed to use the Outer VLAN ID.
The default is outer
-
-calculate_latency¶ Specifies whether to interactively calculate join/leave latency for the group associated to this group membership on the device. Possible values are:
1 - Enables join/leave latency to be calculated interactively. Refer to calculate_latency_delay property to configure the delay to calculate latency. 0 - Disables join/leave latency from being calculated interactively.
The default value is 0.
-
-calculate_latency_delay¶ Specifies the delay (in seconds) before latency is calculated. The timer starts after reports are sent for each device.
Default: 10
Note
Applies to interactive latency tests only.
-
-neighbor_intf_ip_addr¶ Specifies the IP address of the interface for the IGMP neighbor (next hop) that will establish an adjacency with the DUT. The default for IPv4 is 192.85.1.1.
-
-neighbor_intf_ip_addr_step¶ Specifies the difference between the IGMP neighbor’s interface IP addresses when multiple IGMP hosts are created. The default is 0.0.0.0 (that is, the same address).
-
-older_version_timeout¶ The amount of time (in 1/10 seconds) a host must wait after hearing a Version 1 Query before it may send any IGMPv2 messages. Not used for IGMPv3. Possible values are 0 to 4294967295. The default is 4000 milliseconds.
-
-pack_reports¶ Spirent Extension (for Spirent HLTAPI only).
Determines whether to allow multiple group records to be packed into a single report message (for IGMPv3 only)
Values: true, false
Default: false
-
-port_handle¶ The handle of the port on which to create the emulated IGMP session. When -mode is set to “create”, it is Mandatory that you specify -port_handle or -handle, but not both.
-
-qinq_incr_mode¶ Determines which VLAN ID to increment first. Possible values are:
inner - increment the inner VLAN ID before the outer VLAN ID outer - increment the outer VLAN ID before the inner VLAN ID both - increment both the inner and outer VLAN ID at the same time.The default is inner. .. note:: For HLTAPI, qinq can only be incremented on a per host basis.
-
-robustness¶ IGMPv3 only. Specifies the number of times to send a State Change Report. This number is used in the calculation of default values for various timers and counters. Possible values are 2 to 255. The default value is 2.
-
-suppress_report¶ Always enabled. Valid values are 0 (false) and 1 (true). When -suppress_report is set to 1, Spirent HLTAPI suppresses the transmission of a listener report that duplicates one received on the interface. Multicast hosts can suppress the transmission of reports to reduce the amount of multicast communication.
-
-tos¶ Spirent Extension (for Spirent HLTAPI only).
Specifies the value of the TOS field in the IPv4 header
Values: 0-255
Default: 192
-
-tos_type¶ Spirent Extension (for Spirent HLTAPI only).
Specifies the formatting of the TOS value
Values: tos, diffserv
Default: tos
-
-vlan_cfi¶ Sets the canonical format indicator field in VLAN for the emulated router node. Possible values are 0 (Ethernet) and 1 (Token Ring). The default is 1. If set to 0, it indicates Token Ring and packets are dropped by Ethernet ports. If set to 0, it indicates the network is Ethernet.
-
-vlan_id¶ Defines the VLAN ID of the first VLAN sub-interface. Possible values range from 0 to 4095. The default is 1. When the mode is either “create” or “enable”, Spirent HLTAPI checks for a vlan object on the port with the given VLAN ID. If no VLAN object with that ID exists, Spirent HLTAPI creates a VLAN object with the specified VLAN ID.
-
-vlan_id_count¶ Spirent Extension (for Spirent HLTAPI only).
Specifies the number of inner VLAN IDs to use when generating IGMP clients. Spirent HLTAPI assigns VLAN membership in round-robin fashion. Possible values range from 1 to 4096. The default is 1.
-
-vlan_id_mode¶ If you configure more than one interface on Spirent HLTAPI with VLAN, you can choose to either automatically increment the VLAN tag (mode “increment”) or leave it idle for each interface (mode “fixed”), in which case the VLAN ID is the same for all packets. If you set this argument to “increment”, you can specify the -vlan_id_step argument to indicate the step size. The default is “increment”.
-
-vlan_id_step¶ Defines the step size by which the VLAN value is incremented when you set -vlan_id_mode to “increment”. Possible values range from 0 to 32767. You can specify the step when the -count argument is greater than 1. The default is 1.
-
-vlan_id_outer¶ Spirent Extension (for Spirent HLTAPI only).
Specifies the VLAN ID for a particular outer header. Possible values range from 0 to 4095.
-
-vlan_id_outer_count¶ Spirent Extension (for Spirent HLTAPI only).
The number of outer VLAN IDs to use when generating IGMP clients. Spirent HLTAPI assigns VLAN membership in round-robin fashion. Possible values range from 1 to 4096. The default is 1.
-
-vlan_id_outer_mode¶ Spirent Extension (for Spirent HLTAPI only).
Specifies how Spirent HLTAPI will assign VLAN tags to packets in the specified outer header. Possible values are:
fixed - The outer VLAN ID is the same for all packets. increment - For all packets, the outer VLAN tag ID increments by the step specified in the -vlan_id_outer_step argument.
-
-vlan_id_outer_step¶ Spirent Extension (for Spirent HLTAPI only).
The amount by which to increment the specified outer VLAN ID (-vlan_id_outer) for subsequent packets. Possible values range from 0 to 32767. The default is 0.
-
-vlan_outer_cfi¶ Spirent Extension (for Spirent HLTAPI only).
Specifies whether the canonical format indicator (cfi) value is set for the VLAN outer header. Possible values are 0 or 1.
-
-vlan_outer_user_priority¶ Spirent Extension (for Spirent HLTAPI only).
Specifies the VLAN priority to assign to the outer header. Possible values range from 0 to 7. The default is 0.
-
-vlan_user_priority¶ Defines the VLAN priority for the VLANs on this port. Possible values range from 0 to 7. The default is 0.
-
-expand¶ Spirent Extension (for Spirent HLTAPI only).
Determines whether to expand the specified IGMP device parameters into emulated IGMP device objects. It is used in
Scalingtest scenarios.When set to true, a list of emulated device handles (handle_list) with enabled IGMP device configurations is created.
When set to false, only IGMP parameters are configured with no handle returned.
-
-router_alert¶ Specifies to enable/disable router alert option in the IPV4 header of IGMP packet. Possible values are true and false. The default is true. Applicable only in -mode activate when -block_mode or -expand is specified.
-
-mcast_group_count¶ Specifies the number of multicast groups to subscribe to. Possible values range from 1 to 32000. The default is 1. Applicable only in -mode activate when -block_mode or -expand is specified.
-
-ignore_memberships¶ Specifies to enable/disable configuration of group memberships. Possible values are true and false. The default is true. Applicable only in -mode activate when -block_mode or -expand is specified.
-
-mcast_ipv4_addr¶ Specifies the IPv4 multicast group address. The default is 225.0.0.1 Applicable only in -mode activate when -block_mode or -expand is specified.
-
-device_group_mapping¶ Specifies the mapping between the device and subscribed multicast group within their respective blocks. The default is many_to_many Applicable only in -mode activate when -block_mode or -expand is specified.
-
-filtered_sources¶ Mode for specifying filtered sources. Applicable only in -mode activate when -block_mode or -expand is specified. Possible values are:
existing - Use existing sources (Hosts). custom - Specify sources by entering starting source IP, count, and step. none - Specifies an empty source list.
The default is none.
-
-src_ipv4_addr¶ Specifies the multicast source IPv4 address. The default is 1.0.0.2. Applicable only in -mode activate when -block_mode or -expand is specified. These argument settings are required:
-filtered_sources custom -source_filters false
-
-src_ipv4_prefix¶ Specifies the multicast source IPv4 prefix length. The default is 24. Applicable only in -mode activate when -block_mode or -expand is specified. These argument settings are required:
-filtered_sources custom -source_filters false
-
-src_count¶ Specifies the number of multicast address. The default is 1. Applicable only in -mode activate when -block_mode or -expand is specified. These argument settings are required:
-filtered_sources custom -source_filters false
-
-src_step¶ Specifies step for the multicast addresses. The default is 1. Applicable only in -mode activate when -block_mode or -expand is specified. These argument settings are required:
-filtered_sources custom -source_filters false
-
-source_filters¶ Spirent Extension (for Spirent HLTAPI only).
Specifies to configure source address pool when -mode is set to activate. Applicable only in -mode activate when -block_mode or -expand is specified. Possible values are:
true - Configures source IP as IGMPV3 host IP. false - Configures source IP based on the -source_list or -incr_src_ipv4_addr_per_device argument setting.
The default is true.
-
-source_list¶ Spirent Extension (for Spirent HLTAPI only).
Specifies to provide the list of device handles. IGMPV3 group sources will be mapped with provided device IP. Applicable only in -mode activate when -block_mode or -expand is specified. These argument settings are required:
-filtered_sources existing -source_filters false
-
-incr_src_ipv4_addr_per_device¶ Spirent Extension (for Spirent HLTAPI only).
Specifies the source IP incrementation per IGMPV3 host in IPV4 format. Applicable only in -mode activate when -block_mode or -expand is specified. These argument settings are required:
-filtered_sources custom -source_filters false -src_ipv4_addr a.b.c.d
Arguments Unsupported by Save as HLTAPI¶
The following Spirent HLTAPI arguments are currently not supported by the Save as HLTAPI function:
-qinq_incr_mode
Cisco-specific Arguments¶
The following arguments are specific to the Cisco HLTAPI but are not Supported by Spirent HLTAPI:
-emulation_intf_handle
-group_per_intf
-group_pool_handle
-intf_ip_mode
-max_groups_per_pkts
-max_response_control
-max_response_time
-msg_rate
-sessions_per_group
-unsolicited_report_interval
Vendor Specific Arguments Processed by Spirent HLTAPI Wrapper¶
-
-mac_address_init¶ The MAC address for the interface to be created. Valid for mode create
-
-mac_address_step¶ The incrementing step for the MAC address of the interface to be created
-
-interface_handle¶ A handle or list of the handles that are returned from the sth::interface_config call.
-
-port_handle¶ The port on which the session is to be created. Valid for -mode create.
Vendor Specific Arguments Ignored by Spirent HLTAPI Wrapper¶
-enable_packing
-max_sources_per_group
-max_groups_per_pkts
-msg_count_per_interval
-reset
Note
For more information about Spirent HLTAPI Wrapper, refer to Chapter 4 Spirent HLTAPI Wrapper in Spirent HLTAPI Programmer’s Reference.
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 Identifies the created device handle.
handles Identifies the IGMP host configration handle.
handle_list
The emulated device handles list with enabled IGMP configurations
is created when expand is set true.
status
Success (1) or failure (0) of the operation.
log
An error message (if the operation failed).
Description¶
The sth::emulation_igmp_config function creates, modifies, or deletes one
or more emulated IGMP hosts. Use the -mode argument to specify the action
to perform. (See the -mode argument description for information about the
actions.)
When you create an IGMP host, use the -port_handle argument to
specify the Spirent HLTAPI port that the emulated IGMP host will
use for IGMP communication. (The port handle value is contained in the
keyed list returned by the sth::connect function.)
Before you configure IGMP on a port, you must create the port, and use the returned port handle in the call to the sth::emulation_igmp_config function. The first time you call sth::emulation_igmp_config for a particular port, you must specify “-mode create”.
Spirent HLTAPI supports the use of IGMP versions 1, 2, or 3 for multicast group membership. To test IPv4 traffic with one of the Internet Group Management Protocols, you use the Spirent HLTAPI for:
- Generating multicast traffic
- Receiving multicast traffic
- Retrieving multicast results
IGMPv3 provides support for secure communication. Hosts can use Include filters in the Join and Report messages to identify valid sources, or they can use Exclude filters to reject sources. Routers will keep track of the valid sources for every multicast group.
Note when using IGMP over PPPoX/L2TP: Modifying any option during a PPPoE/L2TP session which currently is a member of a multicast group will sever the PPPoE/L2TP session, IGMP host, and multicast group relationship. Therefore, do not use sth::pppox_config/sth::l2tp_config if the PPPoX/L2TP engine is not idle. To see if the PPPoX/L2TP engine is not idle, look at the aggregate.idle flag returned by “sth::pppox_stats -mode aggregate”/”sth::l2tp_stats -mode aggregate”. If aggregate.idle is “0”, then do not send sth::pppox_config/sth::l2tp_config. If the PPPoX/L2TP engine is aborted, you will need to reconfigure the PPPoX/L2TP session. If using IGMP over PPPoX/L2TP, you will also need to reconfigure the IGMP session. (See Examples below).
For more information about the IGMP protocol, see RFC1112 (IGMPv1), RFC2236 (IGMPv2), and RFC3376 (IGMPv3).
Examples¶
#### HLTAPI for Tcl ####
To create an IGMP session:
sth::emulation_igmp_config \
-port_handle $port_handle1 \
-mode create \
-igmp_version v3 \
-intf_ip_addr 10.41.1.2 \
-neighbor_intf_ip_addr 10.41.1.1
Output:
{handles $port_handle1} {status 1}
To create an IGMP over L2TP session:
set l2tp_rL [sth::l2tp_config -mode create -port_handle port1 ... ]
# Connect L2TP
sth::l2tp_control - action connect -handle [keylget l2tp_rL handles]
# Create IGMP clients after all L2TP sessions have finished connecting
set igmp_rL [sth::emulation_igmp_config -handle [keylget l2tp_rL handles]\
-mode create ...]
To create an IGMP over PPPoE session:
set pppox_rL [sth::pppox_config -mode create -port_handle port1 ... ]
# Connect PPPoX
sth::pppox_control -action connect -handle [keylget pppox_rL handles]
# Create IGMP clients after all PPPoX sessions have finished connecting
set igmp_rL [sth::emulation_igmp_config -handle [keylget pppox_rL handles]\
-mode create ...]
To modify an IGMP over PPPoE session:
set pppox_rL [sth::pppox_config -handle host2 -mode modify... ]
Note
If you must modify the PPPoX configuration, modify sth::emulation_igmp_config using the handle returned from sth::pppox_config -mode modify. Otherwise, the IGMP configuration cannot be updated for the modified PPPoX configuration.
To connect PPPoX:
sth::pppox_control -action connect -handle [keylget pppox_rL handles]
# After all PPPoX sessions have finished connecting, update IGMP using the
# handle from "sth::pppox_config -mode modify".
set igmp_rL [sth::emulation_igmp_config -handle [keylget pppox_rL handles]\
-mode modify ...]
To create an IGMP over DHCP session:
# Create DHCP port
set dhcpport_rL [sth::emulation_dhcp_config -mode create -port_handle
port1 ...]
keylget rL handles dhcpport1
# Create the DHCP group
set dhcpgrp_rL [sth::emulation_dhcp_group_config -handle $dhcpport1 \
-mode create ...]
keylget rL handles dhcpgrp1
# Bind DHCP sessions
sth::emulation_dhcp_control -handle $dhcpgrp1 -action bind
# After all DHCP sessions have finished binding, create IGMP clients
set igmp_rL [sth::emulation_igmp_config -handle $dhcpgrp1 -mode create ...]
To modify an IGMP over DHCP session:
# Modify the DHCP group
set dhcpgrp_rL [sth::emulation_dhcp_group_config -handle $dhcpgrp1 \
-mode modify ...]
# Bind DHCP sessions
sth::emulation_dhcp_control -handle $dhcpgrp1 -action bind
# After all DHCP sessions have finished binding, create IGMP clients
set igmp_rL [sth::emulation_igmp_config -handle $dhcpgrp1 -mode modify ...]
IGMP Q-in-Q Examples
The following example shows how to increment by 1 the inner VLAN ID five times (vlan_id_count == 5) before incrementing the outer VLAN ID:
sth::emulation_igmp_config \
-mode create \
-port_handle $hostPortHandle \
-count 23 \
-qinq_incr_mode "outer" \
-vlan_id 1111 \
-vlan_id_count 5 \
-vlan_id_mode "increment" \
-vlan_id_step 1 \
-vlan_user_priority 1 \
-vlan_id_outer 2222 \
-vlan_id_outer_count 5 \
-vlan_id_outer_mode "increment" \
-vlan_id_outer_step 1 \
-vlan_outer_user_priority 5
Output:
Inner 1111 Outer 2222
Inner 1111 Outer 2223
Inner 1111 Outer 2224
Inner 1111 Outer 2225
Inner 1111 Outer 2226
Inner 1112 Outer 2222
Inner 1112 Outer 2223
Inner 1112 Outer 2224
Inner 1112 Outer 2225
Inner 1112 Outer 2226
Inner 1113 Outer 2222
Inner 1113 Outer 2223
Inner 1113 Outer 2224
Inner 1113 Outer 2225
Inner 1113 Outer 2226
Inner 1114 Outer 2222
Inner 1114 Outer 2223
Inner 1114 Outer 2224
Inner 1114 Outer 2225
Inner 1114 Outer 2226
Inner 1115 Outer 2222
Inner 1115 Outer 2223
Inner 1115 Outer 2224
The following example shows how to increment by 1 the outer VLAN ID two times (vlan_id_outer_count == 2) before incrementing the inner VLAN ID:
sth::emulation_igmp_config \
-mode create \
-port_handle $hostPortHandle \
-count 17 \
-qinq_incr_mode "inner" \
-vlan_id 1111 \
-vlan_id_count 3 \
-vlan_id_mode "increment" \
-vlan_id_step 1 \
-vlan_user_priority 1 \
-vlan_id_outer 2222 \
-vlan_id_outer_count 2 \
-vlan_id_outer_mode "increment" \
-vlan_id_outer_step 1 \
-vlan_outer_user_priority 5
Output:
Inner 1111 Outer 2222
Inner 1112 Outer 2222
Inner 1113 Outer 2222
Inner 1111 Outer 2223
Inner 1112 Outer 2223
Inner 1113 Outer 2223
Inner 1111 Outer 2222
Inner 1112 Outer 2222
Inner 1113 Outer 2222
Inner 1111 Outer 2223
Inner 1112 Outer 2223
Inner 1113 Outer 2223
Inner 1111 Outer 2222
Inner 1112 Outer 2222
Inner 1113 Outer 2222
Inner 1111 Outer 2223
Inner 1112 Outer 2223
The following example increments by 1 both the inner and outer VLAN IDs at the same time:
sth::emulation_igmp_config \
-mode create \
-port_handle $hostPortHandle \
-count 21 \
-qinq_incr_mode "both" \
-vlan_id 1111 \
-vlan_id_count 1 \
-vlan_id_mode "increment" \
-vlan_id_step 1 \
-vlan_user_priority 1 \
-vlan_id_outer 2222 \
-vlan_id_outer_count 7 \
-vlan_id_outer_mode "increment" \
-vlan_id_outer_step 1 \
-vlan_outer_user_priority 5
Output:
Inner 1111 Outer 2222
Inner 1111 Outer 2223
Inner 1111 Outer 2224
Inner 1111 Outer 2225
Inner 1111 Outer 2226
Inner 1111 Outer 2227
Inner 1111 Outer 2228
Inner 1111 Outer 2222
Inner 1111 Outer 2223
Inner 1111 Outer 2224
Inner 1111 Outer 2225
Inner 1111 Outer 2226
Inner 1111 Outer 2227
Inner 1111 Outer 2228
Inner 1111 Outer 2222
Inner 1111 Outer 2223
Inner 1111 Outer 2224
Inner 1111 Outer 2225
Inner 1111 Outer 2226
Inner 1111 Outer 2227
Inner 1111 Outer 2228
The following example uses the function in Scaling mode (-mode activate)
with -port_handle and -block_mode:
set igmp_ret [sth::emulation_igmp_config\
-mode activate \
-port_handle $port1\
-count 2 \
-block_mode ONE_DEVICE_PER_BLOCK\
-block_name_index 1\
-vlan_id 444 \
-vlan_outer_id 333 \
-router_id 11.111.11.11 \
-router_id_step 0.0.0.2\
-mac_addr 00:11:11:11:11:11 \
-mac_addr_step 00:00:00:00:00:02 \
-mac_addr_step_per_port 00:00:00:00:01:01 \
-mac_addr_step_per_vlan {"" 00:00:00:00:00:01} \
-ip_step_per_port 0.0.0.5 \
-ip_step_per_vlan {"" 0.0.1.1} \
-intf_prefix_len 22 \
-name DEVICE_BLOCK_IGMP \
-vlan_user_pri 3 \
-vlan_id_count 2 \
-vlan_id_repeatmode REPEAT_ACROSS_PORT\
-vlan_outer_id_count 2 \
-vlan_outer_user_pri 4 \
-vlan_outer_id_repeatmode REPEAT_ACROSS_PORT\
-intf_ip_addr 11.111.11.11 \
-gateway_ip_addr 11.111.11.1 \
-expand true \
-igmp_version v3\
-router_alert true\
-device_group_mapping many_to_many\
-mcast_ipv4_addr 224.0.0.1\
-ignore_memberships true\
-mcast_group_count 1\
-filter_mode include \
-filtered_sources custom \
-src_count 10 \
-src_step 1\
-src_ipv4_addr 15.1.1.1\
-src_ipv4_prefix 24 \
-incr_src_ipv4_addr_per_device 0.0.1.0 \
-source_filters false ]
Sample Output:
{param_handle emulateddevicegenparams1} {status 1} {handle {}} {handle_list
{emulateddevice1 emulateddevice2 emulateddevice3 emulateddevice4 emulateddevice5
emulateddevice6 emulateddevice7 emulateddevice8}} {igmp_handle_list
{igmphostconfig1 igmphostconfig2 igmphostconfig3 igmphostconfig4 igmphostconfig5
igmphostconfig6 igmphostconfig7 igmphostconfig8}} {igmp_group_handle_list
{igmpgroupmembership1 igmpgroupmembership2 igmpgroupmembership3 igmpgroupmembership4
igmpgroupmembership5 igmpgroupmembership6 igmpgroupmembership7 igmpgroupmembership8}}
{multicast_group_handle_list {ipv4group1 ipv4group2 ipv4group3 ipv4group4 ipv4group5
ipv4group6 ipv4group7 ipv4group8}} {handles {emulateddevice1 emulateddevice2
emulateddevice3 emulateddevice4 emulateddevice5 emulateddevice6 emulateddevice7 emulateddevice8}}
#### HLTAPI for Python ####
To create an IGMP session:
device_ret0 = sth.emulation_igmp_config (
mode = 'create',
filter_mode = 'exclude',
port_handle = port_handle[0],
msg_interval = '0',
igmp_version = 'v3',
robustness = '2',
older_version_timeout= '400',
unsolicited_report_interval= '10',
count = '1',
source_mac = '00:10:94:00:00:01',
source_mac_step = '00:00:00:00:00:01',
neighbor_intf_ip_addr_step= '0.0.0.0',
neighbor_intf_ip_addr= '192.85.1.1',
intf_ip_addr = '192.85.1.3',
intf_prefix_len = '24',
intf_ip_addr_step = '0.0.0.1');
Sample Output:
{'status': '1', 'handles': 'igmphostconfig1', 'handle': 'host3'}
#### HLTAPI for Perl ####
To create an IGMP session:
my %device_ret0 = sth::emulation_igmp_config (
mode => 'create',
filter_mode => 'exclude',
port_handle => "$hport[1]",
msg_interval => '0',
igmp_version => 'v3',
robustness => '2',
older_version_timeout=> '400',
unsolicited_report_interval=> '10',
count => '1',
source_mac => '00:10:94:00:00:01',
source_mac_step => '00:00:00:00:00:01',
neighbor_intf_ip_addr_step=> '0.0.0.0',
neighbor_intf_ip_addr=> '192.85.1.1',
intf_ip_addr => '192.85.1.3',
intf_prefix_len => '24',
intf_ip_addr_step => '0.0.0.1');
Sample Output:
$VAR1 = 'handle';
$VAR2 = 'host3';
$VAR3 = 'handles';
$VAR4 = 'igmphostconfig1';
$VAR5 = 'status';
$VAR6 = '1';
End of Procedure Header
sth::emulation_igmp_control¶
Purpose¶
Start, stop, or restart the IGMP host on the specified port. Leaves and joins group pools.
Synopsis¶
Note
M indicates that the argument is Mandatory .
sth::emulation_igmp_control [-mode {restart|join|leave|leave_join} M] [-group_member_handle <handle>] [-port_handle <port_handle_list|all>] [-handle <IGMP_session_handle_list|all>] [-leave_join_delay <0-4294967295>] [-data_duration <0-4294967295>] [-calculate_latency {0|1}]
Arguments¶
-
-handle¶ Identifies a list of IGMP groups to stop, start, restart, join, or leave. Use “all” to specify all IGMP groups. If you do not specify a group, the action is applied to all groups configured on ports specified by -port_handle. This value appears in the keyed list returned by the
sth::emulation_igmp_group_configfunction.
-
-mode¶ Specifies the action to perform on the specified handle. If you provide a handle (-handle), this argument performs the specified action on all groups on this session. If you provide a group member handle (-group_member_handle), this argument performs the specified action on the specified group pool(s). If you do not provide either a handle or a group member handle, this argument performs the specified action on all groups on all sessions. Possible values are restart, join, and leave. You must specify one of these values. The modes are described below:
restart - Stops and then restarts the groups specified by -handle on the specified port. If you do not provide a handle, this action stops and restarts all groups on all ports. join - Joins all groups specified by -handle or group pools specified by -group_member_handle. If you do not provide a handle, this action joins all groups on all ports. leave - Leave all groups specified by -handle or group pools specified by -group_member_handle. If you do not provide a handle, this action leaves all groups on all ports. leave_join - Rejoins all groups specified by -handle or rejoins group pools specified by -group_member_handle. The device specified by -handle or -group_member_handle will resend IGMP/MLD Reports.
Note
You must send the “leave” actions before disconnecting PPPoX sessions. Otherwise, if you disconnect a PPPoX session before sending “leaves”, HLTAPI will not automatically send the “leaves”.
-
-calculate_latency¶ Spirent Extension (for Spirent HLTAPI only).
Specifies whether to calculate latencies when joining or leaving multicast groups. Possible values are 0 (do not calculate latency) and 1 (calculate latency). If set to 1 during an IGMP Join, HLTAPI cannot capture the IGMP control plane packets because the analyzer stops to collect packets so it can calculate latency. The default is 0.
The following example does 100 iterations of join and leaves on 90 sessions. A 10-second delay is added after each join and each leave (using the Tcl command “after”). The delay duration to use depends on the number of iterations and number of sessions:
for {set joinleaveidx 0} {$joinleaveidx < 100} \ {incr joinleaveidx} { # IGMP join sth::emulation_igmp_control \ -mode join \ -calculate_latency 1 \ -handle $IGMPSessionHandle # Adding a delay between join and leave. # This value is based on 90 sessions joining. # May need to be tweaked when ``Scaling`` higher. after 10000 # IGMP leave sth::emulation_igmp_control \ -mode leave \ -calculate_latency 1 \ -handle $IGMPSessionHandle # Adding a delay between the last leave and # the next join when this loops. # This value is based on 90 sessions leaving. # May need to be tweaked when ``Scaling`` higher. after 10000 }
Note
Background traffic analysis with IGMP is unavailable with calculate latency enabled. Also, if you are testing multiple joins and leaves with calculate latency enabled, you must add a delay (a few seconds) between subsequent joins and leaves.
-
-leave_join_delay¶ Specifies the amount of time, in seconds, between joins and leaves. You can use this argument when -mode is join or leave. Possible values range from 0 to 4294967295. The default is 0. (This argument was formerly known as “-delay” in previous versions of the Spirent HLTAPI.)
-
-data_duration¶ Spirent Extension (for Spirent HLTAPI only).
Specifies the amount of time, in seconds, to wait after sending joins or leaves before latencies are calculated. The default is 10.
-
-group_member_handle¶ Identifies the IGMP (one or more) group member handle.
-
-port_handle¶ Identifies a list of ports on which to take the action. Use “all” to specify all ports. If you do not specify a port, all configured ports will be used. This value is returned by the
sth::emulation_igmp_configfunction.
Vendor Specific Arguments Processed by Spirent HLTAPI Wrapper¶
-
-mode¶ Specifies what is being done to the protocol. Possible values are:
stop Stop the protocol start Start the protocol restart Restart the protocol join Join the group ranges specified by -handle, -port_handle or -group_member_handle leave Leave the group ranges specified by handle, -port_handle or -group_member_handle
Vendor Specific Arguments Ignored by Spirent HLTAPI Wrapper¶
-group_member_handle
-group_pool_handle
Note
For more information about Spirent HLTAPI Wrapper, refer to Chapter 4 Spirent HLTAPI Wrapper in Spirent HLTAPI Programmer’s Reference.
Cisco-specific Arguments¶
The -group_member_handle argument is specific to the Cisco HLTAPI but is not supported by Spirent HLTAPI:
-group_member_handle
-group_pool_handle
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_igmp_control function stops, starts, or restarts the
IGMP protocol on the hosts on the specified port. You can also use this
function to send a Join or Leave message from the host to inform a router
that the host is either joining the multicast group specified by handle or
port_handle or terminating its membership in the specified multicast group,
When you call the sth::emulation_igmp_control function, you
specify a port handle. Spirent HLTAPI applies the specified action to
all of the emulated IGMP hosts associated with the specified port.
IPv4 multicast traffic is based on group membership established and maintained with IGMP. Hosts and adjacent routers exchange IGMP messages to establish multicast group membership.
When a host wants to participate in a multicast group, it sends an IGMP “join” message to its local router. After a router receives one or more “joins” for a specific group, it forwards any packets destined for that particular group to the appropriate interface(s). The router regularly verifies that the hosts want to continue to participate in the multicast groups by sending periodic “queries” to the receivers.
When a host is no longer interested in multicast group participation, it sends a “leave” message to the router (IGMPv2 and IGMPv3 only).
Examples¶
#### HLTAPI for Tcl ####
The following example joins all groups specified by -handle:
sth::emulation_igmp_control
-mode join
-handle $IGMPSessionHandle
The following example removes the groups specified by -handle from the hosts on the specified port:
sth::emulation_igmp_control
-mode leave
-handle $IGMPSessionHandle
Sample Output:
{status 1} success or {status 0} fail
#### HLTAPI for Python ####
The following example joins all the specified groups:
ctrl_ret1 = sth.emulation_igmp_control (
port_handle = [port_handle[0],port_handle[1]],
mode = 'join');
Sample Output:
{'status': '1'}
#### HLTAPI for Perl ####
The following example joins all the specified groups:
my %ctrl_ret1 = sth::emulation_igmp_control (
port_handle => "$hport[1] $hport[2] ",
mode => 'join');
Sample Output:
$VAR1 = 'status';
$VAR2 = '1';
End of Procedure Header
sth::emulation_igmp_group_config¶
Purpose¶
Creates group pools and source pools, and modifies and deletes group and
source pools from IGMP hosts. This function configures multicast group
ranges for an emulated IGMP host. You must use the common
sth::multicast_source_config functions with
this function.
Synopsis¶
Note
M indicates that the argument is Mandatory .
sth::emulation_igmp_group_config [-mode {create|modify|delete|clear_all} M] [-device_group_mapping { MANY_TO_MANY | ONE_TO_ONE | ROUND_ROBIN}] [-enable_user_defined_sources { 0 | 1 }] [-filter_mode {include |exclude}] [-ip_addr_list <a.b.c.d>] [-source_filters <device_handle>] [-handle <IGMP_group_membership_handle>] [-group_pool_handle <multicast_group_pool_handle>] [-session_handle <igmp_session_handle>] [-source_pool_handle <multicast_source_pool_handle>] [-specify_sources_as_list { 0 | 1 }]
Arguments¶
-
-group_pool_handle¶ Specifies the name of the group (that is, the list of multicast IP addresses) to link to the IGMP host during create mode. Before specifying the group pool handle, use the
sth::emulation_multicast_group_configfunction to add the group pool. See “Multicast APIs” in the “Spirent TestCenter HLTAPI Command Reference” document for information about the sth::emulation_multicast_group_config andsth::emulation_multicast_source_configfunctions.
-
-handle¶ Sets group membership handle that associates group pools with an IGMP host. In modify mode, membership handle must be used in conjunction with the session handle to identify the multicast group pools. For “-mode create”, the handle is returned by the
sth::emulation_igmp_configfunction. Mode “modify” returns the same handle passed in. .. note:: The IGMP hosts, specified by -handle, join the multicast groups, specified by the -group_pool_handle. So, both arguments are Mandatory for “-mode create”, but -group_pool_handle is optional for “-mode modify”.
-
-mode¶ Specifies the action to perform. Possible values are create, modify, delete, and clear_all. There is no default; you must specify a mode. The modes are described below:
create - Starts emulation on the port specified with -handle and associates an existing multicast group pool (-group_pool_handle) with the specified IGMP host (that is, joins the membership). modify - Changes the configuration identified by the -handle argument by applying the parameters specified in subsequent arguments. delete - Remove one group of pools from this session. clear_all - Remove all group pools from this session.
-
-session_handle¶ Specifies the handle of the IGMP host on which to configure the IGMP group ranges.
-
-source_pool_handle¶ Specifies the name of the source pool (that is, the list of non-multicast source IP addresses) to associate with the groups during create mode. Each multicast group may contain 0 or more of these source IP addresses. Use this argument if the host only wants specific information within the specified multicast group (-group_pool_handle). Specifying the source pool handle along with the group pool handle in the
sth::emulation_igmp_group_configfunction adds the range of source IP addresses to each multicast group. Before specifying the source pool handle, use thesth::emulation_multicast_source_configfunction to add the source pools. See “Multicast APIs” in the “Spirent TestCenter HLTAPI Command Reference” document for information about the sth::emulation_multicast_source_config andsth::emulation_multicast_group_configfunctions. The following example adds two source pools:sth::emulation_multicast_source_config \ -ip_addr_start 1.2.1.2 \ -mode create \ -num_sources 1
-
-filter_mode¶ Spirent Extension (for Spirent HLTAPI only).
Specifies an explicit set of sources from which the multicast group is interested in receiving data. Possible values are:
include Data from the specified sources are filtered and forwarded to the hosts by the multicast router exclude Data from the specified sources are filtered and not forwarded to the hosts by the multicast router
-
-device_group_mapping¶ Spirent Extension (for Spirent HLTAPI only).
Specifies the device-group mapping mode. Possible values are:
MANY_TO_MANY Creates a full mesh of devices and groups ONE_TO_ONE Assigns one device to each group. Mapping stops when it reaches the end of devices or groups. The extra devices or groups are not mapped. ROUND_ROBIN Assigns one device to each group. Mapping stops when all devices are assigned to a group. If there are more devices than groups, the group assignment repeats from the first group.
-
-enable_user_defined_sources¶ Spirent Extension (for Spirent HLTAPI only).
Enables or disables user-defined sources when -igmp_version is set to IGMPv3 or MLDv2 for the multicasting protocol. Possible values are 0 (disable) and 1 (enable).
-
-specify_sources_as_list¶ Spirent Extension (for Spirent HLTAPI only).
When enabled, Spirent HLTAPI will allow the use of a list of IP addresses to specify a range of source addresses. Possible values are 0 (disable) and 1 (enable). If it is set to 1, -enable_user_defined_sources must be enabled.
-
-ip_addr_list¶ Spirent Extension (for Spirent HLTAPI only).
A list of IP addresses that are used to specify a range of source addresses. This argument is available when -enable_user_defined_sources and -specify_sources_as_list are enabled.
-
-source_filters¶ Spirent Extension (for Spirent HLTAPI only).
Specifies the handle of the host block to be used as the source filter. This argument is available when -enable_user_defined_sources is enabled and -specify_sources_as_list is disabled.
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
- Identifies the handle of the group (IGMP_group_config_handle)
created by the
sth::emulation_igmp_group_configfunction. - group_pool_handle
- Identifies the group pool handle used by the
sth::emulation_igmp_group_configfunction to configure or modify the group member. - source_pool_handle
- Identifies the source pool handle used by the
sth::emulation_igmp_group_configfunction to configure or modify the group member. - status
- Success (1) or failure (0) of the operation.
- log
- An error message (if the operation failed).
Description¶
The sth::emulation_igmp_group_config function configures or
modifies a group of IGMP hosts where each group share a
set of common characteristics. Use the -mode argument to specify
the action to perform. (See the -mode argument description for information
about the actions.)
Before using this function, you must specify “-mode create” when
configuring IGMP host emulation on a port and initialize the port handle
argument (using the sth::emulation_igmp_config function).
You can link groups of multicast IP addresses to any interested host or just a subset of IP addresses within each group.
Each multicast IP address directs the information it represents to any host interested in subscribing to it. In the following example, the object represented by MGroupHandle contains 229.0.0.1 & 229.0.0.2. The host handle “hostHandle” has the IP address 3.0.0.1. See below:
sth::emulation_igmp_group_config \
-mode create \
-group_pool_handle $MGroupHandle \
-session_handle $hostHandle
The following illustration shows that host 3.0.0.1 subscribes to both multicast group 229.0.0.1 and 229.0.0.2:
Host 3.0.0.1
*
*****************
* *
************* *************
* MGroup1 * * MGroup2 *
* 229.0.0.1 * * 229.0.0.2 *
************* *************
To subscribe to only one or more particular IP addresses that exist within
a multicast group, you must use the -source_pool_handle as well. Specifying
the source_pool_handle along with the group_pool_handle in the
sth::emulation_igmp_group_config function, adds the range of source IP
addresses to each multicast group. Adding the source_pool_handle
SGroupHandle (which contains source IP addresses 1.1.1.1 and 1.1.1.2)
option to the above example results in:
sth::emulation_igmp_group_config \
-mode create \
-group_pool_handle $MGroupHandle \
-session_handle $hostHandle \
-source_pool_handle $SGroupHandle
The following illustration shows that host 3.0.0.1 subscribes to source 1.1.1.1 and 1.1.1.2 which exist in both multicast groups 229.0.0.1 and 229.0.0.2:
Host 3.0.0.1
*
*****************
* *
************* *************
* MGroup1 * * MGroup2 *
* 229.0.0.1 * * 229.0.0.2 *
************* *************
************* *************
* Source1 * * Source1 *
* 1.1.1.1 * * 1.1.1.1 *
* Source2 * * Source2 *
* 1.1.1.2 * * 1.1.1.2 *
************* *************
Examples¶
#### HLTAPI for Tcl ####
The following example configures the hosts, represented by “igmpSessionHandle”, to subscribe to the multicast group(s) represented by “multicastGroupPoolHandle(1)”:
sth::emulation_igmp_group_config \
-mode create \
-group_pool_handle $multicastGroupPoolHandle(1) \
-session_handle $igmpSessionHandle
The following example causes all hosts on the port, represented by the port
handle “portHandle”, to send “leave” messages to the multicast groups to
which they are currently subscribed. These multicast groups were set using
the sth::emulation_igmp_group_config function:
sth::emulation_igmp_group_config \
-mode clear_all \
-handle $IGMPgroupconfighandle
Sample output for example 1 shown above:
{status 1} {handle igmpgroupmembership1}
The following example configures IGMP hosts using a list of IP addresses as the source filter:
set device_ret0_group_config_1 [sth::emulation_igmp_group_config\
-session_handle $igmp_session\
-mode create\
-group_pool_handle $macstgroup\
-device_group_mapping ONE_TO_ONE\
-filter_mode INCLUDE\
-enable_user_defined_sources 1\
-specify_sources_as_list 1\
-ip_addr_list "10.10.10.10 20.20.20.20 30.30.30.0 40.40.40.40"\
]
Sample Output:
{status 1} {handle igmpgroupmembership2}
The following example configures IGMP hosts using a host block as the source filter:
set device_ret0_group_config_4 [sth::emulation_igmp_group_config\
-session_handle $igmp_session\
-mode create\
-group_pool_handle $macstgroup\
-device_group_mapping MANY_TO_MANY\
-filter_mode EXCLUDE\
-enable_user_defined_source 0\
-specify_sources_as_list 0\
-source_filters $sourcefilterdevice\
]
Sample Output:
{status 1} {handle igmpgroupmembership3}
#### HLTAPI for Python ####
Sample Input:
device_ret0_group_config = sth.emulation_igmp_group_config (
session_handle = igmp_session,
mode = 'create',
group_pool_handle = macstgroup,
source_pool_handle = macstsource);
Sample Output:
{'status': '1', 'handle': 'igmpgroupmembership1'}
#### HLTAPI for Perl ####
Sample Input:
my %device_ret0_group_config = sth::emulation_igmp_group_config (
session_handle => "$igmp_session",
mode => 'create',
group_pool_handle => "$macstgroup",
source_pool_handle => "$macstsource");
Sample output:
$VAR1 = 'handle';
$VAR2 = 'igmpgroupmembership1';
$VAR3 = 'status';
$VAR4 = '1';
End of Procedure Header
sth::emulation_igmp_info¶
Purpose¶
Returns statistics about the IGMP group activity on the specified handle. Statistics include the connection status and number and type of messages sent and received from the specified port.
Synopsis¶
Note
M indicates that the argument is Mandatory .
sth::emulation_igmp_info [-handle <igmp_session_handle_list|all>] [-port_handle <port_handle_list|all>] [-mode < stats|clear_stats>]
Arguments¶
-
-handle¶ Specifies a list of IGMP session handles upon which host emulation is configured. Use “all” to specify all IGMP sessions. If you do not specify an IGMP session, results from all sessions under the specified ports will be returned. This value is returned by the
sth::emulation_igmp_configfunction.
-
-port_handle¶ Specifies the a list of port handles on which the IGMP hosts are affiliated to IS-IS routers. Use “all” to specify all ports. If you do not specify a port, all configured ports will be used.
-
-mode¶ Specifies the action to perform. Possible values are stats and clear_stats. The default value is stats. The modes are described below:
stats If handle is provided, it will return transmitted and received statistics of the specified IGMP host. If port_handle is provided, it will return transmitted and received statistics of the specified IGMP port. clear_stats If handle is provided, it will clear all statistics (transmitted and received counters) of the specified port. If port_handle is provided, it will clear all statistics (transmitted and received counters) of the port to which the specified host is affiliated.
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).
The following IGMP host statistics are returned when you specify the -handle argument:
nvalid_pkts
Number of invalid IGMP packets received. Invalid
IGMP packets include::
invalid IGMP checksum
invalid packet length
invalid IGMP types
ropped_pkts
Will always return 0 because Spirent HLTAPI currently
does not drop valid IGMP packets.
ost_addr
IP address of host whose group membership stats are being
displayed.
roup_addr
Group membership IP address of host whose group membership
stats are being displayed.
roup_membership_stats
List of group membership statistics.
tate
State of group membership of host whose group membership
stats are being displayed.
UNDEFINED - The state is not defined.
NON_MEMBER - The host does not belong to the group on the
interface. Non-member is the initial state for all
memberships on all network interfaces.
DELAYING_MEMBER - The host belongs to the group on the
interface and has a report delay timer running for that
membership.
IDLE_MEMBER - The host belongs to the group on the interface
and does not have a report delay timer running for that
membership.
RETRYING_MEMBER - This state applies to IGMPv1/IGMPv2 hosts
when ForceRobustJoin is True. The host is
retransmitting its initial "join" before transitioning
from the NON_MEMBER state to the DELAYING_MEMBER or
IDLE_MEMBER state.
INCLUDE - Data from the specified sources are filtered and
forwarded to the host by the multicast router.
EXCLUDE - Data from the specified sources are filtered and
not forwarded to the host by the multicast router.
oin_latency
The time, in milliseconds, between sending the IGMP join and
receiving the multicast data for the channel specified in
the join message. This value is valid only when
"sth::emulation_igmp_control -calculate_latency" is set to 1.
eave_latency
The time, in milliseconds, between sending the IGMP leave
for a channel and when multicast data has stopped being
received. This value is valid only when
"sth::emulation_igmp_control -calculate_latency" is set to 1.
host_addr Host IP address
group_addr Group IP multicast address
state Current state of the IGMP group
state_change_timestamp Timestamp of the IGMP group membership state change
join_timestamp Transmit timestamp of the initial IGMP join message
leave_timestamp Transmit timestamp of the IGMP leave message
join_failure Indicates whether or not multicast traffic was received
duplicate_join Indicates whether or not the DUT was already forwarding
multicast prior to a join being sent
The following IGMP port statistics are returned when you specify the -port_handle argument:
igmpv1_queries_rx Number of IGMPv1 membership query messages
received.
igmpv1_group_queries_rx Number of IGMPv1 group queries received.
igmpv1_mem_reports_tx Number of IGMPv1 membership reports sent.
igmpv1_mem_reports_rx Number of IGMPv1 membership reports received.
igmpv2_queries_rx Number of IGMPv2 membership query messages
received.
igmpv2_group_queries_rx Number of IGMPv2 group queries received.
igmpv2_mem_reports_tx Number of IGMPv2 membership reports sent.
igmpv2_mem_reports_rx Number of IGMPv2 membership reports received
igmpv2_leave_tx Number of leave group messages sent.
igmpv3_queries_rx Number of IGMPv1 membership query messages
received.
igmpv3_group_queries_rx Number of IGMPv3 group queries received.
igmpv3_group_src_queries_rx Number of group- and source-specific
queries received.
igmpv3_mem_reports_tx Number of IGMPv3 membership reports sent.
igmpv3_mem_reports_rx Number of IGMPv3 membership reports received.
The following session statistics are returned:
session Session statistics for all multicast groups.
session.<IGMP session handle>
Displays all session statistics for the specified
session handle.
session.<IGMP session handle>.max_join_latency
Maximum join latency for the specified session
handle.
session.<IGMP session handle>.min_join_latency
Minimum join latency for the specified session
handle.
session.<IGMP session handle>.avg_join_latency
Average join latency for the specified session
handle.
session.<IGMP session handle>.min_leave_latency
Minimum leave latency for the specified session
handle.
session.<IGMP session handle>.max_leave_latency
Maximum leave latency for the specified session
handle.
session.<IGMP session handle>.avg_leave_latency
Average leave latency for the specified session
handle.
The following return values are not supported:
For IGMP over PPPoX
grp.<mcast_addr>.join.min - Minimum join latency per group
grp.<mcast_addr>.join.max - Maximum join latency per group
grp.<mcast_addr>.join.avg - Average join latency per group
grp.<mcast_addr>.leave.min - Minimum leave latency per group
grp.<mcast_addr>.leave.max - Maximum leave latency per group
grp.<mcast_addr>.leave.avg - Average leave latency per group
grp.<mcast_addr>.leave_join.min - Minimum latency to leave a group and to
join another group
grp.<mcast_addr>.leave_join.max - Maximum latency to leave a group and to
join another group
grp.<mcast_addr>.leave_join.avg - Average latency to leave a group and to
join another group
aggregate.join.min - Minimum value across all groups
aggregate.join.max - Maximum value across all groups
aggregate.join.avg - Average value across all groups
aggregate.leave.min
aggregate.leave.max
aggregate.leave.avg
aggregate.leave_join.min
aggregate.leave_join.max
Description¶
The sth::emulation_igmp_info function retrieves statistics about the number of
invalid and dropped packets on the specified host as well as several port and
session statistics.
Examples¶
#### HLTAPI for Tcl ####
When you call sth::emulation_igmp_info, the contents of the returned keyed list depends on the status of the call. For example:
sth::emulation_igmp_info -handle $handle1
Sample Output:
{group_membership_stats {{group_addr {{225 {{0 {{0 {{1 {{host_addr {{192 {{85
{{1 {{4 {{state NON_MEMBER} {state_change_timestamp 1Days-13:19:35.31829383}
{Join_timestamp 1Days-13:18:49.92584001} {leave_timestamp
1Days-13:19:35.31873498} {join_latency 0} {leave_latency 10012.53486}
{join_failure false} {duplicate_join true}}} {5 {{state NON_MEMBER}
{state_change_timestamp 1Days-13:19:35.31834067} {Join_timestamp
1Days-13:18:49.92584595} {leave_timestamp 1Days-13:19:35.31875323} {join_latency
0} {leave_latency 10012.51661} {join_failure false} {duplicate_join true}}} {6
{{state NON_MEMBER} {state_change_timestamp 1Days-13:19:35.31837744}
{Join_timestamp 1Days-13:18:49.92584874} {leave_timestamp
1Days-13:19:35.31875760} {join_latency 0} {leave_latency 10012.51224}
{join_failure false} {duplicate_join true}}}}}}}}}}}}}}}}}}}}}}} {session
{{igmphostconfig1 {{min_join_latency 0} {max_join_latency 0} {avg_join_latency
0} {min_leave_latency 0} {max_leave_latency 0} {avg_leave_latency 0}}}}} {status
1}
If there is an error, you will see:
{status 0} {log {Error message}}
The following example returns the statistics for the specified port:
sth::emulation_igmp_info -port_handle $tgen1_port
Sample Output:
{port_stats {{port1 {{- {{invalid_pkts 0} {dropped_pkts 0}}}
{V1 {{igmpv1_mem_reports_rx 0} {igmpv1_mem_reports_tx 2}
{igmpv1_queries_rx 0}}} {V3 {{igmpv3_mem_reports_rx 0}
{igmpv3_mem_reports_tx 0} {igmpv3_group_queries_rx 0}
{igmpv3_queries_rx 0} {igmpv3_group_src_queries_rx 0}}}
{V2 {{igmpv2_queries_rx 0} {igmpv2_leave_tx 0}
{igmpv2_mem_reports_rx 0} {igmpv2_mem_reports_tx 0}
{igmpv2_group_queries_rx 0}}}}}}} {status 1}
The following example clears all statistics on the specied IGMP session handle:
sth::emulation_igmp_info -handle $igmpSession -mode clear_stats
Sample Output:
{status 1}
#### HLTAPI for Python ####
The following example returns the statistics for the specified port:
results_ret1 = sth.emulation_igmp_info (
port_handle = port_handle[0],
mode = 'stats');
Sample Output:
{'status': '1', 'port_stats': {'port1': {'V1': {'igmpv1_mem_reports_tx': '0',
'igmpv1_mem_reports_rx': '0', 'igmpv1_queries_rx': '0'},
'V2': {'igmpv2_leave_tx': '0', 'igmpv2_mem_reports_rx': '0',
'igmpv2_group_queries_rx': '0', 'igmpv2_queries_rx': '1',
'igmpv2_mem_reports_tx': '0'}, 'V3': {'igmpv3_queries_rx': '0',
'igmpv3_mem_reports_tx': '0', 'igmpv3_group_queries_rx': '0',
'igmpv3_mem_reports_rx': '0', 'igmpv3_group_src_queries_rx': '0'},
'-': {'dropped_pkts': '0', 'invalid_pkts': '0'}}}}
#### HLTAPI for Perl ####
The following example returns the statistics for the specified port:
my %results_ret1 = sth::emulation_igmp_info (
port_handle => "$hport[1]",
mode => 'stats');
Sample Output:
$VAR1 = 'port_stats';
$VAR2 = {
'port1' => {
'-' => {
'dropped_pkts' => '0',
'invalid_pkts' => '0'
},
'V3' => {
'igmpv3_queries_rx' => '0',
'igmpv3_group_queries_rx' => '0',
'igmpv3_mem_reports_rx' => '0',
'igmpv3_group_src_queries_rx' => '0',
'igmpv3_mem_reports_tx' => '2'
},
'V2' => {
'igmpv2_group_queries_rx' => '0',
'igmpv2_mem_reports_tx' => '0',
'igmpv2_mem_reports_rx' => '1',
'igmpv2_leave_tx' => '0',
'igmpv2_queries_rx' => '0'
},
'V1' => {
'igmpv1_queries_rx' => '0',
'igmpv1_mem_reports_rx' => '0',
'igmpv1_mem_reports_tx' => '0'
}
}
};
$VAR3 = 'status';
$VAR4 = '1';
Note
If you configure over 1000 host-group pairs, the lower layer only returns avg/min/max latencies in the returned keyed list. If you configure 1000 or less host-group pairs, the returned keyed list contains individual latencies.
End of Procedure Header