8. Command Reference

Unless noted otherwise, all list/get commands are read-only and safe to run at any time.

8.1 realm

Alias: rlm. The realm is the VDURA cluster as a whole; there is only one, so this group has a single, argument-free verb.

panctl realm get
panctl realm get -o 'jsonpath={.realm.state}'

Requires the platform-admin role. Fields include state, locked, clientmode_current, heartbeat_period_seconds, volume_max_vols_realm, and more.

8.2 nodes

Aliases: node, no, n. Physical/virtual storage nodes in the realm, identified by their dataserial (not a name).

$ panctl nodes list
DATASERIAL      IP ADDRESS   STATUS  ROLE   STORAGESET ID  CAPACITY BYTES
109a58fc3162ef  10.97.5.237  online  vosd   0              55650025472

panctl nodes get 109a58fc3162ef
panctl nodes reboot 109a58fc3162ef

Notes: - A STORAGESET ID of 0 means the node isn’t assigned to a storage set yet. - reboot sends the request and returns immediately; there is no confirmation prompt.

8.3 storagesets

Aliases: storageset, ss, s. Pools of nodes that back tenant capacity and volumes.

panctl storagesets create --name "Demo Set" --spares-requested 4
panctl storagesets get 4
panctl storagesets add-storage --storageset-id 4 \
  --dataserials 109a58fc3162ef,3f8889d66162f5 --spares-requested 2
panctl storagesets delete 4

Notes: - --dataserials cannot be left empty on add-storage; an empty list would mean “add every unassigned node in the realm,” so PanCTL blocks it to prevent an accidental mass operation. - add-storage returns immediately, but absorbing new nodes into the set happens asynchronously in the background. Poll to confirm completion: bash until [ "$(panctl storagesets get 4 -o 'jsonpath={.storageset.nodes_online}')" = "6" ]; do sleep 5; done

8.4 tenants

Aliases: tenant, tn, tx, t. Tenants are the isolation boundary for users, capacity, and volumes.

panctl tenants create --name FinTech --short-name fintech --email admin@fintech.example.com
panctl tenants assign-storagesets --tenant fintech --storageset-id 4 --quota 10GB
panctl tenants list-storagesets --tenant fintech
panctl tenants delete <tenant_id>

Notes: - Multi-tenancy is not supported on InfiniBand. tenants create is refused with a 409 Conflict on a realm whose clients connect over InfiniBand, because tenant isolation needs VLAN or VXLAN encapsulation. Ethernet realms are not affected, and a realm that already runs without tenants is unchanged. - --tenant accepts either the tenant’s UUID or its short name; PanCTL resolves short names for you. - --short-name is 3–10 alphanumeric characters and cannot be changed after creation. - assign-storagesets acts as an “upsert”: if the tenant already has capacity in that storage set, this call resizes the quota instead of failing. - Creating a volume successfully is not, by itself, proof that assign-storagesets succeeded; confirm assignment separately with list-storagesets if you need to be certain. - tenants delete has no confirmation prompt and deletes the tenant’s volumes along with it.

8.5 volumes

Aliases: volume, vol, v. File-system volumes within your own tenant.

panctl volumes create --name /data --storageset-id 1 --hard-quota 10GiB \
  --soft-quota 8GiB --raid-type raid5+ --recovery-priority 1

echo '{"new_pathname":"/archive/volume1"}' | panctl volumes rename 3 -f -
echo '{"hard_quota_bytes":21474836480}' | panctl volumes update 3 -f -
panctl volumes delete 3

create options:

Notes: - volumes create always creates the volume in your own tenant; there’s no --tenant flag on this command. - Before creating a volume, make sure: the target storage set has enough online capacity for the chosen RAID layout, your tenant has capacity assigned there (see tenants assign-storagesets), and your tenant has a subnet with an available address. - rename only changes the volume’s path; update changes everything else (quotas, priority) but not the path or RAID type.

8.6 subnets

Aliases: subnet, sub, sn. Per-tenant IP address ranges used by clients to reach volumes, plus their client attachments.

panctl subnets create --tenant fintech --name fintech-net --cidr 10.71.0.0/16 \
  --gateway 10.71.255.254 --mtu 9000 --range-start 10.71.0.1 --range-end 10.71.1.255

panctl subnets attachments create <subnet_id> --underlay-ip 10.128.9.0 --hostname client01
panctl subnets update <subnet_id> --mtu 1500
panctl subnets delete <subnet_id>

