rDWS Diagnostics Endpoints

Base URL for these endpoints: https://ws.bsn.cloud/rest/v1/

_________________________________________________________________________

GET /diagnostics/

Runs network diagnostics on the player

Request Example

GET /rest/v1/diagnostics/?destinationType=player&destinationName={{deviceSerial}} HTTP/1.1
Host: ws.bsn.cloud
Authorization: Bearer {{UserAccessToken}}
Accept: application/json, application/vnd.bsn.error+json

Response Body

ethernet string:
- diagnosis string: Indicates if this type of interface is present
- log object[ ]: This contains the diagnostic results for the ethernet interface. It has fields for name, pass, and result.
  - name string: The name of the diagnostic test
  - pass bool: Indicates whether the test passed or not
  - result string: The actual value for the diagnostic tests like checking type and ping.
- ok bool: If diagnostics were run on the interface or not.
wifi string:
- diagnosis string: Indicates if this type of interface is present
- log object[ ]: This contains the diagnostic results for the wifi interface. It has fields for name, pass, and result.
  - name string: The name of the diagnostic test
  - pass bool: Indicates whether the test passed or not
  - result string: The actual value for the diagnostic tests like checking type and ping.
- ok bool: If diagnostics were run on the interface or not.
modem string:
- diagnosis string: Indicates if this type of interface is present
- log object[ ]: This contains the diagnostic results for the modem interface. It has fields for name, pass, and result.
  - name string: The name of the diagnostic test
  - pass bool: Indicates whether the test passed or not
  - result string: The actual value for the diagnostic tests like checking type and ping.
- ok bool: If diagnostics were run on the interface or not.
internet string:
- diagnosis string: Indicates if this type of interface is present
- log object[ ]: This contains the diagnostic results for the internet connectivity. It has fields for info, name, pass, and result.
  - info string: Returns DNS server info
  - name string: Checks DNS servers and internet connectivity
  - pass bool: Indicates whether the test passed or not
  - result string: The actual value for the diagnostic tests like checking type and ping.
- ok bool: If diagnostics were run on the interface or not.

Endpoints:

1 GET /diagnostics/
2 GET /diagnostics/dns-lookup/{:domain_name}/
3 GET /diagnostics/ping/{:domain_name}/
4 GET /diagnostics/trace-route/{:domain_name}/
5 GET /diagnostics/network-configuration/{:interface}/
6 GET /diagnostics/network-neighborhood/
7 GET /diagnostics/packet-capture/
8 POST /diagnostics/packet-capture/
9 DELETE /diagnostics/packet-capture/
10 GET /diagnostics/telnet/
11 PUT /diagnostics/telnet/
12 GET /diagnostics/ssh/
13 PUT /diagnostics/ssh/

GET /diagnostics/dns-lookup/{:domain_name}/

Tests name resolution on the specified DNS address

Segment

domain_name: The DNS address (for example, google.com)

Request Example

GET /rest/v1/diagnostics/dns-lookup/google.com/?destinationType=player&destinationName={{deviceSerial}} HTTP/1.1
Host: ws.bsn.cloud
Authorization: Bearer {{UserAccessToken}}
Accept: application/json, application/vnd.bsn.error+json

Response Body

The player queries each DNS field separately, then collects returned data into the records object and returned errors into the errorList object. The following DNS fields are queried: "ipv4", "ipv6", "cname", "mx", "service", "text".

records object
- ipv4 string[ ]
- ipv6 string[ ]
- text string[ ]
- mx object[ ]
  - exchange string
  - priority int
server_test object
- tcp object
  - made int: The total number of DNS requests made
  - pass int: The total number of requests that passed
  - fail int: The total number of requests that failed.
  - timeout int: The total number of requests that timed out.
  - mismatch int
- udp object
  - made int: The total number of DNS requests made
  - pass int: The total number of requests that passed
  - fail int: The total number of requests that failed.
  - timeout int: The total number of requests that timed out.
  - mismatch int
errorList object[ ]
- field string
- err object
  - errno string: Error number (usually the same value as code)
  - code string: Error code number
  - syscall string
  - hostname string: The value passed in the URL

GET /diagnostics/ping/{:domain_name}/

Requests the player to ping the specified IP or DNS address on its local network. This call can take over 10 seconds to return.

Segment

domain_name: The specified IP or DNS address

Request Example

GET /rest/v1/diagnostics/ping/0.0.0.0/?destinationType=player&destinationName={{deviceSerial}} HTTP/1.1
Host: ws.bsn.cloud
Authorization: Bearer {{UserAccessToken}}
Accept: application/json, application/vnd.bsn.error+json

Response Body

success bool: A flag that indicates if the operation succeeded or not
response object:
- hostname string: The value that you passed in the URL
- results object
  - ipv4 object[ ]
    - address string: The IPv4 address
    - results object
      - received int: The number of packets received
      - stats object
        average int: The average time for the packet to return
        quickest int: The quickest time for packet to return
        slowest int: The slowest time for the packet to return
        units int: The time units (usually microseconds)
      - transmitted int: The number of packets transmitted
  - ipv6 object[ ]
    - interface string
    - source string
    - address string: The IPv6 address
    - results object
      - received int: The number of packets received
      - transmitted int: The number of packets transmitted

The ipv6 entry will only be returned if IPv6 is present.

GET /diagnostics/trace-route/{:domain_name}/

Requests the player to perform a standard trace-route diagnostic on the specified IP or DNS address. This call can take several minutes to return.

Segment

domain_name: The specified IP or DNS address

Query String Parameter

