System Release 13.3 adds the ability for an SM to get it’s configuration via DHCP option 66. This can be used for the initial configuration of an SM as well as managing the configuration of SMs on an ongoing basis. Here is how it works in brief.
- When the SM boots up, if it is set to use DHCP client, it will send out a DHCP Discover packet which includes a request for DHCP Option 66.
- In case of a brand new SM out of the box, the DHCP Discover packet is sent out if the SM connects to an AP using Installation Color Code (ICC), even though DHCP client is not enabled in factory default config.
- An appropriately configured DHCP server will respond with a DHCP Offer and include a URL in response to the Option 66 request. The URL should point to the configuration file.
- The device will download the configuration file and apply it. The device will reboot automatically if needed. (Note: this requires “rebootIfRequired” flag to be added to the config file. See “Creating the Golden Config File” section).
Note: The out-of-box scenario will work only after Cambium starts shipping 13.3 or newer version from factory. Until then, you will have to upgrade the device to 13.3 or later yourselves to use this feature.
Setting It Up
In summary, the steps are the following:
- Create the golden config file(s)
- Host it on an TFTP/FTP/HTTP/HTTPS server
- Configure the DHCP server to return the URL of the golden config file in option 66
- Enable ICC on AP. If Authentication is enabled on AP, enable ‘Disable Authentication for SM connected via ICC’ option on AP to bypass authentication for this SM
When the SM boots up, it will get the URL for the golden config from the DHCP server via option 66, download it and apply it.
If all the SMs are configured exactly the same, then you can create just one golden config file that can be used with all SMs.
If the SMs are not configured the same, see if it is possible to group the SMs such that SMs with the same configuration are served by the same DHCP pool. You can then create multiple golden config files and configure the DHCP server to use the appropriate config file for each pool.
You can also create one config file per SM. This provides the most flexibility, but is practical only if you have a software tool/script to generate the config file for each MAC address. The files should be named [mac].cfg where [mac] is the MAC address of the SM, and stored in the same directory on the file server. The DHCP server should be configured to return the directory name ending with a ‘/’ in option 66. The SM will automatically add “[mac].cfg” to the path and get its config file.
If some configuration is unique per SM, but rest of the configuration is common, you can stage the SMs with the unique part, and use option 66 to manage the common part. For example, if each SM needs to have its coordinates set, don’t include the coordinates in the golden config file. Instead, configure the coordinates for each SM manually. Now you can manage the rest of the configuration using DHCP option 66.
Creating The Golden Config File
The easiest way to create the golden config file is to configure an SM, export its configuration and edit it. To export the configuration file from the GUI of the SM, go to “Configuration | Unit Settings” tab, go to the “Download Configuration File” section and click on the “[mac].cfg” link. This will give you a text file in JSON format. You can edit this file in a text editor but it’s easier to use a JSON editor like https://www.jsoneditoronline.org/.
You can strip down the config file to remove sections and entries that you don’t care about, and keep only the items that require changes. If there are many required changes, it can easily get confusing. To identify the exact items that you changed, you can first reset the SM to factory default, export the config file, make the necessary changes, export a second config file, then use a tool like WinMerge (http://winmerge.org/) to identify the differences.
The config file contains the following informational entries at the top level.
"cfgUtcTimestamp": "cfgUtcTimestamp", "swVersion": "CANOPY 13.3 (Build 15) SM-AES", "cfgFileString": "Canopy configuration file", "srcMacAddress": "0a-00-3e-a2-c2-74", "deviceType": "5.4/5.7GHz MIMO OFDM - Subscriber Module", "cfgFileVersion": "1.0"
You can delete the “cfgUtcTimestamp”, “swVersion”, “srcMacAddress” and “deviceType” lines if you wish. Do not delete the “cfgFileString” and “cfgFileVersion” entries.
Next, create an object named “configFileParameters” at the top level. Under that, add a parameter called “rebootIfRequired” and set it to true. This tells the SM to reboot automatically if a reboot is needed to apply the new configuration.
A sample configuration file that has been edited for use via DHCP option 66 is given below.
{
"userParameters": {
"smNetworkConfig": {
"networkAccess": 1
},
"location": {
"siteName": "Test site"
},
"smRadioConfig": {
"frequencyScanList": [
5475000,
5480000
],
"colorCodeList": [
{
"colorCode": 42,
"priority": 1
}
]
},
"networkConfig": {
"lanDhcpState": 1
}
},
"cfgFileVersion": "1.0",
"cfgFileString": "Canopy configuration file",
"configFileParameters": {
"rebootIfRequired": true
}
}
When configuration is imported, only the items that exist in the configuration file are modified. Parameters that are not in the imported file are not changed. If you wish to revert those settings to their factory default values, please add a “setToDefaults” item under “configFileParameters” section with a value of true.
"cfgFileVersion": "1.0",
"cfgFileString": "Canopy configuration file",
"configFileParameters": {
"rebootIfRequired": true,
"setToDefaults": true
}
If you would like the SM to fetch the configuration file on each boot up even when not connecting to AP via ICC, set “Network Accessibility” to “Public” and “DHCP State” to “Enabled” in the “Configuration | IP” page before exporting the configuration.
Hosting The Configuration File(s)
Copy the golden configuration file to an FTP, TFTP, HTTP or HTTPS server. This location can be password protected; you just have to include the user name and password in the URL that you will set for option 66 in the DHCP server in the next step.
DHCP Server Configuration
Configure your DHCP server to return the full URL to the golden config file as the value of DHCP option 66.
The following example explains how to make the change for Windows Server 2008. Adapt it to your specific DHCP server.
- Click “Start | Administrative Tools | DHCP”
- If you have multiple “Scopes” defined, identify the correct “Scope” that will serve IP addresses for the SMs
- Right click on “Scope Option” under the correct “Scope” and select “Configure Options”
- In the “Scope Options” dialog, scroll down to “066 Boot Server Host Name”, select the checkbox and enter the full URL to the golden config file as the “String value”. Then click “OK”.
- In the DHCP snap-in window, right click and “Refresh” to see the DHCP option 66 in the list of DHCP options
Supported URL Formats
FTP, TFTP, HTTP and HTTPS URLs are supported. Some examples are given below.
- ftp://10.120.163.253/canopy.cfg
- ftp://admin:admin123@10.120.163.253/canopy.cfg (login as admin with password admin123)
- tftp://10.120.163.253/canopy.cfg
- http://10.120.163.253/golden-config.cfg
- https://10.120.163.253/smconfig/golden-config.cfg
You can also specify the URL pointing to a directory and not a specific file. Terminate the URL with a ‘/’ to indicate that it is a directory and not a file. Use this format when each SM has its own individual config file. The directory should contain files named “[mac].cfg”, one for each SM.
For example:
-
- ftp://10.120.163.253/smconfig/
In this case, the SM will append “[mac].cfg” to the path and try to get that file. For example, if the SM’s MAC address is 0a-00-3e-a2-c2-74, it will request for ftp://10.120.163.253/smconfig/0a003ea2c274.cfg. This mechanism can be used to serve individual config file for each SM.
Troubleshooting
- Make sure the SM is running 13.3 or newer version of software.
- If the SM has factory default config, confirm ICC is enabled on the AP, so the SM can connect to it.
- If the SM is connecting to the AP using a color code other than ICC, make sure the SM has “Network Accessibility” set to “Public” and “DHCP State” set to “Enabled” in the “Configuration | IP” page. Note:
If Authentication is enabled on AP, confirm ‘Disable Authentication for SM connected via ICC’ option is enabled on AP.
- Make sure the golden config file does not turn off “Network Accessibility” or “DHCP State”. If it does, the SM will no longer request the config file when it is rebooted.
- Check the event log of the SM to see the status of the configuration file import including any errors that prevented it from importing the file.
- Capture the DHCP Offer packet from the DHCP server to the SM and verify that Option 66 has the expected URL.
