Skip to main content

OpenWRT

Installing​

Best place to start is the firmware selector. You can pick your platform, version, and also add all the packages you might need together with the base packages, eg, ethernet drivers.

x86_64​

OpenWRT has to be directly installed to a drive from another computer. Download the x86 version OpenWRT. Unzip the image:

gunzip openwrt_2352.img.gz

I formatted the disk to exFAT, and then:

dd if=openwrt_2352.img bs=1M of=/dev/sdX

Remember to check lsblk to see which drive to write.

Then install the hard drive to the other computer. Boot it up and make sure it boots in UEFI, and secure boot is off. It should just boot into OpenWRT now.

VM (QEMU)​

You need to download any x86_64 image. I'm using virt-manager as frontend. Make sure when starting the VM to select “Import existing disk image”.

When starting the VM, you need to change the ip address. Note down the subnet of the host's interface that QEMU is using (probably something like virbr0)

In this example, I assume that the LAN interface on the VM is br-lan and that the host's subnet is 192.168.122.0/24.

IN OPENWRT
----------
ifconfig # confirm the interface name
ifconfig br-lan 192.168.122.10
ifconfig br-lan

You can now access the OpenWRT web interface on that IP.

ARM​

You can either use the process for x86_64, or the Raspberry Pi Imager. Make sure you get all the ethernet drivers for your platform. You can check the chip on the ethernet / wifi card to find the manufacturer. For smaller, embedded systems it's best not to install too many drivers as they take space. For systems with a lot of resources (>2GB storage, >2GB memory, >2 cores) it doesn't matter.

Drivers I use
opkg install kmod-iwlwifi
opkg install iwlwifi-firmware
opkg install wpad
opkg install kmod-rtl8xxxu
opkg install kmod-r8169

Upgrading OpenWRT​

danger

When upgrading, don't forget to install drivers and any DNS packages!

Use the firmware selector to customize your upgrade. For example, I need the extra drivers, the https-dns-proxy package, the cloudflare tunnel, an adblocker, and some tools to resize the filesystem.

so I add the following packages
https-dns-proxy luci-app-https-dns-proxy kmod-r8169 cloudflared luci-app-cloudflared adblock luci-app-adblock cfdisk resize2fs tune2fs

Managing your router​

Change local IP pool​

If you want to change the default IP range of your LAN interface, edit the network file in your config:

/etc/config/network
config interface 'lan'
	option device 'br-lan'
	option proto 'static'
	option ipaddr '192.168.2.3'
	option netmask '255.255.255.0'
	option ip6assign '60'

And then restart the network service:

service network restart
info

When doing changes to your local IP pool, remember to release and renew the IP address on your computer(s). Make sure when setting up the DHCP server to lower the lease time to 1 or 2 minutes.

Usually, releasing and renewing IPs happens on clients:

On Mac, go to System Settings > Network > LAN Device > Details… > TCP/IP > Renew DHCP Lease.

Resizing Filesystem​

When installing OpenWRT on embedded systems (ARM) you will probably come across a problem where the OS is not utilizing all the storage on your drive. For my case, I run OpenWRT on a Raspberry Pi 5. Installing the OS from Rapsberry Pi Imager uses only 100MB of storage. First we need to edit the cmdline.txt in the boot folder. You need to do that right after you flash OpenWRT with Rapsberry Pi Imager, while the SD or disk is still on your other computer:

/boot/cmdline.txt
# THIS
root=PARTUUID=661a1cf7-02

# REPLACE WITH THIS
root=/dev/mmcblk0p2

Boot into OpenWRT and SSH into the system:

Download the script and make it executable
wget -U "" -O expand-root.sh "https://openwrt.org/_export/code/docs/guide-user/advanced/expand_root?codeblock=0"
chmod +x expand-root.sh

# Then run the script
./expand-root.sh

Reboot your system. It will probably reboot a couple of times. I also recommend having a screen hooked up (if possible) to monitor the bootstrap of the router.

802.1q VLAN​

802.1q or dot1q is a standard in networking, specifically defining VLANs. It is used to segregate a local network. A switch (that supports dot1q) can split frames into two or more VLANs.

Openwrt can either directly split up a network if it has enough physical ports, or through a trunk port. A trunk port (or tagged port) is one physical port that can manage traffic on several VLANs. For example, a router has only one physical LAN port, and the network devices are connected to managed switch that supports 802.1q VLAN. Splitting the network happens inside the switch, and the openwrt just manages and forwards the traffic accordingly.

DNS​

tip

If anything is broken, it's probably the DNS; start troubleshooting it first.

Custom DNS Server​

There are two methods to use custom DNS server.

  • Using a custom DNS for a WAN interface:
Network > Interfaces > wan interface > Edit > Advance Settings > Custom DNS

You can also force this DNS server by disabling the Use advertised DNS by peer setting.

  • or DNS Forwarding:
Network > DHCP and DNS > Forwards > DNS Forwarding

DNS Hijacking​

You can configure your router to intercept all DNS traffic on your local network.

Navigate to LuCI → Network → Firewall → Port Forwards.

Click Add and specify:

  1. Name: Intercept-DNS
  2. Restrict to address family: IPv4 and IPv6
  3. Protocol: TCP, UDP
  4. Source zone: lan
  5. External port: 53
  6. Destination zone: unspecified
  7. Internal IP address: any
  8. Internal port: any

Click Save, then Save & Apply.

You can find more info here.

DNS Encryption​

You can encrypt your DNS traffic by sending it over HTTPS (or TLS). The traffic is still routed using UDP for transport, but the payload uses the HTTPS protocol. On Openwrt, you can install the dns-https-proxy and luci-app-dns-https-proxy and start forwarding your DNS traffic HTTPS.

warning

When upgrading, remember to reinstall this package or disable before upgrading; it leaves dnsmasq settings that will be hard to reset without the package.

DDNS with Cloudflare​

Dynanmic DNS helps you keep track of your IP and hook it to a domain name automatically. You will either need to use a service, or find a domain registrar that has an API. I use Cloudflare, which has an API.

Go to your Cloudflare account page, Manage Account, Account API Tokens. Create and new custom API token, add the Permissions "Zone" - "Zone" - "Read" and "Zone" - "DNS" - "Write". Include the domain name that will hook to your IP, save and keep the token.

You will need the following packages installed in OpenWRT:

ddns-scripts
ddns-scripts-cloudflare
ddns-scripts-services
luci-app-ddns

Refresh LuCi and go to Services > DDNS. Edit myddns_ipv4 and select from the DDNS service providers cloudflare.com-v4. Set the rest as:

  • Enabled - true
  • Lookup Hostname - yourdomain.com (for a subdomain: sub.yourdomain.com)
  • Domain - yourdomain.com (for a subdomain: [email protected])
  • Username - Bearer
  • Password - YOUR_CLOUDFLARE_API_TOKEN
  • Use HTTP Secure - true
  • Path to CA Certificate - /etc/ssl/certs

Save everything and refresh. Unfortunately, your ISP rotates your public IP automatically, so there is no way to test this other than waiting for the next rotation. For me, sometimes I get a new public IP if I restart the router or if I unplug and then plug again the WAN interface.