SONiC Management API Wiki

January 21, 2025 ยท View on GitHub

There are many ways to communicate and interact with the PTF container and the DUT from the localhost. This wiki serves as a place to document these API calls. Below is a list of some of the many API calls.

localhost, ptfhost and sonichost objects can use the ansible modules. Many may not provide meaningful output if ptfhost is used (like reduce_and_add_sonic_images).

# These arguments are examples of the pre-configured function arguments

def test_fun(duthosts, rand_one_dut_hostname, ptfhost):
    duthost = duthosts[rand_one_dut_hostname]

    # example dut api call
    duthost.get_extended_minigraph_facts()

    # example ptf api call
    ptfhost.shell("ls")

Ansible Modules

  • acl_facts - Retrieves ACL information from remote host.

  • announce_routes - Announces Routes to the exabgp processes running in the PTF container

  • bgp_facts - Retreives BGP information using Quagga

  • bgp_route - Provides BGP routing info from Quagga using VTYSH cli.

  • command - Used to run commands via shell on remote host.

  • config_facts - Retreives configuration facts for a device

  • conn_graph_facts - Retreives info on lab fannout siwtches and vlan connections.

  • console_facts - Retrieves console feature and status information using Quagga.

  • copy - Used to copy local files to remote host.

  • exabgp - Start or stop exabgp instance with certain configurations

  • extract_log - Unrotate logs and extract information starting from a row with predefined string.

  • feature_facts - Provides the statuses for all active features on a host.

  • fetch - Copies file from remote host to local host.

  • file - Allows for setting attributes of file, symlinks, directories. Can be used to remove files.

  • find - Finds list of files based on specified criteria.

  • get_ip_in_range - Get certain number of ips within a prefix

  • image_facts - Get information on image from remote host.

  • interface_facts - Retrieves information on device interfaces.

  • lag_facts - Retrieve Ling Aggregation Group information from a device.

  • lldpctl_facts - Gathers LLDP facts from the SONiC device.

  • lldp_facts - Retrieve LLDP facts using SNMP

  • minigraph_facts - Retrieve minigraph facts for a device.

  • monit_process - Retrieve process cpu and memory usage

  • ping - Pings the remote host

  • port_alias - Find port-alias mapping if there is any configured.

  • reduce_and_add_sonic_images - Removes excess sonic images and installs a new image if requested.

  • replace - Replaces all instances of a pattern within a specified file. When using this method make sure that the pattern being used to match does not match the replacement text, otherwise the results may be undesirable.

  • sensors_facts - Retrieves sensor facts for a device.

  • service - Controls services on the dut.

  • setup - Gather facts about the duthost.

  • shell - Runs commands on the remote host.

  • shell_cmds - Allows you to run mutliple commands on a remote host.

  • show_interface - Retrieves status and counter values from DUT.

  • show_ip_interface - Retrieve ipv4 address of interface and ipv4 address for corresponding neighbor

  • snmp_facts - Retreives facts for device using SNMP

  • sonic_pfc_counters - Get or clear PFC counter for a device

  • stat - Retrieves facts on specified file.

  • switch_arptable - Reterives ARP table from the SONiC switch

  • switch_capabilities_facts - Retreive switch capability information.

  • sysfs_facts - Get sysfs information from switch

  • tempfile - Generates temp file or directory on remote host.

Sonichost Methods

Multi ASIC Methods

  • asics - Get list of ASIC hosts

  • asic_instance - Retrieves the asic instance given an asic id. Device must be multi-ASIC

  • asic_instance_from_namespace - Provides ASIC instance given a corresponding namespace.

  • critical_services_tracking_list - Gets the list of services running on the DUT.

  • delete_container - Deletes container on sonichost if container's associated service is a default service. Otherwise, container is deleted on each ASIC.

  • get_asic_ids - Provides all ASIC indexes for the ASICs on the Multi-ASIC device.

  • get_asic_id_from_namespace - Returns numeric ID for ASIC given a namespace. This command only works if the dut is a multi-asic device.

  • get_asic_index_for_portchannel - Gets asic index associated with provided portchannel.

  • get_asic_namespace_list - Provides list of namspaces corresponding to ASICs on the duthost. The dut must be a multi-ASIC device for this method to work.

  • get_asic_or_sonic_host - Returns ASIC instance provided a corresponding ASIC instance id.

  • get_asic_or_sonic_host_from_namespace - Returns corresponding sonichost instance if arg namespace is not specified, or corresponding ASIC instance if arg namespace is specified.

  • get_backend_asic_ids - Provides list of ASIC indexes corresponding to ASICs on the Multi-ASIC device.

  • get_backend_asic_namespace_list - Provides list of namespaces for each ASIC on the Multi-ASIC device.

  • get_default_critical_services_list - Provides the default list of critical services for Multi-ASIC device.

  • get_frontend_asic_ids - Provides a list of ASIC indexes representing the ASICs on the device.

  • get_frontend_asic_namespace_list - Provides list of all namespaces corresponding to ASICs on Multi-ASIC device.

  • get_linux_ip_cmd_for_namespace - Specifies a linux ip command for the provided namespace.

  • get_namespace_from_asic_id - Gets the namespace provided an ASIC ID. This only works on multi-ASIC devices.

  • get_port_asic_instance - Returns the numeric ASIC instance that a provided port belongs to. Will fail test if ASIC instance is not found for provided port.

  • get_queue_oid - Get the queue OID of given port and queue number.

  • get_queue_oid_asic_instance - Returns the ASIC instance which has the queue OID saved.

  • get_route - Retreives BGP routes on a provided an ip prefix that the route must match.

  • get_sonic_host_and_frontend_asic_instance - Returns sonic host and all frontend asic instances. Only works on multi-asic devices

  • get_vtysh_cmd_for_namespace - Provides modified VTYSH command provided ASIC namespace and command.

  • has_config_subcommand - Check if a config or show subcommand exists on the remote host. WARNING: to test whether it exists, the method will run the command. Ensure that there will be no negative sid-effects of having this command run on the remote host.

  • is_bgp_state_idle - Checks if all BGP peers are in IDLE state on the sonichost.

  • is_container_running - Returns whether or not a container is running on sonichost if the container's associated service is a default service. Otherwise, it returns whether or not the container is running on any ASIC.

  • is_service_running - Checks if a specified service is running. Can be a service within a docker.

  • restart_service - Restarts a service on the sonichost if the service is a default service. Otherwise service is restarted on each ASIC.

  • start_service - Starts service on sonichost if service is a default service. Otherwise service is started on each ASIC.

  • stop_service - Stops a service on the sonichost if service is a default service. Otherwise serviec is stopped on all ASICs.

