[Tutorial] Build OpenWrt with Multipath TCP

This tutorial explains building OpenWrt images with out-of-tree MPTCP (MPTCPv0 & MPTCPv1) support.

Disclaimer: We can no longer use out-of-tree MPTCP on OpenWrt 22.03 and newer since upstream MPTCP (supports only MPTCPv1) is included instead. I will write a tutorial for building OpenWrt with upstream MPTCP in the future.

There are a few reasons to build your own image to use MPTCP instead of using solutions like OpenMPTCPRouter:

  • Only a few devices are supported.
  • Firmware is heavily bloated, making it impossible to run the image for devices with small flash.

Official out-of-tree MPTCP patches won't work with the kernel used on OpenWrt

Official out-of-tree MPTCP patches only support minor releases of the Linux kernel (starting with 4.9). OpenWrt uses patch releases of the Linux kernel.
Because of this reason, you can't use the patches from the official website.

Wikipedia page explaining major, minor and patch versions.

I maintain my own patches for patch versions of the Linux kernel by diff'ing the official out-of-tree MPTCP branch against the upstream kernel it’s based off of, here:

Building the image

For OpenWrt 21.02

Clone the repository and checkout the commit

git clone https://git.openwrt.org/openwrt/openwrt.git && \
cd openwrt && \
git checkout v21.02.2

Download the patch to target/linux/generic/hack-5.4

curl -L 'https://github.com/arinc9/openwrt/raw/openwrt-21.02-mptcpv0/target/linux/generic/hack-5.4/999-mptcp_v0.96.patch' -o target/linux/generic/hack-5.4/999-mptcp_v0.96.patch

For OpenWrt 19.07

Clone the repository and checkout the commit

git clone https://git.openwrt.org/openwrt/openwrt.git && \
cd openwrt && \
git checkout v19.07.9

Download the patch to target/linux/generic/hack-4.14

curl -L 'https://github.com/arinc9/openwrt/raw/openwrt-19.07-mptcpv0/target/linux/generic/hack-4.14/999-mptcp_v0.94.patch' -o target/linux/generic/hack-4.14/999-mptcp_v0.94.patch

Disclaimer: 19.07 uses kernel 4.14 which MPTCP v0.94 is used instead. MPTCP v0.94 does not support MPTCPv1.


Update feeds and configure menuconfig

./scripts/feeds clean && ./scripts/feeds update -a && ./scripts/feeds install -a && make menuconfig -j$(nproc)

Configure the device model and enable luci at LuCI -> Collections by pressing "y".

Test the patches to see if they apply

make target/linux/{clean,prepare} V=s

Configure kernel menuconfig, this will take a while

make kernel_menuconfig -j$(nproc)

Enable MPTCP protocol then MPTCP: advanced path-manager control & MPTCP: advanced scheduler control at Networking support -> Networking options by pressing "y".
Screenshot 2021-07-18 194701

Enable MPTCP Full-Mesh Path-Manager then choose Default MPTCP Path-Manager as Full mesh at Networking support -> Networking options -> MPTCP: advanced path-manager control by pressing "Enter".

If you'd like to enable MPTCP TCP congestion controls and set default, you can do so at TCP: advanced congestion control.
Screenshot 2021-07-18 194635

Finally, make the image

make -j$(nproc)


Using shadowsocks-libev & v2ray

  • v2ray is recommended for use instead of shadowsocks-libev because of significantly better performance.


v2ray-core: https://github.com/arinc9/v2ray-openwrt
luci-app-v2ray: https://github.com/kuoruan/luci-app-v2ray


opkg update && opkg install luci-app-shadowsocks-libev shadowsocks-libev-config shadowsocks-libev-ss-local shadowsocks-libev-ss-redir shadowsocks-libev-ss-rules shadowsocks-libev-ss-server shadowsocks-libev-ss-tunnel


Here's my Multipath TCP knowledgebase:

Here's the aggregation solution I use:


