admin: update default port to 12535, document -port.legacy

The default admin HTTP port moves from 23646 to 12535 so the derived
worker gRPC port (22535) stays below the Linux ephemeral range
(seaweedfs/seaweedfs#11816). The old 23646/33646 pair is still served
as a best-effort compat listener; Admin-UI gains a Port Migration
section and the -port.legacy option row.

A-typical-step‐by‐step-example.md

@@ -253,7 +253,7 @@ graph LR
     - Set node's ip with dhcp lease per mac address
     - open needed ports
     - allow traffic between nodes
-    - restrict access to the admin interface, which runs on port 23646
+    - restrict access to the admin interface, which runs on port 12535
   - Reboot all node's host for proper/correct ip based on dhcp lease configured above
 
 ---

Admin-UI.md

@@ -25,9 +25,10 @@ weed admin [options]
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `-port` | 23646 | Admin server port |
+| `-port` | 12535 | Admin server port (was 23646 before 4.49 — see [Port Migration](#port-migration)) |
 | `-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 |
+| `-port.legacy` | 23646 | Also serve admin HTTP and worker gRPC (`-port.legacy` + 10000) on the pre-4.49 default for backward compatibility (0 to disable) |
 | `-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 |
@@ -57,11 +58,11 @@ By default the admin server binds to `127.0.0.1` (loopback only) so the unauthen
 
 ### 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):
+With the loopback default, container port forwarding (`docker run -p 12535:12535 ...`) 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 ...
+# publish with: docker run -p 12535:12535 ...
 ```
 
 Or bind explicitly without auth on a trusted network:
@@ -75,17 +76,17 @@ weed admin -master=master:9333 -ip=0.0.0.0 -allowInsecureBind  # INSECURE: admin
 ### Basic Usage
 
 ```bash
-# Start admin interface on default port (23646)
+# Start admin interface on default port (12535)
 weed admin -master=localhost:9333
 
 # Start with custom port and multiple masters
 weed admin -port=8080 -master="master1:9333,master2:9333"
 
 # Start with specific data directory
-weed admin -port=23646 -master="localhost:9333" -dataDir="/var/lib/seaweedfs-admin"
+weed admin -port=12535 -master="localhost:9333" -dataDir="/var/lib/seaweedfs-admin"
 
 # Start with home directory expansion
-weed admin -port=23646 -master="localhost:9333" -dataDir="~/seaweedfs-admin"
+weed admin -port=12535 -master="localhost:9333" -dataDir="~/seaweedfs-admin"
 ```
 
 ### With Authentication
@@ -102,13 +103,13 @@ weed admin -adminUser=admin -adminPassword=secret123 -master="localhost:9333"
 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.
+With this configuration, the admin UI is accessible at `http://localhost:12535/seaweedfs/admin`. All static assets, API endpoints, navigation links, and session cookies are automatically scoped to the prefix.
 
 Example nginx reverse proxy configuration:
 
 ```nginx
 location /seaweedfs/ {
-    proxy_pass http://localhost:23646/seaweedfs/;
+    proxy_pass http://localhost:12535/seaweedfs/;
     proxy_set_header Host $host;
     proxy_set_header X-Real-IP $remote_addr;
     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
@@ -121,7 +122,7 @@ location /seaweedfs/ {
 ```bash
 # Production setup with data persistence and authentication
 weed admin \
-  -port=23646 \
+  -port=12535 \
   -master="master1:9333,master2:9333,master3:9333" \
   -dataDir="/var/lib/seaweedfs-admin" \
   -adminUser=admin \
@@ -251,7 +252,13 @@ ca = "/etc/ssl/ca.crt"     # optional, for mutual TLS
 
 The admin server also runs a gRPC server for worker connections:
 
-- **Port**: HTTP port + 10000 by default (e.g., if admin runs on 23646, gRPC runs on 33646); override with `-port.grpc`
+- **Port**: HTTP port + 10000 by default (e.g., if admin runs on 12535, gRPC runs on 22535); override with `-port.grpc`. A worker given `-admin=host:http` always derives the gRPC port this way; use `host:http.grpc` to pin it explicitly.
+
+## Port Migration
+
+The default admin HTTP port changed from `23646` to `12535` in 4.49: the old default derived gRPC port `33646`, which sits inside the Linux ephemeral port range (`32768`–`60999`) and could be stolen by an outgoing connection before the admin gRPC listener bound it, failing startup.
+
+For compatibility, new releases still listen on the old defaults — HTTP on `23646`, worker gRPC on `33646` — so older workers and bookmarks keep working during rolling upgrades. This is best-effort: if the legacy port is already taken, admin logs a warning and continues on the new ports. Set `-port.legacy=0` (or `-admin.port.legacy=0` in `weed mini`) to disable.
 - **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`
@@ -355,7 +362,7 @@ The admin interface provides RESTful API endpoints for:
    - 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
+   - With no authentication configured, the server binds to `127.0.0.1` (loopback) by default, so `docker -p 12535:12535` 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)
 
@@ -381,7 +388,7 @@ weed admin -v=4 -master="localhost:9333"
 
 Once the admin server is running, access the web interface at:
 ```
-http://localhost:23646
+http://localhost:12535
 ```
 
 Or with custom port:
@@ -391,7 +398,7 @@ http://localhost:PORT
 
 If `-urlPrefix` is configured, include the prefix in the URL:
 ```
-http://localhost:23646/seaweedfs/admin
+http://localhost:12535/seaweedfs/admin
 ```
 
 ### Dashboard (/)

Cloud-Tier.md

@@ -164,7 +164,7 @@ Add `volume.tier.upload -dest s3 -fullPercent=95 -quietFor=1h` to the admin scri
 ```bash
 # Start admin server and worker
 weed admin -master=localhost:9333
-weed worker -admin=localhost:23646
+weed worker -admin=localhost:12535
 ```
 
 Or you can run the `weed shell` periodically in some cron job:

Deployment-with-seaweed-up.md

@@ -265,7 +265,7 @@ s3_servers:
 # Admin UI (dashboard for topology + bucket management)
 admin_servers:
   - ip: 10.0.5.10
-    port: 23646
+    port: 12535
 
 # maintenance Workers (EC, replication, balancing, vacuum)
 worker_servers:

Erasure-Coding-for-warm-storage.md

@@ -40,7 +40,7 @@ Erasure coding is handled by the **`erasure_coding` plugin worker**. Start the a
 
 ```bash
 weed admin -master=localhost:9333
-weed worker -admin=localhost:23646
+weed worker -admin=localhost:12535
 ```
 
 The `erasure_coding` plugin worker automatically detects volumes that are candidates for EC encoding and executes the encoding. It is enabled by default and configurable from the admin UI at `/plugin`. If you are migrating from `master.toml` maintenance scripts, see [[Migrate Maintenance Scripts to Admin Script Plugin]].

Iceberg-Table-Maintenance.md

@@ -31,10 +31,10 @@ Or start a worker with the job type included (it is in the default set):
 
 ```bash
 # Default: includes iceberg_maintenance along with other job types
-weed worker -admin=localhost:23646
+weed worker -admin=localhost:12535
 
 # Explicitly specify job types
-weed worker -admin=localhost:23646 -jobType=iceberg_maintenance
+weed worker -admin=localhost:12535 -jobType=iceberg_maintenance
 ```
 
 ## Operations

Lance-Maintenance-Worker.md

@@ -15,7 +15,7 @@ carries rather than the only one it ever will.
 
 ```bash
 docker run chrislusf/seaweedfs worker-rust \
-  --admin admin:23646 --namespace http://s3:9101
+  --admin admin:12535 --namespace http://s3:9101
 ```
 
 The standard image carries it at `/usr/bin/weed-worker` on `amd64` and `arm64`,
@@ -45,7 +45,7 @@ A Rust toolchain and a protoc; see [Building it](#building-it) below.
 
 ```bash
 weed-worker \
-  --admin localhost:23646 \
+  --admin localhost:12535 \
   --namespace http://localhost:9101
 ```
 
@@ -53,7 +53,7 @@ weed-worker \
 
 | Flag | Default | Meaning |
 |------|---------|---------|
-| `--admin` | `localhost:23646` | admin server's HTTP address |
+| `--admin` | `localhost:12535` | admin server's HTTP address |
 | `--namespace` | | Lance Namespace URL (`WEED_LANCE_NAMESPACE`) |
 | `--id` | hostname-derived | worker id; **two workers sharing one id evict each other** |
 | `--heartbeat-seconds` | `10` | |

Migrate-Maintenance-Scripts-to-Admin-Script-Plugin.md

@@ -31,7 +31,7 @@ The admin server connects to the master. Once connected, the master automaticall
 ### 2. Start a worker
 
 ```bash
-weed worker -admin=localhost:23646
+weed worker -admin=localhost:12535
 ```
 
 The worker registers with the admin server and begins handling plugin jobs. By default it handles all available job types including `admin_script` and `erasure_coding`.
@@ -42,7 +42,7 @@ When the `admin_script` worker registers for the first time, the admin server au
 
 If the admin server cannot reach the master or the `master.toml` has no maintenance scripts configured, the worker's built-in defaults are used instead.
 
-You can review and adjust the imported script in the admin UI at `http://<admin-host>:23646/plugin` under the **Admin Script** job type.
+You can review and adjust the imported script in the admin UI at `http://<admin-host>:12535/plugin` under the **Admin Script** job type.
 
 #### Adjustments to make
 
@@ -97,7 +97,7 @@ Some shell commands use different flag names between the legacy scripts and the
 ```
 ┌──────────────┐         ┌──────────────┐         ┌──────────────┐
 │  weed master │◄────────│  weed admin  │────────►│  weed worker │
-│              │  gRPC   │  :23646      │  gRPC   │              │
+│              │  gRPC   │  :12535      │  gRPC   │              │
 │  master.toml │ ─────── │  Admin UI    │         │ admin_script │
 │  [maintenance│ scripts │  /plugin     │         │ erasure_coding│
 │   scripts    │ imported│              │         │ vacuum       │

Quick-Start-with-weed-mini.md

@@ -20,7 +20,7 @@ The same command also brings up:
 - Volume Server: http://localhost:9340
 - Filer UI: http://localhost:8888
 - WebDAV: http://localhost:7333
-- Admin UI: http://localhost:23646
+- Admin UI: http://localhost:12535
 
 ### What each piece does (and how to drop it)
 
@@ -105,7 +105,7 @@ The `chrislusf/seaweedfs` image runs `weed mini -dir=/data` by default, so the o
 
 ```bash
 docker run -d --name weed-mini \
-  -p 8333:8333 -p 8888:8888 -p 9333:9333 -p 23646:23646 \
+  -p 8333:8333 -p 8888:8888 -p 9333:9333 -p 12535:12535 \
   -v weed-data:/data \
   -e AWS_ACCESS_KEY_ID=admin \
   -e AWS_SECRET_ACCESS_KEY=secret \
@@ -117,7 +117,7 @@ Exposed ports:
 - `8333` — S3 endpoint
 - `8888` — Filer UI
 - `9333` — Master UI
-- `23646` — Admin UI
+- `12535` — Admin UI
 
 Drop any of the env vars to skip that piece (no `S3_BUCKET` → no bucket created; no AWS keys → "Allow All" mode). Drop `-v weed-data:/data` if you don't need data to persist across container restarts.
 
@@ -172,7 +172,7 @@ jobs:
 The S3 gateway starts in **"Allow All" mode** when no credentials are configured — convenient for development, but not what you want in production. The Quick Start command above seeds credentials via `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` so authentication is enabled from the first request.
 
 - **No credentials configured**: All S3 operations are allowed without authentication.
-- **Credentials added**: As soon as *any* credentials are configured (env vars at startup, the Admin UI at http://localhost:23646, or `weed shell`), authentication switches on and all requests must be signed.
+- **Credentials added**: As soon as *any* credentials are configured (env vars at startup, the Admin UI at http://localhost:12535, or `weed shell`), authentication switches on and all requests must be signed.
 
 For larger credential sets, use a JSON file with `-s3.config=s3.config` instead of env vars.
 
@@ -209,7 +209,7 @@ aws --endpoint-url $S3_ENDPOINT s3 ls s3://my-bucket/
 ## Web Interfaces
 
 ### Admin UI
-- **URL**: http://localhost:23646
+- **URL**: http://localhost:12535
 - **Purpose**: User/credential management, task monitoring, system status
 - **No authentication by default** (configurable)
 

S3-Credentials.md

@@ -60,8 +60,8 @@ Use the SeaweedFS Admin UI to manage S3 credentials through a web interface:
 # Start the admin interface (separate from filer)
 weed admin -masters=localhost:9333
 
-# Access the admin UI (default port 23646)
-http://localhost:23646
+# Access the admin UI (default port 12535)
+http://localhost:12535
 ```
 
 Navigate to **Object Store → Users** (`/object-store/users`) to:
@@ -409,7 +409,7 @@ I0723 12:35:12.456 auth_credentials_subscribe.go:55] updated /etc/seaweedfs/iam/
 
 Admin UI changes are automatically applied in real-time since they use the same filer-based storage:
 
-1. **Access Admin UI**: Navigate to `http://localhost:23646`
+1. **Access Admin UI**: Navigate to `http://localhost:12535`
 2. **Go to Users**: Click **Object Store → Users**
 3. **Make Changes**: Create, edit, or delete users through the web interface
 4. **Automatic Sync**: Changes are immediately applied to all connected S3 servers

SeaweedFS-Lance-Catalog.md

@@ -130,7 +130,7 @@ opens the same data with no catalog in the path. duckdb, pandas, Polars and Data
 
 ## Maintenance
 
-A Lance table needs upkeep that no Iceberg worker can do — in particular, rows written after an index was built are not covered by it, so a vector search silently misses them. The worker ships in the SeaweedFS image (`docker run chrislusf/seaweedfs worker-rust --admin admin:23646`) and on each release; see [[Lance Maintenance Worker]].
+A Lance table needs upkeep that no Iceberg worker can do — in particular, rows written after an index was built are not covered by it, so a vector search silently misses them. The worker ships in the SeaweedFS image (`docker run chrislusf/seaweedfs worker-rust --admin admin:12535`) and on each release; see [[Lance Maintenance Worker]].
 
 ## Admin UI
 

Simplest-S3-Bucket-and-User-Setup.md

@@ -29,7 +29,7 @@ weed shell
 3. Attaches the policy to the user
 
 The access key and secret key are printed in the shell output. You can also
-view them any time from the Admin UI at http://localhost:23646.
+view them any time from the Admin UI at http://localhost:12535.
 
 ### Available roles
 

Volume-Management.md

@@ -12,7 +12,7 @@ Maintenance scripts are managed by the **admin script plugin worker**. Start the
 weed admin -master=localhost:9333
 
 # Start worker (connects to admin server)
-weed worker -admin=localhost:23646
+weed worker -admin=localhost:12535
 ```
 
 The admin script plugin has a built-in default script:

Worker.md

@@ -36,7 +36,7 @@ weed worker [options]
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `-admin` | `localhost:23646` | Admin server address |
+| `-admin` | `localhost:12535` | Admin server address |
 | `-id` | *(auto-generated)* | Worker ID (persisted to `-workingDir` when auto-generated) |
 | `-jobType` | `all` | Job types or categories to serve (comma-separated) |
 | `-workingDir` | *(empty)* | Directory for persistent worker state (worker.id) |
@@ -65,19 +65,19 @@ Categories and explicit names can be combined freely:
 
 ```bash
 # All registered job types (default behavior)
-weed worker -admin=localhost:23646 -jobType=all
+weed worker -admin=localhost:12535 -jobType=all
 
 # Only lightweight maintenance jobs
-weed worker -admin=localhost:23646 -jobType=default
+weed worker -admin=localhost:12535 -jobType=default
 
 # Only resource-intensive jobs on dedicated hardware
-weed worker -admin=localhost:23646 -jobType=heavy
+weed worker -admin=localhost:12535 -jobType=heavy
 
 # Default category plus a specific heavy job
-weed worker -admin=localhost:23646 -jobType=default,iceberg
+weed worker -admin=localhost:12535 -jobType=default,iceberg
 
 # Explicit job types (aliases work too)
-weed worker -admin=localhost:23646 -jobType=vacuum,ec
+weed worker -admin=localhost:12535 -jobType=vacuum,ec
 ```
 
 ### Job Type Aliases
@@ -98,39 +98,39 @@ Each job type accepts several aliases on the CLI:
 
 ```bash
 # Start worker connecting to local admin server (all job types)
-weed worker -admin=localhost:23646
+weed worker -admin=localhost:12535
 
 # Connect to remote admin server
-weed worker -admin=admin.example.com:23646
+weed worker -admin=admin.example.com:12535
 
 # Persist worker ID across restarts
-weed worker -admin=localhost:23646 -workingDir=/var/lib/seaweedfs-worker
+weed worker -admin=localhost:12535 -workingDir=/var/lib/seaweedfs-worker
 ```
 
 ### Specialised Workers
 
 ```bash
 # Dedicated lightweight worker
-weed worker -admin=localhost:23646 -jobType=default
+weed worker -admin=localhost:12535 -jobType=default
 
 # Dedicated heavy worker on beefy hardware
-weed worker -admin=localhost:23646 -jobType=heavy -maxExecute=8
+weed worker -admin=localhost:12535 -jobType=heavy -maxExecute=8
 
 # Only vacuum
-weed worker -admin=localhost:23646 -jobType=vacuum
+weed worker -admin=localhost:12535 -jobType=vacuum
 
 # Named worker with specific job type
-weed worker -admin=localhost:23646 -id=ec-worker-1 -jobType=erasure_coding
+weed worker -admin=localhost:12535 -id=ec-worker-1 -jobType=erasure_coding
 ```
 
 ### Monitoring
 
 ```bash
 # Enable Prometheus /metrics, /health, /ready endpoints
-weed worker -admin=localhost:23646 -metricsPort=9328
+weed worker -admin=localhost:12535 -metricsPort=9328
 
 # Debug with pprof
-weed worker -admin=localhost:23646 -debug -debug.port=6060
+weed worker -admin=localhost:12535 -debug -debug.port=6060
 ```
 
 The metric names are listed in [[System Metrics]]. Note that 9327 is the S3
@@ -151,7 +151,7 @@ with one wants 9328.
 ### Connection Details
 
 - **Protocol**: Bidirectional gRPC stream (`plugin.proto`)
-- **Port**: Admin HTTP port + 10000 by default (e.g., admin on 23646 → gRPC on 33646)
+- **Port**: Admin HTTP port + 10000 by default (e.g., admin on 12535 → gRPC on 22535)
 - **Auto-discovery**: Worker queries `GET /api/plugin/status` to resolve the gRPC port when it differs from the default offset
 - **Security**: Supports TLS using `[grpc.worker]` in `security.toml`