Introduction

The beroNet SBC, Gateways and Cards can receive their configuration via TFTP, HTTP or HTTPS. This method can be used to automatically provision the devices. The basic concept is, that the same configuration files that are provided via the backup function, can be used to provision the device. This gives the user the possibility to configure the device in the way he wants via the GUI and then simply download the backup of this configuration and use it to provision multiple devices at once and automatic. 

The provisioning method has evolved throughout the firmware releases:

• Firmware 1 and 2 had HTTP/TFTP provisioning which needed to be triggered by using the API

• Firmware Version 3 introduced DHCP auto-provisioning

• Firmware Version 16 introduced a new API, XML - style of backups and single file provisioning

• Firmware Version 21 introduced HTTPS support using TLSv1.2

This Document provides a step by step guide on how to provision the beroNet SBC, Gateways and Cards.

Prerequirements

In order to provision beroNet devices you will need control over at least a web- or tftp-server. This server provides the configuration files either as plain files or generated via a script. Starting from firmware version 3 you will need control over a DHCP server, only if you want to use auto-provisioning via DHCP. 

Provisioning with Firmware 21.XX

The backup and provisioning uses a single XML file since firmware 16.XX. The structure of this file is explained here: XML Backup & Provisioning File

The first steps to setup a provisioning environment are:

1. setup a HTTP / TFTP server

2. configure a gateway / card in the way you want it to behave

3. download the XXX.config.xml file

4. put the XXX.config.xml file on the webserver

5. test if you can download the file with a browser

The XXX.config.xml files name contains several information. The structure of the name is:

one example is:

You can rename the file to something more simple, but it is very important that the suffix stays .config.xml, otherwise the provisioning won't work!  E.g. you can rename the file to

When the setup is ready and the file can be downloaded via a browser the next step is to inform a gateway about the location of this file. The gateway can receive information about the location via several ways:

• manual configuration via the GUI

• automatic configuration via the API

TLS encryption configuration

The new feature of the 21.XX firmware is to offer a TLS connection with the provisioning URL. To enable your device with the TLS encryption you must initially use the Device Redirect Service from beroCloud to generate and download the client and private certificate. This Service is explained here: https://beronet.atlassian.net/wiki/spaces/PUB/pages/1934098433/Device+Redirect+Service+and+Provisioning#Provisioning-over-TLS

Provisioning URL

In any case the location of the configuration file is a URL including the server and the filename. The beroNet devices support special variables that can be used in the URL:

• {MAC} - is replaced by the Ethernet MAC-Address of the device that requests the URL

• {MODULES} - is replaced by the modules of the device (with ‘none’ by empty module and with '_' between them)

• {SERIAL} - is replaced by the Serial Number of the device that requests the URL

IMPORTANT: {MAC}, {MODULES} and {SERIAL} need to be written in capital letters.

A URL could look like:

Let's assume {MAC} = D8:DF:0D:00:11:22, {MODULES} = bf4FXO_bf2t1e1_none and {SERIAL} = 1-01-0000000001

In this case the webserver should provide the file:

This enables the webserver to provide different config files to different devices, even though the same provisioning URL is set in each device. 

Manual configuration via the GUI

This method is very simple, you can manually configure the provisioning URL under Preferences→Provisioning with different settings:

• Provisioning on Boot: configures provisioning behavior during boot-up

  • never (off)  - does not automatically fetch the config file from above URL on reboot

  • once  - fetches the config file from above URL only once and then turns off provisioning on boot

  • always - fetches the config file from above URL on every boot

• Provisioning-URL: the URL of the provisioning server (see configuration above)

• HTTP User Agent: configures the User Agent used during the HTTP/S request (only available since 21.03 Firmware). As the Provisioning-URL, specials variables can be used:

  • {MAC}, {MODULES} and {SERIAL} as the Provisioning-URL

  • {FIRMWARE} - is replaced by the current installed firmware

• Polling interval in minutes

Open

Configuration via the API

The beroNet API is described here: Using the beroNet Gateway & Card API. For Provisioning just a few API commands are required:

• ProvisioningSetConfiguration  - sets the Provisioning URL, Mode and interval

• ProvisioningGetConfiguration - displays provisioning-configuration 

• ProvisioningTriggerConfig - triggers immediate provisioning

• ProvisioningTriggerFirmware - triggers immediate provisioning of firmware

• ConfigurationActivate - activates configuration-changes

A sample API Call looks like:

In this case 172.20.5.10 is the IP of the beroNet Gateway and 172.20.5.16 is the IP of the Provisioning Server. 

The API will return:

if the request has worked. Or an error if e.g. a mandatory parameter is missing:

You can also check via the API if the ProvisioningSetConfiguration  command has succeeded:

The following command pipe can be used to provision the device via the API:

1. set a provisioning URL for one time configuration updates

2. trigger the configuration fetch mechanism

3. activates the new configuration without reboot

Debugging TLS connection (only available since 21.03 Firmware)

Since the TLS connection can be tricky, the beroNet device offers three differential variables to lighten, debug and analyse it. Under Preferences → Miscellaneous, the Experimental Options entry accepts these three variables:

• openssl_debug=[0|1]

  • 0 is the default value and disable the debugging mode

  • 1 enables the debugging mode

• openssl_verifyhost=[0|1|2]

  • 0 does not verify the certificate’s name against host

  • 1 is used as debug feature

  • 2 is the default value and verifies the certificate's name against host

• openssl_verifypeer=[0|1]

  • 1 is the default value and verifies the authenticity of the peer's certificate

  • 0 does not verify the authenticity of the peer’s certificate

To debug an TLS connection, please follow the steps:

• add openssl_tls=1 as Experimental Options. Save and Activate.

• start a fulltrace

• reboot the device to start a provisioning

• download the fulltrace and looks for curl.provisioning.log file which contains the logs of the TLS connection

Open