When using the NEHotspotConfigurationManager applyConfiguration interface for network connection, there is a certain probability of encountering the "Unable to join network" error. We captured the system logs when the issue occurred, some errors are due to the network not being scanned, while others are rejected by the system（console logs like:WCLScanManager scan is blocked by other system activity 32 or 9）. If there are any methods to optimize or avoid these errors?

I'm creating a custom VPN app which should only work on Cellular. Apart from cellular interface binding VPN is working fine. Even though I specified cellular interface like let cellularParams = NWParameters.udp cellularParams.requiredInterfaceType = .cellular It is going via Wifi when it is ON. I know this is the default iOS behaviour. How can I prevent this and route through cellular only even when Wifi is enabled on device?

Question: Best Practice for NEFilterRule and NENetworkRule Initializers with Deprecated NEHostEndpoint? Hi all, I'm looking for guidance on the right way to construct an NEFilterRule that takes a NENetworkRule parameter. Reading the latest documentation, it looks like: All initializers for NENetworkRule that accept an NEHostEndpoint are now deprecated, including initWithDestinationHost:protocol: and those using the various *Network:prefix: forms. NEHostEndpoint itself is also deprecated; Apple recommends using the nw_endpoint_t type from the Network framework instead. However, NEFilterRule still requires a NENetworkRule for its initializer (docs). With all NENetworkRule initializers that take NEHostEndpoint deprecated, it’s unclear what the recommended way is to create a NENetworkRule (and thus an NEFilterRule) that matches host/domain or network traffic. What’s the proper way to construct these objects now—should we create the endpoints using nw_endpoint_t and use new/undocumented initializers, or is there an updated approach that’s considered best practice? Helpful doc links for reference: NEFilterRule docs NENetworkRule docs NWHostEndpoint (now deprecated)

