OpenWrt Setup Guide

What you need: a router that the OpenWrt Table of Hardware lists as supported in the current stable release, a computer with an Ethernet port and cable, and whatever extra your device's wiki page names for installation or recovery, such as a TFTP server or a serial adapter.

What OpenWrt Is

OpenWrt replaces the manufacturer firmware with a full Linux system: SSH access, a package manager, the UCI configuration system and the LuCI web interface. Compared with most stock firmware, it lets you:

• Run a WireGuard or OpenVPN client or server on the router itself
• Split the network into VLANs, for example to keep IoT devices away from your computers
• Use SQM to reduce bufferbloat (latency spikes while the line is busy)
• Install packages such as ad blocking, dynamic DNS and traffic statistics
• Keep getting security updates for as long as an OpenWrt release series supports your device

Versions This Guide Covers

The current stable series is OpenWrt 25.12; the 25.12 release page lists 25.12.6 (October 18, 2026) as the latest release. 25.12 replaced the opkg package manager with apk, so package commands differ between releases. This guide shows apk commands for 25.12 and the opkg equivalents for 24.10 and older.

The previous series, 24.10, is the "old stable" release; its last listed update is 24.10.8 (July 26, 2026) on the 24.10 release page. The 25.12.0 release notes say 24.10 gets no security updates after September 2026, so as of October 2026 a router on 24.10 no longer receives security fixes. Move it to 25.12 (see Upgrades). The opkg commands below are there for that migration and for older devices.

Is Your Router Supported?

Search the Table of Hardware for your exact model and hardware revision. Revisions of the same model often use different chips and need different images, or aren't supported at all. The revision is usually printed on the label under the device.

On the device's page, check:

• Support status: the device should be supported in the current stable release, not only in snapshot or work-in-progress builds.
• Installation method: some devices install from the vendor's web upgrade page, others need TFTP or a serial console.
• Flash and RAM: the factory install guide suggests at least 16 MB of flash and 128 MB of RAM when you buy a device for OpenWrt. Devices with less can run out of room for LuCI or extra packages.

The Firmware Selector finds the images for your device and release, and can also build a custom image with extra packages already included.

Installation

Before you flash, note your current vendor settings (PPPoE username and password, Wi-Fi names, any port forwards) somewhere off the router. Flashing replaces them, and the vendor firmware's backup file can't be imported into OpenWrt.

Warning: a wrong image or an interrupted flash can leave a router unbootable, and recovery steps differ from device to device. Read your device's wiki page from start to finish before flashing, and keep another way to get online (a phone hotspot or a spare router) so you can still read the recovery instructions if something goes wrong.

For a first install over the vendor firmware, the general steps from the factory install guide are:

1. Download the image meant for installing over vendor firmware. It's often named ...factory.bin or ...factory.img, but the guide notes that many supported devices use other names, so follow the device page. sysupgrade images are for routers that already run OpenWrt.
2. Verify the download's checksum against the one on the download page, and only continue if they match.
3. Connect to the router with an Ethernet cable.
4. Log in to the vendor web interface and use its firmware upgrade page, following the device-specific instructions.
5. Wait while the image is written; this can take several minutes. Don't power off the router before it has rebooted on its own.

First Login

After the reboot, OpenWrt's LAN address is 192.168.1.1. Open http://192.168.1.1 in a browser and log in as root with an empty password, or connect over SSH:

ssh root@192.168.1.1

No root password is set on a fresh install, so anyone on the LAN can log in. Set one first, either from LuCI's "No password set" notice or over SSH:

passwd

If your modem or ISP router also uses 192.168.1.0/24, change OpenWrt's LAN address (Network → Interfaces → LAN) before you connect the WAN port, otherwise the two networks overlap. Networking Fundamentals explains why overlapping subnets break routing.

LuCI Web Interface

LuCI exposes most of the settings you'd otherwise edit with UCI in /etc/config/. A typical first pass:

1. System → Administration: set the root password if you haven't yet.
2. Network → Interfaces: configure WAN (DHCP for most connections, PPPoE if your ISP requires it).
3. Network → Wireless: Wi-Fi is disabled on a fresh install. Set the SSID and a strong passphrase, then enable each radio.
4. System → Software: refresh the package lists before installing anything.

