Requirements

FlexBlock has a short list of hard requirements on the serving host, the cache device and the object store. Check them before installing. The preflight in start checks most of them again for you.

Serving host

Requirement	Detail
Linux kernel	6.1 or newer, with the ublk_drv module loaded and /dev/ublk-control present. The driver must advertise user recovery (UBLK_F_USER_RECOVERY and UBLK_F_USER_RECOVERY_REISSUE), which is what makes a daemon crash survivable.
io_uring	Enabled. Where the sysctl kernel.io_uring_disabled exists (Linux 6.6 and later), it must not be 2.
Architecture	x86_64 or aarch64. The binaries are statically linked; TLS to object storage needs only the system CA certificate store (the ca-certificates package).
Privileges	start and reap drive /dev/ublk-control and need root. attach, detach, update, wipe and init --attach need write access to the cache device, which in practice also means root. update while the daemon serves also needs root. init without --attach touches no device, and show needs only read access.
Runtime state	A writable /run.
Clock	A plausible system clock. Request signing, TLS and license checks depend on it.
Memory	Enough free memory for the transfer buffers, the I/O buffers and cache metadata; see Memory. The preflight refuses when what it reserves at start exceeds half of what is available, unless --allow-overmemory is given or the cache holds unflushed chunks.

Check the kernel prerequisites:

sudo modprobe ublk_drv
ls -l /dev/ublk-control
sysctl kernel.io_uring_disabled

Newer kernels

Three kernel features are detected at start and used when present. None is required.

Kernel	Feature	What it gives you
6.15 or newer	IORING_ENTER_NO_IOWAIT	Idle queue threads do not count as iowait. On older kernels an idle volume can show high iowait in top even though nothing is waiting on storage.
6.16 or newer	UBLK_F_AUTO_BUF_REG	Requests are served with zero copy, using less daemon CPU for large I/O.
6.16 or newer	UBLK_U_CMD_UPDATE_SIZE	update --device-size grows the live device while it serves. On older kernels you grow offline; see Growing a Volume.

Cache device

The cache needs a dedicated block device or partition, ideally NVMe. It must not be mounted, used as swap, or held by device-mapper, and flexblock checks all three before writing to it. A regular file also works, which is convenient for evaluation and testing (see Evaluating Without Hardware).

Ephemeral instance storage is a natural fit. The local NVMe on storage-optimized cloud instances is fast and included in the instance price, but its contents are lost when the instance stops or is replaced. As a flexBlock cache it needs no durability of its own: everything it holds is either already in the bucket or on its way there.

What is at risk when such an instance disappears without a clean stop is only the write-back window: the acknowledged writes that had not yet been flushed. --flush-threshold holds that to about four minutes by default while uploads keep up with writes (eight for a chunk under continuous writes, see --flush-quiet). A write burst faster than the bucket absorbs, or a backlog recovered after a crash, stretches it until the backlog drains, and the flexblock_cache_oldest_dirty_age_seconds metric reports it at any moment. A replacement instance attaches the same volume, with --take-ownership if the old one could not detach, and serves it from a cold cache.

Not a point-in-time copy

The bucket is not a point-in-time copy of the volume. Chunks upload one at a time as they age, and a filesystem flush only reaches the cache device, so after an abrupt loss of the cache the bucket holds each chunk as it was last uploaded: recent writes to different chunks may be only partly present. Expect the filesystem to replay its journal or need a repair (xfs_repair, fsck), and verify databases before trusting them. See Where Data Can Be Lost.

The cache can be much smaller than the volume. Its size determines how much of the volume can be hot at once, and how much dirty data can accumulate before writes wait for write-back. The minimum is one chunk plus about 332 KiB of metadata. A cache that is a meaningful fraction of the working set is what gives local-SSD performance.

Use a partition, not a whole disk, when you can

A partition table makes the cache device’s purpose visible to other tools and administrators. FlexBlock does not need it, but it prevents a future “unused disk” from being reformatted under a live cache.

Object storage and credentials

The grant names the object storage provider, one of S3, GCS, Blob or OCI, together with the bucket or container, prefix, endpoint and region. None of them is passed on the command line, and neither are credentials. Each provider is driven through its native API: reads, plain and conditional (create-if-absent, compare-and-swap) writes, prefix listing, and single or batch deletes.

Credentials come from each provider’s own credential chain, so the common identities that work for the vendor’s tools work for flexBlock; Credentials and the per-provider pages list exactly which are supported.

Provider	Credential chain
S3	The AWS default chain: AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, AWS_PROFILE with the shared config files, web identity, or the container or instance role. Any S3-compatible store with conditional PUTs (If-None-Match and If-Match) works; its endpoint and path style are set in the grant.
GCS	Application Default Credentials: GOOGLE_APPLICATION_CREDENTIALS (a key or workload identity federation file), the gcloud application-default credentials, or the instance metadata server. An http:// endpoint with no GOOGLE_APPLICATION_CREDENTIALS is an emulator and is used anonymously.
Blob	AZURE_STORAGE_KEY for a shared key; otherwise Entra ID: a service principal from AZURE_TENANT_ID, AZURE_CLIENT_ID and AZURE_CLIENT_SECRET, workload identity from AZURE_FEDERATED_TOKEN_FILE, a managed identity, then an Azure CLI or Azure Developer CLI login. The grant carries the storage account.
OCI	OCI_CLI_AUTH picks api_key, security_token, instance_principal or resource_principal. Unset, a resource principal is used when OCI_RESOURCE_PRINCIPAL_VERSION is set, otherwise the profile in ~/.oci/config (OCI_CLI_CONFIG_FILE, OCI_CLI_PROFILE) when that file exists, and an instance principal otherwise. The grant carries the namespace.

The identity needs permission to list, get, put (including overwrite) and delete objects under the prefix, singly and in batches; init, attach and start check all of these. init and attach also check that the store enforces conditional writes, and refuse one that does not.

Server-side encryption is provider managed, except on S3, where SSE-S3 is requested by default and init --s3-no-sse turns it off for stores that reject the header. The choice is recorded on the volume.

The prefix the grant names must be empty when you create the volume: init refuses a prefix that already holds objects.

Next steps

• Install the binary and the grant.
• Credentials: what the identity needs, per provider.