stat.flexfs

Caution

This entire page documents an internal component. stat.flexfs is the billing and metering server operated by Paradigm4. It is not intended for customer deployment.

stat.flexfs collects usage statistics from admin servers, stores them in its database, and sends periodic usage reports via SMTP. In the monthly report email, customers billed by someone else, such as AWS Marketplace customers, are listed in a separate section per biller with its own total, are not included in the invoicing total, and their report files are placed in a billed-by-<biller> folder in the attached archive. A biller’s section is omitted in months where its customers have no cost. It also manages license grants that are returned to admin servers as part of the stats relay flow.

Persistent Flags

These flags apply to every subcommand.

Flag	Type	Default	Description	Visibility
--reportErrors	bool	false	Report errors and panics to Paradigm4	Public

Subcommands

Subcommand	Description	Visibility
deinit creds	Remove the credentials file	Public
deinit systemd	Remove the systemd service unit	Public
init creds	Initialize the credentials file	Public
init systemd	Create and enable a systemd service unit	Public
license	Print license information	Public
start	Start the statistics server	Public
version	Print the build version	Public

deinit creds

stat.flexfs deinit creds [flags]

Removes the credentials file for the stat 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	Visibility
--credsFile	string	~/.flexfs/stat/creds	Credentials file path	Public
--force	bool	false	Remove creds even if referenced by systemd (removes references too)	Public

deinit systemd

sudo stat.flexfs deinit systemd

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

init creds

stat.flexfs init creds [flags]

Initializes a credentials file for the stat server with SMTP settings for usage reports. init on its own does the same thing as init creds.

Flag	Type	Default	Description	Visibility
--credsFile	string	~/.flexfs/stat/creds	Credentials file path	Public
--force	bool	false	Overwrite existing credentials file	Public
--marketplaceToken	string	""	Marketplace API token, at least 32 characters with no spaces (prompted for on a terminal if omitted; leave empty to disable the marketplace API)	Public
--smtpAddr	string	""	SMTP server address (required)	Public
--smtpFrom	string	""	SMTP from email address (required)	Public
--smtpPass	string	""	SMTP server password (will prompt if omitted and a username is set)	Public
--smtpTo	string	""	SMTP to email addresses (comma-separated; required)	Public
--smtpUser	string	""	SMTP server username (required only for authenticated relays)	Public

init systemd

sudo stat.flexfs init systemd [flags]

Creates and enables a systemd service unit (flexfs-stat.service) for the stat server. Requires root. Optional: the server can also be run directly with start by any user. The service runs as root, so it uses root’s /root/.flexfs defaults, credentials included, unless --startFlags names other paths.

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

start

stat.flexfs start [flags]

Starts the statistics server, binding the endpoint that admin servers relay usage to. Any user can run it, and ~ in the defaults is that user’s home folder. A non-root user needs a --bindAddr port above 1023.

Flag	Type	Default	Description	Visibility
--bindAddr	string	0.0.0.0:443	Address and port to bind	Public
--credsFile	string	~/.flexfs/stat/creds	Credentials file path	Public
--dbFolder	string	~/.flexfs/stat	Database folder path	Public
--keyFolder	string	~/.flexfs/license	Signing key folder path	Public
--marketplaceToken	string	""	Marketplace API token (overrides credentials file)	Internal
--mockTime	bool	false	Simulate time as 5 minutes after last reported_at	Internal
--noSSL	bool	false	Serve the stat endpoint over plain HTTP	Public
--pprof	bool	false	Enable pprof profiler	Internal
--pprofPort	int	6067	Pprof server port	Internal
--smtpAddr	string	""	SMTP server address (overrides credentials file)	Internal
--smtpFrom	string	""	SMTP from email address (overrides credentials file)	Internal
--smtpPass	string	""	SMTP server password (overrides credentials file)	Internal
--smtpTo	string	""	SMTP to email addresses (overrides credentials file)	Internal
--smtpUser	string	""	SMTP server username (overrides credentials file)	Internal
--sqliteOpts	string	_journal=WAL&_cache_size=10240&_fk=true&_timeout=5000	SQLite database connection options	Internal
--sslCert	string	~/.flexfs/ssl/cert	SSL certificate file path. A self-signed certificate and key are created if neither exists.	Public
--sslKey	string	~/.flexfs/ssl/key	SSL private key file path	Public
--verbose, -v	bool	false	Enable verbose logging	Public

