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
Code Block |
---|
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[ ]: IPv4 addressesipv6
string[ ]: IPv6 addressestext
string[ ]: Text recordsmx
object[ ]: Mail exchange recordsexchange
stringpriority
int
server_test
objecttcp
objectmade
int: The total number of DNS requests madepass
int: The total number of requests that passedfail
int: The total number of requests that failed.timeout
int: The total number of requests that timed out.mismatch
int: The total number of mismatched requests between the host and pointer records
udp
objectmade
int: The total number of DNS requests madepass
int: The total number of requests that passedfail
int: The total number of requests that failed.timeout
int: The total number of requests that timed out.mismatch
int: The total number of mismatched requests between the host and pointer records
errorList
object[ ]field
string: The field ('ipv4', 'ipv6', 'cname', 'mx', 'service', or 'text') where the error came fromerr
object:errno
string: Error number (usually the same value as code)code
string: Error code number (see DNS | Node.js v14.21.3 Documentation)syscall
string: Information about the system call stackhostname
string: The value passed in the URL
Response Example
Code Block | ||
---|---|---|
| ||
{ "route": "/v1/diagnostics/dns-lookup/google.com", "method": "GET", "data": { "result": { "records": { "ipv4": [ "142.250.105.113", "142.250.105.102", "142.250.105.139", "142.250.105.101", "142.250.105.138", "142.250.105.100" ], "ipv6": [ "2607:f8b0:4002:c0c::8a", "2607:f8b0:4002:c0c::8b", "2607:f8b0:4002:c0c::71", "2607:f8b0:4002:c0c::64" ], "mx": [ { "exchange": "smtp.google.com", "priority": 10 } ] }, "server_test": { "tcp": { "made": 100, "pass": 100, "fail": 0, "timeout": 0, "mismatch": 0 }, "udp": { "made": 100, "pass": 100, "fail": 0, "timeout": 0, "mismatch": 0 } }, "errorList": [ { "field": "cname", "err": { "code": "ENODATA", "syscall": "queryCname", "hostname": "google.com" } }, { "field": "service", "err": { "code": "ENODATA", "syscall": "querySrv", "hostname": "google.com" } }, { "field": "text", "err": { "code": "ETIMEOUT", "syscall": "queryTxt", "hostname": "google.com" } } ] } } } |
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
Code Block |
---|
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 notresponse
object:hostname
string: The value that you passed in the URLresults
object:ipv4
object[ ]:address
string: The IPv4 address that is pingedresults
object:received
int: The number of packets receivedstats
object:average
int: The average time for the packet to returnquickest
int: The quickest time for packet to returnslowest
int: The slowest time for the packet to returnunits
int: The time units (usually microseconds)
transmitted
int: The number of packets transmitted
ipv6
object[ ]: This will only be returned if IPv6 is present.interface
stringsource
stringaddress
string: The IPv6 address that is pingedresults
objectreceived
int: The number of packets receivedtransmitted
int: The number of packets transmitted
The ipv6
entry will only be returned if IPv6 is present.
Response Example
Code Block | ||
---|---|---|
| ||
{ "route": "/v1/diagnostics/ping/0.0.0.0", "method": "GET", "data": { "result": { "success": true, "response": { "hostname": "0.0.0.0", "results": { "ipv4": [ { "address": "0.0.0.0", "results": { "received": 10, "stats": { "average": 318, "quickest": 223, "slowest": 336, "units": "us" }, "transmitted": 10 }, "up": true } ] }, "up": true } } } } |
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
Code Block |
---|
GET /rest/v1/diagnostics/trace-route/google.com/?resolveAddress=true&destinationType=player&destinationName={{deviceSerial}} HTTP/1.1 Host: ws.bsn.cloud Authorization: Bearer {{UserAccessToken}} Accept: application/json, application/vnd.bsn.error+json |
Response Body
address
string: The IP address on which you are running the trace routeresults
object:output
string[ ]: Returns the trace route output information in text formatprotocol
string: The IP protocol, for example, "ipv4"route
object[ ]:hop
int: How many times the data moves from one router to the nextservers
object:address
string: The address to which the trace route request is madehostname
string: The server hostnamestats
object[ ]reachable
string:time
string: The time required for the trace route request to returnunits
string: The time units (usually in milliseconds)
Response Example
Code Block | ||
---|---|---|
| ||
{ "route": "/v1/diagnostics/trace-route/152.101.32.76", "method": "GET", "data": { "result": { "address": "123.456.7.890", "resolveAddress": "true", "results": { "152.101.32.76": { "output": [ "traceroute to 152.101.32.76 (152.101.32.76), 30 hops max, 46 byte packets", " 1 10.0.4.1 0.744 ms 0.458 ms 1.740 ms", " 2 192.168.0.1 1.738 ms 1.387 ms 1.387 ms", " 3 96.120.89.217 10.553 ms 11.250 ms 11.961 ms", " 4 96.110.176.145 11.958 ms 11.250 ms 9.845 ms", " 5 162.151.78.253 11.957 ms 13.366 ms 10.549 ms", " 6 96.108.99.249 13.366 ms 14.072 ms 20.414 ms", " 7 68.86.143.93 13.368 ms 11.960 ms 10.549 ms", " 8 96.97.98.246 32.397 ms 96.112.146.22 11.954 ms 69.241.75.42 9.841 ms", " 9 * * *", "10 152.101.32.76 10.452 ms 152.101.32.76 13.302 ms 152.101.32.76 12.649 ms", "11 192.178.105.102 11.948 ms 142.251.224.181 11.073 ms 192.178.46.198 17.759 ms", "12 142.251.32.46 11.955 ms 12.649 ms 10.543 ms" ], "protocol": "ipv4", "result": 0, "route": [ { "error": "timeout", "hop": 9 } ] } } } } } |
GET /diagnostics/network-configuration/{:interface}/
Retrieves information about network-interface settings on the player
Segment
interface
: The network interface. Possible names includeeth0
,wlan0
, andmodem
.
Request Example
Code Block |
---|
GET /rest/v1/diagnostics/network-configuration/eth0/?destinationType=player&destinationName={{deviceSerial}} HTTP/1.1 Host: ws.bsn.cloud Authorization: Bearer {{UserAccessToken}} Accept: application/json, application/vnd.bsn.error+json |
Response Body
Some entries (e.g. caCertificates
, clientIdentifier
) are identical for all interfaces.
text
string: The network configuration information in plain-text formoutput
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 interfaceparams
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 hostparams
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 certificateclientIdentifier
string: The DHCP client identifier for the network interfacednsServerList
string[ ]: An IP address list of the DNS serversdomain
string: The domain name for the network interfaceeapTlsOptions
string: A string containing EAP-specific optionsenabledProtocolList
string[ ]: An array of enabled IP protocols. Currently supported values are"IPv4"
and "IPv6"
.identity
string: The RADIUS identityipAddressList
string[ ]: The IP addresses assigned to the playerinboundShaperRate
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 bytesprivateKey
string: The private key for authenticationvlanIdList
int[ ]: An array of VLAN ids that are supported on the parent network interfacesecurityMode
string: Security mode for authentication
Response Example
Expand | |||||
---|---|---|---|---|---|
| |||||
|
PUT /diagnostics/network-configuration/{:interface}/
Applies a test network configuration on the player. You should use GET to get the configuration parameters before setting it using this API. The text
and output
parameters are NOT needed in PUT.
Segment
interface
: The network interface. Possible names includeeth0
,wlan0
, andmodem
.
Request Body
caCertificate
string optional: The contents of a CA certificate file in text form (i.e. a "pem" file).clientCertificate
bool optional: A flag indicating whether the player is using a client certificateclientIdentifier
string optional: The DHCP client identifier for the network interfacednsServerList
string[ ] optional: An IP address list of the DNS serversdomain
string optional: The domain name for the network interfaceeapTlsOptions
string optional: A string containing EAP-specific optionsenabledProtocolList
string[ ] optional: An array of enabled IP protocols. Currently supported values are "IPv4" and "IPv6".identity
string optional: The RADIUS identityipAddressList
string[ ] optional: The IP addresses assigned to the playerinboundShaperRate
int optional: 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 optional: The routing metric for the default gateway on the interface. Routes with lower metrics are preferred over routes with higher metrics.mtu
int optional: The maximum transmission unit (MTU) for the network interface in bytesprivateKey
string optional: The private key for authenticationvlanIdList
int[ ] optional: An array of VLAN ids that are supported on the parent network interfacesecurityMode
string optional: Security mode for authentication
Request Example
The example request parameters and headers are set as follows:
Code Block |
---|
PUT /rest/v1/diagnostics/network-configuration/eth0 HTTP/1.1 Host: ws.bsn.cloud Authorization: Bearer {{UserAccessToken}} Accept: application/json Content-Type: application/json Content-Length: 75 |
This is the example request body:
Code Block | ||
---|---|---|
| ||
{ "data": { "caCertificates": "", "clientCertificate": false, "clientIdentifier": "BrightSign:D7E8CV332141", "dnsServerList": [], "domain": "", "eapTlsOptions": "", "enabledProtocolList": [ "IPv4", "IPv6" ], "identity": "", "ipAddressList": [], "privateKey": false, "securityMode": "", "vlanIdList": [] } } |
GET /diagnostics/network-neighborhood/
Retrieves information about the player’s current network neighborhood (the other players on the same network).
Request Example
Code Block |
---|
GET /rest/v1/diagnostics/network-neighborhood/?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 succeededresponse
object[ ]: An array of information about players in your network neighborhoodchassis-descr
string: The model version, OS version, serial number, etc.chassis-id
string: A unique identifier for the playerchassis-name
string: The name of the playermgmt-ip
stringport-descr
string: Which interface the player is usingport-id
stringvlan-pvid
string
If the diagnostic could not be performed, the response body may instead be an error message.
Response Example
Code Block | ||
---|---|---|
| ||
{ "route": "/v1/diagnostics/network-neighborhood", "method": "GET", "data": { "result": { "success": true, "response": [ { "chassis-descr": "BrightSign XT1144 REVE 8.5.47 UHE115005214", "chassis-id": "90:ac:3f:28:fb:a4", "chassis-name": "BrightSign-UHE115005214", "mgmt-ip": "2601:647:4500:1e5e:92ac:3fff:fe28:fba4", "port-descr": "eth0", "port-id": "90:ac:3f:28:fb:a4", "vlan-pvid": "0" } ] } } } |
GET /diagnostics/packet-capture/
Gets the current status of packet capture operation. Packet capture operation requires the legacy DWS to be working.
Request Example
Code Block |
---|
GET /rest/v1/diagnostics/packet-capture/?destinationType=player&destinationName={{deviceSerial}} HTTP/1.1 Host: ws.bsn.cloud Authorization: Bearer {{UserAccessToken}} Accept: application/json, application/vnd.bsn.error+json |
Response Body
statusCode
int: The success or error code (200 is success)is_running
bool: Flag indicating if the packet capture operation is running
Response Example
Code Block | ||
---|---|---|
| ||
{ "route": "/v1/diagnostics/packet-capture", "method": "GET", "data": { "result": { "statusCode": 200, "is_running": false } } } |
POST /diagnostics/packet-capture/
Starts a packet capture operation
Request Body
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
Code Block |
---|
POST /rest/v1/diagnostics/packet-capture/?destinationType=player&destinationName={{deviceSerial}} HTTP/1.1 Host: ws.bsn.cloud Authorization: Bearer {{UserAccessToken}} Accept: application/json, application/vnd.bsn.error+json Content-Type: application/json Content-Length: 190 |
This is the example request body:
Code Block | ||
---|---|---|
| ||
{ "data": { "filename": "capture.pcap", "interface": "eth0", "duration": 300, "maxpackets": 0, "snaplen": 0, "filter": "" } } |
Response Example
Code Block | ||
---|---|---|
| ||
{ "data": { "result": { "statusCode": 200, "is_running": true } }, "route": "/v1/diagnostics/packet-capture", "method": "POST" } |
DELETE /diagnostics/packet-capture/
Stops a packet capture operation
Request Example
Code Block |
---|
DELETE /rest/v1/diagnostics/packet-capture/?destinationType=player&destinationName={{deviceSerial}} HTTP/1.1 Host: ws.bsn.cloud Authorization: Bearer {{UserAccessToken}} Accept: application/json, application/vnd.bsn.error+json |
Response Example
Code Block | ||
---|---|---|
| ||
{ "route": "/v1/diagnostics/packet-capture", "method": "DELETE", "data": { "result": { "statusCode": 200, "is_running": false } } } |
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
Code Block |
---|
GET /rest/v1/diagnostics/telnet?destinationType=player&destinationName={{deviceSerial}} HTTP/1.1 Host: ws.bsn.cloud Authorization: Bearer {{UserAccessToken}} |
Response Example
Code Block | ||
---|---|---|
| ||
{ "route": "/v1/diagnostics/telnet", "method": "GET", "data": { "result": { "enabled": true, "portNumber": 23 } } } |
PUT /diagnostics/telnet/
This is only available in BOS 9.0.110 and above.
Request Body
enabled
boolean: Enable or disable Telnet on the playerportNumber
integer: The port number on which to enable Telnetreboot
boolean: This optional parameter reboots the player immediately after executing this operation. It istrue
by default.
Request Example
The example request parameters and headers are set as follows:
Code Block |
---|
PUT /rest/v1/diagnostics/telnet/ HTTP/1.1 Host: ws.bsn.cloud Authorization: Bearer {{UserAccessToken}} Accept: application/json Content-Type: application/json Content-Length: 75 |
This is the example request body:
Code Block | ||
---|---|---|
| ||
{ "data": { "enabled": true "portNumber": "23", "password": {{password}} } } |
Response Example
Code Block | ||
---|---|---|
| ||
{ "data": { "result": { "success": true, "reboot": true } }, "route": "/v1/diagnostics/telnet", "method": "PUT" } |
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:
Code Block |
---|
GET /rest/v1/diagnostics/ssh/ HTTP/1.1 Host: ws.bsn.cloud Authorization: Bearer {{UserAccessToken}} Accept: application/json |
Response Example
A successful response is a 200 and this response body:
Code Block | ||
---|---|---|
| ||
{ "enabled": true, "portNumber": 22, "password": true // Indicates that a value is set } |
PUT /diagnostics/ssh/
This is only available in BOS 9.0.110 and above.
Request Body
enabled
boolean: Enable or disable SSH on the playerportNumber
integer: The port number on which to enable SSHpassword
string: Sets the plain-text login password for the SSH connectionreboot
boolean: This optional parameter reboots the player immediately after executing this operation. It istrue
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:
Code Block |
---|
PUT /rest/v1/diagnostics/ssh/ HTTP/1.1 Host: ws.bsn.cloud Authorization: Bearer {{UserAccessToken}} Accept: application/json Content-Type: application/json Content-Length: 65 |
This is the example request body:
Code Block | ||
---|---|---|
| ||
{ "data": { "enabled": true, "portNumber": 22, "password": {{password}} } } |
Response Example
Code Block | ||
---|---|---|
| ||
{ "data": { "result": { "success": true, "reboot": true } }, "route": "/v1/diagnostics/ssh", "method": "PUT" } |