How To: Customize a DAL Backup Configuration File

Background

The configuration backup file can be obtained from a DAL device using either the CLI, local web UI, or Digi Remote Manager. The backup file you get is a gzipped tarball with a .bin extension. This file can be extracted, the resulting contents edited, and re-compressed back into a tarball, then loaded onto the same Digi device you got the config backup from or any other Digi device of the same type/model (e.g. a config backup from an EX15W can be loaded onto any EX15W).

The contents of the config file, once extracted, contain everything from the device’s /etc/config/ directory. This includes:

• Config settings

  • /etc/config/accns.json

• custom scripts

  • /etc/config/scripts/ directory

• SSL certificates

  • /etc/config/ssl.crt and /etc/config/ssl.pem

• List of APN+SIM combinations that the device has successfully connected with

  • /etc/config/mm.json

• List of current DHCP leases (if network.advanced.dhcp_persistent_lease is enabled in the DAL device’s config)

  • /etc/config/dhcp.leases

Any/all of the above files can be edited once you extract the config backup
 

Step 1: Getting the config backup file
 

• Option 1: CLI
  • SSH/telnet onto the DAL device, type “a” to access the admin CLI, then run the following CLI command:
    • system backup /tmp/config_backup.bin 
  • Use SCP or some SCP tool (WinSCP, Putty, Filezilla, etc) to copy the backup config file onto your PC. Example SCP command to copy the backup config file from the DAL device to the Downloads/ directory on your PC:
    • scp admin@192.168.210.1:/tmp/config_backup.bin Downloads/
• Option 2:  shell
  • SSH/telnet onto the DAL device, type “s” to access the shell console on the DAL device, then run the following shell command:
    • /bin/backup_and_restore -b > /tmp/config_backup.bin 
  • Use SCP or some SCP tool (WinSCP, Putty, Filezilla, etc) to copy the backup config file onto your PC.
• Option 3:  Web UI
  • Open a web browser on your PC and go to the IP address of the DAL device to access its web UI
  • Once logged in, navigate to the System → Configuration Maintenance page
  • Click the Save button and save the resulting .bin file onto your PC
• Option 4: Digi Remote Manager
  • Login to Digi Remote Manager. Lookup the DAL device, click its IDs, then click the Console tab to remotely access the device’s Admin CLI
  • Run the following CLI command, taking note to store the config backup in a location on the DAL device’s filesystem that DigiRM has access to (e.g. /var/log/)
    • system backup /var/log/config_backup.bin
    • ​
  • Click the Files tab from the DeviceUI in DigiRM, then click the directory you put the config backup file in. Click on the config backup file, then click the download button in DigiRM.
    • 

Step 2: Extracting the config backup file

We will cover using the tar command to extract the config backup file while retaining the file ownership.

• tar - Linux/Mac command. We recommend you put the config backup file into a directory by itself, so it’s easier to keep track of the file contents
  
  mkdir -p ~/Downloads/DAL_config_backup/
mv ~/Downloads/config_backup.bin ~/Downloads/DAL_config_backup/
cd ~/Downloads/DAL_config_backup/
sudo tar -zxvf config_backup.bin

Step 3: Customization options

Below are some noteworthy customization options you may want to make to the config backup file once you have extracted it. As mentioned in the background info above, this config backup contains the full /etc/config/ contents from the DAL device, so there may be other customization options you find outside of what is listed below.
 

Change config settings

The etc/accns.json file contains the entire set of non-default configuration settings on the DAL device you pulled the config backup from. Meaning, any config settings the user made on the device that deviate from the default firmware config settings will be included in the accns.json file. As the file extension implies, this is a JSON-formatted config file. You can edit/remove/add anything in this file, but care should be taken that:

1. The file is JSON-compliant. You can use an online JSON validator like https://jsonlint.com/ to copy/paste the accns.json file into and verify the syntax is correct

2. The contents are valid configuration settings.  All of the values listed in the config backup will be correct, since they were pulled from a DAL device that could parse the config file. However, if you make any edits to the accns.json file and add settings that weren’t there before, ensure you have the proper names and paths to the config settings you’re adding.
   
   To get a reference of the config settings available, you can run config dump from the shell console of a DAL device. The output from that command is a key-value listing of all available config settings. You can configure any of these in the accns.json file, just format it for JSON.   For example:  If you want to set the APN by configuring the network.interface.modem.modem.apn.0.apn setting to testAPN123, it would look like this in the accns.json file:

{
    "network": {
        "interface": {
            "modem": {
                "modem": {
                    "apn": [{
                        "apn": "testAPN123"
                    }],
                    "apn_lock": true
                }
            }
        }
    }
}

Adding custom scripts

The /etc/config/scripts/ directory will contain any Python scripts the user has loaded onto the DAL device from the web UI, CLI, or DigiRM. You can add/edit/remove these python scripts just as you would if you were interacting directly with the DAL device. These scripts can be run either automatically or manually on the DAL device using several options. See user guide link below for details on running Python scripts:

https://www.digi.com/resources/documentation/digidocs/90002344/default.htm#containers/applications-cont.htm
 

Applying config backup to other DAL device types

As mentioned in the background section above, these config backup files can only be loaded onto DAL devices of the same type/model as the device the file was pulled from (e.g. a config backup file from an EX15W can only be loaded onto other EX15W units, not other DAL devices like the TX54 or IX10). This is because each DAL device has unique schema validations and settings it uses. That said, the vast majority of configuration settings are common across DAL devices.

If you trust that your configuration settings are common to all DAL products and want to load the config backup file onto other DAL models/types, you can add the target product types to the tmp/ directory in the extracted contents of the config backup.

The easiest way to do this is to copy the existing file in the tmp/ directory and rename it to include the target product type in the filename. For example, to allow the config backup file to be loaded onto an IX10 unit even though it was downloaded from an EX15W, you would create a file in the tmp/ directory with IX10 in the name like so:

$ ls
config_backup.bin  etc  tmp
$
$ ls tmp/
Digi-EX15W-21.5.56.106-2021-07-08
$ cat tmp/Digi-EX15W-21.5.56.106-2021-07-08 
$ cp tmp/Digi-EX15W-21.5.56.106-2021-07-08 tmp/Digi-IX10-21.5.56.106-2021-07-08 
$ ls tmp/
Digi-EX15W-21.5.56.106-2021-07-08  Digi-IX10-21.5.56.106-2021-07-08
$

Step 4: Re-compress the config backup

• tar (Linux/Mac command)
  • The below example assumes your config backup files are in a directory called
    ~/Downloads/DAL_config_backup/
    • ​cd ~/Downloads/DAL_config_backup/
    • ls tmp/
    • sudo tar zcvf config_backup_new.bin etc/config tmp/<the file name that is in the tmp directory from the previous command>