Back Up and Restore OpenWrt Configuration with LuCI and SSH

I separate two operations that are often both called an “OpenWrt backup.” This guide covers configuration files, not a block-level NOR/NAND image. The goal is to keep an archive that can be carried into an installation or restored after an upgrade.[24]

Scope and prerequisites

I need access to LuCI or SSH/console, plus the ability to manage configuration, packages, services, and logs. Extroot or additional overlay layouts require extra consideration; the official page points block-level work to the Generic backup guide instead.[24]

sysupgrade -b collects files listed by OpenWrt's backup configuration. It is not a raw flash image, does not automatically guarantee that every user-installed package will return, and is not a bootloader or calibration-area recovery method.[24]

Method 1: customize and back up with LuCI

1. Review the file list

1. Open LuCI → System → Backup / Flash Firmware → Configuration.[24]
2. Add or remove the files and directories to keep, then click Submit.[24]
3. Click Open list... to see the effective list.[24]
4. Read it back and make sure every required file is present before creating an archive.[24]

2. Download the archive

1. Go to LuCI → System → Backup / Flash Firmware → Actions → Backup.[24]
2. Click Generate archive to download the configuration archive to the computer.[24]
3. Store the archive in a separate backup location rather than leaving the only copy on the router.[24]

3. Restore an archive

1. Go to LuCI → System → Backup / Flash Firmware → Actions → Restore.[24]
2. Click Choose File and select the saved archive.[24]
3. Click Upload archive... to upload it to the router.[24]

Method 2: customize and verify over SSH

When I want terminal control, I can add files to /etc/sysupgrade.conf, inspect the list that sysupgrade will save, and only then create the archive:[24]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# Add files/directories
cat << EOF >> /etc/sysupgrade.conf
/etc/sudoers
/etc/sudoers.d
EOF

# Edit backup configuration
vi /etc/sysupgrade.conf

# Verify backup configuration
sysupgrade -l

I read the sysupgrade -l output to catch missing paths. Add sensitive files such as /etc/sudoers only when needed, and keep the resulting archive out of Git and public repositories.[24]

Create and download a command-line backup

1
2
3
4
5
6
7
8
9

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

# From the client, download backup
scp root@openwrt.lan:/tmp/backup-*.tar.gz .
# On recent clients, it may be necessary to use the -O flag for compatibility reasons
scp -O root@openwrt.lan:/tmp/backup-*.tar.gz .

/tmp is normally a tmpfs, so I download the file to the client immediately. The final two scp commands are compatibility alternatives: try the first, then use -O if a newer SSH client does not work with the device's older transfer mode.[24]

Restore over SSH

First copy the archive from the client to the router, confirm the filename, restore it, and reboot to apply the changes:[24]

1
2
3
4
5
6
7

# Upload backup
scp backup-*.tar.gz root@openwrt.lan:/tmp

# Restore backup
ls /tmp/backup-*.tar.gz
sysupgrade -r /tmp/backup-*.tar.gz
reboot

I do not restore until I have checked both the target router and the archive. A bad archive can remove network access or management permissions, so I prepare a console or another management path before applying it.[24]

Audit what is kept

The backup combines multiple sources by default. For an audit, use the commands listed by the OpenWrt documentation:[24]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# Automatically detected modifications
opkg list-changed-conffiles

# System configurations supplied by individual packages
grep -r -e . /lib/upgrade/keep.d

# User configuration to edit if necessary
grep -e . /etc/sysupgrade.conf

# Obsolete settings no longer supported
uci show luci.flash_keep

Important limits

This is file-level backup/restore, not a raw flash backup. Extroot needs additional measures, while bootloader, ART/NVRAM, factory data, and MTD layouts belong to a separate model-specific block-level procedure. After restoring, I recheck the management IP, Wi‑Fi, firewall, packages, and services instead of assuming the archive covered everything.[24]

Source

Original source: [Backup and restore]¹, published/updated 2026-08-05.[24]

Sources

[24] https://openwrt.org/docs/guide-user/troubleshooting/backup_restore — OpenWrt Wiki: Backup and restore