CLI reference

CLI Reference

Document all workloadmgr CLI commands — workload-create, workload-list, workload-show, workload-snapshot, snapshot-list, snapshot-show, snapshot-delete, restore-list, restore-show, restore-delete, snapshot-mount, snapshot-unmount, filepath-search, enable-scheduler, disable-scheduler — with all flags, argument types, and examples derived from code.

Description

The workloadmgr command-line tool is provided by the workloadmanager-client component and gives operators, administrators, and developers full control over TrilioVault for OpenStack from the terminal or automation scripts. Use it to define workloads, capture and manage snapshots, initiate and inspect restores, perform file-level recovery, and control the WLM scheduler — all without opening the Horizon dashboard. Every operation maps directly to a call against the wlm-api REST endpoint, so the same actions available in the Horizon plugin are accessible here.

Synopsis

workloadmgr [--os-auth-url <url>] [--os-username <username>] [--os-password <password>]
            [--os-tenant-name <tenant>] [--os-region-name <region>]
            [--os-token <token>] [--wlm-url <url>]
            <subcommand> [subcommand-flags] [args]

All global flags may also be supplied through environment variables (see Environment Variables below). When both are present, the explicit flag takes precedence over the environment variable.

Flags

Global Flags

These flags apply to every workloadmgr subcommand.

Flag	Short	Default	Description
`--os-auth-url`	—	`$OS_AUTH_URL`	Keystone authentication endpoint URL. Required unless `$OS_AUTH_URL` is set.
`--os-username`	—	`$OS_USERNAME`	OpenStack username for authentication.
`--os-password`	—	`$OS_PASSWORD`	OpenStack password. Avoid passing on the command line in shared environments; prefer the environment variable.
`--os-tenant-name`	—	`$OS_TENANT_NAME`	OpenStack project (tenant) name to operate within.
`--os-tenant-id`	—	`$OS_TENANT_ID`	OpenStack project UUID. Use instead of `--os-tenant-name` when names are ambiguous.
`--os-region-name`	—	`$OS_REGION_NAME`	OpenStack region to target.
`--os-token`	—	`$OS_TOKEN`	Pre-authenticated token. Mutually exclusive with `--os-username` / `--os-password`.
`--wlm-url`	—	`$WLM_URL`	Direct URL of the wlm-api service endpoint. Overrides the endpoint resolved from the Keystone service catalog.
`--os-cacert`	—	`$OS_CACERT`	Path to a CA bundle file for TLS verification against the wlm-api endpoint.
`--insecure`	—	`false`	Disable TLS certificate verification. Not recommended in production.
`--debug`	—	`false`	Enable verbose debug output, including full HTTP request and response bodies.
`--help`	`-h`	—	Display help for the command or subcommand and exit.

Subcommand-specific Flags

Flags that apply to individual subcommands are documented in the Examples and Subcommands sections below.

Subcommands

Subcommand	Description
`workload-create`	Create a new workload by grouping one or more VMs (and their attached volumes) into a named protection group.
`workload-list`	List all workloads visible to the current tenant.
`workload-show`	Display detailed information about a specific workload, including its member VMs and snapshot policy.
`workload-snapshot`	Trigger an immediate (on-demand) snapshot of a workload.
`snapshot-list`	List all snapshots for a given workload.
`snapshot-show`	Display detailed metadata about a specific snapshot.
`snapshot-delete`	Delete a snapshot and reclaim its storage on the backup target.
`restore-list`	List all restore operations associated with a workload or snapshot.
`restore-show`	Display detailed status and configuration of a specific restore operation.
`restore-delete`	Remove the record of a completed or failed restore operation.
`snapshot-mount`	Mount a snapshot to a File Recovery Manager instance so that individual files can be browsed and retrieved.
`snapshot-unmount`	Unmount a previously mounted snapshot from the File Recovery Manager instance.
`filepath-search`	Search for a file by name or path within a mounted snapshot to support file-level restore.
`enable-scheduler`	Re-enable the wlm-cron scheduler so that automatic snapshot policies resume firing.
`disable-scheduler`	Pause the wlm-cron scheduler so that no new automatic snapshots are triggered (manual snapshots are unaffected).

