Preface

MintFlow NetStack is a brand new networking toolkit for apple platform.

MintFlow NetStack is built upon the open-source fd.io VPP project, which is the world's fastest and most secure networking data plane. network stack and can be intergrated to Linux/FreeBSD operating systems.

Our team has successfully ported it to the Apple Darwin operating system (which is the core operating system used by iOS, tvOS, and macOS).

Goals

These are the goals of the MintFlow NetStack App. We are working hard to gradually deliver all the following features.

  • Support multiple high performance L3 VPN protocol(WireGuard/IKEv2&IPsec ...)
  • Support well-known L4 proxy protocol(VMESS AEAD/Shadowsocks/Socks5 ...)
  • Support Application Routing (more advanced version of Split Tunneling)
  • Support multiple profiles which you can manage different VPN provider and app routing routes and switch as your need
  • Support deployed to tvOS/macOS as a software router by leverage VPP's high performance routing capability
  • Support HTTPS MITM and header rewrite
  • Support firewall capability
  • Support packet capture and generation
  • Support DPI (possible macOS only due to iOS memory limitation) by leverage nDPI with firewall

Revision History

  • 20250509, create initial manual for user to use MintFlow NetStack efficiently.
  • 20250531, add L4Proxy virtual interface and update document.

Basics

In this chapter, we will cover basic concepts of MintFlow NetStack.

Architecture

Architecture Diagram

Here's a brief diagram showing the MintFlow NetStack Network Extension architecture and how user-installed apps leverage it to improve privacy and unlock limited content.

MintFlow NetStack Architecture

Important Concepts

UTUN Interface

When the Network Extension runs on iOS, Apple allocates a UTUN interface that can be configured to route packets by IP address using LPM (longest prefix match) to the UTUN interface. These packets are then received by the Network Extension's process for handling.

By default, MintFlow NetStack will configure to route all App's traffic to UTUN interface, to enable user to do advanced routing and filtering.

MintFlow NetStack settings include an 'Exclude LAN Networks' toggle that excludes the following well-known LAN network ranges from entering the UTUN interface:

  • 10.0.0.0/8
  • 172.16.0.0/16
  • 192.168.0.0/16

Important: If your L3VPN provides access to remote networks using the same LAN ranges listed above, you must not enable this option. Otherwise, you won't be able to reach the networks that your L3VPN provides.

fd.io VPP

This is the core differentiator of MintFlow NetStack. Unlike other VPN apps that use the LwIP stack, we've ported fd.io VPP for the Apple platform to achieve a WireGuard implementation written in pure C for optimal performance. We also leverage VPP's advanced host stack to perform TCP/IP session reconstruction and dispatch sessions to local internet or proxies.

DNS Server

When users enable app routing in MintFlow NetStack, it starts an internal DNS server that handles domain queries initiated by iOS or user-installed apps.

The app routing rules that match domain sets determine which upstream DNS server the internal DNS server will query. The results are then populated to fd.io VPP to route the packets/sessions to L3VPN/L4Proxy/Direct/Drop/Reject virtual interfaces.

L3VPNs

For L3VPN protocols, we implement them natively in fd.io VPP using the C language, allowing us to use VPP's vectorized packet processing for maximum performance.

For L4Proxy protocols, we implement them in Rust, a memory-safe language that increases stability while maintaining low runtime overhead. We use an internal high-performance protocol to proxy packets in and out of fd.io reconstructed sessions.

Components

This chapter will briefly describe components of MintFlow NetStack App.

MintFlow NetStack UI

This is where you can create VPN interfaces and configure app routing routes and other capability of the App.

It can be closed while the MintFlow NetStack VPN is running in backround as an Apple Packet Tunnel extension.

MintFlow NetStack Packet Tunnel Extension

This is the core component that leverages Apple's Packet Tunnel Provider capability to process all your app's traffic and route packets or flows according to the app routing routes.

It can be further divided into the following sub-components:

  • Packet Processing Core(VPP Core)

    the core compoenent that handles routing, VPN encryption and decryption, and Apple local network proxying.

  • Internal DNS server(When App routing enabled)

    the DNS component that answers iOS app domain queries and interacts with VPP Core to route packets related to the domain to VPNs.

Since MintFlow NetStack is not a simple proxy, it will, by default, request the Apple operating system to route ALL your app's traffic1 to the Tunnel Extension. Packets will then be routed according to the app routing routes.

  1. You can exclude well-known LAN network CIDR ranges from entering the VPN in the VPN Settings of the app. ↩

Interface

An interface is an abstract concept in MintFlow NetStack that allows you to steer app traffic.

For example, if you create a WireGuard (L3VPN1) interface, you can steer all your iOS app's traffic to it by specifying a special CIDR route (0.0.0.0/0), which directs all IPv4 traffic to the interface. This provides high privacy and eliminates concerns about IP leakage in high-risk environments.

