Most apps perform ordinary network operations, like fetching an HTTP resource with URLSession and opening a TCP connection to a mail server with Network framework. These operations are not without their challenges, but they’re the well-trodden path. If your app performs ordinary networking, see TN3151 Choosing the right networking API for recommendations as to where to start. Some apps have extra-ordinary networking requirements. For example, apps that: Help the user configure a Wi-Fi accessory Require a connection to run over a specific interface Listen for incoming connections Building such an app is tricky because: Networking is hard in general. Apple devices support very dynamic networking, and your app has to work well in whatever environment it’s running in. Documentation for the APIs you need is tucked away in man pages and doc comments. In many cases you have to assemble these APIs in creative ways. If you’re developing an app with extra-ordinary networking requirements, this post is for you. Note If you have questions or comments about any of the topics discussed here, put them in a new thread here on DevForums. Make sure I see it by putting it in the App & System Services > Networking area. And feel free to add tags appropriate to the specific technology you’re using, like Foundation, CFNetwork, Network, or Network Extension. Links, Links, and More Links Each topic is covered in a separate post: The iOS Wi-Fi Lifecycle describes how iOS joins and leaves Wi-Fi networks. Understanding this is especially important if you’re building an app that works with a Wi-Fi accessory. Network Interface Concepts explains how Apple platforms manage network interfaces. If you’ve got this far, you definitely want to read this. Network Interface Techniques offers a high-level overview of some of the more common techniques you need when working with network interfaces. Network Interface APIs describes APIs and core techniques for working with network interfaces. It’s referenced by many other posts. Running an HTTP Request over WWAN explains why most apps should not force an HTTP request to run over WWAN, what they should do instead, and what to do if you really need that behaviour. If you’re building an iOS app with an embedded network server, see Showing Connection Information in an iOS Server for details on how to get the information to show to your user so they can connect to your server. Many folks run into trouble when they try to find the device’s IP address, or other seemingly simple things, like the name of the Wi-Fi interface. Don’t Try to Get the Device’s IP Address explains why these problems are hard, and offers alternative approaches that function correctly in all network environments. Similarly, folks also run into trouble when trying to get the host name. On Host Names explains why that’s more complex than you might think. If you’re working with broadcasts or multicasts, see Broadcasts and Multicasts, Hints and Tips. If you’re building an app that works with a Wi-Fi accessory, see Working with a Wi-Fi Accessory. If you’re trying to gather network interface statistics, see Network Interface Statistics. There are also some posts that are not part of this series but likely to be of interest if you’re working in this space: TN3179 Understanding local network privacy discusses the local network privacy feature. Calling BSD Sockets from Swift does what it says on the tin, that is, explains how to call BSD Sockets from Swift. When doing weird things with the network, you often find yourself having to use BSD Sockets, and that API is not easy to call from Swift. The code therein is primarily for the benefit of test projects, oh, and DevForums posts like these. TN3111 iOS Wi-Fi API overview is a critical resource if you’re doing Wi-Fi specific stuff on iOS. TLS For Accessory Developers tackles the tricky topic of how to communicate securely with a network-based accessory. A Peek Behind the NECP Curtain discusses NECP, a subsystem that control which programs have access to which network interfaces. Networking Resources has links to many other useful resources. Share and Enjoy — Quinn “The Eskimo!” @ Developer Technical Support @ Apple let myEmail = "eskimo" + "1" + "@" + "apple.com" Revision History 2025-07-31 Added a link to A Peek Behind the NECP Curtain. 2025-03-28 Added a link to On Host Names. 2025-01-16 Added a link to Broadcasts and Multicasts, Hints and Tips. Updated the local network privacy link to point to TN3179. Made other minor editorial changes. 2024-04-30 Added a link to Network Interface Statistics. 2023-09-14 Added a link to TLS For Accessory Developers. 2023-07-23 First posted.

Hello. There is a condition that two requests are executed from an iPhone to the application, and the same session must be maintained throughout the execution of these two requests. The application resides within AWS. AWS ALB offers a Sticky Session feature to maintain sessions; to use this feature, Sticky Session Cookies are utilized, and it seems that the iPhone must be able to set the cookie. I would like to know if the iPhone can accept cookies for Sticky Sessions. Has anyone experienced a similar situation before?

Hey there Are there any recommendations or guidance for apps on alternatives to certificate pinning to secure their device network traffic? I want to move away from the overhead and risk associated with rotating certificates when using leaf pinning. However, I also don't want people to be able to perform a MITM attack easily using something like Charles Proxy with a self‑signed certificate added to the trust store. My understanding is that an app cannot distinguish between user‑trusted certificates and system‑trusted certificates in the trust store, so it cannot block traffic that uses user‑trusted certificates.

