Interfaces

Manage Profishark interfaces

The endpoints are applicable for IOTA Edge system only.

API

• Get all interfaces:

  • Path: /interfaces

  • Method: GET

  • Response:

    [
        {
            "pretty_mac": "aabbccddeeff",
            "interface":
            {
                "name": "IOTA-10G",
                "mac": "aa:bb:cc:dd:ee:ff",
                "device_type": 17,
                "capture_enabled": true,
                "physical_state":"idle"
            }
        }
    ]

    • pretty_mac is a special format of MAC address, which is used in any other request in this API; see const.html for more information
    • device_type is a numerical value, standing for the type of the device
    • if physical_state == error, all other requests except for /firmware/update are forbidden
• Get state of the interface

  • Path: /interfaces/{PRETTY_MAC}

  • Method: GET

  • response:

    {
        "device_type": 17,
        "link_up_port_a": true,
        "link_up_port_b": false,
        "available_firmware_versions": 
        [
            {
                "sw_version": "0.2.3",
                "hw_version": "2.2.7"
            }
        ],
        "capture_enabled": true,
        "physical_state": 
        {
            "state": "idle",
            "comment": "",
            "last_error_time": 47345243,
            "last_error": "could not enable capture"
        }
    }

    • all other requests to this interface are allowed if and only if physical_state.state == 'idle' && capture_enabled == false
    • possible values of physical_state.state:
      • idle
      • starting_capture
      • stopping_capture
      • changing - some of the interface’s parameters are being changed
      • restarting
      • updating
      • error - the interface is in error state, for example, bad firmware is installed
• Reset the interface
  • Path: /interfaces/{PRETTY_MAC}/reset
  • Method: POST
  • response: success or error message
• Change capture status of the interface

  • Path: /interfaces/{PRETTY_MAC}/capture

  • Method: POST

  • Request params: capture_status object

    {
        "capture_enabled": true
    }

  • response: success or error message + new capture_status object

• Toggle capture status of the interface
  • Path: /interfaces/{PRETTY_MAC}/capture/toggle
  • Method: POST
  • response: success or error message + capture_status object
• Get configuration of the interface

  • Path: /interfaces/{PRETTY_MAC}/configuration

  • Method: GET

  • response:

    {
        "transmit_crc_errors": true,
        "keep_crc32": true,
        "disable_port_a": true,
        "disable_port_b": true,
        "packet_slicing_bytes": 50,
        "inline_mode": true,
        "loopback": true,
        "timestamps_in_packets": true,
        "synchronized_timestamps": true,
        "autonegotiation_port_a": true,
        "autonegotiation_port_b": false,
        "firmware_mode": "1g"
    }

    • optional values (null is to be passed if value is not present):
      • inline_mode
      • loopback
      • firmware_mode
      • autonegotiation_port_a
      • autonegotiation_port_b
    • if packet_slicing_bytes == 0, it means, that slicing feature is disabled; minimum value is 60
    • inline_mode may only be changed if capabilities.span_mode == true
    • loopback may only be changed if capabilities.loopback == true
    • autonegotiation_port_a or autonegotiation_port_b may only be changed if capabilities.autoneg_10g_1g == true and configuration.firmware_mode == 1g
    • firmware_mode:
      • may only be changed if capabilities.multiple_hw == true
      • see const.html for possible values
• Change configuration of the interface
  • Path: /interfaces/{PRETTY_MAC}/configuration
  • Method: PUT
  • Request params: full configuration object
  • response: success or error message + new configuration object
  • note: also saves it to persistent memory along with port control
• Get dynamic configuration of the interface

  • Path: /interfaces/{PRETTY_MAC}/dynamic_configuration

  • Method: GET

  • response:

    {
        "capture_full_frames": true
    }

    • if capture_full_frames == true, the --full-frames flag will be passed to Profishark when starting capture
• Change dynamic configuration of the interface
  • Path: /interfaces/{PRETTY_MAC}/dynamic_configuration
  • Method: PUT
  • Request params: full dynamic_configuration object
  • response: success or error message + new dynamic_configuration object
