From 2463399112a7a919dff38db7c7fc795f4e83d5b8 Mon Sep 17 00:00:00 2001 From: John Logan Date: Thu, 30 Apr 2026 11:13:42 -0700 Subject: [PATCH] Update documents with note about container-to-host networking. - Currently we need to use `pfctl` to create the packet filter rule for container-to-host networking (`host.docker.internal`). This approach unfortunately has a few limitations that require documentation. --- docs/how-to.md | 5 +++++ docs/technical-overview.md | 13 +------------ 2 files changed, 6 insertions(+), 12 deletions(-) diff --git a/docs/how-to.md b/docs/how-to.md index e096c7520..0c2419de2 100644 --- a/docs/how-to.md +++ b/docs/how-to.md @@ -200,6 +200,11 @@ Test access using `curl`: ## Access a host service from a container +> [!IMPORTANT] +> Due to macOS security constraints around packet filter rules, this feature has limited functionality: +> - Creating a localhost domain disables Private Relay. +> - The local domain packet filter rule is removed on a restart. + Create a DNS domain with `--localhost ` to make a domain used by a container to access a host service. Any IPv4 address can be used as ``, which will be assigned to the domain name in container. Choose an IP address that is least likely to conflict with any networks or reserved IP addresses in your environment. Reasonably safe address ranges include: diff --git a/docs/technical-overview.md b/docs/technical-overview.md index 1e4e1a3e2..e7dd49584 100644 --- a/docs/technical-overview.md +++ b/docs/technical-overview.md @@ -74,15 +74,4 @@ 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. 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`. - - Using the macOS `defaults` command, update the default subnet value used by the network helper process. For example, if the bridge address shown by `ifconfig` is 192.168.66.1, run: - ```bash - defaults write com.apple.container.defaults 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. +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.