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"

This is just an FYI in case someone else runs into this problem. This afternoon (12 Dec 2025), I updated to macOS 26.2 and lost my network. The System Settings' Wi-Fi light was green and said it was connected, but traceroute showed "No route to host". I turned Wi-Fi on & off. I rebooted the Mac. I rebooted the eero network. I switched to tethering to my iPhone. I switched to physical ethernet cable. Nothing worked. Then I remembered I had a beta of an app with a network system extension that was distributed through TestFlight. I deleted the app, and networking came right back. I had this same problem ~2 years ago. Same story: app with network system extension + TestFlight + macOS update = lost network. (My TestFlight build might have expired, but I'm not certain) I don't know if anyone else has had this problem, but I thought I'd share this in case it helps.

From time to time the subject of NECP grows up, both here on DevForums and in DTS cases. I’ve posted about this before but I wanted to collect those tidbits into single coherent post. If you have questions or comments, start a new thread in the App & System Services > Networking subtopic and tag it with Network Extension. That way I’ll be sure to see it go by. Share and Enjoy — Quinn “The Eskimo!” @ Developer Technical Support @ Apple let myEmail = "eskimo" + "1" + "@" + "apple.com" A Peek Behind the NECP Curtain NECP stands for Network Extension Control Protocol. It’s a subsystem within the Apple networking stack that controls which programs have access to which network interfaces. It’s vitally important to the Network Extension subsystem, hence the name, but it’s used in many different places. Indeed, a very familiar example of its use is the Settings > Mobile Data [1] user interface on iOS. NECP has no explicit API, although there are APIs that are offer some insight into its state. Continuing the Settings > Mobile Data example above, there is a little-known API, CTCellularData in the Core Telephony framework, that returns whether your app has access to WWAN. Despite having no API, NECP is still relevant to developers. The Settings > Mobile Data example is one place where it affects app developers but it’s most important for Network Extension (NE) developers. A key use case for NECP is to prevent VPN loops. When starting an NE provider, the system configures the NECP policy for the NE provider’s process to prevent it from using a VPN interface. This means that you can safely open a network connection inside your VPN provider without having to worry about its traffic being accidentally routed back to you. This is why, for example, an NE packet tunnel provider can use any networking API it wants, including BSD Sockets, to run its connection without fear of creating a VPN loop [1]. One place that NECP shows up regularly is the system log. Next time you see a system log entry like this: type: debug time: 15:02:54.817903+0000 process: Mail subsystem: com.apple.network category: connection message: nw_protocol_socket_set_necp_attributes [C723.1.1:1] setsockopt 39 SO_NECP_ATTRIBUTES … you’ll at least know what the necp means (-: Finally, a lot of NECP infrastructure is in the Darwin open source. As with all things in Darwin, it’s fine to poke around and see how your favourite feature works, but do not incorporate any information you find into your product. Stuff you uncover by looking in Darwin is not considered API. [1] Settings > Cellular Data if you speak American (-: [2] Network Extension providers can call the createTCPConnection(to:enableTLS:tlsParameters:delegate:) method to create an NWTCPConnection [3] that doesn’t run through the tunnel. You can use that if it’s convenient but you don’t need to use it. [3] NWTCPConnection is now deprecated, but there are non-deprecated equivalents. For the full story, see NWEndpoint History and Advice. Revision History 2025-12-12 Replaced “macOS networking stack” with “Apple networking stack” to avoid giving the impression that this is all about macOS. Added a link to NWEndpoint History and Advice. Made other minor editorial changes. 2023-02-27 First posted.

Hello, I have a .app that runs as LaunchDaemon and configured to be an Agent (LSUIElement) that is stored in /Applications. Installing network extensions works, but deactivation fails with OSSystemExtensionErrorDomain error 13 (authorization required). requestNeedsUserApproval is not called for deactivation, but it's called when being activated. Any ideas? Thank you! P.S. It works on Debug, just not on Release...

We are facing a DNS resolution issue with a specific ISP, where our domain name does not resolve correctly using the system DNS. However, the same domain works as expected when a custom DNS resolver is used. On Android, this is straightforward to handle by configuring a custom DNS implementation using OkHttp / Retrofit. I am trying to implement a functionally equivalent solution in native iOS (Swift / SwiftUI). **Android Reference (Working Behavior) : ** val dns = DnsOverHttps.Builder() .client(OkHttpClient()) .url("https://cloudflare-dns.com/dns-query".toHttpUrl()) .bootstrapDnsHosts(InetAddress.getByName("1.1.1.1")).build() OkHttpClient.Builder().dns(dns).build() **Attempted iOS Approach ** I attempted the following approach : Resolve the domain to an IP address programmatically (using DNS over HTTPS) Connect directly to the resolved IP address Set the original domain in the Host HTTP header **DNS Resolution via DoH : ** func resolveDomain(domain: String) async throws -> String { guard let url = URL( string: "https://cloudflare-dns.com/dns-query?name=\(domain)&type=A" ) else { throw URLError(.badURL) } var request = URLRequest(url: url) request.setValue("application/dns-json", forHTTPHeaderField: "accept") let (data, _) = try await URLSession.shared.data(for: request) let response = try JSONDecoder().decode(DNSResponse.self, from: data) guard let ip = response.Answer?.first?.data else { throw URLError(.cannotFindHost) } return ip } **API Call Using Resolved IP : ** func callAPIUsingCustomDNS() async throws { let ip = try await resolveDomain(domain: "example.com") guard let url = URL(string: "https://\(ip)") else { throw URLError(.badURL) } let configuration = URLSessionConfiguration.ephemeral let session = URLSession( configuration: configuration, delegate: CustomURLSessionDelegate(originalHost: "example.com"), delegateQueue: .main ) var request = URLRequest(url: url) request.setValue("example.com", forHTTPHeaderField: "Host") let (_, response) = try await session.data(for: request) print("Success: \(response)") } **Problem Encountered ** When connecting via the IP address, the TLS handshake fails with the following error: Error Domain=NSURLErrorDomain Code=-1200 "A TLS error caused the secure connection to fail." This appears to happen because iOS sends the IP address as the Server Name Indication (SNI) during the TLS handshake, while the server’s certificate is issued for the domain name. **Custom URLSessionDelegate Attempt : ** class CustomURLSessionDelegate: NSObject, URLSessionDelegate { let originalHost: String init(originalHost: String) { self.originalHost = originalHost } func urlSession( _ session: URLSession, didReceive challenge: URLAuthenticationChallenge, completionHandler: @escaping (URLSession.AuthChallengeDisposition, URLCredential?) -> Void ) { guard challenge.protectionSpace.authenticationMethod == NSURLAuthenticationMethodServerTrust, let serverTrust = challenge.protectionSpace.serverTrust else { completionHandler(.performDefaultHandling, nil) return } let sslPolicy = SecPolicyCreateSSL(true, originalHost as CFString) let basicPolicy = SecPolicyCreateBasicX509() SecTrustSetPolicies(serverTrust, [sslPolicy, basicPolicy] as CFArray) var error: CFError? if SecTrustEvaluateWithError(serverTrust, &error) { completionHandler(.useCredential, URLCredential(trust: serverTrust)) } else { completionHandler(.cancelAuthenticationChallenge, nil) } } } However, TLS validation still fails because the SNI remains the IP address, not the domain. I would appreciate guidance on the supported and App Store–compliant way to handle ISP-specific DNS resolution issues on iOS. If custom DNS or SNI configuration is not supported, what alternative architectural approaches are recommended by Apple?

On my iPhone 16 Pro and iPhone 16 Pro Max devices, running iOS 26.0, 26.0.1, and 26.1, Wi-Fi raw socket communication works flawlessly. Even after keeping the connection active for over 40 minutes, there are no disconnections during data transmission. However, on the iPhone 17 and iPhone 17 Pro, the raw socket connection drops within 20 seconds. Once it disconnects, the socket cannot reconnect unless the Wi-Fi module itself is reset. I believe this issue is caused by a bug in the iPhone 17 series’ communication module. I have looked into many cases, and it appears to be related to a bug in the N1 chipset. Are there any possible solutions or workarounds for this issue?

Hi Team, I have a Network Extension application and UI frontend for it. The UI frontend talks to the Network Extension using XPC, as provided by NEMachServiceName. On M2 machine, The application and XPC connection works fine on clean installation. But, when the application is upgraded, the XPC connection keeps failing. Upgrade steps: PreInstall script kills the running processes, both UI and Network Extension Let installation continue PostInstall script to launch the application after installation complete. Following code is successful to the point of resume from UI application NSXPCInterface *exportedInterface = [NSXPCInterface interfaceWithProtocol:@protocol(IPCUIObject)]; newConnection.exportedInterface = exportedInterface; newConnection.exportedObject = delegate; NSXPCInterface *remoteObjectInterface = [NSXPCInterface interfaceWithProtocol:@protocol(IPCExtObject)]; newConnection.remoteObjectInterface = remoteObjectInterface; self.currentConnection = newConnection; [newConnection resume]; But it fails to get the object id<IPCExtObject> providerProxy = [self.currentConnection remoteObjectProxyWithErrorHandler:^(NSError *registerError) { }]; Please note, this only fails for M2. For M1, this exact code is running fine. Additionally, if I uninstall the application by dropping it in Trash and then installing the newer version, then too, the application works fine.

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 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:...]?