resolveAddress bool: Specifies whether the IP or DNS address should be resolved or not

Request Example

Response Body

address string
results object
- output string[ ]: Returns the trace route output information in text format
- protocol string: The IP protocol, for example, "ipv4"
- route object[ ]:
  - hop int
  - servers object
    - address string: The address to which the trace route request is made
    - hostname string
    - stats object[ ]
      - reachable string
      - time string: The time required for the trace route request to return
      - units string: The time units (usually in milliseconds)

GET /diagnostics/network-configuration/{:interface}/

Retrieves information about network-interface settings on the player

Segment

interface: The network interface. Possible names include eth0, wlan0, and modem.

Request Example

Response Body

Some entries (e.g. caCertificates, clientIdentifier) are identical for all interfaces.

text string: The network configuration information in plain-text form
output Output: The network configuration information as a JSON object:
- interfaces Interface[ ]: An array of Interface objects representing network interfaces:
  - name string: The interface name (for example, "eth0")
  - errors Error[ ]: An array of error messages associated with the interface
  - params Param[ ]: An array of Param objects representing parameters associated with the network interface. Each Param interface has the following entries:
    - name string: The property name (e.g. "MAC")
    - value string: The property value (e.g. "90:ac:3f:0b:d2:88")
- host Info[ ]: An array of Info objects providing network host information. Each object can have the following entries:
  - errors Error[ ]: An array of error messages associated with the network host
  - params Param[ ]: An array of Param objects representing parameters associated with the network host
- bsn Info[ ]: An array of Info objects providing information about BSN communication.
- other Info[ ]: An array of Info objects providing information miscellaneous network information.
caCertificate string: The contents of a CA certificate file in text form (i.e. a "pem" file).
clientCertificate bool: A flag indicating whether the player is using a client certificate
clientIdentifier string: The DHCP client identifier for the network interface
dnsServerList string[ ]: An IP address list of the DNS servers
domain string: The domain name for the network interface
eapTlsOptions string: A string containing EAP-specific options
enabledProtocolList string[ ]: An array of enabled IP protocols. Currently supported values are "IPv4" and "IPv6".
identity string: The RADIUS identity
ipAddressList string[ ]: The IP addresses assigned to the player
inboundShaperRate int: The bandwidth limit for inbound traffic in bits per second. A value of -1 specifies the default bandwidth limit, and a value of 0 specifies no bandwidth limit (these two settings are functionally the same).
metric int: The routing metric for the default gateway on the interface. Routes with lower metrics are preferred over routes with higher metrics.
mtu int: The maximum transmission unit (MTU) for the network interface in bytes
privateKey string: The private key for authentication
vlanIdList int[ ]: An array of VLAN IDs that are supported on the parent network interface
securityMode string: Security mode for authentication
securityMode string

GET /diagnostics/network-neighborhood/

Retrieves information about the current network neighborhood of the player

Request Example

Response Body

success bool: A flag that indicates if the operation succeeded
response object[ ]:
- chassis-descr string
- chassis-id string
- chassis-name string
- mgmt-ip string
- port-descr string
- port-id string
- vlan-pvid string

If the diagnostic could not be performed, the response body may instead be an error message.

GET /diagnostics/packet-capture/

Gets the current status of packet capture operation. Packet capture operation requires the legacy DWS to be working.

Request Example

Response Body

statusCode int: The success or error code (200 is success)
is_running bool: Flag indicating if the packet capture operation is running

POST /diagnostics/packet-capture/

Starts a packet capture operation

Request Body Parameters

filename string: The name of the packet capture file. If you don't pass this string, 'capture.pcap' is the default.
interface string: The name of the interface for which we are performing packet capture. 'eth0' is the default.
duration int: The duration for which the packet capture runs in seconds. The default is 300 seconds (5 minutes).
maxpackets int: The maximum number of packets to capture before concluding the process. 0 is the default value.
snaplen int: The maximum size of each packet. Specifying 0 will instruct the function to capture the entire packet no matter the size.
filter string: A field for conditional filtering of packets. This operation uses standard pcap syntax. This string is empty by default.

Request Example

This is the example request body:

DELETE /diagnostics/packet-capture/

Stops a packet capture operation

Request Example

GET /diagnostics/telnet/

Get information about telnet from the player, including its enabled status and port number. This is only available in BOS 9.0.110 and above.

Request Example

Response Body

PUT /diagnostics/telnet/

This is only available in BOS 9.0.110 and above.

Request Body

enabled boolean: Enable or disable Telnet on the player
portNumber integer: The port number on which to enable Telnet
reboot boolean: This optional parameter reboots the player immediately after executing this operation. It is true by default.

Request Example

The example request parameters and headers are set as follows:

This is the example request body:

Response

GET /diagnostics/ssh/

Returns information about whether or not SSH is enabled on the player, and the port number on which it is enabled if it is. This is only available in BOS 9.0.110 and above.

Request Example

The example request parameters and headers are set as follows:

Response Example

A successful response is a 200 and this response body:

PUT /diagnostics/ssh/

This is only available in BOS 9.0.110 and above.

Request Body

enabled boolean: Enable or disable SSH on the player
portNumber integer: The port number on which to enable SSH
password string: Sets the plain-text login password for the SSH connection
reboot boolean: This optional parameter reboots the player immediately after executing this operation. It is true by default.
obfuscatedPassword string: This optional parameter sets the login password for the SSH connection. The password should previously have been obfuscated using a shared secret. Contact support@brightsign.biz to learn more about generating a key for obfuscation and storing it on the player.

Request Example

The example request parameters and headers are set as follows:

This is the example request body: