diff --git a/docs/reference/commandline/ps.md b/docs/reference/commandline/ps.md index 1d5f31da88..d162532d31 100644 --- a/docs/reference/commandline/ps.md +++ b/docs/reference/commandline/ps.md @@ -32,6 +32,8 @@ Options: - since=(|) - ancestor=([:tag]||) containers created from an image or a descendant. + - publish=([/]|/[]) + - expose=([/]|/[]) - is-task=(true|false) - health=(starting|healthy|unhealthy|none) --format string Pretty-print containers using a Go template @@ -83,6 +85,8 @@ The currently supported filters are: * volume (volume name or mount point) - filters containers that mount volumes. * network (network id or name) - filters containers connected to the provided network * health (starting|healthy|unhealthy|none) - filters containers based on healthcheck status +* publish=(container's published port) - filters published ports by containers +* expose=(container's exposed port) - filters exposed ports by containers #### Label @@ -328,6 +332,44 @@ CONTAINER ID IMAGE COMMAND CREATED STATUS 9d4893ed80fe ubuntu "top" 10 minutes ago Up 10 minutes test1 ``` +#### Publish and Expose + +The `publish` and `expose` filters show only containers that have published or exposed port with a given port +number, port range, and/or protocol. The default protocol is `tcp` when not specified. + +The following filter matches all containers that have published port of 80: + +```bash +$ docker run -d --publish=80 busybox top +$ docker run -d --expose=8080 busybox top + +$ docker ps -a + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +9833437217a5 busybox "top" 5 seconds ago Up 4 seconds 8080/tcp dreamy_mccarthy +fc7e477723b7 busybox "top" 50 seconds ago Up 50 seconds 0.0.0.0:32768->80/tcp admiring_roentgen + +$ docker ps --filter publish=80 + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +fc7e477723b7 busybox "top" About a minute ago Up About a minute 0.0.0.0:32768->80/tcp admiring_roentgen +``` + +The following filter matches all containers that have exposed TCP port in the range of `8000-8080`: +```bash +$ docker ps --filter expose=8000-8080/tcp + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +9833437217a5 busybox "top" 21 seconds ago Up 19 seconds 8080/tcp dreamy_mccarthy +``` + +The following filter matches all containers that have exposed UDP port `80`: +```bash +$ docker ps --filter publish=80/udp + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +``` + ## Formatting The formatting option (`--format`) pretty-prints container output using a Go