OpenWrt 25.x

This guide is designed to assist you in installing, configuring, and managing OpenWrt 25.x on your router. It covers essential topics from initial flashing to network configuration, security settings, and storage expansion.

1. Introduction to OpenWrt 25.x

OpenWrt 25.x represents a modern release of the Linux-based embedded operating system for routers. Key characteristics of this version include:

  • Linux Kernel: Updated kernel supporting newer hardware and security updates.
  • Firewall4 (fw4): Utilizes nftables by default, replacing the legacy iptables-based firewall3.
  • DSA (Distributed Switch Architecture): Fully standardizes switch configuration, treating each physical port as an independent network interface.
  • WPA3 Security: Out-of-the-box support for modern wireless encryption standards.
  • apk Package Manager: Replaces the legacy opkg package manager, providing faster dependency resolution and signature verification.

2. Installation and Flashing

Before proceeding, verify that your device is supported by checking the OpenWrt Table of Hardware (ToH) on the official openwrt.org website.

Step 1: Download the Correct Firmware

OpenWrt provides two primary image types for each device:

  • Factory Image: Used when upgrading from the original manufacturer’s (OEM) firmware to OpenWrt.
  • Sysupgrade Image: Used when upgrading an existing OpenWrt installation to a newer version.

Step 2: Flash the Firmware

Method A: Via the OEM Web Interface

1. Connect your computer to one of the router's LAN ports using an Ethernet cable.
2. Log into your router’s existing administrative web interface.
3. Locate the "Firmware Upgrade" section.
4. Upload the OpenWrt Factory image and proceed.
Note: Do not unplug or power off the router during this process, as it can corrupt the device bootloader.

Method B: Via existing OpenWrt (Sysupgrade)

If you are already running an older version of OpenWrt:
1. Navigate to System -> Backup / Flash Firmware.
2. Under "Flash new firmware image", upload the Sysupgrade image.
3. Uncheck "Keep settings" if you want a clean install to avoid configuration conflicts.

3. Initial Setup and First Login

Once the router reboots (which may take 2 to 5 minutes), it will assign your computer an IP address via DHCP.

Logging in via the Web Interface (LuCI)

1. Open a web browser and navigate to http://192.168.1.1.
2. By default, there is no password. Click Login.
3. Go to System -> Administration to set a strong router root password.

Logging in via Command Line (SSH)

To manage the router via terminal:
1. Open your terminal or SSH client (such as PuTTY).
2. Connect to the router:

   ssh [email protected]

3. Enter the password you configured in LuCI.

4. Basic Network Configuration

WAN Configuration (Internet Access)

Most home connections use DHCP, but some ISPs require PPPoE or Static configurations.

Via LuCI:

1. Navigate to Network -> Interfaces.
2. Click Edit next to the WAN interface.
3. Select your protocol (e.g., DHCP client, PPPoE, or Static address) under Protocol and click Switch protocol.
4. If using PPPoE, enter the username and password provided by your ISP.
5. Click Save and then Save & Apply.

Via CLI (Example for PPPoE):

uci set network.wan.proto='pppoe'
uci set network.wan.username='your_username'
uci set network.wan.password='your_password'
uci commit network
service network restart

LAN Configuration

To change the local IP address of your router to avoid conflicts with other networks:

1. Navigate to Network -> Interfaces.
2. Click Edit next to the LAN interface.
3. Modify the IPv4 address (e.g., 192.168.5.1).
4. Click Save and then Save & Apply.
Note: You will need to access the router using the new IP address.

Wireless Configuration (Wi-Fi)

1. Navigate to Network -> Wireless.
2. Click Enable on the radio interface (2.4GHz or 5GHz).
3. Click Edit on the desired SSID.
4. Under Interface Configuration -> General Setup:

  • Set your ESSID (Wi-Fi Name).

