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

• 20251203, add a dedicate chapter for profile support and it’s syntax.
• 20250922, change some documents after 1.5.0 release, add a howto chatper for user better use the App.
• 20250531, add L4Proxy virtual interface and update document.
• 20250509, create initial manual for user to use MintFlow NetStack

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.

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.

HTTP Engine

When users enable app routing in MintFlow NetStack, you can optional enable HTTP engine which can capture and rewrite HTTP/HTTPS traffic.

L3VPNs&L4Proxies

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.

• HTTP Engine(require App routing enabled)

  the HTTP engine that can capture and rewrite HTTP/HTTPS traffic for selected domains

Since MintFlow NetStack is not a simple proxy, it will, by default, request the Apple operating system to route ALL your app’s traffic¹ 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 (L3VPN¹) 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 L4Proxy² 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

App¹ 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. ↩

HTTP Engine

HTTP Engine can process traffic for any destination, including the traffic routed over Local Interface or L3VPNs or L4Proxies.

Self-signed CA generation for HTTPS MITM

With this feature, user can install locally generated self-signed CA and trust it to decrypt HTTPS traffic using MITM method.

You can generate the self-signed CA and click install from within the App and install the certificate profile.

After you install the certificate profile, you must trust in manually by goto Settings > General > About > Certificate Trust Settings of your phone’s settings.

You can refer to apple officialy document for more information¹.

Add domains that need capture HTTP/HTTPS traffic

By default, NO traffic will be processed by HTTP Engine.

You can add domain from within the App by using domain suffix.

The domain list have nothing to do with the app routing domain set which is used to control traffic destination for the domains in the set.

HTTP Live Capture

After you configure the HTTP process domain list and enable HTTP Engine, and When the VPN is running, you can do live HTTP capture as you will.

Now the App support view HTTP req/resp headers and body part.

HTTP Rewrite

Currently, only URL rewrite is supported, we will add more rewrite capability including HTTP request/response rewrite and rewrite with script.

URL Rewrite

You can add URL rewrite rule from within the App.

For each URL rewrite rule, you provide the following parameter:

• Match Pattern, a regular expression to match URI, such as:

  **^https?://.*doubleclick\.net.*
  

• Action, Reject(return HTTP 404 to App), Redirect(return HTTP 302 to App with new URL)

• Target URL, the new url for Redirect Action.

1. https://support.apple.com/en-us/102390 ↩

Profile Configuration

The text-based profile is a cornerstone of MintFlow, designed to provide power users with a highly flexible and shareable way to control the app’s advanced networking capabilities.

Why Use Profiles?

• Complex Setups: Easily configure sophisticated routing rules, split DNS, and combinations of proxies and VPNs.
• Manage Multiple Configurations: Create and switch between different profiles for various scenarios (e.g., a “Work” profile with a corporate VPN and a “Home” profile for personal use).
• Share and Collaborate: Profiles are plain text, making them easy to share with other MintFlow users, version control with Git, or collaborate on.
• Import and Export: Seamlessly import profiles from URLs or files, and export your configurations to back them up or share them.

MintFlow uses a powerful and flexible text-based profile format to configure all aspects of the VPN and proxy behavior. This document details the syntax and all available configuration options.

Syntax Overview

The profile uses an INI-style format with sections enclosed in [].

# Comments start with # or //
[section-name]
key=value

# Lists are comma-separated
key=value1,value2,value3

# Structured values use subkey:subvalue pairs
key=subkey1:value1,subkey2:value2

Sections

[misc]

This section contains miscellaneous system-level settings.

Example:

[misc]
tun-mtu=1420
exclude-lan-networks=true

[dns]

This section configures the DNS settings.

Example:

[dns]
app-routing-enabled=true
direct-dns=223.5.5.5,114.114.114.114
vpn-dns=8.8.8.8,1.1.1.1

[l3vpns]

This section defines Layer 3 VPN interfaces. The key for each entry is a user-defined name for the interface.

Common Fields

WireGuard Specific Fields (When type=wireguard)

Example:

[l3vpns]
my-wireguard=type:wireguard,nickname:My WG,private-key:...,address:10.0.0.1/32

[wireguard-peers]

This section defines peers for WireGuard interfaces. The key for each entry is a user-defined name for the peer.

Example:

[wireguard-peers]
my-peer=interface:my-wireguard,public-key:...,endpoint:1.2.3.4:51820,allowed-ips:0.0.0.0/0

[l4proxies]

This section defines Layer 4 proxies, like Shadowsocks and VMess. The key for each entry is a user-defined name for the proxy.

Common Fields

Shadowsocks Fields

VMess Fields

Example:

[l4proxies]
my-shadowsocks=type:shadowsocks,server:...,port:443,password:...,method:aes-256-gcm

[domain-sets]

This section defines named sets of domains for use in routing rules. The key is the set name.

Example:

[domain-sets]
social-media=twitter.com,facebook.com,instagram.com

[cidr-sets]

This section defines named sets of IP ranges (CIDRs) for use in routing rules. The key is the set name.

Example:

[cidr-sets]
private-ips=10.0.0.0/8,192.168.0.0/16

[routing]

This section defines the routing rules, which are processed from top to bottom. It does not use key-value pairs.

Rule Format: TYPE,VALUE,ACTION,TARGET

Example:

[routing]
DOMAIN-SET,social-media,L4PROXY,my-shadowsocks
CIDR-SET,private-ips,DIRECT
DEFAULT,L3VPN,my-wireguard

[http-engine]

This section configures the internal HTTP engine.

Example:

[http-engine]
enabled=true
domain-list=example.com
ca-p12=...
ca-passphrase=...

[http-url-rewrite]

This section defines URL rewrite rules for the HTTP engine. The key is a user-defined name for the rule.

Example:

[http-url-rewrite]
block-ads=match:^https?://ads\..*,action:reject
redirect-google=match:^https?://google\.com,action:redirect-302,target:https://duckduckgo.com

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 ¹

  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 interface¹

  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 servers².

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. ↩

HOWTOS

This chapter will provider user a detail guide with App snapshot to guide user better to use the App.

HTTP-Live-Capture

Basic requirement

To make HTTP Live Capture, you need to at least do the following steps:

• Enable App Routing in the Home
• Add Default Route and Dns Fallback route in the Routes, make its action to DIRECT, this will make the MintFlow VPN only send traffic to your local Internet without any VPN servers needed
• Enable HTTP Processing in the Tool/HTTP Engine
• Generate a root CA in the Tool/Http Engine/MITM Certficate, install and trust it in the OS, this will allow the App to capture and decrypt HTTPS traffic.
• Add Interested Domains in the Tool/HTTP Process Domain List
• Start the VPN and do live capture

Here are detail steps and with snapshots to guide you to do the task, all the snapshot is done in a iPhone6s plus device with iOS 15 installed.

Config Steps

Enable App Routing

Just toggle the App routing switch.

Add Routes

When you first install the app and goto the Routes, it will alert you that two required routes is needed to add, you can just click it the add it.

For HTTP live capture case, you just need to keep it’s default action to DIRECT which means all the traffic will be sent to the local Internet after the App process it.

Please note you need to hit the top right Save button to save the routes.

The DNS Fallback route is used to decide which DNS server the internal DNS server of the App will use when process DNS requests from the system.

The Default Route(IPv4) route is used to send all the traffic if you do not configure any specific CIDR/CIDR set routes.

Here is the example snapshot of the saved routes:

Enable HTTP Processing

Since most of the HTTP traffic is HTTPS nowadays, you need to generate a CA and install&trust it in order to let the App to decrypt it.

Generate CA, install & trust

Generate CA

You can just click the Regenerate CA Certificate to create a new localy saved CA.

As you can see from the status below, the Current CA Certificate is generated, in the following step it will refresh automatically to help you to know the CA state.

Download CA

You can just click the Install CA Certificate to download the CA profile from the embedded HTTP Server using web browser.

NOTE:

If the browser does not give the above prompt, please go back to the App and click the Install CA Certificate Again.

Install CA

After the CA profile is downloaded, you can just goto the settings and see the downloaded profile, click Profile Downloaded and install it.

After you install the profile, you can switch back to the App and see it’s now shown in Installed state.

Trust CA

After the CA profile is installed, you can just goto the system General/About/Certificate Trust Settings to trust it.

Enable Trust as following:

After the CA is trusted, you can switch back to the App and see it’s now shown in Trusted state.

Add Interested Domains

Now you can just add some domain suffixes that you want to capture it’s traffic, now matter it’s HTTP or HTTPS.

Only domains listed here will be processed.

NOTE:

Some App use certificate pinning technology, thus it will not trust the CA even we do that in the system, currently there is no way to capture the HTTPS traffic from such App.

Enable VPN

Now you can just enable VPN to route all traffic from your system to the App.

Do Live HTTP Capture

When MintFlow NetStack VPN is running, you can just start capture the HTTP/HTTPS traffic belong to the domains you just added.

Here is what you may captured, and you can go each req/resp and view it’s detail information:

Future Tasks

Here is some future tasks you may needed to better use the App:

• Use DNS activity/DNS logs to check Domains related a specific App

  you can do this by start/stop a specific App multiple times to check domains related to it, then you can add the domain suffixes to the Http Process Domain list to capture it’s traffic.

App Release Notes

20251203, v1.6.0(iOS)

• Config system now refactored to plain-text based profile (Existing old database-based config will be migrated when upgrade to this version)
• Support iOS26 to support initial liquid glass effect

20250922, v1.5.0(iOS)

• Support start and stop HTTP/HTTPS capture anytime when MintFlow NetStack VPN is running, this will let user to only capture interested HTTP/HTTPS traffic when doing App debugging
• Rewrite captured HTTP/HTTPS request/response preview function, user now can view captured and decompressed HTTP/HTTPS body with smart syntax highlight, and export/share the body when needed
• Add a generic UDP forward bridge infra for vpp and L4Proxy component, as a result, UDP forward support to Shadowsocks Protocol
• Rewrite the editor of DomainSet/CidrSet, and enable search for the editor
• Optimize internal stub DNS cache logic to prevent some issues when cache expired
• By default use concurrent DNS query to reduce latency
• Adjust App price from 2.99$ to 5.99$ for increased feature and sustainable long term app developping and maintainence

20250730, v1.3.0(iOS)

• add HTTP engine for capture and rewrite HTTP/HTTPS traffic
• add a standalone DNS activity log page for inspect App DNS requests
• rewrite UI navigation for better UX

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.

• V2Fly domain-list-community
• NETIFY application database ¹

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. ↩