Environment variables

Setting these variables in your shell session (or in an OpenStack openrc file) lets you omit the corresponding flags from every command. Source your tenant's openrc file before running workloadmgr commands to avoid typing credentials repeatedly.

Variable	Default	Description
`OS_AUTH_URL`	(none)	Keystone endpoint URL. Equivalent to `--os-auth-url`.
`OS_USERNAME`	(none)	OpenStack username. Equivalent to `--os-username`.
`OS_PASSWORD`	(none)	OpenStack password. Equivalent to `--os-password`.
`OS_TENANT_NAME`	(none)	Project name. Equivalent to `--os-tenant-name`.
`OS_TENANT_ID`	(none)	Project UUID. Equivalent to `--os-tenant-id`.
`OS_REGION_NAME`	(none)	OpenStack region. Equivalent to `--os-region-name`.
`OS_TOKEN`	(none)	Pre-authenticated token. Equivalent to `--os-token`.
`OS_CACERT`	(none)	CA bundle path for TLS verification. Equivalent to `--os-cacert`.
`WLM_URL`	(none)	Direct wlm-api endpoint URL. Overrides the Keystone service catalog when set. Equivalent to `--wlm-url`.

Exit codes

Code	Meaning
`0`	Command completed successfully.
`1`	General error — invalid arguments, missing required flags, or an unrecognised subcommand.
`2`	Authentication failure — Keystone rejected the credentials or token.
`3`	Authorisation failure — the authenticated user lacks the TrilioVault Trustee RBAC role required for workload, snapshot, or restore operations.
`4`	Resource not found — the specified workload, snapshot, or restore ID does not exist or is not visible to the current tenant.
`5`	Conflict — the operation cannot proceed because of a state conflict (for example, a restore attempted when the target network space is not empty).
`6`	Quota exceeded — the operation would exceed OpenStack Cinder quotas for snapshots or volumes. Ensure your project has headroom for two Cinder snapshots and one temporary volume per disk being backed up.
`7`	Communication error — the client could not reach the wlm-api service endpoint. Check network connectivity and the value of `WLM_URL` or the Keystone service catalog entry.

Examples

Authenticate with an openrc file

Source your tenant credentials before running any workloadmgr commands.

source ~/openrc-myproject

workload-create

Create a workload named web-tier that protects two VMs and takes a daily snapshot at 02:00, retaining the seven most recent snapshots.

workloadmgr workload-create \
  --name web-tier \
  --description "Front-end web tier VMs" \
  --instance-id aaaa-1111-bbbb-2222 \
  --instance-id cccc-3333-dddd-4444 \
  --jobschedule '{"start_time": "02:00 AM", "interval": "24hrs", "retention_policy_type": "Number of Snapshots", "retention_policy_value": "7"}'

Expected output:

+---------------------+--------------------------------------+
| Property            | Value                                |
+---------------------+--------------------------------------+
| id                  | f1e2d3c4-a5b6-7890-cdef-112233445566 |
| name                | web-tier                             |
| description         | Front-end web tier VMs               |
| status              | available                            |
| instances           | aaaa-1111-bbbb-2222                  |
|                     | cccc-3333-dddd-4444                  |
| jobschedule         | interval=24hrs, retention=7          |
| created_at          | 2024-05-10T02:00:00Z                 |
+---------------------+--------------------------------------+

Note: Each VM may belong to only one workload at a time. If you attempt to add a VM that is already a member of another workload, the command returns exit code 5.

Key flags for workload-create:

Flag	Required	Description
`--name`	Yes	Human-readable name for the workload.
`--description`	No	Optional description.
`--instance-id`	Yes (repeat for each VM)	Nova instance UUID to include in the workload. Repeat the flag once per VM.
`--jobschedule`	No	JSON string defining the snapshot schedule and retention policy. Omit for workloads with manual-only snapshots.
`--availability-zone`	No	OpenStack availability zone in which to execute snapshot operations.

workload-list

List all workloads visible to the current project.

workloadmgr workload-list

Expected output:

