LDWS API Diagnostics Endpoints
DELETE /v1/storage/:device/
Formats a storage device
You must disable the autorun before reformatting the SD card on your device.
To disable the autorun, use the PUT /v1/control/reboot with body parameter {“autorun”:”disable”}, as described in this page.
Segment
:device
string: The specified storage device (see this page for a list of available devices)
Request Body
fs
string: The file system to use when reformatting a storage device. The default value of fs is "exfat".
Request Example
DELETE /api/v1/storage/sd/ HTTP/1.1
Host: {{playerIP}}
Authorization: {{DigestAuth}}
Accept: application/json, application/vnd.bsn.error+json
Content-Type: application/json
Content-Length: 49
This is the example request body:
{
"fs": "exfat"
}
Response Example
{
"data": {
"result": {
"success": true,
"output": "Format completeted successfully.",
"error": ""
}
}
}
GET /v1/diagnostics/
Runs network diagnostics on the player and returns the result in JSON format.
Request Example
Response Body
For each of ethernet
, wifi
, modem
, and internet
:
diagnosis
string: Indicates if this type of interface is presentlog
object[ ]: This contains the diagnostic results for the interface:name
string: The name of the diagnostic testpass
bool: Indicates whether the test passed or notresult
string: The actual value for the diagnostic tests like checking type and ping.
ok
bool: If diagnostics were run on the interface or not.
Response Example
GET /v1/diagnostics/dns-lookup/:address/
Runs a DNS lookup for an address, which can be a hostname or IP address.
Segment
:address
: The hostname (for example, http://google.com) or IP address
Request Example
Response Body
The player queries each DNS field separately, then collects returned data into the records object, the tcp and udp connection information is in the server_test object, and returned errors into the errorList object.
records
object:ipv4
string[ ]: IPv4 addressesipv6
string[ ]: IPv6 addressestext
string[ ]: Text recordsmx
object[ ]: Mail exchange recordsexchange
stringpriority
int
server_test
object:tcp
object:made
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 outmismatch
int: The total number of mismatched requests between the host and pointer records
udp
object:made
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') 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
GET /v1/diagnostics/ping/:ipAddress/
Pings the address passed in the request. This does not work for hostnames, only for IP addresses.
Segment
:ipAddress
: The specified IP address
Request Example
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
string:source
string:address
string: The IPv6 address that is pingedresults
object:received
int: The number of packets receivedtransmitted
int: The number of packets transmitted
Response Example
GET /v1/diagnostics/trace-route/:address/
Runs trace-route on the player. You can optionally pass the boolean query parameter ?resolveAddress
to resolve IP addresses in the result.
Segment
:address
: The specified IP or hostname address
Query String Parameter
resolveAddress
bool optional: Specifies whether the IP or hostname address should be resolved or not in the result
Request Example
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
GET /v1/diagnostics/network-neighborhood/
Retrieves information about the player’s current network neighborhood (the other players on the same network).
Request Example
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
string:port-descr
string: Which interface the player is usingport-id
string:vlan-pvid
string:
If the diagnostic could not be performed, the response body may instead be an error message.
Response Example
GET /v1/diagnostics/network-configuration/:interfaceName/
Gets the network configuration on the player. See Local DWS APIs for more information about digest authentication.
Segment
:interfaceName
: The network interface. Possible names includeeth0
,wlan0
, andmodem
.
Request Example
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 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
Response Example
PUT /v1/diagnostics/network-configuration/:interfaceName/
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
:interfaceName
: 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:
This is the example request body:
Response Example
GET /v1/diagnostics/interfaces/
Returns list of applied network interfaces on the player.
Request Body
Response Body
GET /v1/diagnostics/packet-capture/
Returns the current status of packet capture operation.
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
Response Example
POST /v1/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.net_interface
string: The name of the network 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:
Response Example
DELETE /v1/diagnostics/packet-capture/
Stops a packet capture operation
Request Example
Response Example
GET /v1/diagnostics/telnet/
Returns information about whether or not Telnet 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 or 8.5.46 and above.
Request Example
Response Example
A successful response is a 200 and this response body:
PUT /v1/diagnostics/telnet/
This is only available in BOS 9.0.110 or 8.5.46 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:
This is the example request body:
Response Example
GET /v1/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 or 8.5.46 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 /v1/diagnostics/ssh/
This is only available in BOS 9.0.110 or 8.5.46 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:
This is the example request body:
Response Example