diff --git a/crates/metadb-server/src/bin/metadbd.rs b/crates/metadb-server/src/bin/metadbd.rs index a41ec75..6b6640b 100644 --- a/crates/metadb-server/src/bin/metadbd.rs +++ b/crates/metadb-server/src/bin/metadbd.rs @@ -1,25 +1,12 @@ //! `metadbd` — Standalone Single-Node & Distributed Multi-Role MetaDB Server Daemon. use std::path::PathBuf; -use std::sync::Arc; -use std::time::Duration; use clap::Parser; -use http_body_util::Full; -use hyper::body::{Bytes, Incoming}; -use hyper::server::conn::http1; -use hyper::service::service_fn; -use hyper::{Method, Request, Response, StatusCode}; -use hyper_util::rt::{TokioIo, TokioTimer}; -use tokio::net::{TcpListener, TcpStream}; -use tokio::sync::oneshot; -use tokio::task::JoinSet; use metadb_proto::control_plane_service_client::ControlPlaneServiceClient; use metadb_proto::RegisterNodeRequest; -use metadb_server::{ - render_prometheus_metrics, PersistentMetaDbCluster, ServerRole, ServerTomlConfig, -}; +use metadb_server::{PersistentMetaDbCluster, ServerRole, ServerTomlConfig}; #[derive(Debug, Parser)] #[command( @@ -112,7 +99,6 @@ async fn main() -> Result<(), Box> { let node_id = cfg.node.node_id; let cell_id = cfg.node.cell_id; - let metrics_addr_opt = cfg.node.metrics_listen_addr.clone(); let shared_secret = cfg.security.shared_secret.clone(); let (cluster, bound_addr) = PersistentMetaDbCluster::open_and_serve(cfg).await?; tracing::info!(grpc_addr = %bound_addr, "metadbd online and serving requests"); @@ -144,96 +130,8 @@ async fn main() -> Result<(), Box> { tracing::info!(cell_manager = %cm_url, node_id, cell_id, "registered node with cell manager"); } - let metrics_task = if let Some(m_addr) = metrics_addr_opt { - let m_listener = TcpListener::bind(&m_addr).await?; - tracing::info!(metrics_addr = %m_listener.local_addr()?, "Prometheus metrics endpoint listening"); - let (stop, stopped) = oneshot::channel(); - let m_cluster = cluster.clone(); - Some(( - stop, - tokio::spawn(serve_metrics(m_listener, m_cluster, stopped)), - )) - } else { - None - }; - tokio::signal::ctrl_c().await?; tracing::info!("received shutdown signal; flushing state and stopping OpenRaft groups"); - if let Some((stop, task)) = metrics_task { - let _ = stop.send(()); - task.await?; - } cluster.shutdown().await?; Ok(()) } - -// Bound both connection count and request lifetime, including slow readers/writers. -const METRICS_MAX_CONNECTIONS: usize = 64; -const METRICS_MAX_HEADER_BYTES: usize = 8192; -const METRICS_IO_TIMEOUT: Duration = Duration::from_secs(2); - -async fn serve_metrics( - listener: TcpListener, - cluster: Arc, - mut shutdown: oneshot::Receiver<()>, -) { - let mut connections = JoinSet::new(); - loop { - tokio::select! { - _ = &mut shutdown => break, - Some(_) = connections.join_next(), if !connections.is_empty() => {}, - accepted = listener.accept(), if connections.len() < METRICS_MAX_CONNECTIONS => { - let Ok((socket, _)) = accepted else { break; }; - let cluster = cluster.clone(); - connections.spawn(async move { - let _ = tokio::time::timeout(METRICS_IO_TIMEOUT, metrics_connection(socket, cluster)).await; - }); - } - } - } - connections.abort_all(); - while connections.join_next().await.is_some() {} -} - -async fn metrics_connection( - socket: TcpStream, - cluster: Arc, -) -> Result<(), hyper::Error> { - let service = service_fn(move |request: Request| { - let cluster = cluster.clone(); - async move { - let (status, body) = if request.method() != Method::GET { - ( - StatusCode::METHOD_NOT_ALLOWED, - "method not allowed\n".to_owned(), - ) - } else if request.uri().path() != "/metrics" { - (StatusCode::NOT_FOUND, "not found\n".to_owned()) - } else { - ( - StatusCode::OK, - render_prometheus_metrics(&cluster.metrics_snapshot()), - ) - }; - let mut response = Response::new(Full::new(Bytes::from(body))); - *response.status_mut() = status; - response.headers_mut().insert( - hyper::header::CONTENT_TYPE, - hyper::header::HeaderValue::from_static("text/plain; version=0.0.4"), - ); - response.headers_mut().insert( - hyper::header::CONNECTION, - hyper::header::HeaderValue::from_static("close"), - ); - Ok::<_, std::convert::Infallible>(response) - } - }); - http1::Builder::new() - .timer(TokioTimer::new()) - .header_read_timeout(METRICS_IO_TIMEOUT) - .max_headers(64) - .max_buf_size(METRICS_MAX_HEADER_BYTES) - .keep_alive(false) - .serve_connection(TokioIo::new(socket), service) - .await -} diff --git a/crates/metadb-server/src/config.rs b/crates/metadb-server/src/config.rs index e7f73ed..0c1a17d 100644 --- a/crates/metadb-server/src/config.rs +++ b/crates/metadb-server/src/config.rs @@ -1,6 +1,7 @@ //! TOML & programmatic server configuration for `metadbd` and `PersistentMetaDbCluster`. use std::fs; +use std::net::IpAddr; use std::path::{Path, PathBuf}; use serde::{Deserialize, Serialize}; @@ -90,15 +91,15 @@ impl Default for StorageSection { } } -/// Application-level gRPC auth. TLS is not terminated by this process. +/// Application-level bearer auth. This process does not terminate TLS. /// -/// An empty `shared_secret` leaves metadata and control-plane RPCs unauthenticated. -/// The default bind address is `127.0.0.1`. Do not publish that socket on an -/// untrusted network until a secret (or an external TLS terminator) is configured. +/// An empty `shared_secret` is accepted only for loopback listeners. A wildcard or +/// any other non-loopback bind with an empty secret refuses to start. When the +/// secret is non-empty, gRPC and the metrics listener require the same bearer. #[derive(Debug, Clone, Default, Serialize, Deserialize)] #[serde(default)] pub struct SecuritySection { - /// When non-empty, every gRPC call must send `authorization: Bearer `. + /// When non-empty, gRPC and metrics require `authorization: Bearer `. pub shared_secret: String, } @@ -147,8 +148,11 @@ pub struct ServerTomlConfig { impl ServerTomlConfig { pub fn from_toml_str(s: &str) -> Result { - toml::from_str(s) - .map_err(|e| MetaDbError::CodecError(format!("invalid TOML config: {}", e))) + let value: toml::Value = toml::from_str(s) + .map_err(|e| MetaDbError::CodecError(format!("invalid TOML config: {e}")))?; + reject_unsupported_security_keys(&value)?; + ServerTomlConfig::deserialize(value) + .map_err(|e| MetaDbError::CodecError(format!("invalid TOML config: {e}"))) } pub fn from_toml_file(path: impl AsRef) -> Result { @@ -172,6 +176,150 @@ impl ServerTomlConfig { auto_locality_compaction: true, }) } + + /// Refuses to start when a listener is not loopback and no secret is configured. + /// + /// Call this on the configured addresses and again on the address that will + /// actually be bound (a restarted process may reuse a saved advertise address). + pub fn reject_unauthenticated_bind(&self, addr: &str) -> Result<()> { + reject_unauthenticated_bind(addr, &self.security.shared_secret) + } +} + +/// `true` only for an explicit loopback bind: `localhost`, `127.0.0.0/8`, or `::1`. +/// +/// Wildcard addresses (`0.0.0.0`, `::`) and unparseable hosts are not loopback. +/// `localhost` is accepted as a name and is not resolved, so a hosts-file alias +/// is not detected here. +fn is_loopback_bind(addr: &str) -> bool { + let host = bind_host(addr.trim()); + if host.eq_ignore_ascii_case("localhost") { + return true; + } + match host.parse::() { + Ok(ip) => ip.is_loopback(), + Err(_) => false, + } +} + +fn reject_unauthenticated_bind(addr: &str, secret: &str) -> Result<()> { + if !secret.trim().is_empty() || is_loopback_bind(addr) { + return Ok(()); + } + Err(MetaDbError::CodecError(format!( + "refusing to serve unauthenticated listener {addr}; a wildcard or non-loopback bind requires a non-empty [security].shared_secret. Empty, missing, and misspelled secrets fail closed. This process does not terminate TLS" + ))) +} + +fn bind_host(addr: &str) -> &str { + if let Some(rest) = addr.strip_prefix('[') { + let end = rest.find(']').unwrap_or(rest.len()); + return &rest[..end]; + } + match addr.rsplit_once(':') { + Some((host, port)) + if !host.is_empty() + && !host.contains(':') + && port.bytes().all(|b| b.is_ascii_digit()) => + { + host + } + _ => addr, + } +} + +fn normalize_key(key: &str) -> String { + key.to_ascii_lowercase().replace('-', "_") +} + +fn is_tls_key(key: &str) -> bool { + let key = normalize_key(key); + [ + "tls", "ssl", "cert", "x509", "mtls", "cipher", "keystore", "https", + ] + .iter() + .any(|needle| key.contains(needle)) +} + +fn is_secret_key(key: &str) -> bool { + let key = normalize_key(key); + [ + "secret", + "password", + "passwd", + "token", + "credential", + "auth", + ] + .iter() + .any(|needle| key.contains(needle)) + || key.starts_with("secur") +} + +fn security_key_error(key: &str) -> MetaDbError { + if is_tls_key(key) { + MetaDbError::CodecError(format!( + "refusing to start: `{key}` is not a supported TLS setting. This process does not terminate TLS and will not serve plaintext while a TLS option is present. Terminate TLS in an external proxy, then remove `{key}`" + )) + } else { + MetaDbError::CodecError(format!( + "refusing to start: unrecognized security key `{key}`. A missing or misspelled shared_secret must not leave listeners open. The only accepted security key is [security].shared_secret" + )) + } +} + +fn reject_unsupported_security_keys(value: &toml::Value) -> Result<()> { + let Some(root) = value.as_table() else { + return Err(MetaDbError::CodecError( + "TOML config must be a table".to_string(), + )); + }; + if let Some(security) = root.get("security") { + let Some(table) = security.as_table() else { + return Err(MetaDbError::CodecError( + "refusing to start: [security] must be a table. The only accepted security key is [security].shared_secret".to_string(), + )); + }; + for (key, child) in table { + if key != "shared_secret" { + return Err(security_key_error(key)); + } + // The secret value itself must not smuggle a nested TLS or secret table. + reject_nested_security_keys(child)?; + } + } + for (key, child) in root { + if key == "security" { + continue; + } + if is_tls_key(key) || is_secret_key(key) { + return Err(security_key_error(key)); + } + reject_nested_security_keys(child)?; + } + Ok(()) +} + +/// Rejects secret and TLS keys anywhere except the direct `[security].shared_secret` field. +/// Tables and arrays are walked, including `[node.transport]` and `[[listeners]]`. +fn reject_nested_security_keys(value: &toml::Value) -> Result<()> { + match value { + toml::Value::Table(table) => { + for (key, child) in table { + if is_tls_key(key) || is_secret_key(key) { + return Err(security_key_error(key)); + } + reject_nested_security_keys(child)?; + } + } + toml::Value::Array(items) => { + for item in items { + reject_nested_security_keys(item)?; + } + } + _ => {} + } + Ok(()) } #[cfg(test)] @@ -213,4 +361,119 @@ mod tests { assert_eq!(cfg.storage.memtable_size_bytes, 1024); assert_eq!(cfg.storage.block_cache_bytes, 65536); } + + #[test] + fn loopback_binds_are_explicit_and_wildcards_are_not() { + for addr in [ + "127.0.0.1:7800", + "127.0.0.1:0", + "localhost:7800", + "[::1]:7800", + ] { + assert!(is_loopback_bind(addr), "{addr}"); + assert!(reject_unauthenticated_bind(addr, "").is_ok(), "{addr}"); + } + for addr in [ + "0.0.0.0:7800", + "[::]:7800", + "10.1.2.3:7800", + "db.internal:7800", + ] { + assert!(!is_loopback_bind(addr), "{addr}"); + let err = reject_unauthenticated_bind(addr, " ").unwrap_err(); + assert!(err.to_string().contains("refusing to serve"), "{err}"); + } + assert!(reject_unauthenticated_bind("0.0.0.0:7800", "secret").is_ok()); + } + + #[test] + fn misspelled_secret_and_tls_keys_fail_closed() { + let typo = ServerTomlConfig::from_toml_str( + r#" + [node] + grpc_listen_addr = "0.0.0.0:7800" + [security] + shared_secrett = "not-applied" + "#, + ); + assert!( + typo.unwrap_err().to_string().contains("shared_secrett"), + "a misspelled secret key must not parse" + ); + + let tls = ServerTomlConfig::from_toml_str( + r#" + [security] + shared_secret = "secret" + tls_cert = "/tmp/cert.pem" + "#, + ); + let tls_err = tls.unwrap_err().to_string(); + assert!(tls_err.contains("does not terminate TLS"), "{tls_err}"); + + let misplaced = ServerTomlConfig::from_toml_str( + r#" + [node] + shared_secret = "not-in-this-section" + "#, + ); + assert!( + misplaced.unwrap_err().to_string().contains("shared_secret"), + "a secret outside [security] must not be ignored" + ); + + let section = ServerTomlConfig::from_toml_str( + r#" + [tls] + enabled = true + "#, + ); + assert!(section + .unwrap_err() + .to_string() + .contains("does not terminate TLS")); + + let nested = ServerTomlConfig::from_toml_str( + r#" + [node] + grpc_listen_addr = "0.0.0.0:7800" + [node.transport] + tls_cert_file = "/tmp/cert.pem" + [security] + shared_secret = "secret" + "#, + ); + let nested_err = nested.unwrap_err().to_string(); + assert!( + nested_err.contains("does not terminate TLS"), + "{nested_err}" + ); + + let listeners = ServerTomlConfig::from_toml_str( + r#" + [[listeners]] + tls = true + [security] + shared_secret = "secret" + "#, + ); + let listeners_err = listeners.unwrap_err().to_string(); + assert!( + listeners_err.contains("does not terminate TLS"), + "{listeners_err}" + ); + + let cfg = ServerTomlConfig::from_toml_str( + r#" + [node] + node_id = 2 + extra_note = "ignored" + [security] + shared_secret = "secret" + "#, + ) + .unwrap(); + assert_eq!(cfg.node.node_id, 2); + assert_eq!(cfg.security.shared_secret, "secret"); + } } diff --git a/crates/metadb-server/src/lib.rs b/crates/metadb-server/src/lib.rs index 8fd724e..6ec85de 100644 --- a/crates/metadb-server/src/lib.rs +++ b/crates/metadb-server/src/lib.rs @@ -11,8 +11,10 @@ pub mod grpc_services; pub mod metrics; pub mod stress; +mod metrics_http; + use std::collections::BTreeSet; -use std::sync::Arc; +use std::sync::{Arc, OnceLock}; use std::time::Duration; use tokio::net::TcpListener; @@ -38,7 +40,7 @@ impl BearerAuth { } } -fn bearer_header_matches(presented: &str, secret: &str) -> bool { +pub(crate) fn bearer_header_matches(presented: &str, secret: &str) -> bool { let mut expected = Vec::with_capacity(7 + secret.len()); expected.extend_from_slice(b"Bearer "); expected.extend_from_slice(secret.as_bytes()); @@ -501,6 +503,7 @@ pub struct PersistentMetaDbCluster { proxy_router: Arc, shutdown_tx: watch::Sender, task_handles: tokio::sync::Mutex>>, + metrics_addr: OnceLock, } impl PersistentMetaDbCluster { @@ -517,6 +520,10 @@ impl PersistentMetaDbCluster { config.node.role ))); } + config.reject_unauthenticated_bind(&config.node.grpc_listen_addr)?; + if let Some(metrics_addr) = &config.node.metrics_listen_addr { + config.reject_unauthenticated_bind(metrics_addr)?; + } std::fs::create_dir_all(&config.node.data_dir)?; let cell_dir = config .node @@ -534,6 +541,7 @@ impl PersistentMetaDbCluster { } else { config.node.grpc_listen_addr.clone() }; + config.reject_unauthenticated_bind(&listen_addr)?; let listener = match TcpListener::bind(&listen_addr).await { Ok(listener) => listener, Err(error) @@ -637,10 +645,10 @@ impl PersistentMetaDbCluster { if shared_secret.is_empty() { tracing::warn!( listen = %bound_addr, - "gRPC metadata, transaction, and control-plane services have no authentication or TLS. \ - Default bind is 127.0.0.1. Do not expose this process to untrusted networks until \ - [security].shared_secret or an external TLS terminator is configured. \ - RaftTransport on the same listener requires the same bearer when the secret is set." + "gRPC and metrics listeners have no authentication and this process does not terminate TLS. \ + An empty shared_secret is accepted only for loopback binds. \ + A wildcard or other non-loopback address refuses to serve. \ + RaftTransport on this listener requires the same bearer when the secret is set." ); } let grpc_handle = @@ -670,6 +678,7 @@ impl PersistentMetaDbCluster { proxy_router, shutdown_tx, task_handles: tokio::sync::Mutex::new(vec![grpc_handle]), + metrics_addr: OnceLock::new(), }); // Background maintenance task (`AuxDispatcher` + `TxnRecoveryWorker` every 250ms). @@ -688,6 +697,38 @@ impl PersistentMetaDbCluster { }); cluster.task_handles.lock().await.push(bg_handle); + if let Some(metrics_listen) = cluster.config.node.metrics_listen_addr.clone() { + let metrics_listener = match TcpListener::bind(&metrics_listen).await { + Ok(listener) => listener, + Err(error) => { + let _ = cluster.shutdown().await; + return Err(error.into()); + } + }; + let metrics_bound = match metrics_listener.local_addr() { + Ok(addr) => addr.to_string(), + Err(error) => { + let _ = cluster.shutdown().await; + return Err(error.into()); + } + }; + let _ = cluster.metrics_addr.set(metrics_bound.clone()); + tracing::info!( + metrics_addr = %metrics_bound, + "Prometheus metrics endpoint listening" + ); + let metrics_cluster = Arc::downgrade(&cluster); + let metrics_secret = cluster.config.security.shared_secret.clone(); + let metrics_shutdown = cluster.shutdown_tx.subscribe(); + let metrics_handle = tokio::spawn(metrics_http::serve( + metrics_listener, + metrics_cluster, + metrics_secret, + metrics_shutdown, + )); + cluster.task_handles.lock().await.push(metrics_handle); + } + // Publish only after bootstrap or join has finished, so readers know the port is serving. std::fs::write( cluster.config().node.data_dir.join("GRPC_ADDR"), @@ -810,6 +851,11 @@ impl PersistentMetaDbCluster { collect_cluster_metrics(&self.global_manager) } + /// Bound Prometheus address, when `node.metrics_listen_addr` was set. + pub fn metrics_addr(&self) -> Option<&str> { + self.metrics_addr.get().map(String::as_str) + } + /// Gracefully stops gRPC/background loops, flushes all shard state to disk, and stops OpenRaft groups. pub async fn shutdown(&self) -> Result<()> { self.stop_tasks().await; diff --git a/crates/metadb-server/src/metrics_http.rs b/crates/metadb-server/src/metrics_http.rs new file mode 100644 index 0000000..b17fd0c --- /dev/null +++ b/crates/metadb-server/src/metrics_http.rs @@ -0,0 +1,134 @@ +//! Prometheus HTTP listener. Uses the same bearer as the gRPC services. + +use std::sync::Weak; +use std::time::Duration; + +use http_body_util::Full; +use hyper::body::{Bytes, Incoming}; +use hyper::server::conn::http1; +use hyper::service::service_fn; +use hyper::{Method, Request, Response, StatusCode}; +use hyper_util::rt::{TokioIo, TokioTimer}; +use tokio::net::{TcpListener, TcpStream}; +use tokio::sync::watch; +use tokio::task::JoinSet; + +use crate::bearer_header_matches; +use crate::render_prometheus_metrics; +use crate::PersistentMetaDbCluster; + +const METRICS_MAX_CONNECTIONS: usize = 64; +const METRICS_MAX_HEADER_BYTES: usize = 8192; +const METRICS_IO_TIMEOUT: Duration = Duration::from_secs(2); + +pub async fn serve( + listener: TcpListener, + cluster: Weak, + shared_secret: String, + mut shutdown: watch::Receiver, +) { + let mut connections = JoinSet::new(); + loop { + tokio::select! { + _ = shutdown.changed() => break, + Some(_) = connections.join_next(), if !connections.is_empty() => {}, + accepted = listener.accept(), if connections.len() < METRICS_MAX_CONNECTIONS => { + let Ok((socket, _)) = accepted else { break; }; + let cluster = cluster.clone(); + let shared_secret = shared_secret.clone(); + connections.spawn(async move { + let _ = tokio::time::timeout( + METRICS_IO_TIMEOUT, + metrics_connection(socket, cluster, shared_secret), + ) + .await; + }); + } + } + } + connections.abort_all(); + while connections.join_next().await.is_some() {} +} + +async fn metrics_connection( + socket: TcpStream, + cluster: Weak, + shared_secret: String, +) -> Result<(), hyper::Error> { + let service = service_fn(move |request: Request| { + let cluster = cluster.clone(); + let shared_secret = shared_secret.clone(); + async move { + let (status, body, prometheus) = metrics_decision(&request, &cluster, &shared_secret); + let mut response = Response::new(Full::new(Bytes::from(body))); + *response.status_mut() = status; + let content_type = if prometheus { + "text/plain; version=0.0.4" + } else { + "text/plain; charset=utf-8" + }; + response.headers_mut().insert( + hyper::header::CONTENT_TYPE, + hyper::header::HeaderValue::from_static(content_type), + ); + if status == StatusCode::UNAUTHORIZED { + response.headers_mut().insert( + hyper::header::WWW_AUTHENTICATE, + hyper::header::HeaderValue::from_static("Bearer"), + ); + } + response.headers_mut().insert( + hyper::header::CONNECTION, + hyper::header::HeaderValue::from_static("close"), + ); + Ok::<_, std::convert::Infallible>(response) + } + }); + http1::Builder::new() + .timer(TokioTimer::new()) + .header_read_timeout(METRICS_IO_TIMEOUT) + .max_headers(64) + .max_buf_size(METRICS_MAX_HEADER_BYTES) + .keep_alive(false) + .serve_connection(TokioIo::new(socket), service) + .await +} + +fn metrics_decision( + request: &Request, + cluster: &Weak, + shared_secret: &str, +) -> (StatusCode, String, bool) { + if !shared_secret.is_empty() { + let presented = request + .headers() + .get(hyper::header::AUTHORIZATION) + .and_then(|value| value.to_str().ok()) + .unwrap_or(""); + if !bearer_header_matches(presented, shared_secret) { + return (StatusCode::UNAUTHORIZED, "unauthorized\n".to_owned(), false); + } + } + if request.method() != Method::GET { + return ( + StatusCode::METHOD_NOT_ALLOWED, + "method not allowed\n".to_owned(), + false, + ); + } + if request.uri().path() != "/metrics" { + return (StatusCode::NOT_FOUND, "not found\n".to_owned(), false); + } + let Some(cluster) = cluster.upgrade() else { + return ( + StatusCode::SERVICE_UNAVAILABLE, + "unavailable\n".to_owned(), + false, + ); + }; + ( + StatusCode::OK, + render_prometheus_metrics(&cluster.metrics_snapshot()), + true, + ) +} diff --git a/crates/metadb-server/tests/auth_fail_closed.rs b/crates/metadb-server/tests/auth_fail_closed.rs new file mode 100644 index 0000000..78bde86 --- /dev/null +++ b/crates/metadb-server/tests/auth_fail_closed.rs @@ -0,0 +1,236 @@ +//! Fail-closed checks for missing, empty, and mismatched shared secrets. +//! +//! These tests only send a missing or wrong bearer and expect rejection, or they +//! expect startup to refuse a listener. They do not attempt to bypass authentication. + +use std::time::Duration; + +use metadb_proto::control_plane_service_client::ControlPlaneServiceClient; +use metadb_proto::metadata_service_client::MetadataServiceClient; +use metadb_proto::raft_transport_service_client::RaftTransportServiceClient; +use metadb_proto::{GetRoutesRequest, LookupRequest, RaftRpcEnvelope}; +use metadb_server::{PersistentMetaDbCluster, ServerTomlConfig}; +use tokio::io::{AsyncReadExt, AsyncWriteExt}; +use tokio::net::TcpStream; +use tonic::transport::Endpoint; +use tonic::Code; + +fn loopback_dial(bound: &str) -> String { + let port = bound.rsplit_once(':').expect("host:port").1; + format!("127.0.0.1:{port}") +} + +async fn expect_closed(addr: &str) { + let connected = TcpStream::connect(addr).await; + assert!( + connected.is_err(), + "listener {addr} accepted a connection after fail-closed startup" + ); +} + +async fn http_exchange(addr: &str, authorization: Option<&str>, path: &str) -> (u16, String) { + let mut socket = TcpStream::connect(addr).await.expect("metrics connect"); + let mut request = format!("GET {path} HTTP/1.1\r\nHost: localhost\r\nConnection: close\r\n"); + if let Some(value) = authorization { + request.push_str("Authorization: "); + request.push_str(value); + request.push_str("\r\n"); + } + request.push_str("\r\n"); + socket.write_all(request.as_bytes()).await.unwrap(); + let mut body = Vec::new(); + tokio::time::timeout(Duration::from_secs(2), socket.read_to_end(&mut body)) + .await + .expect("metrics response timed out") + .unwrap(); + let text = String::from_utf8_lossy(&body).into_owned(); + let status = text + .split_whitespace() + .nth(1) + .unwrap_or("0") + .parse() + .unwrap_or(0); + (status, text) +} + +fn assert_rejected_http(status: u16, body: &str) { + assert_eq!(status, 401, "{body}"); + assert!( + !body.contains("metadb_"), + "rejected metrics response included metric text: {body}" + ); + assert!( + !body.contains("test-secret"), + "rejected response echoed the configured secret" + ); +} + +#[tokio::test] +async fn wildcard_without_a_secret_does_not_listen() { + let probe = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap(); + let port = probe.local_addr().unwrap().port(); + drop(probe); + + let mut cfg = ServerTomlConfig::default(); + cfg.node.data_dir = std::env::temp_dir().join(format!("metadb-fail-closed-{port}")); + cfg.node.grpc_listen_addr = format!("0.0.0.0:{port}"); + cfg.security.shared_secret.clear(); + let err = match PersistentMetaDbCluster::open_and_serve(cfg).await { + Ok(_) => panic!("empty secret on a wildcard bind must fail closed"), + Err(err) => err, + }; + assert!(err.to_string().contains("refusing to serve"), "{err}"); + expect_closed(&format!("127.0.0.1:{port}")).await; + + let mut spaced = ServerTomlConfig::default(); + spaced.node.grpc_listen_addr = format!("0.0.0.0:{port}"); + spaced.security.shared_secret = " ".into(); + let spaced_err = match PersistentMetaDbCluster::open_and_serve(spaced).await { + Ok(_) => panic!("whitespace secret on a wildcard bind must fail closed"), + Err(err) => err, + }; + assert!( + spaced_err.to_string().contains("refusing to serve"), + "{spaced_err}" + ); + + let metrics_probe = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap(); + let metrics_port = metrics_probe.local_addr().unwrap().port(); + drop(metrics_probe); + let mut metrics = ServerTomlConfig::default(); + metrics.node.grpc_listen_addr = "127.0.0.1:0".into(); + metrics.node.metrics_listen_addr = Some(format!("0.0.0.0:{metrics_port}")); + let metrics_err = match PersistentMetaDbCluster::open_and_serve(metrics).await { + Ok(_) => panic!("wildcard metrics bind without a secret must fail closed"), + Err(err) => err, + }; + assert!( + metrics_err.to_string().contains("refusing to serve"), + "{metrics_err}" + ); + expect_closed(&format!("127.0.0.1:{metrics_port}")).await; +} + +#[tokio::test] +async fn misspelled_secret_and_tls_options_do_not_start() { + let typo = ServerTomlConfig::from_toml_str( + r#" + [node] + grpc_listen_addr = "0.0.0.0:7800" + [security] + shared_secrett = "not-the-field" + "#, + ); + assert!( + typo.unwrap_err().to_string().contains("refusing to start"), + "misspelled shared_secret must not parse into an open listener" + ); + + let tls = ServerTomlConfig::from_toml_str( + r#" + [node] + grpc_listen_addr = "127.0.0.1:7800" + tls_cert_file = "/tmp/cert.pem" + [security] + shared_secret = "secret" + "#, + ); + let tls_err = tls.unwrap_err().to_string(); + assert!(tls_err.contains("does not terminate TLS"), "{tls_err}"); +} + +#[tokio::test(flavor = "multi_thread", worker_threads = 4)] +async fn configured_secret_rejects_missing_and_wrong_credentials() { + let dir = tempfile::tempdir().unwrap(); + let mut cfg = ServerTomlConfig::default(); + cfg.node.data_dir = dir.path().to_path_buf(); + cfg.node.grpc_listen_addr = "0.0.0.0:0".into(); + cfg.node.metrics_listen_addr = Some("0.0.0.0:0".into()); + cfg.security.shared_secret = "test-secret".into(); + let (cluster, grpc_addr) = PersistentMetaDbCluster::open_and_serve(cfg).await.unwrap(); + let grpc_dial = loopback_dial(&grpc_addr); + let metrics_dial = loopback_dial(cluster.metrics_addr().expect("metrics listener")); + + let channel = Endpoint::from_shared(format!("http://{grpc_dial}")) + .unwrap() + .connect() + .await + .unwrap(); + + let mut status = ControlPlaneServiceClient::new(channel.clone()); + let missing_status = status.get_routes(GetRoutesRequest { cell_id: 0 }).await; + let mut empty_status_req = tonic::Request::new(GetRoutesRequest { cell_id: 0 }); + empty_status_req + .metadata_mut() + .insert("authorization", "Bearer ".parse().unwrap()); + let empty_status = status.get_routes(empty_status_req).await; + let mut typo_status_req = tonic::Request::new(GetRoutesRequest { cell_id: 0 }); + typo_status_req + .metadata_mut() + .insert("authorization", "Bearer test-secre".parse().unwrap()); + let typo_status = status.get_routes(typo_status_req).await; + + let mut metadata = MetadataServiceClient::new(channel.clone()); + let missing_lookup = metadata + .lookup(LookupRequest { + pid: 1, + name: "no-such-entry".into(), + ..Default::default() + }) + .await; + let mut wrong_lookup_req = tonic::Request::new(LookupRequest { + pid: 1, + name: "no-such-entry".into(), + ..Default::default() + }); + wrong_lookup_req + .metadata_mut() + .insert("authorization", "Bearer wrong-secret".parse().unwrap()); + let wrong_lookup = metadata.lookup(wrong_lookup_req).await; + + let mut raft = RaftTransportServiceClient::new(channel); + let missing_raft = raft + .vote(RaftRpcEnvelope { + shard_id: 99999, + bincode_payload: vec![], + }) + .await; + + let missing_metrics = http_exchange(&metrics_dial, None, "/metrics").await; + let empty_metrics = http_exchange(&metrics_dial, Some("Bearer "), "/metrics").await; + let wrong_metrics = http_exchange(&metrics_dial, Some("Bearer wrong-secret"), "/metrics").await; + let status_path = http_exchange(&metrics_dial, None, "/status").await; + let authed_metrics = http_exchange(&metrics_dial, Some("Bearer test-secret"), "/metrics").await; + + cluster.shutdown().await.unwrap(); + + for (name, result) in [ + ("cluster status missing", missing_status.map(|_| ())), + ("cluster status empty bearer", empty_status.map(|_| ())), + ("cluster status typo bearer", typo_status.map(|_| ())), + ("lookup missing", missing_lookup.map(|_| ())), + ("lookup wrong", wrong_lookup.map(|_| ())), + ("raft missing", missing_raft.map(|_| ())), + ] { + assert_eq!( + result.unwrap_err().code(), + Code::Unauthenticated, + "{name} was not rejected" + ); + } + assert_rejected_http(missing_metrics.0, &missing_metrics.1); + assert_rejected_http(empty_metrics.0, &empty_metrics.1); + assert_rejected_http(wrong_metrics.0, &wrong_metrics.1); + assert_rejected_http(status_path.0, &status_path.1); + assert_eq!(authed_metrics.0, 200, "{}", authed_metrics.1); + assert!( + authed_metrics.1.contains("text/plain; version=0.0.4"), + "authenticated scrape missing Prometheus content type: {}", + authed_metrics.1 + ); + assert!( + authed_metrics.1.contains("metadb_shards_total"), + "authenticated scrape missing metric text: {}", + authed_metrics.1 + ); +} diff --git a/crates/metadb-server/tests/e2e_cluster_evolution_tests.rs b/crates/metadb-server/tests/e2e_cluster_evolution_tests.rs index 6991ce6..903e064 100644 --- a/crates/metadb-server/tests/e2e_cluster_evolution_tests.rs +++ b/crates/metadb-server/tests/e2e_cluster_evolution_tests.rs @@ -171,31 +171,40 @@ shard_split_threshold_bytes = 2048 assert!(rename_resp.error.is_none()); let renamed_fid = rename_resp.entry.unwrap().attr.unwrap().fid; - // Run maintenance tick so `AuxDispatcher` drains Quota & SecondaryIndex updates! - cluster.run_maintenance_tick().await.unwrap(); - - let quota_resp = meta_client - .get_quota(GetQuotaRequest { - header: None, - uid: 50, - }) - .await - .unwrap() - .into_inner(); - assert!(quota_resp.found); - // 20 initial files - 1 overwritten file = 19 live files * 512 bytes! - assert_eq!(quota_resp.record.unwrap().used_bytes, 19 * 512); - - let idx_resp = meta_client - .get_secondary_index(GetSecondaryIndexRequest { - header: None, - fid: renamed_fid, - }) - .await - .unwrap() - .into_inner(); - assert!(idx_resp.found); - assert_eq!(idx_resp.record.unwrap().pid, dir_b_id); + // One aux propose can miss while the background drain is in flight. + // Retry until the overwrite delta is visible, then assert the final values. + let mut used_bytes = None; + let mut index_pid = None; + for _ in 0..8 { + cluster.run_maintenance_tick().await.unwrap(); + let quota_resp = meta_client + .get_quota(GetQuotaRequest { + header: None, + uid: 50, + }) + .await + .unwrap() + .into_inner(); + assert!(quota_resp.found); + used_bytes = quota_resp.record.map(|record| record.used_bytes); + let idx_resp = meta_client + .get_secondary_index(GetSecondaryIndexRequest { + header: None, + fid: renamed_fid, + }) + .await + .unwrap() + .into_inner(); + if idx_resp.found { + index_pid = idx_resp.record.map(|record| record.pid); + } + // 20 initial files - 1 overwritten file = 19 live files * 512 bytes. + if used_bytes == Some(19 * 512) && index_pid == Some(dir_b_id) { + break; + } + } + assert_eq!(used_bytes, Some(19 * 512)); + assert_eq!(index_pid, Some(dir_b_id)); // Consecutive bulk TTL deletion test on `dir_b_id`: create 25 TTL files, flush to L1, // delete 22 of them (`>= locality_tombstone_threshold = 20`), flush, and verify 0 tombstones! diff --git a/docs/de/architecture.md b/docs/de/architecture.md index 97b1962..e7e5b62 100644 --- a/docs/de/architecture.md +++ b/docs/de/architecture.md @@ -9,16 +9,16 @@ Diese Seite folgt dem Code in `crates/`. Sie beschreibt keinen Mehrprozess-Zelle `PersistentMetaDbCluster::open_and_serve` (`crates/metadb-server/src/lib.rs`): 1. Weist jedes `node.role` außer `all-in-one` zurück. -2. Bindet `node.grpc_listen_addr` (Vorgabe `127.0.0.1:7800`; `127.0.0.1:0` lässt das Betriebssystem einen Port wählen). +2. Weist eine Wildcard oder eine andere Nicht-Loopback-Adresse in `grpc_listen_addr` oder `metrics_listen_addr` zurück, wenn `shared_secret` leer ist. Bindet danach `node.grpc_listen_addr` (Vorgabe `127.0.0.1:7800`; `127.0.0.1:0` lässt das Betriebssystem einen Port wählen). 3. Öffnet `DurableIdAllocator` unter `/global_allocator`. 4. Öffnet `ShardGroupHost` unter `/be`. 5. Öffnet oder bootstrapt `DurableCellManager` unter `/cell_`. 6. Registriert diese eine Zelle bei `DurableGlobalManager` für den Schlüsselbereich `[0x01, 0x04)`. 7. Stellt sicher, dass Wurzel-Inode `1` (`ROOT_INODE_ID`) einen Attributsatz hat. -8. Bedient vier gRPC-Dienste auf demselben Listener. Alle vier nehmen denselben optionalen Bearer-Interceptor. Ein leeres Geheimnis lässt jeden Aufruf zu. +8. Bedient vier gRPC-Dienste auf demselben Listener. Alle vier nehmen denselben Bearer-Interceptor. Wenn `metrics_listen_addr` gesetzt ist, verlangt `GET /metrics` auf dieser Adresse dasselbe Geheimnis. Ein nicht leeres Geheimnis weist einen fehlenden oder falschen Bearer zurück. Ein leeres Geheimnis wird nur für Loopback-Binds akzeptiert. Dieser Prozess beendet TLS nicht. 9. Startet eine Wartungsaufgabe im Abstand von 250 ms. -`metadbd` ist eine dünne Hülle: Es lädt TOML, wendet CLI-Überschreibungen an, ruft `open_and_serve` auf, ruft optional `RegisterNode` an `--cell-manager` auf, liefert optional Prometheus-Text und ruft bei Strg-C `shutdown` auf. +`metadbd` ist eine dünne Hülle: Es lädt TOML, wendet CLI-Überschreibungen an, ruft `open_and_serve` auf, ruft optional `RegisterNode` an `--cell-manager` auf und ruft bei Strg-C `shutdown` auf. Metriken werden, wenn konfiguriert, in `open_and_serve` bedient. ## Schlüssel und Tabellen diff --git a/docs/de/build-and-run.md b/docs/de/build-and-run.md index c035204..d3bc38c 100644 --- a/docs/de/build-and-run.md +++ b/docs/de/build-and-run.md @@ -64,7 +64,7 @@ cargo run -p metadb-server --bin metadbd -- --config ./standalone.toml Logs verwenden den `EnvFilter` von `tracing-subscriber`. Der Standardfilter ist `info`. Überschreiben mit der üblichen Variable `RUST_LOG`, zum Beispiel `RUST_LOG=debug`. -Beim Start mit leerem `security.shared_secret` schreibt der Prozess eine Warnung, dass gRPC keine Authentifizierung und kein TLS hat. Die Standardbindung ist `127.0.0.1`. Diesen Socket nicht in ein nicht vertrauenswürdiges Netz stellen. Ein nicht leeres `[security].shared_secret` verlangt denselben Bearer für Metadaten-, Transaktions-, Control-Plane- und Raft-Transport-RPCs. Der Prozess beendet TLS weiterhin nicht. Den Listener in einem vertrauenswürdigen Netz lassen, oder jeden Dienst hinter einen Proxy setzen, der Clients authentifiziert, und den direkten Zugriff auf diesen Prozess sperren. +Beim Start mit leerem `security.shared_secret` schreibt der Prozess eine Warnung, dass Loopback-gRPC keine Authentifizierung hat. Die Standardbindung ist `127.0.0.1`. Eine Wildcard oder eine andere Nicht-Loopback-Adresse mit leerem, fehlendem oder falsch geschriebenem Geheimnis verweigert das Binden. Ein nicht leeres `[security].shared_secret` verlangt denselben Bearer für Metadaten-, Transaktions-, Control-Plane- und Raft-Transport-RPCs sowie für `GET /metrics`. Der Prozess beendet TLS nicht. Ein TLS- oder Zertifikatsschlüssel in der Konfiguration lässt den Start fehlschlagen, statt Klartext zu dienen. Den Listener in einem vertrauenswürdigen Netz lassen, oder jeden Dienst hinter einen Proxy setzen, der Clients authentifiziert, und den direkten Zugriff auf diesen Prozess sperren. Strg-C schreibt den Shard-Zustand und stoppt die OpenRaft-Gruppen (`cluster.shutdown()`). diff --git a/docs/de/configuration.md b/docs/de/configuration.md index 5e6533e..af567b0 100644 --- a/docs/de/configuration.md +++ b/docs/de/configuration.md @@ -2,7 +2,7 @@ [Überblick](./README.md) · [English](../en/configuration.md) · [Français](../fr/configuration.md) · [日本語](../ja/configuration.md) · [简体中文](../zh/configuration.md) -`metadbd --config` und `ServerTomlConfig::from_toml_file` / `from_toml_str` lesen TOML (`crates/metadb-server/src/config.rs`). Unbekannte Schlüssel werden ignoriert. Die Strukturen verwenden `#[serde(default)]` und setzen `deny_unknown_fields` nicht, und `from_toml_str` ruft `toml::from_str` direkt auf. Ein falsch geschriebener Schlüssel behält seine Vorgabe, auch ein leeres `security.shared_secret`, und der Start gelingt trotzdem. Jeder Abschnitt ist optional. Ausgelassene Felder nehmen die Vorgaben unten an. +`metadbd --config` und `ServerTomlConfig::from_toml_file` / `from_toml_str` lesen TOML (`crates/metadb-server/src/config.rs`). Unbekannte Schlüssel, die kein Geheimnis und kein TLS benennen, werden ignoriert. Ein falsch geschriebenes `shared_secret`, ein Token- oder Passwortschlüssel oder ein TLS- oder Zertifikatsschlüssel wird abgelehnt, und der Prozess startet nicht. Jeder bekannte Abschnitt ist optional. Ausgelassene Felder nehmen die Vorgaben unten an. ## Vorgaben @@ -13,7 +13,7 @@ | `node.role` | `all-in-one` | Ja. Jeder andere Wert liefert einen Fehler | | `node.data_dir` | `./metadb-data` | Ja | | `node.grpc_listen_addr` | `127.0.0.1:7800` | Ja. Bind-Adresse | -| `node.metrics_listen_addr` | nicht gesetzt | Ja, nur wenn gesetzt. `metadbd` bindet einen eigenen TCP-Listener | +| `node.metrics_listen_addr` | nicht gesetzt | Ja, nur wenn gesetzt. Eigener TCP-Listener. Eine Nicht-Loopback-Adresse verlangt ein nicht leeres Geheimnis | | `clock.max_clock_drift_ms` | `500` | Ja. `HybridLogicalClock::with_max_drift_ms` | | `storage.memtable_size_bytes` | `33554432` (32 MiB) | **Nein.** Das Feld wird gespeichert und nie gelesen | | `storage.block_cache_bytes` | `67108864` (64 MiB) | Ja. Gesamtbudget des 16-fachen Blockcaches | @@ -23,7 +23,7 @@ | `storage.locality_tombstone_ratio` | `0.50` | Ja. Mal 1000, auf 1..=1000 begrenzt, gespeichert als `tombstone_min_ratio_permille` | | `sharding.bootstrap_table_shards` | `true` | Ja. `true` erzeugt die Shards 1, 2 und 3. `false` erzeugt Shard 1 über `[0x01, 0x04)` | | `sharding.shard_split_threshold_bytes` | `4294967296` (4 GiB) | Ja. Die Split-Prüfung nutzt die ungefähre Shard-Größe | -| `security.shared_secret` | `""` | Ja. Leer heißt: Metadaten-, Transaktions- und Control-Plane-RPCs sind unauthentifiziert | +| `security.shared_secret` | `""` | Ja. Leer ist nur zulässig, wenn jeder Listener Loopback ist. Nicht leer verlangt denselben Bearer für gRPC und Metriken | Es gibt keine Tabelle `[raft]`. `ServerTomlConfig.raft_options` wird von serde übersprungen und bleibt bei `RaftNodeOptions::default()` (Heartbeat 150 ms, Wahl 450–900 ms, Snapshot-Log-Behalten 0, Segment 64 MiB). @@ -67,13 +67,11 @@ CLI-Flags überschreiben die Datei nach dem Einlesen: `--node-id`, `--cell-id`, ## Sicherheit -Der Prozess beendet TLS nicht. +Dieser Prozess beendet TLS nicht. Es gibt keine Zertifikatskonfiguration, die natives TLS einschaltet. Ein TLS-, SSL- oder Zertifikatsschlüssel in der Datei lässt das Parsen fehlschlagen, und der Prozess dient nicht im Klartext. TLS in einem externen Proxy beenden und keinen TLS-Schlüssel in dieser Datei lassen. -Wenn `shared_secret` nicht leer ist, verlangen `MetadataService`, `TransactionService` und `ControlPlaneService`, dass der Metadatenwert `authorization` gleich `Bearer ` ist. `metadb-ctl --auth-token` (Umgebungsvariable `METADB_AUTH_TOKEN`) sendet diesen Header. `metadbd --cell-manager` sendet dasselbe Geheimnis, wenn es `RegisterNode` aufruft. +Wenn `shared_secret` nicht leer ist, verlangen `MetadataService`, `TransactionService`, `ControlPlaneService` und `RaftTransportService`, dass `authorization` genau `Bearer ` ist. `GET /metrics` auf `metrics_listen_addr` verlangt denselben `Authorization`-Header. Ein fehlender Header, ein leerer Bearer, ein Präfix oder ein längerer Token wird abgelehnt. Der Fehlerkörper der Metriken ist kein Prometheus-Text. Raft-Peers senden denselben Bearer. `metadb-ctl --auth-token` (Umgebungsvariable `METADB_AUTH_TOKEN`) und `metadbd --join` / `--cell-manager` senden ihn. `metadb-ctl cluster status` ruft `GetRoutes` auf und liegt unter demselben Interceptor. -`RaftTransportService` verwendet denselben Interceptor. Ein nicht leeres Geheimnis verlangt auch für Raft-RPCs auf diesem Port `Bearer `. - -Ein leeres Geheimnis lässt alle vier Dienste auf dem Listener zu. Der Code warnt beim Start davor. Der Prozess beendet TLS weiterhin nicht. Bevor ein nicht vertrauenswürdiger Client den Port erreichen kann, die Bindung auf einem vertrauenswürdigen Netz wie `127.0.0.1` lassen, oder jeden Dienst hinter einen Proxy setzen, der den Client authentifiziert (zum Beispiel gegenseitiges TLS), und den direkten Zugriff auf diesen Prozess sperren. +Ein leeres oder nur aus Leerzeichen bestehendes Geheimnis ist nur zulässig, wenn `grpc_listen_addr` und, falls gesetzt, `metrics_listen_addr` Loopback sind (`127.0.0.0/8`, `::1` oder der Name `localhost`). Eine Wildcard (`0.0.0.0`, `::`) oder jede andere Adresse verweigert das Binden. Ein leeres Loopback-Geheimnis wird beim Start gewarnt. Die Listener bleiben Klartext. Sie in einem vertrauenswürdigen Netz lassen, oder jeden Dienst hinter einen Proxy setzen, der den Client authentifiziert, und den direkten Zugriff auf diesen Prozess sperren. ## Was sich nicht konfigurieren lässt @@ -81,4 +79,4 @@ Ein leeres Geheimnis lässt alle vier Dienste auf dem Listener zu. Der Code warn - Peer-Listen, Wählermengen oder ein Join-Token. Die Membership beginnt als dieser eine Prozess. Weitere Peers erscheinen erst nach `RegisterNode` plus `ScaleShardReplicas`, und diese Peers müssen bereits Raft-Mitglieder sein, die `RaftTransportService` für dieselben Shard-Logs sprechen. Ein zweiter all-in-one-Prozess tut das nicht. Siehe [Betrieb](./operations.md). - Den Schlüsselbereich einer zweiten Zelle. `RegisterCell` liefert einen Fehler und speichert nichts. Ein zweiter all-in-one-Prozess mit leerem Verzeichnis tritt dem aktuellen Leader mit `[cluster] join` bei; das bleibt dieselbe Zelle. - Memtable-Bytegrenze, Raft-Zeitgeber oder Locality-Compaction an/aus. -- TLS-Zertifikate. +- Native TLS-Zertifikate. Ein TLS-Schlüssel in dieser Datei wird abgelehnt. Die Terminierung gehört in einen externen Proxy. diff --git a/docs/de/operations.md b/docs/de/operations.md index 37ace8c..3d9a32a 100644 --- a/docs/de/operations.md +++ b/docs/de/operations.md @@ -71,7 +71,7 @@ Siehe [Tests und Benches](./testing.md#metadb-ctl-bench). Das ist ein Client geg ## Metriken -`node.metrics_listen_addr` setzen (zum Beispiel `127.0.0.1:9100`). `metadbd` nimmt TCP-Verbindungen an und schreibt ein einzelnes HTTP `200`, dessen Rumpf Prometheus-Text ist. Es routet nicht nach URL-Pfad. Jede Anfrage erhält denselben Rumpf. +`node.metrics_listen_addr` setzen (zum Beispiel `127.0.0.1:9100`). `open_and_serve` nimmt auf dieser Adresse TCP-Verbindungen an. `GET /metrics` liefert Prometheus-Text. Jeder andere Pfad liefert 404, jede andere Methode 405. Wenn `[security].shared_secret` nicht leer ist, muss jede Anfrage auf diesem Listener `Authorization: Bearer ` senden. Ein fehlender, leerer oder falscher Bearer liefert HTTP 401 und einen Rumpf, der nicht der Metriktext ist, auch für `/status`. Eine Nicht-Loopback-Metrikadresse mit leerem Geheimnis verweigert den Start. Dieser Listener beendet TLS nicht. Gauges und Counter aus `render_prometheus_metrics`: @@ -135,7 +135,7 @@ Die Varianten sind in `crates/metadb-core/src/error.rs` definiert. gRPC-Methoden - `GetRoutes` scheitert geschlossen bei einer unbekannten `cell_id` ungleich null. `StoreHeartbeat` ersetzt zwischengespeicherte Routen nicht. - Jumbo-Isolation ist ein Routenflag plus eine Knotenkennung aus der lokalen Knotentabelle. Sie verdrängt andere Shards nicht von einer Platte. - Heartbeats sind ein RPC ohne Sender in `metadbd`. `StoreHeartbeat` speichert nicht dauerhaft. -- Ein nicht leeres gemeinsames Geheimnis authentifiziert Raft auf dem öffentlichen gRPC-Port mit demselben Bearer wie die drei anderen Dienste. Ein leeres Geheimnis lässt Raft unauthentifiziert. Der Prozess beendet TLS nicht. +- Ein nicht leeres gemeinsames Geheimnis authentifiziert Raft, die drei anderen gRPC-Dienste und den Metrik-Listener mit demselben Bearer. Ein leeres Geheimnis wird nur für Loopback-Binds akzeptiert und lässt diese Listener unauthentifiziert. Ein Wildcard-Bind mit leerem Geheimnis verweigert den Start. Der Prozess beendet TLS nicht. - `memtable_size_bytes` und alle Raft-Zeitgeberfelder ändern das Laufzeitverhalten über TOML nicht. - `metadb-ctl bench` für `hotspot-create` und `bulk-ttl-delete` druckt JSON-Zeilen: einen Kopf mit `bench_pid`, dann Phasenberichte mit attempted, succeeded, failed und Latenzperzentilen. Der Prozess endet mit einem Fehler, wenn nicht jede angeforderte Operation gelingt. `--workload mixed` oder `--embedded` startet den prozessinternen Stress-Harness. `sql` druckt die Antwort als JSON und endet bei einem Anwendungsfehler mit einem Fehlerstatus. @@ -147,6 +147,6 @@ Diese Punkte fehlen im Produkt, daher kann dieser Leitfaden kein Verfahren dafü 2. Einen zweiten und dritten `metadbd`-Betriebssystemprozess einer bestehenden Raft-Gruppe hinzufügen. 3. Eine zweite Zelle anlegen und dorthin routen. 4. Einen Jumbo-Shard auf eine eigene Maschine legen und andere Shards von dieser Maschine wegziehen. -5. TLS-Material, Raft-Authentifizierung und eine heartbeat-getriebene Steuerschleife. +5. Natives TLS. Dieser Prozess beendet TLS nicht. Konfigurationsschlüssel, die TLS oder ein Zertifikat verlangen, werden abgelehnt, statt Klartext zu dienen. Die Terminierung gehört in einen externen Proxy. Raft und Metriken nutzen denselben Bearer wie die anderen Dienste, wenn ein Geheimnis gesetzt ist; das ist kein gegenseitiges TLS. Eine heartbeat-getriebene Steuerschleife ist nicht implementiert. 6. Eine Memtable-Größe oder einen Raft-Zeitgeber, den der Betrieb setzen und beobachten kann. 7. Ein eingechecktes Ergebnis auf Dienstebene für `metadb-ctl bench`. Der Befehl druckt Zahlen für die Maschine, auf der man ihn ausführt. Dieses Repository zeichnet keine auf. Der nicht zusammengeführte Pull Request 2 berichtet einen eigenen eingebetteten Harness; diese Befehle sind nicht in diesem Baum. Siehe [Tests und Benches](./testing.md). diff --git a/docs/en/architecture.md b/docs/en/architecture.md index 5ae865f..013fb2e 100644 --- a/docs/en/architecture.md +++ b/docs/en/architecture.md @@ -9,16 +9,16 @@ This page follows the code in `crates/`. It does not describe a multi-process Ce `PersistentMetaDbCluster::open_and_serve` (`crates/metadb-server/src/lib.rs`): 1. Rejects any `node.role` other than `all-in-one`. -2. Binds `node.grpc_listen_addr` (default `127.0.0.1:7800`; `127.0.0.1:0` asks the OS for a port). +2. Refuses a wildcard or other non-loopback `grpc_listen_addr` or `metrics_listen_addr` when `shared_secret` is empty. Then binds `node.grpc_listen_addr` (default `127.0.0.1:7800`; `127.0.0.1:0` asks the OS for a port). 3. Opens `DurableIdAllocator` at `/global_allocator`. 4. Opens `ShardGroupHost` at `/be`. 5. Opens or bootstraps `DurableCellManager` at `/cell_`. 6. Registers that one cell on `DurableGlobalManager` for the key range `[0x01, 0x04)`. 7. Ensures root directory inode `1` (`ROOT_INODE_ID`) has an attribute record. -8. Serves four gRPC services on the same listener. All four take the same optional bearer interceptor. An empty secret allows every call. +8. Serves four gRPC services on the same listener. All four take the same bearer interceptor. When `metrics_listen_addr` is set, `GET /metrics` on that address requires the same secret. A non-empty secret rejects a missing or wrong bearer. An empty secret is accepted only for loopback binds. This process does not terminate TLS. 9. Spawns a maintenance task on a 250 ms interval. -`metadbd` is a thin wrapper: it loads TOML, applies CLI overrides, calls `open_and_serve`, optionally calls `RegisterNode` on `--cell-manager`, optionally serves Prometheus text, and on Ctrl-C calls `shutdown`. +`metadbd` is a thin wrapper: it loads TOML, applies CLI overrides, calls `open_and_serve`, optionally calls `RegisterNode` on `--cell-manager`, and on Ctrl-C calls `shutdown`. Metrics, when configured, are served inside `open_and_serve`. ## Keys and tables diff --git a/docs/en/build-and-run.md b/docs/en/build-and-run.md index 911255d..8b5b580 100644 --- a/docs/en/build-and-run.md +++ b/docs/en/build-and-run.md @@ -64,7 +64,7 @@ cargo run -p metadb-server --bin metadbd -- --config ./standalone.toml Logs use `tracing-subscriber`'s `EnvFilter`. The default filter is `info`. Override it with the standard `RUST_LOG` variable, for example `RUST_LOG=debug`. -On startup with an empty `security.shared_secret`, the process logs a warning that gRPC has no authentication and no TLS. The default bind is `127.0.0.1`. Do not publish that socket on an untrusted network. A non-empty `[security].shared_secret` requires the same bearer on metadata, transaction, control-plane, and Raft transport RPCs. The process still does not terminate TLS. Keep the listener on a trusted network, or put every service behind a proxy that authenticates clients and block direct access to this process. +On startup with an empty `security.shared_secret`, the process logs a warning that loopback gRPC has no authentication. The default bind is `127.0.0.1`. A wildcard or other non-loopback address with an empty, missing, or misspelled secret refuses to listen. A non-empty `[security].shared_secret` requires the same bearer on metadata, transaction, control-plane, Raft transport, and `GET /metrics`. The process does not terminate TLS. A TLS or certificate key in the config fails startup instead of serving plaintext. Keep the listener on a trusted network, or put every service behind a proxy that authenticates clients and block direct access to this process. Ctrl-C flushes shard state and stops the OpenRaft groups (`cluster.shutdown()`). diff --git a/docs/en/configuration.md b/docs/en/configuration.md index 42f3cb9..58ada6f 100644 --- a/docs/en/configuration.md +++ b/docs/en/configuration.md @@ -2,7 +2,7 @@ [Overview](./README.md) · [Français](../fr/configuration.md) · [Deutsch](../de/configuration.md) · [日本語](../ja/configuration.md) · [简体中文](../zh/configuration.md) -`metadbd --config` and `ServerTomlConfig::from_toml_file` / `from_toml_str` read TOML (`crates/metadb-server/src/config.rs`). Unknown keys are ignored. The structs use `#[serde(default)]` and do not set `deny_unknown_fields`, and `from_toml_str` calls `toml::from_str` directly. A misspelled key keeps its default, including an empty `security.shared_secret`, and startup still succeeds. Every section is optional. Omitted fields take the defaults below. +`metadbd --config` and `ServerTomlConfig::from_toml_file` / `from_toml_str` read TOML (`crates/metadb-server/src/config.rs`). Unknown keys that do not name a secret or TLS setting are ignored. A misspelled `shared_secret`, a token or password key, or any TLS or certificate key is rejected and startup does not proceed, including those keys nested in tables or arrays. `[security].shared_secret` is accepted only as a direct key of the root `[security]` table. Every known section is optional. Omitted fields take the defaults below. ## Defaults @@ -13,7 +13,7 @@ | `node.role` | `all-in-one` | Yes. Any other value returns an error | | `node.data_dir` | `./metadb-data` | Yes | | `node.grpc_listen_addr` | `127.0.0.1:7800` | Yes. Bind address | -| `node.metrics_listen_addr` | unset | Yes, only when set. `metadbd` binds a separate TCP listener | +| `node.metrics_listen_addr` | unset | Yes, only when set. Separate TCP listener. A non-loopback address requires a non-empty secret | | `clock.max_clock_drift_ms` | `500` | Yes. `HybridLogicalClock::with_max_drift_ms` | | `storage.memtable_size_bytes` | `33554432` (32 MiB) | **No.** The field is stored and never read | | `storage.block_cache_bytes` | `67108864` (64 MiB) | Yes. Total budget of the 16-way block cache | @@ -23,7 +23,7 @@ | `storage.locality_tombstone_ratio` | `0.50` | Yes. Multiplied by 1000, clamped to 1..=1000, stored as `tombstone_min_ratio_permille` | | `sharding.bootstrap_table_shards` | `true` | Yes. `true` creates shards 1, 2, and 3. `false` creates shard 1 over `[0x01, 0x04)` | | `sharding.shard_split_threshold_bytes` | `4294967296` (4 GiB) | Yes. Split check uses approximate shard size | -| `security.shared_secret` | `""` | Yes. Empty means all four gRPC services on this listener are unauthenticated | +| `security.shared_secret` | `""` | Yes. Empty is accepted only for loopback listeners. Non-empty requires the same bearer on gRPC and metrics | There is no `[raft]` table. `ServerTomlConfig.raft_options` is skipped by serde and stays at `RaftNodeOptions::default()` (heartbeat 150 ms, election 450–900 ms, snapshot log keep 0, segment 64 MiB). @@ -67,11 +67,11 @@ CLI flags override the file after it is parsed: `--node-id`, `--cell-id`, `--rol ## Security -The process does not terminate TLS. +This process does not terminate TLS. There is no certificate configuration that turns on native TLS. If the file contains a TLS, SSL, or certificate key, parsing fails and the process does not serve plaintext. Terminate TLS in an external proxy, and do not leave a TLS key in this file. -When `shared_secret` is non-empty, `MetadataService`, `TransactionService`, `ControlPlaneService`, and `RaftTransportService` require `authorization` to equal `Bearer ` exactly. Raft peers send the same bearer. `metadb-ctl --auth-token` (environment variable `METADB_AUTH_TOKEN`) and `metadbd --join` / `--cell-manager` send it. A prefix or a longer token is rejected. An empty secret leaves all four services unauthenticated. +When `shared_secret` is non-empty, `MetadataService`, `TransactionService`, `ControlPlaneService`, and `RaftTransportService` require `authorization` to equal `Bearer ` exactly. `GET /metrics` on `metrics_listen_addr` requires the same `Authorization` header. A missing header, an empty bearer, a prefix, or a longer token is rejected. The metrics failure body is not Prometheus text. Raft peers send the same bearer. `metadb-ctl --auth-token` (environment variable `METADB_AUTH_TOKEN`) and `metadbd --join` / `--cell-manager` send it. `metadb-ctl cluster status` calls `GetRoutes` and is covered by that interceptor. -An empty secret allows every RPC on the listener. The code warns about this at startup. The process still does not terminate TLS. Before an untrusted client can reach the port, keep the bind on a trusted network such as `127.0.0.1`, or put every service behind a proxy that authenticates the client (for example mutual TLS) and block direct access to this process. +An empty or whitespace-only secret is accepted only when `grpc_listen_addr` and `metrics_listen_addr` (if set) are loopback (`127.0.0.0/8`, `::1`, or the name `localhost`). A wildcard (`0.0.0.0`, `::`) or any other address refuses to listen. The code warns about an empty loopback secret at startup. The listeners are still plaintext. Keep them on a trusted network, or put every service behind a proxy that authenticates the client and block direct access to this process. ## What you cannot configure @@ -79,4 +79,4 @@ An empty secret allows every RPC on the listener. The code warns about this at s - A voter list in TOML. The first process bootstraps alone. A later all-in-one process joins with `[cluster] join = "host:port"` (or `--join` / `--cell-manager`) pointing at the current leader, and only when its data directory does not already own a cell. The leader must be reached directly; a follower does not forward the membership change. That join is the same cell, not a second cell. See [Operations](./operations.md). - A second cell's key range. `RegisterCell` returns an error and stores nothing. - Memtable byte limit, Raft timers, or locality-compaction on/off. -- TLS certificates. +- Native TLS certificates. A TLS key in this file is rejected. Termination belongs in an external proxy. diff --git a/docs/en/operations.md b/docs/en/operations.md index ec33a9c..b8bf633 100644 --- a/docs/en/operations.md +++ b/docs/en/operations.md @@ -71,7 +71,7 @@ See [Tests and benches](./testing.md#metadb-ctl-bench). This is a client against ## Metrics -Set `node.metrics_listen_addr` (for example `127.0.0.1:9100`). `metadbd` accepts TCP connections and writes a single HTTP `200` whose body is Prometheus text. It does not route on the URL path. Any request receives the same body. +Set `node.metrics_listen_addr` (for example `127.0.0.1:9100`). `open_and_serve` accepts TCP connections on that address. `GET /metrics` returns Prometheus text. Any other path returns 404, and any other method returns 405. When `[security].shared_secret` is non-empty, every request on this listener must send `Authorization: Bearer `. A missing, empty, or wrong bearer returns HTTP 401 and a body that is not the metric text, including a request for `/status`. A non-loopback metrics address with an empty secret refuses to start. This listener does not terminate TLS. Gauges and counters from `render_prometheus_metrics`: @@ -138,7 +138,7 @@ Variants are defined in `crates/metadb-core/src/error.rs`. gRPC methods usually - Quota cursor rows are written after the outbox lock is released, so a flush that already holds the memtable lock can still take the outbox lock. - Jumbo isolation is a route flag plus a node id chosen from the local node map. It does not evict other shards from a disk. - Heartbeats are an RPC with no sender in `metadbd`. `StoreHeartbeat` does not persist. -- A non-empty shared secret authenticates Raft on the public gRPC port with the same bearer as the other three services. An empty secret leaves Raft unauthenticated. The process does not terminate TLS. +- A non-empty shared secret authenticates Raft, the other three gRPC services, and the metrics listener with the same bearer. An empty secret is accepted only for loopback binds and leaves those listeners unauthenticated. A wildcard bind with an empty secret refuses to start. The process does not terminate TLS. - `memtable_size_bytes` and all Raft timer fields do not change runtime behavior through TOML. - `metadb-ctl bench` for `hotspot-create` and `bulk-ttl-delete` prints JSON lines: a header with `bench_pid`, then phase reports with attempted, succeeded, failed, and latency percentiles. The process exits non-zero unless every requested operation succeeds. `--workload mixed` or `--embedded` runs the in-process stress harness. `sql` prints the response as JSON and exits non-zero on an application error. @@ -149,6 +149,6 @@ These items are missing from the product, so this guide cannot describe a proced 1. A multi-process layout for `be`, `proxy`, `cell-manager`, and `global-manager`. 2. A second Cell. `RegisterCell` stays an error. Join reaches only the current leader; a follower does not forward it. 3. Placing a jumbo shard on its own machine and moving other shards off that machine. -4. TLS material, Raft authentication, and a heartbeat-driven control loop. +4. Native TLS. This process does not terminate TLS. Config keys that ask for TLS or a certificate are rejected instead of serving plaintext. Put termination in an external proxy. Raft and metrics use the same bearer as the other services when a secret is set; that bearer is not mutual TLS. A heartbeat-driven control loop is not implemented. 5. A memtable size or Raft timer that operators can set and observe. 6. A checked-in service-level result for `metadb-ctl bench`. The command prints numbers for the machine you run it on. This repository does not record one. See [Tests and benches](./testing.md). diff --git a/docs/fr/architecture.md b/docs/fr/architecture.md index 8526b96..eb7068e 100644 --- a/docs/fr/architecture.md +++ b/docs/fr/architecture.md @@ -9,16 +9,16 @@ Cette page suit le code de `crates/`. Elle ne décrit pas un déploiement de cel `PersistentMetaDbCluster::open_and_serve` (`crates/metadb-server/src/lib.rs`) : 1. Rejette tout `node.role` autre que `all-in-one`. -2. Lie `node.grpc_listen_addr` (défaut `127.0.0.1:7800` ; `127.0.0.1:0` demande un port au système). +2. Refuse un joker ou une autre adresse non locale dans `grpc_listen_addr` ou `metrics_listen_addr` lorsque `shared_secret` est vide. Lie ensuite `node.grpc_listen_addr` (défaut `127.0.0.1:7800` ; `127.0.0.1:0` demande un port au système). 3. Ouvre `DurableIdAllocator` dans `/global_allocator`. 4. Ouvre `ShardGroupHost` dans `/be`. 5. Ouvre ou amorce `DurableCellManager` dans `/cell_`. 6. Enregistre cette unique cellule sur `DurableGlobalManager` pour l'intervalle de clés `[0x01, 0x04)`. 7. Garantit que l'inode racine `1` (`ROOT_INODE_ID`) possède un enregistrement d'attributs. -8. Sert quatre services gRPC sur le même écouteur. Les quatre prennent le même intercepteur bearer facultatif. Un secret vide autorise chaque appel. +8. Sert quatre services gRPC sur le même écouteur. Les quatre prennent le même intercepteur bearer. Lorsque `metrics_listen_addr` est défini, `GET /metrics` sur cette adresse exige le même secret. Un secret non vide rejette un bearer absent ou incorrect. Un secret vide n'est accepté que pour les liaisons en boucle locale. Ce processus ne termine pas TLS. 9. Lance une tâche de maintenance toutes les 250 ms. -`metadbd` est une fine enveloppe : il charge le TOML, applique les remplacements CLI, appelle `open_and_serve`, appelle éventuellement `RegisterNode` sur `--cell-manager`, sert éventuellement le texte Prometheus, et sur Ctrl-C appelle `shutdown`. +`metadbd` est une fine enveloppe : il charge le TOML, applique les remplacements CLI, appelle `open_and_serve`, appelle éventuellement `RegisterNode` sur `--cell-manager`, et sur Ctrl-C appelle `shutdown`. Les métriques, lorsqu'elles sont configurées, sont servies dans `open_and_serve`. ## Clés et tables diff --git a/docs/fr/build-and-run.md b/docs/fr/build-and-run.md index 93c149f..b14c73a 100644 --- a/docs/fr/build-and-run.md +++ b/docs/fr/build-and-run.md @@ -64,7 +64,7 @@ cargo run -p metadb-server --bin metadbd -- --config ./standalone.toml Les journaux utilisent l'`EnvFilter` de `tracing-subscriber`. Le filtre par défaut est `info`. On le remplace avec la variable standard `RUST_LOG`, par exemple `RUST_LOG=debug`. -Au démarrage, si `security.shared_secret` est vide, le processus journalise un avertissement : gRPC n'a ni authentification ni TLS. La liaison par défaut est `127.0.0.1`. Ne pas publier cette socket sur un réseau non fiable. Un `[security].shared_secret` non vide exige le même bearer pour les RPC de métadonnées, de transaction, de plan de contrôle et de transport Raft. Le processus ne termine toujours pas TLS. Garder l'écouteur sur un réseau de confiance, ou placer chaque service derrière un proxy qui authentifie les clients, et bloquer l'accès direct à ce processus. +Au démarrage, si `security.shared_secret` est vide, le processus journalise un avertissement : le gRPC en boucle locale n'a pas d'authentification. La liaison par défaut est `127.0.0.1`. Un joker ou une autre adresse non locale avec un secret vide, absent ou mal orthographié refuse d'écouter. Un `[security].shared_secret` non vide exige le même bearer pour les RPC de métadonnées, de transaction, de plan de contrôle, de transport Raft, et pour `GET /metrics`. Le processus ne termine pas TLS. Une clé TLS ou de certificat dans la configuration fait échouer le démarrage au lieu de servir en clair. Garder l'écouteur sur un réseau de confiance, ou placer chaque service derrière un proxy qui authentifie les clients, et bloquer l'accès direct à ce processus. Ctrl-C vide l'état des shards et arrête les groupes OpenRaft (`cluster.shutdown()`). diff --git a/docs/fr/configuration.md b/docs/fr/configuration.md index 68c6a7f..a5e7851 100644 --- a/docs/fr/configuration.md +++ b/docs/fr/configuration.md @@ -2,7 +2,7 @@ [Présentation](./README.md) · [English](../en/configuration.md) · [Deutsch](../de/configuration.md) · [日本語](../ja/configuration.md) · [简体中文](../zh/configuration.md) -`metadbd --config` et `ServerTomlConfig::from_toml_file` / `from_toml_str` lisent le TOML (`crates/metadb-server/src/config.rs`). Les clés inconnues sont ignorées. Les structs utilisent `#[serde(default)]` et ne posent pas `deny_unknown_fields`, et `from_toml_str` appelle `toml::from_str` directement. Une clé mal orthographiée conserve sa valeur par défaut, y compris un `security.shared_secret` vide, et le démarrage réussit quand même. Chaque section est facultative. Les champs omis prennent les valeurs par défaut ci-dessous. +`metadbd --config` et `ServerTomlConfig::from_toml_file` / `from_toml_str` lisent le TOML (`crates/metadb-server/src/config.rs`). Les clés inconnues qui ne nomment ni un secret ni TLS sont ignorées. Un `shared_secret` mal orthographié, une clé de jeton ou de mot de passe, ou une clé TLS ou de certificat sont refusés, et le processus ne démarre pas. Chaque section connue est facultative. Les champs omis prennent les valeurs par défaut ci-dessous. ## Valeurs par défaut @@ -13,7 +13,7 @@ | `node.role` | `all-in-one` | Oui. Toute autre valeur renvoie une erreur | | `node.data_dir` | `./metadb-data` | Oui | | `node.grpc_listen_addr` | `127.0.0.1:7800` | Oui. Adresse de liaison | -| `node.metrics_listen_addr` | non défini | Oui, seulement s'il est défini. `metadbd` lie un écouteur TCP séparé | +| `node.metrics_listen_addr` | non défini | Oui, seulement s'il est défini. Écouteur TCP séparé. Une adresse non locale exige un secret non vide | | `clock.max_clock_drift_ms` | `500` | Oui. `HybridLogicalClock::with_max_drift_ms` | | `storage.memtable_size_bytes` | `33554432` (32 Mio) | **Non.** Le champ est stocké et jamais lu | | `storage.block_cache_bytes` | `67108864` (64 Mio) | Oui. Budget total du cache de blocs à 16 voies | @@ -23,7 +23,7 @@ | `storage.locality_tombstone_ratio` | `0.50` | Oui. Multiplié par 1000, borné à 1..=1000, stocké dans `tombstone_min_ratio_permille` | | `sharding.bootstrap_table_shards` | `true` | Oui. `true` crée les shards 1, 2 et 3. `false` crée le shard 1 sur `[0x01, 0x04)` | | `sharding.shard_split_threshold_bytes` | `4294967296` (4 Gio) | Oui. Le contrôle de découpage utilise la taille approximative du shard | -| `security.shared_secret` | `""` | Oui. Vide signifie que les RPC de métadonnées, de transaction et de plan de contrôle ne sont pas authentifiés | +| `security.shared_secret` | `""` | Oui. Vide n'est accepté que si chaque écouteur est en boucle locale. Non vide exige le même bearer pour le gRPC et les métriques | Il n'y a pas de table `[raft]`. `ServerTomlConfig.raft_options` est ignoré par serde et reste à `RaftNodeOptions::default()` (battement 150 ms, élection 450–900 ms, conservation du journal d'instantané 0, segment 64 Mio). @@ -67,13 +67,11 @@ Les options CLI remplacent le fichier après son analyse : `--node-id`, `--cell- ## Sécurité -Le processus ne termine pas TLS. +Ce processus ne termine pas TLS. Aucune configuration de certificat n'active un TLS natif. Une clé TLS, SSL ou de certificat dans le fichier fait échouer l'analyse, et le processus ne sert pas en clair. Terminer TLS dans un proxy externe, et ne pas laisser de clé TLS dans ce fichier. -Lorsque `shared_secret` n'est pas vide, `MetadataService`, `TransactionService` et `ControlPlaneService` exigent que la valeur de métadonnée `authorization` soit égale à `Bearer `. `metadb-ctl --auth-token` (variable d'environnement `METADB_AUTH_TOKEN`) envoie cet en-tête. `metadbd --cell-manager` envoie le même secret lorsqu'il appelle `RegisterNode`. +Lorsque `shared_secret` n'est pas vide, `MetadataService`, `TransactionService`, `ControlPlaneService` et `RaftTransportService` exigent que `authorization` soit exactement `Bearer `. `GET /metrics` sur `metrics_listen_addr` exige le même en-tête `Authorization`. Un en-tête absent, un bearer vide, un préfixe ou un jeton plus long est rejeté. Le corps d'échec des métriques n'est pas du texte Prometheus. Les pairs Raft envoient le même bearer. `metadb-ctl --auth-token` (variable d'environnement `METADB_AUTH_TOKEN`) et `metadbd --join` / `--cell-manager` l'envoient. `metadb-ctl cluster status` appelle `GetRoutes` et passe par le même intercepteur. -`RaftTransportService` utilise le même intercepteur. Un secret non vide exige aussi `Bearer ` pour les RPC Raft sur ce port. - -Un secret vide autorise les quatre services de l'écouteur. Le code avertit de cela au démarrage. Le processus ne termine toujours pas TLS. Avant qu'un client non fiable puisse atteindre le port, garder la liaison sur un réseau de confiance tel que `127.0.0.1`, ou placer chaque service derrière un proxy qui authentifie le client (par exemple TLS mutuel) et bloquer l'accès direct à ce processus. +Un secret vide ou composé seulement d'espaces n'est accepté que si `grpc_listen_addr` et `metrics_listen_addr` (s'il est défini) sont en boucle locale (`127.0.0.0/8`, `::1`, ou le nom `localhost`). Un joker (`0.0.0.0`, `::`) ou toute autre adresse refuse d'écouter. Un secret vide en boucle locale produit un avertissement au démarrage. Les écouteurs restent en clair. Les garder sur un réseau de confiance, ou placer chaque service derrière un proxy qui authentifie le client, et bloquer l'accès direct à ce processus. ## Ce que l'on ne peut pas configurer @@ -81,4 +79,4 @@ Un secret vide autorise les quatre services de l'écouteur. Le code avertit de c - Les listes de pairs, les ensembles de votants ou un jeton de jonction. L'appartenance commence par ce seul processus. Des pairs supplémentaires n'apparaissent qu'après `RegisterNode` plus `ScaleShardReplicas`, et ces pairs doivent déjà être des membres Raft qui parlent `RaftTransportService` pour les mêmes journaux de shard. Un second processus all-in-one ne le fait pas. Voir [Exploitation](./operations.md). - L'intervalle de clés d'une seconde cellule. `RegisterCell` renvoie une erreur et ne stocke rien. Un second all-in-one au répertoire vide rejoint le leader courant avec `[cluster] join` ; c'est toujours la même cellule. - La limite en octets du memtable, les temporisations Raft, ou l'activation de la compaction par localité. -- Les certificats TLS. +- Les certificats TLS natifs. Une clé TLS dans ce fichier est rejetée. La terminaison appartient à un proxy externe. diff --git a/docs/fr/operations.md b/docs/fr/operations.md index 1d06dbd..80b6b63 100644 --- a/docs/fr/operations.md +++ b/docs/fr/operations.md @@ -71,7 +71,7 @@ Voir [Tests et bancs](./testing.md#metadb-ctl-bench). C'est un client contre un ## Métriques -Définir `node.metrics_listen_addr` (par exemple `127.0.0.1:9100`). `metadbd` accepte les connexions TCP et écrit un unique HTTP `200` dont le corps est du texte Prometheus. Il ne route pas sur le chemin d'URL. Toute requête reçoit le même corps. +Définir `node.metrics_listen_addr` (par exemple `127.0.0.1:9100`). `open_and_serve` accepte les connexions TCP sur cette adresse. `GET /metrics` renvoie du texte Prometheus. Tout autre chemin renvoie 404, et toute autre méthode renvoie 405. Lorsque `[security].shared_secret` n'est pas vide, chaque requête sur cet écouteur doit envoyer `Authorization: Bearer `. Un bearer absent, vide ou incorrect renvoie HTTP 401 et un corps qui n'est pas le texte des métriques, y compris une requête vers `/status`. Une adresse de métriques non locale avec un secret vide refuse de démarrer. Cet écouteur ne termine pas TLS. Jauges et compteurs de `render_prometheus_metrics` : @@ -135,7 +135,7 @@ Les variantes sont définies dans `crates/metadb-core/src/error.rs`. Les méthod - `GetRoutes` échoue fermé pour un `cell_id` non nul inconnu. `StoreHeartbeat` ne remplace pas les routes en cache. - L'isolation jumbo est un indicateur de route plus un identifiant de nœud choisi dans la table locale. Elle n'évince pas d'autres shards d'un disque. - Les battements de cœur sont un RPC sans émetteur dans `metadbd`. `StoreHeartbeat` ne persiste pas. -- Un secret partagé non vide authentifie Raft sur le port gRPC public avec le même bearer que les trois autres services. Un secret vide laisse Raft non authentifié. Le processus ne termine pas TLS. +- Un secret partagé non vide authentifie Raft, les trois autres services gRPC et l'écouteur de métriques avec le même bearer. Un secret vide n'est accepté que pour les liaisons en boucle locale et laisse ces écouteurs non authentifiés. Une liaison joker avec un secret vide refuse de démarrer. Le processus ne termine pas TLS. - `memtable_size_bytes` et tous les champs de temporisation Raft ne changent pas le comportement d'exécution via le TOML. - `metadb-ctl bench` pour `hotspot-create` et `bulk-ttl-delete` imprime des lignes JSON : un en-tête avec `bench_pid`, puis des rapports de phase avec attempted, succeeded, failed et des percentiles de latence. Le processus se termine en erreur si une opération demandée échoue. `--workload mixed` ou `--embedded` lance le harnais de stress dans le processus. `sql` imprime la réponse en JSON et se termine en erreur sur une erreur d'application. @@ -147,6 +147,6 @@ Ces éléments manquent au produit, donc ce guide ne peut pas décrire de procé 2. L'ajout d'un second et d'un troisième processus `metadbd` du système d'exploitation à un groupe Raft existant. 3. La création et le routage vers une seconde cellule. 4. Le placement d'un shard jumbo sur sa propre machine et le déplacement des autres shards hors de cette machine. -5. La matière TLS, l'authentification Raft, et une boucle de contrôle pilotée par les battements de cœur. +5. Le TLS natif. Ce processus ne termine pas TLS. Les clés de configuration qui demandent TLS ou un certificat sont rejetées au lieu de servir en clair. Placer la terminaison dans un proxy externe. Raft et les métriques utilisent le même bearer que les autres services lorsqu'un secret est défini ; ce n'est pas du TLS mutuel. Une boucle de contrôle pilotée par les battements de cœur n'est pas implémentée. 6. Une taille de memtable ou une temporisation Raft que l'exploitant peut régler et observer. 7. Un résultat de niveau service enregistré pour `metadb-ctl bench`. La commande imprime des nombres pour la machine sur laquelle on l'exécute. Ce dépôt n'en enregistre pas. La pull request non fusionnée n° 2 rapporte un harnais embarqué distinct ; ces commandes ne sont pas dans cet arbre. Voir [Tests et bancs](./testing.md). diff --git a/docs/guides/de/deployment.md b/docs/guides/de/deployment.md index 563e2ff..7329913 100644 --- a/docs/guides/de/deployment.md +++ b/docs/guides/de/deployment.md @@ -34,7 +34,7 @@ bootstrap_table_shards = true shard_split_threshold_bytes = 4294967296 # 4 GiB ``` -Rust 1.100.0 (`rust-toolchain.toml`). Nur die Rolle `all-in-one` startet. Ohne `[security].shared_secret` haben die gRPC-Dienste weder Auth noch TLS; der Default-Bind ist `127.0.0.1`. Den Port nicht in unvertrauenswürdige Netze stellen. +Rust 1.100.0 (`rust-toolchain.toml`). Nur die Rolle `all-in-one` startet. Dieser Prozess beendet TLS nicht. Ohne `[security].shared_secret` gibt es keine Authentifizierung, und nur Loopback-Binds werden akzeptiert. Der Default ist `127.0.0.1`. Eine Wildcard oder eine andere Adresse mit leerem Geheimnis verweigert den Start. Ein nicht leeres `shared_secret` verlangt `authorization: Bearer ` für Metadaten, Transaktionen, die Control Plane, Raft auf demselben Port und `GET /metrics`. ```bash metadbd --config /etc/metadb/standalone.toml diff --git a/docs/guides/en/deployment.md b/docs/guides/en/deployment.md index b7a7bbc..a3d8f4a 100644 --- a/docs/guides/en/deployment.md +++ b/docs/guides/en/deployment.md @@ -48,9 +48,9 @@ metadbd --config /etc/metadb/standalone.toml ### Network exposure -`MetadataService`, `TransactionService`, `ControlPlaneService`, and `RaftTransportService` do **not** terminate TLS. With an empty `[security].shared_secret` (the default) they also perform no application authentication. The default `grpc_listen_addr` is `127.0.0.1:7800`. Do not publish that socket on an untrusted network. +`MetadataService`, `TransactionService`, `ControlPlaneService`, and `RaftTransportService` do **not** terminate TLS. Neither does the metrics listener. With an empty `[security].shared_secret` (the default) they perform no application authentication, and only loopback binds are accepted. A wildcard or other non-loopback address without a non-empty secret refuses to start. The default `grpc_listen_addr` is `127.0.0.1:7800`. A TLS or certificate key in this file is rejected rather than served as plaintext. -Set a shared secret to require `authorization: Bearer ` on metadata, transaction, control-plane, and Raft transport RPCs. Peer Raft clients propagate the same token. `metadb-ctl --auth-token` (or `METADB_AUTH_TOKEN`) and `metadbd --cell-manager` send that header: +Set a shared secret to require `authorization: Bearer ` on metadata, transaction, control-plane, Raft transport, and `GET /metrics`. Peer Raft clients propagate the same token. `metadb-ctl --auth-token` (or `METADB_AUTH_TOKEN`) and `metadbd --cell-manager` send that header: ```toml [security] diff --git a/docs/guides/fr/deployment.md b/docs/guides/fr/deployment.md index d468954..2aaaa2e 100644 --- a/docs/guides/fr/deployment.md +++ b/docs/guides/fr/deployment.md @@ -34,7 +34,7 @@ bootstrap_table_shards = true shard_split_threshold_bytes = 4294967296 # 4 Gio ``` -Rust 1.100.0 (`rust-toolchain.toml`). Seul le rôle `all-in-one` démarre. Sans `[security].shared_secret`, le gRPC n'a ni authentification ni TLS ; l'écoute par défaut est `127.0.0.1`. Ne pas exposer ce port à un réseau non fiable. +Rust 1.100.0 (`rust-toolchain.toml`). Seul le rôle `all-in-one` démarre. Ce processus ne termine pas TLS. Sans `[security].shared_secret`, il n'y a pas d'authentification, et seules les liaisons en boucle locale sont acceptées. Le défaut est `127.0.0.1`. Un joker ou une autre adresse avec un secret vide refuse de démarrer. Un `shared_secret` non vide exige `authorization: Bearer ` pour les métadonnées, les transactions, le plan de contrôle, Raft sur le même port, et `GET /metrics`. ```bash metadbd --config /etc/metadb/standalone.toml diff --git a/docs/guides/ja/deployment.md b/docs/guides/ja/deployment.md index ecae027..0f8827d 100644 --- a/docs/guides/ja/deployment.md +++ b/docs/guides/ja/deployment.md @@ -34,7 +34,7 @@ bootstrap_table_shards = true shard_split_threshold_bytes = 4294967296 # 4 GiB ``` -Rust 1.100.0(`rust-toolchain.toml`)。実装されているロールは `all-in-one` のみ。gRPC は既定で認証も TLS もなく、待受は `127.0.0.1`。信頼できないネットワークに公開しないこと。空でない `[security].shared_secret` は metadata、transaction、control-plane、および同じポートの Raft 転送に `authorization: Bearer ` を要求する。 +Rust 1.100.0(`rust-toolchain.toml`)。実装されているロールは `all-in-one` のみ。このプロセスは TLS を終端しない。空の `[security].shared_secret` では認証もなく、待受はループバックだけを受け付ける。既定は `127.0.0.1`。ワイルドカードやそれ以外のアドレスに空のシークレットがあると起動を拒否する。空でない `shared_secret` は metadata、transaction、control-plane、同じポートの Raft 転送、および `GET /metrics` に `authorization: Bearer ` を要求する。 ```bash metadbd --config /etc/metadb/standalone.toml diff --git a/docs/guides/zh/deployment.md b/docs/guides/zh/deployment.md index 693f3d6..f09f7ec 100644 --- a/docs/guides/zh/deployment.md +++ b/docs/guides/zh/deployment.md @@ -42,7 +42,7 @@ shard_split_threshold_bytes = 4294967296 # 4 GiB 分片分裂阈值 工具链固定为 Rust **1.100.0**(`rust-toolchain.toml`)。当前只有 `all-in-one` 会真正启动;`be` / `proxy` / `cell-manager` / `global-manager` 会被拒绝,而不是静默变成全功能进程。 -gRPC 的 metadata、transaction、control-plane 与 Raft 传输**没有 TLS**。`[security].shared_secret` 为空时也没有应用层认证,默认监听 `127.0.0.1`。在补上共享密钥或外部 TLS 终结之前,不要把该端口暴露到不可信网络。非空 `shared_secret` 要求 metadata、transaction、control-plane 以及同一端口上的 Raft 传输都携带 `authorization: Bearer `。对等 Raft 客户端发送同一个令牌。 +gRPC 的 metadata、transaction、control-plane、Raft 传输以及指标监听器**都不终结 TLS**。`[security].shared_secret` 为空时也没有应用层认证,并且只接受环回绑定。通配或其他非环回地址如果没有非空密钥,会拒绝启动。默认 `grpc_listen_addr` 是 `127.0.0.1:7800`。文件里的 TLS 或证书键会被拒绝,而不是当作明文服务。非空 `shared_secret` 要求 metadata、transaction、control-plane、同一端口上的 Raft 传输以及 `GET /metrics` 都携带 `authorization: Bearer `。对等 Raft 客户端发送同一个令牌。 ```bash metadbd --config /etc/metadb/standalone.toml diff --git a/docs/ja/architecture.md b/docs/ja/architecture.md index e58ca70..cc7595c 100644 --- a/docs/ja/architecture.md +++ b/docs/ja/architecture.md @@ -9,16 +9,16 @@ `PersistentMetaDbCluster::open_and_serve`(`crates/metadb-server/src/lib.rs`)は次を行います。 1. `all-in-one` 以外の `node.role` を拒否する。 -2. `node.grpc_listen_addr` をバインドする(既定は `127.0.0.1:7800`。`127.0.0.1:0` は OS にポートを選ばせる)。 +2. `shared_secret` が空のとき、ワイルドカードまたはループバック以外の `grpc_listen_addr` と `metrics_listen_addr` を拒否する。その後 `node.grpc_listen_addr` をバインドする(既定は `127.0.0.1:7800`。`127.0.0.1:0` は OS にポートを選ばせる)。 3. `/global_allocator` で `DurableIdAllocator` を開く。 4. `/be` で `ShardGroupHost` を開く。 5. `/cell_` で `DurableCellManager` を開くかブートストラップする。 6. その 1 つのセルを、キー範囲 `[0x01, 0x04)` で `DurableGlobalManager` に登録する。 7. ルートの inode `1`(`ROOT_INODE_ID`)に属性レコードがあることを保証する。 -8. 同じリスナーで 4 つの gRPC サービスを提供する。4 つとも同じ任意のベアラインターセプタを取る。シークレットが空ならすべての呼び出しを通す。 +8. 同じリスナーで 4 つの gRPC サービスを提供する。4 つとも同じベアラインターセプタを取る。`metrics_listen_addr` が設定されているとき、そのアドレスの `GET /metrics` は同じシークレットを要求する。シークレットが空でなければ、欠落または誤ったベアラは拒否される。空のシークレットはループバックのバインドだけを受け付ける。このプロセスは TLS を終端しない。 9. 250 ms 間隔のメンテナンスタスクを起動する。 -`metadbd` は薄いラッパです。TOML を読み、CLI の上書きを適用し、`open_and_serve` を呼び、任意で `--cell-manager` へ `RegisterNode` を呼び、任意で Prometheus テキストを提供し、Ctrl-C で `shutdown` を呼びます。 +`metadbd` は薄いラッパです。TOML を読み、CLI の上書きを適用し、`open_and_serve` を呼び、任意で `--cell-manager` へ `RegisterNode` を呼び、Ctrl-C で `shutdown` を呼びます。メトリクスは設定されているとき `open_and_serve` の中で提供されます。 ## キーとテーブル diff --git a/docs/ja/build-and-run.md b/docs/ja/build-and-run.md index d0fd698..7522b2a 100644 --- a/docs/ja/build-and-run.md +++ b/docs/ja/build-and-run.md @@ -64,7 +64,7 @@ cargo run -p metadb-server --bin metadbd -- --config ./standalone.toml ログは `tracing-subscriber` の `EnvFilter` を使います。既定のフィルタは `info` です。標準の環境変数 `RUST_LOG` で上書きします。例: `RUST_LOG=debug`。 -`security.shared_secret` が空のとき、起動時に gRPC には認証も TLS も無いという警告が出ます。既定のバインドは `127.0.0.1` です。信頼できないネットワークへこのソケットを出さないでください。空でない `[security].shared_secret` は、メタデータ、トランザクション、コントロールプレーン、および Raft 転送の RPC に同じベアラを要求します。プロセスは引き続き TLS を終端しません。リスナーを信頼できるネットワークに留めるか、すべてのサービスを、クライアントを認証するプロキシの後ろに置き、このプロセスへの直接アクセスを塞いでください。 +`security.shared_secret` が空のとき、起動時にループバックの gRPC には認証が無いという警告が出ます。既定のバインドは `127.0.0.1` です。ワイルドカードまたはループバック以外のアドレスで、シークレットが空、欠落、または綴り違いなら待受を拒否します。空でない `[security].shared_secret` は、メタデータ、トランザクション、コントロールプレーン、Raft 転送、および `GET /metrics` に同じベアラを要求します。プロセスは TLS を終端しません。設定中の TLS または証明書キーは、平文で提供する代わりに起動を失敗させます。リスナーを信頼できるネットワークに留めるか、すべてのサービスを、クライアントを認証するプロキシの後ろに置き、このプロセスへの直接アクセスを塞いでください。 Ctrl-C はシャード状態をフラッシュし、OpenRaft グループを止めます(`cluster.shutdown()`)。 diff --git a/docs/ja/configuration.md b/docs/ja/configuration.md index ea3447a..b9c1795 100644 --- a/docs/ja/configuration.md +++ b/docs/ja/configuration.md @@ -2,7 +2,7 @@ [概要](./README.md) · [English](../en/configuration.md) · [Français](../fr/configuration.md) · [Deutsch](../de/configuration.md) · [简体中文](../zh/configuration.md) -`metadbd --config` と `ServerTomlConfig::from_toml_file` / `from_toml_str` は TOML を読みます(`crates/metadb-server/src/config.rs`)。未知のキーは無視されます。構造体は `#[serde(default)]` を使い、`deny_unknown_fields` は付けず、`from_toml_str` は `toml::from_str` を直接呼びます。綴りの違うキーは既定値のままです。空の `security.shared_secret` もその例で、起動は成功します。すべてのセクションは省略できます。省略した項目は次の既定値になります。 +`metadbd --config` と `ServerTomlConfig::from_toml_file` / `from_toml_str` は TOML を読みます(`crates/metadb-server/src/config.rs`)。シークレットや TLS を示さない未知のキーは無視されます。綴りの違う `shared_secret`、トークンやパスワードのキー、TLS や証明書のキーは拒否され、プロセスは起動しません。既知のセクションは省略できます。省略した項目は次の既定値になります。 ## 既定値 @@ -13,7 +13,7 @@ | `node.role` | `all-in-one` | する。それ以外の値はエラー | | `node.data_dir` | `./metadb-data` | する | | `node.grpc_listen_addr` | `127.0.0.1:7800` | する。バインドアドレス | -| `node.metrics_listen_addr` | 未設定 | 設定されたときだけする。`metadbd` が別の TCP リスナーをバインドする | +| `node.metrics_listen_addr` | 未設定 | 設定されたときだけする。別の TCP リスナー。ループバック以外は空でないシークレットが必要 | | `clock.max_clock_drift_ms` | `500` | する。`HybridLogicalClock::with_max_drift_ms` | | `storage.memtable_size_bytes` | `33554432`(32 MiB) | **しない。** フィールドは保持されるが読まれない | | `storage.block_cache_bytes` | `67108864`(64 MiB) | する。16 分割ブロックキャッシュの合計予算 | @@ -23,7 +23,7 @@ | `storage.locality_tombstone_ratio` | `0.50` | する。1000 倍し、1..=1000 にクランプし、`tombstone_min_ratio_permille` として保存する | | `sharding.bootstrap_table_shards` | `true` | する。`true` はシャード 1、2、3 を作る。`false` は `[0x01, 0x04)` を覆うシャード 1 を作る | | `sharding.shard_split_threshold_bytes` | `4294967296`(4 GiB) | する。分割判定はシャードの概算サイズを使う | -| `security.shared_secret` | `""` | する。空は、メタデータ、トランザクション、コントロールプレーンの RPC が無認証であることを意味する | +| `security.shared_secret` | `""` | する。空は全リスナーがループバックのときだけ受け付ける。空でない値は gRPC とメトリクスに同じベアラを要求する | `[raft]` テーブルはありません。`ServerTomlConfig.raft_options` は serde がスキップし、`RaftNodeOptions::default()` のままです(ハートビート 150 ms、選挙 450–900 ms、スナップショットログ保持 0、セグメント 64 MiB)。 @@ -67,13 +67,11 @@ CLI フラグはファイルを解析したあとで上書きします。`--node ## セキュリティ -このプロセスは TLS を終端しません。 +このプロセスは TLS を終端しません。ネイティブ TLS を有効にする証明書設定はありません。ファイルに TLS、SSL、または証明書のキーがあると解析は失敗し、プロセスは平文では提供しません。TLS は外部プロキシで終端し、このファイルに TLS キーを残さないでください。 -`shared_secret` が空でないとき、`MetadataService`、`TransactionService`、`ControlPlaneService` は、メタデータ `authorization` が `Bearer ` と等しいことを要求します。`metadb-ctl --auth-token`(環境変数 `METADB_AUTH_TOKEN`)がそのヘッダを送ります。`metadbd --cell-manager` は `RegisterNode` を呼ぶとき同じシークレットを送ります。 +`shared_secret` が空でないとき、`MetadataService`、`TransactionService`、`ControlPlaneService`、`RaftTransportService` は `authorization` が `Bearer ` と完全に一致することを要求します。`metrics_listen_addr` の `GET /metrics` も同じ `Authorization` ヘッダを要求します。ヘッダの欠落、空のベアラ、接頭辞、より長いトークンは拒否されます。失敗したメトリクス応答の本体は Prometheus テキストではありません。Raft ピアは同じベアラを送ります。`metadb-ctl --auth-token`(環境変数 `METADB_AUTH_TOKEN`)と `metadbd --join` / `--cell-manager` も送ります。`metadb-ctl cluster status` は `GetRoutes` を呼び、同じインターセプタの対象です。 -`RaftTransportService` も同じインターセプタを使います。シークレットが空でないとき、このポートの Raft RPC も `Bearer ` を要求します。 - -シークレットが空なら、このリスナーの 4 つのサービスはすべて通ります。コードは起動時にこれを警告します。プロセスは引き続き TLS を終端しません。信頼できないクライアントがポートへ届く前に、バインドを `127.0.0.1` のような信頼できるネットワークに留めるか、すべてのサービスをクライアントを認証するプロキシ(たとえば相互 TLS)の後ろに置き、このプロセスへの直接アクセスを塞いでください。 +空、または空白だけのシークレットは、`grpc_listen_addr` と設定済みの `metrics_listen_addr` がどちらもループバック(`127.0.0.0/8`、`::1`、または名前 `localhost`)のときだけ受け付けます。ワイルドカード(`0.0.0.0`、`::`)やそれ以外のアドレスは待受を拒否します。空のループバックシークレットは起動時に警告されます。リスナーは引き続き平文です。信頼できるネットワークに留めるか、すべてのサービスをクライアントを認証するプロキシの後ろに置き、このプロセスへの直接アクセスを塞いでください。 ## 設定できないもの @@ -81,4 +79,4 @@ CLI フラグはファイルを解析したあとで上書きします。`--node - ピア一覧、投票者集合、参加トークン。メンバーシップはこのプロセス 1 つから始まります。追加のピアは `RegisterNode` と `ScaleShardReplicas` のあとでのみ現れ、そのピアは同じシャードログに対してすでに `RaftTransportService` を話す Raft メンバーでなければなりません。2 つ目の all-in-one プロセスはそれをしません。 [運用](./operations.md) を参照してください。 - 2 つ目のセルのキー範囲。`RegisterCell` はエラーを返し、何も保存しません。空ディレクトリの 2 つ目の all-in-one は `[cluster] join` で現在のリーダーに参加します。これは同じセルです。 - memtable のバイト上限、Raft のタイマ、局所性コンパクションのオンとオフ。 -- TLS 証明書。 +- このプロセス内の TLS 証明書。設定中の TLS キーは拒否される。終端は外部プロキシで行う。 diff --git a/docs/ja/operations.md b/docs/ja/operations.md index f46768d..958e9e6 100644 --- a/docs/ja/operations.md +++ b/docs/ja/operations.md @@ -71,7 +71,7 @@ metadb-ctl --endpoint 127.0.0.1:7800 sql \ ## メトリクス -`node.metrics_listen_addr` を設定します(例: `127.0.0.1:9100`)。`metadbd` は TCP 接続を受け、本体が Prometheus テキストである HTTP `200` を 1 つ書きます。URL パスでは振り分けません。どのリクエストも同じ本体を受け取ります。 +`node.metrics_listen_addr` を設定します(例: `127.0.0.1:9100`)。`open_and_serve` がそのアドレスで TCP 接続を受けます。`GET /metrics` は Prometheus テキストを返します。他のパスは 404、他のメソッドは 405 です。`[security].shared_secret` が空でないとき、このリスナーのすべての要求は `Authorization: Bearer ` を送らなければなりません。欠落、空、または誤ったベアラは HTTP 401 を返し、本体はメトリクス本文ではありません。`/status` への要求も同じです。空のシークレットでループバック以外のメトリクスアドレスは起動を拒否します。このリスナーは TLS を終端しません。 `render_prometheus_metrics` のゲージとカウンタ: @@ -135,7 +135,7 @@ metadb-ctl --endpoint 127.0.0.1:7800 sql \ - 未知で非ゼロの `cell_id` に対する `GetRoutes` は失敗して閉じる。`StoreHeartbeat` はキャッシュ済みルートを置き換えない。 - ジャンボ隔離はルートフラグと、ローカルノード表から選んだノード ID である。他のシャードをディスクから追い出すことはしない。 - ハートビートは RPC であり、`metadbd` に送信側はない。`StoreHeartbeat` は永続化しない。 -- 空でない共有シークレットは、公開 gRPC ポート上の Raft を他の 3 サービスと同じベアラで認証する。空のシークレットでは Raft は無認証のままである。プロセスは TLS を終端しない。 +- 空でない共有シークレットは、Raft、他の 3 つの gRPC サービス、およびメトリクスリスナーを同じベアラで認証する。空のシークレットはループバックのバインドだけを受け付け、それらのリスナーは無認証のままである。空のシークレットでのワイルドカードバインドは起動を拒否する。プロセスは TLS を終端しない。 - `memtable_size_bytes` とすべての Raft タイマ項目は、TOML 経由で実行時の挙動を変えない。 - `hotspot-create` と `bulk-ttl-delete` の `metadb-ctl bench` は JSON 行を印字する。`bench_pid` を含むヘッダのあと、attempted、succeeded、failed とレイテンシのパーセンタイルを持つフェーズ報告が続く。要求した操作がすべて成功しない限り、プロセスは非ゼロで終了する。`--workload mixed` または `--embedded` はプロセス内のストレステストを実行する。`sql` は応答を JSON で印字し、アプリケーションエラーでは非ゼロで終了する。 @@ -147,6 +147,6 @@ metadb-ctl --endpoint 127.0.0.1:7800 sql \ 2. 既存の Raft グループへ 2 つ目と 3 つ目の `metadbd` OS プロセスを加えること。 3. 2 つ目のセルを作り、そこへルーティングすること。 4. ジャンボシャードを専用マシンに置き、他のシャードをそのマシンから移すこと。 -5. TLS 素材、Raft 認証、ハートビート駆動の制御ループ。 +5. プロセス内の TLS。このプロセスは TLS を終端しない。TLS や証明書を求める設定キーは、平文で提供する代わりに拒否される。終端は外部プロキシに置く。シークレットがあるとき、Raft とメトリクスは他のサービスと同じベアラを使う。これは相互 TLS ではない。ハートビート駆動の制御ループは未実装である。 6. 運用者が設定して観測できる memtable サイズまたは Raft タイマ。 7. `metadb-ctl bench` のチェックインされたサービス水準の結果。コマンドは実行したマシンの数値を印字します。このリポジトリはそれを記録していません。未マージのプルリクエスト 2 は別の組み込みハーネスを報告しています。それらのコマンドはこのツリーにはありません。 [テストとベンチ](./testing.md) を参照してください。 diff --git a/docs/zh/architecture.md b/docs/zh/architecture.md index da54422..b81add0 100644 --- a/docs/zh/architecture.md +++ b/docs/zh/architecture.md @@ -9,16 +9,16 @@ `PersistentMetaDbCluster::open_and_serve`(`crates/metadb-server/src/lib.rs`): 1. 拒绝除 `all-in-one` 以外的任何 `node.role`。 -2. 绑定 `node.grpc_listen_addr`(默认 `127.0.0.1:7800`;`127.0.0.1:0` 让操作系统分配端口)。 +2. `shared_secret` 为空时,拒绝通配或其他非环回的 `grpc_listen_addr` 与 `metrics_listen_addr`。然后绑定 `node.grpc_listen_addr`(默认 `127.0.0.1:7800`;`127.0.0.1:0` 让操作系统分配端口)。 3. 在 `/global_allocator` 打开 `DurableIdAllocator`。 4. 在 `/be` 打开 `ShardGroupHost`。 5. 在 `/cell_` 打开或引导 `DurableCellManager`。 6. 把这一个单元以键范围 `[0x01, 0x04)` 注册到 `DurableGlobalManager`。 7. 保证根 inode `1`(`ROOT_INODE_ID`)有属性记录。 -8. 在同一监听器上提供四个 gRPC 服务。四个服务使用同一个可选的持有者拦截器。密钥为空时,所有调用都放行。 +8. 在同一监听器上提供四个 gRPC 服务。四个服务使用同一个持有者拦截器。设置了 `metrics_listen_addr` 时,该地址上的 `GET /metrics` 要求同一个密钥。密钥非空时,缺失或错误的令牌会被拒绝。空密钥只接受环回绑定。本进程不终结 TLS。 9. 启动间隔 250 ms 的维护任务。 -`metadbd` 是薄封装:加载 TOML,应用命令行覆盖,调用 `open_and_serve`,可选地对 `--cell-manager` 调用 `RegisterNode`,可选地提供 Prometheus 文本,并在 Ctrl-C 时调用 `shutdown`。 +`metadbd` 是薄封装:加载 TOML,应用命令行覆盖,调用 `open_and_serve`,可选地对 `--cell-manager` 调用 `RegisterNode`,并在 Ctrl-C 时调用 `shutdown`。配置了指标时,由 `open_and_serve` 提供。 ## 键与表 diff --git a/docs/zh/build-and-run.md b/docs/zh/build-and-run.md index 5571247..e7e2924 100644 --- a/docs/zh/build-and-run.md +++ b/docs/zh/build-and-run.md @@ -64,7 +64,7 @@ cargo run -p metadb-server --bin metadbd -- --config ./standalone.toml 日志使用 `tracing-subscriber` 的 `EnvFilter`。默认过滤器是 `info`。用标准环境变量 `RUST_LOG` 覆盖,例如 `RUST_LOG=debug`。 -`security.shared_secret` 为空时,进程在启动时记录一条警告:gRPC 没有认证,也没有 TLS。默认绑定是 `127.0.0.1`。不要把这个套接字公布到不可信网络。非空的 `[security].shared_secret` 对元数据、事务、控制面和 Raft 传输 RPC 要求同一个持有者令牌。进程仍然不终结 TLS。把监听器留在可信网络上,或把每个服务放到会认证客户端的代理后面,并阻断对本进程的直接访问。 +`security.shared_secret` 为空时,进程在启动时记录一条警告:环回 gRPC 没有认证。默认绑定是 `127.0.0.1`。通配或其他非环回地址如果密钥为空、缺失或拼错,会拒绝监听。非空的 `[security].shared_secret` 对元数据、事务、控制面、Raft 传输和 `GET /metrics` 要求同一个持有者令牌。进程不终结 TLS。配置里的 TLS 或证书键会使启动失败,而不是以明文提供服务。把监听器留在可信网络上,或把每个服务放到会认证客户端的代理后面,并阻断对本进程的直接访问。 Ctrl-C 会刷出分片状态并停止 OpenRaft 组(`cluster.shutdown()`)。 diff --git a/docs/zh/configuration.md b/docs/zh/configuration.md index 08398e1..6f19bae 100644 --- a/docs/zh/configuration.md +++ b/docs/zh/configuration.md @@ -2,7 +2,7 @@ [概览](./README.md) · [English](../en/configuration.md) · [Français](../fr/configuration.md) · [Deutsch](../de/configuration.md) · [日本語](../ja/configuration.md) -`metadbd --config` 以及 `ServerTomlConfig::from_toml_file` / `from_toml_str` 读取 TOML(`crates/metadb-server/src/config.rs`)。未知键会被忽略。这些结构体使用 `#[serde(default)]`,没有 `deny_unknown_fields`,`from_toml_str` 直接调用 `toml::from_str`。拼错的键保持默认值,包括空的 `security.shared_secret`,进程仍然会启动。每个节都可以省略。省略的字段取下面的默认值。 +`metadbd --config` 以及 `ServerTomlConfig::from_toml_file` / `from_toml_str` 读取 TOML(`crates/metadb-server/src/config.rs`)。不表示密钥或 TLS 的未知键仍会被忽略。拼错的 `shared_secret`、令牌或密码键,以及任何 TLS 或证书键都会被拒绝,进程不会启动。每个已知节都可以省略。省略的字段取下面的默认值。 ## 默认值 @@ -13,7 +13,7 @@ | `node.role` | `all-in-one` | 是。任何其他值都返回错误 | | `node.data_dir` | `./metadb-data` | 是 | | `node.grpc_listen_addr` | `127.0.0.1:7800` | 是。绑定地址 | -| `node.metrics_listen_addr` | 未设置 | 仅在设置时应用。`metadbd` 绑定单独的 TCP 监听器 | +| `node.metrics_listen_addr` | 未设置 | 仅在设置时应用。单独的 TCP 监听器。非环回地址要求非空密钥 | | `clock.max_clock_drift_ms` | `500` | 是。`HybridLogicalClock::with_max_drift_ms` | | `storage.memtable_size_bytes` | `33554432`(32 MiB) | **否。** 字段被保存,从不读取 | | `storage.block_cache_bytes` | `67108864`(64 MiB) | 是。16 路块缓存的总预算 | @@ -23,7 +23,7 @@ | `storage.locality_tombstone_ratio` | `0.50` | 是。乘以 1000,钳制到 1..=1000,存为 `tombstone_min_ratio_permille` | | `sharding.bootstrap_table_shards` | `true` | 是。`true` 创建分片 1、2、3。`false` 创建覆盖 `[0x01, 0x04)` 的分片 1 | | `sharding.shard_split_threshold_bytes` | `4294967296`(4 GiB) | 是。分裂检查使用分片的近似大小 | -| `security.shared_secret` | `""` | 是。空表示元数据、事务和控制面 RPC 不认证 | +| `security.shared_secret` | `""` | 是。空密钥只在全部监听器都是环回地址时接受。非空时 gRPC 和指标要求同一个持有者令牌 | 没有 `[raft]` 表。`ServerTomlConfig.raft_options` 被 serde 跳过,保持 `RaftNodeOptions::default()`(心跳 150 ms,选举 450–900 ms,快照日志保留 0,段大小 64 MiB)。 @@ -67,13 +67,11 @@ shared_secret = "replace-with-a-long-random-string" ## 安全 -进程不终结 TLS。 +本进程不终结 TLS。没有能打开本机 TLS 的证书配置。文件里如果出现 TLS、SSL 或证书键,解析失败,进程不会以明文提供服务。请在外部代理终结 TLS,并且不要把 TLS 键留在这个文件里。 -`shared_secret` 非空时,`MetadataService`、`TransactionService` 和 `ControlPlaneService` 要求元数据 `authorization` 等于 `Bearer `。`metadb-ctl --auth-token`(环境变量 `METADB_AUTH_TOKEN`)发送这个头。`metadbd --cell-manager` 在调用 `RegisterNode` 时发送同一密钥。 +`shared_secret` 非空时,`MetadataService`、`TransactionService`、`ControlPlaneService` 和 `RaftTransportService` 要求 `authorization` 精确等于 `Bearer `。`metrics_listen_addr` 上的 `GET /metrics` 要求同一个 `Authorization` 头。缺失的头、空令牌、前缀或更长的令牌都会被拒绝。指标失败响应的正文不是 Prometheus 文本。Raft 对等体发送同一个令牌。`metadb-ctl --auth-token`(环境变量 `METADB_AUTH_TOKEN`)以及 `metadbd --join` / `--cell-manager` 也会发送它。`metadb-ctl cluster status` 调用 `GetRoutes`,走同一个拦截器。 -`RaftTransportService` 使用同一个拦截器。密钥非空时,该端口上的 Raft RPC 同样要求 `Bearer `。 - -空密钥允许该监听器上的四个服务。代码在启动时对此发出警告。进程仍然不终结 TLS。在不可信客户端能够到达该端口之前,把绑定留在 `127.0.0.1` 这类可信网络上,或把每个服务放到会认证客户端的代理后面(例如双向 TLS),并阻断对本进程的直接访问。 +空密钥或只含空白的密钥,仅当 `grpc_listen_addr` 和已设置的 `metrics_listen_addr` 都是环回地址(`127.0.0.0/8`、`::1` 或名字 `localhost`)时才接受。通配地址(`0.0.0.0`、`::`)或其他地址会拒绝监听。空的环回密钥会在启动时记一条警告。监听器仍然是明文。把它们留在可信网络上,或把每个服务放到会认证客户端的代理后面,并阻断对本进程的直接访问。 ## 不能配置的内容 @@ -81,4 +79,4 @@ shared_secret = "replace-with-a-long-random-string" - 对等体列表、投票者集合或加入令牌。成员关系从这一个进程开始。额外对等体只在 `RegisterNode` 加上 `ScaleShardReplicas` 之后出现,而且这些对等体必须已经是同一分片日志上会说 `RaftTransportService` 的 Raft 成员。第二个 all-in-one 进程不会这样做。见 [运维](./operations.md)。 - 第二个单元的键范围。`RegisterCell` 返回错误并且什么都不保存。空数据目录上的第二个 all-in-one 进程用 `[cluster] join` 加入当前 leader,这仍是同一个单元。 - memtable 字节上限、Raft 计时器,或局部性压缩的开关。 -- TLS 证书。 +- 本进程内的 TLS 证书。配置中的 TLS 键会被拒绝。终结应放在外部代理。 diff --git a/docs/zh/operations.md b/docs/zh/operations.md index 7d48e0e..d727ea1 100644 --- a/docs/zh/operations.md +++ b/docs/zh/operations.md @@ -71,7 +71,7 @@ metadb-ctl --endpoint 127.0.0.1:7800 sql \ ## 指标 -设置 `node.metrics_listen_addr`(例如 `127.0.0.1:9100`)。`metadbd` 接受 TCP 连接,并写出一个 HTTP `200`,正文是 Prometheus 文本。它不按 URL 路径路由。任何请求都得到同一正文。 +设置 `node.metrics_listen_addr`(例如 `127.0.0.1:9100`)。`open_and_serve` 在该地址接受 TCP 连接。`GET /metrics` 返回 Prometheus 文本。其他路径返回 404,其他方法返回 405。`[security].shared_secret` 非空时,该监听器上的每个请求都必须发送 `Authorization: Bearer `。缺失、空或错误的令牌返回 HTTP 401,正文不是指标文本,包括对 `/status` 的请求。空密钥配合非环回的指标地址会拒绝启动。该监听器不终结 TLS。 `render_prometheus_metrics` 的计量与计数: @@ -135,7 +135,7 @@ metadb-ctl --endpoint 127.0.0.1:7800 sql \ - 未知且非零的 `cell_id` 上,`GetRoutes` 失败关闭。`StoreHeartbeat` 不会替换缓存路由。 - 巨型隔离是路由标志加上从本地节点表选出的节点标识。它不会把其他分片从磁盘上赶走。 - 心跳是一个 RPC,`metadbd` 里没有发送方。`StoreHeartbeat` 不持久化。 -- 非空共享密钥用与另外三个服务相同的持有者令牌认证公开 gRPC 端口上的 Raft。空密钥下 Raft 仍然不认证。进程不终结 TLS。 +- 非空共享密钥用同一个持有者令牌认证 Raft、另外三个 gRPC 服务和指标监听器。空密钥只接受环回绑定,这些监听器不认证。通配绑定加上空密钥会拒绝启动。进程不终结 TLS。 - `memtable_size_bytes` 和所有 Raft 计时字段不会通过 TOML 改变运行行为。 - `hotspot-create` 和 `bulk-ttl-delete` 的 `metadb-ctl bench` 打印 JSON 行:先是带 `bench_pid` 的头,然后是包含 attempted、succeeded、failed 和延迟分位数的阶段报告。只要有一次请求的操作失败,进程就以非零状态退出。`--workload mixed` 或 `--embedded` 运行进程内的压力工具。`sql` 把响应打印成 JSON,遇到应用错误时以非零状态退出。 @@ -147,6 +147,6 @@ metadb-ctl --endpoint 127.0.0.1:7800 sql \ 2. 把第二个和第三个 `metadbd` 操作系统进程加入已有 Raft 组。 3. 创建第二个单元并路由到它。 4. 把巨型分片放到独立机器上,并把其他分片从那台机器移走。 -5. TLS 材料、Raft 认证,以及由心跳驱动的控制循环。 +5. 本进程内的 TLS。进程不终结 TLS。要求 TLS 或证书的配置键会被拒绝,而不是以明文提供服务。请在外部代理终结 TLS。密钥非空时,Raft 和指标与其他服务使用同一个持有者令牌;这不是双向 TLS。由心跳驱动的控制循环没有实现。 6. 运维人员可以设置并观察到的 memtable 大小或 Raft 计时器。 7. 记入仓库的 `metadb-ctl bench` 服务级结果。该命令打印你运行它的那台机器上的数字。本仓库没有记录一份。未合并的拉取请求 2 报告了另一套嵌入式工具;那些命令不在本树中。见 [测试与压测](./testing.md)。