feat(deploy): bind-address flags for browser-facing ports + nginx docs

By default hbbs and hbbr bind every port to the wildcard, which collides
with operators wanting to put nginx/Caddy in front of the dashboard
(443) and the two browser-facing WebSocket ports (21118 rendezvous,
21119 relay) for TLS termination. Operators reported having to choose
between exposing hbbs directly (no TLS for `wss://`, breaks browsers
since the page is HTTPS) or moving the daemon to a different port.

New flags:
- hbbs `--http-listen=<HOST>` pins the HTTP API + dashboard port.
- hbbs `--ws-listen=<HOST>`   pins the WS rendezvous port (port + 2).
- hbbr `--ws-listen=<HOST>`   pins the WS relay port (port + 2).

All default to the wildcard (current behaviour). Set to `127.0.0.1` to
free up the corresponding public port for nginx.

The plain TCP/UDP ports used by desktop clients (21115 NAT test, 21116
rendezvous, 21117 relay) intentionally stay on the wildcard — desktop
clients bring their own framing + secretbox encryption and don't go
through nginx.

Implementation: a small `bind_tcp_listener(host, port)` helper in
common.rs that falls through to the existing `listen_any` when host is
empty, otherwise binds explicitly. Reused for both ws_port (rendezvous +
relay) and the http_port; the latter just builds a `SocketAddr` inline
since axum::serve takes one.

Documentation: new "TLS deployment with nginx" section in
docs/CONFIGURATION.md covering the port plan, the bind flags, full
example nginx vhost config (three server blocks: 443 dashboard,
21118 WSS rendezvous, 21119 WSS relay) with the WebSocket Upgrade
plumbing and bump-up timeouts that long sessions need, plus the
firewall list and the four common failure modes (SSL protocol error,
connection refused, 502, hung 200 instead of 101).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/common.rs

@@ -1,6 +1,7 @@
 use clap::App;
 use hbb_common::{
-    allow_err, anyhow::{Context, Result}, get_version_number, log, tokio, ResultType
+    allow_err, anyhow::{Context, Result}, get_version_number, log, tcp::listen_any, tokio,
+    tokio::net::TcpListener, ResultType,
 };
 use ini::Ini;
 use sodiumoxide::crypto::sign;
@@ -11,6 +12,27 @@ use std::{
     time::{Instant, SystemTime},
 };
 