Notes: - Size your CIDR generously; use at least a /16 for a tenant subnet, not a /24. Internal addressing places storage-node addresses 256 addresses into the range, and a /24 will silently strand them with no error message. - Subnets are identified by UUID, not a numeric ID. - Attachment create/delete are tenant-scoped operations; even a platform administrator must be logged in as a user of that tenant to manage attachments (a platform-admin session gets a permissions error, even though it can create/delete the subnet itself). - --segment-id, --tunnel-udp-port, and --addr-external can only be set at creation time.

8.7 users

Aliases: user, us, u. Human user accounts. All users are platform-level; there are no separate tenant users.

panctl users create --tenant fintech --username jsmith --email jsmith@fintech.example.com
panctl users set-roles --user-id <user_id> --tenant fintech --roles platform-read-only
panctl users get-roles --user-id <user_id> --tenant fintech
panctl users delete <user_id> --tenant fintech

Notes: - If --tenant is omitted, PanCTL infers it from the short-name prefix of your own logged-in username. It’s safer to always pass --tenant explicitly in scripts. - set-roles replaces the entire role set, it does not add to it. Pass --roles '' to revoke all roles from a user. - There are no tenant roles. The only roles are platform-admin, platform-read-only, and storage-admin, and every user is a platform-level user. See 8.9 for what each role allows.

8.8 service-accounts

Alias: sa. Non-human accounts intended for automation, scoped to the platform rather than a tenant.

panctl service-accounts create --name ci-runner --display-name "CI Runner"
panctl service-accounts set-roles --sa-id <sa_id> --roles storage-admin

TOKEN=$(panctl service-accounts tokens create --sa-id <sa_id> --name ci --expires-in-days 90 -o jsonpath='{.token}')
PANCTL_API_SERVER=<server> panctl auth whoami --token "$TOKEN"

Notes: - A service account’s --name is immutable after creation; only display name and description can be updated. - Available roles: platform-admin, platform-read-only, and storage-admin. See 8.9 for what each one allows. - This is the recommended pattern for giving an automation pipeline its own credentials, separate from any individual administrator’s login.

8.9 roles

Aliases: role, ro, r. A read-only catalogue of what each role is permitted to do.

There are no tenant roles. A user or service account holds one or more of these three platform roles:

$ panctl roles list
ROLE                RESOURCE            ACTIONS
platform-admin      volumes             list, view, create, update, delete, action
...
platform-read-only  volumes             list, view
...
storage-admin       volumes             list, view, create, update, delete, action
...

The sample output is abbreviated; the command lists every resource for every role, one row per role and resource pair.

Useful for confirming exactly what a role grants before assigning it to a user or service account.

8.10 s3

The S3-compatible object gateway. Some commands are realm-wide (platform administrators only) and some are per-tenant (--tenant <ref>).

Realm-wide configuration:

Per-tenant configuration:

panctl s3 get-config --tenant fintech
panctl s3 set-config --tenant fintech --enabled true --prefix /vol1/fintech \
  --owner alice --group staff --dir-mode 0755 --obj-mode 0644
panctl s3 dns panfs --tenant fintech
panctl s3 tls renew --tenant fintech

Instances (gateway processes running on specific nodes, identified by an instance ID iid):

panctl s3 instances list --tenant fintech
panctl s3 instances create abc12 <dataserial> --tenant fintech
panctl s3 instances start abc12 --tenant fintech
panctl s3 instances stop-all --tenant fintech
panctl s3 instances delete-all --tenant fintech --yes

Buckets and credentials:

panctl s3 buckets create archive-2026 --tenant fintech
panctl s3 buckets list --tenant fintech
panctl s3 credentials reveal <access_key> --tenant fintech
panctl s3 credentials rotate <access_key> --tenant fintech

Notes: - s3 instances delete-all requires --yes (this is the only destructive command in PanCTL that enforces an explicit confirmation flag). - credentials reveal returns the current secret without changing it; credentials rotate generates a brand-new secret (the old one stops working immediately). Both print the secret in plain text, so handle the output carefully.

8.11 events

Aliases: ev, e. Recent system events (read-only).

panctl events list
panctl events list --limit 25
panctl events list --tenant fintech

Shows up to 200 of the most recent events (--limit accepts 1–200); this is the exact same feed shown in the web UI.

8.12 alerts

Alias: al. Currently active alerts (read-only, no flags).

panctl alerts list

This shows a live snapshot of active alerts (not a historical log), the same set that drives the alert badge in the web UI.

8.13 audit

Aliases: aud, ad. The administrative audit log (read-only).

panctl audit list
panctl audit list --tenant fintech --since 2h
panctl audit list --user <user_id> --only create,delete
panctl audit list --since 2026-09-04T22:00:00Z --until 2026-09-04T23:59:59Z
panctl audit get <request_id>

audit get <request_id> drills into a single request; for a failed request, it also prints diagnostic details and relevant backend log lines.