UMBP Runtime-Tunable Environment Variables

Reference for the UMBP_* env vars consumed by the Mori UMBP stack at runtime — both the in-process timing/retry knobs parsed by the C++ library and the deployment knobs read by Python launcher scripts and the SGLang/hicache integration layer. Not every UMBP_* variable the code reads is listed yet.

See also:

  • design-master-control-plane.md — what each knob actually affects.

  • src/umbp/include/umbp/common/env_time.h — parser helpers (GetEnvSeconds / GetEnvMilliseconds / GetEnvMicroseconds / GetEnvUint32).

  • src/umbp/include/umbp/common/config.h::UMBPConfig::FromEnvironment — the env overlay applied to per-process UMBPConfig defaults.


Resolution semantics

  • Unset or empty env value → default is used, no log.

  • Non-numeric value, negative number, trailing garbage (e.g. "10abc"), uint32 overflow, or a value below the parameter’s min_allowed threshold → default is used, and one WARN per env name per process is emitted on stderr via UMBP_LOG_WARN.

  • Parsing uses std::strtoll with base 10. This means:

    • Leading whitespace is skipped ("  123" parses as 123).

    • An explicit sign prefix is accepted ("+123" OK; "-5" fails the non-negative check on all current params and falls back).

    • Trailing whitespace or any non-digit suffix ("123 ", "0x10") is rejected, falling back to the default.

  • Every production call site caches the resolved value in a function-local static const auto on first use (distributed/SPDK-proxy consumers). ClientRegistryConfig::FromEnvironment() / EvictionConfig::FromEnvironment() themselves do not cache, but the MasterServerConfig they produce is built once at master startup, so the net effect is the same: env changes after first touch have no effect within the same process. To exercise a different value, fork a fresh binary.

  • std::getenv and the logger are NOT async-signal-safe. First use must happen on a normal thread, not inside a signal handler.

When master starts, bin/master_main.cpp prints one line [Master] Resolved timing: ... after MasterServerConfig::FromEnvironment() so operators can audit the effective values.


Master / client registry

Read by the master process (bin/master_main.cpp via MasterServerConfig::FromEnvironment()).

Env var

Default

Unit

Description

UMBP_HEARTBEAT_TTL_SEC

10

sec

Registry entry TTL; client is evicted if no heartbeat arrives within heartbeat_ttl × max_missed_heartbeats.

UMBP_REAPER_INTERVAL_SEC

5

sec

Reaper wake-up period inside ClientRegistry.

UMBP_MAX_MISSED_HEARTBEATS

3

count

Consecutive misses before a client is considered dead.

UMBP_EVICTION_CHECK_INTERVAL_SEC

5

sec

EvictionManager loop period.

UMBP_LEASE_DURATION_SEC

2

sec

Master-side read-lease length granted by Router::RouteGet: IsLeased() keys are skipped by the eviction scan, keeping a key alive from the moment the master returns its location until the reader connects to the owning peer. Only needs to cover the master→reader gRPC round trip + reach the peer (the actual RDMA transfer is covered peer-side by UMBP_DRAM_READ_LEASE_MS), so seconds is already generous; larger values pin actively-read (hot) keys against eviction.

UMBP_HEARTBEAT_INTERVAL_DIVISOR

2

count

Recommended client heartbeat interval = heartbeat_ttl / divisor. min_allowed=1 guards against div-by-zero. Read by the master and echoed in RegisterClientResponse.heartbeat_interval_ms.

UMBP_EVICTKEY_DEADLINE_MS

1000

ms

Per-call gRPC deadline applied to outbound EvictKey RPCs from MasterPeerStubPool.

UMBP_EVICT_MAX_BYTES_PER_ROUND

0

bytes

Most bytes one eviction round frees from one (node, tier). 0 = its whole overage above the low watermark. Set it to throttle eviction, e.g. how much a demoting tier copies downstream per round.

UMBP_EVICT_DEMOTION_RETRY_MS

30000

ms

How long a peer retries an eviction demotion that failed in a way that can clear (no space at the target, e.g. an SSD staging arena full of reads, or a copy/commit error) before it drops the evicted copy so the tier still frees. Counted from the first attempt. 0 = drop on the first such failure.

