# Configuration & Tuning This page covers the settings most worth knowing and when to change them. Beta Cloud Disk is in beta and under active development. Settings are stored with the disk and apply wherever it's mounted. Change them any time: ``` cloud-disk config mydata set flush-workers=16 cloud-disk config mydata show cloud-disk config mydata unset flush-workers ``` While a disk is mounted, performance settings apply immediately, and `config set` tells you which ones; the rest take effect on the next mount. The defaults cover most deployments, so you'll usually change only a few of these. ## At create time[​](#at-create-time "Direct link to At create time") | Option | Example | Description | | ----------------- | ------- | ------------------------------------------------------------------------- | | `-size` | `100G` | Disk size (`500M`, `1G`, `2T`). Sparse — only written data costs storage. | | `-fstype` | `xfs` | Filesystem for the disk: `ext4` (default), `xfs`, `btrfs`. | | `--set key=value` | | Apply any setting below at create time (repeatable). | | `--no-mount` | | Create only; don't mount. | ## Performance — the high-impact knobs[​](#performance--the-high-impact-knobs "Direct link to Performance — the high-impact knobs") | Setting | Default | When to raise it | | --------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `max-cache-size` | `1G` | The in-RAM cache. Raise it so your working set fits — fewer reads go to Tigris. For read-heavy workloads, a meaningful fraction of RAM (`4G`, `16G`). | | `flush-workers` | `8` | Concurrent uploads to Tigris. Raise (`16`–`32`) for **write-heavy** workloads. | | `read-ahead-workers`, `read-ahead-max-window` | `4` / auto | Prefetching for sequential reads. Raise the window for **streaming / scan-heavy** workloads; set workers to `-1` to disable prefetching. | | `connections` | CPU count | Parallel device connections. Usually leave alone; lower it on small machines sharing many disks. | ## Local disk cache[​](#local-disk-cache "Direct link to Local disk cache") A cache on local disk (SSD) between RAM and Tigris: reads that miss the RAM cache are served from local disk instead of Tigris, and write-back uses it to buffer writes. | Setting | Default | Description | | ----------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `disk-cache-path` | `/var/lib/cloud-disk` | Local directory for the cache and write-back buffer. Each disk uses its own subdirectory, so one path is safe to share (and to inherit on forks). | | `disk-cache-size` | `0` | How much local disk the read cache may use, e.g. `4G`, `100G`. `0` (the default) turns the read cache off while keeping write-back buffering; size it to your working set for the biggest read speedup. | ## Cache warming on mount[​](#cache-warming-on-mount "Direct link to Cache warming on mount") On mount the disk preloads its index and the data at the start of the disk into cache, so the first reads are fast instead of all going to Tigris. This happens in the background — it never delays the mount; the disk serves immediately and warming fills the cache as it runs. Both are on by default and self-limiting — warming never loads more than your cache can hold, counting the RAM cache (`max-cache-size`) and the local disk cache (`disk-cache-size`) together. | Setting | Default | When to change | | -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `warm-start-bytes` | `1G` | How much data from the start of the disk to preload into cache on mount (unwritten regions are skipped). Capped to the combined RAM + local-disk cache size, so it never evicts what it just loaded. Lower it to reduce background fetching after mount; `0` preloads no data (the index is still prewarmed — see below). | | `prewarm-region-map` | `true` | Preload the disk's index up front so reads don't pause for lookups. Cheap — leave on. Set `false` on a very large disk to skip it. | ## Write-back[​](#write-back "Direct link to Write-back") Write-back buffers writes locally and uploads in the background — much faster. Everything is flushed to Tigris on unmount. | Setting | Default | Effect | | ---------------------- | ------- | ---------------------------------------------------------------------------------------------- | | `write-back` | `true` | On by default. Set `false` for write-through (every `fsync` lands in Tigris before returning). | | `max-staging-bytes` | `1G` | Write buffer budget. Raise (`16G`) for bursty write-heavy workloads. | | `max-dirty-ratio` | `0.5` | How full the cache gets before background uploading starts. Lower = upload sooner. | | `sync-writeback-ratio` | `0.8` | How full the cache gets before writes pause for the upload to catch up. `0` disables. | ## Unmount durability[​](#unmount-durability "Direct link to Unmount durability") What a clean unmount does with buffered data before finishing, via `shutdown-mode`: | Mode | Behavior | | ---------- | ----------------------------------------------------------------------------------------------------- | | `remote` | **(default)** Upload everything to Tigris — the bucket is the complete disk. Safest; slowest unmount. | | `local` | Save to local disk only; the next mount finishes the upload. Faster unmount. | | `dirty` | Exit fast. For quick restarts on the same machine. | | `ship-wal` | Like `remote`, plus uploads the recovery log for another machine to take over. | ## Reliability[​](#reliability "Direct link to Reliability") | Setting | Default | When to change | | --------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `retry-max-retries` | `30` | How many times object-store operations retry before reporting an error. The default rides out \~2 minutes of unavailability. | | `nbd-request-timeout` | kernel default (\~30s) | How long a single disk I/O may take before the kernel gives up on it. Raise (`600s`) for slow links or heavily loaded disks. | ## Filesystem & mount[​](#filesystem--mount "Direct link to Filesystem & mount") | Setting | Default | Description | | ------------- | ------------------------ | --------------------------------------------------------------------------------------- | | `fstype` | `ext4` | Filesystem created on first mount (ext4, xfs, btrfs). | | `mount-point` | `/mnt/cloud-disk/` | Where the disk is mounted. Set it on a fork so parent and fork can be mounted together. | | `mount-opts` | — | Extra mount options, e.g. `noatime`. | | `readonly` | off | `true` mounts the disk read-only. | ## Observability[​](#observability "Direct link to Observability") | Setting | Default | Description | | ------------------------ | -------------------------------------------- | -------------------------------------------------- | | `metrics-addr` | — | Expose Prometheus metrics, e.g. `:9090`. | | `stats-interval` | — | Log periodic throughput/latency stats, e.g. `10s`. | | `log-file`, `log-format` | `/var/log/cloud-disk-.log` / `console` | Log destination and format (`console` or `json`). | ## Example: tuned for a database[​](#example-tuned-for-a-database "Direct link to Example: tuned for a database") ``` sudo -E cloud-disk create pg-data -size 200G \ --set disk-cache-size=100G \ --set max-cache-size=16G \ --set flush-workers=16 \ --set max-staging-bytes=16G \ --set metrics-addr=:9090 ```