Currently MintFlow NetStack support the following interface types:

  • L3VPN interface

    This is the interface where packets will be encrypted and routed to the VPN server using IP based processing, since it does not need to reconstruct TCP/UDP sessions using fd.io VPP hoststack, which is more efficient.

    Currently WireGuard L3VPN is supported.

  • L4PROXY interface

    This is the interface where packets will be encrypted and routed to the remote VPN server using session based processing, it need to reconstruct TCP/UDP sessions using fd.io VPP hoststack, which is less efficient compared to L3VPN interface.

    Currently the following L4PROXY types is supported:

    • VMESS-WS-TLS (with AEAED ciphers)
    • Shadowsocks with AEAD ciphers

  • Direct Virtual interface (Requires App Routing Enabled)

    This is the interface where packets will be routed to local internet, be it WIFI or Cellular.

  • Reject Virtual interface

    This is the interface where TCP packets will be rejected by sending RST, which is mainly used for AdBlock, which quickly to make app believe the Ad related domain reject the connection. for UDP packets, it's behavior is same with Drop Virtual Interface.

  • Drop Virtual interface

    This is the interface where packets will be dropped silently. it can be used to implement AdBlock.

We are developing new L4Proxy2 interface to satisfy more user scenarios.

  1. L3VPN is a type of VPN technology that basically only route packet by it's IP address. ↩

  2. L4Proxy is a type of VPN technology that basically handle TCP/UDP session. ↩

App Routing

App1 Routing is defined as follows:

App Routing is a feature that allows users to route specific apps to different interfaces by matching the app's domains and IP ranges.

Currently MintFlow NetStack support the following Routing Criteria:

  • CIDR

    This is plain CIDR route, such as 0.0.0.0/0, 1.1.1.1/32 which match a IP range or Host. 0.0.0.0/0 is the default route and must be have routes configured.

  • Domain Set

    This is a set where users can add the various domains of a SaaS application or app (like Netflix) and route all traffic related to that set to an interface.

  • CIDR Set

    This is a set where users can add the various IP ranges of a SaaS application or app (like Netflix) and route all traffic related to that set to an interface.

  • DNS fallback

    This is a special route which is used only when App Routing is enabled, it's used to specify which DNS server should be used when iOS apps query a domain that is not present in any of configured Domain Sets.

In the future, if we add a DPI engine to the app, we may route apps based on DPI results.

  1. An App can be a iOS App, or a plain WebSite, or a SAAS application. ↩

Scenarios

This chapter provides a few sample configuration of the MintFlow NetStack App.

You can customize your own configuration according your requirement use this as a reference.

Privacy-VPN

Sample Configuration

L3VPN/L4Proxy interface

Let's use WireGuard L3VPN interface as example.

You can create a WireGuard L3VPN interface by the following ways:

  • Import a WireGuard configuration from iCloud, the config file can be downloaded from major VPN provider such as Mullvad, Windscribe and etc.
  • Scan the QR code with your phone camera, VPN provider such as Mullvad support generate QR code
  • Create WireGuard interface manually based on you self-hosted WireGuard server.

App Routing

In this scenario, you do not need to enable App Routing.

You should add a simple CIDR route in the App Routing section.

the route should be 0.0.0.0/0 and point to a L3VPN interface you created in the above step.

VPN & DNS Settings

You should set up the primary and secondary DNS servers in the DNS Settings section of the VPN Settings.

Recommended DNS servers are 8.8.8.8 (Google) and 1.1.1.1 (Cloudflare).

You do not need to specify the route for the DNS server since it's covered by the above 0.0.0.0/0 route.

Desired Behavior

With this configuration, most of your iOS app's traffic will be routed to the local internet, but some Ad traffic will be just dropped to give you a clean browsing experience.

Selective-VPN

This scenario can help you selectively send some app traffic to an L3VPN/L4Proxy while keeping most other app traffic on your local internet connection (Wi-Fi or cellular network), to imporve your experience when using VPNs.

Sample Configuration

L3VPN/L4Proxy interface

Let's use WireGuard L3VPN interface as example.

You can create a WireGuard L3VPN interface by the following ways:

  • Import a WireGuard configuration from iCloud, the config file can be downloaded from major VPN provider such as Mullvad, Windscribe and etc.
  • Scan the QR code with your phone camera, VPN provider such as Mullvad support generate QR code
  • Create WireGuard interface manually based on you self-hosted WireGuard server.

App Routing

In this scenario, you do need to enable App Routing, please enable it in the App Routing toggle of the main screen of the App.

You should add the following routes in the App Routing section:

  • VPN Domain Set to L3VPN interface created by the above step

    First, create the domain set and add the domains related to the apps you want to route to the L3VPN interface. this route will route all the traffic associated with the domains in the VPN Domain Set

  • VPN CIDR Set to L3VPN interface created by the above step 1

    First, create the CIDR set and add the IP ranges related to the apps you want to route to the L3VPN interface. this route will route all the traffic associated with the IP ranges in the CIDR Set

  • VPN DNS server IP CIDR to the L3VPN interface

    Create a route for the VPN DNS server you configured in the Split DNS Settings.

    this route will ensure that domain queries from the VPN Domain Set to the VPN DNS server use the L3VPN interface instead of the local internet, which may cause DNS pollution, provide incorrect IPs, and prevent the apps from working correctly.

  • DNS fallback route to Direct Virtual interface

    since you only define limited domains in Domain Set, thus you must configure a DNS fallback route to specify the domains not present in any Somain Sets should be handled, by set to Direct Virtual interface, the domains will be queried using Direct DNS servers configured in the below step.

  • 0.0.0.0/0 to Direct Virtual interface.