UMBP_HIT_INDEX_TTL_SEC

7200

sec

External KV hit-count entry TTL. A hash with no counted match for longer than this is removed from the hit index.

UMBP_HIT_INDEX_GC_INTERVAL_SEC

60

sec

External KV hit-count GC sweep interval.

UMBP_HIT_QUERY_MAX_BATCH

4096

count

Maximum hashes accepted by one GetExternalKvHitCounts request. Oversized requests return gRPC INVALID_ARGUMENT; the server does not truncate.

UMBP_ROUTE_PUT_SELECT_ALGO

most_available

enum

Base RoutePut placement algorithm over eligible node entry pools. most_available = pick the node with the most projected free space; random = capacity-weighted random (probability proportional to projected available_bytes, never picks a node that cannot fit). Unknown value → default + one WARN.

UMBP_ROUTE_PUT_NODE_AFFINITY

none

enum

Node-affinity bias layered on top of the base algorithm. none = pure base algorithm; same = try to place the whole batch on one node that fits the non-dedup total, else per-key sticky to the first picked node; local = per-key prefer the requester’s local node. All three fall back to the base algorithm so affinity never makes a key fail that the base algorithm could route. Unknown value → default + one WARN.

UMBP_MASTER_INDEX_SHARDS

32

count

Number of independently-locked, key-hashed shards backing the block-location index inside InMemoryMasterMetadataStore (the block lock domain, separate from the single meta_mutex_ that guards client records + external-KV). A heartbeat’s event batch only takes the exclusive lock on the shards its keys hash into, so unrelated RoutePut / BatchLookup readers on other shards don’t block behind a large apply; full-sync likewise becomes N small critical sections instead of one giant one. Read once at store construction via std::strtol; unset / unparseable / < 1 → default 32 (a WARN is logged on unparseable input), clamped to a max of 4096. 1 reproduces the old single-lock block index. Production guidance for heavy heartbeat fan-out (hundreds of clients): 64.

Peer / pool client

Read by each pool client process (typically an SGLang/vLLM worker that has loaded libmori_umbp_pybinds.so, i.e. imported mori.umbp).

Env var

Default

Unit

Description

UMBP_EVICTION_MODE

local

enum

How a node with a master evicts. local: every medium at this node’s own watermarks (a tiered policy’s per-tier pair, else the SSD / DRAM config pair), by its own LRU, without asking the master; the master leaves it out of its EvictKey rounds. master_ranked: the same, with victims ranked by the master (GetEvictionCandidates), falling back to local LRU. master: DRAM/HBM wait for the master’s rounds (SSD still evicts locally). In both master modes the node reports the keys it reads locally, and the keys callers pass to BatchTouch, on its heartbeats (deduplicated; the master counts a heartbeat’s keys as used at once), since the master’s recency otherwise sees only RouteGet. A node without a master always evicts locally, and every mode still serves EvictKey.

UMBP_DRAM_READ_LEASE_MS

500

ms

Read lease of a DRAM or HBM backend: how long a key’s pages stay protected from local eviction while a peer reads them over RDMA. Only needs to exceed one DRAM RDMA round trip (sub-ms), so 500 ms is ~100x margin. Read once per process; min_allowed=1.

UMBP_SSD_READ_LEASE_MS

3000

ms

Read lease of an SSD backend. It has to cover an SSD read plus the RDMA, not just the RDMA, and it is also how long a staging page stays claimed, so it sets the backend’s read concurrency against its fixed staging arena: shortening it frees pages sooner and costs read coalescing. Read once per process; min_allowed=1.

UMBP_RESOLVE_BUSY_TIMEOUT_MS

30000

ms

Overall deadline for retrying a peer-local or remote batch resolve that returned BUSY because SSD staging was temporarily full. Retries discard the whole response and use exponential backoff capped at 50 ms. A batch whose own working set exceeds the arena returns a permanent failure immediately and is not retried. Values above 300000 ms are clamped.

UMBP_REMOTE_READ_VALIDATE

on

bool