Installing Packages

OpenWrt 25.12 uses apk. The wiki's opkg to apk cheat sheet maps the old commands to the new ones:

# OpenWrt 25.12 and later (apk)
apk update
apk add luci-app-sqm          # Smart Queue Management
apk add luci-app-statistics   # traffic and system graphs
apk add luci-app-ddns         # dynamic DNS
apk list --installed          # show installed packages
apk del luci-app-ddns         # remove a package

# OpenWrt 24.10 and older (opkg)
opkg update
opkg install luci-app-sqm
opkg list-installed
opkg remove luci-app-ddns

apk --update-cache add PACKAGE refreshes the index and installs in one step. If apk prints WARNING: opening from cache, the cheat sheet explains that the local indexes are missing or outdated, and apk update usually clears it. Packages you build yourself need --allow-untrusted, because apk checks package signatures.

Flash space is small on most routers. Check the free space on the overlay with df -h before you add large packages.

VLANs for Network Segmentation

VLANs let one router serve separate networks, for example trusted devices, IoT devices and guests, each with its own subnet and firewall rules. Most stock firmware offers little or no VLAN control. In LuCI:

1. On devices that use DSA (most current targets), open Network → Interfaces → Devices, configure the bridge device and enable VLAN filtering to assign ports to VLANs. Older devices use Network → Switch instead.
2. Create an interface for each VLAN with its own static address.
3. Put each interface in its own firewall zone.
4. Enable a DHCP server with its own range on each interface.

A common pattern is an IoT zone that may forward to WAN but not to LAN, so smart devices reach the internet but not your computers. Port layouts differ between devices, so check the device page before changing the VLAN of the port you're connected through; a mistake there cuts off your own access.

VPN Client and Server

WireGuard

apk update
apk add luci-proto-wireguard     # 24.10: opkg install luci-proto-wireguard

