LinuxBox Backup Restore User Guide

Application Scenarios

During the use of LinuxBox devices, you may encounter the following situations: the device has installed a large number of applications, or connected a large number of devices, but due to system upgrades or other reasons, you need to flash the firmware, or replace with a new device. In traditional ways, you need to reinstall and configure all applications one by one, add devices one by one, which is tedious and time-consuming.

To solve this pain point, LinuxBox provides a backup/restore mechanism to help users quickly restore the system state before flashing.

Technical Principles

LinuxBox's backup/restore mechanism is based on the following core technologies:

1. Data Backup Mechanism

• Application Data Backup: Saves user application configuration files, databases, user accounts, etc.
• Runtime State Backup: Saves user application runtime states, enable states, etc.
• System Data Backup: Backs up system configurations, WIFI settings, and other critical system information

2. USB Automated Deployment

• USB Installation Mechanism: Supports automatic application installation from USB devices
• System Recovery Mechanism: Automatically identifies and restores backed up system configurations

Operation Steps

⚠️ Note: Please confirm that there are no channel switching operations or zigbee working mode modification operations before starting the backup. If there are, it is recommended to wait 2-3 hours after the program runs before backing up data

Preparation Phase

1. Prepare Storage Device

• Prepare a USB storage device with sufficient capacity (recommended to use a blank disk)
• Ensure the USB device is properly formatted and can be read/written normally

2. Preparation Phase

• If you want silent backup data, you can create a directory R3Backup in the USB drive in advance
• And create an empty file named .enable-backup under the R3Backup directory. This file will be automatically deleted after the backup is completed

/mnt
└── R3Backup
    └── .enable-backup

Backup Phase

3. Connect Device

• Insert the USB device into the USB interface of LinuxBox
• Wait for the system to recognize the storage device. If recognition is successful, the LED on Linuxbox will show in the form of slow green light flashing

4. Silent Backup Method

• Silent Method: After following step 2, the system will automatically backup application data, system configurations, and application states

5. Manual Backup Method

• Graphical Interface Method: Launch the backup function through the ​​3R-Installer.app application

• Command Line Method: Use USB Debug board to connect to LinuxBox, use command line tools to execute backup commands

supervisor setting backup

• The system will automatically backup application data, system configurations, and application states

⚠️ Note: Linuxbox defaults to keeping a maximum of 5 latest backup files

System Reinstallation Phase

6. Execute Flashing Operation

• If you need to flash Linuxbox for upgrade, follow the standard process to flash LinuxBox
• Ensure the flashing process is complete and error-free

• If you need to factory reset LinuxBox, you can use ​3R-Installer.app operation, or call /lib/armbian/factory-reset.sh through commands to complete

Prepare Recovery Resources

7. Prepare Installation Packages

• Put the .deb software packages that need to be installed into the R3Install directory of this USB device. The required deb files for installation can be obtained from https://github.com/thirdreality/LinuxBox-Installer

• If you need to silently restore backed up content, you need to create an empty file named .enable-restore under R3Backup. This file will be automatically deleted after the restore is completed

/mnt
├── R3Backup
│   ├── .enable-restore
│   └── setting_20250819035544.tar.gz
└── R3Install
    ├── board_firmware_1.04.01.deb
    ├── hacore_2025.6.6.deb
    ├── hacore-config_2025.6.3.deb
    ├── otbr-agent_2025.08.15.deb
    ├── python3_3.13.3.deb
    └── zigbee-mqtt_2.5.1.deb

Recovery Phase

6. Silent Restore Method

• After the LinuxBox system starts, insert the USB device containing backup data
• If the USB drive is successfully recognized, the LED on Linuxbox will show in the form of slow green light flashing
• The system will automatically detect backup files on the USB drive. If multiple backup files exist, it will select the latest one for restore operation
• Wait for the system to complete application installation and configuration recovery. If the user previously configured valid WIFI, when the system completes restore, the LED usually shows in the form of steady blue light

7. Manual Restore Method

• Graphical Interface Method: Restore backup function through the ​​3R-Installer.app application

If there are multiple backup files in the USB drive, users can select the file that needs to be restored according to the timestamp

• Command Line Method: Use USB Debug board to connect to LinuxBox, use command line tools to execute backup commands

supervisor setting restore

If multiple backup files exist, it will select the latest one for restore operation

• Wait for the system to complete application installation and configuration recovery. If the user previously configured valid WIFI, when the system completes restore, the LED usually shows in the form of steady blue light

Precautions

• During the backup process, please ensure the USB device has sufficient storage space
• Before flashing, please confirm the backup has been successfully completed
• Do not disconnect the USB device during backup and restore processes
• It is recommended to perform regular backups to ensure data security

Troubleshooting

During backup/restore, issues may occur due to the following special cases:

• Updating the zigbee/thread board firmware using board_firmware.deb;
• Restoring a backup from this device onto another different device;

Here are the fixes:

ZHA Issue

When this happens, go to Settings and you will see a new Home Assistant repair issue: "Zigbee network settings have changed".

Click the issue and select "Restore backup (recommended)". Then follow the on-screen prompts to proceed.

Zigbee2MQTT Issue

On the Dashboard, you may see two "Zigbee2MQTT Bridge" entries. Click the greyed-out, unavailable one and delete it as prompted.

Thread Issue

Go to Settings > Thread > Configuration. If Preferred network is empty, select OpenThread from the list, then click:

• Add to preferred network
• Use route for Android+IOS credentials

Bluetooth Issue

Under "Needs attention", click Delete from the dot menu.

In the "Discovered" card, click Add and follow the prompts.

Technical Advantages

LinuxBox's backup/restore mechanism has the following advantages:

• One-click Operation: Simplifies traditional manual backup and restore processes
• Intelligent Recognition: Automatically identifies and processes different types of application data
• Integrity Guarantee: Ensures complete system state recovery
• Flexibility: Supports multiple backup and restore methods

By properly utilizing this mechanism, users can significantly improve system maintenance efficiency and reduce the workload of reconfiguration.