Interfaces

Manage Profishark interfaces

API

• Get all interfaces:
  • Path: /interfaces
  • Method: GET
  • Response: json [ { "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: json { "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: json { "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: json { "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: json { "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: json { "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: json [ { "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: json { "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: json [ { "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: json { "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: json { "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: json { "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: json { "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: json { "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: json [ { "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
• Get auto-start capture on boot flag value
  • Path: /interfaces/{PRETTY_MAC}/capture/auto_start_on_boot
  • Method: GET
  • response: json { "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: json { "auto_start_on_boot": true }
  • response: json { "message":"Success", "data": { "auto_start_on_boot": true } }

Back to Index