1.Overview of Clone Packages

1.1 What is a Clone Package?

A Clone Package is a comprehensive system snapshot of a "Template Gateway." Unlike a simple configuration backup, it captures the entire operational state of the device.

1.2 What Exactly Gets Cloned?

1. Bootloader Partition: Core hardware initialization and OS.
2. Kernel Partition: The Linux kernel.
3. Rootfs Partition (Read-only): The factory-standard operating system.
4. Overlay Partition (Read/Write): All user-level changes, including installed Docker containers, Python apps, custom scripts, and all network/system configurations.

1. Hardware-Bound Identifiers: Hardware-derived identifiers such as physical MAC addresses,IMEI values, and device serial numbers (SN) are typicallypreserved by the target hardware and are not intended to be overwritten by the clone package.
2. Real-time Volatile State: Temporary runtime data such as active process states,RAM-resident sessions, and transient files under /tmpare not preserved across cloning operations.
3. Live Cellular Connection States: Temporary modem session states, network registration,dynamic signal metrics (e.g., RSRP/RSRQ), and active carrier attachment states are not preserved.
   

1. Network conflicts
2. Authentication failures
3. Duplicate cloud registration
4. MQTT client collisions
   

1. Identity Duplication: Cloning replicates everything, including IP addresses, SSH keys, SSL certificates, and device-specific credentials. In large-scale deployments, failure to regenerate device-specific identities may result in network conflicts,authentication failures, or duplicate device registration.
2. Hardware Binding: Clone package are hardware-specific. A clone package created on an EG5120 can only be restored to another EG5120 with the same hardware variant and memory configuration. Even if you are deploying to the same base model line(e.g.,EG5120), a package created on a unit with 2GB RAM cannot be restored to an EG5120 variant with 1GB of RAM. Doing so will result in a restoration failure.
3. Data Overwrite: Restoring a clone package will permanently erase all existing data on the target device.
   
4. Baseline Reset Transformation: Successful installation of a clone package establishes a new system baseline. Consequently, the standard "Factory Reset" function will no longer return the device to its original out-of-the-box state, but will instead revert it to this specific cloned configuration. To restore the original factory firmware state, a factory image reinstallation is required.

3. Core Value

• Large-Scale Efficient Deployment: By using clone packages to batch replicate systems, deployment efficiency and accuracy can be significantly improved.
• Rapid Recovery from Extreme Failures: In extreme situations where the gateway experiences business interruptions due to hardware replacement or system crashes, a clone package can restore the complete operating environment within 1 hour, maximizing business continuity.

4.Clone Package Creation Process

4.1 Preparing Stage

Step 1: Select the Template Gateway

For ensuring consistency in the cloned environment，choose a device that is identical to the target gateway model (e.g., EG5120_C2FCZ) as the template. 

Upgrade the Gateway Firmware (Recommend)

1. Requirements: Following the prerequisites, the clone package functionality requires the firmware version to be V2.4.0 or higher. You need to check and update your firmware version first.

2. Operation Steps:

• Log in to the gateway's web management interface (default address: 192.168.0.1).
• Navigate to "System > Update," and upload the V2.4.0 firmware file (e.g., factory-eg5120_2.4.0_arm64.deb).This operation will upgrade the read-only system partition to the target version, restore the template gateway to the factory state of the target version, and help reduce the space occupied by clone package and system backups.

• After the upload is complete, click "OK" to proceed with the firmware upgrade.

• After the installation is complete, click "OK" to reboot the device.

•  If succeed, the new firmware version will be updated, and can be seen form the "System Information" page.

Step 2: Create a Sudo account

Creating a clone package requires system permissions in advance. For getting the administrative access, please ensure that you are using an account with sudo privileges to execute the relevant commands.

• Navigate to "System > User Management", Click "+" to create a Sudo user account.

• Make sure to click the "Save & Apply" button to save the account. 

Step 3: Deploy Applications and Validate Configuration

1. Application Deployment: On the template gateway, install and configure all necessary applications according to actual business needs.
   

2. Function Validation: To avoid any abnormal states in the clone package, a testing must be conducted to ensure all applications and configurations are functioning correctly.Crucially, after installing all applications, ensure the remaining available space on the overlay partition is 50% or more.
   
   You can use the df command to verify the overlay partition's remaining space.
   

   Robustel@Edge-Gateway:~$ df
   Filesystem        1K-blocks   Used Available Use% Mounted on
   /dev/mmcblk2p4       256512 256512         0 100% /rom
   devtmpfs             908748      0    908748   0% /dev
   tmpfs                976780      0    976780   0% /dev/shm
   tmpfs                390716  25912    364804   7% /run
   tmpfs                  5120      4      5116   1% /run/lock
   /dev/mmcblk2p9     13074580 168160  12220472   2% /overlay
   /dev/mmcblk2p6          256    256         0 100% /middle/extend
   overlayfs:overlay  13074580 168160  12220472   2% /
   /dev/mmcblk2p7        14585     14     13425   1% /misc
   /dev/mmcblk2p8       287237  39529    228252  15% /data
   tmpfs                976780    144    976636   1% /tmp
   tmpfs                976780    184    976596   1% /var/config
   tmpfs                976780      0    976780   0% /var/socks
   tmpfs                976780     84    976696   1% /var/status

4.2 Create the Clone Package

The clone package is created using the rbt-system-mgmt clone create command, which supports custom storage paths and optional backups

