fix podman create/run UTS NS docs

Add better error message when using `--pod` and `--hostname`.
Improve the docs to better explain the uts hostname relation.
Add more valid options for the `--uts` flag.

Signed-off-by: Paul Holzinger <paul.holzinger@web.de>

3 files changed, 15 insertions, 11 deletions

diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md
index 05aea53b6..976a1e681 100644
--- a/docs/source/markdown/podman-create.1.md
+++ b/docs/source/markdown/podman-create.1.md
@@ -339,7 +339,7 @@ value can be expressed in a time format such as `1m22s`.  The default value is `
 
 Container host name
 
-Sets the container host name that is available inside the container.
+Sets the container host name that is available inside the container. Can only be used with a private UTS namespace `--uts=private` (default). If `--pod` is specified and the pod shares the UTS namespace (default) the pods hostname will be used.
 
 **--help**
 
@@ -898,12 +898,14 @@ Set the user namespace mode for the container.  It defaults to the **PODMAN_USER
 
 This option is incompatible with --gidmap, --uidmap, --subuid and --subgid
 
-**--uts**=*host*
+**--uts**=*mode*
 
-Set the UTS mode for the container
-    **host**: use the host's UTS namespace inside the container.
-    **ns**: specify the user namespace to use.
-    Note: the host mode gives the container access to changing the host's hostname and is therefore considered insecure.
+Set the UTS namespace mode for the container. The following values are supported:
+
+- **host**: use the host's UTS namespace inside the container.
+- **private**: create a new namespace for the container (default).
+- **ns:[path]**: run the container in the given existing UTS namespace.
+- **container:[container]**: join the UTS namespace of the specified container.
 
 **--volume**, **-v**[=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]*]
 
diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md
index ef78e15e3..b6c1fab17 100644
--- a/docs/source/markdown/podman-run.1.md
+++ b/docs/source/markdown/podman-run.1.md
@@ -358,7 +358,7 @@ Print usage statement
 
 Container host name
 
-Sets the container host name that is available inside the container.
+Sets the container host name that is available inside the container. Can only be used with a private UTS namespace `--uts=private` (default). If `--pod` is specified and the pod shares the UTS namespace (default) the pods hostname will be used.
 
 **--http-proxy**=**true**|**false**
 
@@ -938,10 +938,9 @@ This option is incompatible with **--gidmap**, **--uidmap**, **--subuid** and **
 Set the UTS namespace mode for the container. The following values are supported:
 
 - **host**: use the host's UTS namespace inside the container.
-- **private**: create a new namespace for the container (default)
-- **ns**: use own UTS namespace.
-
-**NOTE**: the host mode gives the container access to changing the host's hostname and is therefore considered insecure.
+- **private**: create a new namespace for the container (default).
+- **ns:[path]**: run the container in the given existing UTS namespace.
+- **container:[container]**: join the UTS namespace of the specified container.
 
 **--volume**, **-v**[=[[_source-volume_|_host-dir_:]_container-dir_[:_options_]]]
 
diff --git a/pkg/specgen/container_validate.go b/pkg/specgen/container_validate.go
index 8289e2089..76961fa80 100644
--- a/pkg/specgen/container_validate.go
+++ b/pkg/specgen/container_validate.go
@@ -46,6 +46,9 @@ func (s *SpecGenerator) Validate() error {
 	}
 	// Cannot set hostname and utsns
 	if len(s.ContainerBasicConfig.Hostname) > 0 && !s.ContainerBasicConfig.UtsNS.IsPrivate() {
+		if s.ContainerBasicConfig.UtsNS.IsPod() {
+			return errors.Wrap(ErrInvalidSpecConfig, "cannot set hostname when joining the pod UTS namespace")
+		}
 		return errors.Wrap(ErrInvalidSpecConfig, "cannot set hostname when running in the host UTS namespace")
 	}
 	// systemd values must be true, false, or always