PCSM-345 Make HTTP server bind host configurable

docs/install/docker.md

@@ -165,7 +165,8 @@ Start the {{pcsm.short}} container. You can specify connection strings using env
     $ docker run --name pcsm1 --network mymongo -d \
         -e PCSM_SOURCE_URI="mongodb://source:password@psmdb-source:27017" \
         -e PCSM_TARGET_URI="mongodb://target:password@psmdb-target:27017" \
-        -p 2242:2242 \
+        -e PCSM_LISTEN_HOST=0.0.0.0 \
+        -p 127.0.0.1:2242:2242 \
         percona/percona-clustersync-mongodb:latest \
         --port 2242 \
         --log-level debug

docs/install/parameters.md

@@ -14,7 +14,7 @@
 - `--clone-num-insert-workers`: Number of insert workers that write batches to the target. Shared for all collections.
 - `--clone-segment-size`: Segment size for clone operations. Accepts plain bytes or a unit suffix (e.g. `500MB`, `1GiB`). When omitted, the tool automatically calculates segment size based on collection size and available read workers.
 - `--use-collection-bulk-write`: Forces collection-level bulk write instead of the newer client-level bulk write (MongoDB 8.0+).
-
+- `--listen-host`: Host the HTTP server binds to. See [Configure the HTTP listen address](../install/start-pcsm.md#configure-the-http-listen-address).
 
 ??? example "Examples"
 
@@ -46,4 +46,5 @@
 | `PCSM_REPL_EVENT_QUEUE_SIZE` | Controls the size of the internal event queue used by the replication subsystem. | `5000` |
 | `PCSM_REPL_WORKER_QUEUE_SIZE` | Defines the maximum number of replication events that each replication worker thread can queue before processing. | `5000` |
 | `PCSM_REPL_BULK_OPS_SIZE` | Defines the maximum number of operations that can be grouped together into a single bulk apply batch during replication. | `5000` |
+| `PCSM_LISTEN_HOST` | Host the HTTP server binds to. See [Configure the HTTP listen address](../install/start-pcsm.md#configure-the-http-listen-address) | `localhost` |
 

docs/install/start-pcsm.md

@@ -36,6 +36,82 @@
 
 See [Percona ClusterSync for MongoDB startup configuration](parameters.md) for all available options.
 
+## Configure the HTTP listen address
+
+By default, the PCSM HTTP server listens on `localhost`, which keeps the control API and the profiling endpoints reachable only from the local host. Most deployments don't need to change this.
+
+Containerized deployments are the exception. Kubernetes runs HTTP liveness and readiness probes against the pod IP, and Docker forwards published ports to the container IP rather than the container loopback address. A loopback-only listener refuses these connections; failed readiness probes mark the pod unready, while repeated failed liveness probes can restart it.
+
+## Set the bind host
+
+To make the server reachable through the pod IP, set the listen host to `0.0.0.0` for an IPv4 pod or `::` for an IPv6 pod:
+
+```{.bash data-prompt="$"}
+$ PCSM_LISTEN_HOST=0.0.0.0 pcsm
+```
+
+For an IPv6 pod, use `::` instead:
+
+```{.bash data-prompt="$"}
+$ PCSM_LISTEN_HOST=:: pcsm
+```
+
+Alternatively, use the `--listen-host` option:
+
+```{.bash data-prompt="$"}
+$ pcsm --listen-host 0.0.0.0
+```
+
+For an IPv6 pod:
+
+```{.bash data-prompt="$"}
+$ pcsm --listen-host ::
+```
+
+You can also give an IP address or a DNS name. To listen on the IPv6 loopback address:
+
+```{.bash data-prompt="$"}
+$ pcsm --listen-host ::1
+```
+
+!!! warning
+    Binding to `0.0.0.0` (IPv4) or :: (IPv6) exposes all PCSM HTTP endpoints on every network interface of the host or pod. This includes `/start`, `/pause`, `/resume`, `/finalize`, `/status`, `/metrics`, and the `pprof` profiling endpoints. None of them require authentication, so anything that can route to the pod can start, pause, or finalize replication.
+
+    In Kubernetes, restrict access with a `NetworkPolicy` or an equivalent network control. If all you need is a health check, an exec probe against `localhost` gives you the same result with no network exposure.
+
+### Accepted values
+
+| **Value** | **Binds to** | **Use it for** |
+| --- | --- | --- |
+| `localhost` | `localhost:2242` | The default. Local host only. |
+| `0.0.0.0` | `0.0.0.0:2242` | All IPv4 interfaces, including an IPv4 pod IP. |
+| `::` | `[::]:2242` | All IPv6 interfaces, including an IPv6 pod IP. |
+| An IP literal, such as `10.0.2.15` | `10.0.2.15:2242` | A single interface. |
+| `::1` | `[::1]:2242` | The IPv6 loopback address. {{pcsm.short}} adds the brackets automatically. |
+| A DNS name | Resolved when the server binds | A named interface. The name is accepted without being resolved first, so validation doesn't catch an unresolvable name. |
+| Anything containing a port | Rejected at startup | Not supported. Values such as `localhost:2242`, `127.0.0.1:2242`, and `[::1]:2242` fail. Use `--port` to set the port. |
+
+Changing the bind host doesn't affect the CLI. Subcommands such as `pcsm status` always connect to `localhost`.
+
+### What to pass
+
+Give `--listen-host` a host and nothing else. The `--port` option sets the port, and defaults to `2242`.
+
+A value that already contains a port is rejected, so `localhost:2242`, `127.0.0.1:2242`, and `[::1]:2242` all fail at startup. A DNS name is accepted without being resolved first, which means a name that can't be resolved isn't caught by validation.
+
+Changing the bind host doesn't affect the CLI. Subcommands such as `pcsm status` always connect to `localhost`.
+
+### Check that it worked
+
+PCSM reports its bind address when the HTTP server starts. Read the startup log and confirm the address matches what you set:
+
+```sh
+INF s=http Starting HTTP server at http://0.0.0.0:2242
+```
+
+A response means the bind address took effect. Connection refused means the server is still on loopback, so check that the environment variable or option reached the process.
+
+See [Percona ClusterSync for MongoDB startup configuration](parameters.md) for all available options, and [PCSM HTTP API](../api.md) for the endpoints themselves.
 
 ## How to see {{pcsm.full_name}} logs