meta.flexfs

meta.flexfs is the metadata server that stores inodes, directory entries, attributes, extended attributes, and ACLs for one or more flexFS volumes. Mount clients communicate with it over an RPC protocol, and utilities like analyze.flexfs and find.flexfs use its REST API.

Subcommands

| Subcommand | Description | |---|---| | deinit creds | Remove the credentials file | | deinit systemd | Remove the systemd service unit | | init creds | Initialize the credentials file | | init systemd | Create and enable a systemd service unit | | license | Print license information | | migrate | Run database migrations | | missing-objects | Report meta-tracked block keys absent from the block store | | start | Start the metadata server | | verify | Verify database integrity | | version | Print the build version |

Caution

The verify, migrate, and missing-objects subcommands are internal and should only be used under guidance from Paradigm4 support.

Usage

meta.flexfs start [flags]

Persistent Flags

These flags apply to all subcommands:

| Flag | Type | Default | Description | |---|---|---|---| | --credsFile | string | ~/.flexfs/meta/creds | Credentials file path | | --dbFolder | string | ~/.flexfs/meta/data | Database folder path |

Start Flags

| Flag | Type | Default | Description | Visibility | |---|---|---|---|---| | --adminAddr | string | | Admin server address (overrides creds file) | Internal | | --bindAddr | string | 0.0.0.0:443 | Address and port to bind | Public | | --blockPass | string | | Block storage password (overrides creds file) | Internal | | --blockUser | string | | Block storage username (overrides creds file) | Internal | | --dbMemCapacity | string | 50% | Database memory cache capacity (e.g. 5%, 64M) | Internal | | --fallback | string | | Fallback RPC version for old clients (e.g. v1.4) | Internal | | --noAdminSSL | bool | false | Disable SSL for admin server connections | Internal | | --noSSL | bool | false | Disable SSL for the REST API | Public | | --pprof | bool | false | Enable pprof profiler | Internal | | --pprofPort | int | 6062 | Pprof server port | Internal | | --sizeBins | bool | false | ~~Deprecated~~ — size bins are now always enabled | Internal | | --sslCert | string | ~/.flexfs/ssl/cert | SSL certificate file path | Public | | --sslKey | string | ~/.flexfs/ssl/key | SSL private key file path | Public | | --sync | bool | false | Fsync every write for full crash durability | Public | | --token | string | | Metadata server auth token (overrides creds file) | Internal | | --verbose, -v | bool | false | Enable verbose logging | Public |

Init Creds

meta.flexfs init creds [flags]

Initializes a credentials file for the metadata server. If --token is omitted, the command prompts for a metadata server token interactively.

| Flag | Type | Default | Description | |---|---|---|---| | --adminAddr | string | "" | Admin server address | | --blockPass | string | "" | Block storage password | | --blockUser | string | "" | Block storage username | | --force | bool | false | Overwrite existing creds file | | --token | string | "" | Metadata server auth token (will prompt if omitted) |

Init Systemd

sudo meta.flexfs init systemd [flags]

Creates and enables a systemd service unit (flexfs-meta.service) for the metadata server. Requires root.

| Flag | Type | Default | Description | |---|---|---|---| | --force | bool | false | Overwrite existing systemd unit file | | --now | bool | false | Start the service immediately after enabling | | --startFlags | string | "" | Additional flags to pass to the start command |

Deinit Creds

meta.flexfs deinit creds [flags]

Removes the credentials file for the metadata server. If the credentials file is referenced by a systemd unit, the command refuses unless --force is passed, in which case it removes the references too.

| Flag | Type | Default | Description | |---|---|---|---| | --force | bool | false | Remove creds even if referenced by systemd (removes references too) |

Deinit Systemd

sudo meta.flexfs deinit systemd

Removes the systemd service unit (flexfs-meta.service) for the metadata server. Requires root.

Verify (Internal)

Caution

This subcommand is internal and should only be used under guidance from Paradigm4 support.

meta.flexfs verify [volume-id] [flags]

Verifies the integrity of the metadata database by comparing stored counters, dentries, and size bins against actual data. If a volume ID is provided, only that volume is verified; otherwise all volumes are checked.

| Flag | Type | Default | Description | |---|---|---|---| | --fix | bool | false | Fix mismatched counts by recomputing from actual data |

Migrate (Internal)

Caution

This subcommand is internal and should only be used under guidance from Paradigm4 support.

meta.flexfs migrate [flags]

Migrates volume data from the legacy snapshot format to the current database format.

| Flag | Type | Default | Description | |---|---|---|---| | --srcFolder | string | ~/.flexfs/meta/data | Source data folder |

Missing Objects (Internal)

Caution

This subcommand is internal and should only be used under guidance from Paradigm4 support.

meta.flexfs missing-objects [volume-id] [flags]

For each block key tracked by meta (live and/or retired), HEADs the corresponding object in the block store and reports any that are missing. Runs offline against the Pebble database, so the meta service must be stopped (Pebble lock); contacts the admin server to fetch per-volume block settings, so the admin server must be reachable. If a volume ID is provided, only that volume is scanned; otherwise all volumes are scanned.

| Flag | Type | Default | Description | |---|---|---|---| | --concurrency | int | 32 | Number of parallel HEAD requests | | --live-only | bool | false | Only check live block keys | | --retired-only | bool | false | Only check retired block keys | | --noAdminSSL | bool | false | Disable SSL for admin server connections |

Credentials File

The credentials file is a TOML file with connection details populated during init creds:

adminAddr = "admin.example.com:443"
token = "$TOKEN"
blockUser = "$USERNAME"
blockPass = "$PASSWORD"

REST Endpoints

The metadata server exposes the following REST endpoints for utilities and monitoring:

| Endpoint | Method | Description | |---|---|---| | /analyze/files | GET | Top files by size or cost | | /analyze/folders | GET | Per-directory recursive size and cost | | /analyze/users | GET | Per-user size and cost | | /duplicates | GET | Duplicate file candidates | | /find | GET | Filesystem search | | /metrics | GET | Prometheus metrics | | /status | GET | Server health status |