Skip to content

Latest commit

 

History

History
461 lines (234 loc) · 27.2 KB

README.md

File metadata and controls

461 lines (234 loc) · 27.2 KB
Raw

SONiC Management API Wiki

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.