configure.flexfs

Note

configure.flexfs is an Enterprise-only tool. It is not available in the Community edition.

configure.flexfs is the management CLI for flexFS Enterprise. It provides CRUD operations on all admin server resource types, communicating with the admin server over its REST API.

The tool follows a verb/resource model: a verb subcommand (create, delete, list, show, or update) is paired with a <resource> and, for create and update, a set of --field flags. The init creds, deinit creds, license, and version subcommands manage credentials and print build metadata.

It runs in two modes. When run without arguments from a terminal, it starts an interactive REPL with tab completion and command history:

configure.flexfs> list volumes
configure.flexfs> show volume <volume-name>
configure.flexfs> create volume --name test --metaStoreID 1 --blockStoreID 1
configure.flexfs> exit

Commands can also be run directly from the shell in single-command mode:

configure.flexfs list volumes --json
configure.flexfs create volume --name test --metaStoreID 1 --blockStoreID 1

Persistent Flags

These flags apply to every subcommand.

Flag	Type	Default	Description	Visibility
--adminAddr	string	""	Admin server address (overrides credentials file)	Internal
--credsFile	string	~/.flexfs/configure/creds	Credentials file path	Public
--json	bool	false	Output results as JSON (create, list, and show only)	Public
--noAdminSSL	bool	false	Disable SSL for admin server connections	Internal
--reportErrors	bool	false	Report errors and panics to Paradigm4	Public
--token	string	""	Account auth token (overrides credentials file)	Internal

Subcommands

Subcommand	Description	Visibility
create	Create a resource	Public
deinit creds	Remove the credentials file	Public
delete	Delete a resource	Public
init creds	Initialize the credentials file	Public
license	Print license information	Public
list	List resources	Public
show	Show details for a single resource	Public
update	Update an existing resource	Public
version	Print the build version	Public

Resources

The verbs operate on the following resource types. create, delete, show, and update name the resource by its command name (show block-store 1); list names it by its API name (list block-stores). The API name is also used in REST paths and JSON output.

Resource	API Name	Verbs	Description
account	accounts	list, show, update	User account
block-api	block-apis	list, show	Block store API type
block-store	block-stores	all	Block store (bucket configuration)
meta-store	meta-stores	all	Metadata store
provider	providers	all	Cloud provider
proxy-group	proxy-groups	all	Proxy group
region	regions	all	Provider region
volume	volumes	all	Volume
volume-proxy-group	volume-proxy-groups	create, delete, list, show	Volume-to-proxy-group association
volume-token	volume-tokens	all	Volume access token

delete, show, and update identify a resource by its key:

Resource	Key
account, block-store, meta-store, proxy-group	<id> (numeric ID)
block-api	<code>
provider	<code>
region	<providerCode> <code>
volume	<id> (volume ID or name)
volume-proxy-group	<volumeID> <proxyGroupID> (volume ID or name, then proxy group ID)
volume-token	<token>

Volume names are unique only within an account. When a name matches volumes in more than one account, the command fails and lists the matching volume IDs; use the volume ID instead.

create

configure.flexfs create <resource> --field=value ...

Creates a new resource of the given type. The fields accepted depend on the resource; each resource’s fields are documented in the ### subsections below. Fields marked required must be supplied on create.

The --flags field on volumes and volume tokens draws its values from a shared vocabulary documented in Accepted Volume and Token Flags.

Account Fields

Accounts cannot be created with configure.flexfs; the following fields are accepted on update.

Flag	Type	Default	Description	Visibility
--email	string	""	Email address	Public
--name	string	""	Account name	Public
--token	string	""	Auth token (UUID)	Public

Block Store Fields

The following fields are available on create. On update, only --address, --namespace, --password, --prefix, and --username are accepted.

An update that changes --prefix is refused with 409 while any volume that has not finished retirement cleanup uses the block store, and one that changes --namespace is refused with 409 while any such volume has blocks stored.

