Volume Management

Note

Volume management via configure.flexfs is an Enterprise-only feature. Community edition supports a single pre-configured volume created during free.flexfs init creds.

A volume is the fundamental unit of storage in flexFS. Each volume is an independent filesystem backed by a block store (object storage bucket) and a metadata store (metadata server). Mount clients authenticate with a volume token and mount the volume as a POSIX filesystem.

Creating a Volume

configure.flexfs create volume \
  --name my-volume \
  --metaStoreID 1 \
  --blockStoreID 1 \
  --blockSize 4MiB \
  --compression lz4 \
  --retention 7d

Volume Fields

Field	Flag	Type	Default	Description
name	--name	string	(required)	Human-readable volume name
meta_store_id	--metaStoreID	integer	(required)	Metadata store to use for this volume
block_store_id	--blockStoreID	integer	(required)	Block store to use for this volume
id	--id	string	(auto-generated)	Volume UUID; auto-generated if omitted
block_size	--blockSize	string	4MiB	Block size for file data (see Block Size)
compression_algo	--compression	string	lz4	Compression algorithm (see Compression)
encryption	--encryption	boolean	false	Enable end-to-end encryption (see Encryption)
retention	--retention	string	7d	Data retention period (see Retention)
max_blocks	--maxBlocks	integer	0	Maximum block count; 0 = unlimited
max_inodes	--maxInodes	integer	0	Maximum inode count; 0 = unlimited
max_proxied	--maxProxied	integer	0	Maximum proxied blocks per file; 0 = unlimited
flags	--flags	string	(empty)	Comma-separated mount flags
notes	--notes	string	(empty)	Free-form notes

Block Size

The block size determines how file data is divided into blocks stored in object storage. It is set at volume creation and cannot be changed afterward.

Accepted values use human-readable suffixes: 256KiB, 512KiB, 1MiB, 2MiB, 4MiB, 8MiB (or plain byte counts). The suffix is case-insensitive and supports KiB, MiB, GiB, KB, MB, GB, K, M, G forms.

Block Size	Best For
256KiB - 512KiB	Small files, random I/O patterns
1MiB - 2MiB	Mixed workloads
4MiB (default)	General purpose, large sequential reads
8MiB	Very large files, streaming workloads

Larger block sizes reduce the number of object storage requests for sequential reads but increase the minimum read/write granularity. Smaller block sizes improve random I/O at the cost of more metadata overhead.

Compression

Compression is applied to each block before it is stored in object storage. Choose an algorithm at volume creation:

Algorithm	Flag Value	Characteristics
LZ4	lz4 (default)	Very fast compression and decompression; moderate ratio
Snappy	snappy	Fast, lightweight; slightly lower ratio than LZ4
Zstandard	zstd	Higher compression ratio; somewhat slower
None	none	No compression; lowest CPU usage

Compression is set at volume creation and cannot be changed afterward.

End-to-End Encryption

When --encryption is set to true, all block data and metadata values are encrypted end-to-end with AES-256 before leaving the mount client. The encryption key is derived from a passphrase using Argon2id and never leaves the client.

Caution

End-to-end encryption cannot be enabled after volume creation. Once a volume is created without it, its blocks cannot be retroactively encrypted.

After creating an encrypted volume, mount clients must provide the encryption secret when mounting. See End-to-End Encryption for setup details.

Retention

Retention controls how long deleted data is preserved before being permanently purged. This applies to both metadata (inodes, directory entries, attributes) and block data in object storage. During the retention period, deleted or overwritten files remain accessible via time-travel mounting.

The --retention flag accepts several formats:

Format	Example	Description
Duration with d suffix	7d	7 days
Go duration string	168h, 168h30m	Standard duration
Combined	7d6h30m	7 days, 6 hours, 30 minutes
Seconds	604800	Plain number of seconds
Forever	forever or -1	Never purge deleted data

The default retention is 7d (7 days / 604800 seconds).

Tip

Longer retention periods increase metadata storage requirements. Use forever only when compliance or audit requirements demand indefinite history.

Retention can be changed on an existing volume with update:

configure.flexfs update volume my-volume --retention 30d

Quotas

Volumes support three types of quotas to control resource usage:

Block Quota (--maxBlocks)

Limits the total number of data blocks stored in the volume. Each block is blockSize bytes, so the effective storage limit is maxBlocks * blockSize. A value of 0 means unlimited.

Inode Quota (--maxInodes)

Limits the total number of files and directories (inodes) in the volume. A value of 0 means unlimited.

Proxy Block Quota (--maxProxied)

Limits the maximum number of blocks that can be cached on proxy servers for any single file in this volume. This controls proxy cache consumption for volumes with very large files. A value of 0 means unlimited.

Volume Flags

The --flags field sets default mount flags for all mounts of this volume. Multiple flags are comma-separated:

configure.flexfs create volume --name secure-vol \
  --metaStoreID 1 --blockStoreID 1 \
  --flags "ro,noatime,acl,xattr"

Common flags:

Flag	Description
ro	Mount the volume read-only
noatime	Do not update access times
acl	Enable extended ACL support
xattr	Enable extended attribute support
noExec	Prevent execution of binaries
noSUID	Ignore set-user-ID and set-group-ID bits

Flags set at the volume level apply to all mounts. They can be further restricted (but not relaxed) at the volume token level.

Updating a Volume

Update mutable fields on an existing volume:

configure.flexfs update volume my-volume \
  --maxBlocks 1000000 \
  --maxInodes 500000 \
  --notes "Production data volume"

Updatable fields: metaStoreID, blockStoreID, name, maxBlocks, maxInodes, maxProxied, flags, retention, notes.

Block size, compression, and end-to-end encryption cannot be changed after creation.

Viewing Volumes

configure.flexfs list volumes
configure.flexfs show volume my-volume

The show command displays full details including the associated account, metadata store address, and block store endpoint. Volumes can be referenced by name or UUID.

Retiring a Volume

Deleting a volume retires it rather than permanently removing data:

configure.flexfs delete volume my-volume

The volume’s retired_at timestamp is set and it becomes unavailable for new mounts. Block data remains in object storage until explicitly cleaned up or the retention period expires.