# PacketTunnel System Extension Logging and App Group Containers (macOS)

## Overview

When debugging a `NEPacketTunnelProvider` system extension on macOS, it
is important to understand that the extension does **not** run in the
same user context as the host application.

A PacketTunnel system extension is launched and managed by the system
(via `neagent`) and typically executes with **root privileges**.

As a result, even though the host app and the system extension share the
same **App Group ID**, they do **not** resolve to the same physical
container directory.

------------------------------------------------------------------------

## App Group Container Resolution Difference

Because the PacketTunnel system extension runs as **root**, its App
Group container resolves under:

    /private/var/root/Library/Group Containers/...

Whereas the main macOS application runs as the logged-in user, so its
App Group container resolves under:

    ~/Library/Group Containers/...

Therefore, the host app and the PacketTunnel system extension are
writing into two different container directories.

------------------------------------------------------------------------

## Practical Impact

This difference explains why file-based logging via `wg_log()` works in
the main app but appears to produce no output from the system extension.

The system extension is writing its log file into the root-owned
container:

-   **Main app container:**

    ~/Library/Group Containers/K42595UFF3.group.com.finlayintl.poponet/

-   **System extension container:**

    /private/var/root/Library/Group Containers/K42595UFF3.group.com.finlayintl.poponet/

Since the host app only exports logs from its own user container, logs
written by the system extension are never included.

------------------------------------------------------------------------

## Recommended Debugging Approach: Use Unified Logging (`os_log`)

For PacketTunnel providers, Apple's intended debugging mechanism is
**Unified Logging**, not App Group file logging.

### Step 1 --- Insert `os_log()` Calls in the System Extension

Example:

``` swift
if let url = FileManager.tunnelUnhealthyFlagURL {
    os_log("SE log path: %{public}s", url.path)
}
```

This ensures logs appear in the macOS unified logging system.

------------------------------------------------------------------------

### Step 2 --- Stream Logs in Terminal

Run:

``` bash
log stream --predicate 'process CONTAINS "packetTunnel"'
```

This streams all unified logs emitted by the PacketTunnel system
extension.

------------------------------------------------------------------------

### Step 3 --- Trigger Events in the App

Perform the relevant action (connect tunnel, restart, etc.) that causes
the system extension to execute the `os_log()` call.

------------------------------------------------------------------------

### Step 4 --- Filter Output

Inspect the streamed output to identify the system extension log
entries.

------------------------------------------------------------------------

## Conclusion

`wg_log()` appeared to "not work" inside `packetTunnelSE` because the
PacketTunnel provider runs as **root**, causing its App Group container
path to differ from the main application's container path.

For reliable debugging of Network Extensions on macOS, prefer:

-   `os_log()` / unified logging
-   Provider-to-app IPC for persistent log export (if needed)

------------------------------------------------------------------------
