General: Forums subtopic: App & System Services > Networking DevForums tag: Network Extension Network Extension framework documentation Routing your VPN network traffic article Filtering traffic by URL sample code Filtering Network Traffic sample code TN3120 Expected use cases for Network Extension packet tunnel providers technote TN3134 Network Extension provider deployment technote TN3165 Packet Filter is not API technote Network Extension and VPN Glossary forums post Debugging a Network Extension Provider forums post Exporting a Developer ID Network Extension forums post Network Extension vs ad hoc techniques on macOS forums post Network Extension Provider Packaging forums post NWEndpoint History and Advice forums post Extra-ordinary Networking forums post Wi-Fi management: Wi-Fi Fundamentals forums post TN3111 iOS Wi-Fi API overview technote How to modernize your captive network developer news post iOS Network Signal Strength forums post See also Networking Resources. Share and Enjoy — Quinn “The Eskimo!” @ Developer Technical Support @ Apple let myEmail = "eskimo" + "1" + "@" + "apple.com"

Hello, I am writing a NetworkExtension VPN using custom protocol and our client would like to able to use 5G network slice on the VPN, is this possible at all? From Apple's documentation, I found the following statement: If both network slicing and VPN are configured for an app or device, the VPN connection takes precedence over the network slice, rendering the network slice unused. Is it possible to assign a network slice on a NetworkExtension-based VPN and let the VPN traffic uses the assign network slice? Many thanks

Hello, We are developing a content filter solution which includes both a content filter and a packet filter (NEFilterControlProvider and NEFilterPacketProvider). We've observed that if the packet filter is enabled (both by itself or in conjunction with the content filter) we are having issues with bridged thunderbolt connections - traffic on that interface stops in both directions. We've tested on bridges to other MacOS devices or Windows devices, but both exhibit the same behavior. Even if the packet provider is reduces to "allow all" in the callback the issue remains. Our handler is not called at all anyway so we can't allow or deny packets. We've tested this on Macos 15 and 26 but it behaves the same. If we only enable the NEFilterControlProvider everything works fine. All other types of network interfaces work fine as well. Is this a known issue? Is there an workaround? Thanks.

I’m using an NETransparentProxyProvider where I add UDP-53 rules to intercept DNS queries from a private application. These queries are resolved locally on the endpoint by returning a custom DNS response. Example Rules look like this: NENetworkRule(destinationHost: NWHostEndpoint(hostname: "mypaapp.com", port: 53),protocol:.UDP) This works as expected through browser and ping. handleNewUDPFlow/handleNewFlow with NEAppProxyUDPFlow gets called where custom dns response get written. Using nslookup mypaapp.com doesn't works. Why does this behaves differently for nslookup?

Hi everyone, I’m exploring Network Extension options for a use case where I need to log and filter network activity at the packet level. More specifically, I need the ability to detect and potentially block certain TCP behaviors during the handshake. From everything I’ve tested, NEFilterPacketProvider seems to be the only Network Extension type that operates early enough in the flow. NEFilterDataProvider appears to receive flows after the TCP handshake is already completed. It also has some limitations with IP-based filtering (might include hostname instead of IP), inconsistent ICMP behavior, etc. So I went with NEFilterPacketProvider. However, I’m running into a major issue: extremely high CPU usage. To isolate the problem, I stripped my packet handler down to the simplest possible implementation — basically returning .allow for every inbound/outbound packet without any filtering logic. Even with that minimal setup, playing one or two videos in a browser causes the CPU usage of the extension to spike to 20–50%. This seems to be caused purely by the packet volume. I haven’t found any way to pre-filter packets before the handler is invoked, nor any documented method to significantly optimize packet handling at this stage. It’s possible I’m missing something fundamental. Questions: Has anyone else experienced this kind of high CPU usage with NEFilterPacketProvider? Is there any recommended way to reduce the packet handling overhead or avoid processing every single packet? Any known best practices or configuration tips? Thanks in advance!