• Get L2-L4 filter of the interface

  • Path: /interfaces/{PRETTY_MAC}/filter

  • Method: GET

  • response:

    {
      "mac": "AA:BB:CC:*:EE:FF",
      "ip_src": "1.1.1.1",
      "ip_dst": "*.2.*.2",
      "port_dst": "333"
    }

    • fields constraints:
      • mac, ip and port fields are used to check against both SRC and DST fields of the packet, joined with OR
      • mac_src, mac_dst… fields are used to check against the corresponding field of the packet
      • mac and (mac_src or mac_dst) cannot appear together; the same is true for other filters
      • mac_src and mac_dst can appear together; only one of them is also possible; the same is true for other filters
    • mac and ip field families may also contain masked values:
      • mac examples:
        • aa:*:cc:dd:*:ff *:*:*:*:*:* are correct values
        • **:bb:cc:dd:ee:ff, aa:b*:cc:dd:*e:ff are incorrect values
      • ip version 4 examples:
        • 1.2.*.4, *.*.*.* are correct values
        • 192.1*.2.3, 1*2.1.2.3 are incorrect values
      • ip version 6 examples:
        • aabb:cc*:*dd::00, aabb:**::ff, **::** are correct values
        • *::*, *:c*d:a*:*d:*::00 are incorrect values
        • so, basically, each star represents one masked byte of IPv6 address (or two characters in string representation)
    • available only if capabilities.filtering == true
    • if the filter is disabled, empty JSON object is returned
• Change L2-L4 filter of the interface
  • Path: /interfaces/{PRETTY_MAC}/filter
  • Method: PUT
  • Request params: filter object
    • if one does not want to enable the filtering field, do not send it (for example, if only MAC filter is to be enabled, send only the relevant field)
    • if filter is to be disabled, empty object is to be sent
  • response: success or error message + new filter object
• Get port control configuration of the interface

  • Path: /interfaces/{PRETTY_MAC}/portcontrol

  • Method: GET

  • response:

    {
        "port_control_a": 
        {
            "gigabit_ethernet": true,
            "fast_ethernet_fd": true,
            "fast_ethernet_hd": true,
            "ethernet_fd": true,
            "ethernet_hd": true,
            "autonegotiation": false,
            "symmetric_pause": true,
            "asymmetric_pause": true,
            "prefer_master": true,
            "force_preferred_role": true
        },
        "port_control_b": 
        {
            "gigabit_ethernet": false,
            "fast_ethernet_fd": true,
            "fast_ethernet_hd": true,
            "ethernet_fd": true,
            "ethernet_hd": true,
            "autonegotiation": false,
            "symmetric_pause": true,
            "asymmetric_pause": true,
            "prefer_master": true,
            "force_preferred_role": true
        }
    }

  • verification conditions:

    • if autonegotiation is false, one and only one of the following shall be true:
      • fast_ethernet_fd
      • fast_ethernet_hd
      • ethernet_fd
      • ethernet_hd
    • if autonegotiation is false, gigabit_ethernet shall never be true
    • if configuration.inline_mode is true, port_control_b settings are ignored

  • available only if capabilities.port_control == true

• Change port control configuration of the interface
  • Path: /interfaces/{PRETTY_MAC}/portcontrol
  • Method: PUT
  • Request params: full portcontrol object
  • response: success or error message + new portcontrol object
  • note: also saves it to persistent memory along with overall configuration
  • available only if capabilities.port_control == true
• Get ports status information (available only for 1G devices):

  • Path: /interfaces/{PRETTY_MAC}/portsinfo

  • Method: GET

  • response:

    [
        {
            "label": "link_speed",
            "type": "general_status",
            "value_a": null,
            "value_b": "10Gbps HDX"
        },
        ...
    ]

    • possible values of label:
      • link_speed: one of Down, 10Gbps_FDX, 10Gbps_HDX, 1Gbps_FDX, 1Gbps_HDX, 100Mbps_FDX, 100Mbps_HDX, 10Mbps_FDX, 10Mbps_HDX
      • idle_error_count: int
      • is_master: bool
      • link_partner_autoneg_capable: bool
      • link_partner_next_page_capable: bool
      • next_page_request: bool
      • acknowledge: bool
      • advertise_1000baset_fdx: bool
      • advertise_1000baset_hdx: bool
      • advertise_100basetx_fdx: bool
      • advertise_100basetx_hdx: bool
      • advertise_10baset_fdx: bool
      • advertise_10baset_hdx: bool
      • advertise_asympause: bool
      • advertise_sympause: bool
      • parallel_detection_fault: bool
      • remote_fault: bool
      • master_slave_fault: bool
      • local_receiver: bool
      • remote_receiver: bool
      • lock_error_100basetx: bool
      • receive_error_100basetx: bool
      • transmit_error_100basetx: bool
      • ssd_error_100basetx: bool
      • esd_error_100basetx: bool
      • lock_error_1000baset: bool
      • receive_error_1000baset: bool
      • transmit_error_1000baset: bool
      • ssd_error_1000baset: bool
      • esd_error_1000baset: bool
      • carrier_extension_error_1000baset: bool
      • mdi_crossover_error: bool
    • any of the values except idle_error_count can be null; it means that it should be reported as N/A
    • possible values of type:
      • general_status
      • link_partner_status
      • fault_status

  • available only if capabilities.port_control == true