Flag	Type	Default	Description	Visibility
--address	string	""	Endpoint address	Public
--apiCode	string	""	Block API code (s3, gcs, azure, oci) (required, create only)	Public
--bucket	string	""	Block storage bucket (required, create only)	Public
--namespace	string	""	Object storage namespace (required for oci, rejected for every other API)	Public
--password	string	""	Access password	Public
--prefix	string	flexfs	Key prefix within bucket	Public
--providerCode	string	""	Provider code (required, create only)	Public
--regionCode	string	""	Region code (required, create only)	Public
--username	string	""	Access username	Public

Meta Store Fields

The following fields are available on create. On update, only --address and --token are accepted.

Flag	Type	Default	Description	Visibility
--address	string	""	Server address (required for create)	Public
--providerCode	string	""	Provider code (required, create only)	Public
--regionCode	string	""	Region code (required, create only)	Public
--token	string	""	Auth token (UUID, auto-generated if omitted)	Public

Provider Fields

The following fields are available on both create and update.

Flag	Type	Default	Description	Visibility
--code	string	""	Provider code (required for create)	Public
--name	string	""	Provider name (required for create)	Public

Proxy Group Fields

The following fields are available on create. On update, only --addresses is accepted.

Flag	Type	Default	Description	Visibility
--addresses	string	""	Comma-separated proxy addresses (required for create)	Public
--providerCode	string	""	Provider code (required, create only)	Public
--regionCode	string	""	Region code (required, create only)	Public

Region Fields

The following fields are available on create. On update, only --code and --name are accepted.

Flag	Type	Default	Description	Visibility
--code	string	""	Region code (required for create)	Public
--name	string	""	Region name (required for create)	Public
--providerCode	string	""	Provider code (required, create only)	Public

Volume Fields

The following fields are available on create. On update, --blockSize, --compression, --encryption, and --id are not accepted, and a retired volume cannot be updated (409).

A volume name is 3 to 63 characters of letters, digits, ., -, and _, starting and ending with a letter or digit, and cannot contain ... The block size must be a power of 2 from 256 KiB to 8 MiB; the units KiB, MiB, and GiB (or K, M, G, KB, MB, GB, all read as powers of 1024) are accepted in any case.

Flag	Type	Default	Description	Visibility
--blockSize	string	4MiB	Block size, e.g. 4MiB, 256KiB, or raw bytes (create only)	Public
--blockStoreID	int64	0	Block store ID (required for create)	Public
--compression	string	lz4	Compression algorithm: lz4, snappy, zstd, or none (create only)	Public
--encryption	bool	false	Enable end-to-end encryption (create only)	Public
--flags	string	""	Comma-separated mount flags (see Accepted Volume and Token Flags)	Public
--id	string	auto-generated	Volume ID, UUID (create only)	Public
--maxBlocks	int64	0	Max block count, 0 = unlimited	Public
--maxInodes	int64	0	Max inode count, 0 = unlimited	Public
--maxProxied	int64	0	Max proxied blocks per file, 0 = unlimited	Public
--metaStoreID	int64	0	Metadata store ID (required for create)	Public
--name	string	""	Volume name (required for create)	Public
--notes	string	""	Free-form notes	Public
--retention	string	7d	Retention duration (e.g. 7d, 168h, 30m) or seconds; -1 = forever	Public

Volume Proxy Group Fields

Volume-to-proxy-group associations cannot be updated; the following fields are accepted on create only.

Flag	Type	Default	Description	Visibility
--proxyGroupID	int64	0	Proxy group ID (required)	Public
--volumeID	string	""	Volume ID or name (required)	Public

Volume Token Fields

The following fields are available on create. On update, only --flags, --mountPath, and --notes are accepted.