+/// Bind a TCP listener for `port`. When `host` is empty (the default for
+/// every flag that accepts it), falls through to `listen_any` which binds
+/// the dual-stack `[::]` wildcard. When `host` is set, binds only to that
+/// address — used by deployments that put nginx/Caddy out front for TLS
+/// termination on the WS / HTTP ports and want hbbs/hbbr's plain sockets
+/// reachable only from localhost.
+pub async fn bind_tcp_listener(host: &str, port: i32) -> ResultType<TcpListener> {
+    if host.is_empty() {
+        return listen_any(port as u16).await;
+    }
+    let host_with_brackets = if host.contains(':') && !host.starts_with('[') {
+        format!("[{}]", host)
+    } else {
+        host.to_string()
+    };
+    let addr: SocketAddr = format!("{}:{}", host_with_brackets, port).parse()?;
+    let l = TcpListener::bind(addr).await?;
+    log::info!("listen on tcp {}", addr);
+    Ok(l)
+}
+
 #[allow(dead_code)]
 pub(crate) fn get_expired_time() -> Instant {
     let now = Instant::now();

src/hbbr.rs

@@ -15,6 +15,7 @@ fn main() -> ResultType<()> {
     let args = format!(
         "-p, --port=[NUMBER(default={RELAY_PORT})] 'Sets the listening port'
         -k, --key=[KEY] 'Only allow the client with the same key'
+        --ws-listen=[HOST] 'Bind address for the browser-facing WebSocket relay port (port+2). Default = wildcard. Set to 127.0.0.1 (or ::1) when a reverse proxy claims the public port for TLS termination.'
         ",
     );
     let matches = App::new("hbbr")
@@ -40,6 +41,7 @@ fn main() -> ResultType<()> {
         matches
             .value_of("key")
             .unwrap_or(&std::env::var("KEY").unwrap_or_default()),
+        matches.value_of("ws-listen").unwrap_or(""),
     )?;
     Ok(())
 }

src/main.rs

@@ -22,6 +22,8 @@ fn main() -> ResultType<()> {
         -r, --relay-servers=[HOST] 'Sets the default relay servers, separated by comma'
         -M, --rmem=[NUMBER(default={RMEM})] 'Sets UDP recv buffer size, set system rmem_max first, e.g., sudo sysctl -w net.core.rmem_max=52428800. vi /etc/sysctl.conf, net.core.rmem_max=52428800, sudo sysctl –p'
         --http-port=[NUMBER(default=21114)] 'HTTP management API port (0 disables)'
+        --http-listen=[HOST] 'Bind address for --http-port. Default = wildcard. Set to 127.0.0.1 (or ::1) when nginx/Caddy fronts this port for TLS.'
+        --ws-listen=[HOST] 'Bind address for the browser-facing WebSocket rendezvous port (port+2). Default = wildcard. Set to 127.0.0.1 (or ::1) when a reverse proxy claims the public port for TLS termination.'
         --bootstrap-admin-username=[USERNAME] 'Username to seed on first startup if users table is empty'
         --bootstrap-admin-password=[PASSWORD] 'Password to seed on first startup if users table is empty'
         --ab-legacy-mode=[on|off] 'When on, /api/ab/personal returns 404 to force legacy single-blob AB'
@@ -58,6 +60,8 @@ fn main() -> ResultType<()> {
         &get_arg_or("key", "-".to_owned()),
         rmem,
         http_port,
+        &get_arg("ws-listen"),
+        &get_arg("http-listen"),
     )?;
     Ok(())
 }

src/relay_server.rs

@@ -46,7 +46,7 @@ const BLACKLIST_FILE: &str = "blacklist.txt";
 const BLOCKLIST_FILE: &str = "blocklist.txt";
 
 #[tokio::main(flavor = "multi_thread")]
-pub async fn start(port: &str, key: &str) -> ResultType<()> {
+pub async fn start(port: &str, key: &str, ws_listen: &str) -> ResultType<()> {
     let key = get_server_sk(key);
     if let Ok(mut file) = std::fs::File::open(BLACKLIST_FILE) {
         let mut contents = String::new();
@@ -82,10 +82,21 @@ pub async fn start(port: &str, key: &str) -> ResultType<()> {
     log::info!("Listening on tcp :{}", port);
     let port2 = port + 2;
     log::info!("Listening on websocket :{}", port2);
+    // The WS port (21119 default) is the only browser-facing endpoint at
+    // hbbr — operators put nginx/Caddy in front of it for TLS. Allow
+    // pinning it to localhost so the reverse proxy can claim the public
+    // port without colliding. The plain TCP relay port (21117) is for
+    // desktop clients and stays on the wildcard.
+    let ws_listen = ws_listen.to_owned();
     let main_task = async move {
         loop {
             log::info!("Start");
-            io_loop(listen_any(port).await?, listen_any(port2).await?, &key).await;
+            io_loop(
+                listen_any(port).await?,
+                crate::common::bind_tcp_listener(&ws_listen, port2 as i32).await?,
+                &key,
+            )
+            .await;
         }
     };
     let listen_signal = crate::common::listen_signal();

src/rendezvous_server.rs

@@ -110,10 +110,16 @@ impl RendezvousServer {
         key: &str,
         rmem: usize,
         http_port: i32,
+        ws_listen: &str,
+        http_listen: &str,
     ) -> ResultType<()> {
         let (key, sk) = Self::get_server_sk(key);
         let nat_port = port - 1;
         let ws_port = port + 2;
+        // Capture the bind addresses as owned Strings so the async move
+        // closures below can hold onto them across reconnect retries.
+        let ws_listen = ws_listen.to_owned();
+        let http_listen = http_listen.to_owned();
         let pm = PeerMap::new().await?;
         // M1: build the HTTP API state and seed the admin user if requested.
         // Done here (right after PeerMap::new) so the API server, the seeding,
@@ -199,7 +205,11 @@ impl RendezvousServer {
         rs.parse_relay_servers(&get_arg("relay-servers"));
         let mut listener = create_tcp_listener(port).await?;
         let mut listener2 = create_tcp_listener(nat_port).await?;
-        let mut listener3 = create_tcp_listener(ws_port).await?;
+        // The WS port is the only browser-facing endpoint at hbbs — it's
+        // the one operators put nginx/Caddy in front of for TLS. Allow
+        // pinning it to localhost so the reverse proxy can claim
+        // `[::]:21118` without colliding.
+        let mut listener3 = crate::common::bind_tcp_listener(&ws_listen, ws_port).await?;
         let test_addr = std::env::var("TEST_HBBS").unwrap_or_default();
         if std::env::var("ALWAYS_USE_RELAY")
             .unwrap_or_default()
@@ -266,7 +276,7 @@ impl RendezvousServer {
                     }
                     LoopFailure::Listener3 => {
                         drop(listener3);
-                        listener3 = create_tcp_listener(ws_port).await?;
+                        listener3 = crate::common::bind_tcp_listener(&ws_listen, ws_port).await?;
                     }
                 }
             }
@@ -278,7 +288,15 @@ impl RendezvousServer {
         let api_task: std::pin::Pin<
             Box<dyn std::future::Future<Output = ResultType<()>> + Send>,
         > = if http_port > 0 {
-            let addr: SocketAddr = format!("0.0.0.0:{http_port}").parse()?;
+            let bind_host = if http_listen.is_empty() { "0.0.0.0" } else { http_listen.as_str() };
+            // Allow IPv6 / [::1] / hostnames — wrap bare IPv6 in brackets for the URL form.
+            let host_with_brackets = if bind_host.contains(':') && !bind_host.starts_with('[') {
+                format!("[{}]", bind_host)
+            } else {
+                bind_host.to_string()
+            };
+            let addr: SocketAddr = format!("{}:{}", host_with_brackets, http_port).parse()?;
+            log::info!("HTTP API listening on {}", addr);
             let st = api_state.clone();
             Box::pin(crate::api::serve(addr, st))
         } else {