• Get capabilities of the device:

  • Path: /interfaces/{PRETTY_MAC}/capabilities

  • Method: GET

  • response:

    {
        "basic": true,
        "dual_ports": true,
        "span_mode": true,
        "gps": true,         
        "update": true,
        "poe": true,
        "sfp": true,
        "filtering": true,
        "statistics_v1": true,
        "statistics_v2": true,
        "port_control": true,
        "loopback": true,
        "phy1": true,   
        "phy2": true,
        "pcap_ng": true,
        "slicing_length": true,
        "phy3": true,
        "multiple_hw": true,
        "capture_full_frames": true,
        "ntp_disciplined_timestamp": true,
        "packet_type_filter": false,
        "pps_resolution_5ns": true,
        "pps_resolution_8ns": true,
        "autoneg_10g_1g": true
    }

• Get SFP properties of the device (only 10G):

  • Path: /interfaces/{PRETTY_MAC}/sfp

  • Method: GET

  • response:

    [
        {
            "label": "link_up",
            "type": "general_information",
            "value_a": true,
            "value_b": false
        },
        ...
    ]

    • possible values of label with their types:
      • link_up: bool
      • inline_mode: bool
      • vendor_name: string
      • vendor_oui: int
      • model: string
      • revision: string
      • date_code: string
      • serial_no: string
      • nominal_rate: int
      • maximum_bitrate: int
      • minimum_bitrate: int
      • encoding: string
      • rate_id: string
      • identifier: string
      • extended_identifier: int
      • connector: string
      • wave_length_nm: int
      • monitoring_type: string
      • sff8472_compliance: string
      • length_9um_m: int
      • length_50um_m: int
      • length_625um_m: int
      • length_copper_m: int
      • length_50um2_m: int
      • temperature_celsius: float
      • voltage_v: float
      • tx_bias_ma: float
      • tx_power_mw: float
      • rx_power_mw: float
      • low_alarm_temperature_celsius: float
      • low_alarm_voltage_v: float
      • low_alarm_tx_bias_ma: float
      • low_alarm_tx_power_mw: float
      • low_alarm_rx_power_mw: float
      • low_warning_temperature_celsius: float
      • low_warning_voltage_v: float
      • low_warning_tx_bias_ma: float
      • low_warning_tx_power_mw: float
      • low_warning_rx_power_mw: float
      • high_alarm_temperature_celsius: float
      • high_alarm_voltage_v: float
      • high_alarm_tx_bias_ma: float
      • high_alarm_tx_power_mw: float
      • high_alarm_rx_power_mw: float
      • high_warning_temperature_celsius: float
      • high_warning_voltage_v: float
      • high_warning_tx_bias_ma: float
      • high_warning_tx_power_mw: float
      • high_warning_rx_power_mw: float
      • alarms: array of strings
      • warnings: array of strings
      • status_bits: array of strings
    • possible values of type:
      • general_information
      • port_properties
      • other_information
    • if link_up is false on the port, it means there will be no SFP information for that port; the full default object will still be sent as a response

  • available only if capabilities.sfp == true

• Get packet type filters of the interface

  • Path: /interfaces/{PRETTY_MAC}/packet_type_filters

  • Method: GET

  • response:

    {
        "ipv4": true,
        "ipv6": true,
        "arp": true,
        "tcp": true,
        "udp": true,
        "icmp": true,
        "igmp": true,
        "https": false,
        "http": true,
        "ftp": true,
        "dns": true,
        "smtp": true,
        "pop3": true,
        "dhcp": true,
        "ssh": false,
        "sip": true,
        "smb": true,
        "tcp_fin": true,
        "tcp_syn": true,
        "tcp_rst": true,
        "tcp_psh": false,
        "tcp_ack": true,
        "zero_window": true,
        "quic": true,
        "l2_other": true,
        "l4_other": false
    }

  • available only if capabilities.packet_type_filter == true

• Change packet type filters of the interface
  • Path: /interfaces/{PRETTY_MAC}/packet_type_filters
  • Method: PUT
  • Request params: full packet_type_filters object
  • response: success or error message + new packet_type_filter object
  • available only if capabilities.packet_type_filter == true