5. Under Wireless Security:

  • Set Encryption to WPA2-PSK/WPA3-SAE Mixed or WPA3-SAE for modern security.
  • Enter your Wi-Fi password in the Key field.

6. Click Save and then Save & Apply.

5. Firewall and Port Forwarding (Firewall4)

OpenWrt 25.x uses firewall4 which is configured through /etc/config/firewall.

Creating a Port Forward Rule

To forward external traffic (e.g., port 2222) to an internal device (e.g., SSH on port 22 at 192.168.1.100):

Via LuCI:

1. Navigate to Network -> Firewall -> Port Forwards.
2. Scroll to the bottom and click Add.
3. Set the parameters:

  • Name: SSH-Forward
  • Protocol: TCP
  • External zone: wan
  • External port: 2222
  • Internal zone: lan
  • Internal IP address: 192.168.1.100
  • Internal port: 22

4. Click Save and then Save & Apply.

Via CLI:

Add the following block to /etc/config/firewall:

config redirect
        option name 'SSH-Forward'
        option src 'wan'
        option src_dport '2222'
        option dest 'lan'
        option dest_ip '192.168.1.100'
        option dest_port '22'
        option proto 'tcp'
        option target 'DNAT'

Apply the changes:

uci commit firewall
service firewall restart

6. Package Management (using apk)

OpenWrt 25.x uses apk as its default package manager, replacing opkg. Internet connectivity on the router is required to download packages.

Updating Package Lists

Before installing packages, synchronize the package index:

apk update

Searching for Packages

To search for a package (for example, wireguard):

apk search wireguard

Installing Packages

  • Quality of Service (SQM - Smart Queue Management): Helps reduce lag and bufferbloat.
    apk add luci-app-sqm
  • Statistics and Monitoring:
    apk add luci-app-statistics
  • WireGuard VPN Support:
    apk add luci-proto-wireguard

Removing Packages

To remove a package that is no longer needed:

apk del package_name

7. Storage Expansion (Extroot)

Many routers have limited flash storage (e.g., 16MB). You can expand the storage using a USB drive formatted with ext4.

Step 1: Install Required Packages

Connect your router to the internet and run:

apk update
apk add kmod-usb-storage kmod-fs-ext4 block-mount e2fsprogs fdisk

Step 2: Format the USB Drive

Partition and format your USB drive (assuming the drive is detected as /dev/sda):

# Create partition
fdisk /dev/sda
# (Press 'n' for new partition, then 'p', then '1', use defaults, then 'w' to write)

# Format to ext4
mkfs.ext4 /dev/sda1

Step 3: Configure Mount Points

Generate the fstab configuration to mount the USB drive as the overlay filesystem:

# Mount the new partition temporarily
mount /dev/sda1 /mnt

# Copy existing overlay configuration to the USB drive
tar -C /overlay -cvf - . | tar -C /mnt -xf -

# Create fstab entry
block detect > /etc/config/fstab

Edit /etc/config/fstab to enable the mount. The section for /dev/sda1 should look similar to this:

config 'mount'
        option target '/overlay'
        option uuid 'YOUR_USB_UUID_HERE'
        option enabled '1'

(You can verify the configuration or UUID using the command block info).

Reboot the router:

reboot

After rebooting, check System -> Software in LuCI or run df -h in SSH to confirm the expanded storage is active.

8. Backup, Restore, and Factory Reset

Creating a Configuration Backup

To back up your configuration files:
1. Navigate to System -> Backup / Flash Firmware.
2. Under Backup, click Generate archive. This will download a .tar.gz file containing your settings.

Factory Reset

If you lose access to the router or run into configuration conflicts, you can revert to the default OpenWrt settings.

Via CLI:

firstboot
reboot

Via Hardware Button:

1. With the router powered on, locate the physical Reset button.
2. Press and hold the button for 10-15 seconds until the LED lights begin to flash rapidly.
3. Release the button and wait for the router to reboot into its default state.

The guide was created in June 2026.