+--------------------------------------+-----------+---------------------+-----------+
| ID                                   | Name      | Created At          | Status    |
+--------------------------------------+-----------+---------------------+-----------+
| f1e2d3c4-a5b6-7890-cdef-112233445566 | web-tier  | 2024-05-10T02:00:00Z| available |
| 99887766-5544-3322-1100-aabbccddeeff | db-tier   | 2024-05-09T03:00:00Z| available |
+--------------------------------------+-----------+---------------------+-----------+

workload-show

Display full details for the web-tier workload, including its member instances and schedule.

workloadmgr workload-show f1e2d3c4-a5b6-7890-cdef-112233445566

Expected output:

+---------------------+--------------------------------------+
| Property            | Value                                |
+---------------------+--------------------------------------+
| id                  | f1e2d3c4-a5b6-7890-cdef-112233445566 |
| name                | web-tier                             |
| description         | Front-end web tier VMs               |
| status              | available                            |
| instances           | aaaa-1111-bbbb-2222                  |
|                     | cccc-3333-dddd-4444                  |
| jobschedule         | interval=24hrs, retention=7          |
| created_at          | 2024-05-10T02:00:00Z                 |
| updated_at          | 2024-05-10T02:00:00Z                 |
+---------------------+--------------------------------------+

workload-snapshot

Trigger an immediate on-demand snapshot of the web-tier workload. The --name flag labels the snapshot for easy identification later.

workloadmgr workload-snapshot \
  --workload-id f1e2d3c4-a5b6-7890-cdef-112233445566 \
  --name "pre-deployment-snapshot"

Expected output:

+---------------------+--------------------------------------+
| Property            | Value                                |
+---------------------+--------------------------------------+
| id                  | snap-1234-abcd-5678-efgh             |
| name                | pre-deployment-snapshot              |
| workload_id         | f1e2d3c4-a5b6-7890-cdef-112233445566 |
| status              | in-progress                          |
| created_at          | 2024-05-11T10:30:00Z                 |
+---------------------+--------------------------------------+

The status transitions from in-progress to available when wlm-workloads finishes writing data to the backup target. Poll with snapshot-show to confirm completion.

Key flags for workload-snapshot:

Flag	Required	Description
`--workload-id`	Yes	UUID of the workload to snapshot.
`--name`	No	Label for this snapshot. Defaults to a timestamp-based name.
`--description`	No	Optional description.
`--full`	No	Force a full snapshot regardless of whether incremental data is available.

snapshot-list

List all snapshots for the web-tier workload.

workloadmgr snapshot-list \
  --workload-id f1e2d3c4-a5b6-7890-cdef-112233445566

Expected output:

+-------------------------+-------------------------+---------------------+-----------+
| ID                      | Name                    | Created At          | Status    |
+-------------------------+-------------------------+---------------------+-----------+
| snap-1234-abcd-5678-efgh| pre-deployment-snapshot | 2024-05-11T10:30:00Z| available |
| snap-9876-wxyz-5432-mnop| scheduled-2024-05-10    | 2024-05-10T02:00:00Z| available |
+-------------------------+-------------------------+---------------------+-----------+

Key flags for snapshot-list:

Flag	Required	Description
`--workload-id`	Yes	UUID of the workload whose snapshots you want to list.

snapshot-show

Display detailed metadata for a specific snapshot, including size, type (full or incremental), and backup target location.

workloadmgr snapshot-show snap-1234-abcd-5678-efgh

Expected output:

+---------------------+--------------------------------------+
| Property            | Value                                |
+---------------------+--------------------------------------+
| id                  | snap-1234-abcd-5678-efgh             |
| name                | pre-deployment-snapshot              |
| workload_id         | f1e2d3c4-a5b6-7890-cdef-112233445566 |
| status              | available                            |
| snapshot_type       | incremental                          |
| size_mb             | 4096                                 |
| created_at          | 2024-05-11T10:30:00Z                 |
+---------------------+--------------------------------------+

snapshot-delete

Delete an older snapshot to reclaim space on the backup target. This operation is permanent.

workloadmgr snapshot-delete snap-9876-wxyz-5432-mnop

Expected output:

Request to delete snapshot snap-9876-wxyz-5432-mnop has been accepted.

restore-list

List all restore operations initiated from snapshots of the web-tier workload.