The path from Network Extension’s in-provider networking APIs to Network framework has been long and somewhat rocky. The most common cause of confusion is NWEndpoint, where the same name can refer to two completely different types. I’ve helped a bunch of folks with this over the years, and I’ve decided to create this post to collect together all of those titbits. If you have questions or comments, please put them in a new thread. Put it 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" NWEndpoint History and Advice A tale that spans three APIs, two languages, and ten years. The NWEndpoint type has a long and complex history, and if you’re not aware of that history you can bump into weird problems. The goal of this post is to explain the history and then offer advice on how to get around specific problems. IMPORTANT This post focuses on NWEndpoint, because that’s the type that causes the most problems, but there’s a similar situation with NWPath. The History In iOS 9 Apple introduced the Network Extension (NE) framework, which offers a convenient way for developers to create a custom VPN transport. Network Extension types all have the NE prefix. Note I’m gonna use iOS versions here, just to keep the text simple. If you’re targeting some other platform, use this handy conversion table: iOS | macOS | tvOS | watchOS | visionOS --- + ----- + ---- + ------- + -------- 9 | 10.11 | 9 | 2 | - 12 | 10.14 | 12 | 5 | - 18 | 15 | 18 | 11 | 2 At that time we also introduced in-provider networking APIs. The idea was that an NE provider could uses these Objective-C APIs to communicate with its VPN server, and thereby avoiding a bunch of ugly BSD Sockets code. The in-provider networking APIs were limited to NE providers. Specifically, the APIs to construct an in-provider connection were placed on types that were only usable within an NE provider. For example, a packet tunnel provider could create a NWTCPConnection object by calling -createTCPConnectionToEndpoint:enableTLS:TLSParameters:delegate:] and -createTCPConnectionThroughTunnelToEndpoint:enableTLS:TLSParameters:delegate:, which are both methods on NEPacketTunnelProvider. These in-provider networking APIs came with a number of ancillary types, including NWEndpoint and NWPath. At the time we thought that we might promote these in-provider networking APIs to general-purpose networking APIs. That’s why the APIs use the NW prefix. For example, it’s NWTCPConnection, not NETCPConnection. However, plans changed. In iOS 12 Apple shipped Network framework as our recommended general-purpose networking API. This actually includes two APIs: A Swift API that follows Swift conventions, for example, the connection type is called NWConnection A C API that follows C conventions, for example, the connection type is called nw_connection_t These APIs follow similar design patterns to the in-provider networking API, and thus have similar ancillary types. Specifically, there are an NWEndpoint and nw_endpoint_t types, both of which perform a similar role to the NWEndpoint type in the in-provider networking API. This was a source of some confusion in Swift, because the name NWEndpoint could refer to either the Network framework type or the Network Extension framework type, depending on what you’d included. Fortunately you could get around this by qualifying the type as either Network.NWEndpoint or NetworkExtension.NWEndpoint. The arrival of Network framework meant that it no longer made sense to promote the in-provider networking APIs to general-purposes networking APIs. The in-provider networking APIs were on the path to deprecation. However, deprecating these APIs was actually quite tricky. Network Extension framework uses these APIs in a number of interesting ways, and so deprecating them required adding replacements. In addition, we’d needed different replacements for Swift and Objective-C, because Network framework has separate APIs for Swift and C-based languages. In iOS 18 we tackled that problem head on. To continue the NWTCPConnection example above, we replaced: -createTCPConnectionToEndpoint:enableTLS:TLSParameters:delegate:] with nw_connection_t -createTCPConnectionThroughTunnelToEndpoint:enableTLS:TLSParameters:delegate: with nw_connection_t combined with a new virtualInterface property on NEPacketTunnelProvider Of course that’s the Objective-C side of things. In Swift, the replacement is NWConnection rather than nw_connection_t, and the type of the virtualInterface property is NWInterface rather than nw_interface_t. But that’s not the full story. For the two types that use the same name in both frameworks, NWEndpoint and NWPath, we decided to use this opportunity to sort out that confusion. To see how we did that, check out the <NetworkExtension/NetworkExtension.apinotes> file in the SDK. Focusing on NWEndpoint for the moment, you’ll find two entries: … - Name: NWEndpoint SwiftPrivate: true … SwiftVersions: - Version: 5.0 … - Name: NWEndpoint SwiftPrivate: false … The first entry applies when you’re building with the Swift 6 language mode. This marks the type as SwiftPrivate, which means that Swift imports it as __NWEndpoint. That frees up the NWEndpoint name to refer exclusively to the Network framework type. The second entry applies when you’re building with the Swift 5 language mode. It marks the type as not SwiftPrivate. This is a compatible measure to ensure that code written for Swift 5 continues to build. The Advice This sections discusses specific cases in this transition. NWEndpoint and NWPath In Swift 5 language mode, NWEndpoint and NWPath might refer to either framework, depending on what you’ve imported. Add a qualifier if there’s any ambiguity, for example, Network.NWEndpoint or NetworkExtension.NWEndpoint. In Swift 6 language mode, NWEndpoint and NWPath always refer to the Network framework type. Add a __ prefix to get to the Network Extension type. For example, use NWEndpoint for the Network framework type and __NWEndpoint for the Network Extension type. Direct and Through-Tunnel TCP Connections in Swift To create a connection directly, simply create an NWConnection. This support both TCP and UDP, with or without TLS. To create a connection through the tunnel, replace code like this: let c = self.createTCPConnectionThroughTunnel(…) with code like this: let params = NWParameters.tcp params.requiredInterface = self.virtualInterface let c = NWConnection(to: …, using: params) This is for TCP but the same basic process applies to UDP. UDP and App Proxies in Swift If you’re building an app proxy, transparent proxy, or DNS proxy in Swift and need to handle UDP flows using the new API, adopt the NEAppProxyUDPFlowHandling protocol. So, replace code like this: class AppProxyProvider: NEAppProxyProvider { … override func handleNewUDPFlow(_ flow: NEAppProxyUDPFlow, initialRemoteEndpoint remoteEndpoint: NWEndpoint) -> Bool { … } } with this: class AppProxyProvider: NEAppProxyProvider, NEAppProxyUDPFlowHandling { … func handleNewUDPFlow(_ flow: NEAppProxyUDPFlow, initialRemoteFlowEndpoint remoteEndpoint: NWEndpoint) -> Bool { … } } Creating a Network Rule To create an NWHostEndpoint, replace code like this: let ep = NWHostEndpoint(hostname: "1.2.3.4", port: "12345") let r = NENetworkRule(destinationHost: ep, protocol: .TCP) with this: let ep = NWEndpoint.hostPort(host: "1.2.3.4", port: 12345) let r = NENetworkRule(destinationHostEndpoint: ep, protocol: .TCP) Note how the first label of the initialiser has changed from destinationHost to destinationHostEndpoint.

I have a requirement to create a VPN app which only works on Cellular. But I'm facing an issue like when wifi is ON, OS is using wifi interface to route the traffic instead of cellular. I tried some ways like let cellularParams = NWParameters.udp cellularParams.requiredInterfaceType = .cellular But this is not working properly as expected. How can I manually bind to cellular interface in iOS?

I have few API's written with URLSession. Will they work in Carrier-constrained network / satellite mode ?