It works when one device is only a publisher and the other is only a subscriber. However, when both devices act as both publisher and subscriber simultaneously—which Apple’s documentation (https://developer.apple.com/documentation/wifiaware/adopting-wi-fi-aware#Declare-services) indicates is valid—the connection never establishes. After timing out, both NetworkListener and NetworkBrowser transition to the failed state. This appears to be a race condition in Network framework. Task.detached { try await NetworkListener( for: .wifiAware( .connecting( to: .myService, from: .allPairedDevices, datapath: .defaults ) ), using: .parameters { Coder( sending: ..., receiving: ..., using: NetworkJSONCoder() ) { TCP() } } ).run { connection in await self.add(connection: connection) } } Task.detached { try await NetworkBrowser( for: .wifiAware( .connecting( to: .allPairedDevices, from: .myService ) ), using: .tcp ).run { endpoints in for endpoint in endpoints { await self.connect(to: endpoint) } } }

For important background information, read Extra-ordinary Networking before reading this. Share and Enjoy — Quinn “The Eskimo!” @ Developer Technical Support @ Apple let myEmail = "eskimo" + "1" + "@" + "apple.com" Working with a Wi-Fi Accessory Building an app that works with a Wi-Fi accessory presents specific challenges. This post discusses those challenges and some recommendations for how to address them. Note While my focus here is iOS, much of the info in this post applies to all Apple platforms. IMPORTANT iOS 18 introduced AccessorySetupKit, a framework to simplify the discovery and configuration of an accessory. I’m not fully up to speed on that framework myself, but I encourage you to watch WWDC 2024 Session 10203 Meet AccessorySetupKit and read the framework documentation. IMPORTANT iOS 26 introduced WiFiAware, a framework for setting up communication with Wi-Fi Aware accessories. Wi-Fi Aware is an industry standard to securely discover, pair, and communicate with nearby devices. This is especially useful for stand-alone accessories (defined below). For more on this framework, watch WWDC 2025 Session 228 Supercharge device connectivity with Wi-Fi Aware and read the framework documentation. For information on how to create a Wi-Fi Aware accessory that works with iPhone, go to Developer > Accessories, download Accessory Design Guidelines for Apple Devices, and review the Wi-Fi Aware chapter. Accessory Categories I classify Wi-Fi accessories into three different categories. A bound accessory is ultimately intended to join the user’s Wi-Fi network. It may publish its own Wi-Fi network during the setup process, but the goal of that process is to get the accessory on to the existing network. Once that’s done, your app interacts with the accessory using ordinary networking APIs. An example of a bound accessory is a Wi-Fi capable printer. A stand-alone accessory publishes a Wi-Fi network at all times. An iOS device joins that network so that your app can interact with it. The accessory never provides access to the wider Internet. An example of a stand-alone accessory is a video camera that users take with them into the field. You might want to write an app that joins the camera’s network and downloads footage from it. A gateway accessory is one that publishes a Wi-Fi network that provides access to the wider Internet. Your app might need to interact with the accessory during the setup process, but after that it’s useful as is. An example of this is a Wi-Fi to WWAN gateway. Not all accessories fall neatly into these categories. Indeed, some accessories might fit into multiple categories, or transition between categories. Still, I’ve found these categories to be helpful when discussing various accessory integration challenges. Do You Control the Firmware? The key question here is Do you control the accessory’s firmware? If so, you have a bunch of extra options that will make your life easier. If not, you have to adapt to whatever the accessory’s current firmware does. Simple Improvements If you do control the firmware, I strongly encourage you to: Support IPv6 Implement Bonjour [1] These two things are quite easy to do — most embedded platforms support them directly, so it’s just a question of turning them on — and they will make your life significantly easier: Link-local addresses are intrinsic to IPv6, and IPv6 is intrinsic to Apple platforms. If your accessory supports IPv6, you’ll always be able to communicate with it, regardless of how messed up the IPv4 configuration gets. Similarly, if you support Bonjour, you’ll always be able to find your accessory on the network. [1] Bonjour is an Apple term for three Internet standards: RFC 3927 Dynamic Configuration of IPv4 Link-Local Addresses RFC 6762 Multicast DNS RFC 6763 DNS-Based Service Discovery WAC For a bound accessory, support Wireless Accessory Configuration (WAC). This is a relatively big ask — supporting WAC requires you to join the MFi Program — but it has some huge benefits: You don’t need to write an app to configure your accessory. The user will be able to do it directly from Settings. If you do write an app, you can use the EAWiFiUnconfiguredAccessoryBrowser class to simplify your configuration process. HomeKit For a bound accessory that works in the user’s home, consider supporting HomeKit. This yields the same onboarding benefits as WAC, and many other benefits as well. Also, you can get started with the HomeKit Open Source Accessory Development Kit (ADK). Bluetooth LE If your accessory supports Bluetooth LE, think about how you can use that to improve your app’s user experience. For an example of that, see SSID Scanning, below. Claiming the Default Route, Or Not? If your accessory publishes a Wi-Fi network, a key design decision is whether to stand up enough infrastructure for an iOS device to make it the default route. IMPORTANT To learn more about how iOS makes the decision to switch the default route, see The iOS Wi-Fi Lifecycle and Network Interface Concepts. This decision has significant implications. If the accessory’s network becomes the default route, most network connections from iOS will be routed to your accessory. If it doesn’t provide a path to the wider Internet, those connections will fail. That includes connections made by your own app. Note It’s possible to get around this by forcing your network connections to run over WWAN. See Binding to an Interface in Network Interface Techniques and Running an HTTP Request over WWAN. Of course, this only works if the user has WWAN. It won’t help most iPad users, for example. OTOH, if your accessory’s network doesn’t become the default route, you’ll see other issues. iOS will not auto-join such a network so, if the user locks their device, they’ll have to manually join the network again. In my experience a lot of accessories choose to become the default route in situations where they shouldn’t. For example, a bound accessory is never going to be able to provide a path to the wider Internet so it probably shouldn’t become the default route. However, there are cases where it absolutely makes sense, the most obvious being that of a gateway accessory. Acting as a Captive Network, or Not? If your accessory becomes the default route you must then decide whether to act like a captive network or not. IMPORTANT To learn more about how iOS determines whether a network is captive, see The iOS Wi-Fi Lifecycle. For bound and stand-alone accessories, becoming a captive network is generally a bad idea. When the user joins your network, the captive network UI comes up and they have to successfully complete it to stay on the network. If they cancel out, iOS will leave the network. That makes it hard for the user to run your app while their iOS device is on your accessory’s network. In contrast, it’s more reasonable for a gateway accessory to act as a captive network. SSID Scanning Many developers think that TN3111 iOS Wi-Fi API overview is lying when it says: iOS does not have a general-purpose API for Wi-Fi scanning It is not. Many developers think that the Hotspot Helper API is a panacea that will fix all their Wi-Fi accessory integration issues, if only they could get the entitlement to use it. It will not. Note this comment in the official docs: NEHotspotHelper is only useful for hotspot integration. There are both technical and business restrictions that prevent it from being used for other tasks, such as accessory integration or Wi-Fi based location. Even if you had the entitlement you would run into these technical restrictions. The API was specifically designed to support hotspot navigation — in this context hotspots are “Wi-Fi networks where the user must interact with the network to gain access to the wider Internet” — and it does not give you access to on-demand real-time Wi-Fi scan results. Many developers look at another developer’s app, see that it’s displaying real-time Wi-Fi scan results, and think there’s some special deal with Apple that’ll make that work. There is not. In reality, Wi-Fi accessory developers have come up with a variety of creative approaches for this, including: If you have a bound accessory, you might add WAC support, which makes this whole issue go away. In many cases, you can avoid the need for Wi-Fi scan results by adopting AccessorySetupKit. You might build your accessory with a barcode containing the info required to join its network, and scan that from your app. This is the premise behind the Configuring a Wi-Fi Accessory to Join the User’s Network sample code. You might configure all your accessories to have a common SSID prefix, and then take advantage of the prefix support in NEHotspotConfigurationManager. See Programmatically Joining a Network, below. You might have your app talk to your accessory via some other means, like Bluetooth LE, and have the accessory scan for Wi-Fi networks and return the results. Programmatically Joining a Network Network Extension framework has an API, NEHotspotConfigurationManager, to programmatically join a network, either temporarily or as a known network that supports auto-join. For the details, see Wi-Fi Configuration. One feature that’s particularly useful is it’s prefix support, allowing you to create a configuration that’ll join any network with a specific prefix. See the init(ssidPrefix:) initialiser for the details. For examples of how to use this API, see: Configuring a Wi-Fi Accessory to Join the User’s Network — It shows all the steps for one approach for getting a non-WAC bound accessory on to the user’s network. NEHotspotConfiguration Sample — Use this to explore the API in general. Secure Communication Users expect all network communication to be done securely. For some ideas on how to set up a secure connection to an accessory, see TLS For Accessory Developers. Revision History 2025-11-05 Added a link to the Accessory Design Guidelines for Apple Devices. 2025-06-19 Added a preliminary discussion of Wi-Fi Aware. 2024-09-12 Improved the discussion of AccessorySetupKit. 2024-07-16 Added a preliminary discussion of AccessorySetupKit. 2023-10-11 Added the HomeKit section. Fixed the link in Secure Communication to point to TLS For Accessory Developers. 2023-07-23 First posted.

For Local network access, Chrome prompts the user to allow access and adds it to Settings --> Privacy & Security --> Local Network. However, for Safari, no prompt appears. How do I force Safari to authorise these local network access requests if it won't trigger the permission dialogue? Is there a specific WKWebView configuration or Safari-specific header required to satisfy this security check?

Hi, I'm experiencing intermittent delays with URLSession where requests take 3-4 seconds to be sent, even though the actual server processing is fast. This happens randomly, maybe 10-20% of requests. The pattern I've noticed is I create my request I send off my request using try await urlSession.data(for: request) My middleware ends up receiving this request 4-7s after its been fired from the client-side The round trip ends up taking 4-7s! This hasn't been reproducible consistently at all on my end. I've also tried ephemeral URLSessions (so recreating the session instead of using .shared so no dead connections, but this doesn't seem to help at all) Completely lost on what to do. Please help!

We have an iOS companion app that talks to our IoT device over the device’s own Wi‑Fi network (often with no internet). The app performs bi-directional, safety-critical duties over that link. We use an NEAppPushProvider extension so the handset can keep exchanging data while the UI is backgrounded. During testing we noticed that if the user backgrounds the app (still connected to the device’s Wi‑Fi) and opens Safari, the extension’s stop is invoked with NEProviderStopReason.unrecoverableNetworkChange / noNetworkAvailable, and iOS tears the extension down. Until the system restarts the extension (e.g. the user foregrounds our app again), the app cannot send/receive its safety-critical data. Questions: Is there a supported way to stop a safety-critical NEAppPushProvider from being terminated in this “background app → open Safari” scenario when the device remains on the same Wi‑Fi network (possibly without internet)? If not, is NEAppPushProvider the correct extension type for an always-on local-network use case like this, or is there another API we should be using? For safety-critical applications, can Apple grant entitlements/exemptions so the system does not terminate the extension when the user switches apps but stays on the local Wi‑Fi? Any guidance on the expected lifecycle or alternative patterns for safety-critical local connectivity would be greatly 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?

I want to add more cipher suites. I use NWConnection to make a connection. Before I use sec_protocol_options_append_tls_ciphersuite method to add more cipher suites, I found that Apple provided 20 cipher suites shown in the client hello packet. But after I added three more cipher suites, I found that nothing changed, and still original 20 cipher suites shown in the client hello packet when I made a new connection. The following is the code about connection. I want to add three more cipher suites: tls_ciphersuite_t.ECDHE_ECDSA_WITH_AES_128_CBC_SHA256, tls_ciphersuite_t.ECDHE_ECDSA_WITH_AES_256_CBC_SHA384, tls_ciphersuite_t.ECDHE_RSA_WITH_AES_256_CBC_SHA384 Can you give me some advice about how to add more cipher suites? Thanks. By the way, I working on a MacOS app. Xcode version: 16 MacOS version: 15.6

Hi there, We are facing some issues regarding TLS connectivity: Starting with iOS 26, the operating system refuses to open TLS sockets to local devices with self-signed certificates over Wi-Fi. In this situation, connection is no longer possible, even if the device is detected on the network with Bonjour. We have not found a workaround for this problem. We've tryied those solutions without success: Added the 'NSAppTransportSecurity' key to the info.plist file, testing all its items, such as "NSAllowsLocalNetworking", "NSExceptionDomains", etc. Various code changes to use properties such as "sec_protocol_options_set_local_identity" and "sec_protocol_options_set_tls_server_name" to no avail. Brutally import the certificate files into the project and load them via, for example, "Bundle.main.url(forResource: "nice_INTERFACE_server_cert", withExtension: "crt")", using methods such as sec_trust_copy_ref and SecCertificateCopyData. Download the .pem or .crt files to the iPhone, install them (now visible under "VPN & Device Management"), and then flag them as trusted by going to "Settings -> General -> Info -> Trust". certificates" The most critical part seems to be the line sec_protocol_options_set_verify_block(tlsOptions.securityProtocolOptions, { $2(true) }, queue) whose purpose is to bypass certificate checks and validate all of them (as apps already do). However, on iOS26, if I set a breakpoint on leg$2(true),` it never gets there, while on iOS 18, it does. I'll leave as example the part of the code that was tested the most below. Currently, on iOS26, the handler systematically falls back to .cancelled: func startConnection(host: String, port: UInt16) { self.queue = DispatchQueue(label: "socketQueue") let tlsOptions = NWProtocolTLS.Options() sec_protocol_options_set_verify_block(tlsOptions.securityProtocolOptions, { $2(true) }, queue) let parameters = NWParameters(tls: tlsOptions) self.nwConnection = NWConnection(host: .init(host), port: .init(rawValue: port)!, using: parameters) self.nwConnection.stateUpdateHandler = { [weak self] state in switch state { case .setup: break case .waiting(let error): self?.connectionDidFail(error: error) case .preparing: break case .ready: self?.didConnectSubject.onNext(Void()) case .failed(let error): self?.connectionDidFail(error: error) case .cancelled: self?.didDisconnectSubject.onNext(nil) @unknown default: break } } self.setupReceive() self.nwConnection.start(queue: queue) } These are the prints made during the procedure. The ones with the dot are from the app, while the ones without are warnings/info from Xcode: 🔵 INFO WifiNetworkManager.connect():52 - Try to connect onto the interface access point with ssid NiceProView4A9151_AP 🔵 INFO WifiNetworkManager.connect():68 - Connected to NiceProView4A9151_AP tcp_output [C13:2] flags=[R.] seq=215593821, ack=430284980, win=4096 state=CLOSED rcv_nxt=430284980, snd_una=215593821 nw_endpoint_flow_failed_with_error [C13 192.168.0.1:443 in_progress channel-flow (satisfied (Path is satisfied), viable, interface: en0[802.11], dns, uses wifi, LQM: unknown)] already failing, returning nw_connection_copy_protocol_metadata_internal_block_invoke [C13] Client called nw_connection_copy_protocol_metadata_internal on unconnected nw_connection nw_connection_copy_protocol_metadata_internal_block_invoke [C13] Client called nw_connection_copy_protocol_metadata_internal on unconnected nw_connection nw_connection_copy_connected_local_endpoint_block_invoke [C13] Client called nw_connection_copy_connected_local_endpoint on unconnected nw_connection nw_connection_copy_connected_remote_endpoint_block_invoke [C13] Client called nw_connection_copy_connected_remote_endpoint on unconnected nw_connection nw_connection_copy_protocol_metadata_internal_block_invoke [C14] Client called nw_connection_copy_protocol_metadata_internal on unconnected nw_connection nw_connection_copy_protocol_metadata_internal_block_invoke [C14] Client called nw_connection_copy_protocol_metadata_internal on unconnected nw_connection nw_connection_copy_connected_local_endpoint_block_invoke [C14] Client called nw_connection_copy_connected_local_endpoint on unconnected nw_connection nw_connection_copy_connected_remote_endpoint_block_invoke [C14] Client called nw_connection_copy_connected_remote_endpoint on unconnected nw_connection [C14 192.168.0.1:443 tcp, tls, attribution: developer] is already cancelled, ignoring cancel [C14 192.168.0.1:443 tcp, tls, attribution: developer] is already cancelled, ignoring cancel nw_connection_copy_protocol_metadata_internal_block_invoke [C15] Client called nw_connection_copy_protocol_metadata_internal on unconnected nw_connection nw_connection_copy_protocol_metadata_internal_block_invoke [C15] Client called nw_connection_copy_protocol_metadata_internal on unconnected nw_connection nw_connection_copy_connected_local_endpoint_block_invoke [C15] Client called nw_connection_copy_connected_local_endpoint on unconnected nw_connection nw_connection_copy_connected_remote_endpoint_block_invoke [C15] Client called nw_connection_copy_connected_remote_endpoint on unconnected nw_connection nw_connection_copy_protocol_metadata_internal_block_invoke [C16] Client called nw_connection_copy_protocol_metadata_internal on unconnected nw_connection nw_connection_copy_protocol_metadata_internal_block_invoke [C16] Client called nw_connection_copy_protocol_metadata_internal on unconnected nw_connection nw_connection_copy_connected_local_endpoint_block_invoke [C16] Client called nw_connection_copy_connected_local_endpoint on unconnected nw_connection nw_connection_copy_connected_remote_endpoint_block_invoke [C16] Client called nw_connection_copy_connected_remote_endpoint on unconnected nw_connection [C16 192.168.0.1:443 tcp, tls, attribution: developer] is already cancelled, ignoring cancel [C16 192.168.0.1:443 tcp, tls, attribution: developer] is already cancelled, ignoring cancel 🔴 ERROR InterfaceDisconnectedViewModel.connect():51 - Sequence timeout.

How often do we see control filter start and stop? I read somewhere that data filter is long lived and control Filter is short lived. When does the operating system kills the control filter process?

I need to run multiple, slightly different copies of a modeling tool, which all need access to a model repository on a different machine. Security Settings -> Network tends to pick one modeling tool (and unfortunately the wrong one) for permission, but the dialog offers no way to add the other copies manually. Where can I configure the permission on low level. [macOS Sequoia 15.6.1]

This is a topic that’s come up a few times on the forums, so I thought I’d write up a summary of the issues I’m aware of. 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" Network Extension Provider Packaging There are two ways to package a network extension provider: App extension ( appex ) System extension ( sysex ) Different provider types support different packaging on different platforms. See TN3134 Network Extension provider deployment for the details. Some providers, most notably packet tunnel providers on macOS, support both appex and sysex packaging. Sysex packaging has a number of advantages: It supports direct distribution, using Developer ID signing. It better matches the networking stack on macOS. An appex is tied to the logged in user, whereas a sysex, and the networking stack itself, is global to the system as a whole. Given that, it generally makes sense to package your Network Extension (NE) provider as a sysex on macOS. If you’re creating a new product that’s fine, but if you have an existing iOS product that you want to bring to macOS, you have to account for the differences brought on by the move to sysex packaging. Similarly, if you have an existing sysex product on macOS that you want to bring to iOS, you have to account for the appex packaging. This post summarises those changes. Keep the following in mind while reading this post: The information here applies to all NE providers that can be packaged as either an appex or a sysex. When this post uses a specific provider type in an example, it’s just an example. Unless otherwise noted, any information about iOS also applies to iPadOS, tvOS, and visionOS. Process Lifecycle With appex packaging, the system typically starts a new process for each instance of your NE provider. For example, with a packet tunnel provider: When the users starts the VPN, the system creates a process and then instantiates and starts the NE provider in that process. When the user stops the VPN, the system stops the NE provider and then terminates the process running it. If the user starts the VPN again, the system creates an entirely new process and instantiates and starts the NE provider in that. In contrast, with sysex packaging there’s typically a single process that runs all off the sysex’s NE providers. Returning to the packet tunnel provider example: When the users starts the VPN, the system instantiates and starts the NE provider in the sysex process. When the user stops the VPN, the system stops and deallocates the NE provider instances, but leaves the sysex process running. If the user starts the VPN again, the system instantiates and starts a new instances of the NE provider in the sysex process. This lifecycle reflects how the system runs the NE provider, which in turn has important consequences on what the NE provider can do: An appex acts like a launchd agent [1], in that it runs in a user context and has access to that user’s state. A sysex is effectively a launchd daemon. It runs in a context that’s global to the system as a whole. It does not have access to any single user’s state. Indeed, there might be no user logged in, or multiple users logged in. The following sections explore some consequences of the NE provider lifecycle. [1] It’s not actually run as a launchd agent. Rather, there’s a system launchd agent that acts as the host for the app extension. App Groups With an app extension, the app extension and its container app run as the same user. Thus it’s trivial to share state between them using an app group container. Note When talking about extensions on Apple platforms, the container app is the app in which the extension is embedded and the host app is the app using the extension. For network extensions the host app is the system itself. That’s not the case with a system extension. The system extension runs as root whereas the container app runs an the user who launched it. While both programs can claim access to the same app group, the app group container location they receive will be different. For the system extension that location will be inside the home directory for the root user. For the container app the location will be inside the home directory of the user who launched it. This does not mean that app groups are useless in a Network Extension app. App groups are also a factor in communicating between the container app and its extensions, the subject of the next section. IMPORTANT App groups have a long and complex history on macOS. For the full story, see App Groups: macOS vs iOS: Working Towards Harmony. Communicating with Extensions With an app extension there are two communication options: App-provider messages App groups App-provider messages are supported by NE directly. In the container app, send a message to the provider by calling sendProviderMessage(_:responseHandler:) method. In the appex, receive that message by overriding the handleAppMessage(_:completionHandler:) method. An appex can also implement inter-process communication (IPC) using various system IPC primitives. Both the container app and the appex claim access to the app group via the com.apple.security.application-groups entitlement. They can then set up IPC using various APIs, as explain in the documentation for that entitlement. With a system extension the story is very different. App-provider messages are supported, but they are rarely used. Rather, most products use XPC for their communication. In the sysex, publish a named XPC endpoint by setting the NEMachServiceName property in its Info.plist. Listen for XPC connections on that endpoint using the XPC API of your choice. Note For more information about the available XPC APIs, see XPC Resources. In the container app, connect to that named XPC endpoint using the XPC Mach service name API. For example, with NSXPCConnection, initialise the connection with init(machServiceName:options:), passing in the string from NEMachServiceName. To maximise security, set the .privileged flag. Note XPC Resources has a link to a post that explains why this flag is important. If the container app is sandboxed — necessary if you ship on the Mac App Store — then the endpoint name must be prefixed by an app group ID that’s accessible to that app, lest the App Sandbox deny the connection. See the app groups documentation for the specifics. When implementing an XPC listener in your sysex, keep in mind that: Your sysex’s named XPC endpoint is registered in the global namespace. Any process on the system can open a connection to it [1]. Your XPC listener must be prepared for this. If you want to restrict connections to just your container app, see XPC Resources for a link to a post that explains how to do that. Even if you restrict access in that way, it’s still possible for multiple instances of your container app to be running simultaneously, each with its own connection to your sysex. This happens, for example, if there are multiple GUI users logged in and different users run your container app. Design your XPC protocol with this in mind. Your sysex only gets one named XPC endpoint, and thus one XPC listener. If your sysex includes multiple NE providers, take that into account when you design your XPC protocol. [1] Assuming that connection isn’t blocked by some other mechanism, like the App Sandbox. Inter-provider Communication A sysex can include multiple types of NE providers. For example, a single sysex might include a content filter and a DNS proxy provider. In that case the system instantiates all of the NE providers in the same sysex process. These instances can communicate without using IPC, for example, by storing shared state in global variables (with suitable locking, of course). It’s also possible for a single container app to contain multiple sysexen, each including a single NE provider. In that case the system instantiates the NE providers in separate processes, one for each sysex. If these providers need to communicate, they have to use IPC. In the appex case, the system instantiates each provider in its own process. If two providers need to communicate, they have to use IPC. Managing Secrets An appex runs in a user context and thus can store secrets, like VPN credentials, in the keychain. On macOS this includes both the data protection keychain and the file-based keychain. It can also use a keychain access group to share secrets with its container app. See Sharing access to keychain items among a collection of apps. Note If you’re not familiar with the different types of keychain available on macOS, see TN3137 On Mac keychain APIs and implementations. A sysex runs in the global context and thus doesn’t have access to user state. It also doesn’t have access to the data protection keychain. It must use the file-based keychain, and specifically the System keychain. That means there’s no good way to share secrets with the container app. Instead, do all your keychain operations in the sysex. If the container app needs to work with a secret, have it pass that request to the sysex via IPC. For example, if the user wants to use a digital identity as a VPN credential, have the container app get the PKCS#12 data and password and then pass that to the sysex so that it can import the digital identity into the keychain. Memory Limits iOS imposes strict memory limits an NE provider appexen [1]. macOS imposes no memory limits on NE provider appexen or sysexen. [1] While these limits are not documented officially, you can get a rough handle on the current limits by reading the posts in this thread. Frameworks If you want to share code between a Mac app and its embedded appex, use a structure like this: MyApp.app/ Contents/ MacOS/ MyApp PlugIns/ MyExtension.appex/ Contents/ MacOS/ MyExtension … Frameworks/ MyFramework.framework/ … There’s one copy of the framework, in the app’s Frameworks directory, and both the app and the appex reference it. This approach works for an appex because the system always loads the appex from your app’s bundle. It does not work for a sysex. When you activate a sysex, the system copies it to a protected location. If that sysex references a framework in its container app, it will fail to start because that framework isn’t copied along with the sysex. The solution is to structure your app like this: MyApp.app/ Contents/ MacOS/ MyApp Library/ SystemExtensions/ MyExtension.systemextension/ Contents/ MacOS/ MyExtension Frameworks/ MyFramework.framework/ … … That is, have both the app and the sysex load the framework from the sysex’s Frameworks directory. When the system copies the sysex to its protected location, it’ll also copy the framework, allowing the sysex to load it. To make this work you have to change the default rpath configuration set up by Xcode. Read Dynamic Library Standard Setup for Apps to learn how that works and then tweak things so that: The framework is embedded in the sysex, not the container app. The container app has an additional LC_RPATH load command for the sysex’s Frameworks directory (@executable_path/../Library/SystemExtensions/MyExtension.systemextension/Contents/Frameworks). The sysex’s LC_RPATH load command doesn’t reference the container app’s Frameworks directory (@executable_path/../../../../Frameworks) but instead points to the sysex’s Framweorks directory (@executable_path/../Frameworks). Entitlements When you build an app with an embedded NE extension, both the app and the extension must be signed with the com.apple.developer.networking.networkextension entitlement. This is a restricted entitlement, that is, it must be authorised by a provisioning profile. The value of this entitlement is an array, and the values in that array differ depend on your distribution channel: If you distribute your app directly with Developer ID signing, use the values with the -systemextension suffix. Otherwise — including when you distribute the app on the App Store and when signing for development — use the values without that suffix. Make sure you authorise these values with your provisioning profile. If, for example, you use an App Store distribution profile with a Developer ID signed app, things won’t work because the profile doesn’t authorise the right values. In general, the easiest option is to use Xcode’s automatic code signing. However, watch out for the pitfall described in Exporting a Developer ID Network Extension. Revision History 2025-11-06 Added the Entitlements section. Explained that, with sysex packaging, multiple instances of your container app might connect simultaneously with your sysex. 2025-09-17 First posted.

Hello, I am currently investigating if we can disable usage of QUIC on application level. I know we can set enable_quic from /Library/Preferences/com.apple.networkd.plist to false but it will have a global impact since this is a system file, all the applications on machine will stop using QUIC. I don't want that. What i am looking for is to disable QUIC only for my application. Is there any way i can modify URLSession object in my application and disable QUIC? or modify URLSessionConfiguration so system will not use QUIC?

Hi everyone, I’m currently developing a macOS app that is distributed via a DMG file on our website. The app includes an App Extension (appex) for Network Extension functionality. I’m wondering if distributing via DMG on the web requires the app extension to be implemented as a System Extension instead of an App Extension. Is it necessary to migrate to System Extension for web-based DMG distribution, or can I continue using App Extension as is? Any insights or recommendations would be greatly appreciated. Thank you!

I need to know the https address of a certain page within my app. This is going to be used as a redirect URL. I don't think it is a good idea to use deep links because it has to be an https address. I don't think Universal Links will work because it is not my website that I will be communicating with.

We are developing a client server application using TCP bsd sockets. When our client is connected to the server, copying another client .app bundle from a file server on the same machine (using Finder or terminal using cp), occasionally causes the first client to disconnect. The client receives an EBROKENPIPE error when attempting to write to its socket. In the Console, the following message appears just before the disconnection: necp_socket_find_policy_match: Marking socket in state 258 as defunct This issue seems to occur only when copying an .app bundle signed with the same TeamIdentifier as the running client. Copying arbitrary files or bundles with a different TeamIdentifier does not trigger the problem. We are running on macOS 15.5. The issue appears specific to macOS 15 and was not observed on earlier versions. Any help or pointers would be greatly appreciated!

Hello, Our app uses Network Extension / Packet Tunnel Provider to establish VPN connections on macOS and iOS. We have observed that after creating a utun device and adding any IPv4 routes (NEPacketTunnelNetworkSettings.IPv4Settings), the OS automatically adds several host routes via utun to services such as Akamai, Apple Push, etc. These routes appear to correspond to TCP flows that were active at the moment the VPN connection was established. When a particular TCP flow ends, the corresponding host route is deleted. We understand this is likely intended to avoid breaking existing TCP connections. However, we find the behavior of migrating existing TCP flows to the new utun interface simply because any IPv4 route is added somewhat questionable. This approach would make sense in a "full-tunnel" scenario — for example, when all IPv4 traffic (e.g., 0.0.0.0/0) is routed through the tunnel — but not necessarily in a "split-tunnel" configuration where only specific IPv4 routes are added. Is there any way to control or influence this behavior? Would it be possible for FlowDivert to differentiate between full-tunnel and split-tunnel cases, and only preserve existing TCP flows via utun in the full-tunnel scenario? Thank you.

ios構成プロファイルの制限のallowCloudPrivateRelayのプライベートリレーの制御とRelayペイロードの機能は関係がありますか？ それとも別々の機能でしょうか？ ↓ s there a relationship between the private relay control in the iOS configuration profile restriction allowCloudPrivateRelay and the functionality of the Relay payload? Or are they separate features?