Overview
OpenWrt is a highly extensible open-source Linux distribution targeting embedded devices, most commonly wireless routers. Unlike vendor firmware that provides a static, limited feature set, OpenWrt delivers a fully writable filesystem with a package manager (opkg), allowing users to install hundreds of additional packages to customize their router’s functionality. It supports a vast range of hardware from consumer routers to enterprise access points and single-board computers.
The system is built around the UCI (Unified Configuration Interface) framework, which standardizes configuration across all services. OpenWrt includes LuCI, a web-based administration interface, alongside full SSH and command-line access. Common use cases include advanced firewalling with nftables, VPN servers, mesh networking, traffic shaping, DNS filtering with adblock, VLAN segmentation, and running containers on capable hardware. The project maintains an extensive hardware compatibility database and regular releases with long-term security support.
Installation
Downloading Firmware
# Find your device at https://openwrt.org/toh/start
# Download the correct firmware image for your hardware
# Sysupgrade image (for upgrading existing OpenWrt)
wget https://downloads.openwrt.org/releases/23.05.3/targets/ath79/generic/openwrt-23.05.3-ath79-generic-device-squashfs-sysupgrade.bin
# Factory image (for first install from vendor firmware)
wget https://downloads.openwrt.org/releases/23.05.3/targets/ath79/generic/openwrt-23.05.3-ath79-generic-device-squashfs-factory.bin
# Verify checksum
sha256sum openwrt-*.bin
First-Time Setup
# Default IP after flashing
# Connect via ethernet to LAN port
ssh root@192.168.1.1
# Set root password
passwd
# Configure basic networking via UCI
uci set network.lan.ipaddr='192.168.10.1'
uci commit network
/etc/init.d/network restart
Sysupgrade (Upgrade Existing OpenWrt)
# From command line
sysupgrade -v /tmp/openwrt-sysupgrade.bin
# Keep settings during upgrade
sysupgrade -c /tmp/openwrt-sysupgrade.bin
# Force upgrade (discard settings)
sysupgrade -n /tmp/openwrt-sysupgrade.bin
# Generate backup before upgrade
sysupgrade -b /tmp/backup-$(date +%F).tar.gz
Package Management (opkg)
| Command | Description |
|---|
opkg update | Refresh package lists |
opkg list | List all available packages |
opkg list-installed | List installed packages |
opkg install <package> | Install a package |
opkg remove <package> | Remove a package |
opkg upgrade <package> | Upgrade a package |
opkg info <package> | Show package details |
opkg find "*vpn*" | Search packages by name |
opkg list-changed-conffiles | List modified config files |
Essential Packages
opkg update
opkg install luci # Web interface
opkg install luci-ssl # HTTPS for LuCI
opkg install nano # Text editor
opkg install tcpdump # Packet capture
opkg install curl wget # Download tools
opkg install openvpn-openssl # OpenVPN
opkg install wireguard-tools # WireGuard VPN
opkg install adblock luci-app-adblock # Ad blocking
opkg install vnstat2 luci-app-vnstat2 # Traffic statistics
opkg install kmod-usb-storage # USB storage support
UCI Configuration System
Basic UCI Commands
| Command | Description |
|---|
uci show | Show all configuration |
uci show network | Show network config |
uci get network.lan.ipaddr | Get specific value |
uci set network.lan.ipaddr='10.0.0.1' | Set a value |
uci add_list firewall.@zone[1].network='vpn' | Add to a list |
uci delete network.wan6 | Delete a section |
uci commit | Save all changes |
uci commit network | Save specific subsystem |
uci changes | Show uncommitted changes |
uci revert network | Discard uncommitted changes |
Network Configuration
# /etc/config/network
# WAN interface (DHCP)
uci set network.wan=interface
uci set network.wan.device='eth1'
uci set network.wan.proto='dhcp'
# WAN interface (Static)
uci set network.wan.proto='static'
uci set network.wan.ipaddr='203.0.113.10'
uci set network.wan.netmask='255.255.255.0'
uci set network.wan.gateway='203.0.113.1'
uci set network.wan.dns='8.8.8.8 8.8.4.4'
# PPPoE
uci set network.wan.proto='pppoe'
uci set network.wan.username='user@isp.com'
uci set network.wan.password='secret'
uci commit network
/etc/init.d/network restart
Wireless Configuration
# /etc/config/wireless
# View wireless hardware
wifi status
# Configure 2.4GHz radio
uci set wireless.radio0.disabled='0'
uci set wireless.radio0.channel='6'
uci set wireless.radio0.htmode='HT40'
uci set wireless.radio0.country='US'
# Configure SSID
uci set wireless.default_radio0.ssid='MyNetwork'
uci set wireless.default_radio0.encryption='sae-mixed'
uci set wireless.default_radio0.key='MyPassword123'
# Guest network on separate VLAN
uci add wireless wifi-iface
uci set wireless.@wifi-iface[-1].device='radio0'
uci set wireless.@wifi-iface[-1].network='guest'
uci set wireless.@wifi-iface[-1].mode='ap'
uci set wireless.@wifi-iface[-1].ssid='GuestNetwork'
uci set wireless.@wifi-iface[-1].encryption='sae'
uci set wireless.@wifi-iface[-1].key='GuestPass456'
uci set wireless.@wifi-iface[-1].isolate='1'
uci commit wireless
wifi reload
Firewall Configuration
# /etc/config/firewall
# Allow SSH from WAN
uci add firewall rule
uci set firewall.@rule[-1].name='Allow-SSH-WAN'
uci set firewall.@rule[-1].src='wan'
uci set firewall.@rule[-1].dest_port='22'
uci set firewall.@rule[-1].proto='tcp'
uci set firewall.@rule[-1].target='ACCEPT'
# Port forward (DNAT)
uci add firewall redirect
uci set firewall.@redirect[-1].name='WebServer'
uci set firewall.@redirect[-1].src='wan'
uci set firewall.@redirect[-1].src_dport='8080'
uci set firewall.@redirect[-1].dest='lan'
uci set firewall.@redirect[-1].dest_ip='192.168.1.100'
uci set firewall.@redirect[-1].dest_port='80'
uci set firewall.@redirect[-1].proto='tcp'
uci commit firewall
/etc/init.d/firewall restart
VLAN Configuration
# Create VLAN device
uci set network.vlan10=device
uci set network.vlan10.type='8021q'
uci set network.vlan10.ifname='eth0'
uci set network.vlan10.vid='10'
# Assign to interface
uci set network.iot=interface
uci set network.iot.device='eth0.10'
uci set network.iot.proto='static'
uci set network.iot.ipaddr='10.10.10.1'
uci set network.iot.netmask='255.255.255.0'
# DHCP for VLAN
uci set dhcp.iot=dhcp
uci set dhcp.iot.interface='iot'
uci set dhcp.iot.start='100'
uci set dhcp.iot.limit='150'
uci set dhcp.iot.leasetime='12h'
# Firewall zone
uci add firewall zone
uci set firewall.@zone[-1].name='iot'
uci set firewall.@zone[-1].input='REJECT'
uci set firewall.@zone[-1].output='ACCEPT'
uci set firewall.@zone[-1].forward='REJECT'
uci set firewall.@zone[-1].network='iot'
uci commit
/etc/init.d/network restart
/etc/init.d/firewall restart
Service Management
| Command | Description |
|---|
/etc/init.d/network restart | Restart networking |
/etc/init.d/firewall restart | Restart firewall |
/etc/init.d/dnsmasq restart | Restart DNS/DHCP |
service network reload | Reload network config |
service list | List all services |
logread | View system log |
logread -f | Follow system log |
dmesg | Kernel messages |
Advanced Usage
WireGuard VPN Server
opkg update && opkg install wireguard-tools luci-proto-wireguard
# Generate keys
wg genkey | tee /etc/wireguard/server_private | wg pubkey > /etc/wireguard/server_public
# Configure WireGuard interface
uci set network.wg0=interface
uci set network.wg0.proto='wireguard'
uci set network.wg0.private_key="$(cat /etc/wireguard/server_private)"
uci set network.wg0.listen_port='51820'
uci add_list network.wg0.addresses='10.0.100.1/24'
# Add peer
uci add network wireguard_wg0
uci set network.@wireguard_wg0[-1].public_key='PEER_PUBLIC_KEY'
uci set network.@wireguard_wg0[-1].allowed_ips='10.0.100.2/32'
uci commit network
/etc/init.d/network restart
DNS over HTTPS (DoH)
opkg update && opkg install https-dns-proxy luci-app-https-dns-proxy
/etc/init.d/https-dns-proxy enable
/etc/init.d/https-dns-proxy start
Scheduled Tasks (cron)
# Edit crontab
crontab -e
# Reboot every Sunday at 4am
0 4 * * 0 /sbin/reboot
# Clear DNS cache hourly
0 * * * * /etc/init.d/dnsmasq restart
Backup and Restore
# Create full backup
sysupgrade -b /tmp/backup-$(date +%F).tar.gz
# List backup contents
tar tzf /tmp/backup-*.tar.gz
# Restore from backup
sysupgrade -r /tmp/backup-2024-01-15.tar.gz
Troubleshooting
| Issue | Solution |
|---|
| Locked out after config change | Hold reset button 10s for failsafe mode (192.168.1.1) |
| WiFi not starting | Check wifi status, ensure radio not disabled |
| No internet after setup | Verify WAN config: uci show network.wan |
| Package install fails | Run opkg update first, check /tmp disk space |
| LuCI not accessible | Install with opkg install luci, check uhttpd service |
| DNS resolution fails | Check dnsmasq: /etc/init.d/dnsmasq restart |
| Firmware won’t flash | Verify image checksum, try TFTP recovery |
| Slow speeds | Check SQM QoS, verify hardware offloading enabled |
Failsafe Mode
# Enter failsafe mode:
# 1. Power on device
# 2. Watch for LED pattern (rapid blinking)
# 3. Press reset button during that window
# 4. Connect to 192.168.1.1 via ethernet
# 5. SSH: ssh root@192.168.1.1 (no password)
# Reset to defaults from failsafe
firstboot && reboot
Diagnostic Commands
# Network diagnostics
ifconfig
ip addr show
ip route show
ping -c 4 8.8.8.8
traceroute google.com
nslookup google.com
# Wireless diagnostics
iwinfo wlan0 info
iwinfo wlan0 scan
iw dev wlan0 station dump
# System resources
free -m
df -h
top
cat /proc/cpuinfo