We have an application which is written in Swift, which activates Transparent Proxy network extension. We want to use MDM deployment for this network system extension. Our Transparent Proxy module is a system extension, which is exposing an app proxy provider interface (We are using NETransparentProxyProvider class and in extension’s Info.plist we use com.apple.networkextension.app-proxy key.) We don’t have any remote server setup to forward the traffic, instead we open a connection with a certain localhost:port (127.0.0.1:3128) to redirect the traffic which is received in our transparent proxy. We have another module that listens to the particular localhost:port to process the traffic further. As per https://developer.apple.com/documentation/devicemanagement/vpn/transparentproxy documentation, we noticed that we can use the VPN payload with app-proxy as Provider Type for Transparent Proxy. By referring this document, we created the profile. If we provide "127.0.0.1" as RemoteAddress field, we were able to install the profile and also while installing our product, the Transparent Proxy gets mapped with the one which is installed via profile. However after that the network is broken and hence unable to browse anything. We are suspecting the remote server(RemoteAddress) filed is causing this. What value should be provided in the RemoteAddress field?

We are a Layer 3 VPN provider offering a comprehensive SASE (Secure Access Service Edge) solution that includes TLS inspection, threat protection, granular access control, and secure access to private resources. One of the key challenges we face involves TLS inspection. Many mobile applications, especially on iOS, implement certificate pinning, which causes them to fail when TLS inspection is applied. These apps expect connections to be secured with a specific certificate or trusted certificate authority, and inspection disrupts this trust model. On iOS, the current limitation is that the Packet Tunnel Provider extension does not provide visibility into the originating application (i.e., there is no API to obtain the app’s bundle ID or package name associated with a given network connection). Due to this, we are unable to dynamically determine whether TLS inspection should be bypassed for a particular app. While Apple’s Per-App VPN is one possible solution, it introduces a significant drawback: any applications that are excluded from the VPN configuration are entirely outside the VPN tunnel. This means they do not benefit from any of our SASE features — including secure access to internal resources, DNS/web content filtering, or threat detection. This limits the effectiveness of our solution in environments where both inspection and secure access are critical. We would like to understand whether iOS has any current or planned capabilities to associate a network flow (e.g., a 5-tuple: source IP, destination IP, source port, destination port, and protocol) with the originating app. Such a capability would allow us to programmatically identify certificate-pinned apps and selectively disable TLS inspection without excluding them entirely from the VPN, thereby preserving the full set of SASE protections. Is there any guidance or roadmap update from Apple that addresses this use case?

Context I'm working on a DNS proxy network extension and would like to be able to parse replies from the upstream DNS server for extracting the TTL for caching purposes. I already have a working DNS proxy network extension, but at the moment I am not handling the responses and just forward all queries to an upstream DNS server. My understanding is that I have to take care of result caching myself because I cannot use the system resolver in the DNS proxy network extension. Question What is the best way to parse DNS replies in Swift to extract e.g. the TTL? I found an old thread (https://forums.swift.org/t/parse-dns-packet-requests-and-responses/41797/5) describing a way to achieve this using dns_util. The solution described there works - but dns_parse_packet in dns_util have been marked deprecated since iOS 16. So, I am wondering if there is a better way to achieve the parser. I tried to utilize the dnssd framework but was unable to figure out how to achieve only parsing of the raw DNS reply. If that is possible it would be great to get some pointers.

I am trying to intercept localhost connections within NETransparentProxyProvider system extension. As per NENetworkRule documentation If the address is a wildcard address (0.0.0.0 or ::) then the rule will match all destinations except for loopback (127.0.0.1 or ::1). To match loopback traffic set the address to the loopback address. I tried to add NWHostEndpoint *localhostv4 = [NWHostEndpoint endpointWithHostname:@"127.0.0.1" port:@""]; NENetworkRule *localhostv4Rule = [[NENetworkRule alloc] initWithDestinationNetwork:localhostv4 prefix:32 protocol:NENetworkRuleProtocolAny]; in the include network rules. I tried several variations of this rule like port 0, prefix 0 and some others. But the provider disregards the rule and the never receives any traffic going to localhost on any port. Is there any other configuration required to receive localhost traffic in NETransparentProxyProvider?

Our app uses NEVPNManager with IPsec to create VPN. It uses certificate authentication(.p12) and VPN connectivity is working as expected. Now I am trying to apply On demand rules to manage this VPN. let onDemandRule = NEOnDemandRuleConnect() onDemandRule.interfaceTypeMatch = .wiFi onDemandRule.ssidMatch = ["DNET"] NEOnDemandRuleConnect with interfaceTypeMatch and ssidMatch is starting VPN when the rule matches. When I add onDemandRule.dnsSearchDomainMatch = ["pa.test2.com"], it is not switching ON the VPN when I browse the "pa.test2.com" in the safari. I also tried *.test2.com and *.com. None of these domains switching ON the VPN. Can you please help me if I am missing anything?

