802.1x Functions¶
sth::emulation_dot1x_config¶
Purpose¶
Creates, modifies or deletes 802.1x emulation on the specified test port.
IEEE 802.1x defines a port-based access control and authentication protocol that prevents unauthorized clients from connecting to a LAN through publicly accessible ports unless they are properly authenticated.
IEEE 802.1x supports multiple authentication methods based on Extensible Authentication Protocol (EAP).
Synopsis¶
Note
- M indicates that the argument is Mandatory .
- S indicates the argument is for
scalingscenarios.
sth::emulation_dot1x_config
[-mode {create|enable|modify|activate|delete} M]
[-port_handle <port_handle>]
[-handle <handle>]
[-auth_retry_count <0-4294967295>]
[-auth_retry_interval <0-4294967295>]
[-authenticator_mac <aa:bb:cc:dd:ee:ff>]
[-certificate <certificate>]
[-certificate_wildcard {0 | 1}]
[-eap_auth_method {md5|fast|tls}]
[-encapsulation {ethernet_ii | ethernet_ii_vlan | ethernet_ii_qinq}]
[-gateway_ip_addr <a.b.c.d> ]
[-gateway_ip_addr_step <a.b.c.d>]
[-gateway_ipv6_addr <aaaa:bbbb:cccc:dddd:eeee:ffff:gggg:hhhh>]
[-gateway_ipv6_addr_step <aaaa:bbbb:cccc:dddd:eeee:ffff:gggg:hhhh>]
[-ip_version {ipv4 | ipv6 | ipv4_6 | none}]
[-local_ip_addr <a.b.c.d>]
[-local_ip_addr_step <a.b.c.d>]
[-local_ip_prefix_len <0-32>]
[-local_ipv6_addr <aaaa:bbbb:cccc:dddd:eeee:ffff:gggg:hhhh>]
[-local_ipv6_addr_step <aaaa:bbbb:cccc:dddd:eeee:ffff:gggg:hhhh>]
[-local_ipv6_prefix_len <0-128>]
[-mac_addr <aa:bb:cc:dd:ee:ff>]
[-mac_addr_step <aa:bb:cc:dd:ee:ff>]
[-max_authentications <1-4294967295>]
[-name <ALPHANUM>]
[-num_sessions <1-32768>]
[-pac_key_file <pac_key_file>]
[-pac_key_file_wildcard {0 | 1}]
[-password <ALPHANUM>]
[-password_wildcard {0 | 1}]
[-qinq_incr_mode {inner | outer | both}]
[-retransmit_count <0-4294967295>]
[-retransmit_interval <0-4294967295>]
[-supplicant_auth_rate <1-4294967295>]
[-supplicant_logoff_rate <1-4294967295>]
[-use_pae_group_mac {0 | 1}]
[-username <ALPHANUM>]
[-username_wildcard {0 | 1}]
[-vlan_id <0-4095>]
[-vlan_cfi {0 | 1}]
[-vlan_ether_type <0x8100|0x88A8|0x9100|0x9200>]
[-vlan_id_count <1-4096>]
[-vlan_id_step <0-4095>]
[-vlan_user_priority <0-7>]
[-vlan_outer_id <0-4095>]
[-vlan_outer_cfi <0 | 1>]
[-vlan_outer_ether_type <0x8100|0x88A8|0x9100|0x9200>]
[-vlan_outer_id_count <1-4096>]
[-vlan_outer_id_step <0-4095>
[-vlan_outer_user_priority <0-7>]
[-wildcard_pound_start <0-65535>]
[-wildcard_pound_end <0-65535>]
[-wildcard_pound_fill <0-9>]
[-wildcard_question_start <0-65535>]
[-wildcard_question_end <0-65535>]
[-wildcard_question_fill <0-9>]
[-expand {true|false} S]
[-duplicate_uid_password {true|false}]
[-enable_client_cert {true|false}]
[-inner_certificate <ANY>]
[-inner_password <ANY>]
[-inner_user_id <ANY>]
[-inner_tunnel_eap_auth_method {auto|gtc|md5|mschapv2}]
[-peap_version {peapauto|peapv0|peapv1}]
[-use_authenticator_mac_for_all {true|false}]
[-dbd_mechanism {0 | 1}]
Arguments¶
-
-mode¶ Specifies the action to perform. This argument is Mandatory . Possible values are:
create - Configures 802.1x devices on the port specified with the -port_handle argument. enable - Creates 802.1x emulation on the device specified with the -handle argument. modify - Changes the configuration for the 802.1x device identified by the -handle argument. activate - Used for ``Scaling`` scenarios. 1. Enables 802.1x devices and configures 802.1x 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_dot1x_config`` function for more information. For this mode, only the following set of options are valid:: authenticator_mac auth_retry_count auth_retry_interval duplicate_uid_password certificate eap_auth_method enable_client_cert inner_certificate inner_password inner_userid inner_tunnel_eap_auth_method pac_key_file password peap_version retransmit_count retransmit_interval use_authenticator_mac_for_all use_pae_group_mac username 2. Creates devices and enables 802.1x 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 -link_local_ipv6_addr -link_local_ipv6_addr_step -intf_ipv6_addr -intf_ipv6_addr_step -intf_ipv6_prefix_len -link_local_ipv6_prefix_len -gateway_ipv6_addr -gateway_ipv6_addr_step -mac_addr_step_per_port -mac_addr_step_per_vlan -ip_step_per_port -ip_step_per_vlan -ipv6_step_per_vlan -ipv6_step_per_port -link_local_ipv6_step_per_port -link_local_ipv6_step_per_vlan .. note:: Please refer to the emulation_device_config documentation. delete - Deletes the 802.1x device identified by the -handle argument
-
-port_handle¶ Specifies the handle of the port on which to create the 802.1x supplicants when -mode is set to create. This argument is Mandatory for the create mode only.
-
-handle¶ Specifies the handle of the 802.1x supplicants to use when -mode is set to modify, enable or delete. This argument is Mandatory for modify, enable and delete mode. When -mode is set to either modify or delete, the value is the device handle returned by the
sth::emulation_dot1x_configfunction. When -mode is set to enable, the value is the device handle returned by other protocol emulation functions with mode create.
-
-auth_retry_count¶ Specifies the number of retries attempted when authentication fails. Possible values range from 0 to 4294967295. The default value is 10.
-
-auth_retry_interval¶ Specifies the number of milliseconds to wait between authentication attempts. Possible values range from 0 to 4294967295. The default value is 1000.
-
-authenticator_mac¶ Specifies the MAC address of the authenticator switch/router. This argument is available when -use_pae_group_mac is 0. The default value is 00:10:94:00:00:02.
-
-certificate¶ Specifies X.509 supplicant certificate(s). You can use wildcard characters to generate a unique certificate name for each supplicant. Please refer to -certificate_wildcard for more information. This argument is available and Mandatory when -eap_auth_method is set to tls.
-
-certificate_wildcard¶ Enables or disables wildcard substitution in the -certificate argument. Possible values are 0 (disable) and 1 (enable). The default value is 0. If the value is set to 1, any wildcards used in -certificate are replaced with the corresponding values for -wildcard_pound_start, -wildcard_pound_end, -wildcard_question_start and -wildcard_question_end. If the value is 0, wildcards are not replaced in the specified certificate.
-
-eap_auth_method¶ Specifies the EAP authentication method. Possible values are:
tls - Transport Layer Security, a cryptographic protocol defined in RFC 5216. It encrypts the segments of network connections above the Transport Layer, using symmetric cryptography for privacy and a keyed message authentication code for message reliability. fast - Flexible Authentication via Secure Tunneling. md5 - Message Digest 5, a widely used cryptographic hash function with a 128-bit hash value.The default value is md5.
-
-encapsulation¶ Specifies the type of Layer 2 encapsulation. Possible values are:
ethernet_ii - Ethernet II ethernet_ii_vlan - Ethernet II with a single VLAN tag. ethernet_ii_qinq - Ethernet II with two VLAN tags.
The default value is ethernet_ii.
-
-gateway_ip_addr¶ Configures the first IPv4 gateway address for the emulated 802.1x devices. The value must be in IPv4 format. The default value is 192.85.1.1. This argument is applicable when -ip_version is set to ipv4.
-
-gateway_ip_addr_step¶ Specifies the incrementing IPv4 address step for 802.1x devices. The value must be in IPv4 format. The default value is 0.0.0.0. This argument is applicable when -ip_version is set to ipv4.
-
-gateway_ipv6_addr¶ Configures the first IPv6 gateway address for the emulated 802.1x devices. The value must be in IPv6 format. The default value is 2001::1. This argument is applicable when -ip_version is set to ipv6.
-
-gateway_ipv6_addr_step¶ Defines the increment used to generate IPv6 gateway addresses for multiple devices. The value must be in IPv6 format. The default value is ::. This argument is applicable when -ip_version is set to ipv6.
-
-ip_version¶ Specifies the IP version of the emulated 802.1x device. Possible values are:
ipv4 - IPv4 address format ipv6 - IPv6 address format ipv4_6 - Dual stack none - the 802.1x device does not have IP encapsulationThe default value is ipv4.
Note
You cannot change -ip_version after you have created 802.1x devices.
-
-local_ip_addr¶ Specifies the starting IPv4 address of the emulated 802.1x devices. The value must be in IPv4 format. The default value 192.85.1.3. This argument is applicable when -ip_version is set to ipv4.
-
-local_ip_addr_step¶ Specifies the incrementing IPv4 address step for 802.1x devices. The value must be in IPv4 format. The default value is 0.0.0.1. This argument is applicable when -ip_version is set to ipv4.
-
-local_ip_prefix_len¶ Specifies the IPv4 address prefix length. Possible values range from 0 to 32. The default value is 24. This argument is applicable when -ip_version is set to ipv4.
-
-local_ipv6_addr¶ Specifies the starting IPv6 address of the emulated 802.1x devices. The value must be in IPv6 format. The default value is 2001::2. This argument is applicable when -ip_version is set to ipv6.
-
-local_ipv6_addr_step¶ Defines the increment used to generate IPv6 gateway addresses for multiple devices. The value must be in IPv4 format. The default value is 0::1. This argument is applicable when -ip_version is set to ipv6.
-
-local_ipv6_prefix_len¶ Specifies the IPv6 address prefix length. Possible values range from 0 to 128. The default value is 64. This argument is applicable when -ip_version is set to ipv6.
-
-mac_addr¶ Defines the first MAC address to use when emulating multiple 802.1x supplicants. Each supplicant must have a unique source MAC address. The value must be in MAC format. The default value is 00:10:94:00:00:01.
-
-mac_addr_step¶ Specifies the increment to generate additional MAC addresses for multiple 802.1x supplicants. The default value is 00:00:00:00:00:01.
-
-max_authentications¶ Specifies the number of maximum outstanding supplicant authentications that can occur at any given time. This is a port-wide argument. Any subsequent use of This argument on a port after the initial “-mode create” will overwrite any previous setting. Possible values range from 1 to 4294967295. The default value is 100.
-
-name¶ Specifies the name of emulated 802.1x device.
-
-num_sessions¶ Specifies the number of 802.1x devices to create on the specified port. The maximum number of 802.1x supplicants you can create per port is 32k. Possible values range from 1 to 32768. The default value is 1.
-
-pac_key_file¶ Specifies the PAC (Portal Access Control) key file(s) required for EAP-FAST authentication. PAC provides control over frame transmission and reception by clients attached to its Controlled Port, and uses the MAC Service provided by a Common Port.
You can use wildcard characters to generate a unique pac key filename for each supplicant. Please refer to -pac_key_file_wildcard for more information. This argument is available and Mandatory when -eap_auth_method is set to fast.
-
-pac_key_file_wildcard¶ Enables or disables wildcard substitution in the -pac_key_file argument. Possible values are 1 (enable) and 0 (disable). The default value is 0. If the value is set to 1, any wildcards used in pac_key_file are replaced with the corresponding values for -wildcard_pound_start, -wildcard_pound_end, -wildcard_question_start and -wildcard_question_end. If the value is 0, wildcards are not replaced in the specified pac key file.
-
-password¶ Specifies the supplicant password(s). Wildcard characters can be used to generate a unique password for each supplicant. Please refer to -password_wildcard for more information. The default value is sprient.
-
-password_wildcard¶ Enables or disables wildcard substitution in the -password argument. Possible values are 1 (enable) and 0 (disable). The default value is 0. If the value is set to 1, any wildcards used in -password are replaced with the corresponding values for -wildcard_pound_start, -wildcard_pound_end, -wildcard_question_start and -wildcard_question_end. If the value is 0, wildcards are not replaced in the specified password.
-
-qinq_incr_mode¶ Specifies the Vlan ID increment mode for ethernet_ii_qinq encapsulation. This parameter is available when -encapsulation is set to ethernet_ii_qinq. Possible values are inner, outer and both. The default value is both. The modes are described below:
inner - When the number of sessions is greater than the inner VLAN count times the outer VLAN count, the inner VLAN ID is incremented first until the specified number of inner VLANs is exhausted, then the outer VLAN ID is incremented. This continues in a round-robin fashion until the number of sessions is exhausted. outer - When the number of sessions is greater than the inner VLAN count times the outer VLAN count, the outer VLAN ID is incremented first until the specified number of outer VLANs is exhausted, and then the inner VLAN ID is incremented. This continues in a round-robin fashion until the number of sessions is exhausted. both - When the number of sessions is greater than the inner VLAN count times the outer VLAN count, the inner VLAN ID and outer VLAN ID increment at the same time. This continues in a round-robin fashion until the number of sessions is exhausted.
-
-retransmit_count¶ Specifies the number of times to resend an unacknowledged message. Possible values range from 0 to 4294967295. The default value is 10.
-
-retransmit_interval¶ Specifies the number of milliseconds to wait between packet retransmissions. Possible values range from 0 to 4294967295. The default is 1000.
-
-supplicant_auth_rate¶ Specifies the supplicant authentication rate in seconds. This is a port-wide argument. Any subsequent use of this argument on a port after the initial “-mode create” will overwrite any previous setting. Possible values range from 1 to 4294967295. The default is 100.
-
-supplicant_logoff_rate¶ Specifies the supplicant logoff rate in seconds. This is a port-wide argument. Any subsequent use of This argument on a port after the initial “-mode create” will overwrite any previous setting. Possible values range from 1 to 4294967295. The default value is 100.
-
-use_pae_group_mac¶ Indicates whether to use the PAE (port access entity) multicast MAC in transmitted EAPOL (EAP over LAN) packets. PAE is the protocol entity associated with a Port. It can support the protocol functionality associated with the Authenticator, the Supplicant, or both. Possible values are 0 and 1. The default value is 1, in which case the PAE group MAC will be set as the authenticator MAC, and -authenticator_mac will be ignored.
-
-username¶ Specifies 802.1x supplicant user id(s). You can use wildcard characters generate a unique password for each supplicant. Refer to -username_wildcard for more information. The default value is spirent.
-
-username_wildcard¶ Enables or disables wildcard substitution in the -username argument. Possible values are 1 (enable) and 0 (disable). The default value is 0. If the value is set to 1, any wildcards used in -username are replaced with the corresponding values for -wildcard_pound_start, -wildcard_pound_end, -wildcard_question_start and -wildcard_question_end. If the value is wildcards are not replaced in the specified username.
-
-vlan_cfi¶ Sets the canonical format indicator (CFI) field in VLAN for the emulated router node. Possible values are 0 (Ethernet) and 1 (Token Ring). The default value is 1.
-
-vlan_ether_type¶ Specifies the VLAN ether type for the first VLAN sub-interface. Possible values are 0x8100, 0x88A8, 0x9100 and 0x9200. The default value is 0x8100.
-
-vlan_id¶ Specifies the starting VLAN ID for the ethernet_ii_vlan encapsulation or the ethernet_ii_qinq encapsulation. Possible values range from 0 to 4095. The default value is 100. This argument is available when -encapsulation is set to ethernet_ii_qinq or ethernet_ii_vlan.
-
-vlan_id_count¶ Specifies the number of VLAN IDs to use when generating 802.1x devices. Possible values range from 1 to 4096. The default value is 1.
-
-vlan_id_step¶ Specifies the step size by which the VLAN ID is incremented. Possible values range from 0 to 4095. The default value is 1.
-
-vlan_user_priority¶ Specifies the VLAN user priority assigned to emulated 802.1x supplicants. Possible values range from 0 to 7. The default value is 0.
-
-vlan_outer_cfi¶ Specifies the CFI field in outer VLAN tag for the emulated device. Possible values are 0 (Ethernet) and 1 (Token Ring). The default value is 1.
-
-vlan_outer_ether_type¶ Specifies the VLAN ether type for the outer VLAN header. Possible values are 0x8100, 0x88A8, 0x9100 and 0x9200. The default value is 0x8100.
-
-vlan_outer_id¶ Specifies the starting outer VLAN ID for the QinQ encapsulation. Possible values range from 0 to 4095. The default value is 100. This argument is available when -encapsulation is set to ethernet_ii_qinq.
-
-vlan_outer_id_count¶ Specifies the number of outer VLAN IDs to use when generating 802.1x devices. Possible values range from 1 to 4096. The default value is 1.
-
-vlan_outer_id_step¶ Specifies the step size by which the outer VLAN ID is incremented. Possible values range from 0 to 4095. The default value is 1.
-
-vlan_outer_user_priority¶ Specifies the VLAN priority to assign to the outer VLAN header. Possible values range from 0 to 7. The default value is 0.
-
-wildcard_pound_start¶ Starting value to replace the wildcard pound (#) characters in username, password, pac_key_file or certificate_file, such as user# or pwd#. Possible values range from 0 to 65535. The default value is 1. This argument is available when -username_wildcard, -password_wildcard, -pac_key_file_wildcard or -certificate_file_wildcard is enabled.
-
-wildcard_pound_end¶ Final numerical value to replace the wildcard pound (#) character in username, password, pac_key_file or certificate_file, such as user# or pwd#. Possible values range from 0 to 65535. The default value is 1. This argument is available when -username_wildcard, -password_wildcard, -pac_key_file_wildcard or -certificate_file_wildcard is enabled.
-
-wildcard_pound_fill¶ Wildcard fill character for -wildcard_question_start and -wildcard_question_end. Possible values range from 0 to 9. The default value is 0. If it is set to 0, the numbers are replaced without leading zeroes. Otherwise, leading zeroes are added to ensure that the number is at least the specified number of digits wide. This argument is available when -username_wildcard, -password_wildcard, -pac_key_file_wildcard or -certificate_file_wildcard is enabled.
-
-wildcard_question_start¶ Starting numerical value to replace the wildcard question mark character in username, password, pac_key_file and certificate_file. Possible values range from 0 to 65535. The default value is 1.
This argument is available when -username_wildcard, -password_wildcard, -pac_key_file_wildcard or -certificate_file_wildcard is enabled.
-
-wildcard_question_end¶ Final numerical value to replace the wildcard question mark character in username password pac_key_file or certificate_file, such as user? or pwd?. Possible values range from 0 to 65535. The default value is 1. This argument is available when -username_wildcard, -password_wildcard, -pac_key_file_wildcard or -certificate_file_wildcard is enabled.
-
-wildcard_question_fill¶ Wildcard fill character for -wildcard_question_start and -wildcard_question_end. Possible values range from 0 to 9. The default value is 0. If it is set to 0, the numbers are replaced without leading zeroes. Otherwise, leading zeroes are added to ensure that the number is at least the specified number of digits wide. This argument is available when -username_wildcard, -password_wildcard, -pac_key_file_wildcard or -certificate_file_wildcard is enabled.
-
-expand¶ Spirent Extension (for Spirent HLTAPI only).
Determines whether to expand the specified 802.1x device parameters into emulated 802.1x device objects. It is used in
Scalingtest scenarios.When set to true, a list of emulated device handles (handle_list) with enabled 802.1x device configurations is created.
When set to false, only 802.1x parameters are configured with no handle returned.
-
-duplicate_uid_password¶ Duplicate UserID and Password from Supplicant’s to inner tunnel. Use the same UserID and Password for both tunnel and inner tunnel EAP authentication. Possible values are true and false. The default is true Applicable only in -mode activate when -block_mode or -expand is specified.
-
-enable_client_cert¶ Supplicant can use X.509 certificate(s) if required. Possible values are true and false. The default is true Applicable only in -mode activate when -block_mode or -expand is specified.
-
-inner_certificate¶ X.509 certificate(s) required for EAP-TLS authentication for inner tunnel TLS. The default is “” (empty string) Applicable only in -mode activate when -block_mode or -expand is specified.
-
-inner_password¶ Supplicant password(s) of inner tunnel. The default is spirent Applicable only in -mode activate when -block_mode or -expand is specified.
-
-peap_version¶ Specifies the version information of EAP-PEAP used by Supplicant. The packet of version other than specified would be rejected and a Legacy NAK would be sent. The default is peapauto Applicable only in -mode activate when -block_mode or -expand is specified.
-
-inner_user_id¶ Specifies the supplicant user id(s) of inner tunnel. The default is spirent Applicable only in -mode activate when -block_mode or -expand is specified.
-
-inner_tunnel_eap_auth_method¶ Specifies the EAP authentication method for supplicant(s) used in inner tunnel. The default is auto Applicable only in -mode activate when -block_mode or -expand is specified.
-
-use_authenticator_mac_for_all¶ Enables or disables the use authenticator MAC argument for all transmissions. Possible values are true and false. The default is false Applicable only in -mode activate when -block_mode or -expand is specified.
-
-dbd_mechanism¶ Enables or disables the dbd (device behind device) mechanism on 802.1x devices. Possible values are 1 (enable) and 0 (disable). The default value is 1. If the value is set to 1 and -encapsulation is set to ethernet_ii_vlan or ethernet_ii_qinq, it creates one 802.1x device and an additional device between the 802.1x emulation and the DUT. If the value is set to 0 and -encapsulation is set to ethernet_ii_vlan or ethernet_ii_qinq, it creates single 802.1x device with vlan encapsulation.
Arguments Unsupported by Save as HLTAPI¶
None
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 or $FAILURE
log An error message if command returns {status 0}.
port_handle The port handle on which 802.1x devices was configured.
handle The handle(s) that identify the 802.1x emulation created by the
``sth::emulation_802.1x_config`` function.
handle_list The emulated device handles list with enabled 802.1x device
configurations is created when expand is set true.
Description¶
The sth::emulation_dot1x_config function creates, modifies or deletes the
802.1x emulation. Use the -mode argument to specify the action to perform.
(See the -mode argument description for information about the actions.)
When you create 802.1x devices, you must use the -port_handle argument to
specify the Spirent HLTAPI port that the emulated 802.1x supplicants will use
for 802.1x communication. (The port handle value is contained in the keyed list
returned by the sth::connect function.)
In addition to specifying the -port_handle, you must also provide one or more of the following arguments when you create 802.1x supplicants or use their default values:
-num_sessions (the number of 802.1x supplicants to emulate)
-encapsulation (Layer 2 encapsulation)
-ip_version (IP version)
-eap_auth_method (EAP authentication method)
-username (if specifying an authentication method)
-password (if specifying an authentication method)
-pac_key_file (if -eap_auth_method is set to fast)
-certificate (if -eap_auth_method is set to tls)
In the modify mode, you can change the configuration of the created 802.1x devices except for these arguments: -encapsulation, and -ip_version. In the delete mode, you can remove the created device. If a creation, configuration, or deletion fails, Spirent HLTAPI returns an error message. For example, if the user tries to modify a non-existing session handle, an error message will be returned.
Examples¶
#### HLTAPI for Tcl ####
The following example creates 1000 802.1x devices:
sth::emulation_dot1x_config -mode "create" \
-port_handle port1 \
-num_sessions 1000 \
-name Dot1x_1 \
-encapsulation ethernet_ii \
-ip_version ipv4 \
-mac_addr 00:33:00:00:00:01 \
-local_ip_addr 10.0.0.22 \
-gateway_ip_addr 10.0.0.1 \
-supplicant_auth_rate 100 \
-supplicant_logoff_rate 300 \
-max_authentications 600 \
-retransmit_count 300 \
-eap_auth_method md5 \
-username spirent \
-password spirent \
Sample Output:
{port_handle port1} {handle host3}{status 1}
The following example modifies the created 802.1x device:
sth::emulation_dot1x_config -mode modify \
-handle host3 \
-supplicant_auth_rate 200 \
Sample Output:
{handle host3} {status 1}
The following example deletes the created 802.1x device:
sth::emulation_dot1x_config -mode delete \
-handle host3 \
Sample Output:
{status 1}
The following example uses the function in Scaling mode (-mode activate)
with -port_handle and -block_mode:
set dot1x_ret [sth::emulation_dot1x_config\
-mode activate \
-port_handle $port1\
-count 2 \
-block_mode ONE_DEVICE_PER_BLOCK\
-block_name_index 1\
-authenticator_mac 00:10:94:00:00:03\
-auth_retry_count 11\
-auth_retry_interval 1100\
-duplicate_uid_password false\
-certificate spirent@s\
-eap_auth_method md5\
-enable_client_cert false\
-inner_certificate spirent@s\
-inner_password spirent1\
-inner_userid spirent1\
-inner_tunnel_eap_auth_method auto\
-pac_key_file sample_key.key\
-username spirent\
-password spirent\
-peap_version peapv0\
-retransmit_count 11\
-retransmit_interval 1100\
-use_authenticator_mac_for_all true\
-use_pae_group_mac 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_ipv6_prefix_len 65 \
-ipv6_step_per_vlan {"" ::2} \
-ipv6_step_per_port ::1 \
-intf_prefix_len 22 \
-link_local_ipv6_step_per_port ::4 \
-link_local_ipv6_step_per_vlan {::4 ::5} \
-name DEVICE_BLOCK_DOT1x_ROUTER \
-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\
-router_id_ipv6 0101::011 \
-router_id_ipv6_step ::11 \
-intf_ip_addr 11.111.11.11 \
-gateway_ip_addr 11.111.11.1 \
-link_local_ipv6_addr 2000::2 \
-link_local_ipv6_addr_step ::1 \
-intf_ipv6_addr 1111::3e9 \
-intf_ipv6_addr_step ::1 \
-link_local_ipv6_prefix_len 64 \
-gateway_ipv6_addr 1111::1 \
-gateway_ipv6_addr_step ::1 \
-expand true ]
.. note:: Devices created using this function will have unique usernames and passwords in an
incremented manner.
As per the above example API, the usernames and passwords for the devices
will be configured as spirent1, spirent2, spirent3 and so on.
If the user provides spirent_1 as the value for -username, and test as the value for -password, then
the usernames will be spirent_11, spirent_12, spirent_13 and so on and
the passwords will be test1, test2, test3 and so on.
Sample Output:
{param_handle emulateddevicegenparams1} {status 1} {handle_list {emulateddevice1
emulateddevice2 emulateddevice3 emulateddevice4 emulateddevice5 emulateddevice6
emulateddevice7 emulateddevice8}} {handle {}} {handles {emulateddevice1
emulateddevice2 emulateddevice3 emulateddevice4 emulateddevice5 emulateddevice6
emulateddevice7 emulateddevice8}}
#### HLTAPI for Python ####
The following example creates 5 802.1x devices:
device_ret0 = sth.emulation_dot1x_config (
mode = 'create',
ip_version = 'ipv4',
username_wildcard = '1',
password_wildcard = '1',
wildcard_pound_start= '1',
wildcard_pound_end = '3',
wildcard_question_start= '1',
wildcard_question_end= '4',
username = 'spirent#',
password = 'spirent?',
encapsulation = 'ethernet_ii',
port_handle = port_handle[0],
supplicant_logoff_rate= '100',
max_authentications = '100',
supplicant_auth_rate= '100',
auth_retry_count = '10',
use_pae_group_mac = '1',
retransmit_interval = '1000',
authenticator_mac = '00:10:94:00:00:02',
eap_auth_method = 'md5',
retransmit_count = '10',
auth_retry_interval = '1000',
num_sessions = '5',
name = 'Device_1',
mac_addr = '00:10:94:00:00:01',
mac_addr_step = '00:00:00:00:00:01',
local_ip_prefix_len = '24',
gateway_ip_addr = '12.85.1.1',
local_ip_addr_step = '0.0.0.1',
gateway_ip_addr_step= '0.0.0.0',
local_ip_addr = '12.85.1.3');
Sample Output:
{'status': '1', 'handle': 'host3', 'port_handle': 'port1'}
#### HLTAPI for Perl ####
The following example creates 5 802.1x devices:
my %device_ret0 = sth::emulation_dot1x_config (
mode => 'create',
ip_version => 'ipv4',
username_wildcard => '1',
password_wildcard => '1',
wildcard_pound_start=> '1',
wildcard_pound_end => '3',
wildcard_question_start=> '1',
wildcard_question_end=> '4',
username => 'spirent#',
password => 'spirent?',
encapsulation => 'ethernet_ii',
port_handle => "$hport[1]",
supplicant_logoff_rate=> '100',
max_authentications => '100',
supplicant_auth_rate=> '100',
auth_retry_count => '10',
use_pae_group_mac => '1',
retransmit_interval => '1000',
authenticator_mac => '00:10:94:00:00:02',
eap_auth_method => 'md5',
retransmit_count => '10',
auth_retry_interval => '1000',
num_sessions => '5',
name => 'Device_1',
mac_addr => '00:10:94:00:00:01',
mac_addr_step => '00:00:00:00:00:01',
local_ip_prefix_len => '24',
gateway_ip_addr => '12.85.1.1',
local_ip_addr_step => '0.0.0.1',
gateway_ip_addr_step=> '0.0.0.0',
local_ip_addr => '12.85.1.3');
Sample Output:
$VAR1 = 'status';
$VAR2 = '1';
$VAR3 = 'handle';
$VAR4 = 'host3';
$VAR5 = 'port_handle';
$VAR6 = 'port1';
Note
You can generate outgoing usernames, passwords, pac key file names or certificate file names based on wildcard replacements. The following example generates 50 usernames, passwords and certificate files:
sth::emulation_dot1x_config -mode "create" \
-port_handle port1 \
-encapsulation ethernet_ii \
-ip_version ipv4 \
-mac_addr 00:66:00:00:00:01 \
-local_ip_addr 20.0.0.22 \
-gateway_ip_addr 20.0.0.1 \
-eap_auth_method tls \
-username User# \
-password acstest# \
-certificate "test1#.pem" \
-password_wildcard 1 \
-username_wildcard 1 \
-certificate_wildcard 1 \
-wildcard_pound_start 1 \
-wildcard_pound_end 50 \
The # character represents a counter. For example, define a counter to start at 1 (-wildcard_pound_start 1), run to 50 (-wildcard_pound_end), and increment by 1. Then, in the -username argument, specify User#, which would be replaced with User1, User2, and so on. When authentication begins, The wildcard is replaced with a counter, starting at 1. For example, User becomes User1, User2, and so on. If you do not specify, then no substitution will take place.
End of Procedure Header
Procedure Header
sth::emulation_dot1x_control¶
Purpose¶
Download or delete all certificates. Starts, stops and aborts the emulated 802.1x device.
Synopsis¶
Note
M indicates that the argument is Mandatory .
sth::emulation_dot1x_control
[-action {download|delete_all}]
[-certificate_dir]
[-handle <device handle>]
[-mode {start|stop|logout|abort}]
[-port_handle <port handle>] |
Arguments¶
-
-mode¶ Specifies the action to perform. Possible values are:
start - Start 802.1x supplicant authentication stop - Stop 802.1x supplicant authentication. The mode stop is same as the mode abort. logout - Log out of the 802.1x supplicant sessions abort - Aborts all 802.1x sessions and resets the 802.1x emulation engine on the specified device
-
-port_handle¶ Specifies a list of ports on which to perform the action. You must specify either -handle or -port_handle, but not both.
-
-handle¶ Specifies a list of 802.1x devices on which to perform the action. You must specify either -handle or -port_handle, but not both.
-
-action¶ Determines to download certificates to a specified port or delete all certificates from a specified port. You must specify the -port_handle argument when using this argument.
Note
You must download corresponding certificates to the specific port before you configure 802.1x supplicants with fast or tls authentication method on the port by using sth::emulation_dot1x_config. You can refer to Examples for more details.
-
-certificate_dir¶ Specifies the directory containing certificate(s) or PAC key file(s) to download. If the directory contains zip files, then these file will be downloaded to the ports and unzipped. The zip extensions currently supported are .zip, .tar and .tar.gz. This argument is available and Mandatory when -action is download.
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 or $FAILURE
log returned debug info for when status is $FAILURE.
Description¶
The sth::emulation_dot1x_control function provides the function to download
certificates to a specified port or delete all certificates from a specified port.
When you want to configure 802.1x suppliants with fast or tls authentication
method on a test port, you must download the associated certificates to the
specified port. (See the -action argument description for information)
After you create 802.1x devices, you can use sth::emulation_dot1x_control to perform the following actions: connecting, disconnecting, logging out or aborting 802.1x sessions. When you call this function, you specify either a port handle (-port_handle) or device handle (-handle) to apply the specified actions.
Examples¶
#### HLTAPI for Tcl ####
The following example deletes all certificates/PAC files:
sth::emulation_dot1x_control \
-action "delete_all" \
-port_handle port1\
Sample Output:
{status 1}
The following example downloads certificates/PAC files:
sth::emulation_dot1x_control \
-action "download" \
-certificate_dir "//10.61.37.32/ENGPhxPV /pac" \
-port_handle port1\
Sample Output:
{status 1}
The following example starts an authentication:
sth::emulation_dot1x_control \
-mode start \
-port_handle port1\
Sample Output:
{status 1}
The following example logs out of an authentication:
sth::emulation_dot1x_control \
-mode logout \
-port_handle port1\
Sample Output:
{status 1}
#### HLTAPI for Python ####
The following example starts an authentication:
ctrl_ret1 = sth.emulation_dot1x_control (
handle = device_list,
mode = 'start');
Sample Output:
{'status': '1'}
#### HLTAPI for Perl ####
The following example starts an authentication:
my %ctrl_ret2 = sth::emulation_dot1x_control (
handle => "$device_list",
mode => 'start');
Sample Output:
$VAR1 = 'status';
$VAR2 = '1';
End of Procedure Header
Procedure Header
sth::emulation_dot1x_stats¶
Purpose¶
Retrieves statistics for the 802.1x devices configured on the specified test port.
Synopsis¶
Note
M indicates that the argument is Mandatory .
sth::emulation_dot1x_stats
[-mode {aggregate|sessions} M]
[-port_handle <port_handle>]
[-handle <802.1x_device_handle>]
Arguments¶
-
-mode¶ Specifies statistics retrieval mode as either aggregate for all configured sessions or on a per session basis. This argument is mandatory. The modes are described below:
aggregate - retrieves statistics aggregated per port sessions - retrieves statistics per device
-
-port_handle¶ Specifies the port to retrieve statistics from. You must specify either -handle or -port_handle, but not both.
-
-handle¶ Specifies the handle of the 802.1x device to retrieve statistics from. You must specify either -handle or -port_handle, but not both.
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 or $FAILURE
log Error message if command returns {status 0}
The following keys are returned when you specify -mode aggregate:
Example: <port_handle>.statistics
attempt_auth_count
Total number of sessions initiated, including any retries.
success_auth_count
Total number of sessions successfully established.
failed_auth_count
Total number of sessions failed, including retries.
aborted_auth_count
Total number of sessions aborted.
attempt_re_auth_count
Number of reauthentication attempts.
success_re_auth_count
Number of successful reauthentication attempts.
failed_re_auth_count
Number of unsuccessful reauthentication attempts.
logoff_attempts
Number of logoff attempts.
failed_logoff_attempts
Number of unsuccessful logoff attempts.
success_logoff_attempts
Number of successful logoff attempts.
tx_start_pkts
Number of EAPOL-Start packets transmitted.
tx_logoff_pkts
Number of EAPOL-Logoff packets transmitted.
tx_key_pkts
Number of EAPOL-Key packets transmitted.
tx_eap_pkts
Number of EAP packets transmitted.
rx_eap_pkts
Number of EAP packets received.
rx_invalid_pkts
Number of invalid EAPOL packets received.
tx_eap_req_pkts
Number of EAP-Request packets transmitted.
rx_eap_req_pkts
Number of EAP-Request packets received.
tx_eap_resp_pkts
Number of EAP-Response packets transmitted.
rx_eap_resp_pkts
Number of EAP-Response packets received.
rx_eap_success_pkts
Number of EAP-Success packets received.
rx_eap_failure_pkts
Number of EAP-Failure packets received.
tx_eap_resp_id_pkts
Number of EAP-Response Identity packets transmitted.
rx_eap_req_id_pkts
Number of EAP-Request Identity packets received.
tx_eap_resp_notif_pkts
Number of EAP-Response Notification packets transmitted.
rx_eap_resp_notif_pkts
Number of EAP-Response Notification packets received.
tx_eap_resp_legacy_nak_pkts
Number of EAP-Response Legacy NAK packets transmitted.
tx_eap_resp_expanded_nak_pkts
Number of EAP-Response Expanded Types packets transmitted.
tx_eap_resp_expanded_types_pkts
Number of EAP-Response Expanded Types packets transmitted.
rx_eap_resp_expanded_types_pkts
Number of EAP-Response Expanded Types packets received.
tx_eap_resp_md5_chal_pkts
Number of EAP-Response MD5 Challenge packets transmitted.
rx_eap_resp_md5_chal_pkts
Number of EAP-Response MD5 Challenge packets received.
The following keys are returned when you specify -mode sessions:
Example: session.<handle>.statistics
authentication_state
State of authentication. These are the possible states:
unauthorized - Supplicant is not authorized.
authenticating - Supplicant is being authenticated.
reauthenticating - Supplicant is being reauthenticated.
authenticated - Supplicant was authenticated.
authentication failed - Supplicant was not authenticated.
logging off - Supplicant is logging off.
attempt_auth_count
Total number of sessions initiated, including any retries.
success_auth_count
Total number of sessions successfully established.
failed_auth_count
Total number of sessions failed, including retries.
aborted_auth_count
Total number of sessions aborted.
attempt_re_auth_count
Number of reauthentication attempts.
success_re_auth_count
Number of successful reauthentication attempts.
failed_re_auth_count
Number of unsuccessful reauthentication attempts.
logoff_attempts
Number of logoff attempts.
failed_logoff_attempts
Number of unsuccessful logoff attempts.
success_logoff_attempts
Number of successful logoff attempts.
avg_auth_success_duration
Average duration of a successful authentication attempt in milliseconds.
max_auth_success_duration
Maximum duration of a successful authentication attempt in milliseconds.
min_auth_success_duration
Minimum duration of a successful authentication attempt in milliseconds.
tx_start_pkts
Number of EAPOL-Start packets transmitted
tx_logoff_pkts
Number of EAPOL-Logoff packets transmitted
tx_key_pkts
Number of EAPOL-Key packets transmitted.
tx_eap_pkts
Number of EAP packets transmitted.
rx_eap_pkts
Number of EAP packets received.
rx_invalid_pkts
Number of invalid EAPOL packets received.
avg_start_pkt_latency
Average latency for EAPOL-Start packets in milliseconds
min_start_pkt_latency
Minimum latency for EAPOL-Start packets in milliseconds
max_start_pkt_latency
Maximum latency for EAPOL-Start packets in milliseconds
avg_logoff_pkt_latency
Average latency for EAPOL-Logoff packets in milliseconds.
min_logoff_pkt_latency
Minimum latency for EAPOL-Logoff packets in milliseconds.
max_logoff_pkt_latency
Maximum latency for EAPOL-Logoff packets in milliseconds.
avg_key_pkt_latency
Average latency for EAPOL-Key packets in milliseconds.
min_key_pkt_latency
Minimum latency for EAPOL-Key packets in milliseconds.
max_key_pkt_latency
Maximum latency for EAPOL-Key packets in milliseconds.
avg_eap_pkt_latency
Average latency for EAP packets in milliseconds.
min_eap_pkt_latency
Minimum latency for EAP packets in milliseconds.
max_eap_pkt_latency
Maximum latency for EAP packets in milliseconds.
tx_eap_req_pkts
Number of EAP-Request packets transmitted.
rx_eap_req_pkts
Number of EAP-Request packets received.
tx_eap_resp_pkts
Number of EAP-Response packets transmitted.
rx_eap_resp_pkts
Number of EAP-Response packets received.
rx_eap_success_pkts
Number of EAP-Success packets received.
rx_eap_failure_pkts
Number of EAP-Failure packets received.
tx_eap_resp_id_pkts
Number of EAP-Response Identity packets transmitted.
rx_eap_req_id_pkts
Number of EAP-Request Identity packets received.
tx_eap_resp_notif_pkts
Number of EAP-Response Notification packets transmitted.
rx_eap_resp_notif_pkts
Number of EAP-Response Notification packets received.
tx_eap_resp_legacy_nak_pkts
Number of EAP-Response Legacy NAK packets transmitted.
tx_eap_resp_expanded_nak_pkts
Number of EAP-Response Expanded NAK packets transmitted.
tx_eap_resp_expanded_types_pkts
Number of EAP-Response Expanded Types packets transmitted.
rx_eap_resp_expanded_types_pkts
Number of EAP-Response Expanded Types packets received.
tx_eap_resp_md5_chal_pkts
Number of EAP-Response MD5 Challenge packets transmitted.
rx_eap_resp_md5_chal_pkts
Number of EAP-Response MD5 Challenge packets received.
Note
Statistics list info will be returned per session basis.
Description¶
Thesth::emulation_dot1x_statsfunction retrieves a list of aggregate statistics for the 802.1x session configured on a specified port, or session statistics for a specified 802.1x device.
Examples¶
#### HLTAPI for Tcl ####
The following example retrieves aggregate results:
sth::emulation_dot1x_stats \
-mode aggregate \
-port_handle port1\
Output:
{aggregate {{port1 {{rx_eap_success_pkts 0} {aborted_auth_count 4}
{rx_eap_req_pkts 0}{rx_eap_failure_pkts 0} {rx_eap_resp_pkts 0}
{success_auth_count 0} {tx_start_pkts 54}{logoff_attempts 0}
{tx_eap_resp_expanded_types_pkts 0} {attempt_auth_count 6}
{tx_eap_resp_legacy_nak_pkts 0} {rx_eap_resp_md5_chal_pkts 0}
{success_logoff_attempts 0}{tx_eap_resp_md5_chal_pkts 0} {rx_invalid_pkts 0}
{tx_eap_pkts 0} {rx_eap_req_id_pkts 0}{tx_key_pkts 0}
{success_re_auth_count 0} {rx_eap_resp_notif_pkts 0} {tx_eap_req_pkts 0}
{failed_logoff_attempts 0} {rx_eap_resp_expanded_types_pkts 0}
{tx_eap_resp_id_pkts 0} {tx_logoff_pkts 0}{tx_eap_resp_expanded_nak_pkts 0}
{rx_eap_pkts 0} {tx_eap_resp_notif_pkts 0} {tx_eap_resp_pkts 0}
{failed_re_auth_count 0} {attempt_re_auth_count 0} {failed_auth_count0}}}}}
{status 1}
The following example retrieves session results:
sth::emulation_dot1x_stats \
-mode session \
-port_handle port1
Sample Output:
{session {{host3 {{authentication_state authenticated}
{max_start_pkt_latency 0} {rx_eap_success_pkts 0} {aborted_auth_count 4}
{avg_key_pkt_latency 0} {rx_eap_req_pkts 0} {rx_eap_failure_pkts 0}
{rx_eap_resp_pkts 0} {success_auth_count 0} {tx_start_pkts 54}
{min_logoff_pkt_latency 0} {logoff_attempts 0}
{tx_eap_resp_expanded_types_pkts 0} {attempt_auth_count 5}
{avg_eap_pkt_latency 0} {tx_eap_resp_legacy_nak_pkts 0}
{min_auth_success_duration 0} {avg_auth_success_duration 0}
{rx_eap_resp_md5_chal_pkts 0} {success_logoff_attempts 0}
{tx_eap_resp_md5_chal_pkts 0} {rx_invalid_pkts 0} {tx_eap_pkts 0}
{rx_eap_req_id_pkts 0} {min_start_pkt_latency 0} {avg_logoff_pkt_latency 0}
{avg_start_pkt_latency 0} {min_key_pkt_latency 0} {max_key_pkt_latency 0}
{tx_key_pkts 0} {success_re_auth_count 0} {rx_eap_resp_notif_pkts 0}
{tx_eap_req_pkts 0} {failed_logoff_attempts 0}
{rx_eap_resp_expanded_types_pkts 0} {min_eap_pkt_latency 0}
{tx_eap_resp_id_pkts 0} {max_eap_pkt_latency 0} {tx_logoff_pkts 0}
{max_auth_success_duration 0} {tx_eap_resp_expanded_nak_pkts 0}
{rx_eap_pkts 0} {tx_eap_resp_notif_pkts 0} {tx_eap_resp_pkts 0}
{failed_re_auth_count 0} {attempt_re_auth_count 0} {failed_auth_count 0}
{max_logoff_pkt_latency 0}}}} {status 1}
#### HLTAPI for Python ####
The following example retrieves aggregate results:
results_ret1 = sth.emulation_dot1x_stats (
handle = device,
mode = 'aggregate');
#### HLTAPI for Perl ####
The following example retrieves aggregate results:
my %results_ret2 = sth::emulation_dot1x_stats (
handle => "$device",
mode => 'aggregate');
End of Procedure Header