OpenWrt on Raspberry Pi: Use your Pi as a router (Tutorial)

Recent Raspberry Pi models are more powerful than traditional routers, so using one in this role could be interesting. But it’s not perfect, as they are not supported by most router software (or only in command lines). Fortunately, OpenWrt might be the solution. It’s available on Raspberry Pi with a web interface to configure everything. Let’s learn how to use it.

OpenWrt has a custom release available on its website for all Raspberry Pi models. It can be flashed on an SD card like any other operating system. A few commands are required to configure the network on the first boot, but after that, everything can be done from the web interface.

Even if you are used to OpenWrt on a PC or traditional router, the installation process and initial configuration are quite different. So, let me guide you through the first steps until you get access to the web interface to do everything as usual.

If you’re new to Raspberry Pi or Linux, I’ve got something that can help you right away!
Download my free Linux commands cheat sheet – it’s a quick reference guide with all the essential commands you’ll need to get things done on your Raspberry Pi. Click here to get it for free!

Prerequisites: Before Installing OpenWrt

Before installing OpenWrt on your Raspberry Pi, there are a few prerequisites to keep in mind. Let me explain.

Update Your Bootloader

All Raspberry Pi models have a piece of code directly on the main board (not on the SD card) to handle the boot process. It has been frequently updated since the initial release (for example for USB and network boot support, bug fixes, etc.).

OpenWrt requires that your bootloader (the EEPROM package) is up-to-date.
This update is done automatically on Raspberry Pi OS, so if you’ve already used it (and have done the updates) on your Raspberry Pi, it’s probably already OK.

But, if you just bought the Raspberry Pi, they recommend installing Raspberry Pi OS first, updating the EEPROM, and only then installing OpenWrt.

Here is how to check if the bootloader is up-to-date on Raspberry Pi OS:

• In a terminal, run this command:
  sudo rpi-eeprom-update
• It will tell you which version you have and if an update is available.
• If needed, you can then install the update with:
  sudo rpi-eeprom-update -a
sudo reboot

Once done (after a full restart), you can stop the Raspberry Pi, and follow the next steps to install OpenWrt on it.

Quick note: If you find it hard to remember all these commands, I’ve put them all on a one-page cheat sheet. You can download it for free here so you have it handy whenever you're working on a project.

Warning: Avoid Network Conflicts

As with most routers, OpenWrt will be set up with the IP address 192.168.1.1 by default on the first boot. There is a high probability that your current router is already using this IP address, which can create conflicts on your network.

If you don’t want to break anything, it’s probably better to unplug the Ethernet cable on the first boot or to create a different physical network while following this tutorial.

You can for example use a small network switch (I use this one on Amazon), plug the Raspberry Pi and your PC into it, and manually set your computer to use any IP starting with 192.168.1.X.

If you’re having a hard time with all the technical details, I can help you.
I’ve written a book to help you move from a beginner’s level to a more advanced one with Raspberry Pi (and everything that comes with it: Linux, network stuff, programming). Thousands of readers have finally become more familiar with this jargon and can now complete fun and useful projects easily.
⇒ Get your copy here.

Hardware Requirements

If you aren’t creating a separate network (especially if your main network is on the same range), you’ll need a keyboard and monitor plugged into the Raspberry Pi.

In my case, my home network starts with 192.168.222.X, so it won’t create any conflict. But I won’t be able to connect to 192.168.1.1 from my computer. So, I will change the Raspberry Pi IP address manually, with a few command lines, a keyboard, and monitor are required for this.

For your information, OpenWrt starts with a QWERTY configuration (US default) and doesn’t support any other layout. If, like me, you use something else, you might need this for the first boot:

Aside from that, you don’t need anything special.
Here’s what I’m using while testing this tutorial for you:

• Raspberry Pi: OpenWrt supports almost every board, including the newest Raspberry Pi 5. For this tutorial, I’m using a Pi 4 with 4 GB RAM.
• A good SD card: you don’t need anything fancy, the image is tiny, and the archive is less than 100 MB!.
• My Raspberry Pi monitor (link to my review) with a micro-HDMI cable.
• My new favorite keyboard from Rii.
• An Ethernet cable.

That’s it, let’s see how to install OpenWrt on it now.

Install OpenWrt on Raspberry Pi

Here are the required steps to install OpenWrt on Raspberry Pi:

• Download the latest image from the official Wiki.
• Flash it onto an SD card.
• Boot the Raspberry Pi.
• Configure the network interface.
• Access the web interface.

Let’s discuss how to do each of these steps in detail.

Download OpenWrt from the Official Website

The first step is to download the latest image available from the official Wiki.

On that page, find this table:

Find the column corresponding to your Raspberry Pi model. Click on the link in the “Firmware Openwrt Install” column to download the .gz image file. There’s no need to extract it.

Flash the Downloaded Image

Once the image is downloaded, flash it onto your SD card. I use Raspberry Pi Imager in general when I already have the image on my PC, but other tools like Balena Etcher should work just fine.