Flag	Type	Default	Description	Visibility
--flags	string	""	Comma-separated mount flags, plus the volume token flags (see Accepted Volume and Token Flags)	Public
--mountPath	string	""	Subdirectory path to mount as root (e.g. /data/project). Also scopes the token’s reporting queries.	Public
--notes	string	""	Free-form notes	Public
--token	string	auto-generated	Access token, UUID (create only)	Public
--volumeID	string	""	Volume ID or name (required, create only)	Public

Accepted Volume and Token Flags

The --flags field on volumes and volume tokens accepts a comma-separated list of mount options. When set on a volume, they apply to all mounts of that volume. When set on a volume token, they are merged with the volume-level flags (token flags take precedence).

Most flags are accepted in both places. The volume token flags below are accepted on a volume token only.

Boolean flags are enabled by name. Key-value flags use name=value syntax (e.g., umask=0027,attrvalid=3600); values are validated when set, so a flag that is accepted here is one that will be honored.

Flag names are matched case-insensitively and ignoring hyphens, so noAtime, noatime, and no-atime are the same flag, as are anonUID and anon-uid. Whitespace is not significant and is removed before the list is stored.

Boolean flags

Flag	Effect
acl	Enable extended ACL support (implies xattr)
allsquash	Map every uid / gid to the anonymous uid / gid (implies rootsquash)
noatime	Disable access-time updates
noexec	Prevent execution of files
nonempty	Allow mounting over a non-empty directory
noprefetch	Disable block prefetching
noproxy	Bypass proxy servers for all block I/O
noproxyreads	Bypass proxy servers for block reads
noproxywrites	Bypass proxy servers for block writes
nosuid	Disable SUID/SGID special permissions
reporterrors	Require mounts to report panics and background failures to Paradigm4 (--reportErrors), including the mount log of a client that fails to start. An admin or free server started with --reportMountErrors adds this flag to every volume it serves
ro	Read-only (implies noatime)
rootsquash	Map uid 0 / gid 0 to the anonymous uid / gid (implies acl)
xattr	Enable extended attribute support

Volume token flags

These flags are accepted on a volume token and rejected on a volume.

