OpenWrt

Basics

Buying a device for use with OpenWrt

OpenWrt supports a large number of devices. When shopping for a device you can check if it’s supported here: https://openwrt.org/toh/start

One device that’s currently popular (as of 2021) due to its low cost and capable hardware is the Xiaomi Mi Router 4A Gigabit Edition.

Installation and initial configuration

https://openwrt.org/docs/guide-quick-start/factory_installation

  1. Make sure your device is in the list of supported devices

    https://openwrt.org/toh/start

  2. Download the latest firmware for your device

    1. Still in the Supported Devices page, click on the link in the Device Page column
    2. Download the latest release for your model and hardware number
      • Download the factory image if you’re flashing over stock firmware
      • Download the sysupgrade image if you’re flashing over an existing OpenWrt installation
  3. Flash OpenWrt

    1. Follow the instructions on the device page

      Note: If you’re flashing a different version of OpenWrt, make sure you don’t keep the existing configuration as this will likely cause problems

  4. Connect to the device

    https://openwrt.org/docs/guide-quick-start/webadmingui

    1. If your device has network ports, wireless will be disabled by default. Connect to the device with a network cable
    2. Browse to the device url (http://192.168.1.1) and log in (root, no password)
  5. Set the root password

    1. System > Administration
    2. Set Password
    3. Save & Apply
  6. Set the time zone

    1. System > System
    2. Set Timezone
    3. Save & Apply
  7. Set the country code

    1. Network > Wireless > Edit > Advanced Settings
    2. Set Country Code
    3. Save > Save & Apply
  8. Configure wireless

    https://openwrt.org/docs/guide-quick-start/basic_wifi

    1. Network > Wireless > Edit > Interface Configuration
    2. General Setup
      1. Set ESSID
      2. Save & Apply
    3. Wireless Security
      1. Encryption > WPA2-PSK
      2. Set Key
      3. Save & Apply
  9. Enable wireless

    1. Network > Wireless > Enable
  10. Reboot

    This makes sure the time zone takes effect if you’re using it in your firewall rules (iptables’ timestart)

    1. System > Reboot > Perform reboot

Change the IP address

  1. Network > Interfaces > LAN > Edit
  2. Change IPv4 address > Save
  3. At the bottom of the page, if there’s a dropdown near Save & Apply, select Apply unchecked, then click Apply unchecked
    • Otherwise, click Save & Apply, and if you see Configuration has been rolled back!, click Apply unchecked
  4. Connect to the device at the new address
    • If you’re unable to connect, try rebooting the router

Add a host file blacklist

  1. Download a host file blacklist (e.g. https://github.com/StevenBlack/hosts)
  2. Copy the host file to the device
    scp hosts root@192.168.0.100:/tmp/hosts
    
  3. SSH to the device
    ssh root@192.168.0.100
    
  4. Restart dnsmasq
    service dnsmasq restart
    

Create a scheduled task

  1. First, make sure the system time is correct

    1. System > System

    2. Make sure the Timezone is properly set

    3. Make sure Local Time is correct. If not, click Sync with NTP-Server

      If syncing with NTP doesn’t work, see below for troubleshooting NTP issues

  2. System > Scheduled Tasks

  3. Create the scheduled task

    For example, if you wanted to start the wireless network every day at 6:00 and shut it down at 21:00:

    0 6 * * * /sbin/wifi up
    0 21 * * * /sbin/wifi down
    
  4. Submit

  5. As mentioned on that page, if there were no scheduled tasks already, you need to restart the cron service:

    System > Startup > find cron and click Restart

NTP

Troubleshoot NTP issues

  1. Before doing anything else, make sure DNS is working

    1. Network > Diagnostics > Nslookup

      If DNS isn’t working, you’ll need to get that fixed before NTP will work

Additional troubleshooting:

  1. Get the command that’s being used to run the NTP client (ntpd):

    tr '\0' ' ' < /proc/$(ps | grep [n]tp | awk '{print $1}')/cmdline; echo
    

    e.g.

    # tr '\0' ' ' < /proc/$(ps | grep [n]tp | awk '{print $1}')/cmdline; echo
    /usr/sbin/ntpd -n -N -S /usr/sbin/ntpd-hotplug -p 0.openwrt.pool.ntp.org -p 1.openwrt.pool.ntp.org -p 2.openwrt.pool.ntp.org -p 3.openwrt.pool.ntp.org
    
  2. Watch the command line to see what the output is, e.g.

    # /usr/sbin/ntpd -n -N -S /usr/sbin/ntpd-hotplug -p 0.openwrt.pool.ntp.org -p 1.openwrt.pool.ntp.org -p 2.openwrt.pool.ntp.org -p 3.openwrt.pool.ntp.org
    ntpd: bad address '0.openwrt.pool.ntp.org'
    ntpd: bad address '1.openwrt.pool.ntp.org'
    ntpd: bad address '2.openwrt.pool.ntp.org'
    ntpd: bad address '3.openwrt.pool.ntp.org'
    

    (In this example, the router isn’t able to find the NTP servers due to DNS misconfiguration)

Flashing firmware via TFTP

Tips

  • Make sure the firewall on the TFTP server is configured to allow TFTP traffic
  • Disable Wifi on the TFTP server
  • Make sure the file on the TFTP server is appropriately named (varies by device)
  • Make sure the router is connected to the TFTP server on the appropriate port (varies by device)
  • Connect the router directly to the TFTP server using a normal network cable (not a crossover cable)

TFTP server setup on Ubuntu

  1. Install TFTP server

    sudo apt install atftpd
    
  2. Copy the firmware to /srv/tftp/

  3. Change permissions of the firmware

    sudo chown nobody:nogroup -R /srv/tftp
    
  4. Tail the TFTP logs

    sudo journalctl -f | grep --line-buffered tftp