Description: We are investigating an issue where running a specific e-commerce iOS app inside the Xcode Simulator intermittently disrupts the Mac’s network connectivity. When the app is launched in the Simulator, our NETransparentProxyProvider and NEFilterDataProvider extensions occasionally stop receiving traffic correctly, and shortly afterward the entire macOS DNS resolution fails. Once this happens, all apps on the Mac lose internet access until mac is restarted. Disabling extensions also fixing the issue. This issue only appears when the app runs in the Xcode Simulator. I would like to confirm: Is it possible for traffic patterns or network behavior inside the Simulator to interfere with system-level Network Extension providers on macOS? Are there known limitations or conflicts between the Simulator’s virtual networking interfaces and Network Extensions? Any recommended debugging steps or best practices to isolate this behavior? Any guidance, known issues, or suggestions would be appreciated.

Hi all, I have a working macOS (Intel) system extension app that currently uses only a Content Filter (NEFilterDataProvider). I need to capture/log HTTP and HTTPS traffic in plain text, and I understand NETransparentProxyProvider is the right extension type for that. For HTTPS I will need TLS inspection / a MITM proxy — I’m new to that and unsure how complex it will be. For DNS data (in plain text), can I use the same extension, or do I need a separate extension type such as NEPacketTunnelProvider, NEFilterPacketProvider, or NEDNSProxyProvider? Current architecture: Two Xcode targets: MainApp and a SystemExtension target. The SystemExtension target contains multiple network extension types. MainApp ↔ SystemExtension communicate via a bidirectional NSXPC connection. I can already enable two extensions (Content Filter and TransparentProxy). With the NETransparentProxy, I still need to implement HTTPS capture. Questions I’d appreciate help with: Can NETransparentProxy capture the DNS fields I need (dns_hostname, dns_query_type, dns_response_code, dns_answer_number, etc.), or do I need an additional extension type to capture DNS in plain text? If a separate extension is required, is it possible or problematic to include that extension type (Packet Tunnel / DNS Proxy / etc.) in the same SystemExtension Xcode target as the TransparentProxy? Any recommended resources or guidance on TLS inspection / MITM proxy setup for capturing HTTPS logs? There are multiple DNS transport types — am I correct that capturing DNS over UDP (port 53) is not necessarily sufficient? Which DNS types should I plan to handle? I’ve read that TransparentProxy and other extension types (e.g., Packet Tunnel) cannot coexist in the same Xcode target. Is that true? Best approach for delivering logs from multiple extensions to the main app (is it feasible)? Or what’s the best way to capture logs so an external/independent process (or C/C++ daemon) can consume them? Required data to capture (not limited to): All HTTP/HTTPS (request, body, URL, response, etc.) DNS fields: dns_hostname, dns_query_type, dns_response_code, dns_answer_number, and other DNS data — all in plain text. I’ve read various resources but remain unclear which extension(s) to use and whether multiple extension types can be combined in one Xcode target. Please ask if you need more details. Thank you.

Hello, I am building a Content Filter app for iOS and would like to get access to some information about network connections that are happening on the device. I managed to have the handle(_ report: NEFilterReport) method of my NEFilterControlProvider called, but the bytesOutboundCount and bytesInboundCount properties of the report are always 0. How can I have the real byte count of the connection ?

I've noticed that if a call to startVPNTunnel() is made while no network interface is active on the system, the call "succeeds" (i.e., doesn't throw), but the VPN connection state goes straight from NEVPNStatus.disconnecting to NEVPNStatus.disconnected. The docs for startVPNTunnel() state: In Swift, this method returns Void and is marked with the throws keyword to indicate that it throws an error in cases of failure. Additionally, there is an NEVPNConnectionError enum that contains a noNetworkAvailable case. However, this isn't thrown in this case, when startVPNTunnel() is called. I just wanted to ask under what circumstances startVPNTunnel() does throw, and should this be one of them? Additionally, to catch such errors, would it be better to call fetchLastDisconnectError() in the .NEVPNStatusDidChange handler?

