IxNetwork Python Client

Common errors

• ixnetwork_restpy.errors.ConnectionError: Unable to connect to <IP_ADDRESS>. Check the ip address and consider using the rest_port parameter.

  cause The Python client failed to establish a connection to the specified IxNetwork API server. This can be due to an incorrect IP address, an inaccessible or incorrect REST API port, the IxNetwork API server not running, or a firewall blocking the connection.
  fix Verify that the `IpAddress` and `RestPort` (if explicitly provided) are correct. Ensure the IxNetwork API server (Windows GUI, Connection Manager, or Linux API Server) is running and accessible from the machine running the script. Check firewall settings on both client and server.

• ixnetwork_restpy.errors.BadRequestError: ... /vport/protocols => 400 Bad Request

  cause This error typically indicates that an API call (often `add()` for a child object) was made with invalid parameters or when the parent object is not in a suitable state to accept the operation. For example, adding a protocol before the virtual port is fully configured or assigned.
  fix Review the parameters being passed to the method causing the `BadRequestError`. Ensure that all parent objects are properly configured and committed before attempting to add child objects like protocols. Consult the specific IxNetwork API documentation for required attributes and prerequisites.

• Only getting one 'Traffic Item Statistics' when I have multiple traffic items.

  cause When using `StatViewAssistant`, the default retrieval or display might only show a summary or the first matched traffic item if not explicitly filtered or iterated to gather all relevant statistics.
  fix Utilize the filtering capabilities of `StatViewAssistant` to target specific traffic items by name or other properties. Alternatively, iterate through the rows of the statistics view to extract data for each individual traffic item, as demonstrated in samples using `StatViewAssistant`'s methods.

Warnings

• breaking Introduction of `slots` support in version 1.0.41 (September 2019) causes `AttributeError` when accessing non-existent properties.
  Fix: Review existing scripts and update property access to match the official API. Use `help()` on objects or consult online documentation to verify valid properties.
• gotcha IxNetwork saved configuration files (`.ixncfg`) are generally forward-compatible but not backward-compatible. A configuration saved with a newer IxNetwork server version will not load on an older server version.
  Fix: Always use a configuration file saved with a version of IxNetwork that is equal to or older than the target IxNetwork API server version.
• deprecated The older `IxNetRestApi` library is deprecated in favor of `ixnetwork-restpy`. The `IxNetRestApi` is no longer maintained, and new features/enhancements will not be added to it.
  Fix: Migrate any scripts using `IxNetRestApi` to `ixnetwork-restpy` for continued support and access to new features.

Install

• pip install --upgrade ixnetwork-restpy Install or Upgrade

Imports

• SessionAssistant

  from ixnetwork_restpy import SessionAssistant

  SessionAssistant is the recommended entry point for general scripting, providing simplified session management and access to the IxNetwork object.
• TestPlatform
  wrong:

  from ixnetwork_restpy import TestPlatform

  correct:

  from ixnetwork_restpy.testplatform.testplatform import TestPlatform

  While functional, SessionAssistant is generally preferred for its consolidated features. If using TestPlatform, ensure to import from the full path `ixnetwork_restpy.testplatform.testplatform`. Older examples might show a direct import that is now incorrect.

Quickstart

This quickstart demonstrates how to connect to an IxNetwork API server, authenticate, map physical ports, create a basic traffic item, start/stop traffic, and retrieve statistics. Replace '10.0.0.1' with your IxNetwork chassis IP, and ensure the `IXNET_SERVER_IP`, `IXNET_USERNAME`, and `IXNET_PASSWORD` environment variables are set or updated in the script. It uses `SessionAssistant` for simplified workflow and `PortMapAssistant` for port management.

import os
from ixnetwork_restpy import SessionAssistant, Files

# Configure connection parameters
IXNETWORK_API_SERVER_IP = os.environ.get('IXNET_SERVER_IP', '127.0.0.1')
IXNETWORK_USERNAME = os.environ.get('IXNET_USERNAME', 'admin')
IXNETWORK_PASSWORD = os.environ.get('IXNET_PASSWORD', 'admin')

# Create a session and connect to IxNetwork
try:
    session_assistant = SessionAssistant(
        IpAddress=IXNETWORK_API_SERVER_IP,
        UserName=IXNETWORK_USERNAME,
        Password=IXNETWORK_PASSWORD,
        ClearConfig=True, # Clears any existing configuration on the server
        LogLevel=SessionAssistant.LOGLEVEL_INFO
    )
    ixnetwork = session_assistant.Ixnetwork
    print(f"Connected to IxNetwork API Server at {IXNETWORK_API_SERVER_IP}")

    # Example: Create a simple configuration (e.g., two ports, basic traffic)
    # These IPs and ports must match your physical setup
    port_map = session_assistant.PortMapAssistant()
    port_map.Map('10.0.0.1', 1, 1, Name='TxPort') # Chassis IP, Card ID, Port ID
    port_map.Map('10.0.0.1', 1, 2, Name='RxPort') # Chassis IP, Card ID, Port ID
    port_map.Connect(ForceOwnership=True)
    print("Ports mapped and connected.")

    # Add a traffic item
    traffic_item = ixnetwork.Traffic.TrafficItem.add(Name='Simple Traffic', TrafficType='raw')
    traffic_item.EndpointSet.add(
        Sources=ixnetwork.Vport.find(Name='^TxPort$').Protocols.find(),
        Destinations=ixnetwork.Vport.find(Name='^RxPort$').Protocols.find()
    )
    traffic_config = traffic_item.ConfigElement.find()
    traffic_config.FrameRate.update(Type='percentLineRate', Rate='10')
    traffic_config.TransmissionControl.update(Type='continuous')
    print("Traffic item configured.")

    # Apply and start traffic
    ixnetwork.Traffic.Apply()
    ixnetwork.Traffic.StartStatelessTrafficBlocking()
    print("Traffic started. Waiting for stats...")

    # Get and print statistics
    port_stats = session_assistant.StatViewAssistant('Port Statistics')
    traffic_item_stats = session_assistant.StatViewAssistant('Traffic Item Statistics')
    
    print("\n--- Port Statistics ---")
    print(port_stats)
    print("\n--- Traffic Item Statistics ---")
    print(traffic_item_stats)

    # Stop traffic and clear config
    ixnetwork.Traffic.StopStatelessTrafficBlocking()
    session_assistant.ClearConfig()
    print("Traffic stopped and configuration cleared.")

except Exception as e:
    print(f"An error occurred: {e}")
finally:
    if 'session_assistant' in locals() and session_assistant.Is</span>Connected:
        # Ensure the session is properly closed if it was opened
        session_assistant.Session.delete()
        print("Session deleted.")