Installation[edit | edit source]

Refer to OpenWRT's list of hardware and firmware downloads at:

Intel based Hardware or as a VM[edit | edit source]

Navigate to the 'x86' target of the latest release. Use the '64' release for 64-bit capable processors or 'Generic' for 32-bit. For example, OpenWRT 19.0.7 for Intel based 64bit processors can be found at https://downloads.openwrt.org/releases/19.07.3/targets/x86/64/.

Use either the read-only squashfs image (which limits you to 230MB available for packages) or the ext4 image (which can be expanded and the entire filesystem is writable but without a factory reset feature).

Download the combined ext4 disk image, uncompress the image, then dd the image to your hard drive or flash media. For ext4 images, use fdisk to expand the second partition to the full size of the storage device and then run resize2fs /dev/sdx2.

Raspberry Pi 1 Model B[edit | edit source]

For all other Raspberry Pis, the installation information can be found at https://openwrt.org/toh/raspberry_pi_foundation/raspberry_pi

The installation process involves dd'ing the image to the SD card. You may wish to resize the SD card after the image has been written. To do so, resize the data partition and then run e2fsck -f /dev/mmcblk0p2 and resize2fs /dev/mmcblk0p2. More info at https://elinux.org/RPi_Resize_Flash_Partitions#Manually_resizing_the_SD_card_on_Linux.

# dd if=openwrt-brcm2708-bcm270{8,9}-sdcard-vfat-ext4.img of=/dev/sdX bs=2M conv=fsync status=progress

## Optionally resize the data partition
# e2fsck -f /dev/sdX2
# resize2fs /dev/sdX2

Serial is enabled and is available via GPIO pins 8 and 10 for TX and RX respectively.

Default IP is 192.168.1.1/24.

Raspberry Pi 2 Model B v1.2[edit | edit source]

Update: It appears there is an official image. I have not tried this yet and the information below may be inaccurate or unnecessary. See https://openwrt.org/toh/raspberry_pi_foundation/raspberry_pi for more information.

OpenWRT does not list an official image for the Raspberry Pi 2 v1.2 board. Neither the Pi 3 or Pi 2 image works. This is because the Raspberry Pi 2 v1.2 board uses the bcm2710 SOC (same as the Pi 3) but both images don't properly handle the Pi 2 v1.2 board and as such, both versions fail to boot.

To get OpenWRT to work on this board, image the SD card with the bcm2710 image (the Pi 3 version) and then:

  1. Mount /boot
  2. Copy bcm2710-rpi-3-b.dtb to bcm2709-rpi-2-b.dtb

A copy can be found at https://github.com/raspberrypi/firmware/raw/master/boot/bcm2710-rpi-3-b.dtb to bcm2709-rpi-2-b.dtb.

Buffalo WZR-600HP[edit | edit source]

See: WZR-600DHP

Package Development[edit | edit source]

Guide on building packages for OpenWRT: http://dvblog.soabit.com/building-custom-openwrt-packages-an-hopefully-complete-guide/

Tasks[edit | edit source]

Change LAN IP Address[edit | edit source]

By default, OpenWRT will assign itself 192.168.1.1. You can change this default IP address to something else by editing /etc/config/network or using the Unified Configuration Interface (uci) configuration tool.

The first method requires editing /etc/config/network and changing the option ipaddr value within the 'lan' interface section.

## The 'lan' section in /etc/config/network
config interface 'lan'
        option type 'bridge'
        option ifname 'eth0'
        option proto 'static'
        option ipaddr '192.168.1.1'    <-- change this
        option netmask '255.255.255.0'
        option ip6assign '60'

Apply the changes by running service network reload, or /etc/init.d/network reload.

Alternatively, use uci by setting the network.lan.ipaddr with the desired IP address.

# uci set network.lan.ipaddr  10.1.0.10
## Optionally set other values as well:
# uci set network.lan.gateway 10.1.1.1
# uci set network.lan.dns 10.1.1.1
# uci set network.lan.ifname  eth0
## Apply changes, and reload network
# uci commit network
# /etc/init.d/network reload

See Also: https://openwrt.org/docs/guide-user/base-system/basic-networking

Add an IP Alias[edit | edit source]

To add an additional IP address to the LAN interface, create a new interface with the ifname set to @lan.

# uci set network.lan2=interface
# uci set network.lan2.ifname='@lan'
# uci set network.lan2.proto=static
# uci set network.lan2.ipaddr=192.168.35.10
# uci set network.lan2.netmask=255.255.255.0
# uci commit network
# /etc/init.d/network reload

Running a PHP Application[edit | edit source]