Here are the steps to flash the image:

• Start Raspberry Pi Imager (or your favorite tool).
  Imager is free and can be downloaded here if you don’t have it yet.
• Insert your SD card into your computer using an SD Card reader.
• Click Choose OS > Use custom and point to the file you downloaded above.
• Click Choose Storage and select your SD card.
• Click Next, and when asked to apply settings, hit No.
  After confirming, the write process will begin.

As you can see, the image is tiny (14 MB in this example), so it’ll only take a few seconds.

First Boot

Once the SD card creation is complete, insert it into your Raspberry Pi and power it on.

You’ll see a bunch of debug messages (white text on a black screen). Once it stops scrolling, press Enter to get access to the command prompt:

If you get the same thing, everything is fine, and you can move to the next step.

If it doesn’t start, or you get an error, double-check the prerequisites (especially the EEPROM update) and feel free to visit the OpenWrt forum to ask for help.

Optional: Set the Ethernet IP Address

As explained previously, OpenWrt will set the Ethernet adapter to 192.168.1.1 by default. If it’s fine for you, you can probably skip this step and access the web interface directly.

But in most cases (and for me), it needs to be changed.
My network is using the range 192.168.222.1-254, and I want to access OpenWrt from my other devices.
Or maybe 192.168.1.1 is already taken by your primary router, so you need to change the OpenWrt to use a different IP.

Either way, you can change the default IP address using these three commands:
uci set network.lan.ipaddr=>YOUR_IP>
uci commit
/etc/init.d/network restart

Remember: the default keyboard layout is in QWERTY (US), so you might need to use the picture given previously to type these commands.

If you started with the network cable disconnected, to avoid any conflict, you can now plug it in and move on. In my case, I can now ping the Raspberry Pi, so I’m ready to configure it.

Access the Web Interface

Now that you’ve got the OpenWrt device connected to your network, all of its configuration can be done from a web interface. So, you won’t have to use console commands anymore.

• Open a web browser from a PC on the same network as the Raspberry Pi, and visit the Pi’s IP address:
  http://<YOUR-IP>
It’s the IP you just set in the command line, or maybe it’s 192.168.1.1 if you haven’t changed it.
• The default username is root, and the password is left blank.

You’ll get connected to the full interface of OpenWrt, but before going any further, setting a root password is a good idea.

Set the root password

The first step once connected to the web interface will be to set a password for root.

Go to System > Administration, and you’ll get a form looking like:

Fill in a strong password, and click Save to apply the change.

Tips to Use OpenWrt on Raspberry Pi

We’re almost done, but let me give you a few tips to use OpenWrt on your Raspberry Pi.
My goal today is not to host a masterclass on OpenWrt, but at least explain the first steps to get you started the right way.

Switch to SSH

As soon as you have set the IP address and the root password, the SSH service becomes available.

So, if in the future you need to run a few command lines on OpenWrt, it will probably be more comfortable to use your SSH client instead of typing them directly on the Pi.

You can log in with root. On most operating systems, you can use this command from a terminal:
ssh root@IP

Type the password you just set, and you’ll be connected.

If you need more guidance on how to use SSH with a Raspberry Pi, click the link to read my full guide about it. It’s mostly for Raspberry Pi OS, but the principles are the same with any distribution (and I share my favorite SSH client in it).

Update System Time

When you install OpenWrt fresh, it will often have the wrong date. This misalignment can interfere with updating packages later.

Here’s how to update your system time on OpenWrt:

• Go to System > System
• Under the General Settings tab, click either Sync with browser or Sync with NTP-Server.
  You can try both for good measure.
  
• Wait 5-10 seconds for it to sync. It will update your system to UTC date and time, which is a good default.
• Click Save & Apply at the bottom.

Now the Local Time should be correct (don’t forget it’s in UTC).

Configure the DNS Server

I had many issues with the web interface at first, but I quickly identified the reason.
For example, I was getting these errors when trying to update new packages:

• Failed to download the package list from X
• opkg_download: Check your network settings and connectivity.
• Failed to send request: Operation not permitted.

That’s because we haven’t set a DNS server for OpenWrt to use, so almost everything that requires Internet access won’t work. There are 2 possible solutions here.

Solution #1: Use Custom DNS Servers

• In the web interface, go to Network > Interfaces.
• Click Edit in front of the LAN interface.
• Go to the Advanced Settings tab and find the field Use custom DNS servers.
• Fill in the address of your preferred DNS server. You can use one on the local network if you have one, or simply a public DNS server (I’m testing with 8.8.8.8, the one from Google).
  
• Click Save. Back on the next screen, don’t forget to hit Save & Apply.
  

Solution #2: Change Protocol to DHCP Client

If the above method didn’t work for you, try this one.

Usually, people will turn an OpenWrt device into a router that’s connected straight to the internet. But in my case, the OpenWrt-Pi was sitting behind another router, my primary router. This configuration caused DNS issues where OpenWrt couldn’t access the internet.

