From 83a1b0117f3e880680a3d62c0078da9fbe89e075 Mon Sep 17 00:00:00 2001 From: Devin Date: Tue, 29 Sep 2026 10:21:58 +0800 Subject: [PATCH] Admin-UI: document -ip/-allowInsecureBind, network binding rules, and container usage --- Admin-UI.md | 70 ++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 56 insertions(+), 14 deletions(-) diff --git a/Admin-UI.md b/Admin-UI.md index 361019d..f0df4f2 100644 --- a/Admin-UI.md +++ b/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