Hello, I have been playing around the the SimpleURLFilter sample code. I keep getting this error upon installed the filter profile on the device: mapError unexpected error domain NEVPNConnectionErrorDomainPlugin code 7 which then causes this error: Received filter status change: <FilterStatus: 'stopped' errorMessage: 'The operation couldn’t be completed. (NetworkExtension.NEURLFilterManager.Error error 14.)'> I can't find much info about code 7. Here is the configuration I am trying to run: <Configuration: pirServerURL: 'http://MyComputer.local:8080' pirAuthenticationToken: 'AAAA' pirPrivacyPassIssuerURL: 'http://MyComputer.local:8080' enabled: 'true' shouldFailClosed: 'true' controlProviderBundleIdentifier: 'krpaul.SimpleURLFilter.SimpleURLFilterExtension' prefilterFetchInterval: '2700.0'>

I'm working with Apple's SimpleURLFilter sample project and consistently encountering an error when trying to implement the URL filter. Here are the details: Setup: Downloaded the official SimpleURLFilter sample project from Apple Set the developer team for both targets (main app and extension) Built and ran the PIR server on my laptop using Docker as per the sample instructions Built the iOS project on my iPhone running iOS 26.0.1 Server is accessible at my Mac's IP address on port 8080 Configuration: PIR Server URL: http://[my-mac-ip]:8080 Authentication Token: AAAA (as specified in service-config.json) Privacy Pass Issuer URL: (left empty) Fail Closed: enabled Code Changes: The only modifications I made were: Updated bundle identifiers to include my team identifier Updated PIR server's service-config.json to match: com.example.apple-samplecode.SimpleURLFilter[TEAM_ID].url.filtering Modified URLFilterControlProvider.swift: Added existingPrefilterTag: String? parameter to fetchPrefilter() method Added tag: "bloom_filter" parameter to NEURLFilterPrefilter initializer Issue: After configuring the filter and entering my passcode in Settings, I consistently see: Received filter status change: <FilterStatus: 'starting'> Received filter status change: <FilterStatus: 'stopped' errorMessage: 'The operation couldn't be completed. (NetworkExtension.NEURLFilterManager.Error error 9.)'> Questions: What does NEURLFilterManager.Error error 9 specifically indicate? Could the URLFilterControlProvider modifications be causing this issue? Are there debugging steps to get more detailed error information? Any guidance would be appreciated!

Our application uses NEFilterPacketProvider to filter network traffic and we sometimes get a wired crash when removing/updating the network extension. It only happens on MacOS 11-12 . The crashing thread is always this one and it shows up after I call the completionHandler from the stopFilter func Application Specific Information: BUG IN CLIENT OF LIBDISPATCH: Release of a suspended object Thread 6 Crashed:: Dispatch queue: com.apple.network.connections 0 libdispatch.dylib 0x00007fff2039cc35 _dispatch_queue_xref_dispose.cold.1 + 24 1 libdispatch.dylib 0x00007fff20373808 _dispatch_queue_xref_dispose + 50 2 libdispatch.dylib 0x00007fff2036e2eb -[OS_dispatch_source _xref_dispose] + 17 3 libnetwork.dylib 0x00007fff242b5999 __nw_queue_context_create_source_block_invoke + 41 4 libdispatch.dylib 0x00007fff2036d623 _dispatch_call_block_and_release + 12 5 libdispatch.dylib 0x00007fff2036e806 _dispatch_client_callout + 8 6 libdispatch.dylib 0x00007fff203711b0 _dispatch_continuation_pop + 423 7 libdispatch.dylib 0x00007fff203811f4 _dispatch_source_invoke + 1181 8 libdispatch.dylib 0x00007fff20376318 _dispatch_workloop_invoke + 1784 9 libdispatch.dylib 0x00007fff2037ec0d _dispatch_workloop_worker_thread + 811 10 libsystem_pthread.dylib 0x00007fff2051545d _pthread_wqthread + 314 11 libsystem_pthread.dylib 0x00007fff2051442f start_wqthread + 15 I do have a DispatchSourceTimer but I cancel it in the stop func. Any ideas on how to tackle this?