this will keep most of the traffic routed to the local internet.

VPN & DNS Settings

You can't set up the primary and secondary DNS servers the DNS Settings of the VPN Settings because will iOS will use internal VPN server of the MintFlow NetStack if App Routing is enabled.

You must set up both the VPN DNS servers and the Direct DNS servers in the Split DNS settings.

You do not need to specify the route for the Direct DNS server since it's covered by the above 0.0.0.0/0 route.

To differentiate VPN DNS and Direct DNS servers, we recommend you use the following servers:

  • VPN DNS servers

    Use 8.8.8.8 and 8.8.4.4. Some VPN providers, such as Windscribe, provide customized DNS servers that can perform ad blocking. You can find these in the WireGuard configuration file or view them in the app's interface section, where we have saved the original configuration data as debug data.

  • Direct DNS servers

    Use 1.1.1.1 and 1.0.0.1, or other local internet-provided DNS servers, or your self-hosted Pi-hole DNS server.

Desired Behavior

With this configuration, only the traffic of selected apps will be routed to the VPN, while most of the remaining iOS app traffic will be routed to the local internet.

This scenario can be used to unlock some content blocking(such as NetFlix) in you location.

  1. this is optional if the Apps only used domains to provide service for you. ↩

AdBlock-Without-VPN

This scenario can help you to block some Ad traffic without using a VPN provider.

Sample Configuration

L3VPN interface

You do not need to create any L3VPN interfaces.

App Routing

In this scenario, you do need to enable App Routing, please enable it in the App Routing toggle of the main screen of the App.

You should add the following routes in the App Routing section:

  • Ad Domain Set to Drop interface

    you should first create the domain set and add some Ad domains you want to block. this route will block all the traffic associated with the domains in the Ad Domain Set

  • Ad CIDR Set to Drop interface1

    you should first create the CIDR set and add some IP ranges related the Ads you want to block. this route will block all the traffic associated with the IP ranges in the Ad CIDR Set

  • DNS fallback route to Direct Virtual interface

    since you only define limited domains in Domain Set, thus you must configure a DNS fallback route to specify the domains not present in any Somain Sets should be handled, by set to Direct Virtual interface, the domains will be queried using Direct DNS servers configured in the below step.

  • 0.0.0.0/0 to Direct Virtual interface.

    this will route most of the traffic to the local internet.

VPN & DNS Settings

You cannot set up the primary and secondary DNS servers in the DNS Settings of the VPN Settings because iOS will use the internal VPN server of the MintFlow NetStack if App Routing is enabled.

You do not set up the VPN DNS servers in the Split DNS settings, since no domains will be routed to the VPN.

You need set up the Direct DNS servers in the Split DNS settings, since all the domains will be queried using the Direct DNS servers2.

You do not need to specify the route for the Direct DNS server since it's covered by the above 0.0.0.0/0 route.

Desired Behavior

With this configuration, only selected App's traffic will routed to the VPN, most of the remaining iOS app's traffic will be routed through local internet.

This scenario can be used to unlock some content blocking(such as NetFlix) in you location.

  1. this is optional if the Apps only used domains to provide service for you. ↩

  2. blocked Ad domains's IP will be blackholed in the Packet Processing Core. ↩

App Release Notes

20250610, v1.2.1(iOS)

  • add Shadowsocks with AEAD ciphers support
  • fix some crash and connection prematurely close issue
  • UI styling enhancement

20250531, v1.2.0(iOS)

  • add VPN On-Demand support.
  • add L4Proxy virtual interface, with initial VMESS-WS-TLS(AEAD supported) support is added.
  • add a REJECT virtual interface, which behavior better for AdBlocking rules compared with DROP virtual interface.
  • optimize app routing DNS result processing delay.
  • optimize app log and add a in-app log viewer
  • various stability and performance bugfixes

20250430, v1.1.1 (iOS)

  • Added support for proxying UDP/TCP traffic to the local internet using VPP’s advanced host stack
  • Introduced App Routing: split traffic by CIDR, CIDR Set, or Domain Set with support for Direct, DROP, and L3VPN actions
  • WireGuard interface can now be created by importing config files via iCloud
  • UI enhancements for improved usability
  • Various bug fixes and performance optimizations

Resources

App Domains/CIDRs

You can use MintFlow NetStack's in-app DNS cache viewer to get the domains of the current app and fine-tune your app routing routes. However, if you find that difficult, you can use the following resources.

  1. NETIFY is a paid DPI service that provides only samples of app domains and IP ranges. Its data is not complete on the website. ↩