I want to run a PHP application on a separate IP address. I will use the built-in uHTTPd web server and have the PHP application served from a secondary IP address.

## Install PHP and dependencies
# opkg install php7 php7-cgi php7-cli php7-mod-mbstring php7-mod-json php7-mod-pdo-sqlite php7-mod-sqlite3

## Set the primary IP LAN address for luci only
# uci set uhttpd.main.listen_http=`uci get network.lan.ipaddr`:80
# uci set uhttpd.main.listen_https=`uci get network.lan.ipaddr`:443
# uci commit uhttpd

## Create a second listener for 'app' listening on second IP address
## served from /srv/www
# uci set uhttpd.app=uhttpd
# uci set uhttpd.app.listen_http=`uci get network.lan2.ipaddr`:80
# uci set uhttpd.app.home=/srv/www

## Enable PHP interpreter and index files
## Unset doc_root in php.ini so script can be found in /srv/www
# uci add_list uhttpd.app.interpreter=".php=/usr/bin/php-cgi"
# uci set uhttpd.app.index_page="index.html index.php"
# sed -i 's,doc_root.*,doc_root = "",g' /etc/php.ini

## Apply and restart uhttpd
# uci commit uhttpd
# /etc/init.d/uhttpd restart

This will start an instance of uhttpd serving /srv/www on the second IP address on port 80. From a security point of view however, this is far from ideal since uhttpd is spawned as root and your PHP script will also execute with root privileges.

To make this second instance of uhttpd run as a non-root user, we will need to make a few changes to /etc/init.d/uhttpd so that procd is told what user to run uhttpd as. However, we will also need to change the listen port from 80 to something above 1024 because uhttpd is no longer running as a privileged user. We can still make it this instance appear on port 80 by configuring the firewall to redirect port 80 to our new listen port number.

# Set listen port to 8000 and run as a non-root user
# uci set uhttpd.app.listen_http=`uci get network.lan2.ipaddr`:8000
# uci set uhttpd.app.user=httpd

## Ensure that a user 'httpd' is created.
# useradd ...

## Configure the firewall
# uci set firewall.@redirect[0]=redirect
# uci set firewall.@redirect[0].proto='tcp'
# uci set firewall.@redirect[0].dest_ip='192.168.35.10'
# uci set firewall.@redirect[0].src='lan'
# uci set firewall.@redirect[0].name='8000to80'
# uci set firewall.@redirect[0].src_dip='192.168.35.10'
# uci set firewall.@redirect[0].dest='lan'
# uci set firewall.@redirect[0].target='DNAT'
# uci set firewall.@redirect[0].dest_port='8000'
# uci set firewall.@redirect[0].reflection='0'
# uci set firewall.@redirect[0].src_dport='80'

The /etc/init.d/uhttpd script must have the following lines added in start_instance():

config_get user "$cfg" user
procd_set_param user "$user"


Setup Adblock[edit | edit source]

You can make the DNS server block advertisement servers using blacklists that are available online. This is similar to how Pi-hole blocks ads with a modified version of dnsmasq.

To set up adblock on OpenWRT, install the following packages:

  • adblock
  • luci-app-adblock

Update block lists in the luci adblock page.

Backup[edit | edit source]

Run uci export to dump all configs. Useful for generating a periodic config backup.

$ ssh root@openwrt "uci export" > config

Logging DNS Queries[edit | edit source]

For troubleshooting, you may wish to enable DNS logging in dnsmasq. Do so by editing two files:

/etc/dnsmasq.conf:

log-queries
    log-facility=/tmp/dnsmasq.log

/etc/config/dhcp:

config dnsmasq
        ...
        option logdhcp '1'
        option logqueries '1'
        option logfacility '/tmp/dnsmasq.log'

When done, comment out log-queries and restart dnsmasq with /etc/init.d/dnsmasq restart.

Recursive DNS[edit | edit source]

I did not get this working.

OpenWRT by default uses dnsmasq which will forward non-local DNS lookups to another server (typically your actual router or ISP retrieved from WAN DHCP). You could configure dnsmasq to use a local resolver such as Unbound.

See: https://kevinlocke.name/bits/2017/03/09/unbound-with-dnsmasq-on-openwrt/

Troubleshooting[edit | edit source]

your adblock config seems to be too old, please update your config with the '--force-maintainer' opkg option[edit | edit source]

Recreate the configs from the package by reinstalling the package:

# opkg --force-maintainer --force-reinstall install adblock

TP-Link USB WiFi Support[edit | edit source]

The TP-Link dual antenna USB adapter that I have has a RTL8192 chip. Install these packages:

  • rtl8192cu-firmware
  • kmod-rtl8192cu
  • kmod-rtl8192
  • cu-common