How to Backup Your OpenWrt Router When Built-in Tools Fail

In the past, I have followed a method of updating OpenWrt devices with an option to restore all installed packages and their configurations without needing to spend hours on reconfiguring and testing everything.

This method uses a simple script run in the terminal to generate a list of installed packages, followed by a web interface to generate a backup file used to restore everything.

As long as the backup file is generated correctly, the restoration process works well, but the problem arises when it isn’t!

On several routers with OpenWrt (24.10.x) that I worked with over recent weeks, I experienced a strange issue that caused me to rethink how I generate a backup file to later use to restore all packages and settings after updating OpenWrt to the latest version.

I discovered this issue the hard way when I wanted to extract a backup to retrieve some configuration from individual files. I noticed that the backup failed to extract correctly.

Generating (backup) archive – LuCI

Typically, when you generate a backup file of your configuration, you navigate to:

• System > Backup / Flash Firmware

From there, you simply need to click Generate archive to obtain your backup.

If you want to include an additional folder in your archive, click the Configuration tab, where you can specify an additional location to be included, with each entry on a separate line.

My current content looks as follows:

## This file contains files and directories that should
## be preserved during an upgrade.

# /etc/example.conf
# /etc/openvpn/
/etc/ssl/
/etc/cloudflared/
/etc/sysctl.d/
/etc/init.d/
/etc/config/
/root/
Copy

This can be found in the /etc/sysupgrade.conf file.

Modified files in /etc/config/ and certain other configurations are automatically preserved by OpenWrt, so you don’t need to explicitly include this folder.

I have tested numerous variations of generating a backup file, with and without some additional folders mentioned above. Each time, at some stage, the backup becomes corrupted.

The main problem is that this issue is unrepeatable (unable to reproduce using the same steps).

You can document all the steps you took until you encountered the issue, perform a factory reset on your router, and repeat them, yet you might not face the issue again—or you might encounter it much earlier.

The cause remains unknown.

Corrupted (backup) archive - LuCI

Returning to the generated archive of your backup.

Typically, after pressing the Generate archive button, your browser will automatically download the file:

• backup-OpenWrt-2025-09-01.tar.gz

After extracting this file using any available tool (such as 7Zip on Windows or Keka on macOS), you should see a folder containing /etc and /root.

Each of these folders will include plain text files that you can view with any software to access the settings.

The problem arises when you try to extract the file and end up with a single TAR file instead of folders and files. Further extraction attempts from this TAR file result in an error.

tar: Error opening archive: Unrecognised archive format
Copy

When I run file backup-OpenWrt-2025-09-01.tar.gz, the system recognizes it as a valid archive:

backup-OpenWrt-2025-09-01.tar.gz: gzip compressed data, from Unix, original size modulo 2^32 895035
Copy

Some people suggested that the web browser or operating system used might be the cause. I have tried on different computers and browsers, with the same results.

Interestingly, you can open this TAR file in VS Code using Text Preview, where you can see the content of each file amidst a lot of garbage. So, in the worst-case scenario, you can retrieve what you need from there. It seems that the files and folder structure are corrupted upon extraction.

Generating (backup) archive – terminal

I attempted to generate a backup directly on the router to eliminate any impact from an internet browser or operating system.

I followed the suggested method:

# Generate backup
umask go=
sysupgrade -b /tmp/backup-${HOSTNAME}-$(date +%F).tar.gz
ls /tmp/backup-*.tar.gz

Corrupted (backup) archive - terminal

Once the file was generated, I attempted to unpack it in the /tmp folder on the router:

tar -zxvf backup-OpenWrt-2025-09-01.tar.gz

and got

tar: invalid tar magic
Copy

Since some OpenWrt installations don’t include the latest or full version of the TAR command, I installed it:

opkg update
opkg install tar

Repeating my extraction command tar -zxvf, I get:

tar: This does not look like a tar archive
tar: Skipping to next header
tar: Exiting with failure status due to previous errors
Copy

Analysing corruption with AI

Running out of options and unable to pinpoint a specific package causing the issue, I used AI to analyse the extracted TAR file to see its suggestions:

Based on your provided summary and excerpt, the tar file (backup-OpenWrt-2025-08-20.tar) contains mostly valid OpenWrt config and init files, but there are signs of corruption:

• Binary junk and misplaced null bytes: Many files have trailing or embedded null bytes (\x00) and binary junk, which is not normal for text config files.
• File boundaries and padding: Some files appear to have excessive padding or are not properly terminated, which can confuse tar extraction tools.
• File size mismatches: The tar headers specify file sizes, but the actual content may not match, causing extraction errors.

Most likely cause of extraction failure:

• The corruption is probably due to improper file boundaries, excessive null padding, or truncated files, especially in binary files like .tdb or key files.
• If you see errors like Unexpected EOF or tar: Skipping to next header, it’s usually because the tar stream is interrupted or a file’s declared size does not match its actual content.

Alternative way of generating (backup) archive

While searching the OpenWrt forum and other sites, I came across various methods for generating a backup directly from the router.

sysupgrade -l | tar -czf backup.tar.gz -T -

Based on that, I built my file, which generates a valid archive with my backup files that can be extracted correctly, despite the official method of generating a backup (over a web browser or through the official command in the terminal) returning a corrupted file.

I created a gen_backup file in my /root folder and added execution rights with chmod +x gen_backup. The file contained:

# Generate backup
umask go=
sysupgrade -l -v | tar -czf /tmp/backup-${HOSTNAME}-$(date +%F).tar.gz -T -
ls /tmp/backup-*.tar.gz

Once the command runs correctly, I am presented with my backup file backup-OpenWrt-2025-09-01.tar.gz in my /tmp folder.

Now, I need to retrieve this file and save it locally.

Copying generated (backup) archive - SFTP

To copy the file from the router, I need to install FTP server.

opkg update
opkg install openssh-sftp-server

Now, with the preferred FTP client (I am using CyberDuck on macOS), I need to initiate an SFTP connection (on your SSH port, default 22), logging in using root credentials.

By heading to the /tmp folder, you can easily drag the file to your computer.

Locally, double-clicking on the downloaded file will extract it in the way it should have been originally, presenting you with folders containing config files.

If your file extracts correctly in such a manner, restoring your settings with the installed packages, as described, will work correctly.

Even if you change the device, and thus cannot restore using the described method, by extracting it locally and examining each config file, you can swiftly prepare your new device to function as it did on the old one.

The issue is very intriguing and is a head-scratcher for me.

I am trying to engage on OpenWrt Forum post #235434 to get this issue resolved; however, so far, nothing suggests the root cause and a possible long-term solution. If you cannot replicate the issue, it’s difficult to find the cause.

In the meantime, I’ve got a working backup solution that I need to stick with.

Regards.