Deploying OpenWrt/iStoreOS with Docker: A Step-by-Step Guide to Turning Your NAS into a Superb Bypass Router

Deploying OpenWrt/iStoreOS with Docker: A Step-by-Step Guide to Turning Your NAS into a Superb Bypass Router

NAS教程
17NAS17NAS
2025/1/10
2178 reads
\n\n

\n \n

\n\n

Beyond storing photos and seeding PT torrents, what else can your NAS do? For anyone who enjoys tinkering with networks, running OpenWrt or iStoreOS in Docker as a "bypass router (gateway)" is the best value for money. Whether you have a Synology, a QNAP, a Raspberry Pi, an N1 box, or even a Wangxin Cloud OEC, as long as the device supports Docker you can follow this tutorial to supercharge your home network (ad blocking, extra features, and more) without touching your main router configuration.

\n

This tutorial skips the waffle and goes straight to hands-on practice, walking you through running OpenWrt perfectly on a single-NIC device using Macvlan mode.

\n\n

1. Avoiding the pitfalls: choose a reliable Docker image

\n\n

There are thousands of firmwares on Docker Hub, and picking the right image saves half your debugging time. After long-term testing, these two images are the most stable:

\n\n

1. The classic general-purpose build: OpenWrt (Sulinggg)

\n

This is the image built by the well-known community figure Susu, with an extremely high download count on Docker Hub. It is highly integrated, ships with all the plugins you would expect, and supports both x86 and ARM architectures (Raspberry Pi, N1, and so on) — a worry-free, out-of-the-box choice.

\n
\n Image address: sulinggg/openwrt
\n\n

2. The lightweight UI build: iStoreOS

\n

If you prefer a simpler interface, or want an app-store-like way to install plugins, iStoreOS is currently the hot favourite. This image is ported from the R2S firmware and is very beginner-friendly.

\n
\n Image address: kowming/istoreos-openwrt-n1-aarch64
\n\n

Terminal pull commands (pick one as needed):

\n 
# pull the OpenWrt image\ndocker pull registry.cn-shanghai.aliyuncs.com/suling/openwrt:armv8\n\n# pull the iStoreOS image\ndocker pull kowming/istoreos-openwrt-n1-aarch64:istoreos
\n\n

2. The core steps: enable promiscuous mode and create a Macvlan

\n\n

This is the key to whether the bypass router works. We need the Docker container to have its own independent IP address, as though it were a device physically connected to the router — which requires Macvlan technology.

\n\n

1. Confirm the network interface name

\n

SSH into your NAS or box (with root privileges) and run the following command to inspect the network interfaces:

\n 
ifconfig
\n

The eth0 shown is usually your physical interface name. Make a note of it.

\n\n

2. Enable promiscuous mode on the interface

\n

For the interface to receive all packets (not just those addressed to it), promiscuous mode must be enabled:

\n 
ip link set eth0 promisc on
\n\n

3. Create the virtual network (Macvlan)

\n

Adjust the IP addresses below to match your own router’s subnet. Suppose your main router is 192.168.100.1, then the subnet is 192.168.100.x.

\n 
docker network create -d macvlan \\\n--subnet=192.168.100.0/24 \\\n--gateway=192.168.100.1 \\\n-o parent=eth0 macnet
\n
    \n
  • subnet: your LAN subnet.
    • \n
  • gateway: your main router’s IP.
    • \n
  • macnet: the name we give this virtual network.
    • \n
\n\n

3. Start the container: the moment of truth

\n\n

With the network in place, let’s start the system. It is best to assign a static IP manually here, to avoid IP conflicts and make future management easier. For example, if the main router is .1, the NAS is .5, we can set OpenWrt to .8.

\n \n

OpenWrt startup command:

\n 
docker run --restart always --name OpenWrt -d \\\n--network macnet --ip 192.168.100.8 \\\n--privileged \\\nregistry.cn-shanghai.aliyuncs.com/suling/openwrt:armv8 \\\n/sbin/init
\n\n

iStoreOS startup command:

\n 
docker run --restart always --name istoreos -d \\\n--network macnet --ip 192.168.100.7 \\\n--privileged \\\nkowming/istoreos-openwrt-n1-aarch64:istoreos \\\n/sbin/init
\n

⚠️ Note: the --privileged flag is very important. It grants the container privileges; without it, network forwarding will not work.

\n\n

4. The final step: fix the network inside the container

\n\n