Flag	Effect
admin	Allows the token to run reporting queries against the metadata server — /find, /analyze/* and /duplicates, which list file and directory names along with their owners and permissions

A flag set on a volume applies to every token of that volume, so a grant meant for one token belongs on that token. Grant it when creating or updating a volume token:

configure.flexfs create volume-token \
  --volumeID <volume-name> \
  --flags admin \
  --notes "reporting for the storage team"

admin says nothing about how a volume is mounted and has no effect on a mount, so the same token can be used for both. It is still worth issuing a separate token for reporting, so that the grant can be withdrawn without disturbing any mount.

Where a volume token also sets a mount path, its reporting queries are confined to that subdirectory, exactly as its mounts are. See Metadata REST API.

Key-value flags

Flag	Type	Effect
anongid=N	uint32	GID squashed callers are mapped to
anonuid=N	uint32	UID squashed callers are mapped to
attrvalid=N	uint64	Attribute cache TTL in seconds
attrvalidnsec=N	uint32	Nanosecond offset for attrvalid (0 to 999999999)
entryvalid=N	uint64	Directory entry cache TTL in seconds
entryvalidnsec=N	uint32	Nanosecond offset for entryvalid (0 to 999999999)
negentryvalid=N	uint64	Negative lookup cache TTL in seconds
negentryvalidnsec=N	uint32	Nanosecond offset for negentryvalid (0 to 999999999)
umask=NNNN	octal	File creation mask, with or without a leading 0 — 27 and 0027 mean the same thing; max 0777

For boolean flags, either the local mount option or the server-side flag can enable the behavior — neither side can disable what the other enables. For key-value flags, the server-side value takes precedence over the local mount option when set. The squash flags do not follow either rule; see below.

Volume token flags are outside these rules entirely: they are not mount options, so there is nothing on the mount side for them to combine with.

Squash flags

rootsquash, allsquash, anonuid and anongid are the only flags a mount is refused for setting locally as an unprivileged user — setting them here is how a volume squashes mounts whose users it does not control. (Other options can be unavailable to a non-root mount without refusing it: SUID/SGID cannot be enabled, and allow_other may not be permitted.)

They are also the exception to the combining rules above. Setting rootsquash or allsquash here replaces the mount’s entire local squash configuration rather than combining with it: --rootSquash, --allSquash, --anonUID and --anonGID are all discarded, whether or not this side states an identity of its own — an unstated identity falls back to 65534, not to what the mount asked for. So a local --allSquash does not take effect against a volume that sets only rootsquash, which is the one case where a locally enabled boolean is disabled by the server side.

A mount whose root is being squashed chooses neither what it is squashed to nor how widely: use anonuid / anongid here to pick a non-default identity, and allsquash here to squash every caller.

deinit creds

configure.flexfs deinit creds

Removes the credentials file for configure.flexfs. Removing a file that is not there is not an error: deinit creds is idempotent.

delete

configure.flexfs delete <resource> <key>

Deletes the resource of the given type identified by its key.

delete volume retires the volume instead of removing its record: its volume tokens are deleted, mounts are refused, and the metadata server then deletes the volume’s files and blocks without waiting for the retention period. The volume’s name stays reserved while its record exists. Deleting a retired volume removes its record once its data has been deleted, and is refused with 409: volume data is still being deleted before then. See Retiring a Volume.

A provider, region, block store, meta store, or proxy group that a volume uses cannot be deleted (409: in use by a volume), unless every such volume is retired and its data has been deleted. Deleting a block store, meta store, region, or provider then also deletes the records of those volumes, but not the other stores they used: deleting a block store, for example, leaves their meta store. Deleting a proxy group only detaches those volumes from it. Deleting a provider also deletes its regions, and deleting a region also deletes its block stores, meta stores, and proxy groups. To delete a proxy group that active volumes use, first remove its volume associations.

init creds

configure.flexfs init creds [flags]

Initializes a credentials file for configure.flexfs with the admin server address and an account token. If --token is omitted, the command prompts for it interactively. init on its own does the same thing as init creds.

Flag	Type	Default	Description	Visibility
--adminAddr	string	""	Admin server address (required)	Public
--force	bool	false	Overwrite existing credentials file	Public
--token	string	""	Account auth token (will prompt if omitted)	Public

list

configure.flexfs list <resource> [flags]

Lists all instances of the given resource. The table shows a summary set of columns; show or --json gives every field. Columns other than a resource’s key that are empty across every row are hidden unless --json is set.

list all lists every resource type in this order: accounts, block-apis, block-stores, meta-stores, providers, proxy-groups, regions, volumes, volume-proxy-groups, volume-tokens.

list volumes leaves out retired volumes whose data has been deleted; list volumes --cleaned lists only those. Other commands still find such a volume by name or volume ID.

List Filters

Every list <resource> accepts a --<field> filter for each column of that resource — for example list block-stores --providerCode aws or list volumes --name myvol. Filters match exactly and combine with AND. Run configure.flexfs list <resource> --help for the exact set a given resource accepts.

In addition, list volume-proxy-groups and list volume-tokens accept a join filter that the raw columns do not provide:

Flag	Type	Default	Description	Visibility
--volumeName	string	""	Filter by volume name	Public

show

configure.flexfs show <resource> <key>

Shows the full details for a single resource identified by its key.

update

configure.flexfs update <resource> <key> --field=value ...

Updates an existing resource identified by its key. At least one --field must be specified.

update accepts the same per-resource fields as create, with the per-resource restrictions noted in each field table above (for example, block-store update accepts only --address, --namespace, --password, --prefix, and --username; volume update does not accept --blockSize, --compression, --encryption, or --id). The --flags vocabulary is documented under Accepted Volume and Token Flags.