Provisioning & Recovery

overview brightsign players in large, distributed networks should meet certain provisioning and recovery requirements partners who want to set up their own provisioning and recovery systems, rather than using bsn cloud, should make sure that those systems meet the following requirements each player must be able to provision itself, and once provisioned, periodically check in with the server for updates if configured to do so the player and server must also be able to initiate a recovery process should the player enter an error state that cannot be fixed by rebooting (for example, filesystem corruption caused by power loss or failure of the storage device) to meet these requirements, two separate but complementary systems must be developed a set of autorun brs files that can play content, facilitate fault recovery, or provision the player for an html/javascript playback environment a request handler server to process recovery/provisioning http requests sent by the player the request handler delivers an autorun file or other http response depending on player information contained within the header of the request the request handler database can also contain conditional flags for each player, that enable new autorun scripts to be pushed to specific players in the field if a partner specific request handler is not specified in the registry, bsn cloud provides a default request handler player provisioning brightsign player provisioning integrates the player into your environment, primarily by changing registry settings to reflect that environment and usually by downloading an application or setup package to the player the following settings are configured within the registry during brightauthor\ connected or bsn cloud provisioning bsn cloud account, username, password, and group recovery/provisioning url, error notification url, crash report url timezone player registry entries the following player registry entries are associated with the provisioning and recovery process these keys can be modified by accessing the registry’s “networking” section using the roregistry docid\ ytpsfntswyfmxx8pcqjlf brightscript object registry key description ub the url prefix that is applied to the urls of the ru, eu, and cu key values this prefix is not applied to a key value containing a colon ru the provisioning/recovery url used by the player to download an autorun script eu the url to which error notifications are posted cu the url to which crash reports are posted p the password to the recovery handler ( ru ) that is specified above the following registry keys are specific to bsn cloud but can be modified by partners to affect the bsn cloud registration you should not store your own information in these sections because it can affect bsn cloud operations registry key description a the name of the bsn cloud account to which the player belongs u the name of the bsn cloud user in the account to which the player belongs g the bsn cloud group within the account to which the player belongs the account, username, and group registry keys are used for provisioning/recovery with bsn cloud a request handler may use these keys, but they are not required player startup processes these processes occur when a brightsign player boots the player connects to a network and obtains an ip address the player checks the storage device for an autorun if an autorun is found, the player will execute the autorun and if none is found, it will proceed with the steps below see player storage docid\ o4yzospnpfagbglduleee for more information about storage devices and device priority (if you have multiple storage devices) if an ipv4 address exists, the player will attempt to provision over the network the player will check for a recovery url (ru) if a dhcp option 43 recovery url (ru) is found, it will override any registry value for ru until the end of the dhcp lease this url can be set through dhcp option 43 see option 43 docid 5rglqfftt pxzahhl8gl3 to configure a dhcp server to communicate this url to a brightsign player if dhcp option 43 ru is not found, the ru that is set in the registry will be used if there is no registry value for the ru, this step will be skipped if the recovery url is blank, the player will attempt well known host provisioning also known as custom name mapping in your network's dns server if an ip address is mapped to brightsign b deploy , then the player will attempt to use the associated ip to provision itself automatically b deploy cloud provisioning see b deploy/provisioning apis docid\ wccw4tqerzpxv7kjq a3p multicast dns (mdns) the player will automatically check the standard mdns location ( http //brightsign b deploy local/) and if there is a server on your network with that address, the player will automatically provision itself however, no other provisioning methods can be active if you want to provision with mdns see the appendix at the end of this page for more information about this option the player will retry the provisioning process every 30 seconds until there is a successful response or interruption url request parameters these parameters are used for communicating between a player and the request handler player request parameters the following parameters are included in the header of http get requests that a player sends to provisioning/recovery url parameter example value description devicemodel xt1144 the model designation of the brightsign player devicefamily malibu the family designation of the brightsign player deviceid d5e86p001287 the unique serial number of the player devicefwversion 8 2 42 the os (firmware) version currently installed on the player deviceuptime 240 the amount of time (in seconds) since the player booted up recoverymode override the mode of the current url request \ override the initial http get request of a player with a valid autorun script \ periodic subsequent http get requests of a player with a valid autorun script \ last resort the http get request of a player without a valid autorun script crashdump yes a flag indicating that the current boot was initiated by a forced reboot due to a crash (this header is only present if true) storagestatus usb1=none;sd=autorun; sd2=storage;ssd=none; the current autorun and file system status of each storage device optional bsn cloud keys parameter example value description account bsaccount the a registry value described above user bsuser the u registry value described above group bsgroup the g registry value described above password bspassword the p registry value described above storage status parameters the storagestatus value contains a list of key value pairs indicating the status of each storage device the following storage device keys are returned brightscript key storage status key usb1 usb1 sd sd sd2 sd2 ssd ssd these status values can be returned for each storage device storage status value description none the storage device was not detected storage the storage device is present, but an autorun script was not detected autorun the storage device is present and contains an autorun brs or autorun zip file autorun load error the storage device is present and contains an autorun brs or autorun zip file that failed to load autorun runtime error the storage device is present and contains an autorun brs or autorun zip file that encountered a runtime error error the storage device is present but failed a file system check this value also implies that attempts to repair the file system also failed server response parameters the header of a request handler response may contain a single parameter this parameter can accompany an http 204 or 200 response (even if the response body is empty) parameter example value description retry after 7200 the amount of time (in seconds) that the player should wait to make a periodic request to the provisioning/recovery url if this parameter is not provided, the default request interval will be two hours player recovery if no valid autorun is found, a recovery is triggered in a recovery, the player pulls down content from the recovery url (stored in the registry) and attempts to execute it the recovery process and the recovery url should not be confused while the recovery process uses the recovery url, some deployment scenarios also use the recovery url and it is also the provisioning url in the registry override recovery once the boot process has been completed, the player scans each storage device to determine if one or more devices contain an autorun file if at least one device contains an autorun file, the player will delay executing the autorun while a background process sends an http get request (containing parameters describing the player in the header) to the provisioning/recovery url if the request handler responds using an http code 200 with a non empty body, the player will use the response body as the new autorun script if the request handler responds with an http code 204, or an http code 200 containing an empty message body, the player will execute the preexisting autorun script as normal the response may also include a "retry after" header indicating (in seconds) how frequently the player should check in with the request handler if this parameter is not specified, the check in interval will default to two hours if no response is received within 20 seconds, the preexisting autorun will be executed the player will send another request to the request handler after five minutes, then after 10 minutes it will then make a request once every two hours if multiple storage devices contain an autorun file, the player will select the first autorun in the following order usb, sd, sd2, ssd if it takes too long to check the integrity of a storage device, then that device might be skipped in the order of autorun selection so do not build a system that relies on this order if none of the devices contain an autorun, the player will enter last resort recovery mode periodic recovery the player will periodically send an http get request to the provisioning and recovery url to determine if the device should be updated if no response is received, the preexisting autorun will continue without interruption if the request handler responds with an http code 204, or an http code 200 containing an empty message body, the preexisting autorun will continue without interruption the response may also include a "retry after" header indicating (in seconds) how frequently the player should check in with the request handler if this parameter is not specified, the check in interval will default to two hours if the request handler responds using an http code 200 with a non empty body, the player will use the response body as the new autorun script diagram1a png last resort recovery if none of the attached storage devices contain an autorun file, or if the designated autorun encounters an autorun load error or autorun runtime error , then last resort recovery will begin the player sends an http get request to the provisioning/recovery url the header of this request contains information about the player, as well as the status of the storage devices and autorun files on the player this allows the request handler to determine the correct course of action based on the attributes and current status of the player if the request handler responds using an http code 200 with a non empty body, the player will use the response body as the new autorun script the autorun script should reboot the player once it performs necessary recovery tasks (the player will not automatically reboot) if the request handler responds with an http code 204, or an http code 200 containing an empty message body, the player will immediately reboot if the request handler does not respond, the player will continue to send requests for 30 minutes before rebooting alternatively, a reboot will occur after only 5 minutes if the autorun script has encountered an autorun runtime error this process will cycle indefinitely until an autorun script is received from the request handler diagram3 png appendix mdns multicast dns is a unique dns protocol developed for small networks these diagrams show the differences between a normal dns setup and a mdns setup note that multicast dns is not on by default in all networks screenshot 2024 03 22 at 1 17 38 pm png set up a recovery / provisioning server the following workflow diagram describes a simple request handler implementation this workflow assumes implementation of a database that can associate forced recovery flags with an individual device or group of devices a provisioning script a recovery script that first reformats the storage device a recovery script that does not reformat the storage device this workflow does not implement the following features different provisioning scripts depending on the deviceid or group (or other http get parameters) multiple provisioning or recovery autorun scripts for different storage screenshot 2024 03 22 at 10 46 21 am png autorun files docid 7vitoacfasnmpnozl0zbq