Metadata Server Overview
The metadata server (meta.flexfs) is the central component that stores and manages all filesystem metadata — inodes, directory entries, file attributes, extended attributes, ACLs, and file locks. It serves as the coordination point for all mount clients accessing a volume.
The metadata server:
- Stores filesystem structure — All inodes, directory entries (dentries), file attributes (size, timestamps, permissions), extended attributes, and access control lists are persisted in the metadata database.
- Serves mount clients via RPC — Mount clients establish persistent RPC sessions with the metadata server. All filesystem operations (open, read, write, mkdir, unlink, rename, etc.) are coordinated through these sessions.
- Serves utilities via REST — Utilities like
analyze.flexfs,find.flexfs, anddedup.flexfscommunicate with the metadata server over its REST API to query and analyze volume contents. - Manages block lifecycle — The metadata server tracks which blocks belong to which files, manages block retention for time-travel capabilities, and coordinates garbage collection of unreferenced blocks.
- Reports to the admin server — The metadata server periodically reports volume statistics (size, inode count, session count) to the admin server.
Protocols
Section titled “Protocols”RPC (mount clients)
Section titled “RPC (mount clients)”Mount clients connect to the metadata server over a persistent RPC session. The RPC protocol supports:
- Filesystem operations (lookup, getattr, setattr, create, mkdir, unlink, rename, link, symlink, readdir, etc.)
- File locking (fcntl/flock)
- Extended attributes (getxattr, setxattr, listxattr, removexattr)
- ACL operations
- Session management (connect, disconnect, heartbeat)
The RPC protocol version is negotiated at session establishment, allowing the metadata server to serve mount clients running different versions simultaneously (within compatibility bounds).
REST (utilities and admin)
Section titled “REST (utilities and admin)”The metadata server exposes an HTTP REST API for:
| Endpoint | Description |
|---|---|
/find | Search for files by name, path, size, or modification time |
/analyze/files | Analyze volume contents by file type and size |
/analyze/folders | Analyze folder sizes and file counts |
/analyze/users | Analyze storage usage per user |
/duplicates | Find duplicate files for deduplication |
/metrics | Prometheus metrics endpoint |
/status | Server health check |
Relationship to volumes
Section titled “Relationship to volumes”Each metadata server instance serves one or more volumes. The mapping between metadata servers and volumes is managed by the admin server. When a mount client presents a volume token, the admin server directs it to the appropriate metadata server.
High availability
Section titled “High availability”The metadata server is a single-instance service per volume group. It is not horizontally scaled. High availability is achieved through:
- Systemd auto-restart — The systemd service unit is configured with
Restart=always. - Database durability — The metadata database persists to disk. After a crash or restart, the server recovers from its on-disk state.
- Mount client reconnection — Mount clients automatically retry connections to the metadata server when it becomes temporarily unavailable.