Admin-UI: document -ip/-allowInsecureBind, network binding rules, and container usage

Admin-UI.md

@@ -26,13 +26,49 @@ weed admin [options]
 | Option | Default | Description |
 |--------|---------|-------------|
 | `-port` | 23646 | Admin server port |
-| `-masters` | localhost:9333 | Comma-separated master servers |
-| `-dataDir` | "" | Directory to store admin configuration and data files |
+| `-ip` | 127.0.0.1 | IP address to listen on. Auto-upgrades to `0.0.0.0` when `-adminPassword` or `[https.admin]` mTLS is configured (see [Network Binding](#network-binding)) |
+| `-port.grpc` | port + 10000 | gRPC server port for worker connections |
+| `-master` | localhost:9333 | Comma-separated master servers (`-masters` is deprecated) |
+| `-filerGroup` | "" | filerGroup for the filers, brokers, and S3 servers |
+| `-dataDir` | . | Directory to store admin configuration and data files |
 | `-adminUser` | admin | Admin interface username |
 | `-adminPassword` | "" | Admin interface password (if empty, auth is disabled) |
 | `-readOnlyUser` | "" | Read-only user username (optional) |
 | `-readOnlyPassword` | "" | Read-only user password (optional; requires adminPassword) |
+| `-allowInsecureBind` | false | INSECURE: allow binding a non-loopback IP without adminPassword or mTLS |
 | `-urlPrefix` | "" | URL path prefix for subdirectory deployment (e.g. `/seaweedfs`) |
+| `-iceberg.port` | 8181 | Iceberg REST Catalog port (0 to hide in UI) |
+| `-lance.port` | 9101 | Lance Namespace port (0 to hide in UI) |
+| `-metricsPort` | 0 | Prometheus metrics listen port (disabled when 0) |
+| `-metricsIp` | "" | Metrics listen IP (empty = all interfaces) |
+| `-debug` | false | Serve runtime pprof data on `-debug.port` (localhost only) |
+| `-debug.port` | 6060 | HTTP port for the pprof debug server |
+| `-cpuprofile` | "" | CPU profile output file, written on shutdown |
+| `-memprofile` | "" | Memory profile output file, written on shutdown |
+
+## Network Binding
+
+By default the admin server binds to `127.0.0.1` (loopback only) so the unauthenticated admin API is never exposed on the network by accident.
+
+- **Authentication configured** (`-adminPassword` or `[https.admin]` mTLS in `security.toml`): the default bind address upgrades to `0.0.0.0` (all interfaces), so authenticated deployments stay reachable from the network without an explicit `-ip` flag.
+- **`-ip`**: set explicitly to override either default.
+- **Non-loopback without auth**: binding a non-loopback address with no `-adminPassword` and no mTLS is refused at startup, unless `-allowInsecureBind` is set (INSECURE; only for trusted isolated networks).
+- **Worker gRPC** (`-port.grpc`): stays on the `-ip` value and does not follow the authenticated `0.0.0.0` upgrade — its authentication comes from `[grpc.admin]` mTLS, not the admin password.
+
+### Running in Docker / Containers
+
+With the loopback default, container port forwarding (`docker run -p 23646:23646 ...`) cannot reach the admin UI. To expose it, enable authentication (recommended — binds `0.0.0.0` automatically):
+
+```bash
+weed admin -master=master:9333 -adminPassword=secret123
+# publish with: docker run -p 23646:23646 ...
+```
+
+Or bind explicitly without auth on a trusted network:
+
+```bash
+weed admin -master=master:9333 -ip=0.0.0.0 -allowInsecureBind  # INSECURE: admin API exposed unauthenticated
+```
 
 ## Examples
 
@@ -40,30 +76,30 @@ weed admin [options]
 
 ```bash
 # Start admin interface on default port (23646)
-weed admin -masters=localhost:9333
+weed admin -master=localhost:9333
 
 # Start with custom port and multiple masters
-weed admin -port=8080 -masters="master1:9333,master2:9333"
+weed admin -port=8080 -master="master1:9333,master2:9333"
 
 # Start with specific data directory
-weed admin -port=23646 -masters="localhost:9333" -dataDir="/var/lib/seaweedfs-admin"
+weed admin -port=23646 -master="localhost:9333" -dataDir="/var/lib/seaweedfs-admin"
 
 # Start with home directory expansion
-weed admin -port=23646 -masters="localhost:9333" -dataDir="~/seaweedfs-admin"
+weed admin -port=23646 -master="localhost:9333" -dataDir="~/seaweedfs-admin"
 ```
 
 ### With Authentication
 
 ```bash
 # Enable authentication
-weed admin -adminUser=admin -adminPassword=secret123 -masters="localhost:9333"
+weed admin -adminUser=admin -adminPassword=secret123 -master="localhost:9333"
 ```
 
 ### Behind a Reverse Proxy (Subdirectory)
 
 ```bash
 # Serve the admin UI under /seaweedfs/ subdirectory
-weed admin -masters="localhost:9333" -urlPrefix=/seaweedfs
+weed admin -master="localhost:9333" -urlPrefix=/seaweedfs
 ```
 
 With this configuration, the admin UI is accessible at `http://localhost:23646/seaweedfs/admin`. All static assets, API endpoints, navigation links, and session cookies are automatically scoped to the prefix.
@@ -86,7 +122,7 @@ location /seaweedfs/ {
 # Production setup with data persistence and authentication
 weed admin \
   -port=23646 \
-  -masters="master1:9333,master2:9333,master3:9333" \
+  -master="master1:9333,master2:9333,master3:9333" \
   -dataDir="/var/lib/seaweedfs-admin" \
   -adminUser=admin \
   -adminPassword=strongpassword123
@@ -94,10 +130,10 @@ weed admin \
 
 ## Data Directory
 
-The data directory (`-dataDir`) is used to persist admin configuration data:
+The data directory (`-dataDir`, default `.`) is used to persist admin configuration data:
 
-- **If specified**: Configuration and data are persisted to disk
-- **If not specified**: All configuration is kept in memory only
+- **Default**: Persists under the current directory
+- **If set to empty** (`-dataDir=""`): All configuration is kept in memory only
 - **Path expansion**: Supports tilde (`~`) expansion for home directory
 - **Auto-creation**: Directory is automatically created if it doesn't exist
 - **Format**: Configuration files are stored in JSON format for easy editing
@@ -215,7 +251,8 @@ ca = "/etc/ssl/ca.crt"     # optional, for mutual TLS
 
 The admin server also runs a gRPC server for worker connections:
 
-- **Port**: HTTP port + 10000 (e.g., if admin runs on 23646, gRPC runs on 33646)
+- **Port**: HTTP port + 10000 by default (e.g., if admin runs on 23646, gRPC runs on 33646); override with `-port.grpc`
+- **Bind address**: follows the explicit `-ip` value; unlike the HTTP listener it does not auto-upgrade to `0.0.0.0` when authentication is configured
 - **Purpose**: Handles worker connections and task distribution
 - **TLS**: Uses `[grpc.admin]` configuration from `security.toml`
 - **Fallback**: Workers fall back to insecure connections if TLS is unavailable
@@ -317,13 +354,18 @@ The admin interface provides RESTful API endpoints for:
    - Verify TLS configuration for worker connections
    - Check firewall rules for gRPC port
 
+5. **Admin UI unreachable from another host or through container port forwarding**:
+   - With no authentication configured, the server binds to `127.0.0.1` (loopback) by default, so `docker -p 23646:23646` forwarding cannot reach it
+   - Set `-adminPassword` (binds `0.0.0.0` automatically) or `-ip=0.0.0.0` with `-allowInsecureBind` on trusted networks
+   - See [Network Binding](#network-binding)
+
 ### Debug Information
 
 Enable debug logging for detailed troubleshooting:
 
 ```bash
 # Run with verbose logging
-weed admin -v=4 -masters="localhost:9333"
+weed admin -v=4 -master="localhost:9333"
 ```
 
 ## Related Commands