Hourly statistics

Metadata servers report volume statistics at the top of each hour, and admin servers relay them to the stat server. With each relay attempt, admin servers send a Report-Age header with the number of seconds since they received the report. The stat server subtracts that from its own clock, so reports delayed by relay retries or outages of up to 24 hours are recorded under the correct hour regardless of the reporting host’s clock. Reports without the header, or older than 24 hours, are filed by their arrival time instead. AWS Marketplace metering meters each hour about 2 hours after it ends, so it includes reports for that hour that arrive by then.

A report is filed under an hour if its time falls from 10 minutes before that hour until 50 minutes after it, so a report at 09:59:58 or 10:03:00 is recorded as the 10:00 report. A warning is logged when a report’s time is more than 2 minutes before the hour, which usually means the reporting host’s clock is fast.

Only one report per volume is recorded for each hour. A repeated report for the same hour, such as a retry, replaces the earlier one and is answered normally. A volume listed more than once in the same report is recorded once, from its last entry, and a warning is logged.

The monthly report email is sent at 03:01 UTC on the 1st, after late reports for the previous month’s last hours have arrived.

Grants and suspended customers

Admin servers post usage to POST /v1/stats and receive a license grant valid for 7 days in return, signed with the private.pem in --keyFolder. If that file is missing or cannot be used, the statistics are still recorded and the request is answered with 204 and no grant. A customer can have grants suspended through the marketplace API. A suspended customer’s statistics are still recorded, but the request is answered with 403 and no grant, so the customer’s volumes become read-only once the current grant expires. The Enterprise installer reports this as subscription is not active.

Usage report endpoint

GET /v1/reports generates and emails the monthly usage reports on demand. It only accepts requests made directly to the stat server from the same host (a loopback address with no X-Forwarded-For, X-Real-IP, or Forwarded header) and answers 403 otherwise. When the stat server runs behind a reverse proxy on the same host, the proxy must set X-Real-IP or X-Forwarded-For on every request it forwards.

Marketplace API

Marketplace integration servers such as aws.flexfs use these endpoints to manage customers. They are enabled only when marketplaceToken is set, and every request must send Authorization: Bearer <marketplaceToken>. With no token configured, they answer 503. The grants and usage endpoints only act on customers created with a billed_by value, and answer 404 for any other customer, so the token cannot affect directly invoiced customers.

Endpoint	Body	Response	Description
POST /v1/customers	{"billed_by": "AWS Marketplace", "id": "<uuid>", "name": "...", "rate_bins": {"0": 0.10}}	201 {"id": "<license key>"}, or 200 if a customer with that id exists	Create a customer; name, billed_by (who bills the customer), and a positive rate bin 0 are required; id (a lowercase UUID) is optional and makes the request safe to repeat
PUT /v1/customers/{id}/grants	{"suspended": true}	204	Suspend or resume license grants for a customer; suspended is required
GET /v1/customers/{id}/usage?from=<unix>&to=<unix>		200 [{"cost": 0.0, "hour": 0, "size": 0, "units": 0.0}]	Hourly cost, size, and hot-equivalent GiB-months summed across volumes, for hours in [from, to); hours without statistics are omitted; the range is limited to 31 days

units is each report’s cost divided by the bin 0 rate of the rate bins recorded with that report, so cold data counts as a fraction of a hot GiB-month and the result does not depend on the absolute rates. For a report whose bin 0 rate is 0, units is its size in GiB-months without tier weighting.