Description : Our app helps users connect to Wi-Fi hotspots. We are trying to adapt our code to iOS 26 Hotspot Authentication and Hotspot Evaluation application extensions. When filtering hotspots in the filterScanList callback, we need to fetch support information from a remote server to determine which hotspots are supported. However, attempts to use URLSession or NWTCPConnection in the extension always fail. When accessing a URL (e.g., https://www.example.com), the network log shows: Error Domain=NSURLErrorDomain Code=-1003 "A server with the specified hostname could not be found." When accessing a raw IP address, the log shows: [1: Operation not permitted] Interestingly, NWPathMonitor shows the network path as satisfied, indicating that the network is reachable. Question: Are there any missing permissions or misconfigurations on our side, or are we using the wrong approach? Is there an official recommended way to perform network requests from an NEHotspotEvaluationProvider extension?

I develop a Network Extension with NEFilterDataProvider and want to understand how to stop or disable it on exit of the base app without deactivating NE from OS and leave ability to start it again without requiring a password from the user. It starts normally, but when I try to disable it: NEFilterManager.sharedManager.enabled = NO; [NEFilterManager.sharedManager saveToPreferencesWithCompletionHandler:^(NSError * _Nullable error) { // never called }]; the completion handler has never called. But stopFilterWithReason inside the NE code called by the framework where I only replay with required completionHandler();. Then NE process keeps alive. I also tried to call remove, which should disable NE: [NEFilterManager.sharedManager removeFromPreferencesWithCompletionHandler:^(NSError * _Nullable error) { // never called }]; with same result - I freeze forever on waiting completion handler. So what is the correct way to disable NE without explicit deactivation it by [OSSystemExtensionRequest deactivationRequestForExtension:...]?

Following previous question here :https://developer.apple.com/forums/thread/801397, I've decided to move my VPN implementation using NEPacketTunnelProvider on a dedicated networkExtension. My extension receives packets using readPacketsWithCompletionHandler and forwards them immediately to a daemon through a shared memory ring buffer with Mach port signaling. The daemon then encapsulates the packets with our VPN protocol and sends them over a UDP socket. I'm seeing significant throughput degradation, much higher than the tunnel overhead itself. On our side, the IPC path supports parallel handling, but I'm not not sure whether the provider has any internal limitation that prevents packets from being processed in parallel. The tunnel protocol requires packet ordering, but preparation can be done in parallel if the provider allows it. Is there any inherent constraint in NEPacketTunnelProvider that prevents concurrent packet handling, or any recommended approach to improve throughput in this model? For comparison, when I create a utun interface manually with ifconfig and route traffic through it, I observe performance that is about four times faster.

we use the api as NEHotspotConfigurationManager.shared.apply(hotspotConfig) to join a wifi, but we find that in in iphone 17+, some user report the time to join wifi is very slow the full code as let hotspotConfig = NEHotspotConfiguration(ssid: sSSID, passphrase: sPassword, isWEP: false) hotspotConfig.joinOnce = bJoinOnce if #available(iOS 13.0, *) { hotspotConfig.hidden = true } NEHotspotConfigurationManager.shared.apply(hotspotConfig) { [weak self] (error) in guard let self else { return } if let error = error { log.i("connectSSID Error while configuring WiFi: \(error.localizedDescription)") if error.localizedDescription.contains("already associated") { log.i("connectSSID Already connected to this WiFi.") result(["status": 0]) } else { result(["status": 0]) } } else { log.i("connectSSID Successfully connected to WiFi network \(sSSID)") result(["status": 1]) } } Normally it might only take 5-10 seconds, but on the iPhone 17+ it might take 20-30 seconds.

Hello, I’m developing a macOS application signed with a Developer ID (outside the App Store) that includes a Network Extension. The app has been successfully notarized, and the network filter is registered, but the Network Extension itself remains inactive — it does not install or run properly. It seems that the issue might be related to the entitlements configuration between the container app and the Network Extension target. Could you please provide a detailed checklist for: The required entitlements and configurations for the container app, and The required entitlements and configurations for the Network Extension target? Additionally, are there any specific Xcode settings that are mandatory for the Network Extension to be properly installed and activated on macOS when distributed via Developer ID? Thank you in advance for your help.

Hello, I’m developing a macOS application signed with a Developer ID (outside the App Store) that includes a Network Extension. The app has been successfully notarized, and the network filter is registered, but the Network Extension itself remains inactive — it does not install or run properly. It seems that the issue might be related to the entitlements configuration between the container app and the Network Extension target. Could you please provide a detailed checklist for: 1.The required entitlements and configurations for the container app, and 2.The required entitlements and configurations for the Network Extension target? Additionally, are there any specific Xcode settings that are mandatory for the Network Extension to be properly installed and activated on macOS when distributed via Developer ID? Thank you in advance for your help.

I'm currently testing URLFilter for use in a macOS product. After calling loadFromPreferences, I set the following configuration parameters: pirServerURL = URL(string: "http://localhost:8080")! pirAuthenticationToken = "AAAA" controlProviderBundleIdentifier = "{extension app bundle identifier}" However, when I call saveToPreferences, I get an Invalid Configuration error. Is there a way to determine which parameter is invalid or incorrectly set? Also, I would appreciate any macOS-specific examples of using NEURLFilterManager, as most of the documentation I’ve found seems to focus on iOS. Thank you.

Title： iPhone 17 Wi-Fi connection via NEBOTspotConfigurationManager::applyConfiguration is significantly slower compared to other models Description： When using the NEBOTspotConfigurationManager::applyConfiguration API to connect to a Wi-Fi network, the connection process on iPhone 17 is extremely slow compared to other iPhone models. For example, in one test case: The API call to connect to Wi-Fi (LRA-AN00%6149%HonorConnect) was initiated at 16:16:29. However, the Association Request was not actually initiated until 16:16:58. During this ~29-second delay, the device appears to be scanning before starting the association process. This issue is specific to iPhone 17 — the same code and network environment do not exhibit this delay on other iPhone models. Steps to Reproduce: On an iPhone 17, call NEBOTspotConfigurationManager::applyConfiguration to connect to a known Wi-Fi network. Observe the timestamps between API invocation and the start of the Association Request. Compare with the same process on other iPhone models. Expected Result: The Association Request should start almost immediately after the API call, similar to other iPhone models. Actual Result: On iPhone 17, there is a ~29-second delay between API call and Association Request initiation, during which the device appears to be scanning. Impact: This delay affects user experience and connection performance when using programmatic Wi-Fi configuration on iPhone 17. Environment: Device: iPhone 17 iOS Version:26.0.1 API: NEBOTspotConfigurationManager::applyConfiguration Network: WPA2-Personal IOS.txt

I’m building a Personal VPN app (non-MDM) that uses a NEPacketTunnelProvider extension for content filtering and blocking. When configuring the VPN locally using NETunnelProviderManager.saveToPreferences, the call fails with: Error Domain=NEConfigurationErrorDomain Code=10 "permission denied" Error Domain=NEVPNErrorDomain Code=5 "permission denied" The system does prompt for VPN permission (“Would Like to Add VPN Configurations”), but the error still occurs after the user allows it. Setup: • Main App ID – com.promisecouple.app • Extension ID – com.promisecouple.app.PromiseVPN • Capabilities – App Group + Personal VPN + Network Extensions • Main app entitlements:   com.apple.developer.networking.vpn.api = allow-vpn   com.apple.developer.networking.networkextension = packet-tunnel-provider • Extension entitlements: same + shared App Group Problem: • If I remove the networkextension entitlement, the app runs locally without the Code 5 error. • But App Store Connect then rejects the build with: Missing Entitlement: The bundle 'Promise.app' is missing entitlement 'com.apple.developer.networking.networkextension'. Question: What is the correct entitlement configuration for a Personal VPN app using NEPacketTunnelProvider (non-MDM)? Is com.apple.developer.networking.networkextension required on the main app or only on the extension? Why does including it cause saveToPreferences → Code 5/10 “permission denied” on device? Environment: Xcode 26.1 (17B55), iOS 17.3+ on physical device (non-MDM) Both provisioning profiles and certificates are valid.