• Get GPS/timing configuration of the interface

  • Path: /interfaces/{PRETTY_MAC}/timing

  • Method: GET

  • response:

    {
        "deviation": 524280.0,
        "external_pps_detected": true,
        "gps_pps_detected": false,
        "gps_sync": false,
        "pps_output": true,
        "time_source": "system_pps"
    }

    • possible values of time_source:
      • system
      • system_pps
      • gps
      • other

  • available only if capabilities.gps == true

• Change GPS/timing configuration of the interface
  • Path: /interfaces/{PRETTY_MAC}/timing
  • Method: PUT
  • Request params: timing object with some restrictions:
    • all fields except pps_output and time_source are ignored
    • time_source may not be set to the value other
  • response: success or error message + new timing object
  • note: also saves it to persistent memory along with overall configuration
  • available only if capabilities.gps == true
• Change time of the interface

  • Path: /interfaces/{PRETTY_MAC}/timing/push

  • Method: POST

  • Request params:

    {
        "push_time_source": "manual",
        "time":
        {
            "sec": 1234567,
            "nsec": 890123
        }
    }

    • possible values of push_time_source:
      • manual
      • gps
      • ntp
    • if push_time_source == manual, time object is required, otherwise it’s ignored
    • time::sec is number of seconds passed from the epoch, time::nsec are nanoseconds of this second

  • available only if capabilities.gps == true

• Get statistics of the interface

  • Path: /interfaces/{PRETTY_MAC}/statistics

  • Method: GET

  • response:

    {
        "error_code": 4,
        "sw_dropped_packets": 8,
        "hw_dropped_packets": 8,
        "cache_used_bytes": 15,
        "maximum_cache_bytes": 16,
        "written_bytes": 23,
        "written_files": 42,
        "timestamp_ms": 47398745629,
        "1g": 
        {
          "link_up_ms": 123456,
          "link_down_ms": 7890,
          "port_a":
          {
            "less_than_64_packets": 1,
            "between_64_1518_packets": 2,
            "more_than_1518_packets": 3,
            "collisions": 4,
            "crc_error_packets": 5,
            "jabber_packets": 6,
            "total_bytes": 7,
            "total_valid_packets": 8,
            "total_invalid_packets": 9,
            "hw_dropped_packets": 10
          },
          "port_b": 
          {
            "less_than_64_packets": 1,
            "between_64_1518_packets": 2,
            "more_than_1518_packets": 3,
            "collisions": 4,
            "crc_error_packets": 5,
            "jabber_packets": 6,
            "total_bytes": 7,
            "total_valid_packets": 8,
            "total_invalid_packets": 9,
            "hw_dropped_packets": 10
          }
        },
        "10g":
        {
          "port_a":
          {
            "crc_error_packets": 1,
            "hw_dropped_packets": 10
          },
          "port_b": 
          {
            "crc_error_packets": 1,
            "hw_dropped_packets": 10
          }
        }
    }

    • either 1g or 10g field can be set at one time; the other will be null explicitly
• Reset statistics of the interface
  • Path: /interfaces/{PRETTY_MAC}/statistics
  • Method: DELETE
  • response: success or error message
• Get firmware of the interface

  • Path: /interfaces/{PRETTY_MAC}/firmware

  • Method: GET

  • response:

    {
        "cmd_utility_v": "1.17",
        "profishark_api_v": "2.3.26.0",
        "driver_v": "1.9.34.0",
        "sw_firmware_v": "0.2.3.46",
        "hw_firmware_v": "0319"
    }

• Get possible versions of firmware of the interface

  • Path: /interfaces/{PRETTY_MAC}/firmware/update

  • Method: GET

  • response:

    [
        {
            "sw_version": "0.2.3",
            "hw_version": "2.2.7"
        }
    ]

• Update a firmware of the interface
  • Path: /interfaces/{PRETTY_MAC}/firmware/update
  • Method: POST
  • Request params: versions object defined upwards
  • response: success or error message + versions object
  • only available if state.physical_state == "idle" && general_state.state == "idle"
• Get auto-start capture on boot flag value

  • Path: /interfaces/{PRETTY_MAC}/capture/auto_start_on_boot

  • Method: GET

  • response:

    {
        "message":"Success",
        "data":
        {
            "auto_start_on_boot":false
        }
    }

• Set auto-start capture on boot flag value

  • Path: /interfaces/{PRETTY_MAC}/capture/auto_start_on_boot

  • Method: PUT

  • Payload:

    {
        "auto_start_on_boot": true
    }

  • response:

    {
        "message":"Success",
        "data":
        {
            "auto_start_on_boot": true
        }
    }

Back to Index