One solution is to make OpenWrt receive its DNS from your primary router. Here’s how:

• Go to Network > Interfaces.
• Click Edit.
• Under the General Settings tab, change Protocol to DHCP client.
  
• Click Save. Back on the next screen, hit Save & Apply.

Your Pi will reconnect to the network and receive a new IP address. You’ll have to figure out your Pi’s new IP address, since it will be randomly applied.

Once you can reconnect to the web interface, check if the internet access is working.
Go to Network > Diagnostics and click IPv4 Ping. If it works, you should get a response.

Install Add-ons

If the Internet connection is available and the DNS server is configured properly, you can now use the Software feature in the web interface to install new packages.

The System > Software page is pretty empty by default. Click on Update lists… to sync with the repository. You should get something like:

Note: If your update fails, it’s probably because OpenWrt can’t reach the internet. To check, go to Network > Diagnostics and try to ping a domain. If pinging fails, use the methods in the sections above to fix your DNS settings.

Similar to how packages work on Raspberry Pi OS and most Linux distributions, you can easily install new packages on OpenWrt from this page (we’ll use it later).

You’ll find drivers for specific devices, as well as traditional packages (that you can use in command lines) or features for the web interface. There is a search engine you can use to quickly find something here.

Enable the Wireless Interface

On my Raspberry Pi 4, there is a wireless interface, and it was detected automatically. So, you can quickly configure it and use it once you get access to the web interface.

I lost a bunch of time testing this because I was trying to configure it from the “Network” > “Interfaces” menu, but in fact, it was already there under “Network” > “Wireless”.

If you use a Raspberry Pi 4, you should have something like:

Click on “Scan” to see a list of the wireless network detected.
Click on the one you want to be connected to and fill out the form with your password:

Follow the steps in the wizard to save the configuration and get connected to your Wi-Fi.
If everything goes well, you should now see both network configurations on the home page:

It’s a pretty bad example, as I should use two different network ranges if my goal was really to build a router. But I’m just showing you how to configure the basics. After that, you’re free to change anything to fit your needs.

For example, once connected to your Wi-Fi, you can now configure the Ethernet to use a different network range, to isolate your Ethernet network from the other computers.

How to Use a USB adapter

Raspberry Pis only have an Ethernet adapter, which is not great to build a router. On some models, you have the wireless interface, but not all of them. Good news: if your case uses a USB to Ethernet adapter with OpenWrt, it’s supported!

I have one model (from a random brand from Amazon), and when I plugged it in, it was detected directly.

On the monitor, I got these messages:

Even if OpenWrt is detecting that you plugged something, it won’t necessarily have the driver installed by default (and it’s not plug & play, you’ll need to install it).

There are two things to note in the previous screenshot:

• The manufacturer is Realtek. We don’t care about the brand noted on the adapter, the important element is the network adapter manufacturer, which is generally Realtek or Intel.
• The exact model is 8153 (RTL8153).

With this info, you can go into the software installer and search for the corresponding driver. If you have a different adapter, make sure to search for your exact model.

The search engine is not perfect, though. In my case, there was no result, whatever I tried. I found online that you can use the RTL8152 driver for the 8153 model. So, I installed it, and it was then detected properly in the web interface.

But you might need to do a little bit of research to find the correct driver that is missing.

Once done, you can go to “Network” > “Devices” and you should see your USB adapter here:

Click on “Configure” to create a new interface using this network device.

Going Further with OpenWRT

From there, using OpenWrt on your Raspberry Pi wouldn’t be different from using it on any other device. You have access to the web interface and your hardware is properly detected (even if you use USB adapters), so you can move on and create the configuration you need.

As I told you, my goal here was to help you to get started when using a Raspberry Pi instead of a more traditional device. If you need more guidance, you can follow the official documentation or any good tutorial online, even if it’s not written for Raspberry Pi.

And if you don’t like OpenWrt and want to try the old school method (with IPTables), you can follow this other tutorial I wrote years ago, explaining how to do everything manually :-). There is also a brief introduction in it about networking in general, that might be interesting even if you do the same project with OpenWrt.

An alternative to iptables, while staying in command lines, would be to test “ufw” which stands for “Uncomplicated FireWall”. I explain everything in this article.

Whenever you’re ready, here are other ways I can help you:

Test Your Raspberry Pi Level (Free): Not sure why everything takes so long on your Raspberry Pi? Take this free 3-minute assessment and see what’s causing the problems.

The RaspberryTips Community: Need help or want to discuss your Raspberry Pi projects with others who actually get it? Join the RaspberryTips Community and get access to private forums, exclusive lessons, and direct help.

Master your Raspberry Pi in 30 days: If you are looking for the best tips to become an expert on Raspberry Pi, this book is for you. Learn useful Linux skills and practice multiple projects with step-by-step guides.

Master Python on Raspberry Pi: Create, understand, and improve any Python script for your Raspberry Pi. Learn the essentials step-by-step without losing time understanding useless concepts.

You can also find all my recommendations for tools and hardware on this page.