After the container starts, even though we assigned a specific IP, the image’s internal default configuration may not match your LAN. You must go inside the container and edit the configuration file.

\n\n

1. Enter the container terminal

\n 
docker exec -it OpenWrt /bin/sh\n# if you are on iStoreOS, replace OpenWrt with istoreos
\n\n

2. Edit the network configuration (Vim)

\n

Enter the following command to edit the configuration file:

\n 
vim /etc/config/network
\n\n

\n Operating tips:
1. Press the i key to enter edit mode.
2. Find the section under config interface 'lan'.
3. Change option ipaddr to the IP you set earlier (for example 192.168.100.8).
4. Change option gateway to your main router’s IP.
5. Change option dns to your main router’s IP or a public DNS (such as 114.114.114.114).
6. When you are done, press the Esc key, type :wq and press Enter to save and exit.

\n\n

3. Restart the network service

\n 
/etc/init.d/network restart
\n

At this point you should be able to open a browser, enter 192.168.100.8 and reach the OpenWrt admin panel! The default password is usually password.

\n\n

5. How do you actually use it?

\n\n

Once deployed, your home network does not change at all — everyone else keeps browsing normally and is completely unaffected. That is the beauty of a bypass router.

\n

\n If you want a particular device (a phone, a PC, an Apple TV) to route through OpenWrt:\n

\n
    \n
  1. Open the WiFi settings on your phone or computer.
    2. \n
  2. Set the IP address to manual and enter an IP in the same subnet.
    3. \n
  3. Set the router (gateway) address to the OpenWrt IP (192.168.100.8).
    4. \n
  4. Set the DNS address to the OpenWrt IP as well.
    5. \n
\n\n

Deploying OpenWrt in Docker not only uses few resources, but even if you break something you can just delete the container and start over — an essential skill for NAS enthusiasts. Go ahead and give it a try!

\n\n\n

6. QNAP TS-464C2 hands-on notes: dual 2.5G ports make it even easier

The Macvlan approach above is the universal solution, suited to single-NIC devices. But if you have a QNAP TS-464C2, it has two 2.5GbE ports, which opens up a cleaner path.

First, confirm your machine’s specs

The TS-464C2 packs an Intel Celeron N5095 quad-core processor, 8GB DDR4 as standard (expandable to 16GB), 4 drive bays, dual 2.5GbE ports, two built-in M.2 PCIe Gen 3 slots, and runs the QTS system (switchable to QuTS hero from QTS 5.2.1).

For a bypass router setup, only one thing matters: there are two ports. That means you do not have to wrestle with the various limitations of Macvlan.

Option comparison: Macvlan vs physical port passthrough

Macvlan (the universal option): the host and the container cannot talk to each other directly without extra configuration; promiscuous mode must be enabled; in some environments DHCP cannot obtain an address. The upside is that it works on a single NIC.

Physical port passthrough (available on the TS-464C2): dedicate the second 2.5G port to the OpenWrt container, using --network host or by specifying the physical interface directly. The advantage is no Macvlan and no promiscuous mode required, with the host and the bypass router fully independent and non-interfering — network behaviour closest to a real router.

How to do it on the TS-464C2

  1. In QTS’s "Network & Virtual Switch", confirm the names of the two ports (usually eth0 / eth1).
  2. Leave eth0 for the QTS host (keep using it for the admin panel and file services).
  3. Assign eth1 to the OpenWrt container, connected to the same switch or router.
  4. When creating the container use --network host, or map eth1 into the container through the QTS Docker interface.
  5. Once inside the container, configure OpenWrt’s LAN/WAN onto the interface corresponding to eth1.

Note: the exact interface names depend on your QTS version, so always verify them under "Network & Virtual Switch" first rather than copying eth0/eth1. Different QTS versions also differ in Docker networking support, so it is best to test during a non-critical window.

Is the N5095 enough for a bypass router?

Yes. The N5095 is a quad-core x86 processor, and running a lightweight routing system like OpenWrt is far below its capability ceiling. The real bottleneck is usually port bandwidth rather than the CPU — and the TS-464C2’s 2.5GbE is generous at this price point.

If you also want to run Jellyfin transcoding, Docker apps and a bypass router on this machine at the same time, the N5095’s integrated GPU can share the transcoding load, but keep an eye on memory usage — 8GB is the floor, and expanding to 16GB makes multi-container workloads much more comfortable.

\n

Related reading: IPv6 reachability monitoring report by province · NAT type test · OpenWrt single-line multi-dial speed boost

\n
Back to article list