Filesystem

The filesystem backend stores each blob of the blob store as a file in a directory. It serves single-node installations that want to keep the database small by placing message contents on a separate volume. Because the blobs are ordinary files, ordinary file system tools can also back them up.

Configuration

The backend is selected with the FileSystem variant of the BlobStore object (found in the WebUI under Settings › Storage › Blob Store). path is the directory in which blobs are written, and it is created if it does not exist.

A single directory holding every blob would grow to an unmanageable number of files. The files are therefore distributed among nested subdirectories, named after the leading bytes of each blob’s identifier. depth sets the number of directory levels, at most 5. Each level has up to 256 subdirectories, so two levels already spread the blobs over up to 65,536 directories.

The depth must not change once blobs have been written. The location of every existing blob is derived from the depth in force when it was written, so after a change the server would look for those blobs in the wrong place and no longer find them.

The following blob store keeps blobs under /var/lib/stalwart/blobs:

{
  "@type": "FileSystem",
  "path": "/var/lib/stalwart/blobs",
  "depth": 2
}

Restrictions

The directory belongs to one node. Several nodes can share a filesystem blob store only when the directory is on a shared file system that every node mounts at the same path. Without one, a cluster uses an S3-compatible or Azure blob store.

A filesystem blob store also cannot hold the snapshots of cache swapping. On a server with this blob store, cache swapping uses either the LocalFile backend, which writes snapshots to a local directory, or Redis.