workloadmgr restore-list \
  --workload-id f1e2d3c4-a5b6-7890-cdef-112233445566

Expected output:

+---------------------------+---------------------+-----------+
| ID                        | Created At          | Status    |
+---------------------------+---------------------+-----------+
| restore-aaaa-1111-bbbb    | 2024-05-12T08:00:00Z| available |
+---------------------------+---------------------+-----------+

Key flags for restore-list:

Flag	Required	Description
`--workload-id`	No	Filter restores by the parent workload UUID.
`--snapshot-id`	No	Filter restores by the source snapshot UUID.

restore-show

Display the current status and configuration of a specific restore operation.

workloadmgr restore-show restore-aaaa-1111-bbbb

Expected output:

+---------------------+--------------------------------------+
| Property            | Value                                |
+---------------------+--------------------------------------+
| id                  | restore-aaaa-1111-bbbb               |
| snapshot_id         | snap-1234-abcd-5678-efgh             |
| status              | available                            |
| restore_type        | selective                            |
| created_at          | 2024-05-12T08:00:00Z                 |
+---------------------+--------------------------------------+

restore-delete

Remove the metadata record of a completed or failed restore. This does not affect any VMs or volumes that were created by the restore.

workloadmgr restore-delete restore-aaaa-1111-bbbb

Expected output:

Request to delete restore restore-aaaa-1111-bbbb has been accepted.

snapshot-mount

Mount a snapshot to a running File Recovery Manager instance so you can browse its filesystem and retrieve individual files. The Glance image used for the File Recovery Manager must have the property tvault_recovery_manager=yes set, or it will not appear as a valid mount target.

workloadmgr snapshot-mount \
  --snapshot-id snap-1234-abcd-5678-efgh \
  --mount-vm-id frm-instance-uuid-9999

Expected output:

+---------------------+--------------------------------------+
| Property            | Value                                |
+---------------------+--------------------------------------+
| snapshot_id         | snap-1234-abcd-5678-efgh             |
| mount_vm_id         | frm-instance-uuid-9999               |
| status              | mounted                              |
+---------------------+--------------------------------------+

Key flags for snapshot-mount:

Flag	Required	Description
`--snapshot-id`	Yes	UUID of the snapshot to mount.
`--mount-vm-id`	Yes	Nova instance UUID of the File Recovery Manager VM that will host the mount.

snapshot-unmount

Detach a previously mounted snapshot from the File Recovery Manager instance once file recovery is complete.

workloadmgr snapshot-unmount \
  --snapshot-id snap-1234-abcd-5678-efgh

Expected output:

Snapshot snap-1234-abcd-5678-efgh has been successfully unmounted.

Key flags for snapshot-unmount:

Flag	Required	Description
`--snapshot-id`	Yes	UUID of the snapshot to unmount.

filepath-search

Search for a file by name inside a mounted snapshot to locate it before performing a file-level restore. The snapshot must already be mounted with snapshot-mount before you run this command.

workloadmgr filepath-search \
  --snapshot-id snap-1234-abcd-5678-efgh \
  --search-path "/var/www/html/index.php"

Expected output:

+---------------------+--------------------------------------+
| Property            | Value                                |
+---------------------+--------------------------------------+
| snapshot_id         | snap-1234-abcd-5678-efgh             |
| search_path         | /var/www/html/index.php              |
| results             | /var/www/html/index.php (found)      |
+---------------------+--------------------------------------+

Key flags for filepath-search:

Flag	Required	Description
`--snapshot-id`	Yes	UUID of the mounted snapshot to search.
`--search-path`	Yes	Absolute file path or filename pattern to search for within the snapshot filesystem.

enable-scheduler

Re-enable the wlm-cron service so that snapshot policies resume firing automatically. Use this after a maintenance window during which the scheduler was paused.

workloadmgr enable-scheduler

Expected output:

Scheduler has been enabled successfully.

disable-scheduler

Pause the wlm-cron service to prevent automatic snapshots from firing during a maintenance window or a storage migration. Manual snapshots triggered with workload-snapshot are not affected.

workloadmgr disable-scheduler

Expected output:

Scheduler has been disabled successfully.