Sonic ASIC Methods

  • bgp_drop_rule - Programs iptable rule to either add or remove DROP for BGP control frames

  • bgp_facts - Provides BGP facts for current ASIC.

  • check_bgp_statistic - Checks that the BGP statistic matches some expected value.

  • check_bgp_session_state - Check whether the state of the bgp session matches a specified state for a list of bgp neighbors for the current ASIC.

  • command - Runs commands specified for the ASIC calling the method.

  • config_facts - Current config facts for ASIC.

  • config_ip_intf - Allows for addition or removal of ip addresses to existing interfaces on the ASIC instance.

  • config_portchannel - Creates or removes a portchannel on the ASIC instance

  • config_portchannel_member - Adds or removes portchannel member for a specified portchannel on the ASIC instance.

  • create_ssh_tunnel_sai_rpc - Create ssh tunnel between host and ASIC namespace on syncd RPC port.

  • delete_container - Deletes a ASIC specific docker.

  • get_active_ip_interfaces - Provides a information on active IP interfaces. Works on ASIC devices.

  • get_asic_namespace - Provides namespace for ASIC.

  • get_bgp_statistic - Get the value corresponding to a named statistic for BGP.

  • get_critical_services - Gets the critical services for the ASIC.

  • get_docker_cmd - Provides modified command to be run on a specific docker container given an initail command and the name of the desired container.

  • get_docker_name - Gets ASIC specific name for docker container.

  • get_extended_minigraph_facts - Gets detailed facts on configured minigraph.

  • get_ip_route_info - Returns route information for a destionation. The destination could an ip address or ip prefix.

  • get_portchannels_and_members_in_ns - Finds a portchannel present on ASIC interface's namspace and returns its name and members.

  • get_queue_oid - Get the queue OID of given port and queue number.

  • get_service_name - Provides ASIC specific service name.

  • interface_facts - Gets information about interfaces associated with the ASIC calling the method.

  • is_backend_portchannel - Checks whether specified portchannel is a backend portchannel.

  • is_container_running - Returns whether or not a specified ASIC specific container is running.

  • is_it_backend - Checks whether the ASIC is a backend node

  • is_it_frontend - Checks whether ASIC is a frontend node.

  • is_service_running - Checks if a specified service is running. Can be a service within a docker.

  • os_version - Provides the SONiC OS version for the sonichost associated with the calling ASIC

  • ping_v4 - Pings specified ipv4 address via ASIC.

  • portchannel_on_asic - CHecks whether a specified portchannel is configured on ASIC instance

  • port_exists - Checks whether a provided port exists in the ASIC instance calling the method.

  • port_on_asic - Checks if provided port is configured on ASIC instance

  • remove_ssh_tunnel_sai_rpc - Removes any ssh tunnels if present created for syncd RPC communication

  • reset_service - Resets an ASIC service on the corresponding docker.

  • restart_service - Restarts an ASIC service on the corresponding docker.

  • run_redis_cli_cmd - Runs redist cmd through redis CLI for ASIC that calls method.

  • run_redis_cmd - Runs a redis command on the DUT.

  • shell - Runs a shell command via the sonichost associated with the ASIC instance calling the method.

  • show_interface - Show status and counter values for a given interface on the ASIC.

  • show_ip_interface - Retrieve ipv4 address for interface and ipv4 address for corresponding neighbor

  • shutdown_interface - Shuts down interface specified for the ASIC instance calling the method.

  • startup_interface - Starts up interface specified for ASIC instance calling the method.

  • start_service - Starts an ASIC service on its corresponding ASIC docker.

  • stop_service - Stops a specified ASIC service on the corresponding docker

  • switch_arptable - Gets ARP table information from sonichost device specified for ASIC instance calling the method.

Ptfhost Methods

Preconfigured Function Arguments

  • duthosts - Provides a dictionary that maps DUT hostnames to DUT instances

  • localhost - The localhost instance. Used to run ansible modules from the localhost.

  • ptfhost - The PTF container host instance. Used to run ptf methods and anisble modules from the PTF.

  • rand_one_dut_hostname - A random hostname belonging to one of the DUT instances defined by the deployed testbed.