diff --git a/docs/technical-overview.md b/docs/technical-overview.md index e7dd49584..37c7db8a8 100644 --- a/docs/technical-overview.md +++ b/docs/technical-overview.md @@ -74,4 +74,16 @@ In macOS 15, all containers attach to the default vmnet network. The `container In macOS 15, limitations in the vmnet framework mean that the container network can only be created when the first container starts. Since the network XPC helper provides IP addresses to containers, and the helper has to start before the first container, it is possible for the network helper and vmnet to disagree on the subnet address, resulting in containers that are completely cut off from the network. -Normally, vmnet creates the container network using the CIDR address 192.168.64.1/24, and on macOS 15, `container` defaults to using this CIDR address in the network helper. If your containers have no network access on macOS 15, see [All networking fails on macOS 15](troubleshooting.md#all-networking-fails-on-macos-15) for diagnosis and remediation steps. +Normally, vmnet creates the container network using the CIDR address 192.168.64.1/24, and on macOS 15, `container` defaults to using this CIDR address in the network helper. To diagnose and resolve issues stemming from a subnet address mismatch between vmnet and the network helper: + +- Before creating the first container, scan the output of the command `ifconfig` for a bridge interface named similarly to `bridge100`. +- After creating the first container, run `ifconfig` again, and locate the new bridge interface to determine the container subnet address. +- Run `container ls` to check the IP address given to the container by the network helper. If the address corresponds to a different network: + - Run `container system stop` to terminate the services for `container`. + - Following the [container system config tutorial](tutorials/container-system-config-tutorial.md), add or update the default network subnet in `~/.config/container/config.toml`. For example, if the bridge address shown by `ifconfig` is 192.168.66.1, use: + ```toml + [network] + subnet = "192.168.66.1/24" + ``` + - Run `container system start` to launch services again. + - Try running the container again and verify that its IP address matches the current bridge interface value.