From f8dd8f074def2448519dd7af3f4beabd6c09ae61 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Tue, 12 Dec 2023 22:36:26 +0100
Subject: [PATCH] docs: refresh --publish, add --publish-all
Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
docs/reference/commandline/run.md | 43 +++++++++++++++++++++++--------
1 file changed, 32 insertions(+), 11 deletions(-)
diff --git a/docs/reference/commandline/run.md b/docs/reference/commandline/run.md
index 092204f668..46e46db561 100644
--- a/docs/reference/commandline/run.md
+++ b/docs/reference/commandline/run.md
@@ -90,7 +90,7 @@ Create and run a new container from an image
| `--platform` | `string` | | Set platform if server is multi-platform capable |
| [`--privileged`](#privileged) | | | Give extended privileges to this container |
| [`-p`](#publish), [`--publish`](#publish) | `list` | | Publish a container's port(s) to the host |
-| `-P`, `--publish-all` | | | Publish all exposed ports to random ports |
+| [`-P`](#publish-all), [`--publish-all`](#publish-all) | | | Publish all exposed ports to random ports |
| [`--pull`](#pull) | `string` | `missing` | Pull image before running (`always`, `missing`, `never`) |
| `-q`, `--quiet` | | | Suppress the pull output |
| [`--read-only`](#read-only) | | | Mount the container's root filesystem as read only |
@@ -483,26 +483,47 @@ $ docker run -t -i --mount type=bind,src=/data,dst=/data busybox sh
### Publish or expose port (-p, --expose)
```console
-$ docker run -p 127.0.0.1:80:8080/tcp ubuntu bash
+$ docker run -p 127.0.0.1:80:8080/tcp nginx:alpine
```
-This binds port `8080` of the container to TCP port `80` on `127.0.0.1` of the host
-machine. You can also specify `udp` and `sctp` ports.
-The [Docker User Guide](https://docs.docker.com/network/links/)
-explains in detail how to use ports in Docker.
+This binds port `8080` of the container to TCP port `80` on `127.0.0.1` of the
+host. You can also specify `udp` and `sctp` ports. The [Networking overview
+page](https://docs.docker.com/network/) explains in detail how to publish ports
+with Docker.
-Note that ports which are not bound to the host (i.e., `-p 80:80` instead of
-`-p 127.0.0.1:80:80`) are externally accessible. This also applies if
-you configured UFW to block this specific port, as Docker manages its
-own iptables rules. [Read more](https://docs.docker.com/network/iptables/)
+> **Note**
+>
+> If you don't specify an IP address (i.e., `-p 80:80` instead of `-p
+> 127.0.0.1:80:80`) when publishing a container's ports, Docker publishes the
+> port on all interfaces (address `0.0.0.0`) by default. These ports are
+> externally accessible. This also applies if you configured UFW to block this
+> specific port, as Docker manages its own iptables rules. [Read
+> more](https://docs.docker.com/network/packet-filtering-firewalls/)
```console
-$ docker run --expose 80 ubuntu bash
+$ docker run --expose 80 nginx:alpine
```
This exposes port `80` of the container without publishing the port to the host
system's interfaces.
+### Publish all exposed ports (-P, --publish-all)
+
+```console
+$ docker run -P nginx:alpine
+```
+
+The `-P`, or `--publish-all`, flag publishes all the exposed ports to the host.
+Docker binds each exposed port to a random port on the host.
+
+The `-P` flag only publishes port numbers that are explicitly flagged as
+exposed, either using the Dockerfile `EXPOSE` instruction or the `--expose`
+flag for the `docker run` command.
+
+The range of ports are within an *ephemeral port range* defined by
+`/proc/sys/net/ipv4/ip_local_port_range`. Use the `-p` flag to explicitly map a
+single port or range of ports.
+
### Set the pull policy (--pull)
Use the `--pull` flag to set the image pull policy when creating (and running)