Parameter Description Example

• Snapshot: A manually created and restored system archive, allowing users to save and revert to a specific system state.
• Backup: A manually created but automatically restored system copy, designed for the system to invoke automatically upon failure to ensure service continuity.
• Factory Backup: A manually restored baseline image that returns the device to its original state, used for data purging or as a last-resort recovery method.
• Command Example: Save the clone package to a USB storage device and include backup files.
  

sudo apt-get clean
rm -rf /var/lib/apt/lists/*

Step 2: Generation

sudo rbt-system-mgmt clone -D /media/sda1

/dev/mmcblk2boot0 is the active uboot partition!
creating clone...
tar: /overlay/upper/var/agentx/master: socket ignored                                                       ]   4% ETA 0:03:05
 950MiB 0:02:44 [5.76MiB/s] [==============================================================================>] 100%
Archive created successfully: /media/sda1/EG5120_C2FCZ-clone-2.4.0.20251017.e686882b.tar.gz
TYPE=clone
RAW=273
COMPRESSED=253
TAR_SIZE=264294910
HASH=58a1cc9bcd0d3d583908739ee317f5ac244f62862f03a60fa6b2a0c7f4b55e1a
SYS_VERSION=20250927-g87f4040+
MODEL=EG5120-C2FCZ
CREATE_TIME=1760695903
VERSION=2.4.0.20251017.e686882b
SECURE_BOOT=false

4.3 Validate & QA (Crucial Step)

Step: check the metadata of the clone package.（Recommend）

rbt-system-mgmt clone info /media/sda1/EG5120_C2FCZ-clone-2.4.0.20251017.e686882b.tar.gz
TYPE=clone
RAW=273
COMPRESSED=253
TAR_SIZE=264294910
HASH=58a1cc9bcd0d3d583908739ee317f5ac244f62862f03a60fa6b2a0c7f4b55e1a
SYS_VERSION=20250927-g87f4040+
MODEL=EG5120-C2FCZ
CREATE_TIME=1760695903
VERSION=2.4.0.20251017.e686882b
SECURE_BOOT=false

Step 1: Restore to a Test Device

rbt-system-mgmt clone restore /media/sda1/EG5120_C2FCZ-clone-2.4.0.20251017.e686882b.tar.gz
The operation would result in removing the existing backup and snapshot, and the current system will be overwritten. (Y/N) Y
checking for restore validity...
OK!
Extracting clone into directory '/overlay/restore'...
Start using clone to restore the system...
tar: Removing leading `/' from member names
252MiB 0:00:07 [31.7MiB/s] [==========================================================================================>] 100%
The system version is the same, skip restore system image.
/overlay/.rbt-system-mgmt-blocked-list will be removed.
/overlay/.rbt-system-mgmt-failback will be removed.
/overlay/lost+found will be removed.
done!
The system has been cloned successfully. Reboot is required to take effect.
root@Edge-Gateway:~# reboot

Step 2: Verification Checklist

• Reboot the gateway. The RUN LED will flash rapidly during installation.When the LEDs display a chasing light pattern, the installation is complete. Remove the USB drive at this point, and the device will reboot again
  

• Execute the following command in the device to initiate a reboot:
  

Robustel @Edge-Gateway:~$ reboot

• After the system reboots, use the command below to check the results of the restoration process:

root@Edge-Gateway:~# rbt-system-mgmt restore status
Restore command: rbt-system-mgmt clone restore /overlay/clone/EG5120_C2FCZ-clone-2.4.0.20251017.e686882b.tar.gz at 2025-10-17 18:32:26
Restore result: success at 2025-10-17 18:33:17
root@Edge-Gateway:~#

• Once recovery is complete, perform a thorough audit of the system, applications, and configurations on the test gateway to ensure they are fully synchronized and consistent with the template gateway.

5.Troubleshooting：What if it fails？

5.1 Common Creation Failures

1. Insufficient Storage Space
   

1. Cause: The device has less than 50% free overlay space, or the destination USB drive is full.
   

2. Solution: Delete unnecessary logs/data from the gateway or use a higher-capacity USB drive.

2. Incorrect File System Format
   

1. Cause: The external USB drive is not formatted correctly.
   

2. Solution: Ensure the USB drive is formatted to ext4 before attempting to create the clone.

3. Write Permission Errors
   

1. Cause:The system cannot write to the designated path.
   

2. Solution: Ensure the USB is correctly mounted (e.g., /media/sda1) and that you are using sudo to execute the command.

5.2 Common Restoration Failures

1. Hardware or RAM Mismatch
   
1. Cause: The clone package was created on a different model or a device with a different RAM size.
   
2. Solution: Only deploy clone packages to identical hardware models ( Not only the Device Type, but also RAM size). 
2. Firmware Incompatibility
   
1. Cause: The target device is running an unsupported firmware version.
   
2. Solution: Ensure the target device is upgraded to RobustOS Pro v2.4.0 or higher before restoration.
3. Premature Media Removal
   
1. Cause: The USB drive was unplugged before the reboot and background restoration processes were finished.
   
2. Solution: Keep the USB drive inserted until the device fully reboots and the status indicator light confirms completion.
4. Corrupted Clone Package
   
1. Cause: The package file is broken or incomplete.
2. Solution: Run rbt-system-mgmt clone info <file> to verify the package metadata. If it fails, recreate the clone from the template device

Document Feedback