diff --git a/.gitignore b/.gitignore index 1076086..de0f89d 100644 --- a/.gitignore +++ b/.gitignore @@ -3,7 +3,6 @@ __pycache__ model-temp log makefile.local -docs/* logs/* *.pyc .vscode/ diff --git a/README.md b/README.md index b04cdb3..deb692e 100644 --- a/README.md +++ b/README.md @@ -490,6 +490,9 @@ Debugging can be difficult when using Ansible. To make it easier to troubleshoot Check the [playbook](playbooks) folder for more examples. +### More detailed documentation + +Please check [docs](docs) folder for more detailed documentation. # Implementation and Design diff --git a/docs/BGP.rst b/docs/BGP.rst new file mode 100644 index 0000000..75a21a9 --- /dev/null +++ b/docs/BGP.rst @@ -0,0 +1,619 @@ +Routing Protocol - BGP +====================== + +.. contents:: + :local: + :depth: 1 + +Overview +-------- + +`STC Ansible` module allows you to create various Border Gateway Protocol (BGP) test scenarios. +It helps to create scaling tests with hundreds of emulated BGP routers advertising thousands of +routes. + +To create and configure an emulated Border Gateway Protocol (BGP) test through `STC Ansible` module, +initially you should create `BGProuterconfig` object under an emulated device. +Once the BGP protocol is enabled on the emulated device, it will act as a BGP router. + +BGP routes should be created on top of an emulated BGP router using BGP route objects. + +You can configure all the characteristics of a BGP emulated router as well as the routes during +the creation of BGP devices and routes. Same can also be reconfigured/modify later. + +Once the BGP routers and routes set up is done, you can configure the Streamblock/traffic generator +between the routers or the routes by setting the source and destination BGP object references. + +Now, you can verify the traffic statistics (transmitted and received packets) between the +routers/routes by starting the devices (here emulated BGP routers). + +Please refer example playbook `BGP_Traffic `_. + + +Create BGP Device +----------------- + +Purpose +~~~~~~~ + +Creates BGP object(s) in the Spirent Test Center(stc) datamodel under the emulated device object(s). +During the object creation, Name and other BGP properties can be defined. +The name of the BGP object will be used as a reference in order to reconfigure/modify +any of it's properties later. + +.. role:: mandatory + + +Synopsis +~~~~~~~~ + +.. note:: :mandatory:`M` indicates that the parameter is :mandatory:`Mandatory`. + +.. parsed-literal:: + - + name: create bgp device + stc: + action: create :mandatory:`M` + under: :mandatory:`M` + count: + objects: + - :mandatory:`M` + + + . + . + +Parameters +~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstring +
Specifies the action for the given task. Here, it is create.
+
Required: Yes
+
underxpath +
An emulated device under which the BGP protocol is created.
+
Required: Yes
+
Example:
+
under: /EmulatedDevice[@Name=’Device1’]
+
See Also:
+ + +
NOTES:
+
1. EmulatedDevice must already exist.
+
2. If the device does not exist with the specified name, an exception will be raised and the playbook stops.
+
count integer +
Specifies the number of BGP devices to be created.
+
Count value above 1, creates several BGP objects in an iterative way.
+
Use the keyword ${item} as a template in device names. The item will be replace with the values from 1 to count.
+
Required: No. Optional field
+
objectsstring +
Specifies to identify stc objects and attributes.
+
To create BGP device, use BgpRouterConfig object.
+
Required: Yes.
+
See Also:
+
+ + + + + +Examples +~~~~~~~~ + +.. code-block:: yaml + + - + name: create bgp on Ipv4 Device + stc: + action: create + under: /EmulatedDevice[@Name='IPV4-Device1'] + count: 1 + objects: + - BgpRouterConfig: + IpVersion: IPV4 + AsNum: 1111 + DutAsNum: 2222 + Name: "IPV4-BGPRouter1" + + - + name: create bgp on Ipv6 Device + stc: + action: create + under: /EmulatedDevice[@Name='IPV6-Device1'] + count: 1 + objects: + - BgpRouterConfig: + IpVersion: IPV6 + AsNum: 1111 + DutAsNum: 2222 + Name: "IPV6-BGPRouter1" + + - + name: create 10 bgp devices + stc: + action: create + under: /EmulatedDevice[@Name='IPV6-Device${item}'] + count: 10 + objects: + - BgpRouterConfig: + IpVersion: IPV6 + AsNum: 1111 + DutAsNum: 2222 + Name: "IPV6-BGPRouter${item}" + DutIpv4Addr: 1.1.1.${item} + + +Configure BGP Device +-------------------- + +Purpose +~~~~~~~ + +Reconfigures/modifies an existing BGP objects properties. + +.. role:: mandatory + + +Synopsis +~~~~~~~~ + +.. parsed-literal:: + - + name: configure bgp device + count: + stc: + action: config :mandatory:`M` + object: :mandatory:`M` + properties: :mandatory:`M` + + + . + . + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstringSpecifies the action for the given task. Here it is config. +
Required: Yes
+
count integer +
Specifies the number of BGP devices to be configured.
+
Count value above 1, creates several BGP objects in an iterative way.
+
Use the keyword ${item} as a template in device names. The item will be replace + with the values from 1 to count.
+
Required: No. Optional field
+
objectxpath +
An emulated BGP device object under which the attributes are configured.
+
Required: Yes
+
Example:
+
object: ref:/EmulatedDevice[@Name='Dev1']/BgpRouterConfig[@Name='BGPDev1']
+
See Also:
+ +
NOTES:
+
1. BGP device must already exist.
+
2. If the device does not exist with the specified name, an exception will be raised and the playbook stops.
+
propertiesstring +
Specifies to identify the properties of BGP object.
+
Required: Yes
+
For BGP attributes, please refer
+ + +Examples +~~~~~~~~ + +.. code-block:: yaml + + - + name: configure/modify BGP device properties + stc: + action: configure + count: 1 + object: ref:/EmulatedDevice[@Name='Device1']/BgpRouterConfig[@Name='BGPDevice1'] + properties: + AsNum: 101 + DutAsNum: 102 + DutIpv4Addr: 1.1.1.1 + + - + name: configure/modify multiple BGP device properties + stc: + action: configure + count: 10 + object: ref:/EmulatedDevice[@Name='Device${item}']/BgpRouterConfig[@Name='BGPDevice${item}'] + properties: + AsNum: 101 + DutAsNum: 102 + DutIpv4Addr: 1.1.${item}.1 + + +Create BGP Routes +----------------- + +Purpose +~~~~~~~ + +Creates and configures BGP routes under a specific BGP device object. +It also defines the characteristics of the routes that will be advertised at the +beginning of the session. + +Synopsis +~~~~~~~~ + +.. parsed-literal:: + - + name: create bgp route + under: :mandatory:`M` + count: + stc: + action: create :mandatory:`M` + objects: :mandatory:`M` + - : + + + . + . + +Parameters +~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstringSpecifies the action for the given task. Here it is create. +
Required: yes
+
underxpath +
A BGP device under which the BGP route is created.
+
Required: Yes
+
Example:
+
under: ref:/EmulatedDevice[@Name='Dev1']/BgpRouterConfig[@Name='BGPDev1']
+
See also:
+ +
NOTES:
+
1. BGP Device must already exist
+
2. If the path is incorrect, an exception will be raised and the playbook stops. +
count integer +
Specifies the number of BGP routes to be created.
+
Count value above 1, creates several BGP Route objects in an iterative way.
+
Use the keyword ${item} as a template in device names. The item will be replace with the values from 1 to count.
+
Required: No. Optional field.
+
objectsstring +
Specifies to identify stc objects and attributes.
+
To create IPv4 and IPv6 BGP routes, use BgpIpv4RouteConfig and BgpIpv6RouteConfig objects. +
Required: Yes.
+
See Also: + + +
BGP object Reference Guide for other BGP routes creation like SRTE, LinkState, EVPN etc.
+
+ + + +Examples +~~~~~~~~ + +.. code-block:: yaml + + - + name: create ipv4 route on bgp device + stc: + action: create + under: /EmulatedDevice[@Name='Device1']/BgpRouterConfig[@Name='BGPRouter1'] + count: 1 + objects: + - BgpIpv4RouteConfig: + name: "BGPV4Route1" + AsPath: 2222 + Ipv4NetworkBlock: + NetworkCount: 100 + StartIpList: 2.2.2.2 + + - + name: create ipv6 route on bgp device + stc: + action: create + under: /EmulatedDevice[@Name='IPV6-Device1']/BgpRouterConfig[@Name='IPV6-BGPRouter1'] + count: 1 + objects: + - BgpIpv6RouteConfig: + name: "BGPV6Route1" + AsPath: 2222 + Ipv4NetworkBlock: + NetworkCount: 100 + StartIpList: 2000::1 + + - + name: create 10 ipv4 routes + stc: + action: create + under: /EmulatedDevice[@Name='Device${item}']/BgpRouterConfig[@Name='BGPRouter{item}'] + count: 10 + objects: + - BgpIpv4RouteConfig: + name: "BGPV4Route${item}" + AsPath: 2222 + Ipv4NetworkBlock: + NetworkCount: 100 + StartIpList: 2.${item}.2.2 + + +Configure BGP Routes +-------------------- + +Purpose +~~~~~~~ + +Reconfigures/modifies an existing BGP Route object and it's child objects properties. + +.. role:: mandatory + + +Synopsis +~~~~~~~~ + +.. parsed-literal:: + - + name: configure bgp route + count: + stc: + action: config :mandatory:`M` + object: :mandatory:`M` + properties: :mandatory:`M` + + + + + + + +Parameters +~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstringSpecifies the action for the given task. Here it is config. +
Required: Yes.
+
count integer +
Specifies the number of BGP routes to be configured.
+
Count value above 1, creates several BGP route objects in an iterative way.
+
Use the keyword ${item} as a template in device names. The item will be replace + with the values from 1 to count.
+
Required: No. Optional field.
+
objectxpath +
An emulated BGP route object under which the attributes are configured.
+
Required: Yes
+
Example:
+
ref:/EmulatedDevice[@Name='Dev1']/BgpRouterConfig[@Name='BGPDev1']/
+
BgpIpv4RouteConfig[@Name='Route1']
+
See Also:
+ +
NOTES:
+
1. BGP device must already exist.
+
2. If the device does not exist with the specified name, an exception will be raised and the playbook stops.
+
propertiesstring +
Specifies to identify the properties of BGP Route objects.
+
Required: Yes
+
See Also: + + +
BGP object Reference Guide for other BGP routes configuration like SRTE, LinkState, EVPN etc.
+
+ + +Examples +~~~~~~~~ + +.. code-block:: yaml + + - + name: config another ipv4route on device2 + stc: + action: config + count: 1 + objects: /EmulatedDevice[@Name='BGPDevice2']/BgpRouterConfig[@Name='BGPRouter2']/BgpIpv4RouteConfig[@Name='BGPV4Route'] + properties: + AsPath: 1111 + Ipv4NetworkBlock: + NetworkCount: 101 + StartIpList: 3.3.3.3 + + +Configure BGP Traffic +--------------------- + +Purpose +~~~~~~~ + +Configures the traffic between the BGP devices or routes. +About creating a bound streamblock, please refer `StreamBlock <../docs/StreamBlock.rst>`_ section and +`Start Protocols <../docs/Start_Protocols.rst>`_, `Results <../docs/Results.rst>`_ section to +start devices and get TX(transmitted)/RX(received) counter values. + +Examples +~~~~~~~~ + +.. code-block:: yaml + + # To configure traffic between BGP Devices + - + name: Configure the traffic generator1 + stc: + count: 1 + action: create + under: /project + objects: + - StreamBlock: + EnableStreamOnlyGeneration: true + SrcBinding-targets: ref:/EmulatedDevice[@Name='Device1']/Ipv4If + DstBinding-targets: ref:/EmulatedDevice[@Name='Device2']/Ipv4If + AffiliationStreamBlockLoadProfile: + Load: 10 + + + # To configure traffic between BGP IPV4 network blocks + - + name: Configure the traffic generator2 + stc: + count: 1 + action: create + under: /project + objects: + - StreamBlock: + EnableStreamOnlyGeneration: true + SrcBinding-targets: | + ref:/EmulatedDevice[@Name='Device1']/BgpRouterConfig[@Name='BGPRouter1'] + /BgpIpv4RouteConfig/Ipv4NetworkBlock + DstBinding-targets: | + ref:/EmulatedDevice[@Name='Device2']/BgpRouterConfig[@Name='BGPRouter2'] + /BgpIpv4RouteConfig/Ipv4NetworkBlock + AffiliationStreamBlockLoadProfile: + Load: 10 + + + # To configure traffic between BGP IPV6 network blocks + - + name: Configure the traffic generator3 + stc: + count: 1 + action: create + under: /project + objects: + - StreamBlock: + EnableStreamOnlyGeneration: true + SrcBinding-targets: | + ref:/EmulatedDevice[@Name='Device1']/BgpRouterConfig[@Name='BGPRouter1'] + /BgpIpv6RouteConfig/Ipv6NetworkBlock + DstBinding-targets: | + ref:/EmulatedDevice[@Name='Device2']/BgpRouterConfig[@Name='BGPRouter2'] + /BgpIpv6RouteConfig/Ipv6NetworkBlock + AffiliationStreamBlockLoadProfile: + Load: 10 + + +For more examples please check `Playbooks `_. \ No newline at end of file diff --git a/docs/DHCP.rst b/docs/DHCP.rst new file mode 100644 index 0000000..056b9ab --- /dev/null +++ b/docs/DHCP.rst @@ -0,0 +1,722 @@ +Access Protocol - DHCP +====================== + +.. contents:: + :local: + :depth: 1 + +Overview +-------- + +`STC-ansible` allows you to create complex tests to validate DHCP implementations. + +DHCP (Dynamic Host Configuration Protocol) uses a client-server model, in which DHCP servers provide network +addresses and configuration parameters to DHCP clients. + +To create and configure a DHCP server through `STC Ansible` module, initially you should create +`DHCPv4Serverconfig` object for Ipv4 and `DHCPv6Serverconfig` object for Ipv6 under an emulated device. + +Then, you need to configure DHCP at the port level using the object `Dhcpv4PortConfig` for IPv4 or +`Dhcpv6PortConfig` for Ipv6 under a client port. The parameters apply to all DHCP hosts (clients) +emulated by the applicable port. + +Use `Dhcpv4BlockConfig` for IPv4 or `Dhcpv6BlockConfig` for IPv6 to configure blocks of hosts for +DHCP emulation. The parameters also configure the DHCP messages sentbetween the emulated DHCP hosts (clients) +and the DHCP server (DUT) in order to obtain an IP address. + +You can configure all the characteristics of a DHCP Server and client/session block during +the creation. Same can also be reconfigured/modify later. + +Now, you can verify the DHCP server and session results by starting the devices. + +Please refer example playbooks dhcpv4-config.yaml and dhcpv6-config.yaml in +`Github `_ link. + + +Create DHCPv4/v6 Server +----------------------- + +Purpose +~~~~~~~ + +Creates DHCPv4 or DHCPv6 server object(s) in the Spirent Test Center(stc) datamodel under the emulated device object(s). +During the object creation, Name and other DHCP properties can be defined. +The name of the DHCP object will be used as a reference in order to reconfigure/modify +any of it's properties later. + +.. role:: mandatory + + +Synopsis +~~~~~~~~ + +.. note:: :mandatory:`M` indicates that the parameter is :mandatory:`Mandatory`. + +.. parsed-literal:: + - + name: create DHCPv4/v6 device + stc: + action: create :mandatory:`M` + under: :mandatory:`M` + count: + objects: + - :mandatory:`M` + + + . + . + +Parameters +~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstring +
Specifies the action for the given task. Here, it is create.
+
Required: Yes
+
underxpath +
An emulated device under which the DHCP Server is created.
+
Required: Yes
+
Example:
+
under: /EmulatedDevice[@Name=’Device1’]
+
See Also:
+ + +
NOTES:
+
1. EmulatedDevice must already exist.
+
2. If the device does not exist with the specified name, an exception will be raised and the playbook stops.
+
count integer +
Specifies the number of DHCP Servers to be created.
+
Count value above 1, creates several DHCP server objects in an iterative way.
+
Use the keyword ${item} as a template in device names. The item will be replace with the values from 1 to count.
+
Required: No. Optional field
+
objectsstring +
Specifies to identify stc objects and attributes.
+
To create DHCPv4 Server, use DHCPv4ServerConfig object.
+
To create DHCPv6 Server, use DHCPv6ServerConfig object.
+
Required: Yes.
+
See Also:
+
+ + + + + +Examples +~~~~~~~~ + +.. code-block:: yaml + + - + name: create DHCPv4 Server + stc: + action: create + under: /EmulatedDevice[@Name='Device1'] + count: 1 + objects: + - Dhcpv4ServerConfig: + HostName: server_@p-@b-@s + LeaseTime: 3600 + Ipv4Tos: 192 + name: "DHCPv4Server" + dhcpv4serverdefaultpoolconfig: + StartIpList: 192.85.1.4 + + - + name: create DHCPv6 Server + stc: + action: create + under: /EmulatedDevice[@Name='Device1'] + count: 1 + objects: + - Dhcpv6ServerConfig: + EmulationMode: DHCPV6 + name: "DHCPv6Server" + Dhcpv6ServerDefaultPrefixPoolConfig: + StartIpList: 2001::10 + + - + name: create 10 DHCPv4 Servers + stc: + action: create + under: /EmulatedDevice[@Name='Device${item}'] + count: 10 + objects: + - Dhcpv4ServerConfig: + HostName: server_${item} + LeaseTime: 3600 + Ipv4Tos: 192 + name: "DHCPv4Server${item}" + dhcpv4serverdefaultpoolconfig: + StartIpList: 192.85.1.${item} + + +Configure DHCPv4/v6 Server +-------------------------- + +Purpose +~~~~~~~ + +Reconfigures/modifies an existing DHCPv4 or DHCPv6 Server objects properties. + +.. role:: mandatory + + +Synopsis +~~~~~~~~ + +.. parsed-literal:: + - + name: configure DHCP Server + count: + stc: + action: config :mandatory:`M` + object: :mandatory:`M` + properties: :mandatory:`M` + + + . + . + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstringSpecifies the action for the given task. Here it is config. +
Required: Yes
+
count integer +
Specifies the number of DHCP Servers to be configured.
+
Count value above 1, creates several DHCP Server objects in an iterative way.
+
Use the keyword ${item} as a template in device names. The item will be replace + with the values from 1 to count.
+
Required: No. Optional field
+
objectxpath +
An emulated DHCPv4 or DHCPv6 Server object under which the attributes are configured.
+
Required: Yes
+
Example:
+
object: ref:/EmulatedDevice[@Name='Dev1']/DHCPv4ServerConfig[@Name='DHCPSer1']
+
OR
+
object: ref:/EmulatedDevice[@Name='Dev1']/DHCPv6ServerConfig[@Name='DHCPSer1']
+
See Also:
+ +
NOTES:
+
1. DHCPv4 or DHCPv6 Server must already exist.
+
2. If the device does not exist with the specified name, an exception will be raised and the playbook stops.
+
propertiesstring +
Specifies to identify the properties of DHCPv4 or DHCPv6 Server object.
+
Required: Yes
+
For DHCPv4 and DHCPv6 Server attributes, please refer
+ + +Examples +~~~~~~~~ + +.. code-block:: yaml + + - + name: configure/modify DHCPv4 server properties + stc: + action: configure + count: 1 + object: ref:/EmulatedDevice[@Name='Device1']/DHCPv4ServerConfig[@Name='DHCPSer1'] + properties: + HostName: server_1 + LeaseTime: 3200 + Ipv4Tos: 190 + dhcpv4serverdefaultpoolconfig: + StartIpList: 192.85.1.6 + + - + name: configure/modify DHCPv6 server properties + stc: + action: configure + count: 1 + object: ref:/EmulatedDevice[@Name='Device1']/DHCPv6ServerConfig[@Name='DHCPv6Ser1'] + properties: + EmulationMode: DHCPV6_PD + Dhcpv6ServerDefaultPrefixPoolConfig: + StartIpList: 2001::11 + + - + name: configure/modify multiple DHCPv4 Server properties + stc: + action: configure + count: 10 + object: ref:/EmulatedDevice[@Name='Device${item}']/DHCPv4ServerConfig[@Name='DHCPv4Ser${item}'] + properties: + HostName: server_${item} + LeaseTime: 3200 + Ipv4Tos: 190 + dhcpv4serverdefaultpoolconfig: + StartIpList: 192.85.1.${item} + + +Configure DHCPv4/v6 Port +------------------------ + +Purpose +~~~~~~~ + +Configures an existing DHCPv4 or DHCPv6 port object properties. +These characteristics applies only to the DHCPv4 or DHCPv6 client/session blocks created under +the same port. + +.. role:: mandatory + + +Synopsis +~~~~~~~~ + +.. parsed-literal:: + - + name: configure DHCP port + count: + stc: + action: config :mandatory:`M` + object: :mandatory:`M` + properties: :mandatory:`M` + + + . + . + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstringSpecifies the action for the given task. Here it is config. +
Required: Yes
+
count integer +
Specifies the number of DHCPv4 or DHCPv6 ports to be configured.
+
Count value above 1, creates several DHCP port objects in an iterative way.
+
Use the keyword ${item} as a template in device names. The item will be replace + with the values from 1 to count.
+
Required: No. Optional field
+
objectxpath +
A DHCPv4 or DHCPv6 port object under which the attributes need to be configured.
+
Required: Yes
+
Example:
+
object: ref:/Port[@Name='Port1']/Dhcpv4PortConfig
+
See Also:
+ +
NOTES:
+
1. A port must already exist.
+
2. If the port does not exist with the specified name, an exception will be raised and the playbook stops.
+
propertiesstring +
Specifies to identify the properties of DHCPv4 or DHCPv6 port object.
+
Required: Yes
+
For DHCPv4 and DHCPv6 Port attributes, please refer
+ + +Examples +~~~~~~~~ + +.. code-block:: yaml + + - + name: configure DHCPv4 port properties + stc: + action: configure + count: 1 + object: ref:/Port[@Name='Port1']/DHCPv4PortConfig + properties: + LeaseTime: 60 + ReleaseTimeout: 1 + + - + name: configure DHCPv6 port properties + stc: + action: configure + count: 1 + object: ref:/Port[@Name='Port1']/DHCPv6PortConfig + properties: + LeaseTime: 60 + ReleaseTimeout: 2 + + +Create DHCPv4/v6 Session Block +------------------------------ + +Purpose +~~~~~~~ + +Creates DHCPv4 or DHCPv6 sessions block object(s) in the Spirent Test Center(stc) datamodel under the emulated device object(s). +During the object creation, Name and other DHCP session properties can be defined. +The name of the DHCP object will be used as a reference in order to reconfigure/modify +any of it's properties later. + +.. role:: mandatory + + +Synopsis +~~~~~~~~ + +.. note:: :mandatory:`M` indicates that the parameter is :mandatory:`Mandatory`. + +.. parsed-literal:: + - + name: create DHCPv4/v6 session block + stc: + action: create :mandatory:`M` + under: :mandatory:`M` + count: + objects: + - :mandatory:`M` + + + . + . + +Parameters +~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstring +
Specifies the action for the given task. Here, it is create.
+
Required: Yes
+
underxpath +
An emulated device under which the DHCP Session block is created.
+
Required: Yes
+
Example:
+
under: /EmulatedDevice[@Name=’Device1’]
+
See Also:
+ + +
NOTES:
+
1. EmulatedDevice must already exist.
+
2. If the device does not exist with the specified name, an exception will be raised and the playbook stops.
+
count integer +
Specifies the number of DHCP Session blocks to be created.
+
Count value above 1, creates several DHCP session block objects in an iterative way.
+
Use the keyword ${item} as a template in device names. The item will be replace with the values from 1 to count.
+
Required: No. Optional field
+
objectsstring +
Specifies to identify stc objects and attributes.
+
To create DHCPv4 Session block, use DHCPv4BlockConfig object.
+
To create DHCPv6 Session block, use DHCPv6BlockConfig object.
+
Required: Yes.
+
See Also:
+
+ + + + + +Examples +~~~~~~~~ + +.. code-block:: yaml + + + - + name: create DHCPv4 session block on the device2 + stc: + action: create + under: ref:/EmulatedDevice[@Name='Device2'] + count: 1 + objects: + - Dhcpv4BlockConfig: + UsesIf-targets: ref:/EmulatedDevice[@Name='Device2']/Ipv4if + HostName: client_@p-@b-@s + name: "DHCPv4sessionblock" + + - + name: create DHCPv6 session block on the device2 + stc: + action: create + under: ref:/EmulatedDevice[@Name='Device2'] + count: 1 + objects: + - Dhcpv6BlockConfig: + UsesIf-targets: ref:/EmulatedDevice[@Name='Device2']/Ipv6if + Dhcpv6ClientMode: DHCPV6 + name: "DHCPv6sessionblock" + + - + name: create 10 DHCPv4 session blocks + stc: + action: create + under: ref:/EmulatedDevice[@Name='Device${item}'] + count: 10 + objects: + - Dhcpv4BlockConfig: + UsesIf-targets: ref:/EmulatedDevice[@Name='Device${item}']/Ipv4if + HostName: client_${item} + name: "DHCPv4sessionblock${item}" + + +Configure DHCPv4/v6 Session Blocks +---------------------------------- + +Purpose +~~~~~~~ + +Reconfigures/modifies an existing DHCPv4 or DHCPv6 Session block objects properties. + +.. role:: mandatory + + +Synopsis +~~~~~~~~ + +.. parsed-literal:: + - + name: configure DHCP Session block + count: + stc: + action: config :mandatory:`M` + object: :mandatory:`M` + properties: :mandatory:`M` + + + . + . + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstringSpecifies the action for the given task. Here it is config. +
Required: Yes
+
count integer +
Specifies the number of DHCP Session block to be configured.
+
Count value above 1, creates several DHCP Session block objects in an iterative way.
+
Use the keyword ${item} as a template in device names. The item will be replace + with the values from 1 to count.
+
Required: No. Optional field
+
objectxpath +
An emulated DHCPv4 or DHCPv6 Session block object under which the attributes are configured.
+
Required: Yes
+
Example:
+
object: ref:/EmulatedDevice[@Name='Dev1']/DHCPv4BlockConfig[@Name='DHCPblock1']
+
OR
+
object: ref:/EmulatedDevice[@Name='Dev1']/DHCPv6BlockConfig[@Name='DHCPblock1']
+
See Also:
+ +
NOTES:
+
1. DHCPv4 or DHCPv6 Session block object must already exist.
+
2. If the device does not exist with the specified name, an exception will be raised and the playbook stops.
+
propertiesstring +
Specifies to identify the properties of DHCPv4 or DHCPv6 Session block object.
+
Required: Yes
+
For DHCPv4 and DHCPv6 Session block attributes, please refer
+ + +Examples +~~~~~~~~ + +.. code-block:: yaml + + - + name: configure/modify DHCPv4 session block properties + stc: + action: configure + count: 1 + object: ref:/EmulatedDevice[@Name='Device1']/DHCPv4BlockConfig[@Name='DHCPblock1'] + properties: + HostName: client_@p-@b-@s + + - + name: configure/modify DHCPv6 session block properties + stc: + action: configure + count: 1 + object: ref:/EmulatedDevice[@Name='Device1']/DHCPv6BlockConfig[@Name='DHCPv6block1'] + properties: + Dhcpv6ClientMode: DHCPV6 + + - + name: configure/modify multiple DHCPv4 session block properties + stc: + action: configure + count: 10 + object: ref:/EmulatedDevice[@Name='Device${item}']/DHCPv4BlockConfig[@Name='DHCPv4block${item}'] + properties: + HostName: client_${item} + + +Please refer `Start Protocols <../docs/Start_Protocols.rst>`_ and `Results <../docs/Results.rst>`_ sections +to start DHCP devices and verify the session results. + diff --git a/docs/Delete_Objects.rst b/docs/Delete_Objects.rst new file mode 100644 index 0000000..a76466e --- /dev/null +++ b/docs/Delete_Objects.rst @@ -0,0 +1,109 @@ +Delete Objects +============== + +.. contents:: + :local: + :depth: 1 + +Purpose +------- + +Deletes a specific stc datamodel object(s). +This will also delete all child objects of the deleted objects. + +.. role:: mandatory + +Synopsis +-------- + +.. note:: :mandatory:`M` indicates that the parameter is :mandatory:`Mandatory`. + +.. parsed-literal:: + + - + name: delete object + stc: + action: delete :mandatory:`M` + objects: :mandatory:`M` + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstringSpecifies the action for the given task. + Here, it is delete. +
Required: Yes.
+
objectsxpath +
Specifies the object (port/device/result) path to delete.
+
Required: Yes.
+
Example: ref:/EmulatedDevice[@Name='Device1']
+
+ + + + + +Examples +-------- + +.. code-block:: yaml + + # To delete Port + - + name: Delete port1 + stc: + action: delete + objects: ref:/port[@name='Port1'] + + # To delete a BGP device + - + name: Delete BGP object + stc: + action: delete + objects: ref:/EmulatedDevice[@Name='Device1']/BgpRouterConfig[@Name='BGPDevice1'] + + # To delete an emulated device + - + name: Delete BGP object + stc: + action: delete + objects: ref:/EmulatedDevice[@Name='Device1'] \ No newline at end of file diff --git a/docs/EmulatedDevice.rst b/docs/EmulatedDevice.rst new file mode 100644 index 0000000..2592575 --- /dev/null +++ b/docs/EmulatedDevice.rst @@ -0,0 +1,1137 @@ +Emulated Device +=============== + +.. contents:: + :local: + :depth: 1 + +Overview +-------- + +Using `STC Ansible` module, you can create and configure multiple emulated devices distributed throughout +the ports in a test. + +To create an emulated device, use `EmulatedDevice` object under the project object affiliated with any available +ports. + +You can configure all the characteristics of an emulated device as well as the interface stack objects during +the creation of emulated device. Same can also be reconfigured/modify later. + +An emulated device can be designated as a router, host, client, server by confiugring specific protocols in it +or it can simply use as a traffic-only device. + +Once the emulated device creation and configuration is done, you can configure the Streamblock/traffic generator +between the devices by setting the source and destination with device object references. Please refer `StreamBlock <../docs/StreamBlock.rst>`_ section. + +Then, you can verify the traffic statistics (transmitted and received packets) between the +emulated devices by starting the traffic. + +Create Emulated Device +---------------------- + +Purpose +~~~~~~~ + +Creates emulated device object(s) in the Spirent Test Center(stc) datamodel under the project object +affiliated with any created port object(s). +During the object creation, requires to configure interface stacking and individual properties like ip address, +gateway, devicecount, name etc. +The name of the emulated device object will be used as a reference in order to reconfigure/modify +any of it's properties later. + +In `STC Ansible` module, an emulated device can be created in 2 ways. + 1. Using the `perform` method and `DeviceCreate` command. It is an esiest way which takes care of + creating the interface stack. + 2. Using the `create` method. It is an extensive way which requires configuration of all of the + indiviudal properties such as the IP address and Interface stacking. + +.. role:: mandatory + + +Synopsis +~~~~~~~~ + +.. note:: :mandatory:`M` indicates that the parameter is :mandatory:`Mandatory`. + +.. parsed-literal:: + + - + name: create emulated device using `perform` + stc: + action: perform :mandatory:`M` + command: DeviceCreate :mandatory:`M` + properties: + ParentList: ref:/project :mandatory:`M` + CreateCount: + DeviceCount: + Port: :mandatory:`M` + IfStack: :mandatory:`M` + IfCount: :mandatory:`M` + name: + +For the properties details of first method (creating emulateddevice using `perform`), please refer +`DeviceCreate Command Reference Document `_. + +.. parsed-literal:: + + - + name: create emulated device using `create` + stc: + action: create :mandatory:`M` + under: :mandatory:`M` + count: + objects: + - :mandatory:`M` + AffiliatedPort: :mandatory:`M` + PrimaryIf: :mandatory:`M` + TopLevelIf: :mandatory:`M` + + + . + . + +Parameters +~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstring +
Specifies the action for the given task. Here, it is create.
+
Required: Yes
+
underxpath +
A project under which an emulateddevice is created.
+
Required: Yes
+
Example:
+
under: /project
+
See Also:
+ + +
NOTES:
+
1. Port must already exist.
+
count integer +
Specifies the number of emulated devices to be created.
+
Count value above 1, creates several emulated device objects in an iterative way.
+
Use the keyword ${item} as a template in device names. The item will be replace with the values from 1 to count.
+
Required: No. Optional field
+
objectsstring +
Specifies to identify stc objects and attributes.
+
To create emulateddevice, use EmulatedDevice object.
+
Required: Yes.
+
See Also:
+
EmulatedDevice object reference guide
+
Following are some direct links to specific interface objects. Same are also available in 'EmulatedDevice object reference guide' link given above.
+
For EthIIIf properties EthIIIf object reference page +
+
For VlanIf properties VlanIf object reference page +
+
For Ipv4If properties Ipv4If object reference page +
+
For Ipv6If properties Ipv6If object reference page +
+
+ + + + + +Examples +~~~~~~~~ + + 1. Sample YAML code to create IPv4 emulated devices: + + .. code-block:: yaml + + - + name: create one IPv4 emulated device using 'perform' + stc: + action: perform + command: DeviceCreate + properties: + ParentList: ref:/project + CreateCount: 1 + DeviceCount: 1 + Port: ref:/port[@Name='port1'] + IfStack: Ipv4If EthIIIf + IfCount: 1 1 + name: "device1" + + - + name: create one IPv4 emulated device using 'create' + stc: + action: create + under: ref:/project + count: 1 + objects: + - emulateddevice: + AffiliatedPort: ref:/port[@name='Port1'] + DeviceCount: 1 + name: "Device1" + PrimaryIf: ref:./Ipv4If + TopLevelIf: ref:./Ipv4If + EthIIIf: + SourceMac: 00:10:94:00:00:01 + Ipv4If: + Address: "192.85.1.2" + Gateway: "192.85.1.1" + PrefixLength: 24 + stackedon: ref:./EthIIIf + + 2. Sample YAML code to create IPv4 emulated devices with single VLAN: + + .. code-block:: yaml + + + - + name: create one IPv4 emulated device with single vlan + stc: + action: create + under: ref:/project + count: 1 + objects: + - emulateddevice: + AffiliatedPort: ref:/port[@name='Port1'] + DeviceCount: 1 + name: "Device1" + PrimaryIf: ref:./Ipv4If + TopLevelIf: ref:./Ipv4If + EthIIIf: + SourceMac: 00:10:94:00:00:01 + VlanIf: + VlanId: "101" + StackedOnEndpoint-targets: ref:./EthIIIf + Ipv4If: + Address: "192.85.1.2" + Gateway: "192.85.1.1" + PrefixLength: 24 + StackedOnEndpoint-targets: ref:./VlanIf + TopLevelIfSource: ref:/EmulatedDevice[@Name="Device1"] + PrimaryIfSource: ref:/EmulatedDevice[@Name="Device1"] + + - + name: create one IPv4 emulated device with vlan using 'perform' + stc: + action: perform + command: DeviceCreate + properties: + ParentList: ref:/project + CreateCount: 1 + DeviceCount: 1 + Port: ref:/port[@Name='port1'] + IfStack: Ipv4If VlanIf EthIIIf + IfCount: 1 1 1 + name: "device1" + + 3. Sample YAML code to create IPv4 emulated devices with double VLAN: + + .. code-block:: yaml + + - + name: create one IPv4 emulated device with dual vlan using 'perform' + stc: + action: perform + command: DeviceCreate + properties: + ParentList: ref:/project + CreateCount: 1 + DeviceCount: 1 + Port: ref:/port[@Name='Port1'] + IfStack: Ipv4If VlanIf VlanIf EthIIIf + IfCount: '1 1 1 1' + name: "ipv4_dual_vlan_2" + + + - + name: create one IPv4 emulated device with dual vlan using 'create' + stc: + action: create + under: ref:/project + count: 1 + objects: + - emulateddevice: + AffiliatedPort: ref:/port[@name='Port1'] + DeviceCount: 1 + name: "ipv4_dual_vlan_1" + PrimaryIf: ref:./Ipv4If + TopLevelIf: ref:./Ipv4If + EthIIIf: + SourceMac: 00:10:96:00:00:01 + VlanIf: + VlanId: 100 + Ipv4If: + AddrStep: 0.0.0.1 + Address: 192.168.1.2 + Gateway: 192.168.1.1 + TopLevelIfSource: ref:/EmulatedDevice[@Name='ipv4_dual_vlan_1'] + PrimaryIfSource: ref:/EmulatedDevice[@Name='ipv4_dual_vlan_1'] + + - + name: create VlanIf under ipv4_dual_vlan + stc: + action: create + under: ref:/EmulatedDevice[@Name='ipv4_dual_vlan_1'] + count: 1 + objects: + - VlanIf: + VlanId: 100 + + - + name: config Ipv4If for ipv4_dual_vlan + stc: + action: config + objects: ref:/EmulatedDevice[@Name='ipv4_dual_vlan_1']/Ipv4If + properties: + StackedOnEndpoint-targets: ref:/EmulatedDevice[@Name='ipv4_dual_vlan_1']/VlanIf[1] + + - + name: config VlanIf 2 - ipv4_dual_vlan + stc: + action: config + objects: ref:/EmulatedDevice[@Name='ipv4_dual_vlan_1']/VlanIf[1] + properties: + StackedOnEndpoint-targets: ref:/EmulatedDevice[@Name='ipv4_dual_vlan_1']/VlanIf[0] + + - + name: config VlanIf 1 - ipv4_dual_vlan + stc: + action: config + objects: ref:/EmulatedDevice[@Name='ipv4_dual_vlan_1']/VlanIf[0] + properties: + StackedOnEndpoint-targets: ref:/EmulatedDevice[@Name='ipv4_dual_vlan_1']/EthIIIf + + + 4. Sample YAML code to create multiple IPv4 emulated devices: + + .. code-block:: yaml + + + - + name: create 50 IPv4 emulated devices + stc: + action: create + under: ref:/project + count: 50 + objects: + - emulateddevice: + AffiliatedPort: ref:/port[@name='Port1'] + DeviceCount: 1 + name: "Device$item" + PrimaryIf: ref:./Ipv4If + TopLevelIf: ref:./Ipv4If + EthIIIf: + SourceMac: 00:10:94:00:00:$item + VlanIf: + VlanId: "10$item" + StackedOnEndpoint-targets: ref:./EthIIIf + Ipv4If: + Address: "192.85.1.${item+3}" + Gateway: "192.85.1.1" + PrefixLength: 24 + StackedOnEndpoint-targets: ref:./VlanIf + TopLevelIfSource: ref:/EmulatedDevice[@Name="Device$item"] + PrimaryIfSource: ref:/EmulatedDevice[@Name="Device$item"] + + 5. Sample YAML code to create IPv6 emulated device: + + .. code-block:: yaml + + - + name: create one IPv6 emulated device using 'create' method + stc: + action: create + under: ref:/project + count: 1 + objects: + - emulateddevice: + AffiliatedPort: ref:/port[@name='Port1'] + DeviceCount: 1 + name: "ipv6_device_1" + PrimaryIf: ref:./Ipv6If + TopLevelIf: ref:./Ipv6If + EthIIIf: + SourceMac: 00:10:94:00:00:01 + Ipv6If: + Address: "2000::2" + Gateway: "2000::1" + PrefixLength: 64 + + - + name: Create linklocal ipv6if under ipv6_device_1 + stc: + action: create + under: ref:/EmulatedDevice[@Name='ipv6_device_1'] + count: 1 + objects: + - Ipv6If: + AddrStep: ::1 + Address: fe80::1 + PrimaryIfSource: ref:/EmulatedDevice[@Name='ipv6_device_1'] + TopLevelIfSource: ref:/EmulatedDevice[@Name='ipv6_device_1'] + + - + name: config EthIIIf stack relation + stc: + action: config + objects: ref:/EmulatedDevice[@Name='ipv6_device_1']/EthIIIf + properties: + stackedonendpoint-Sources: ref:/EmulatedDevice[@Name='ipv6_device_1']/Ipv6If + + ###################################################################################### + - + name: create one IPv6 emulated device using 'perform' + stc: + action: perform + command: DeviceCreate + properties: + ParentList: ref:/project + CreateCount: 1 + DeviceCount: 1 + Port: ref:/port[@Name='Port2'] + IfStack: Ipv6If EthIIIf + IfCount: '1 1' + name: "ipv6_device_2" + + - + name: Config ipv6if address + stc: + action: config + objects: ref:/EmulatedDevice[@Name='ipv6_device_2']/Ipv6If + properties: + Address: 2002::3 + Gateway: 2002::1 + + - + name: Create ipv6if + stc: + action: create + under: ref:/EmulatedDevice[@Name="ipv6_device_2"] + count: 1 + objects: + - Ipv6If: + AddrStep: ::1 + Address: fe80::1 + PrimaryIfSource: ref:/EmulatedDevice[@Name="ipv6_device_2"] + TopLevelIfSource: ref:/EmulatedDevice[@Name="ipv6_device_2"] + StackedOnEndpoint-targets: ref:/EmulatedDevice[@Name="ipv6_device_2"]/EthIIIf + + 6. Sample YAML code to create IPv6 emulated device with single VLAN: + + .. code-block:: yaml + + - + name: Create one IPv6 emulated device with single vlan using 'create' method + stc: + action: create + under: ref:/project + count: 1 + objects: + - emulateddevice: + AffiliatedPort: ref:/port[@name='Port1'] + DeviceCount: 1 + name: "ipv6_single_vlan_1" + PrimaryIf: ref:./Ipv6If + TopLevelIf: ref:./Ipv6If + EthIIIf: + SourceMac: 00:10:96:00:00:01 + VlanIf: + VlanId: 100 + StackedOnEndpoint-targets: ref:./EthIIIf + Ipv6If: + AddrStep: ::1 + Address: 2001::2 + Gateway: 2001::1 + StackedOnEndpoint-targets: ref:./VlanIf + TopLevelIfSource: ref:/EmulatedDevice[@Name='ipv6_single_vlan_1'] + PrimaryIfSource: ref:/EmulatedDevice[@Name='ipv6_single_vlan_1'] + + - + name: Create ipv6if under device 1 + stc: + action: create + under: ref:/EmulatedDevice[@Name='ipv6_single_vlan_1'] + count: 1 + objects: + - Ipv6If: + AddrStep: ::1 + Address: fe80::2 + PrimaryIfSource: ref:/EmulatedDevice[@Name='ipv6_single_vlan_1'] + TopLevelIfSource: ref:/EmulatedDevice[@Name='ipv6_single_vlan_1'] + StackedOnEndpoint-targets: ref:/EmulatedDevice[@Name='ipv6_single_vlan_1']/VlanIf + + ########################################################################################### + - + name: Create one IPv6 emulated device with single vlan using 'perform' method + stc: + action: perform + command: DeviceCreate + properties: + ParentList: ref:/project + CreateCount: 1 + DeviceCount: 1 + Port: ref:/port[@Name='Port2'] + IfStack: Ipv6If VlanIf EthIIIf + IfCount: '1 1 1' + name: "ipv6_single_vlan_2" + + - + name: Create ipv6if + stc: + action: create + under: ref:/EmulatedDevice[@Name="ipv6_single_vlan_2"] + count: 1 + objects: + - Ipv6If: + AddrStep: ::1 + Address: fe80::1 + PrimaryIfSource: ref:/EmulatedDevice[@Name="ipv6_single_vlan_2"] + TopLevelIfSource: ref:/EmulatedDevice[@Name="ipv6_single_vlan_2"] + StackedOnEndpoint-targets: ref:/EmulatedDevice[@Name="ipv6_single_vlan_2"]/VlanIf + + 7. Sample YAML code to create IPv6 emulated device with double VLAN: + + .. code-block:: yaml + + - + name: Create one IPv6 emulated device with double vlan using 'create' method + stc: + action: create + under: ref:/project + count: 1 + objects: + - emulateddevice: + AffiliatedPort: ref:/port[@name='Port1'] + DeviceCount: 1 + name: "ipv6_dual_vlan_1" + PrimaryIf: ref:./Ipv6If + TopLevelIf: ref:./Ipv6If + EthIIIf: + SourceMac: be:ef:00:00:00:00 + VlanIf: + VlanId: 100 + Ipv6If: + AddrStep: ::1 + Address: 2001::2 + Gateway: 2001::1 + + - + name: Create linklocal ipv6if + stc: + action: create + under: ref:/EmulatedDevice[@Name="ipv6_dual_vlan_1"] + count: 1 + objects: + - Ipv6If: + AddrStep: ::1 + Address: fe80::1 + PrimaryIfSource: ref:/EmulatedDevice[@Name="ipv6_dual_vlan_1"] + TopLevelIfSource: ref:/EmulatedDevice[@Name="ipv6_dual_vlan_1"] + + - + name: create second VlanIf under emulated device + stc: + action: create + under: ref:/EmulatedDevice[@Name="ipv6_dual_vlan_1"] + count: 1 + objects: + - VlanIf: + VlanId: 100 + StackedOnEndpoint-targets: ref:/EmulatedDevice[@Name="ipv6_dual_vlan_1"]/VlanIf[0] + + - + name: config ipv6if stack relation + stc: + action: config + count: 1 + objects: ref:/EmulatedDevice[@Name="ipv6_dual_vlan_1"]/Ipv6If[0] + properties: + StackedOnEndpoint-targets: ref:/EmulatedDevice[@Name="ipv6_dual_vlan_1"]/VlanIf[1] + + - + name: config VlanIf stack relation + stc: + action: config + count: 1 + objects: ref:/EmulatedDevice[@Name="ipv6_dual_vlan_1"]/VlanIf[0] + properties: + StackedOnEndpoint-targets: ref:/EmulatedDevice[@Name="ipv6_dual_vlan_1"]/EthIIIf + + - + name: config linklocal Ipv6If stack relation + stc: + action: config + count: 1 + objects: ref:/EmulatedDevice[@Name="ipv6_dual_vlan_1"]/Ipv6If[1] + properties: + StackedOnEndpoint-targets: ref:/EmulatedDevice[@Name="ipv6_dual_vlan_1"]/VlanIf[1] + + ######################################################################################### + - + name: Create one IPv6 emulated device with double vlan using 'perform' method + stc: + action: perform + command: DeviceCreate + properties: + ParentList: ref:/project + CreateCount: 1 + DeviceCount: 1 + Port: ref:/port[@Name='Port2'] + IfStack: Ipv6If VlanIf VlanIf EthIIIf + IfCount: '1 1 1 1' + name: "ipv6_dual_vlan_2" + + - + name: Create ipv6if + stc: + action: create + under: ref:/EmulatedDevice[@Name="ipv6_dual_vlan_2"] + count: 1 + objects: + - Ipv6If: + AddrStep: ::1 + Address: fe80::3 + PrimaryIfSource: ref:/EmulatedDevice[@Name="ipv6_dual_vlan_2"] + TopLevelIfSource: ref:/EmulatedDevice[@Name="ipv6_dual_vlan_2"] + StackedOnEndpoint-targets: ref:/EmulatedDevice[@Name="ipv6_dual_vlan_2"]/VlanIf[0] + + 8. Sample YAML code to create dualstack(IPv4IPv6) emulated device: + + .. code-block:: yaml + + - + name: Create dualstack device using 'create' method + stc: + action: create + under: ref:/project + count: 1 + objects: + - emulateddevice: + AffiliatedPort: ref:/port[@name='Port1'] + DeviceCount: 1 + name: "ipv4_ipv6_device_1" + PrimaryIf: ref:./Ipv4If + TopLevelIf: ref:./Ipv4If + EthIIIf: + SourceMac: 00:10:96:00:00:01 + Ipv4If: + AddrStep: 0.0.0.1 + Address: 192.168.1.2 + Gateway: 192.168.1.1 + StackedOnEndpoint-targets: ref:./EthIIIf + TopLevelIfSource: ref:/EmulatedDevice[@Name='ipv4_ipv6_device_1'] + PrimaryIfSource: ref:/EmulatedDevice[@Name='ipv4_ipv6_device_1'] + Ipv6If: + AddrStep: ::1 + Address: 2001::2 + Gateway: 2001::1 + StackedOnEndpoint-targets: ref:./EthIIIf + TopLevelIfSource: ref:/EmulatedDevice[@Name='ipv4_ipv6_device_1'] + PrimaryIfSource: ref:/EmulatedDevice[@Name='ipv4_ipv6_device_1'] + + - + name: Create ipv6if for device 1 + stc: + action: create + under: ref:/EmulatedDevice[@Name='ipv4_ipv6_device_1'] + count: 1 + objects: + - Ipv6If: + AddrStep: ::1 + Address: fe80::1 + PrimaryIfSource: ref:/EmulatedDevice[@Name='ipv4_ipv6_device_1'] + TopLevelIfSource: ref:/EmulatedDevice[@Name='ipv4_ipv6_device_1'] + StackedOnEndpoint-targets: ref:/EmulatedDevice[@Name='ipv4_ipv6_device_1']/EthIIIf + ########################################################################################## + - + name: create dualstack device using 'perform' + stc: + action: perform + command: DeviceCreate + properties: + ParentList: ref:/project + CreateCount: 1 + DeviceCount: 1 + Port: ref:/port[@Name='Port2'] + IfStack: Ipv6If Ipv4If EthIIIf + IfCount: '1 1 1' + name: "ipv4_ipv6_device_2" + + - + name: Config ipv4if address + stc: + action: config + objects: ref:/EmulatedDevice[@Name='ipv4_ipv6_device_2']/Ipv4If + properties: + Address: 192.168.1.1 + Gateway: 192.168.1.2 + TopLevelIfSource: ref:/EmulatedDevice[@Name="ipv4_ipv6_device_2"] + + - + name: Config ipv6if address + stc: + action: config + objects: ref:/EmulatedDevice[@Name='ipv4_ipv6_device_2']/Ipv6If + properties: + Address: 2001::1 + Gateway: 2001::2 + StackedOnEndpoint-targets: ref:/EmulatedDevice[@Name="ipv4_ipv6_device_2"]/EthIIIf + + - + name: Create ipv6if + stc: + action: create + under: ref:/EmulatedDevice[@Name="ipv4_ipv6_device_2"] + count: 1 + objects: + - Ipv6If: + AddrStep: ::1 + Address: fe80::1 + PrimaryIfSource: ref:/EmulatedDevice[@Name="ipv4_ipv6_device_2"] + TopLevelIfSource: ref:/EmulatedDevice[@Name="ipv4_ipv6_device_2"] + StackedOnEndpoint-targets: ref:/EmulatedDevice[@Name="ipv4_ipv6_device_2"]/EthIIIf + + 9. Sample YAML code to create dualstack(IPv4IPv6) emulated device with single VLAN: + + .. code-block:: yaml + + - + name: Create dualstack device with single vlan using 'create' method + stc: + action: create + under: ref:/project + count: 1 + objects: + - emulateddevice: + AffiliatedPort: ref:/port[@name='Port1'] + DeviceCount: 1 + name: "ipv4_ipv6_single_vlan_1" + PrimaryIf: ref:./Ipv6If + TopLevelIf: ref:./Ipv6If + EthIIIf: + SourceMac: 00:10:96:00:00:01 + VlanIf: + VlanId: 100 + Ipv4If: + AddrStep: 0.0.0.1 + Address: 192.168.1.2 + Gateway: 192.168.1.1 + Ipv6If: + AddrStep: ::1 + Address: 2002::2 + Gateway: 2002::1 + + - + name: Config ipv6if Stack relation + stc: + action: config + objects: ref:/EmulatedDevice[@Name='ipv4_ipv6_single_vlan_1']/Ipv6If + properties: + TopLevelIfSource: ref:/EmulatedDevice[@Name="ipv4_ipv6_single_vlan_1"] + StackedOnEndpoint-targets: ref:/EmulatedDevice[@Name="ipv4_ipv6_single_vlan_1"]/VlanIf + + - + name: Create linklocal ipv6if + stc: + action: create + under: ref:/EmulatedDevice[@Name='ipv4_ipv6_single_vlan_1'] + count: 1 + objects: + - Ipv6If: + AddrStep: ::1 + Address: fe80::1 + PrimaryIfSource: ref:/EmulatedDevice[@Name='ipv4_ipv6_single_vlan_1'] + TopLevelIfSource: ref:/EmulatedDevice[@Name='ipv4_ipv6_single_vlan_1'] + StackedOnEndpoint-targets: ref:/EmulatedDevice[@Name='ipv4_ipv6_single_vlan_1']/VlanIf + + - + name: config VlanIf stack relation + stc: + action: config + objects: ref:/EmulatedDevice[@Name='ipv4_ipv6_single_vlan_1']/VlanIf + properties: + StackedOnEndpoint-targets: ref:/EmulatedDevice[@Name='ipv4_ipv6_single_vlan_1']/EthIIIf + + - + name: config ipv4if stack relation + stc: + action: config + objects: ref:/EmulatedDevice[@Name='ipv4_ipv6_single_vlan_1']/Ipv4If + properties: + StackedOnEndpoint-targets: ref:/EmulatedDevice[@Name='ipv4_ipv6_single_vlan_1']/VlanIf + TopLevelIfSource: ref:/EmulatedDevice[@Name="ipv4_ipv6_single_vlan_1"] + ############################################################################################### + - + name: create dualstack device with single vlan using 'perform' + stc: + action: perform + command: DeviceCreate + properties: + ParentList: ref:/project + CreateCount: 1 + DeviceCount: 1 + Port: ref:/port[@Name='Port2'] + IfStack: Ipv6If Ipv4If VlanIf EthIIIf + IfCount: '1 1 1 1' + name: "ipv4_ipv6_single_vlan_2" + + - + name: config ipv6if + stc: + action: config + objects: ref:/EmulatedDevice[@Name='ipv4_ipv6_single_vlan_2']/Ipv6If + properties: + StackedOnEndpoint-targets: ref:/EmulatedDevice[@Name="ipv4_ipv6_single_vlan_2"]/VlanIf + + - + name: config ipv4if + stc: + action: config + objects: ref:/EmulatedDevice[@Name='ipv4_ipv6_single_vlan_2']/Ipv4If + properties: + Address: 192.168.1.1 + Gateway: 192.168.1.2 + TopLevelIfSource: ref:/EmulatedDevice[@Name="ipv4_ipv6_single_vlan_2"] + StackedOnEndpoint-targets: ref:/EmulatedDevice[@Name="ipv4_ipv6_single_vlan_2"]/VlanIf + + - + name: Create ipv6if + stc: + action: create + under: ref:/EmulatedDevice[@Name="ipv4_ipv6_single_vlan_2"] + count: 1 + objects: + - Ipv6If: + AddrStep: ::1 + Address: fe80::4 + PrimaryIfSource: ref:/EmulatedDevice[@Name="ipv4_ipv6_single_vlan_2"] + TopLevelIfSource: ref:/EmulatedDevice[@Name="ipv4_ipv6_single_vlan_2"] + StackedOnEndpoint-targets: ref:/EmulatedDevice[@Name="ipv4_ipv6_single_vlan_2"]/VlanIf + + 10. Sample YAML code to create dualstack(IPv4IPv6) emulated device with double VLAN: + + .. code-block:: yaml + + - + name: Create dualstack device with double vlan using 'create' method + stc: + action: create + under: ref:/project + count: 1 + objects: + - emulateddevice: + AffiliatedPort: ref:/port[@name='Port1'] + DeviceCount: 1 + name: "ipv4_ipv6_dual_vlan_1" + PrimaryIf: ref:./Ipv6If + TopLevelIf: ref:./Ipv6If + EthIIIf: + SourceMac: 00:10:96:00:00:01 + VlanIf: + VlanId: 100 + Ipv4If: + AddrStep: 0.0.0.1 + Address: 192.168.1.1 + Gateway: 192.168.1.2 + Ipv6If: + AddrStep: ::1 + Address: 2002::2 + Gateway: 2002::1 + + - + name: create VlanIf under device 1 + stc: + action: create + under: ref:/EmulatedDevice[@Name='ipv4_ipv6_dual_vlan_1'] + count: 1 + objects: + - VlanIf: + VlanId: 100 + + - + name: Create linklocal ipv6if on emulated device + stc: + action: create + under: ref:/EmulatedDevice[@Name='ipv4_ipv6_dual_vlan_1'] + count: 1 + objects: + - Ipv6If: + AddrStep: ::1 + Address: fe80::1 + PrimaryIfSource: ref:/EmulatedDevice[@Name='ipv4_ipv6_dual_vlan_1'] + TopLevelIfSource: ref:/EmulatedDevice[@Name='ipv4_ipv6_dual_vlan_1'] + + - + name: config outer VlanIf Stack relation + stc: + action: config + objects: ref:/EmulatedDevice[@Name='ipv4_ipv6_dual_vlan_1']/VlanIf[1] + properties: + StackedOnEndpoint-targets: ref:/EmulatedDevice[@Name='ipv4_ipv6_dual_vlan_1']/VlanIf[0] + + - + name: config Ipv4If Stack relation + stc: + action: config + objects: ref:/EmulatedDevice[@Name='ipv4_ipv6_dual_vlan_1']/Ipv4If + properties: + StackedOnEndpoint-targets: ref:/EmulatedDevice[@Name='ipv4_ipv6_dual_vlan_1']/VlanIf[1] + PrimaryIfSource: ref:/EmulatedDevice[@Name='ipv4_ipv6_dual_vlan_1'] + TopLevelIfSource: ref:/EmulatedDevice[@Name='ipv4_ipv6_dual_vlan_1'] + + - + name: config Ipv6If Stack relation + stc: + action: config + objects: ref:/EmulatedDevice[@Name='ipv4_ipv6_dual_vlan_1']/Ipv6If[0] + properties: + StackedOnEndpoint-targets: ref:/EmulatedDevice[@Name='ipv4_ipv6_dual_vlan_1']/VlanIf[1] + + - + name: config linklocal Ipv6If Stack relation + stc: + action: config + objects: ref:/EmulatedDevice[@Name='ipv4_ipv6_dual_vlan_1']/Ipv6If[1] + properties: + StackedOnEndpoint-targets: ref:/EmulatedDevice[@Name='ipv4_ipv6_dual_vlan_1']/VlanIf[1] + + - + name: config inner VlanIf Stack relation + stc: + action: config + objects: ref:/EmulatedDevice[@Name='ipv4_ipv6_dual_vlan_1']/VlanIf[0] + properties: + StackedOnEndpoint-targets: ref:/EmulatedDevice[@Name='ipv4_ipv6_dual_vlan_1']/EthIIIf + ############################################################################################# + - + name: create dualstack device with double vlan using 'perform' + stc: + action: perform + command: DeviceCreate + properties: + ParentList: ref:/project + CreateCount: 1 + DeviceCount: 1 + Port: ref:/port[@Name='Port2'] + IfStack: Ipv6If Ipv4If VlanIf VlanIf EthIIIf + IfCount: '1 1 1 1 1' + name: "ipv4_ipv6_dual_vlan_2" + + - + name: config ipv4if + stc: + action: config + objects: ref:/EmulatedDevice[@Name='ipv4_ipv6_dual_vlan_2']/Ipv4If + properties: + TopLevelIfSource: ref:/EmulatedDevice[@Name="ipv4_ipv6_dual_vlan_2"] + + - + name: config ipv6if + stc: + action: config + objects: ref:/EmulatedDevice[@Name='ipv4_ipv6_dual_vlan_2']/Ipv6If + properties: + StackedOnEndpoint-targets: ref:/EmulatedDevice[@Name="ipv4_ipv6_dual_vlan_2"]/VlanIf[0] + + - + name: Create ipv6if + stc: + action: create + under: ref:/EmulatedDevice[@Name="ipv4_ipv6_dual_vlan_2"] + count: 1 + objects: + - Ipv6If: + AddrStep: ::1 + Address: fe80::5 + PrimaryIfSource: ref:/EmulatedDevice[@Name="ipv4_ipv6_dual_vlan_2"] + TopLevelIfSource: ref:/EmulatedDevice[@Name="ipv4_ipv6_dual_vlan_2"] + StackedOnEndpoint-targets: ref:/EmulatedDevice[@Name="ipv4_ipv6_dual_vlan_2"]/VlanIf[0] + +Configure Emulated Device +------------------------- + +Purpose +~~~~~~~ + +Reconfigures/modifies an existing Emulation device and it's sub object properties. + +.. role:: mandatory + + +Synopsis +~~~~~~~~ + +.. parsed-literal:: + - + name: configure emulated device + count: + stc: + action: config :mandatory:`M` + objects: :mandatory:`M` + properties: + + + . + . + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstringSpecifies the action for the given task. Here it is config. +
Required: Yes
+
count integer +
Specifies the number of emulated devices to be configured.
+
Count value above 1, creates several emulated device objects in an iterative way.
+
Use the keyword ${item} as a template in device names. The item will be replace + with the values from 1 to count.
+
Required: No. Optional field
+
objectsxpath +
An emulated device object under which the attributes are configured.
+
Required: Yes
+
Example:
+
object: ref:/EmulatedDevice[@Name='Dev1']
+
See Also:
+ +
NOTES:
+
1. Emulated device must already exist.
+
2. If the device does not exist with the specified name, an exception will be raised and the playbook stops.
+
propertiesstring +
Specifies to identify the properties of emulated device object.
+
Required: Yes
+
Example:
+
properties:
+
DeviceCount: 1
+
RouterId: 1.0.0.0
+
See Also:
+
+ + +Examples +~~~~~~~~ + + .. code-block:: yaml + + - + name: config device properties + stc: + action: config + objects: ref:/EmulatedDevice[@Name='Dev1'] + properties: + DeviceCount: 1 + EnablePingResponse: True + RouterId: 1.0.0.0 + + + - + name: config device Ipv4 properties + stc: + action: config + objects: ref:/EmulatedDevice[@Name='Dev1']/Ipv4If + properties: + Address: 10.1.1.2 + AddressStep: 0.1.0.0 + Gateway: 10.0.0.1 + GatewayStep: 0.0.0.1 + PrefixLength: 24 + + - + name: config device Ipv6 properties + stc: + action: config + objects: ref:/EmulatedDevice[@Name='Dev1']/Ipv6If + properties: + Address: 1000::2 + AddressStep: ::1 + Gateway: 1000::1 + GatewayStep: ::0 + PrefixLength: 64 + + - + name: config device single VlanIf properties + stc: + action: config + objects: ref:/EmulatedDevice[@Name='Dev1']/VlanIf[0] + properties: + VlanId: 100 + IdStep: 1 + Priority: 1 + +For more examples please check `Playbooks `_. \ No newline at end of file diff --git a/docs/Getting_Started.rst b/docs/Getting_Started.rst new file mode 100644 index 0000000..32d80bf --- /dev/null +++ b/docs/Getting_Started.rst @@ -0,0 +1,217 @@ +Getting Started +=============== + + +.. contents:: + :local: + :depth: 1 + +Introduction +------------ + +STC Ansible is an experimental plugin designed to configure Spirent TestCenter data models +and execute tests. + + +Preparation +----------- + +- This STC Ansible module requires a recent version (>=2.5) of the Ansible client. +- This STC Ansible module can be used to remote configure an STC Lab Server. +- Configuration of STC-web is currently not supported. +- This module is supported and tested in Linux (Ubuntu 18.04 64bit) environment. + +Installation +------------ + +First, you need to install Python dependencies for the Ansible client: + +.. parsed-literal:: + `pip install ansible` + `pip install requests` + `pip install pytest` + +Configuration +------------- + +Inventory +~~~~~~~~~ + +In your inventory (inventory.ini), declare the STC Lab Servers you want the Ansible playbook to connect to: + +.. parsed-literal:: + + [labservers] + my-labserver-1 ansible_host=10.61.67.200 + + [labservers:vars] + ansible_connection=paramiko + ansible_host_key_checking=no + ansible_user=admin + ansible_ssh_pass=spirent + ansible_ssh_common_args=/bin/ssh + ansible_paramiko_pty=no + +.. note:: `ansible_paramiko_pty` must be set to no as it will otherwise fail to connect to the STC Lab Server. + +Ansible STC Module +~~~~~~~~~~~~~~~~~~ + +If you want to use the STC module outside of this direction, you will need to copy the content +of the `module_utils` and `library` into the folder from which you are running your Ansible playbook. + +Running an Ansible Playbook +--------------------------- + +There are several example playbooks in the `playbooks `_ folder. To run all of them, +just use make play, and it will create an STC session for each of the playbooks. +(You can also use make debug to run ansible with extra verbose output). + +Debugging +~~~~~~~~~ + +Debugging can be difficult when using Ansible. +To make it easier to troubleshoot your playbook, you can use the STC ansible emulator. For example: + +.. parsed-literal:: + + ./emulator.py -labserver lab-serverIP-address you-playbook.yaml + +STC Ansible Actions +------------------- + +The stc Ansible module makes it possible to execute one of the following actions: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
actionDescription
create_session or session +
Attach to an existing session. If the session does not exsit, a new session is created.
+
If the session exists, the data model is first reset to the default data model.
+
attach_session +
Attach to an existing session. If the session does not exisit, the script will fail.
+
delete_session +
Deletes a specific session or few sessions specified.
+
delete_all_sessions +
Deletes all the existing sessions.
+
load +
Loads a predefined XML data model. Note that the model must first be copied to the target
+
STC Lab Server using the copy module. Check the datamodel-loader.yaml playbook for reference.
+
create +
Creates a new object in the data model.
+
config +
Configures an existing object in the data model.
+
perform +
Perform a command against the data model.
+
delete +
Deletes an object in the data model.
+
get +
Returns the value of a given attribute of one or more objects -
+
this can be used for instance to check results.
+
wait +
Waits for one of several object attribute to become a specific value
+
(eg wait for the attritube BlockState of the PPPoE object PppoeClientBlockConfig to become CONNECTING )
+
download +
Download files such as bll.log, bll.session.log, etc...
+
+ + + + +STC configuration structure +--------------------------- + +The STC Ansible module does not connect directly to the STC Lab Server via the STC REST API. +Instead, it first ssh into the STC Lab Server, and then uses the REST API to connect to the BLL. + +.. image:: /docs/_static/images/design.png + + +Related Documentation +~~~~~~~~~~~~~~~~~~~~~ + +Additional documentation related to this guide: + +- `Instructions on how to set up LabServer` - https://support.spirent.com/SpirentCSC/SC_KnowledgeView?cid=null&id=DOC10792 + +- `Spirent TestCenter Automation Object Reference` - http://kms.spirentcom.com/CSC/pabtech/stc-automation-html/index-all.htm + +- `Ansible user guide` - https://docs.ansible.com/ansible/latest/user_guide/index.html + +- `YAML syntax` - https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html + + diff --git a/docs/IGMP.rst b/docs/IGMP.rst new file mode 100644 index 0000000..215e28f --- /dev/null +++ b/docs/IGMP.rst @@ -0,0 +1,632 @@ +Multicast Protocol - IGMP +========================= + +.. contents:: + :local: + :depth: 1 + +Overview +-------- + +`STC Ansible` module allows you to create/configure blocks of hosts for Internet Group Management Protocol (IGMP) emulation. +The parameters also configure the messages sent between the emulated hosts (clients) and +the router (DUT) in order to send membership reports. +IGMP versions 1, 2 and 3 are supported. + +To create and configure an emulated IGMP Protocol test through `STC Ansible` module, +initially you should create `IGMPhostconfig` object under an emulated device. Once the +IGMP protocol is enabled on the emulated device, it will act as a IGMP host. + +An IGMP host should be assosiated to a membership with a multicast group block. To create IGMP group +membership, use `IgmpGroupMembership` object. + +You can configure all the characteristics of a IGMP emulated host as well as the group memberships in create mode. +Same can also be reconfigured/modify later. + +Once the IGMP hosts and group memberships set up is done, you can configure the Streamblock/traffic generator +between the hosts or the multicast groups by setting the source and destination IGMP object references. + +Now, you can verify the traffic statistics (transmitted and received packets) between the +hosts/multicast groups by starting the devices (here emulated IGMP hosts). + +Please refer example playbooks igmp-config.yaml in +`Github `_ playbook folder. + + +Create IGMP Host +---------------- + +Purpose +~~~~~~~ + +Creates IGMP object(s) in the Spirent Test Center(stc) datamodel under the emulated device object(s). +During the object creation, Name and other IGMP properties can be defined. +The name of the IGMP object will be used as a reference in order to reconfigure/modify +any of it's properties later. + +.. role:: mandatory + + +Synopsis +~~~~~~~~ + +.. note:: :mandatory:`M` indicates that the parameter is :mandatory:`Mandatory`. + +.. parsed-literal:: + - + name: create IGMP host block + stc: + action: create :mandatory:`M` + under: :mandatory:`M` + count: + objects: + - :mandatory:`M` + + + . + . + +Parameters +~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstring +
Specifies the action for the given task. Here, it is create.
+
Required: Yes
+
underxpath +
An emulated device under which the IGMP host is created.
+
Required: Yes
+
Example:
+
under: /EmulatedDevice[@Name=’Device1’]
+
See Also:
+ + +
NOTES:
+
1. EmulatedDevice must already exist.
+
2. If the device does not exist with the specified name, an exception will be raised and the playbook stops.
+
count integer +
Specifies the number of IGMP hosts to be created.
+
Count value above 1, creates several IGMP objects/hosts in an iterative way.
+
Use the keyword ${item} as a template in device names. The item will be replace with the values from 1 to count.
+
Required: No. Optional field
+
objectsstring +
Specifies to identify stc objects and attributes.
+
To create IGMP version 1, 2 or 3 host blocks, use IgmphostConfig object.
+
Required: Yes.
+
See Also:
+
+ + + + + +Examples +~~~~~~~~ + +.. code-block:: yaml + + - + name: create IGMP v1 on Ipv4 Device + stc: + action: create + under: /EmulatedDevice[@Name='IPV4-Device1'] + count: 1 + objects: + - IGMPhostConfig: + Active: True + Version: IGMP_V1 + RouterAlert: TRUE + Name: "IGMPv1Host" + + - + name: create IGMP v2 on Ipv4 Device + stc: + action: create + under: /EmulatedDevice[@Name='IPV4-Device2'] + count: 1 + objects: + - IGMPhostConfig: + Active: True + Version: IGMP_V2 + RouterAlert: TRUE + Name: "IGMPv2Host" + + - + name: create IGMP v3 on Ipv4 Device + stc: + action: create + under: /EmulatedDevice[@Name='IPV4-Device3'] + count: 1 + objects: + - IGMPhostConfig: + Active: True + Version: IGMP_V3 + RouterAlert: TRUE + Name: "IGMPv3Host" + + - + name: create 10 IGMP host blocks + stc: + action: create + under: /EmulatedDevice[@Name='Device${item}'] + count: 10 + objects: + - IGMPhostConfig: + Active: True + Version: IGMP_V3 + RouterAlert: TRUE + Name: "IGMPv3Host${item}" + + +Configure IGMP Host +------------------- + +Purpose +~~~~~~~ + +Reconfigures/modifies an existing IGMP hosts properties. + +.. role:: mandatory + + +Synopsis +~~~~~~~~ + +.. parsed-literal:: + - + name: configure IGMP device + count: + stc: + action: config :mandatory:`M` + object: :mandatory:`M` + properties: :mandatory:`M` + + + . + . + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstringSpecifies the action for the given task. Here it is config. +
Required: Yes
+
count integer +
Specifies the number of IGMP hosts to be configured.
+
Count value above 1, creates several IGMP objects in an iterative way.
+
Use the keyword ${item} as a template in device names. The item will be replace + with the values from 1 to count.
+
Required: No. Optional field
+
objectxpath +
An emulated IGMP device object under which the attributes are configured.
+
Required: Yes
+
Example:
+
object: ref:/EmulatedDevice[@Name='Dev1']/IGMPHostConfig[@Name='IGMPDev1']
+
See Also:
+ +
NOTES:
+
1. IGMP host must already exist.
+
2. If the device does not exist with the specified name, an exception will be raised and the playbook stops.
+
propertiesstring +
Specifies to identify the properties of IGMP objects.
+
Required: Yes
+
For IGMP attributes, please refer
+ + +Examples +~~~~~~~~ + +.. code-block:: yaml + + - + name: configure/modify IGMP v1/v2/v3 host properties + stc: + action: config + count: 1 + object: ref:/EmulatedDevice[@Name='Device1']/IGMPhostConfig[@Name='IGMPDevice1'] + properties: + Ipv4Tos: 10 + RouterAlert: FALSE + + - + name: configure/modify multiple IGMP host properties + stc: + action: config + count: 10 + object: ref:/EmulatedDevice[@Name='Device${item}']/IGMPhostConfig[@Name='IGMPDevice${item}'] + properties: + Ipv4Tos: 10 + RouterAlert: FALSE + + +Create IGMP Group Membership +---------------------------- + +Purpose +~~~~~~~ + +Creates blocks of IGMP group memberships under a specific IGMP host object. +It also defines the characteristics of the group membership and the source pools. + +Synopsis +~~~~~~~~ + +.. parsed-literal:: + - + name: create IGMP group membership + under: :mandatory:`M` + count: + stc: + action: create :mandatory:`M` + objects: :mandatory:`M` + - : + + + . + . + +Parameters +~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstringSpecifies the action for the given task. Here it is create. +
Required: yes
+
underxpath +
An IGMP host under which the IGMP group membership is created.
+
Required: Yes
+
Example:
+
under: /EmulatedDevice[@Name='Dev1']/IGMPhostConfig[@Name='IGMPDev1']
+
See also:
+ +
NOTES:
+
1. IGMP v1/v2/v3 host must already exist
+
2. If the path is incorrect, an exception will be raised and the playbook stops. +
count integer +
Specifies the number of IGMP group memberships to be created.
+
Count value above 1, creates several IGMP group membership objects in an iterative way.
+
Use the keyword ${item} as a template in device names. The item will be replace with the values from 1 to count.
+
Required: No. Optional field.
+
objectsstring +
Specifies to identify stc objects and attributes.
+
To create group memberships under IGMP v1/v2/v3 hosts, use IgmpGroupMembership object. +
Required: Yes.
+
See Also: + +
NOTES:
+
1. An IPv4 Multicast group must already exist. Multicast Group section
+
+ + +Examples +~~~~~~~~ + + 1. Sample YAML code to create IGMP group membership on IGMP v2 host: + + .. code-block:: yaml + + - + name: create IGMP group membership + stc: + action: create + under: /EmulatedDevice[@Name='Device1']/IGMPhostConfig[@Name='IGMPv2host'] + count: 1 + objects: + - IgmpGroupMembership: + name: "IGMPgroup1" + DeviceGroupMapping: MANY_TO_MANY + FilterMode: INCLUDE + MulticastGroup: ref:/Ipv4Group[@Name='MulticastGroup1'] + + + + 2. Sample YAML code to create IGMP group membership on IGMP v3 host: + + .. code-block:: yaml + + - + name: create IGMP group membership + stc: + action: create + under: /EmulatedDevice[@Name='Device1']/IGMPhostConfig[@Name='IGMPv3host'] + count: 1 + objects: + - IgmpGroupMembership: + name: "IGMPgroup1" + DeviceGroupMapping: MANY_TO_MANY + FilterMode: INCLUDE + IsSourceList: FALSE + UserDefinedSources: FALSE + MulticastGroup: ref:/Ipv4Group[@Name='MulticastGroup1'] + -Ipv4NetworkBlock: + StartIpList: 192.0.1.0 + NetworkCount: 10 + + + 3. Sample YAML code to create multiple IGMP group memberships on IGMP v2 host: + + .. code-block:: yaml + + - + name: create 10 IGMP group memberships + stc: + action: create + under: /EmulatedDevice[@Name='Device${item}']/IGMPhostConfig[@Name='IGMPhost${item}'] + count: 10 + objects: + - IgmpGroupMembership: + name: "IGMPgroup${item}" + DeviceGroupMapping: MANY_TO_MANY + FilterMode: INCLUDE + IsSourceList: FALSE + UserDefinedSources: FALSE + MulticastGroup: ref:/Ipv4Group[@Name='MulticastGroup${item}'] + -Ipv4NetworkBlock: + StartIpList: 192.0.${item}.0 + NetworkCount: 10 + + +Configure IGMP group membership +------------------------------- + +Purpose +~~~~~~~ + +Reconfigures/modifies an existing IGMP group membership and it's child objects properties. + +.. role:: mandatory + + +Synopsis +~~~~~~~~ + +.. parsed-literal:: + - + name: configure IGMP group membership + count: + stc: + action: config :mandatory:`M` + object: :mandatory:`M` + properties: :mandatory:`M` + + + + + + + +Parameters +~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstringSpecifies the action for the given task. Here it is config. +
Required: Yes.
+
count integer +
Specifies the number of IGMP group memberships to be configured.
+
Count value above 1, creates several IGMP group membership objects in an iterative way.
+
Use the keyword ${item} as a template in group membership names. The item will be replace + with the values from 1 to count.
+
Required: No. Optional field.
+
objectxpath +
An IGMP group membership object under which the attributes are configured.
+
Required: Yes
+
Example:
+
ref:/EmulatedDevice[@Name='Dev1']/IGMPhostConfig[@Name='IGMPhost1']/
+
IgmpGroupMembership[@Name='group1']
+
See Also:
+ +
NOTES:
+
1. IGMP devices and group memberships must already exist.
+
2. If the device does not exist with the specified name, an exception will be raised and the playbook stops.
+
propertiesstring +
Specifies to identify the properties of IGMP group membership objects.
+
Required: Yes
+
See Also: + +
NOTES:
+
1. An IPv4 Multicast group must already exist. Multicast Group section
+
+ + +Examples +~~~~~~~~ + +.. code-block:: yaml + + - + name: config IGMP group membership under IGMP v3 device + stc: + action: config + count: 1 + objects: /EmulatedDevice[@Name='IGMPDevice1']/IGMPhostConfig[@Name='IGMPhost1']/IgmpGroupMembership[@Name='group1'] + properties: + DeviceGroupMapping: ONE_TO_ONE + FilterMode: EXCLUDE + IsSourceList: FALSE + UserDefinedSources: FALSE + MulticastGroup: ref:/Ipv4Group[@Name='MulticastGroup1'] + Ipv4NetworkBlock: + StartIpList: 193.0.1.0 + NetworkCount: 10 + +Configure IGMP Traffic +---------------------- + +Purpose +~~~~~~~ + +Configures the traffic between the IGMP hosts or groups. +About creating a bound streamblock, please refer `StreamBlock <../docs/StreamBlock.rst>`_ section and +`Start Protocols <../docs/Start_Protocols.rst>`_, `Results <../docs/Results.rst>`_ sections to +start devices and get TX(transmitted)/RX(received) counter values. + +Examples +~~~~~~~~ + +.. code-block:: yaml + + # To configure traffic between IGMP Devices + - + name: Configure multicast stream + stc: + count: 1 + action: create + under: /project + objects: + - StreamBlock: + EnableStreamOnlyGeneration: true + SrcBinding-targets: ref:/EmulatedDevice[@Name='Device1']/Ipv4If + DstBinding-targets: ref:/EmulatedDevice[@Name='Device2']/Ipv4If + AffiliationStreamBlockLoadProfile: + Load: 10 + + + # To configure traffic between IGMP groups + - + name: Configure the traffic generator2 + stc: + count: 1 + action: create + under: /project + objects: + - StreamBlock: + EnableStreamOnlyGeneration: true + SrcBinding-targets: | + ref:/EmulatedDevice[@Name='Device1']/IGMPhostConfig[@Name='IGMPhost1'] + /IgmpGroupMembership[@Name='group1']/Ipv4NetworkBlock + DstBinding-targets: | + ref:/EmulatedDevice[@Name='Device2']/IGMPhostConfig[@Name='IGMPhost2'] + /IgmpGroupMembership[@Name='group2']/Ipv4NetworkBlock + AffiliationStreamBlockLoadProfile: + Load: 10 + +For more examples please check `Playbooks `_. \ No newline at end of file diff --git a/docs/MLD.rst b/docs/MLD.rst new file mode 100644 index 0000000..d8e67db --- /dev/null +++ b/docs/MLD.rst @@ -0,0 +1,618 @@ +Multicast Protocol - MLD +========================= + +.. contents:: + :local: + :depth: 1 + +Overview +-------- + +`STC Ansible` module allows you to create/configure blocks of hosts for Multicast Listener Discovery (MLD) emulation +using different services across multiple ports. +MLD versions 1 and 2 are supported. + +To create and configure an emulated MLD Protocol test through `STC Ansible` module, +initially you should create `MLDhostconfig` object under an emulated device. Once the +MLD protocol is enabled on the emulated device, it will act as a MLD host. + +An MLD host should be assosiated to a membership with a multicast group block. To create MLD group +membership, use `mldGroupMembership` object. + +You can configure all the characteristics of a MLD emulated host as well as the group memberships in create mode. +Same can also be reconfigured/modify later. + +Once the MLD hosts and group memberships set up is done, you can configure the Streamblock/traffic generator +between the hosts or the multicast groups by setting the source and destination MLD object references. + +Now, you can verify the traffic statistics (transmitted and received packets) between the +hosts/multicast groups by starting the devices (here emulated MLD hosts). + +Please refer example playbooks mld-config.yaml in +`Github `_ playbook folder. + + +Create MLD Host +---------------- + +Purpose +~~~~~~~ + +Creates MLD object(s) in the Spirent Test Center(stc) datamodel under the emulated device object(s). +During the object creation, Name and other MLD properties can be defined. +The name of the MLD object will be used as a reference in order to reconfigure/modify +any of it's properties later. + +.. role:: mandatory + + +Synopsis +~~~~~~~~ + +.. note:: :mandatory:`M` indicates that the parameter is :mandatory:`Mandatory`. + +.. parsed-literal:: + - + name: create MLD host block + stc: + action: create :mandatory:`M` + under: :mandatory:`M` + count: + objects: + - :mandatory:`M` + + + . + . + +Parameters +~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstring +
Specifies the action for the given task. Here, it is create.
+
Required: Yes
+
underxpath +
An emulated device under which the MLD host is created.
+
Required: Yes
+
Example:
+
under: /EmulatedDevice[@Name=’Device1’]
+
See Also:
+ + +
NOTES:
+
1. EmulatedDevice must already exist.
+
2. If the device does not exist with the specified name, an exception will be raised and the playbook stops.
+
count integer +
Specifies the number of MLD hosts to be created.
+
Count value above 1, creates several MLD objects/hosts in an iterative way.
+
Use the keyword ${item} as a template in device names. The item will be replace with the values from 1 to count.
+
Required: No. Optional field
+
objectsstring +
Specifies to identify stc objects and attributes.
+
To create MLD version 1, 2 or 3 host blocks, use MLDhostConfig object.
+
Required: Yes.
+
See Also:
+
+ + + + + +Examples +~~~~~~~~ + +.. code-block:: yaml + + - + name: create MLD v1 on Ipv6 Device + stc: + action: create + under: /EmulatedDevice[@Name='IPV6-Device1'] + count: 1 + objects: + - MLDhostConfig: + Active: True + Version: MLD_V1 + RouterAlert: TRUE + Name: "MLDv1Host" + + - + name: create MLD v2 on Ipv6 Device + stc: + action: create + under: /EmulatedDevice[@Name='IPV6-Device2'] + count: 1 + objects: + - MLDhostConfig: + Active: True + Version: MLD_V2 + RouterAlert: TRUE + Name: "MLDv2Host" + + - + name: create 10 MLD host blocks + stc: + action: create + under: /EmulatedDevice[@Name='Device${item}'] + count: 10 + objects: + - MLDhostConfig: + Active: True + Version: MLD_V2 + RouterAlert: TRUE + Name: "MLDv2Host${item}" + + +Configure MLD Host +------------------- + +Purpose +~~~~~~~ + +Reconfigures/modifies an existing MLD hosts properties. + +.. role:: mandatory + + +Synopsis +~~~~~~~~ + +.. parsed-literal:: + - + name: configure MLD device + count: + stc: + action: config :mandatory:`M` + object: :mandatory:`M` + properties: :mandatory:`M` + + + . + . + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstringSpecifies the action for the given task. Here it is config. +
Required: Yes
+
count integer +
Specifies the number of MLD hosts to be configured.
+
Count value above 1, creates several MLD objects in an iterative way.
+
Use the keyword ${item} as a template in device names. The item will be replace + with the values from 1 to count.
+
Required: No. Optional field
+
objectxpath +
An emulated MLD device object under which the attributes are configured.
+
Required: Yes
+
Example:
+
object: ref:/EmulatedDevice[@Name='Dev1']/MLDHostConfig[@Name='MLDDev1']
+
See Also:
+ +
NOTES:
+
1. MLD host must already exist.
+
2. If the device does not exist with the specified name, an exception will be raised and the playbook stops.
+
propertiesstring +
Specifies to identify the properties of MLD objects.
+
Required: Yes
+
For MLD attributes, please refer
+ + +Examples +~~~~~~~~ + +.. code-block:: yaml + + - + name: configure/modify MLD v1/v2 host properties + stc: + action: config + count: 1 + object: ref:/EmulatedDevice[@Name='Device1']/MLDhostConfig[@Name='MLDDevice1'] + properties: + Ipv6Tos: 10 + RouterAlert: FALSE + + - + name: configure/modify multiple MLD host properties + stc: + action: config + count: 10 + object: ref:/EmulatedDevice[@Name='Device${item}']/MLDhostConfig[@Name='MLDDevice${item}'] + properties: + Ipv6Tos: 10 + RouterAlert: FALSE + + +Create MLD Group Membership +---------------------------- + +Purpose +~~~~~~~ + +Creates blocks of MLD group memberships under a specific MLD host object. +It also defines the characteristics of the group membership and the source pools. + +Synopsis +~~~~~~~~ + +.. parsed-literal:: + - + name: create MLD group membership + under: :mandatory:`M` + count: + stc: + action: create :mandatory:`M` + objects: :mandatory:`M` + - : + + + . + . + +Parameters +~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstringSpecifies the action for the given task. Here it is create. +
Required: yes
+
underxpath +
An MLD host under which the MLD group membership is created.
+
Required: Yes
+
Example:
+
under: /EmulatedDevice[@Name='Dev1']/MLDhostConfig[@Name='MLDDev1']
+
See also:
+ +
NOTES:
+
1. MLD v1/v2 host must already exist
+
2. If the path is incorrect, an exception will be raised and the playbook stops. +
count integer +
Specifies the number of MLD group memberships to be created.
+
Count value above 1, creates several MLD group membership objects in an iterative way.
+
Use the keyword ${item} as a template in device names. The item will be replace with the values from 1 to count.
+
Required: No. Optional field.
+
objectsstring +
Specifies to identify stc objects and attributes.
+
To create group memberships under MLD v1/v2 hosts, use MLDGroupMembership object. +
Required: Yes.
+
See Also: + +
NOTES:
+
1. An IPv6 Multicast group must already exist. Multicast Group section
+
+ + +Examples +~~~~~~~~ + + 1. Sample YAML code to create MLD group membership on MLD v1 host: + + .. code-block:: yaml + + - + name: create MLD group membership + stc: + action: create + under: /EmulatedDevice[@Name='Device1']/MLDhostConfig[@Name='MLDv1host'] + count: 1 + objects: + - MLDGroupMembership: + name: "MLDgroup1" + DeviceGroupMapping: MANY_TO_MANY + FilterMode: EXCLUDE + MulticastGroup: ref:/Ipv6Group[@Name='MulticastGroup1'] + + + + 2. Sample YAML code to create MLD group membership on MLD v2 host: + + .. code-block:: yaml + + - + name: create MLD group membership + stc: + action: create + under: /EmulatedDevice[@Name='Device1']/MLDhostConfig[@Name='MLDv2host'] + count: 1 + objects: + - MLDGroupMembership: + name: "MLDgroup1" + DeviceGroupMapping: MANY_TO_MANY + FilterMode: EXCLUDE + IsSourceList: FALSE + UserDefinedSources: FALSE + MulticastGroup: ref:/Ipv6Group[@Name='MulticastGroup1'] + -Ipv6NetworkBlock: + StartIpList: 2000::1 + NetworkCount: 10 + + + 3. Sample YAML code to create multiple MLD group memberships on MLD v2 host: + + .. code-block:: yaml + + - + name: create 10 MLD group memberships + stc: + action: create + under: /EmulatedDevice[@Name='Device${item}']/MLDhostConfig[@Name='MLDhost${item}'] + count: 10 + objects: + - MLDGroupMembership: + name: "MLDgroup${item}" + DeviceGroupMapping: MANY_TO_MANY + FilterMode: EXCLUDE + IsSourceList: FALSE + UserDefinedSources: FALSE + MulticastGroup: ref:/Ipv6Group[@Name='MulticastGroup${item}'] + -Ipv6NetworkBlock: + StartIpList: 2000::${item} + NetworkCount: 10 + + +Configure MLD group membership +------------------------------- + +Purpose +~~~~~~~ + +Reconfigures/modifies an existing MLD group membership and it's child objects properties. + +.. role:: mandatory + + +Synopsis +~~~~~~~~ + +.. parsed-literal:: + - + name: configure MLD group membership + count: + stc: + action: config :mandatory:`M` + object: :mandatory:`M` + properties: :mandatory:`M` + + + + + + + +Parameters +~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstringSpecifies the action for the given task. Here it is config. +
Required: Yes.
+
count integer +
Specifies the number of MLD group memberships to be configured.
+
Count value above 1, creates several MLD group membership objects in an iterative way.
+
Use the keyword ${item} as a template in group membership names. The item will be replace + with the values from 1 to count.
+
Required: No. Optional field.
+
objectxpath +
An MLD group membership object under which the attributes are configured.
+
Required: Yes
+
Example:
+
ref:/EmulatedDevice[@Name='Dev1']/MLDhostConfig[@Name='MLDhost1']/
+
MLDGroupMembership[@Name='group1']
+
See Also:
+ +
NOTES:
+
1. MLD devices and group memberships must already exist.
+
2. If the device does not exist with the specified name, an exception will be raised and the playbook stops.
+
propertiesstring +
Specifies to identify the properties of MLD group membership objects.
+
Required: Yes
+
See Also: + +
NOTES:
+
1. An IPv6 Multicast group must already exist. Multicast Group section
+
+ + +Examples +~~~~~~~~ + +.. code-block:: yaml + + - + name: config MLD group membership under MLD v2 device + stc: + action: config + count: 1 + objects: /EmulatedDevice[@Name='MLDDevice1']/MLDhostConfig[@Name='MLDhost1']/MLDGroupMembership[@Name='group1'] + properties: + DeviceGroupMapping: ONE_TO_ONE + FilterMode: EXCLUDE + IsSourceList: FALSE + UserDefinedSources: FALSE + MulticastGroup: ref:/Ipv6Group[@Name='MulticastGroup1'] + Ipv6NetworkBlock: + StartIpList: 2000::1 + NetworkCount: 10 + +Configure MLD Traffic +---------------------- + +Purpose +~~~~~~~ + +Configures the traffic between the MLD hosts or groups. +About creating a bound streamblock, please refer `StreamBlock <../docs/StreamBlock.rst>`_ section and +`Start Protocols <../docs/Start_Protocols.rst>`_, `Results <../docs/Results.rst>`_ sections to +start devices and get TX(transmitted)/RX(received) counter values. + +Examples +~~~~~~~~ + +.. code-block:: yaml + + # To configure traffic between MLD Devices + - + name: Configure multicast stream + stc: + count: 1 + action: create + under: /project + objects: + - StreamBlock: + EnableStreamOnlyGeneration: true + SrcBinding-targets: ref:/EmulatedDevice[@Name='Device1']/Ipv6If + DstBinding-targets: ref:/EmulatedDevice[@Name='Device2']/Ipv6If + AffiliationStreamBlockLoadProfile: + Load: 10 + + + # To configure traffic between MLD groups + - + name: Configure the traffic generator2 + stc: + count: 1 + action: create + under: /project + objects: + - StreamBlock: + EnableStreamOnlyGeneration: true + SrcBinding-targets: | + ref:/EmulatedDevice[@Name='Device1']/MLDhostConfig[@Name='MLDhost1'] + /MLDGroupMembership[@Name='group1']/Ipv6NetworkBlock + DstBinding-targets: | + ref:/EmulatedDevice[@Name='Device2']/MLDhostConfig[@Name='MLDhost2'] + /MLDGroupMembership[@Name='group2']/Ipv6NetworkBlock + AffiliationStreamBlockLoadProfile: + Load: 10 + +For more examples please check `Playbooks `_. \ No newline at end of file diff --git a/docs/Multicast.rst b/docs/Multicast.rst new file mode 100644 index 0000000..2dc5c60 --- /dev/null +++ b/docs/Multicast.rst @@ -0,0 +1,295 @@ +Multicast Group +=============== + +.. contents:: + :local: + :depth: 1 + +Overview +-------- + +In `STC Ansible` you can create IPv4 or IPv6 multicast group objects. + +These multicast group objects will be used for the IGMP (for IPv4), MLD (for IPv6), and PIM protocols. + +Create Multicast Group +---------------------- + +Purpose +~~~~~~~ + +Creates IPv4 or IPv6 multicast group object(s) in the Spirent Test Center(stc) datamodel under the project. +During the object creation, Name and other properties can be defined. +The name of the multicast group will be used as a reference in order to reconfigure/modify +any of it's properties later. + +.. role:: mandatory + + +Synopsis +~~~~~~~~ + +.. note:: :mandatory:`M` indicates that the parameter is :mandatory:`Mandatory`. + +.. parsed-literal:: + - + name: create multicast group + stc: + action: create :mandatory:`M` + under: :mandatory:`M` + count: + objects: + - :mandatory:`M` + + . + . + +Parameters +~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstring +
Specifies the action for the given task. Here, it is create.
+
Required: Yes
+
underxpath +
A project under which the multicast group is created.
+
Required: Yes
+
Example:
+
under: ref:/project
+
See Also:
+ +
count integer +
Specifies the number of multicast groups to be created.
+
Count value above 1, creates several multicast groups in an iterative way.
+
Use the keyword ${item} as a template in group names. The item will be replace with the values from 1 to count.
+
Required: No. Optional field
+
objectsstring +
Specifies to identify stc objects and attributes.
+
To create IPv4 multicast group, use Ipv4group object.
+
To create IPv6 multicast group, use Ipv6group object.
+
Required: Yes.
+
See Also:
+
+ + + + + +Examples +~~~~~~~~ + +.. code-block:: yaml + + - + name: create IPv4 Multicast group + stc: + action: create + under: /project + count: 1 + objects: + - Ipv4group: + name: Ipv4Group1 + Active: true + Ipv4NetworkBlock: + StartIpList: 225.0.0.1 + PrefixLength: 32 + NetworkCount: 10 + Active: true + + - + name: create IPv6 Multicast group + stc: + action: create + under: /project + count: 1 + objects: + - Ipv6group: + name: Ipv6Group1 + Active: true + Ipv6NetworkBlock: + StartIpList: ff1e::1 + PrefixLength: 128 + NetworkCount: 10 + Active: true + + - + name: create 10 IPv4 multicast groups + stc: + action: create + under: /project + count: 10 + objects: + -IPv4group + Name: "Ipv4group${item}" + Active: true + Ipv4NetworkBlock: + StartIpList: 225.0.${item}.1 + PrefixLength: 32 + NetworkCount: 10 + Active: true + + + +Configure Multicast Group +------------------------- + +Purpose +~~~~~~~ + +Reconfigures/modifies an existing multicast group properties. + +.. role:: mandatory + + +Synopsis +~~~~~~~~ + +.. parsed-literal:: + - + name: configure multicast group + count: + stc: + action: config :mandatory:`M` + object: :mandatory:`M` + properties: :mandatory:`M` + + . + . + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstringSpecifies the action for the given task. Here it is config. +
Required: Yes
+
count integer +
Specifies the number of multicast groups to be configured.
+
Count value above 1, configures several multicast groups in an iterative way.
+
Use the keyword ${item} as a template in group names. The item will be replace + with the values from 1 to count.
+
Required: No. Optional field
+
objectxpath +
An emulated IGMP device object under which the attributes are configured.
+
Required: Yes
+
Example:
+
object: ref:/project
+
OR
+
object: /project
+
See Also:
+ +
propertiesstring +
Specifies to identify the properties of multicast group.
+
Required: Yes
+
For IPv4 multicast group attributes, please refer
+
IPv4 multicast group reference guide
+
For IPv6 multicast group attributes, please refer
+ + +Examples +~~~~~~~~ + +.. code-block:: yaml + + - + name: configure IPv4 multicast group + stc: + action: config + count: 1 + object: ref:/project/Ipv4Group[@Name='Ipv4group1'] + properties: + Ipv4NetworkBlock: + StartIpList: 225.0.1.1 + PrefixLength: 32 + NetworkCount: 10 + Active: true + + - + name: configure IPv6 multicast group + stc: + action: config + count: 1 + object: ref:/project/Ipv6Group[@Name='Ipv6group1'] + properties: + Ipv6NetworkBlock: + StartIpList: ff1e::1 + PrefixLength: 128 + NetworkCount: 10 + Active: true + diff --git a/docs/OSPF.rst b/docs/OSPF.rst new file mode 100644 index 0000000..31d4eba --- /dev/null +++ b/docs/OSPF.rst @@ -0,0 +1,709 @@ +Routing Protocol - OSPF +======================= + +.. contents:: + :local: + :depth: 1 + +Overview +-------- + +`STC Ansible` module allows you to create various Open Shortest Path First (OSPF) Protocol test scenarios. +It helps to create scaling tests with hundreds of emulated OSPF routers advertising thousands of +Link-state advertisements (LSAs). + +To create and configure an emulated OSPF Protocol test through `STC Ansible` module, +initially you should create `Ospfv2routerconfig` object for OSPF v2 or `Ospfv3routerconfig` object for OSPF v3 +under an emulated device. Once the OSPF protocol is enabled on the emulated device, it will act as a OSPF router. + +OSPF LSAs should be created on top of an emulated OSPF router using different LSA objects. + +You can configure all the characteristics of a OSPF emulated router as well as the LSAs during +the creation of OSPF devices and LSAs. Same can also be reconfigured/modify later. + +Once the OSPF routers and LSAs set up is done, you can configure the Streamblock/traffic generator +between the routers or the LSAs by setting the source and destination OSPF object references. + +Now, you can verify the traffic statistics (transmitted and received packets) between the +routers/LSAs by starting the devices (here emulated OSPF routers). + +Please refer example playbooks ospfv2-traffic.yaml and ospfv3-traffic.yaml in +`Github `_ link. + + +Create OSPF Device +------------------ + +Purpose +~~~~~~~ + +Creates OSPF object(s) in the Spirent Test Center(stc) datamodel under the emulated device object(s). +During the object creation, Name and other OSPF properties can be defined. +The name of the OSPF object will be used as a reference in order to reconfigure/modify +any of it's properties later. + +.. role:: mandatory + + +Synopsis +~~~~~~~~ + +.. note:: :mandatory:`M` indicates that the parameter is :mandatory:`Mandatory`. + +.. parsed-literal:: + - + name: create OSPF device + stc: + action: create :mandatory:`M` + under: :mandatory:`M` + count: + objects: + - :mandatory:`M` + + + . + . + +Parameters +~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstring +
Specifies the action for the given task. Here, it is create.
+
Required: Yes
+
underxpath +
An emulated device under which the OSPF protocol is created.
+
Required: Yes
+
Example:
+
under: /EmulatedDevice[@Name=’Device1’]
+
See Also:
+ + +
NOTES:
+
1. EmulatedDevice must already exist.
+
2. If the device does not exist with the specified name, an exception will be raised and the playbook stops.
+
count integer +
Specifies the number of OSPF devices to be created.
+
Count value above 1, creates several OSPF objects in an iterative way.
+
Use the keyword ${item} as a template in device names. The item will be replace with the values from 1 to count.
+
Required: No. Optional field
+
objectsstring +
Specifies to identify stc objects and attributes.
+
To create OSPF version 2 device, use Ospfv2RouterConfig object.
+
To create OSPF version 3 device, use Ospfv3RouterConfig object.
+
Required: Yes.
+
See Also:
+
+ + + + + +Examples +~~~~~~~~ + +.. code-block:: yaml + + - + name: create OSPF v2 on Ipv4 Device + stc: + action: create + under: /EmulatedDevice[@Name='IPV4-Device1'] + count: 1 + objects: + - Ospfv2RouterConfig: + AreaId: 0.0.0.0 + NetworkType: P2P + HelloInterval: 20 + Name: "OSPFv2Router1" + + - + name: create OSPF v3 on Ipv6 Device + stc: + action: create + under: /EmulatedDevice[@Name='IPV6-Device1'] + count: 1 + objects: + - Ospfv3RouterConfig: + AreaId: 0.0.0.0 + NetworkType: P2P + HelloInterval: 20 + Name: "OSPFv3Router1" + + - + name: create 10 OSPF devices with different area id's + stc: + action: create + under: /EmulatedDevice[@Name='Device${item}'] + count: 10 + objects: + - Ospfv2RouterConfig: + AreaId: 0.0.0.${item} + NetworkType: P2P + HelloInterval: 20 + Name: "IPV6-OSPFRouter${item}" + + +Configure OSPF Device +--------------------- + +Purpose +~~~~~~~ + +Reconfigures/modifies an existing OSPF objects properties. + +.. role:: mandatory + + +Synopsis +~~~~~~~~ + +.. parsed-literal:: + - + name: configure OSPF device + count: + stc: + action: config :mandatory:`M` + object: :mandatory:`M` + properties: :mandatory:`M` + + + . + . + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstringSpecifies the action for the given task. Here it is config. +
Required: Yes
+
count integer +
Specifies the number of OSPF devices to be configured.
+
Count value above 1, creates several OSPF objects in an iterative way.
+
Use the keyword ${item} as a template in device names. The item will be replace + with the values from 1 to count.
+
Required: No. Optional field
+
objectxpath +
An emulated OSPF device object under which the attributes are configured.
+
Required: Yes
+
Example:
+
object: ref:/EmulatedDevice[@Name='Dev1']/Ospfv2RouterConfig[@Name='OSPFDev1']
+
object: ref:/EmulatedDevice[@Name='Dev1']/Ospfv3RouterConfig[@Name='OSPFDev1']
+
See Also:
+ +
NOTES:
+
1. OSPFv2 or OSPFv3 device must already exist.
+
2. If the device does not exist with the specified name, an exception will be raised and the playbook stops.
+
propertiesstring +
Specifies to identify the properties of OSPF objects.
+
Required: Yes
+
+ + +Examples +~~~~~~~~ + +.. code-block:: yaml + + - + name: configure/modify OSPFv2 device properties + stc: + action: config + count: 1 + object: ref:/EmulatedDevice[@Name='Device1']/Ospfv2RouterConfig[@Name='OSPFDevice1'] + properties: + AreaId: 0.0.0.1 + NetworkType: P2P + HelloInterval: 10 + + - + name: configure/modify OSPFv3 device properties + stc: + action: config + count: 1 + object: ref:/EmulatedDevice[@Name='Device1']/Ospfv3RouterConfig[@Name='OSPFDevice1'] + properties: + AreaId: 0.0.0.1 + NetworkType: P2P + HelloInterval: 10 + + - + name: configure/modify multiple OSPF device properties + stc: + action: configure + count: 10 + object: ref:/EmulatedDevice[@Name='Device${item}']/Ospfv2RouterConfig[@Name='OSPFDevice${item}'] + properties: + AreaId: 0.0.0.${item} + NetworkType: P2P + HelloInterval: 10 + + +Create OSPF LSAs +---------------- + +Purpose +~~~~~~~ + +Creates and configures different types of OSPF LSAs under a specific OSPF device object. +It also defines the characteristics of the LSA's that will be advertised at the +beginning of the session. + +Synopsis +~~~~~~~~ + +.. parsed-literal:: + - + name: create OSPF LSA + under: :mandatory:`M` + count: + stc: + action: create :mandatory:`M` + objects: :mandatory:`M` + - : + + + . + . + +Parameters +~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstringSpecifies the action for the given task. Here it is create. +
Required: yes
+
underxpath +
A OSPF device under which the OSPF LSA is created.
+
Required: Yes
+
Example:
+
under: /EmulatedDevice[@Name='Dev1']/Ospfv2RouterConfig[@Name='OSPFDev1']
+
OR
+
under: ref:/EmulatedDevice[@Name='Dev1']/Ospfv3RouterConfig[@Name='OSPFDev1']
+
See also:
+ +
NOTES:
+
1. OSPF v2 or OSPF v3 Device must already exist
+
2. If the path is incorrect, an exception will be raised and the playbook stops. +
count integer +
Specifies the number of OSPF routes to be created.
+
Count value above 1, creates several OSPF Route objects in an iterative way.
+
Use the keyword ${item} as a template in device names. The item will be replace with the values from 1 to count.
+
Required: No. Optional field.
+
objectsstring +
Specifies to identify stc objects and attributes.
+
To create Router LSAs under OSPF v2 and OSPF v3 routers, use RouterLsa and Ospfv3RouterLsa objects. +
To create AS-External Prefix LSA under OSPF v2 and OSPF v3 routers, use ExternalLsablock and Ospfv3AsExternalLsaBlock objects. +
Required: Yes.
+
+ + +Examples +~~~~~~~~ + + 1. Sample YAML code to Router LSA on OSPF v2 device: + + .. code-block:: yaml + + - + name: create Router LSA on Ospf v2 device + stc: + action: create + under: /EmulatedDevice[@Name='Device1']/Ospfv2RouterConfig[@Name='Ospfv2Router1'] + count: 1 + objects: + - RouterLsa: + name: "LSA1" + AdvertisingRouterId: 1.1.1.1 + Abr: FALSE + LinkStateId: 2.2.2.2 + RouterLsaLink: + LinkCount: 10 + LinkType: POINT_TO_POINT + + 2. Sample YAML code to Router LSA on OSPF v3 device: + + .. code-block:: yaml + + - + name: create Router LSA on Ospf v3 device + stc: + action: create + under: /EmulatedDevice[@Name='IPV6-Device1']/Ospfv3RouterConfig[@Name='Ospfv3Router1'] + count: 1 + objects: + - Ospfv3RouterLsa: + name: "LSA1" + AdvertisingRouterId: 1.1.1.1 + Abr: FALSE + LinkStateId: 1 + Ospfv3RouterLsaIf: + IfType: POINT_TO_POINT + NeighborRouterId: 1.1.1.1 + Ospfv3Srv6EndXSidSubTlv: + Algorithm: 1 + SID: aaaa:1:1:1:: + + 3. Sample YAML code to NSSA LSA on OSPF v2 device: + + .. code-block:: yaml + + - + name: create NSSA on OSPF v2 device + stc: + action: create + under: /EmulatedDevice[@Name='OSPFDevice1']/Ospfv2RouterConfig[@Name='OSPFRouter1'] + count: 1 + objects: + - ExternalLsaBlock: + name: "NSSA1" + Ipv4NetworkBlock: + NetworkCount: 10 + StartIpList: 2.2.2.2 + + 4. Sample YAML code to NSSA LSA on OSPF v3 device: + + .. code-block:: yaml + + - + name: create NSSA on OSPF v3 device + stc: + action: create + under: /EmulatedDevice[@Name='Ipv6-OSPFDevice1']/Ospfv3RouterConfig[@Name='OSPFRouter1'] + count: 1 + objects: + - Ospfv3AsExternalLsaBlock: + name: "NSSA1" + Ipv6NetworkBlock: + NetworkCount: 10 + StartIpList: 3000::1 + + 5. Sample YAML code to create multiple Router LSAs on OSPF v2 device: + + .. code-block:: yaml + + - + name: create 10 Ospf v2 LSAs + stc: + action: create + under: /EmulatedDevice[@Name='Device${item}']/Ospfv2RouterConfig[@Name='OSPFRouter${item}'] + count: 10 + objects: + - RouterLsa: + name: "LSA1" + AdvertisingRouterId: 1.1.1.${item} + Abr: FALSE + LinkStateId: 2.2.2.${item} + RouterLsaLink: + LinkCount: 10 + LinkType: POINT_TO_POINT + + +Configure OSPF LSAs +------------------- + +Purpose +~~~~~~~ + +Reconfigures/modifies an existing OSPF v2 or v3 LSA object and it's child objects properties. + +.. role:: mandatory + + +Synopsis +~~~~~~~~ + +.. parsed-literal:: + - + name: configure OSPF LSA + count: + stc: + action: config :mandatory:`M` + object: :mandatory:`M` + properties: :mandatory:`M` + + + + + + + +Parameters +~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstringSpecifies the action for the given task. Here it is config. +
Required: Yes.
+
count integer +
Specifies the number of OSPF LSAs to be configured.
+
Count value above 1, creates several OSPF LSA objects in an iterative way.
+
Use the keyword ${item} as a template in device names. The item will be replace + with the values from 1 to count.
+
Required: No. Optional field.
+
objectxpath +
An emulated OSPF LSA object under which the attributes are configured.
+
Required: Yes
+
Example:
+
ref:/EmulatedDevice[@Name='Dev1']/Ospfv2RouterConfig[@Name='OSPFDev1']/
+
ExternalLsablock[@Name='NSSA-Route1']
+
OR
+
ref:/EmulatedDevice[@Name='Dev1']/Ospfv3RouterConfig[@Name='OSPFDev1']/
+
Ospfv3AsExternalLsaBlock[@Name='NSSA-Route1']
+
See Also:
+ +
NOTES:
+
1. OSPF device must already exist.
+
2. If the device does not exist with the specified name, an exception will be raised and the playbook stops.
+
propertiesstring +
Specifies to identify the properties of OSPF LSA objects.
+
Required: Yes
+
+ + +Examples +~~~~~~~~ + +.. code-block:: yaml + + - + name: config NSSA LSA under OSPF v2 device + stc: + action: config + count: 1 + objects: /EmulatedDevice[@Name='OSPFDevice1']/Ospfv2RouterConfig[@Name='OSPFRouter1']/ExtendedLinkLsa[@Name='NSSA1'] + properties: + AdvertisingRouterId: 1.1.1.1 + Ipv4NetworkBlock: + NetworkCount: 101 + StartIpList: 3.3.3.3 + + - + name: config NSSA LSA under OSPF v3 device + stc: + action: config + count: 1 + objects: /EmulatedDevice[@Name='OSPFDevice2']/Ospfv3RouterConfig[@Name='OSPFRouter2']/Ospfv3AsExternalLsaBlock[@Name='NSSA1'] + properties: + AdvertisingRouterId: 1.1.1.1 + Ipv6NetworkBlock: + NetworkCount: 101 + StartIpList: 3000::1 + + +Configure OSPF Traffic +---------------------- + +Purpose +~~~~~~~ + +Configures the traffic between the OSPF devices or LSAs. +About creating a bound streamblock, please refer `StreamBlock <../docs/StreamBlock.rst>`_ section and +`Start Protocols <../docs/Start_Protocols.rst>`_, `Results <../docs/Results.rst>`_ sections to +start devices and get TX(transmitted)/RX(received) counter values. + +Examples +~~~~~~~~ + +.. code-block:: yaml + + # To configure traffic between OSPF Devices + - + name: Configure the traffic generator1 + stc: + count: 1 + action: create + under: /project + objects: + - StreamBlock: + EnableStreamOnlyGeneration: true + SrcBinding-targets: ref:/EmulatedDevice[@Name='Device1']/Ipv4If + DstBinding-targets: ref:/EmulatedDevice[@Name='Device2']/Ipv4If + AffiliationStreamBlockLoadProfile: + Load: 10 + + + # To configure traffic between OSPF v2 network blocks + - + name: Configure the traffic generator2 + stc: + count: 1 + action: create + under: /project + objects: + - StreamBlock: + EnableStreamOnlyGeneration: true + SrcBinding-targets: | + ref:/EmulatedDevice[@Name='Device1']/Ospfv2RouterConfig[@Name='OSPFRouter1'] + /ExternalLsablock[@Name='NSSA1']/Ipv4NetworkBlock + DstBinding-targets: | + ref:/EmulatedDevice[@Name='Device2']/Ospfv2RouterConfig[@Name='OSPFRouter2'] + /ExternalLsablock[@Name='NSSA2']/Ipv4NetworkBlock + AffiliationStreamBlockLoadProfile: + Load: 10 + + + # To configure traffic between OSPF v3 network blocks + - + name: Configure the traffic generator3 + stc: + count: 1 + action: create + under: /project + objects: + - StreamBlock: + EnableStreamOnlyGeneration: true + SrcBinding-targets: | + ref:/EmulatedDevice[@Name='Device1']/Ospfv3RouterConfig[@Name='OSPFRouter1'] + /Ospfv3AsExternalLsaBlock[@Name='NSSA1']/Ipv6NetworkBlock + DstBinding-targets: | + ref:/EmulatedDevice[@Name='Device2']/Ospfv3RouterConfig[@Name='OSPFRouter2'] + /Ospfv3AsExternalLsaBlock[@Name='NSSA2']/Ipv6NetworkBlock + AffiliationStreamBlockLoadProfile: + Load: 10 + +For more examples please check `Playbooks `_. \ No newline at end of file diff --git a/docs/Port.rst b/docs/Port.rst new file mode 100644 index 0000000..3a73a8b --- /dev/null +++ b/docs/Port.rst @@ -0,0 +1,419 @@ +Port +==== + +.. contents:: + :local: + :depth: 1 + +Overview +-------- + +In `STC Ansible`, after creating a session and connecting to the Spirent Test Center chassis, +you need to create the port objects. + +You can create a single or multiple ports. Use `Port` object to create ports under the project. +All the characteristics of a port can be configured during the creation of port itself. +Same can also be reconfigured/modify later. + +Once the port creation is done, you can create/configure the `Emulated Devices <../docs/EmulatedDevice.rst>`_, +`Stream Blocks <../docs/Stream Block.rst>`_ under the ports. + +Then reserve the ports to perform the test and get the expected results. + + +Create Port +----------- + +Purpose +~~~~~~~ + +Creates port object(s) in the Spirent Test Center(stc) datamodel under the project. +During the object creation, requires to configure it's characteristics like name and location. +The name of the port object will be used as a reference in order to reconfigure/modify +any of it's properties later. + + +.. role:: mandatory + + +Synopsis +~~~~~~~~ + +.. note:: :mandatory:`M` indicates that the parameter is :mandatory:`Mandatory`. + + +.. parsed-literal:: + + - + name: create port + stc: + action: create :mandatory:`M` + under: :mandatory:`M` + count: + under: :mandatory:`M` + objects: + - :mandatory:`M` + + + . + . + +Parameters +~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstring +
Specifies the action for the given task. Here, it is create.
+
Required: Yes
+
underxpath +
A project reference under which a stream block is created.
+
Required: Yes
+
Example:
+
under: ref:/project
+
See Also:
+ + +
NOTES:
+
1. Session must already exist.
+
count integer +
Specifies the number of stream blocks to be created.
+
Count value above 1, creates several port objects in an iterative way.
+
Use the keyword ${item} as a template in port object names. The item will be replace with the values from 1 to count.
+
Required: No. Optional field
+
objectsstring +
Specifies to identify stc objects and attributes.
+
To create port, use Port object.
+
Required: Yes.
+
See Also:
+
+ + + + + +Examples +~~~~~~~~ + + 1. Sample YAML code to create a port under project: + + .. code-block:: yaml + + - + name: Create a port + stc: + action: create + under: ref:/project + objects: + - port: + location: "//10.109.123.122/1/1" + name: Port1 + + 2. Sample YAML code to create multiple ports: + + .. code-block:: yaml + + - + name: Create 10 ports + stc: + action: create + under: ref:/project + count: 10 + objects: + - port: + location: "//10.109.123.122/1/$item" + name: Port-$item + + 3. Create ports with the reference to pre-defined port locations and names. + Chassis, ports and names will be defined in session creation task or in an inventory.ini file. + Please refer `Session <../docs/Session.rst>`_ section for more details. + + .. code-block:: yaml + + - + name: Create 10 ports + stc: + action: create + under: ref:/project + count: 10 + objects: + - port: + location: "//${chassis[0]}/1/$item" + name: Port-$item + + - + name: Create 11 ports + stc: + action: create + count: 11 + under: ref:/project + objects: + - port: + location: ${ports[item]} + name: ${names[item]} + + 4. Sample YAML code to create offline ports: + + .. code-block:: yaml + + - + name: Create a port + stc: + action: create + under: ref:/project + objects: + - port: + location: "//(Offline)/1/1" + name: Port1 + - port: + location: "//(Offline)/1/2" + name: Port2 + +Configure Port +-------------- + +Purpose +~~~~~~~ + +Reconfigures/modifies an existing port properties. + +.. role:: mandatory + + +Synopsis +~~~~~~~~ + +.. parsed-literal:: + - + name: configure port + count: + stc: + action: config :mandatory:`M` + objects: :mandatory:`M` + properties: + + + . + . + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstringSpecifies the action for the given task. Here it is config. +
Required: Yes
+
count integer +
Specifies the number of ports to be configured.
+
Count value above 1, creates several port objects in an iterative way.
+
Use the keyword ${item} as a template in port names. The item will be replace + with the values from 1 to count.
+
Required: No. Optional field
+
objectsxpath +
A port object under which the attributes are configured.
+
Required: Yes
+
Example:
+
object: /Port[@Name='Port1']
+
See Also:
+ +
NOTES:
+
1. Session must already exist.
+
2. If the port does not exist with the specified name, an exception will be raised and the playbook stops.
+
propertiesstring +
Specifies to identify the properties of port object.
+
Required: Yes
+
Example:
+
properties:
+
location: "//10.109.123.12/1/1"
+
See Also:
+
+ + +Examples +~~~~~~~~ + + .. code-block:: yaml + + - + name: Configure port properties + stc: + action: config + under: ref:/project + objects: ref:/Port[@Name='Port1'] + properties: + location: "//10.109.123.123/1/1" + + +Bring ports online/offline +-------------------------- + +Purpose +~~~~~~~ + +Reserves/releases and map/unmap one or more ports. + + +Synopsis +~~~~~~~~ + +.. parsed-literal:: + + - + name: Reserve/Release ports + stc: + action: perform :mandatory:`M` + command: Attachports/DetachPorts :mandatory:`M` + properties: + PortList: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstringSpecifies the action for the given task. Here it is perform. +
Required: Yes.
+
command string +
Specifies the command name to reserve or release ports.
+
To reserve ports, use AttachportsCommand
+
To release ports, use DetachPortsCommand
+
Required: Yes.
+
propertiesstring +
Specifies the properties supported to perform AttachPorts or DetachPorts command. +
Required: Yes.
+
See Also:
+
+ + +Examples +~~~~~~~~ + +.. code-block:: yaml + + # To reserve one port + - + name: Take ports online + stc: + action: perform + command: AttachPorts + properties: + PortList: ref:/port[@Name='Port1'] + + # To reserve all ports + - + name: Take ports online + stc: + action: perform + command: AttachPorts + properties: + PortList: ref:/port + + # To release one port + - + name: Take ports offline + stc: + action: perform + command: DetachPorts + properties: + PortList: ref:/port[@Name='Port1'] + + # To release ports + - + name: Take ports offline + stc: + action: perform + command: DetachPorts + properties: + PortList: ref:/port diff --git a/docs/Results.rst b/docs/Results.rst new file mode 100644 index 0000000..5dbe1f3 --- /dev/null +++ b/docs/Results.rst @@ -0,0 +1,511 @@ +Results +======= + +.. contents:: + :local: + :depth: 1 + +Overview +-------- + +STC Ansible allows you to subscribe to a runtime Result Views (Classic views) that is already +defined by a Result View Template XML file. + +After completing the test configuration, you need to subscribe specific result views in order +to get and display the results related to your current test. + +In STC Ansible to get DRV results, first you need to create Dynamic Result View by defining +the required properties and then need to subscribe them. + +After subscribing the result views, you can start the test (Start devices/traffic) and get the +results. Using `register` option, you can store the result output in a variable. To display the +stored result content you need to use `debug` task. + +Subscribe Results +----------------- + +Purpose +~~~~~~~ + +Specifies to subscribe to a runtime Result View that is already defined by a Result +View Template XML file. + +.. role:: mandatory + + +Synopsis +~~~~~~~~ + +.. note:: :mandatory:`M` indicates that the parameter is :mandatory:`Mandatory`. + + +.. parsed-literal:: + + - + name: subscribe results + stc: + action: perform :mandatory:`M` + command: SubscribeResultsView :mandatory:`M` + properties: + TemplateUri: :mandatory:`M` + + +Parameters +~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstring +
Specifies the action for the given task. Here, it is perform.
+
Required: Yes
+
commandstring +
Specifies the command name to subscribe the result views.
+
To subscribe result views, use SubscribeResultsView command.
+
Required: Yes.
+
propertiesstring +
Specifies the properties supported to perform subscribe results command. +
Required: Yes.
+
Example:
+
properties:
+
TemplateUri: "/Result Views/Stream Results/Stream Block Results.xml"
+
See Also:
+
SubscribeResultsViewCommand page
+
NOTES:
+
Default result view template xml files are available in Labserver under
+
"/home/testcenter/server/Templates/System/Result Views/"
+
+ + + + + +Examples +~~~~~~~~ + + 1. Sample YAML code to subscribe Stream Block Results: + + .. code-block:: yaml + + - + name: subscribe to streamblock results + stc: + action: perform + command: SubscribeResultsView + properties: + ExecuteSynchronous: true + TemplateUri: "/Result Views/Stream Results/Stream Block Results.xml" + + 2. Sample YAML code to subscribe Detailed Stream Results: + + .. code-block:: yaml + + - + name: subscribe to streamblock results + stc: + action: perform + command: SubscribeResultsView + properties: + ExecuteSynchronous: true + TemplateUri: "/Result Views/Stream Results/Detailed Stream Results.xml" + + 3. Sample YAML code to subscribe PPPox Results: + + .. code-block:: yaml + + - + name: subscribe to PPPoX results + stc: + action: perform + command: SubscribeResultsView + properties: + ExecuteSynchronous: true + TemplateUri: "/Result Views/Access Protocols/PPPoX Results.xml" + + + +Get results +----------- + +Purpose +~~~~~~~ + +Specifies to get the results from the properties of the result object defined in the data model. + +.. role:: mandatory + + +Synopsis +~~~~~~~~ + +.. note:: :mandatory:`M` indicates that the parameter is :mandatory:`Mandatory`. + + +.. parsed-literal:: + + - + name: get results + register: + stc: + action: get :mandatory:`M` + objects: :mandatory:`M` + +Parameters +~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
registerstring +
Specifies a variable name to store the results.
+
It will be used later to display the received result counters details.
+
Required: No. optional field.
+
actionstring +
Specifies the action for the given task. Here, it is get.
+
Required: Yes
+
commandstring +
Specifies the command name to subscribe the result views.
+
To subscribe result views, use SubscribeResultsView command.
+
Required: Yes.
+
objectsxpath +
Specifies to identify result object names.
+
Required: Yes
+
Example:
+
objects: /port/StreamBlock/RxStreamBlockResults
+
objects: /port/StreamBlock/TxStreamBlockResults
+
objects: /EmulatedDevice[@Name='PPPoE']/PppoeServerBlockConfig/
+
PppoeServerBlockResults
+
See Also:
+ + +
+ + + + + +Examples +~~~~~~~~ + + 1. Sample YAML code to get StreamBlock Rx Results: + + .. code-block:: yaml + + - + name: get StreamBlock Rx Results + register: resultRx + stc: + action: get + objects: /port/StreamBlock/RxStreamBlockResults + + 2. Sample YAML code to get StreamBlock Tx Results: + + .. code-block:: yaml + + - + name: get StreamBlock Tx Results + register: resultRx + stc: + action: get + objects: /port/StreamBlock/TxStreamBlockResults + + 3. Sample YAML code to get PPPoE Server Results: + + .. code-block:: yaml + + - + name: Get the server binding results + register: pppoxresult + stc: + action: get + objects: /EmulatedDevice[@Name='PPPoE Server']/PppoeServerBlockConfig/PppoeServerBlockResults + +Display Results +--------------- + +To display the results or the output of the registered variable, use the debug task. + +.. parsed-literal:: + + - debug: + var: + +Examples +~~~~~~~~ + + 1. Sample YAML code to get and display the StreamBlock Rx Results: + + .. code-block:: + + - + name: get StreamBlock Rx Results + register: resultRx + stc: + action: get + objects: /port/StreamBlock/RxStreamBlockResultss + + - debug: + var: resultRx + + +Create and get DRV Results +-------------------------- + +Purpose +~~~~~~~ + +Creates the dynamic result view (DRV) related queries and properties. The sub object +`PresentationResultQuery` provides SQL like syntax for defining the result that users +are interested in. +After creating the DRV query, subscribes and get the DRV specific result counters. + +.. role:: mandatory + + +Synopsis +~~~~~~~~ + +.. note:: :mandatory:`M` indicates that the parameter is :mandatory:`Mandatory`. + +.. parsed-literal:: + - + name: create a DRV + stc: + action: create :mandatory:`M` + under: :mandatory:`M` + objects: + - DynamicResultView: :mandatory:`M` + PresentationResultQuery: :mandatory:`M` + + + . + . + +Parameters +~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstring +
Specifies the action for the given task. Here, it is create.
+
Required: Yes
+
underxpath +
A project reference under which the Dynamic Result View is created.
+
Required: Yes
+
Example:
+
under: ref:/project
+
See Also:
+ +
count integer +
Specifies the number of BGP devices to be created.
+
Count value above 1, creates several BGP objects in an iterative way.
+
Use the keyword ${item} as a template in device names. The item will be replace with the values from 1 to count.
+
Required: No. Optional field
+
objectsstring +
Specifies to identify stc objects and attributes.
+
To create a DRV, use DynamicResultView object.
+
Required: Yes.
+
Example:
+
objects:
+
-DynamicResultView:
+
PresentationResultQuery:
+
Selectproperties: "StreamBlock.StreamId StreamBlock.Name Port.Name"
+
See Also:
+
DynamicResultView object reference guide
+
NOTES:
+
If the DRV query parameters are not valid, the create action will not fail, but the subsequent drv.subscribe will fail.
+
+ + + + + +Examples +~~~~~~~~ + +.. code-block:: yaml + + - + name: Create a DRV for dropped frames + stc: + action: create + under: ref:/project + objects: + - DynamicResultView: + name: "Dropped Frames DRV" + PresentationResultQuery: + DisableAutoGrouping: True + SelectProperties: "StreamBlock.StreamId StreamBlock.Name Port.Name StreamBlock.ActualRxPortName StreamBlock.FrameConfig.ipv4:IPv4.1.sourceAddr StreamBlock.FrameConfig.ipv4:IPv4.1.destAddr StreamBlock.FrameConfig.ethernet:EthernetII.1.srcMac StreamBlock.FrameConfig.ethernet:EthernetII.vlans.Vlan.1.id StreamBlock.TxFrameCount StreamBlock.RxSigFrameCount StreamBlock.TxFrameRate StreamBlock.RxSigFrameRate StreamBlock.DuplicateFrameCount StreamBlock.DroppedFrameCount StreamBlock.DroppedFrameDuration StreamBlock.MinLatency StreamBlock.MaxLatency StreamBlock.AvgLatency StreamBlock.IsExpected" + WhereConditions: "{StreamBlock.DroppedFrameCount > 0 AND StreamBlock.IsExpected = 1}" + SortBy: "{StreamBlock.DroppedFrameCount DESC}" + FromObjects: ref:/project/port + LimitSize: 20000 + + +Subscribe DRV Results +~~~~~~~~~~~~~~~~~~~~~ + +To subscribe the DRV results use the following YAML task. + + .. code-block:: yaml + + - + name: Subscribe DRV results for dropped frames + stc: + action: drv.subscribe + objects: ref:/project/DynamicResultView[name="Dropped Frames DRV"] + +Get and display DRV Results +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To get and display the DRV results use the following YAML task. + + .. code-block:: yaml + + - + name: Fetch DRV results for dropped frames + register: DRVResults + stc: + action: drv.fetch + objects: ref:/project/DynamicResultView[name="Dropped Frames DRV"] + + - + debug: + var: DRVResults diff --git a/docs/Session.rst b/docs/Session.rst new file mode 100644 index 0000000..4ce5041 --- /dev/null +++ b/docs/Session.rst @@ -0,0 +1,529 @@ +Session +======= + +.. contents:: + :local: + :depth: 1 + +Overview +-------- + +In `STC Ansible`, the first task of the playbook must be to create/attach to a STC labserver session. + +To create new session, you need to use `session` or `create_session` actions by specifing the user +and session name. If the session is already exists with the given name, it will attach automatically. + +If you wanted to connect only to an existing session, then use `attach_session` action. + +`STC Ansible` also allows to delete the existing sessions using `delete_session` and `delete_all_sessions`. + + +Create Session +-------------- + +Purpose +~~~~~~~ + +Creates session or attaches to an exisiting session. + + +.. role:: mandatory + + +Synopsis +~~~~~~~~ + +.. note:: :mandatory:`M` indicates that the parameter is :mandatory:`Mandatory`. + + +.. parsed-literal:: + + - + name: create session + stc: + action: session or create_session :mandatory:`M` + user: :mandatory:`M` + name: :mandatory:`M` + kill_existing: + reset_existing: + chassis: + ports: + names: + +Parameters +~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstring +
Specifies the action for the given task. Here, it is session or create_session.
+
Required: Yes
+
userstring +
Specifies the STC labserver session user name.
+
Required: Yes
+
namestring +
Specifies the STC labserver session name.
+
Required: Yes
+
kill_existingchoice +
true/false
+ 		+
Specifies to kill/attach to the existing session.
+
When the value is set to true - If the session with the given name is already exists on the connected STC lab server, it will be first killed and then creates new session./div> +
When the value is set to false - Attaches to an existing session./div> +
Default value is false.
+
Required: No. Optional field.
+
reset_existingchoice +
true/false
+ 		+
Specifies to reset the configuration.
+
When the value is set to true - Resets the in-memory configuration before connecting to the session./div> +
When the value is set to false - It will not perform reset./div> +
Default value is true.
+
Required: No. Optional field.
+
chassisstring +
Specifies the IP or hostname of the chassis to connect to.
+
Required: No. Optional field.
+
Example:
+
chassis: "10.109.118.32"
OR +
If the chassis IPs are already defined in inventory.ini file,
+
chassis: "{{ hostvars[inventory_hostname].chassis }}"
+
See Also:
+
- Getting Started section to configure inventory.ini file
+
portsstring +
Specifies the location of the slot/ports.
+
Required: No. Optional field.
+
Example:
+
ports: //${chassis[0]}/1/1
+
If ports are already defined in inventory.ini file,
+
ports: "{{ hostvars[inventory_hostname].ports }}"
+
See Also:
+
- Getting Started section to configure inventory.ini file
+
namesstring +
Specifies to define the port names.
+
Required: No. Optional field.
+
Example:
+
names: Port-1, Port-2
+
If port names are already defined in inventory.ini file,
+
names: "{{ hostvars[inventory_hostname].names }}"
+
See Also:
+
- Getting Started section to configure inventory.ini file
+
+ + + + + +Examples +~~~~~~~~ + + 1. Sample YAML code to create a session: + + .. code-block:: yaml + + - + name: Create a session + stc: + action: session + user: ansible + name: sample_session1 + chassis: "10.109.118.32" + + OR + + - + name: Create a session + stc: + action: create_session + user: ansible + name: sample_session1 + chassis: "10.109.118.32" + + 2. Sample YAML code to create a session with pre-defined chassis, ports and names in the inventory.ini file: + + .. code-block:: yaml + + - + name: Create a session + stc: + action: create_session + user: ansible_user + name: sample_session1 + chassis: "{{ hostvars[inventory_hostname].chassis }}" + ports: "{{ hostvars[inventory_hostname].ports }}" + names: "{{ hostvars[inventory_hostname].names }}" + + 3. Sample YAML code to create a session with single chassis,slot and multiple ports: + + .. code-block:: yaml + + - + name: Create a session + stc: + action: create_session + user: mkatta + name: multi-port-test1 + chassis: "10.108.8.10" + ports: "//${chassis[0]}/2/1-5,6,8 //${chassis[0]}/2/7" + names: "port[1:7] qmport[8:8]" + + - + name: Create ports using pre-defined port locations and names + stc: + action: create + count: 8 + objects: + - project: + - port: + location: ${ports[item]} + name: ${names[item]} + + 4. Sample YAML code to create a session with single chassis and multiple slots/ports: + + .. code-block:: yaml + + - + name: Create a session + stc: + action: create_session + user: mkatta + name: multi-port-test1 + chassis: "10.109.115.123" + ports: "//${chassis[0]}/2/1-3,4,5 //${chassis[0]}/9/1" + names: "port[1:5] [6:6]myport" + + - + name: Create ports using pre-defined port locations and names + stc: + action: create + count: 6 + objects: + - project: + - port: + location: ${ports[item]} + name: ${names[item]} + + 5. Sample YAML code to create a session with multiple chassis and multiple slots/ports: + + .. code-block:: yaml + + - + name: Create a session + stc: + action: create_session + user: mkatta + name: multi-port-test1 + chassis: "10.109.115.123 10.109.112.121" + ports: "//${chassis[0]}/2/1-3,4,5 //${chassis[1]}/1/1" + names: "port[1:5] [6:6]myport" + + - + name: Create ports using pre-defined port locations and names + stc: + action: create + count: 6 + objects: + - project: + - port: + location: ${ports[item]} + name: ${names[item]} + +Attach an existing Session +-------------------------- + +Purpose +~~~~~~~ + +Use to attach an existing STC labserver session. If the session doen't exist, the playbook will fail. + +.. note:: :mandatory:`M` indicates that the parameter is :mandatory:`Mandatory`. + + +.. parsed-literal:: + + - + name: Attach session + stc: + action: attach_session :mandatory:`M` + user: + name: + +Parameters +~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstring +
Specifies the action for the given task. Here, it is attach_session.
+
Required: Yes
+
userstring +
Specifies the STC labserver session user name.
+
Required: Yes
+
namestring +
Specifies the STC labserver session name.
+
Required: Yes
+
+ + + + + +Examples +~~~~~~~~ + + Sample YAML code to attach a session: + + .. code-block:: yaml + + - + name: Attach a session + stc: + action: attach_session + user: ansible + name: session1 + + + +Delete Session +-------------- + +Purpose +~~~~~~~ + +Use to delete an existing session/all the sessions. + +.. note:: :mandatory:`M` indicates that the parameter is :mandatory:`Mandatory`. + + +.. parsed-literal:: + + - + name: Delete session + stc: + action: delete_session or delete_all_sessions :mandatory:`M` + user: + name: + +Parameters +~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstring +
Specifies the action for the given task. Here, it is delete_session or delete_all_sessions.
+
Required: Yes
+
userstring +
Specifies the STC labserver session user name.
+
This parameter can be specified when specific user created sessions need to be deleted.
+
Applicable only for delete_session action.
+
Required: No. Optional field
+
namestring +
Specifies the STC labserver session name or names.
+
Applicable only for delete_session action.
+
Required: Yes
+
Example:
+
name: Session1
+
To delete multiple sessions:
+
name: Session1, Session 2, Session3
+
+ + + + + +Examples +~~~~~~~~ + + 1. Sample YAML code to delete a session: + + .. code-block:: yaml + + - + name: Delete a session + stc: + action: delete_session + name: session1 + + 2. Sample YAML code to delete a session created by a specific user: + + .. code-block:: yaml + + - + name: Delete a session + stc: + action: delete_session + user: ansible + name: session1 + + 3. Sample YAML code to delete multiple sessions created by a specific user: + + .. code-block:: yaml + + - + name: Delete a session + stc: + action: delete_session + user: ansible + name: session1, session2 + + 4. Sample YAML code to delete all the existing sessions in the connected STC lab server: + + .. code-block:: yaml + + - + name: Delete a session + stc: + action: delete_all_sessions diff --git a/docs/Start_Protocols.rst b/docs/Start_Protocols.rst new file mode 100644 index 0000000..41d3418 --- /dev/null +++ b/docs/Start_Protocols.rst @@ -0,0 +1,118 @@ +Start Device (Protocols) +======================== + +.. contents:: + :local: + :depth: 1 + +.. role:: mandatory + +Purpose +~~~~~~~ + +Starts all the protocols on the specified device(s) or Port(s). + +Synopsis +~~~~~~~~ + +.. parsed-literal:: + + - + name: start devices + stc: + action: perform :mandatory:`M` + command: DeviceStart :mandatory:`M` + properties: + DeviceList: + +Parameters +~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstringSpecifies the action for the given task. Here it is perform. +
Required: Yes.
+
command string +
Specifies the command name to start the devices.
+
Required: Yes.
+
propertiesstring +
Specifies the properties supported to perform devicestart command. + Currently, supported property is "DeviceList".
+
Required: No. Optional field.
+
+ + + + +Examples +~~~~~~~~ + +.. code-block:: yaml + + # To start all devices + - + name: start devices + stc: + action: perform + command: DeviceStart + + # To start a specific device + - + name: start devices + stc: + action: perform + command: DeviceStart + properties: + DeviceList: ref:/EmulatedDevice[@Name='Device1'] + + # To start devices on a specific port + - + name: start devices + stc: + action: perform + command: DeviceStart + properties: + DeviceList: ref:/Port[@Name='Port1'] diff --git a/docs/StreamBlock.rst b/docs/StreamBlock.rst new file mode 100644 index 0000000..43699c5 --- /dev/null +++ b/docs/StreamBlock.rst @@ -0,0 +1,464 @@ +StreamBlock +=========== + +.. contents:: + :local: + :depth: 1 + +Overview +-------- + +STC Ansible allows to create a stream block or group of stream blocks of network traffic on the specified test port(s) or project. +A stream is a series of packets that can be tracked by STC Ansible. A stream block is a collection +of one or more streams represented by a base stream definition plus one or more rules that describe +how the base definition is modified to produce additional streams. + +To create a stream block, use `StreamBlock` object under the project or the port. + +Stream blocks are associated with a port. A port traffic generator sends traffic that is characterized +by the stream blocks that are associated with the port. + +A stream block defines the characteristics of traffic, such as frame size, QoS parameters and traffic rate. +Spirent TestCenter has two types of stream blocks: bound and raw. The characteristics of both +bound and raw stream blocks can be configured using STC Ansible in `create` and `config` modes. + +A bound stream block is associated with specific source/destination endpoints (devices). +Use bound stream blocks when the test involves creating devices, such as hosts or routers, +and you want to use the addresses already specified in the stream blocks without having to configure them again. + +When you configure devices (`Emulated Device <../docs/EmulatedDevice.rst>`_, +`BGP Device <../docs/BGP.rst>`_), you can specify L2, L3 and L4 address/port, VLAN tags, MPLS labels and +other parameters for the devices. +When you create a bound stream block and identify the source and destination devices, Spirent TestCenter +uses the values configured for the devices to populate the frame headers. When you change device parameters, +such as the L2 or L3 address in a configuration that uses bound stream blocks, the stream blocks are +automatically updated with the change. If the values are negotiated dynamically, such as through ARP/ND, +DHCP or MPLS label negotiation, the appropriate header fields are automatically updated for a bound stream block. + +When defining a raw stream block, you specify header information, such as source/destination addresses, +at the time you configure the stream block instead of associating the block with a device. + +Use raw stream blocks when the test is focused specifically on traffic and does not include device behavior, +such as testing protocols (access, routing, multicast, etc.). + +Then, you can verify the traffic statistics (`Results <../docs/Results.rst>`_) between the +devices by starting the traffic. + +Create Stream Block +------------------- + +Purpose +~~~~~~~ + +Creates stream block object(s) in the Spirent Test Center(stc) datamodel under the project +or any created port object(s). +During the object creation, requires to configure it's characteristics like name, Source and destination +targets etc. +The name of the stream block object will be used as a reference in order to reconfigure/modify +any of it's properties later. + + +.. role:: mandatory + + +Synopsis +~~~~~~~~ + +.. note:: :mandatory:`M` indicates that the parameter is :mandatory:`Mandatory`. + + +.. parsed-literal:: + + - + name: create stream block + stc: + action: create :mandatory:`M` + under: :mandatory:`M` + count: + objects: + - :mandatory:`M` + + + . + . + +Parameters +~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstring +
Specifies the action for the given task. Here, it is create.
+
Required: Yes
+
underxpath +
A project or a port reference under which a stream block is created.
+
Required: Yes
+
Example:
+
under: /project
+ or +
under: ref:/Port[@Name='Port1']
+
See Also:
+ + +
NOTES:
+
1. Port must already exist.
+
count integer +
Specifies the number of stream blocks to be created.
+
Count value above 1, creates several stream block objects in an iterative way.
+
Use the keyword ${item} as a template in stream block object names. The item will be replace with the values from 1 to count.
+
Required: No. Optional field
+
objectsstring +
Specifies to identify stc objects and attributes.
+
To create stream block, use StreamBlock object.
+
Required: Yes.
+
See Also:
+
+ + + + + +Examples +~~~~~~~~ + + 1. Sample YAML code to create a stream block under project: + + .. code-block:: yaml + + - + name: Create a stream block + stc: + action: create + under: ref:/project + objects: + - streamblock: + Name: "sb1" + TrafficPattern: PAIR + EnableBidirectionalTraffic: True + EnableStreamOnlyGeneration: true + SrcBinding-targets: ref:/EmulatedDevice[@Name='Dev1']/Ipv4If + DstBinding-targets: ref:/EmulatedDevice[@Name='Dev2']/Ipv4If + AffiliationStreamBlockLoadProfile: + Load: 10 + + 2. Sample YAML code to create a stream block with mesh traffic under port: + + .. code-block:: yaml + + - + name: Create traffic between emulated device end points + stc: + action: create + under: ref:/Port[@Name='Port1'] + objects: + - streamblock: + Name: "sb1" + TrafficPattern: MESH + EnableBidirectionalTraffic: True + EnableStreamOnlyGeneration: true + SrcBinding-targets: ref:/EmulatedDevice[@Name='Dev1']/Ipv4If + DstBinding-targets: ref:/EmulatedDevice[@Name='Dev2']/Ipv4If + AffiliationStreamBlockLoadProfile: + Load: 10 + + 3. Sample YAML code to create a stream block with UDP header and it's modifiers: + + .. code-block:: yaml + + - + name: Create udp header under streamblock + stc: + action: create + under: /Port[@Name='Port1']/Streamblock[@Name='sb1'] + objects: + - "udp:Udp": + name: 'udp1' + sourcePort: '1024' + - RangeModifier: + name: 'rangemodifier 1' + OffsetReference: udp1.destPort + ModifierMode: INCR + data: '50000' + RecycleCount: 8000 + StepValue: 1 + Mask: 65535 + - TableModifier: + name: 'tablemodifier 1' + OffsetReference: udp1.sourcePort + data: '1025 1024' + + 4. To create a stream block with multiple source and destination target references, + need to use the ansible feature jinja2 templeting in yaml. + See `Templating jinja2 `_. + + .. code-block:: yaml + + - + name: Create a stream block with multiple source and destination targets + stc: + action: create + under: ref:/Port[@name='Port1'] + objects: + - streamblock: + TrafficPattern: PAIR + EnableBidirectionalTraffic: false + EnableStreamOnlyGeneration: true + SrcBinding-targets: ref:/EmulatedDevice[@tag='Port1Device']/Ipv4If + DstBinding-targets: |- + "{%- for x in range(0, 10) -%} + ref:/EmulatedDevice[@Name='Port2Dev1']/Ipv4If, + {%- endfor -%}" + AffiliationStreamBlockLoadProfile: + Load: 10 + +Configure Stream Block +---------------------- + +Purpose +~~~~~~~ + +Reconfigures/modifies an existing stream block and it's sub object properties. + +.. role:: mandatory + + +Synopsis +~~~~~~~~ + +.. parsed-literal:: + - + name: configure stream block + count: + stc: + action: config :mandatory:`M` + objects: :mandatory:`M` + properties: + + + . + . + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstringSpecifies the action for the given task. Here it is config. +
Required: Yes
+
count integer +
Specifies the number of stream blocks to be configured.
+
Count value above 1, creates several stream block objects in an iterative way.
+
Use the keyword ${item} as a template in stream block names. The item will be replace + with the values from 1 to count.
+
Required: No. Optional field
+
objectsxpath +
A stream block object under which the attributes are configured.
+
Required: Yes
+
Example:
+
object: /Port[@Name='Port1']/Streamblock[@Name='Streamblock1']
+ or +
object: /project/Streamblock[@Name='Streamblock1']
+
See Also:
+ +
NOTES:
+
1. Stream block must already exist.
+
2. If the stream block does not exist with the specified name, an exception will be raised and the playbook stops.
+
propertiesstring +
Specifies to identify the properties of stream block object.
+
Required: Yes
+
Example:
+
properties:
+
FrameLengthMode: "FIXED"
+
FixedFrameLength: 256
+
See Also:
+
+ + +Examples +~~~~~~~~ + + .. code-block:: yaml + + - + name: Configure a stream block + stc: + action: config + objects: ref:/Port[@Name='Port1']/Streamblock[@Name='Streamblock1'] + properties: + FrameLengthMode: "FIXED" + FixedFrameLength: 256 + AffiliationStreamBlockLoadProfile: + Load: 100 + +Start/Stop Traffic(Generator) +----------------------------- + +Purpose +~~~~~~~ + +Starts/stops the traffic generator. All the active stream blocks in the generator will be started. + + +Synopsis +~~~~~~~~ + +.. parsed-literal:: + + - + name: start devices + stc: + action: perform :mandatory:`M` + command: GeneratorStart/GeneratorStop :mandatory:`M` + properties: + GeneratorList: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstringSpecifies the action for the given task. Here it is perform. +
Required: Yes.
+
command string +
Specifies the command name to start/stop the traffic.
+
To start traffic, use GeneratorStartCommand
+
To stop traffic, use GeneratorStopCommand
+
Required: Yes.
+
propertiesstring +
Specifies the properties supported to perform generatorstart or generatorstop command. + Currently, supported property is "GeneratorList".
+
Required: No. Optional field.
+
See Also:
+
+ + +Examples +~~~~~~~~ + +.. code-block:: yaml + + # To start traffic on all stream blocks + - + name: start traffic + stc: + action: perform + command: GeneratorStart + + # To start a specific generator + - + name: start traffic + stc: + action: perform + command: GeneratorStart + properties: + GeneratorList: ref:/project + +.. code-block:: yaml + + # To stop traffic on all stream blocks + - + name: stop traffic + stc: + action: perform + command: GeneratorStop + + # To stop a specific generator + - + name: stop traffic + stc: + action: perform + command: GeneratorStop + properties: + GeneratorList: ref:/project \ No newline at end of file diff --git a/docs/System.rst b/docs/System.rst new file mode 100644 index 0000000..df4768c --- /dev/null +++ b/docs/System.rst @@ -0,0 +1,172 @@ +System +====== + +.. contents:: + :local: + :depth: 1 + +Overview +-------- + +After creating a session, STC ansible allows to configure License Server host details which +requires to reserve Spirent TestCenter virtual ports. + +Also, if declaring your own data model is too complex, you can import/load an +existing XML data model. +You must first copy the data model to the STC Lab Server before you are able to import/load it. + +Configure License Server +------------------------ + +Purpose +~~~~~~~ + +Configures the License server (virtual controller) that hosts port and feature license files. +License servers are only required when reserving Spirent TestCenter virtual ports. + + +.. role:: mandatory + + +Synopsis +~~~~~~~~ + +.. note:: :mandatory:`M` indicates that the parameter is :mandatory:`Mandatory`. + + +.. parsed-literal:: + + - + name: Configure the lab server license manager + stc: + action: create :mandatory:`M` + under: /system/LicenseServerManager :mandatory:`M` + objects: + - LicenseServer: :mandatory:`M` + : + +Parameters +~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstring +
Specifies the action for the given task. Here, it is create.
+
Required: Yes
+
underxpath +
A licenseserver manager path which is automatically created object of a test hierarchy.
+
Required: Yes
+
Example:
+
under: /system/LicenseServerManager
+
See Also:
+ + +
NOTES:
+
1. Session must already exist.
+
objectsstring +
Specifies to identify stc objects and attributes.
+
To configure license server properties, use LicenseServer object.
+
Required: Yes.
+
Example:
+
objects:
+
- LicenseServer:
+
Server: 127.0.0.1
+
See Also:
+
+ + + + + +Examples +~~~~~~~~ + + Sample YAML code to configure primary and backup License servers: + + .. code-block:: yaml + + - + name: Configure the lab server license manager + stc: + action: create + under: /system/LicenseServerManager + objects: + - LicenseServer: + Server: 10.66.240.120 + BackupServer: 10.66.240.130 + Name: LicenceServer + + +Load Data Module +---------------- + +To copy an existing XML data model to the STC Lab Server, use the following YAML code +by providing source and destination paths. + + + .. code-block:: yaml + + - + name: Copy the data model + copy: + src: asset/datamodel.xml + dest: /tmp/datamodel.xml + +Load/import the XML datamodel to the STC Lab Server, use the following YAML task by specifying +the action as `load` and datamodel path. + + + .. code-block:: yaml + + + - name: Load a data model + stc: + action: load + datamodel: /tmp/datamodel.xml + + + diff --git a/docs/Tags.rst b/docs/Tags.rst new file mode 100644 index 0000000..5a0ba6a --- /dev/null +++ b/docs/Tags.rst @@ -0,0 +1,82 @@ +Tags +==== + +.. contents:: + :local: + :depth: 1 + +Overview +-------- + +Use tags to achieve scalability in large tests by organizing and viewing subsets of objects +within a test configuration. + +When creating Ports, Emulated Device or Stream blocks, the "tag" can be identified. +Multiple tags are separated by SPACE in Ansible. Thus, SPACE is not allowed to define +one single tag. Otherwise, it will be treated as multiple tags. + + +Tag Ports +--------- + +The example below is given by tagging each port with "Server, myPortTag-0" and "Server, myPortTag-1". + + .. code-block:: yaml + + - + name: Create the ports + stc: + action: create + count: 2 + objects: + - project: + - port: + location: ${ports[item]} + name: ${names[item]} + tag: "Server myPortTag-$item" + +Tag Emulated Devices +-------------------- + +The example below is given by tagging each Emulated Device with "devTagDhcp, devtag-0" and "devTagDhcp, devtag-1". + + .. code-block:: yaml + + - + name: create 2 block of 5 devices + stc: + action: perform + command: DeviceCreate + properties: + ParentList: ref:/project + CreateCount: 2 + DeviceCount: 5 + Port: ref:/port[@name='Port1'] + IfStack: Ipv4If PppIf PppoeIf EthIIIf + IfCount: '1 1 1 1' + name: "dev-$item" + tag: "devTagDhcp devtag-$item" + + +Tag Stream blocks +----------------- + +The example below is given by tagging each stream block with "traffMesh, traff-0" and "traffMesh, traff-1". + + .. code-block:: yaml + + - + name: Configure the traffic generator + stc: + count: 2 + action: create + under: ref:/project + objects: + - StreamBlock: + tag: "traffMesh traff-$item" + EnableStreamOnlyGeneration: true + TrafficPattern: MESH + SrcBinding-targets: ref:/EmulatedDevice[@name='dev-$item']/Ipv4If + DstBinding-targets: ref:/EmulatedDevice[@name!='dev-$item']/Ipv4If + AffiliationStreamBlockLoadProfile: + Load: 100 \ No newline at end of file diff --git a/docs/VXLAN.rst b/docs/VXLAN.rst new file mode 100644 index 0000000..a98c02a --- /dev/null +++ b/docs/VXLAN.rst @@ -0,0 +1,795 @@ +Switching Protocol - VXLAN +========================== + +.. contents:: + :local: + :depth: 1 + +Overview +-------- + +`STC-ansible` allows you to create Virtual eXtensible Local Area Network (VXLAN) emulated devices. + +VXLAN encapsulates MAC frames in a UDP header to create a Layer 2 connection across an IP network +between two vSphere hypervisor hosts. These hosts are known as Virtual Tunnel Endpoints (VTEPs) and +perform the encapsulation/decapsulation function for the tunnel. VXLAN uses IP multicast to associate +a VM MAC address with a VTEP IP address. + +`STC ansible` helps to construct VTEPs, VMs, and traffic for a VXLAN test. + +Please refer example playbooks vxlan-bgp-evpn-config.yaml in +`Github `_ link. + + +Create VTEP Device +------------------ + +Purpose +~~~~~~~ + +Creates VXLAN Tunnel End Point (VTEP) object(s) in the Spirent Test Center(stc) datamodel under the emulated device object(s). +During the object creation, Name and other VTEP properties can be defined. +The name of the VTEP object will be used as a reference in order to reconfigure/modify +any of it's properties later. + +.. role:: mandatory + + +Synopsis +~~~~~~~~ + +.. note:: :mandatory:`M` indicates that the parameter is :mandatory:`Mandatory`. + +.. parsed-literal:: + - + name: create VTEP device + stc: + action: create :mandatory:`M` + under: :mandatory:`M` + count: + objects: + - :mandatory:`M` + + + . + . + +Parameters +~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstring +
Specifies the action for the given task. Here, it is create.
+
Required: Yes
+
underxpath +
An emulated device under which the VTEP is created.
+
Required: Yes
+
Example:
+
under: /EmulatedDevice[@Name=’Device1’]
+
See Also:
+ + +
NOTES:
+
1. EmulatedDevice must already exist.
+
2. If the device does not exist with the specified name, an exception will be raised and the playbook stops.
+
count integer +
Specifies the number of VTEP's to be created.
+
Count value above 1, creates several VTEP objects in an iterative way.
+
Use the keyword ${item} as a template in device names. The item will be replace with the values from 1 to count.
+
Required: No. Optional field
+
objectsstring +
Specifies to identify stc objects and attributes.
+
To create VTEP, use VxlanVtepConfig object.
+
Required: Yes.
+
See Also:
+
+ + + + + +Examples +~~~~~~~~ + +.. code-block:: yaml + + - + name: Create Vxlan VTEP config 1 + stc: + action: create + under: ref:/project/Emulateddevice[@Name='VTEP Device'] + count: 1 + objects: + - VxlanVtepConfig: + Name: "VxlanVtep_1" + AutoSelectUdpSrcPort: "true" + MulticastType: MULTICAST_IGMP + UdpChecksumEnabled: "false" + UsesIf-targets: ref:/project/Emulateddevice[@Name='VTEP Device']/Ipv4If[0] + + - + name: Create multiple Vxlan VTEP's + stc: + action: create + under: ref:/project/Emulateddevice[@Name='VTEP Device${item}'] + count: 10 + objects: + - VxlanVtepConfig: + Name: "VxlanVtep_${item}" + AutoSelectUdpSrcPort: "true" + MulticastType: MULTICAST_IGMP + UdpChecksumEnabled: "false" + UsesIf-targets: ref:/project/Emulateddevice[@Name='VTEP Device${item}']/Ipv4If[0] + + +Create Vxlan Interface +---------------------- + +Purpose +~~~~~~~ + +Creates Vxlan interface on VTEP enabled Emulated device object(s). + +.. role:: mandatory + + +Synopsis +~~~~~~~~ + +.. note:: :mandatory:`M` indicates that the parameter is :mandatory:`Mandatory`. + +.. parsed-literal:: + - + name: create Vxlanif + stc: + action: create :mandatory:`M` + under: :mandatory:`M` + count: + objects: + - :mandatory:`M` + + + . + . + +Parameters +~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstring +
Specifies the action for the given task. Here, it is create.
+
Required: Yes
+
underxpath +
An emulated device under which the Vxlan interface object is created.
+
Required: Yes
+
Example:
+
under: /EmulatedDevice[@Name=’Device1’]
+
See Also:
+ + +
NOTES:
+
1. A VTEP enabled EmulatedDevice must already exist.
+
2. If the device does not exist with the specified name, an exception will be raised and the playbook stops.
+
count integer +
Specifies the number of Vxlan interface objects to be created.
+
Count value above 1, creates several VxlanIf objects in an iterative way.
+
Use the keyword ${item} as a template in device names. The item will be replace with the values from 1 to count.
+
Required: No. Optional field
+
objectsstring +
Specifies to identify stc objects and attributes.
+
To create Vxlan interface, use VxlanIf object.
+
Required: Yes.
+
See Also:
+
+ + + + + +Examples +~~~~~~~~ + +.. code-block:: yaml + + - + name: Create Vxlanif + stc: + action: create + under: ref:/Emulateddevice[@Name='VTEP 1'] + count: 1 + objects: + - VxlanIf: + StackedOnEndpoint-targets: ref:/project/Emulateddevice[@Name='VTEP 1']/Ipv4If[0] + + +Create VXLAN Segment +-------------------- + +Purpose +~~~~~~~ + +Creates VXLAN Segment object(s) under the project object. + +.. role:: mandatory + + +Synopsis +~~~~~~~~ + +.. note:: :mandatory:`M` indicates that the parameter is :mandatory:`Mandatory`. + +.. parsed-literal:: + - + name: Create VXLAN Segment + stc: + action: create :mandatory:`M` + under: :mandatory:`M` + count: + objects: + - :mandatory:`M` + + + . + . + +Parameters +~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstring +
Specifies the action for the given task. Here, it is create.
+
Required: Yes
+
underxpath +
Project reference under which the Vxlan Segment object is created.
+
Required: Yes
+
Example:
+
under: /project
+
See Also:
+ +
NOTES:
+
1. If the reference path does not exist with the specified name, an exception will be raised and the playbook stops.
+
count integer +
Specifies the number of Vxlan Segment objects to be created.
+
Count value above 1, creates several Vxlan segment objects in an iterative way.
+
Use the keyword ${item} as a template in device names. The item will be replace with the values from 1 to count.
+
Required: No. Optional field
+
objectsstring +
Specifies to identify stc objects and attributes.
+
To create Vxlan segments, use VxlanSegmentConfig object.
+
Required: Yes.
+
See Also:
+
+ + + + + +Examples +~~~~~~~~ + +.. code-block:: yaml + + - + name: Create Vxlan Segment + stc: + action: create + under: ref:/project + count: 1 + objects: + - VxlanSegmentConfig: + Name: "Segment_1" + CommunicationType: EVPN_LEARNING + Vni: 100 + + + - + name: Create multiple Vxlan Segments + stc: + action: create + under: ref:/project + count: 10 + objects: + - VxlanSegmentConfig: + Name: "Segment_${item}" + CommunicationType: EVPN_LEARNING + Vni: 10${item} + + +Create VXLAN VM Info +-------------------- + +Purpose +~~~~~~~ + +Creates VXLAN VM configuration object(s) under the project object. + +.. role:: mandatory + + +Synopsis +~~~~~~~~ + +.. note:: :mandatory:`M` indicates that the parameter is :mandatory:`Mandatory`. + +.. parsed-literal:: + - + name: Create VXLAN VM config + stc: + action: create :mandatory:`M` + under: :mandatory:`M` + count: + objects: + - :mandatory:`M` + + + . + . + +Parameters +~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstring +
Specifies the action for the given task. Here, it is create.
+
Required: Yes
+
underxpath +
Project reference under which the Vxlan VM config object is created.
+
Required: Yes
+
Example:
+
under: /project
+
See Also:
+ +
NOTES:
+
1. If the reference path does not exist with the specified name, an exception will be raised and the playbook stops.
+
count integer +
Specifies the number of Vxlan VM configuration objects to be created.
+
Count value above 1, creates several Vxlan VM configuration objects in an iterative way.
+
Use the keyword ${item} as a template in device names. The item will be replace with the values from 1 to count.
+
Required: No. Optional field
+
objectsstring +
Specifies to identify stc objects and attributes.
+
To create Vxlan VM configuration, use VxlanVMInfo object.
+
Required: Yes.
+
See Also:
+
+ + + + + +Examples +~~~~~~~~ + +.. code-block:: yaml + + - + name: Create Vxlan VMinfo + stc: + action: create + under: ref:/project + count: 1 + objects: + - VxlanVmInfo: + Name: "VM_info_1" + UseAttachedVtepIpAddr: "false" + + +Config VXLAN VM Info +-------------------- + +Purpose +~~~~~~~ + +Configures an existing VXLAN VM Info objects properties and the mapping of +VXLAN Segments to the VM Info objects. + +.. role:: mandatory + + +Synopsis +~~~~~~~~ + +.. parsed-literal:: + - + name: configure VM Info + count: + stc: + action: config :mandatory:`M` + object: :mandatory:`M` + properties: :mandatory:`M` + + + . + . + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue TypeDescription
actionstringSpecifies the action for the given task. Here it is config. +
Required: Yes
+
count integer +
Specifies the number of VXLAN VM Info objects to be configured.
+
Count value above 1, creates several VXLAN VM Info objects in an iterative way.
+
Use the keyword ${item} as a template in device names. The item will be replace + with the values from 1 to count.
+
Required: No. Optional field
+
objectxpath +
A VXLAN VM Info object under which the attributes are configured.
+
Required: Yes
+
Example:
+
object: /project/VxlanVmInfo[@Name='VM_info_1']
+
See Also:
+ +
NOTES:
+
1. VXLAN VM Info object must already exist.
+
2. If the device does not exist with the specified name, an exception will be raised and the playbook stops.
+
propertiesstring +
Specifies to identify the properties of VXLAN VM Info object object.
+
Required: Yes
+
For VXLAN VM Info object attributes and possible relations, please refer
+ +Examples +~~~~~~~~ + +1. To map VXLAN Seqments with VXLAN VM Info objects, + +.. code-block:: yaml + + - + name: Config VM info 1 + stc: + action: config + objects: ref:/project/VxlanVmInfo[@Name='VM_info_1'] + properties: + MemberOfVxlanSegment-Sources: ref:/project/VxlanSegmentConfig[@Name='Segment_1'] + + +2. To configures other properties, + +.. code-block:: yaml + + - + name: Config VM info 1 + stc: + action: config + objects: ref:/project/VxlanVmInfo[@Name='VM_info_1'] + properties: + UseAttachedVtepIpAddr: FALSE + UseL3VniForTraffic: FALSE + + +Config VM device +---------------- + +Purpose +~~~~~~~ + +Configures VM host with required mappings. + +1. Map VM device (An emulated device must already be created) with Vxlan VM configuration. + + +.. code-block:: yaml + + - + name: Config host1 + stc: + action: config + objects: ref:/project/EmulatedDevice[@Name='VM 1'] + properties: + UsesVxlanVmInfo-targets: ref:/project/VxlanVmInfo[@Name='VM_info_1'] + +2. Create "VXLAN VM to VTEP Device Link" between VTEP and VM devices and configure link source + and destination interfaces. + +.. code-block:: yaml + + - + name: Create Link + stc: + action: perform + command: LinkCreate + properties: + SrcDev: ref:/project/EmulatedDevice[@Name='VM Device 1'] + DstDev: ref:/project/Emulateddevice[@Name='VTEP Device 1'] + LinkType: "VXLAN VM to VTEP Device Link" + + - + name: Config host1 + stc: + action: config + objects: ref:/project/EmulatedDevice[@Name='VM Device 1'] + properties: + ContainedLink-targets: ref:/project/EmulatedDevice[@Name='VM Device 1']/vxlanvmtovteplink + + - + name: Config host1 + stc: + action: config + objects: ref:/project/EmulatedDevice[@Name='VM Device 1']/vxlanvmtovteplink + properties: + LinkSrc-targets: ref:/EmulatedDevice[@Name='VM Device 1']/EthIIIf[0] + LinkDst-targets: ref:/EmulatedDevice[@Name='VTEP Device 1']/VxlanIf[0] + +Enable Routing Protocol on VTEP Device +-------------------------------------- + +To enable routing protocols like BGP on the VTEP device, need to create protocol objects under +the VTEP enabled emulated device(s). + +Example to enable BGP on VTEP device, + +.. code-block:: yaml + + - + name: Enable BGP on VTEP Device 1 + stc: + action: create + under: ref:/EmulatedDevice[@Name='VTEP Device 1'] + count: 1 + objects: + - BgpRouterConfig: + IpVersion: IPV4 + AsNum: 1 + DutAsNum: 1 + name: "BGPRouter1" + + +Configure VXLAN Traffic +----------------------- + +Purpose +~~~~~~~ + +Configures the traffic between the VXLAN VM devices. +About creating a bound streamblock, please refer `StreamBlock <../docs/StreamBlock.rst>`_ section and +`Start Protocols <../docs/Start_Protocols.rst>`_, `Results <../docs/Results.rst>`_ sections to +start devices and get TX(transmitted)/RX(received) counter values. + +Examples +~~~~~~~~ + +.. code-block:: yaml + + # To configure traffic between VM Devices + - + name: Configure the traffic generator1 + stc: + count: 1 + action: create + under: /project + objects: + - StreamBlock: + EnableStreamOnlyGeneration: true + SrcBinding-targets: ref:/EmulatedDevice[@Name='VM Device 1']/Ipv4If + DstBinding-targets: ref:/EmulatedDevice[@Name='VM Device 2']/Ipv4If + AffiliationStreamBlockLoadProfile: + Load: 10 + diff --git a/docs/_static/images/design.png b/docs/_static/images/design.png new file mode 100644 index 0000000..df8db98 Binary files /dev/null and b/docs/_static/images/design.png differ