Interfaces

Manage Profishark interfaces

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 json { "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
  • 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 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
• 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": null
    }

    • 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", see General state

Back to Index