Document container name vs hostname and network DNS

docs/source/markdown/options/hostname.container.md

@@ -15,3 +15,7 @@ This option can only be used with a private UTS namespace `--uts=private`
 (default), the pod's hostname is used. The given hostname is also added to the
 `/etc/hosts` file using the container's primary IP address (also see the
 << '**AddHost=**' if is_quadlet else '**--add-host**' >> option).
+
+When << '**HostName=** is unset' if is_quadlet else '**--hostname** is not used' >> and the container uses a private UTS namespace (default), Podman sets the hostname to the first 12 characters of the container ID. The container name assigned with << '**ContainerName=**' if is_quadlet else '**--name**' >> is not used unless *container_name_as_hostname=true* is set in `containers.conf`.
+
+Podman network DNS registers the container name, the short container ID (first 12 characters), and any explicitly set **--hostname** as DNS names. The default hostname matches the short ID alias. See **[podman-network(1)](podman-network.1.md)**.

docs/source/markdown/options/name.container.md

@@ -18,8 +18,17 @@ The operator can identify a container in three ways:
 
 Podman generates a UUID for each container, and if no name is assigned to the
 container using << '**ContainerName=**' if is_quadlet else '**--name**' >>,
-Podman generates a random string name. The name can
-be useful as a more human-friendly way to identify containers. This works for
-both background and foreground containers. The container's name is also added
-to the `/etc/hosts` file using the container's primary IP address (also see the
+Podman generates a random string name such as `exciting_chebyshev` (`adjective_noun`,
+compatible with Docker). Container names are not required to be valid hostnames or
+domain names. Underscores and other characters allowed by naming rules are
+permitted. On Podman networks with DNS enabled, container-to-container name
+resolution still uses the name as given, for example `exciting_chebyshev`. The
+name can be useful as a more human-friendly way to identify containers.
+This works for both background and foreground containers.
+The container's name is also added to the `/etc/hosts` file using the
+container's primary IP address (also see the
 << '**AddHost=**' if is_quadlet else '**--add-host**' >> option).
+
+The name is not the hostname inside the container; see
+<< '**HostName=**' if is_quadlet else '**--hostname**' >>. See
+**[podman-network(1)](podman-network.1.md)** for more on network DNS.

docs/source/markdown/podman-network-connect.1.md

@@ -13,7 +13,7 @@ Once connected, the container can communicate with other containers in the same
 ## OPTIONS
 #### **--alias**=*name*
 Add network-scoped alias for the container. If the network has DNS enabled (`podman network inspect -f {{.DNSEnabled}} <NAME>`),
-these aliases can be used for name resolution on the given network.  Multiple *--alias* options may be specified as input.
+these aliases can be used for name resolution on the given network in addition to the container name.  Multiple *--alias* options may be specified as input. See **DNS NOTES** in **[podman-network(1)](podman-network.1.md)**.
 
 #### **--ip**=*address*
 Set a static ipv4 address for this container on this network.

docs/source/markdown/podman-network.1.md

@@ -11,6 +11,23 @@ The network command manages networks for Podman.
 
 Podman uses [Netavark](https://github.com/containers/netavark) as the network backend.
 
+## DNS NOTES
+
+On networks with DNS enabled (the default, unless **--disable-dns** is used),
+[aardvark-dns](https://github.com/containers/aardvark-dns) registers each
+container under its name and aliases. Containers that share a pod network
+namespace are registered under the pod name.
+
+The container name is always registered. The short container ID (first 12
+characters) is always registered as an alias. When **--hostname** is explicitly
+set, that hostname is also registered as an alias. By default the hostname
+inside the container is the short ID, so it already matches the alias. Setting
+*container_name_as_hostname=true* in the `[containers]` section of
+**[containers.conf(5)](https://github.com/containers/container-libs/blob/main/common/docs/containers.conf.5.md)**
+changes the hostname only. Additional names can be set with **--alias** on
+**podman run --network** or **podman network connect**. Auto-generated names use
+an underscore between words, for example `exciting_chebyshev`.
+
 ## COMMANDS
 
 | Command    | Man Page                                                       | Description                                                     |