I'm new to Control Filter Extensions and have a question about their network capabilities. I'm building an app that processes network data and need to send some results to a remote server. My main questions: Are Control Filter Extensions officially permitted to make outbound UDP connections? I want to confirm this is a supported capability before implementing the network export functionality. What specific entitlements are required for outbound network access? Currently using content-filter-provider - do I need additional network-related entitlements? Are there any restrictions or considerations for UDP data export in production vs development builds? I want to ensure I'm following Apple's guidelines and using the correct entitlements for this type of data export from a Control Filter Extension. Any guidance on the official network capabilities and required setup would be greatly appreciated!

I've discovered that a system network extension can communicate with a LaunchDaemon (loaded using SMAppService) over XPC, provided that the XPC service name begins with the team ID. If I move the launchd daemon plist to Contents/Library/LaunchAgents and swap the SMAppService.daemon calls to SMAppService.agent calls, and remove the .privileged option to NSXPCConnection, the system extension receives "Couldn't communicate with a helper application" as an error when trying to reach the LaunchAgent advertised service. Is this limitation by design? I imagine it is, but wanted to check before I spent any more time on it.

This has happened a few times, including out in the field; it's happened on macOS 14 and 15 I think. "This" is: our app runs, activates the extension, it has to get user approval, and... the system dialogue window never appears. The extension stays waiting for user approval. I've got sysdiagnose from one of the systems, and I see the system log about it going into the user approval needed state, and... nothing else. It's there in Settings, and can be approved then. Has anyone run into this? Ever?