Then add a new interface with the WireGuard protocol under Network → Interfaces (reboot first if the protocol isn't offered yet). The concepts are the same as on a Linux server: key pairs, peers and AllowedIPs. WireGuard Cloud Deployment explains them, including what to check when there's no handshake.

OpenVPN

apk add luci-app-openvpn         # 24.10: opkg install luci-app-openvpn

WireGuard only uses UDP. OpenVPN can also run over TCP, which helps on networks that block UDP. OpenVPN Cloud Deployment covers the server side.

Smart Queue Management (SQM)

Bufferbloat is the extra latency you get when a busy connection fills the router's buffers: calls stutter while someone else downloads. The wiki's SQM guide covers the setup:

apk add luci-app-sqm             # 24.10: opkg install luci-app-sqm

• Measure your speed and latency under load first, so you have a baseline to compare against.
• Under Network → SQM QoS, enable SQM on the WAN interface and set download and upload limits a little below your measured speeds (the wiki's worked example uses 90%).
• The wiki prefers cake as the queue discipline; fq_codel is lighter if the CPU can't keep up.
• Set the link layer adaptation for your connection type.
• SQM doesn't work with hardware flow offloading, so leave that off under Network → Firewall. Software flow offloading is fine.

SQM runs on the router's CPU, so slower devices may not shape your full line speed. Repeat the same test afterwards and compare the latency under load.

Firewall Basics

Under Network → Firewall, OpenWrt groups interfaces into zones, much like OPNsense does:

• lan: your internal network; traffic from here may go out to WAN by default.
• wan: the internet side; inbound connections are rejected unless you add a rule.

Port forwards live under Network → Firewall → Port Forwards. Forward only what you need, and reach admin interfaces through a VPN rather than exposing them.

Ad Blocking

apk add luci-app-adblock         # 24.10: opkg install luci-app-adblock

Configure it under Services → Adblock. It filters ads for every device that uses the router for DNS, without a separate machine. If you want a dashboard and per-client statistics, a dedicated DNS filter such as Pi-hole or AdGuard Home offers more, and you can hand its address to clients through the router's DHCP settings.

Upgrades

Don't upgrade every package in place. The opkg to apk cheat sheet warns against apk upgrade for this: some packages have missing conflicts or incomplete dependencies, and blind upgrades can eventually brick the device. To pick up all updates or move to a new release, install a new firmware image instead.

The supported ways to do that are the Attended Sysupgrade (ASU) clients described in the 25.12.0 release notes:

• LuCI Attended Sysupgrade, installed by default in 25.12. It sends your installed package list to the build server, downloads a matching image and installs it while keeping your settings.
• owut, the command-line equivalent, included by default on 25.12 images for devices with larger flash. Run owut check --verbose --version-to 25.12 first and review it, then owut upgrade --verbose --version-to 25.12.
• Firmware Selector: build an image with your package list in the browser, then flash it under System → Backup / Flash Firmware with "Keep settings" enabled.

From 24.10 to 25.12: the release notes say a sysupgrade from 24.10 works in many cases and tries to keep your configuration; take a backup first anyway. On 24.10 the ASU tools are optional, so install them with opkg update and opkg install luci-app-attendedsysupgrade (or opkg install owut). Read the upgrade section of the release notes for device-specific exceptions.

From 23.05 or older: a direct sysupgrade from 23.05 to 25.12 isn't officially supported. Upgrade to 24.10 first, or do a scratch install: back up, flash the new image without keeping settings (sysupgrade -n, or LuCI with "Keep settings" turned off), then rebuild your configuration using the backup as a reference.

Backup Configuration

Under System → Backup / Flash Firmware, choose Generate archive and download it after every significant change. With that archive, a reflash or a replacement router becomes a restore rather than a rebuild. The archive holds settings, not packages, so also keep a list of what you installed (apk list --installed, or opkg list-installed on 24.10).

Troubleshooting

Can't reach 192.168.1.1 after flashing

• Your computer has no address on the new LAN. Unplug and replug the cable or renew DHCP, then check that you have a 192.168.1.x address (ip addr on Linux, ipconfig on Windows).
• Wrong port. Use a LAN port, not WAN.
• The router didn't come back. Watch the LEDs, check the device page for its recovery method, and see the failsafe section below.

LAN works, but there's no internet

• Check whether WAN has an address under Network → Interfaces. If it doesn't, check the cable to the modem and, for PPPoE, the username and password.
• Over SSH, ping -c 3 1.1.1.1 tests routing and nslookup openwrt.org tests DNS. If the ping works but the lookup fails, the problem is DNS, not the connection.
• logread | tail -n 50 shows recent system log messages, including DHCP and PPPoE errors.

Package installs fail

• Refresh the index first (apk update, or opkg update on 24.10); stale indexes are the usual cause.
• Use the commands for your release: 25.12 uses apk, 24.10 and older use opkg.
• "No space left on device" means the overlay is full. Remove packages you don't need, or build an image with the packages included through the Firmware Selector.

The Wi-Fi network doesn't appear

Wi-Fi is off after a fresh install. Enable each radio under Network → Wireless, then save and apply.

If Things Go Wrong: Failsafe and Reset

If a configuration change locks you out, failsafe mode boots OpenWrt with a minimal fixed configuration so you can repair it. It only works on installs from a SquashFS image, which covers most of them. The wiki's procedure:

1. Give your computer a static address such as 192.168.1.10 and connect it by Ethernet, trying LAN1 first.
2. Power on the router. When the LED starts blinking during boot, press a button (Reset, WPS or another). On 24.10 and later the window is about four seconds; on 23.05 and earlier it was two.
3. Connect with ssh root@192.168.1.1. DHCP and Wi-Fi are off in failsafe mode.
4. Run mount_root to mount your configuration, fix the file you broke (for example /etc/config/network), then run reboot.

To start over instead, run firstboot && reboot, or, on devices with a reset button, hold it for about 10 seconds once the router has finished booting. Both erase your settings. If failsafe doesn't work, the device page may describe TFTP or serial console recovery.

Before You Flash: Checklist

• Exact model and revision found in the Table of Hardware, and supported in the current stable release.
• Your device's wiki page read in full: the install method, the recovery method and the known issues are all device-specific.
• Checksum verified for the image you're about to flash.
• A second way online, so you can read recovery instructions if the router doesn't come back.