From 0f36f3ca0a281824a9849683e93bfbae23f66e11 Mon Sep 17 00:00:00 2001
From: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Date: Thu, 25 Jun 2026 17:40:18 -0700
Subject: [PATCH] docs: clarify --dns-domain/--dns-option guest-vs-host DNS
 behavior

Expand the help text for --dns-domain/--dns-option to say they set the guest
/etc/resolv.conf and do not register DNS records (use 'container system dns
create' / config.toml [dns] for that), and mirror the clarification in the
command-reference and how-to docs. Fixes #1794.

Signed-off-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
---
 .../Services/ContainerAPIService/Client/Flags.swift    | 10 ++++++++--
 docs/command-reference.md                              |  8 ++++----
 docs/how-to.md                                         |  2 ++
 3 files changed, 14 insertions(+), 6 deletions(-)

diff --git a/Sources/Services/ContainerAPIService/Client/Flags.swift b/Sources/Services/ContainerAPIService/Client/Flags.swift
index 6a964e8cb..3f63a1a54 100644
--- a/Sources/Services/ContainerAPIService/Client/Flags.swift
+++ b/Sources/Services/ContainerAPIService/Client/Flags.swift
@@ -134,13 +134,19 @@ public struct Flags {
 
         @Option(
             name: .customLong("dns-domain"),
-            help: .init("Default DNS domain", valueName: "domain")
+            help: .init(
+                "Set guest /etc/resolv.conf domain; does not register host or guest DNS records. Use 'container system dns create' and config.toml [dns] for local DNS domains",
+                valueName: "domain"
+            )
         )
         public var domain: String? = nil
 
         @Option(
             name: .customLong("dns-option"),
-            help: .init("DNS options", valueName: "option")
+            help: .init(
+                "Set guest /etc/resolv.conf options (debug, ndots:0); does not register DNS records. Use 'container system dns create' and config.toml [dns] for local domains",
+                valueName: "option"
+            )
         )
         public var options: [String] = []
 
diff --git a/docs/command-reference.md b/docs/command-reference.md
index 9254e35d2..7475e4b36 100644
--- a/docs/command-reference.md
+++ b/docs/command-reference.md
@@ -48,8 +48,8 @@ container run [<options>] <image> [<arguments> ...]
 *   `--cidfile <cidfile>`: Write the container ID to the path provided
 *   `-d, --detach`: Run the container and detach from the process
 *   `--dns <ip>`: DNS nameserver IP address
-*   `--dns-domain <domain>`: Default DNS domain
-*   `--dns-option <option>`: DNS options
+*   `--dns-domain <domain>`: Set the default domain written to the guest container's `/etc/resolv.conf`. This does not register host- or guest-resolvable DNS records; use `container system dns create` and the `config.toml` `[dns]` domain setting to configure local container DNS domains.
+*   `--dns-option <option>`: Add a resolver option written to the guest container's `/etc/resolv.conf`, such as `debug`, `ndots:0`, `timeout:1`, `attempts:1`, or `rotate`. This does not register host- or guest-resolvable DNS records; use `container system dns create` and the `config.toml` `[dns]` domain setting to configure local container DNS domains.
 *   `--dns-search <domain>`: DNS search domains
 *   `--entrypoint <cmd>`: Override the entrypoint of the image
 *   `--init`: Run an init process inside the container that forwards signals and reaps processes
@@ -211,8 +211,8 @@ container create [<options>] <image> [<arguments> ...]
 *   `--cidfile <cidfile>`: Write the container ID to the path provided
 *   `-d, --detach`: Run the container and detach from the process
 *   `--dns <ip>`: DNS nameserver IP address
-*   `--dns-domain <domain>`: Default DNS domain
-*   `--dns-option <option>`: DNS options
+*   `--dns-domain <domain>`: Set the default domain written to the guest container's `/etc/resolv.conf`. This does not register host- or guest-resolvable DNS records; use `container system dns create` and the `config.toml` `[dns]` domain setting to configure local container DNS domains.
+*   `--dns-option <option>`: Add a resolver option written to the guest container's `/etc/resolv.conf`, such as `debug`, `ndots:0`, `timeout:1`, `attempts:1`, or `rotate`. This does not register host- or guest-resolvable DNS records; use `container system dns create` and the `config.toml` `[dns]` domain setting to configure local container DNS domains.
 *   `--dns-search <domain>`: DNS search domains
 *   `--entrypoint <cmd>`: Override the entrypoint of the image
 *   `--init`: Run an init process inside the container that forwards signals and reaps processes
diff --git a/docs/how-to.md b/docs/how-to.md
index e096c7520..a31c40f08 100644
--- a/docs/how-to.md
+++ b/docs/how-to.md
@@ -220,6 +220,8 @@ Create a domain for host connection:
 sudo container system dns create host.container.internal --localhost 203.0.113.113
 ```
 
+DNS flags on `container run` and `container create`, such as `--dns-domain` and `--dns-option`, only configure the guest container's `/etc/resolv.conf`. They do not create DNS records or make names like `name.<domain>` resolve from the host or from a guest. Use `container system dns create` to create local DNS domains, and set the default local container DNS domain with the `config.toml` `[dns]` domain setting or `container system property set dns.domain <domain>`.
+
 Test access to the host HTTP server from a container:
 
 ```console