Check-after-read for remote gets (#749). The peer’s read lease (UMBP_DRAM_READ_LEASE_MS / UMBP_SSD_READ_LEASE_MS) is only a timer, so after each remote batch’s RDMA read the reader sends one ValidateReads RPC asking whether every copy it read is still the one the peer resolved; a copy that was freed or refilled meanwhile becomes a miss instead of another key’s bytes, counted in mori_umbp_client_remote_get_dropped_total{reason="stale"}. Fails closed: an RPC error drops the batch’s reads as reason="unverified". Skipped for a peer that stamps no generations (an older build). The RPC deadline is UMBP_RESOLVE_BUSY_TIMEOUT_MS. 0 disables the check — meant for measuring its cost, since it reopens the stale-read window. Read once per process.

UMBP_RPC_SHUTDOWN_TIMEOUT_MS

3000

ms

Deadline for UnregisterClient and the last Heartbeat in ~MasterClient. Bounds ~MasterClient worst-case at ≤ 2 × this value.

UMBP_GRPC_SHUTDOWN_DEADLINE_SEC

3

sec

server_->Shutdown(deadline) budget, shared by master and peer service.

UMBP_METRICS_REPORT_INTERVAL_MS

1000

ms

Cadence at which the pool client’s MasterClient flushes buffered counters/gauges/histograms via ReportMetrics.

UMBP_STANDALONE_METRICS_PORT

9092

port

Port the standalone server serves /metrics on when it runs without a master, so a masterless node publishes what it measures instead of discarding it. Not the master’s 9091, so a node running both does not have two processes contending for one port. 0/off/false/no (case-insensitive) disables the endpoint; anything else that is not a port number is rejected at startup rather than read as “off”. Ignored when a master is configured — the metrics go to the master then, and a second endpoint would double-count on any Prometheus scraping both. A failed bind logs ERROR and the server still starts. Scrape fragment: examples/monitoring/umbp_standalone.scrape.yml.

UMBP_SUMMARY_INTERVAL_MS

60000

ms

Cadence of the periodic activity summary: one INFO line per window saying what this process offloaded, loaded, evicted, promoted and demoted, plus what is resident. Runs in every deployment — master, masterless, embedded — because it is the readout for the runs that have no Prometheus at all (a ctest, a one-shot benchmark, an sglang rank being bisected). 0 disables it. A window in which nothing moved still logs one line, carrying resident bytes and key count, because a node holding keys and moving none of them is the stall this is meant to catch. It replaced the per-key DEBUG logs on the re-cache and local-eviction paths; an unparseable value falls back to the default rather than refusing to start.

UMBP_AUTO_FLUSH_EVENT_THRESHOLD

128

count

Number of unshipped KvEvents at which a backend’s completed puts auto-trigger a heartbeat flush (FlushHeartbeat), so the ADDs become visible at the master without waiting for the heartbeat interval or an explicit Flush(). Every backend (DRAM, HBM, SSD) has the hook. Parsed via std::strtoull (no WARN on bad input); unset / unparseable -> default 128. 0 disables size-based auto-flush on DRAM and HBM backends, but an SSD backend treats 0 as 1 and flushes on every event; set a very large value to keep auto-flush armed but effectively never fire on size. Read once per process.

UMBP_WORKLOAD_TRACE_PATH

empty

path

Records successful production PUT/GET calls in the benchmark trace format. Empty disables recording.

UMBP_WORKLOAD_TRACE_CLIENT_ID

0

id

Logical client stream written into production trace events.

UMBP_WORKLOAD_TRACE_SEED

0

seed

Payload seed stored in the trace header for deterministic replay.

UMBP_PEER_MIN_POLLERS

8

count

Minimum gRPC sync poller threads on the peer service. The default pool is small, and every peer RPC that stages SSD bytes holds one of those threads for the whole device read — on a loopback read the pool, not the drive, is the binding constraint. Same head-of-line-blocking fix as UMBP_MASTER_MIN_POLLERS.

UMBP_PEER_MAX_POLLERS

64

count

Maximum gRPC sync poller threads on the peer service. Clamped up to UMBP_PEER_MIN_POLLERS if set lower.

UMBP_DISTRIBUTED_SSD_STAGING_USE_HUGEPAGES

0

bool

Back the SSD staging arena with hugetlbfs pages. Every byte the SSD backend moves crosses that arena twice (device <-> arena, arena <-> wire), so its TLB behaviour is on the critical path in a way an ordinary buffer’s is not. Falls back to 4 KiB pages when no hugetlb pages are free — a node must still come up. Standalone server binary only; the SGLang path uses the pybind ssd_staging_use_hugepages field.

UMBP_DISTRIBUTED_SSD_STAGING_HUGEPAGE_SIZE

2 MiB

bytes

Hugepage size requested for the SSD staging arena.

UMBP_DISTRIBUTED_RANGED_SCRATCH_BYTES

0

bytes

Size of the registered host arena backing ranged (sub-object) multi-buffer I/O, and the entire opt-in for the feature: at 0 the client allocates and registers nothing and SupportsRangedIO() reports false, so a caller that asks — the SGLang tree connector does — falls back to whole-object I/O. Purely a remote-path resource: remote gets are staged in it and remote puts assembled in it, while ranged I/O served by this node’s own medium never touches it. Must exceed the largest object a ranged batch will move remotely; an object bigger than the arena fails that key with an error rather than the batch. Applies on every medium including SSD (that exclusion was lifted — see doc/design-ssd-ranged-io.md). In the standalone server each arena is laid out by NUMA node (UMBP_DISTRIBUTED_RANGED_SCRATCH_NUMA): the bytes are split evenly over the nodes that have GPUs, one shard per GPU by default, so the largest object it can stage is one node’s share. Each arena, or each node’s part, is one NIC memory region, and AINIC firmware before 1.117.5-a-190 translates only its first 2^18 page entries: on 4 KiB pages keep a region within 1 GiB or use UMBP_DISTRIBUTED_RANGED_SCRATCH_USE_HUGEPAGES; on such firmware the client warns at startup otherwise. Standalone server binary only; the SGLang path uses the pybind ranged_scratch_size field.

UMBP_DISTRIBUTED_RANGED_SCRATCH_USE_HUGEPAGES

0

bool

Back both ranged scratch arenas with hugetlbfs pages. Each arena is ONE NIC memory region whose translation entries are its pages, and NICs cap entries per region, so hugepages let an arena grow far larger. Needs 2 * RANGED_SCRATCH_BYTES of free hugetlb pages on top of any hugepage DRAM tier. Falls back to 4 KiB pages when they are not free; the startup line `[DistributedClient] ranged scratch: … pages (hugetlb

UMBP_DISTRIBUTED_RANGED_SCRATCH_HUGEPAGE_SIZE

2097152

bytes

Hugepage size for UMBP_DISTRIBUTED_RANGED_SCRATCH_USE_HUGEPAGES (2 MiB or 1 GiB). Standalone server binary only; pybind field ranged_scratch_hugepage_size.

UMBP_DISTRIBUTED_RANGED_SCRATCH_SHARDS

1; one per GPU with the NUMA layout

count

How many shards a ranged scratch arena is cut into, counted over the whole arena (at most 64), each leased by one call at a time, so that many remote ranged calls stage concurrently; a shard is UMBP_DISTRIBUTED_RANGED_SCRATCH_BYTES / SHARDS whether or not the arena is laid out by NUMA node. The NUMA layout splits the count evenly over the nodes, so set a multiple of their number: another value is rounded down to one, with at least one shard per node, and a warning says what was used; the node count gives each node’s part a single shard. Shards split the same bytes: more of them means a smaller shard and more arena rounds for a call that moves more than one, and a call needing more than a shard takes its arena (with the NUMA layout, its node’s part) exclusively, so raise UMBP_DISTRIBUTED_RANGED_SCRATCH_BYTES along with it.

UMBP_DISTRIBUTED_RANGED_SCRATCH_NUMA

1

bool

Lay the ranged scratch arenas out by NUMA node: each arena’s bytes are split evenly over the nodes that have GPUs, each part bound to its node and registered on its own, and a remote ranged call stages through the part on its caller buffer’s node (a GPU’s node for device memory). Its RDMA leg then runs on that node’s NICs and the copy into the GPU stays on its socket; total memory is unchanged. A node whose part cannot be allocated on it falls back to one arena per direction. 0 keeps one arena per direction. Standalone server binary only.

UMBP_DISTRIBUTED_MEDIUM

DRAM

enum

The one medium this node serves when no backend policy is given: DRAM, HBM or SSD. Selecting SSD is the whole opt-in for a storage node — there is no separate pure-SSD flag. An unknown value is rejected at startup rather than silently defaulting. Ignored once UMBP_BACKEND_POLICY names a policy, which describes the backends directly. Standalone server binary only; the SGLang path uses the pybind medium field.

SPDK proxy

Read by the spdk_proxy daemon (for intervals it emits) and by the pool client process via SpdkProxyTier (for stale / poll checks).

Env var

Default

Unit

Description

UMBP_SPDK_PROXY_HEARTBEAT_STALE_MS

5000

ms

Threshold after which the SHM-header heartbeat is considered stale. Consumed by SpdkProxyTier.

UMBP_SPDK_PROXY_HEARTBEAT_INTERVAL_MS

500

ms

How often the proxy daemon’s PollLoop writes proxy_heartbeat_ms.

UMBP_SPDK_PROXY_REAP_INTERVAL_SEC

5

sec

Period of dead-channel reap + SyncTelemetry in PollLoop.

UMBP_SPDK_PROXY_INIT_FAIL_SLEEP_SEC

2

sec

Sleep before detach when SpdkEnv::Init fails during daemon startup.

UMBP_SPDK_PROXY_BUSY_YIELD_MS

1

ms

Yield step used by writeback / batch-drain busy waits.

UMBP_SPDK_PROXY_TIMEOUT_MS

30000

ms

Max time SpdkProxyTier waits for the proxy to reach READY.

UMBP_SPDK_PROXY_IDLE_EXIT_TIMEOUT_MS

30000

ms

Daemon self-exits after this much idle time with zero active sessions.

UMBP_SPDK_PROXY_TENANT_GRACE_MS

30000

ms

Grace period before forcibly reaping an inactive tenant.

UMBP_SPDK_PROXY_WRITE_BACK

0

bool

Set non-zero to enable proxy write-back caching.

UMBP_SPDK_PROXY_DEFAULT_TENANT_QUOTA_BYTES

0

bytes

Per-tenant SHM data-region quota. 0 = no per-tenant cap.

UMBP_SPDK_PROXY_CACHE_MB / UMBP_SPDK_RING_MB

—

MB

SPDK ring buffer size in MB. UMBP_SPDK_RING_MB is the canonical name; UMBP_SPDK_PROXY_CACHE_MB is the legacy alias.

UMBP_SPDK_RAID_STRIP_KB

128

KB

RAID strip size when constructing a SPDK RAID bdev across multiple NVMe controllers.


UMBPConfig overlay

UMBPConfig() (and its alias UMBPConfig::FromEnvironment()) overlays these on top of the struct defaults; fields the caller assigns afterwards win. Set them before constructing the config — they are read once, there.

Env var

Default

Description

UMBP_DRAM_CAPACITY

4 GiB

dram.capacity_bytes.

UMBP_DRAM_HIGH_WM / UMBP_DRAM_LOW_WM

0.95 / 0.9

DRAM tier eviction watermarks.

UMBP_SSD_ENABLED

1

0 to disable the SSD tier entirely. This no longer selects a medium: a single-medium SSD node is chosen with UMBP_DISTRIBUTED_MEDIUM=SSD (or distributed.medium), or named as a backend in UMBP_BACKEND_POLICY, and umbp_standalone_server refuses to start if this is set while neither named one, rather than quietly serving DRAM.

UMBP_EMBEDDED_DRAM_PAGE_SIZE

64 KiB

Allocation granularity of the pool an embedded deployment gets when the config names no deployment at all. The pool is paged, so a value smaller than a page still occupies one: a caller storing KV pages should set this to the page’s exact byte size, and one storing small values wants it smaller. Ignored once distributed is configured — set distributed.dram_page_size there instead.

UMBP_SSD_DIR

/tmp/umbp_ssd

POSIX backend root(s). Comma-separated for multi-drive, one directory per physical drive (e.g. /mnt/nvme0,/mnt/nvme1). More than one turns the tier into a ShardedSsdTier: keys are placed on the drive with the most free space and batch IO runs on every drive at once, so the tier delivers their aggregate bandwidth.

UMBP_SSD_CAPACITY

32 GiB

ssd.capacity_bytes. With multiple UMBP_SSD_DIR entries this is the TOTAL budget, split evenly across the drives. Charged in padded on-disk bytes (see UMBP_SSD_DIRECT_IO), not raw value bytes, and in bytes on disk: an evicted record keeps its space until its whole segment file is deleted, so the used figure (and the eviction watermarks) count dead records too.

UMBP_SSD_SEGMENT_SIZE

4 GiB

ssd.segment_size_bytes, a multiple of 4096. Segment files are the unit disk comes back in: eviction empties whole segments (emptiest and coldest first) and a segment file is deleted once nothing in it is live. Smaller segments free space in finer steps and drop fewer still-useful keys with each one, at the cost of more files and fds. A drive whose share of UMBP_SSD_CAPACITY is under 8 segments uses 1/8 of that share instead.

UMBP_SSD_DIRECT_IO

1

ssd.direct_io — 1 opens segments O_DIRECT, bypassing the page cache. On by default; set 0 only to deliberately measure or exploit the page cache. Buffered can serve an entire working set from page cache and move zero bytes to the device, which makes drive-count and DRAM-vs-SSD comparisons meaningless — that is why the default is direct. Requires record format v3 (already unconditional), so a directory reads back either way.

UMBP_SSD_VERIFY_CRC

1

Compute checksums on write, verify on read. Off isolates how much of the SSD path is integrity work rather than storage — the DRAM tier does no checksumming, so an unqualified comparison conflates the two. Records written with it off carry kFlagNoCrc and stay readable either way.

UMBP_SSD_TIER_IO_THREADS

4

Worker threads for the CPU-bound phases inside one drive’s batch (checksum verify on read, checksum + record assembly on write). Matches the DRAM tier’s default so a DRAM-vs-SSD comparison is not silently 4 threads against 1.

UMBP_SSD_SHARD_IO_THREADS

0

Worker threads for the multi-drive fan-out. 0 = one per drive, which is what saturates N drives. Ignored with a single UMBP_SSD_DIR.

UMBP_SSD_SINGLE_FLIGHT

1

Coalesce concurrent reads of the same key: the first requester touches the drive, the rest are served by memcpy from its buffer. Exists for MLA + TP, where every attention-TP rank GETs a byte-identical key and one page is otherwise read tp_size times. MHA keys carry a per-rank suffix and never collide, so this is a no-op there.

UMBP_SSD_DURABILITY

strict

strict fdatasync()s every batch write; relaxed leaves it to the kernel. Relaxed is safe for a pure cache — the bytes are re-fetchable and the peer discards leftover segments at startup — so the flush buys nothing there while costing a large share of write time. Unknown values leave the configured mode untouched.

UMBP_SSD_TIMING

unset

Diagnostic. Prints a stage-by-stage [SsdPerf/tier], [SsdPerf/shard] and [SsdPerf/peer] breakdown per batch (index lookup / device IO / CRC / fan-out, with implied GB/s), which is what answers “device or CPU?” without a profiler. Several lines per batch — turn it off again after investigating.

UMBP_SSD_BACKEND

file

file or spdk. Implicitly upgraded to spdk if UMBP_SPDK_NVME_PCI is set.

UMBP_EVICTION_POLICY

lru

Forwarded to eviction.policy.

UMBP_ROLE

(empty)

leader / follower / standalone. If unset, falls back to LOCAL_RANK / OMPI_COMM_WORLD_LOCAL_RANK / SLURM_LOCALID / MPI_LOCALRANKID: rank 0 → leader, others → follower.

UMBP_SPDK_BDEV

(empty)

SPDK bdev name (e.g. Malloc0, NVMe0n1).

UMBP_SPDK_REACTOR_MASK

0x1

SPDK reactor CPU mask.

UMBP_SPDK_MEM_MB

256

DPDK hugepage limit (MB).

UMBP_SPDK_NVME_PCI

(empty)

NVMe PCI BDF (e.g. 0000:47:00.0).

UMBP_SPDK_NVME_CTRL

NVMe0

SPDK NVMe controller name.

UMBP_SPDK_IO_WORKERS

4

Internal I/O worker threads for SpdkSsdTier batch ops.

UMBP_SPDK_PROXY_SHM

/umbp_spdk_proxy

SHM segment name.

UMBP_SPDK_PROXY_TENANT_ID

0

Tenant id for this client.

UMBP_SPDK_PROXY_TENANT_QUOTA_BYTES

0

Per-tenant quota, 0 = unlimited.

UMBP_SPDK_PROXY_MAX_CHANNELS (alias UMBP_SPDK_PROXY_MAX_RANKS)

8

Channel count.

UMBP_SPDK_PROXY_DATA_PER_CHANNEL_MB (alias UMBP_SPDK_PROXY_DATA_MB)

32

MB of SHM data region per channel.

UMBP_SPDK_PROXY_BIN

(auto)

Path to the spdk_proxy binary. The Python mori.umbp package auto-fills this from the packaged binary.

UMBP_SPDK_PROXY_AUTO_START

1

Auto-spawn the proxy daemon if not already running.

UMBP_SPDK_PROXY_ALLOW_BORROW

0

Allow tenants to borrow capacity from the shared pool.

UMBP_SPDK_PROXY_RESERVED_SHARED_BYTES

0

Reserved shared bytes that cannot be borrowed.


Deployment / launcher env vars

Not parsed by the C++ library directly. These are consumed by the SGLang / hicache wrappers and src/umbp/scripts/run_umbp_single_node_hicache.sh to construct the UMBPDistributedConfig plumbed into the C++ side. Listed here so operators can find them in one place.

Env var

Description

UMBP_MASTER_ADDRESS

host:port of the master to connect to (e.g. 10.0.0.1:15558). Optional. Without it the same client is an embedded deployment: same backends and transfer engine, nothing routed, registered or heartbeated, and a local miss is the final answer. It is also what decides whether the backend evicts for itself and whether it records heartbeat events at all.

UMBP_BACKEND_POLICY

JSON backend/tier policy used by a distributed-backed standalone server.

UMBP_MASTER_LISTEN

host:port the master should listen on (when starting it locally).

UMBP_MASTER_AUTO_START

true/false: auto-spawn umbp_master on this node before connecting.

UMBP_MASTER_BIN

Path to the umbp_master binary. The Python mori.umbp package auto-fills this from the packaged binary; override to point at a custom build.

UMBP_NODE_ADDRESS

This node’s address as advertised to peers. Must be reachable from every other node. Required only with a master: with none, nothing registers and no peer can dial in, so umbp_standalone_server synthesizes it (as it does UMBP_NODE_ID) and omitting UMBP_IO_ENGINE_HOST simply builds no RDMA engine.

UMBP_IO_ENGINE_HOST

mori::io::IOEngine listener host (typically 127.0.0.1).

UMBP_IO_ENGINE_PORT / UMBP_IO_ENGINE_PORTS

IO engine port (single port, or comma-separated list for multi-engine deployments).

UMBP_PEER_SERVICE_PORT

Port PeerServiceServer should bind.

UMBP_CACHE_REMOTE_FETCHES

true/false: locally re-cache blocks fetched from a remote peer. Set to false for clean throughput benchmarks where you want to measure raw remote-fetch cost.


Pre-existing / unrelated knobs

Env var

Default

Description

MORI_UMBP_LOG_LEVEL

unset, which means error

UMBP’s log level: trace, debug, info, warn, error or critical (case-insensitive; anything else means error). MORI_GLOBAL_LOG_LEVEL sets every MORI module. See include/mori/utils/mori_log.hpp.

MORI_IO_SQ_BACKOFF_TIMEOUT_US is not in the UMBP namespace; it is owned by MORI-IO (src/io/rdma/common.cpp).


Testing

  • tests/cpp/umbp/distributed/test_env_time.cpp covers the parser helpers (default / valid / empty / non-numeric / trailing garbage / negative / below-min / zero-when-allowed / uint32 overflow / multiple independent names).

  • Business-path tests that require exercising multiple values of the same env within one test suite must fork — the function-local static const caches cannot be reset mid-process.

  • CI environments that export any UMBP_* globally must strip those variables before running UMBP test targets, otherwise the first test to touch a given name will freeze the CI-injected value for the entire process.