Hi, I run a PacketTunnelProvider embedded within a system extension. We have been having success using this; however we have problems with accessing certificates/private keys manually imported in the file-based keychain. As per this, we are explicitly targeting the file-based keychain. However when attempting to access the certificate and private key we get the following error: System error using certificate key from keychain: Error Domain=NSOSStatusErrorDomain Code=-25308 "CSSM Exception: -2147415840 CSSMERR_CSP_NO_USER_INTERACTION" (errKCInteractionNotAllowed / errSecInteractionNotAllowed: / Interaction is not allowed As per the online documentation, I would expect to be prompted for the access to the application: When an app attempts to access a keychain item for a particular purpose—like using a private key to sign a document—the system looks for an entry in the item’s ACL containing the operation. If there’s no entry that lists the operation, then the system denies access and it’s up to the calling app to try something else or to notify the user. If there is an entry that lists the operation, the system checks whether the calling app is among the entry’s trusted apps. If so, the system grants access. Otherwise, the system prompts the user for confirmation. The user may choose to Deny, Allow, or Always Allow the access. In the latter case, the system adds the app to the list of trusted apps for that entry, enabling the app to gain access in the future without prompting the user again But I do not see that prompt, and I only see the permission denied error in my program. I can work around this one of two ways Change the access control of the keychain item to Allow all applications to access this item. This is not preferable, as it essentially disables any ACLs for this item. Embed the certificate in a configuration profile that is pushed down to the device via MDM or something similar. This works at a larger scale, but if I'm trying to manually test out a certificate, I don't always want to have to set this up. Is there another way that I go about adding my application to the ACL of the keychain item? Thanks!

[Q] Has there been a change in macOS 15.3.2 and later that can explain why some UDP traffic is not seen by some Network Extensions when it is in previous macOS minor and major versions?

Hello, I'm working on a Transparent Proxy and when the proxy is being stopped, I'm stopping all the flows by calling flow.closeWriteWithError(POSIXError(.ECANCELED)) flow.closeReadWithError(POSIXError(.ECANCELED)) Then all the flows are deallocated. When deallocating the flow the crash occurs: OS Version: macOS 14.1.2 (23B92) Exception Type: EXC_BREAKPOINT (SIGTRAP) Exception Codes: 0x0000000000000001, 0x000000018c2ef704 Termination Reason: Namespace SIGNAL, Code 5 Trace/BPT trap: 5 Terminating Process: exc handler [553] Thread 32 Crashed:: Dispatch queue: <my dispatch queue> 0 CoreFoundation 0x18c2ef704 CF_IS_OBJC + 76 1 CoreFoundation 0x18c23f61c CFErrorGetDomain + 32 2 libnetworkextension.dylib 0x19fe56a00 flow_error_to_errno + 28 3 libnetworkextension.dylib 0x19fe56920 flow_handle_pending_write_requests + 216 4 libnetworkextension.dylib 0x19fe5667c __NEFlowDeallocate + 380 5 CoreFoundation 0x18c2efe28 _CFRelease + 292 6 NetworkExtension 0x19d208390 -[NEAppProxyFlow dealloc] + 36 Is there any way to debug what is happening and if it's related to closing the flow with POSIXError? Thank you

I have checked the storage space of my phone. There is still over a hundred gigabytes of space left. An error occurred when the app was checking the network interface status. The error message is as follows:Error : Error Domain=NSPOSIXErrorDomain Code=28 "No space left on device" UserInfo={_NSURLErrorFailingURLSessionTaskErrorKey=LocalDataTask <7DB1CBFD-B9BE-422D-9C9A-78D8FC04DC1B>.<76>, _kCFStreamErrorDomainKey=1, _kCFStreamErrorCodeKey=28, _NSURLErrorRelatedURLSessionTaskErrorKey=( "LocalDataTask <7DB1CBFD-B9BE-422D-9C9A-78D8FC04DC1B>.<76>" ), _NSURLErrorNWPathKey=satisfied (Path is satisfied), interface: pdp_ip0[lte], ipv4, ipv6, dns, expensive, estimated upload: 65536Bps, uses cell}

Hi! My project has the Local Push Connectivity entitlement for a feature we have requiring us to send low-latency critical notifications over a local, private Wi-Fi network. We have our NEAppPushProvider creating a SSE connection using the Network framework with our hardware running a server. The server sends a keep-alive message every second. On an iPhone 16 with iOS 18+, the connection is reliable and remains stable for hours, regardless of whether the iOS app is in the foreground, background, or killed. One of our QA engineers has been testing on an iPhone 13 running iOS 16, and has notice shortly after locking the phone, specifically when not connected to power the device seems to turn off the Wi-Fi radio. So when the server sends a notification, it is not received. About 30s later, it seems to be back on. This happens on regular intervals. When looking at our log data, the provider does seem to be getting stopped, then restarted shortly after. The reason code is NEProviderStopReasonNoNetworkAvailable, which further validates that the network is getting dropped by the device in regular intervals. My questions are: Were there possibly silent changes to the framework between iOS versions that could be the reason we're seeing inconsistent behavior? Is there a connection type we could use, instead of SSE, that would prevent the device from disconnecting and reconnecting to the Wi-Fi network? Is there an alternative approach to allow us to maintain a persistent network connection with the extension or app?

Hi, Our project is a MacOS SwiftUI GUI application that bundles a (Sandboxed) System Network Extension, signed with a Developer ID certificate for distribution outside of the app store. The system network extension is used to write a packet tunnel provider (NEPacketTunnelProvider), as our project requires the creation of a TUN device. In order for our System VPN to function, it must reach out to a (self-hosted) server (i.e. to discover a list of peers). Being self-hosted, this server is typically not accessible via the public web, and may only be accessible from within a VPN (such as those also implemented using NEPacketTunnelProvider, e.g. Tailscale, Cloudflare WARP). What we've discovered is that the networking code of the System Network Extension process does not attempt to use the other VPN network interfaces (utunX) on the system. In practice, this means requests to IPs and hostnames that should be routed to those interfaces time out. Identical requests made outside of the Network System Extension process use those interfaces and succeed. The simplest example is where we create a URLSession.downloadTask for a resource on the server. A more complicated example is where we execute a Go .dylib that continues to communicate with that server. Both types of requests time out. Two noteworthy logs appear when packets fail to send, both from the kernel 'process': cfil_hash_entry_log:6088 <CFIL: Error: sosend_reinject() failed>: [30685 com.coder.Coder-Desktop.VPN] <UDP(17) out so b795d11aca7c26bf 57728068503033955 57728068503033955 age 0> lport 3001 fport 3001 laddr 100.108.7.40 faddr 100.112.177.88 hash 58B15863 cfil_service_inject_queue:4472 CFIL: sosend() failed 49 I also wrote some test code that probes using a UDP NWConnection and NWPath availableInterfaces. When run from the GUI App, multiple interfaces are returned, including the one that routes the address, utun5. When ran from within the sysex, only en0 is returned. I understand routing a VPN through another is unconventional, but we unfortunately do need this functionality one way or another. Is there any way to modify which interfaces are exposed to the sysex? Additionally, are these limitations of networking within a Network System Extension documented anywhere? Do you have any ideas why this specific limitation might exist?