It took me 3 days to test the patches and make the guide. Have fun!

  • 05/01/2021 Update: Made a list of packages to install for use with LuCI.
  • 04/03/2021 Update: Updated snapshot commit to the latest kernel version which the kernel patches work.
  • 23/05/2021 Update: Here's the knowledgebase I created about Multipath TCP.
  • 09/06/2021 Update: Updated snapshot commit to the latest kernel version which the kernel patches work, removed unneeded patches from 19.07 and snapshot, changed patch directory from specific platform to generic & made shadowsocks optional.
  • 11/06/2021 Update: Fixed the download location of the patch which broke the tutorial. Sorry about that.
  • 19/06/2021 Update: Changed disclaimer about official MPTCP patches, added steps for OpenWrt-21.02, changed steps to enable MPTCP support using kernel menuconfig & moved openmptcprouter feed from MPTCP support to proxy tools.
  • 23/06/2021 Update: Removed OpenMPTCPRouter feed & changed the way of installing the proxy tools.
  • 18/07/2021 Update: Updated snapshot commit to the latest kernel version which the kernel patches work, simplified cloning the repository, added visual explanation to enabling MPTCP on the kernel menuconfig, included MPTCP scheduler, option to enable TCP congestion controls and change the default TCP congestion control.
  • 03/11/2021 Update: Updated to the latest OpenWrt-21.02 version which the kernel patches work. Renamed snapshot to trunk and added warning about newer kernel versions. Updated the URL to retreive the MPTCPv0 patch for OpenWrt-21.02 & trunk.
  • 23/12/2021 Update: Replaced the patches from Ysurac with mine as I maintain my own patches now. Added support for OpenWrt 19.07.8. Wishing everyone a happy new year!
  • 04/01/2022 Update: Added accurate information about MPTCPv0 & MPTCPv1 and out-of-tree & upstream implementations. Put my Multipath TCP & Aggregation Solution pages on the post.
  • 20/01/2022 Update: Slight syntax changes to retrieve patches with curl.
  • 02/04/2022 Update: Remove building for trunk as it's not possible anymore. Add a disclaimer about it. Remove mentions to the patch supporting certain patch versions of the Linux kernel as the patch can be slightly modified to apply to any patch version of the Linux kernel. Update the patches to apply to the kernel versions used on OpenWrt 21.02.2 and 19.07.9.

Your tutorial worked perfectly for D-Link DIR-842 C1!! I didn't get any error at all, just copy pasted everything from your tutorial and it all went smoothly. I flashed the resulting image, and was able to verify with external servers that MPTCP actually works! Thanks a lot! :grinning:

That's great to hear! I'm using this solution on my router Linksys WRT32X as well. Getting 200/13mbps speed over v2ray socks connection. I couldn't get full speed on shadowsocks. I even ran a few tests here. Quoting from there:

  • Shadowsocks (shadowsocks-libev & v2ray)
    • shadowsocks-libev gives max of 50mbps speed
    • v2ray gives max of 110mbps speed
  • SOCKS5 (SSH & v2ray)
    • SSH gives max of 50mbps speed
    • v2ray gives full speed

First time I am hearing of v2ray. Will have to check it out.

It would be interesting to test Wireguard performance. If v2ray is giving you full speed, I suspect Wireguard would give you full speed too

WireGuard uses UDP as the transport protocol. You wouldn’t benefit of MPTCP as is.

In that case, x2ray is the way to go. I will give it a try see how it works

@arinc9 - Is this procedure still valid?

I haven't tested it on newer kernels but as long as the patches are being updated, it should work. I see that last contribution from Ysurac was made in 6 days, pretty recent.

You should give it a try for your device, see if it works.

Edit: There are new patches on the directory, I will update the post to include them and update the commit if you post success. Other patches are not necessary.

ok thanks. I guess my other concern is that I see a build.sh mentioned in his repo and wondering if anything from this method may be missing vs. his build script. I am trying not to have anything bloated also but to cut down on build time I would also like to leverage the snapshot imagebuilder.

We use kernel patches to support MPTCP and mptcp & mptcpd packages to make it work fullmesh path manager to automatically set up subflows. I know nothing about the build script.
If you think we can leverage that here, definitely let me know.

Do you need some sort of server with a lot of bandwidth to connect your MPTCP router to in order to use MPTCP?

Correct. There is a bunch of hosting services which you can rent a VPS at ~$4 per month. Or even free if you use AWS EC2. Though, there’s a data quota on the free option which they start charging for extra traffic if you exceed it.

@arinc9 - with this method, how are you handling applying these patches?

We put the patches to their respective directory for the architecture we want to build generic folder where they are applied to the kernel. Then, OpenWrt SDK applies the patches and builds the kernel.

This is the same way it’s done for OpenMPTCPRouter and any other OpenWrt-derived distro.

I believe you're only doing these patches:

But not these?

Perhaps these others are being applied by the feed build process?

Sorry, I'm a bit busy these days. I'll briefly answer to your questions.

For OpenWrt Trunk (Snaphot) this is correct but only the mptcp patch is used in this directory.
For 19.07, there's hack-4.14.

Trunk has kernel 5.4, 19.07 has kernel 4.14

The patches at the links below are not related to MPTCP kernel patches, so no, they are not used.

They're not, you have to manually put the patches in the hack-x directory so they can be applied. You can make sense of it by checking this section of the main post:

Download the patches to target/linux/generic/hack-5.4.

@arinc9 - what do you run to setup the VPS with this method?

You just have to install a kernel with MPTCP support. Then, you can set up proxies or VPNs that use TCP as the transport protocol, OpenVPN, DSVPN, SOCKS5, v2ray, etc.

I put a simple knowledgebase on the main post which shows how you can install & boot the MPTCP kernel.

Thanks. So the VPS has to be running Debian or would Ubuntu work?

Anything Linux would work. So yeah.

1 Like