Configuration

HTTP Config API

Ultipa exposes a REST-style HTTP Config API on the metrics port (default 9091) for runtime configuration inspection and hot-update. The API is available on the Name Server alongside the /health, /ready, and /metrics endpoints.

Viewing Configuration

Send a GET request to the /config endpoint to retrieve all server configuration keys with their current values and descriptions:

Bash
curl http://<name-server-host>:9091/config

Response:

JSON
{
  "Log.level": {
    "value": "info",
    "description": "Log level (hot update)"
  },
  "Log.format": {
    "value": "text",
    "description": "Log format: text or json (hot update)"
  },
  "Server.mem_threshold_percent": {
    "value": "80.000000",
    "description": "Memory threshold percent (hot update)"
  }
}

Hot-updatable keys are annotated with "hot update" in the description field.

Updating Configuration

Send a POST request to the /config endpoint to hot-update one or more configuration keys:

Bash
curl -X POST http://<name-server-host>:9091/config \
  -H 'Content-Type: application/json' \
  -d '{"Log.format": "json", "Log.level": "debug"}'

Response:

JSON
{
  "results": {
    "Log.format": "OK",
    "Log.level": "OK"
  }
}

If a key does not support hot-update or is invalid, the response includes an error message for that key:

JSON
{
  "results": {
    "Unknown.Key": "Unknown.Key does not support hot update."
  }
}

A single request can contain a mix of valid and invalid keys; each key's result is returned independently.

NOTE

Hot-updated values are in-memory only and are not persisted to config files. Values are lost on server restart. To make permanent changes, edit the server config files directly.

Cross-Server Updates

Use key prefixes to route configuration updates to Shard Servers or Meta Servers through the Name Server:

A single POST request can contain keys for all three server types:

Bash
curl -X POST http://<name-server-host>:9091/config \
  -H 'Content-Type: application/json' \
  -d '{
    "Server.slow_query": "3000",
    "Shard.Log.file_retain_counts": "10",
    "Meta.Server.real_time_sync_meta_to_shards": "true"
  }'

Hot-Updatable Configuration Keys

Name Server Keys

NOTE

Changing any SSO key triggers an SSO authenticator reload.

Shard Server Keys

These keys use the Shard. prefix when sent to the Name Server HTTP API.

Meta Server Keys

These keys use the Meta. prefix when sent to the Name Server HTTP API.

Storage Engine Configuration

The storage engine configuration is set in shard-server.config under the [StorageEngine] section. Some parameters support hot-update via the HTTP Config API using the Shard.StorageEngine. prefix.

Hot-Updatable Parameters

Example

Bash
curl -X POST http://<name-server-host>:9091/config \
  -H 'Content-Type: application/json' \
  -d '{
    "Shard.StorageEngine.max_background_flushes": "4",
    "Shard.StorageEngine.compression": "lz4",
    "Shard.StorageEngine.block_cache_size": "2048"
  }'

Restart-Only Parameters

The following parameters require a server restart to take effect:

High-Performance Configuration Template

Ini
[StorageEngine]
db_buffer_size = 512
max_db_buffer_number = 5
enable_block_cache = true
block_cache_size = 4096

# Background threads
max_background_flushes = 4
max_background_compactions = 8

# Compaction triggers
level0_file_num_compaction_trigger = 8
level0_slowdown_writes_trigger = 40
level0_stop_writes_trigger = 64
max_bytes_for_level_base = 512
target_file_size_base = 128

# Compression: lz4 for speed, zstd for bottom level
compression = lz4
bottommost_compression = zstd

# Periodic sync to avoid I/O spikes
bytes_per_sync = 1048576
wal_bytes_per_sync = 524288

# Pipelined write + write buffer merge
enable_pipelined_write = true
min_write_buffer_number_to_merge = 2

# Larger block size to reduce index overhead
block_size = 16
cache_index_and_filter_blocks = true