Requirements

This page details the hardware, software, network, and storage requirements you must satisfy before deploying TrilioVault for OpenStack. Meeting these requirements on every node — TVM appliance nodes, the OpenStack controller extensions, and the compute node datamover agents — ensures that backup, snapshot scheduling, and restore operations work reliably and at scale. Pay particular attention to the POSIX user alignment rules for the nova user: mismatches here are the most common cause of silent permission failures on the backup target.

Before you review node-specific requirements, confirm the following baseline conditions are already in place across your environment:

OpenStack

• OpenStack release ≥ Stein
• OpenStack Keystone (identity service) — required for authentication and the TrilioVault Trustee RBAC role
• OpenStack Nova (compute service) — required for VM quiescing and disk access during snapshot capture
• OpenStack Cinder (block storage service) — required for snapshot and temporary volume creation
• OpenStack Horizon (dashboard) — optional; required only if you plan to install the horizon-tvault-plugin

Python

• Python ≥ 3.6 on any host where you run the workloadmgr CLI or the workloadmgrclient library

Backup target (one of the following must be provisioned and reachable before deployment)

• NFS share
• S3-compatible object storage endpoint (supported from TrilioVault 3.0 onward)
• OpenStack Swift

Configuration management (optional; required only if you use the triliovault-cfg-scripts automation)

• Ansible, Salt, or Juju installed on the node running the configuration playbooks/states/charms

Operating system

• Linux with a systemd-based init system on all nodes

TrilioVault appliance nodes are deployed as QCOW2 images on standalone KVM hosts. The nodes must exist outside the OpenStack cloud they protect — TVM nodes cannot run as VMs under the same OpenStack cloud they back up.

Step 1 — Obtain the QCOW2 image

Download the official TrilioVault QCOW2 image from your Trilio distribution channel and copy it to each KVM host that will run a TVM node.

# Example: copy image to KVM host
scp triliovault-<version>.qcow2 root@<kvm-host>:/var/lib/libvirt/images/

Step 2 — Instantiate the TVM appliance on each KVM host

Create a VM from the QCOW2 image using virt-install or your preferred KVM management tool. Repeat for each node in your cluster (three nodes is the recommended HA configuration).

virt-install \
  --name triliovault-node-1 \
  --ram 16384 \
  --vcpus 8 \
  --disk path=/var/lib/libvirt/images/triliovault-<version>.qcow2,format=qcow2 \
  --import \
  --os-variant rhel8.0 \
  --network bridge=br0 \
  --noautoconsole

Note: Adjust --ram, --vcpus, and --network to match the sizing and network topology requirements documented in the sections below.

Step 3 — Assign the cluster VIP

Even in a single-node deployment, you must allocate an additional cluster IP address (VIP). This VIP is managed by Pacemaker/HAProxy and is registered as the Keystone service endpoint for wlm-api.

# Confirm the VIP is routable from your OpenStack controller
ping -c 3 <cluster-vip>

Step 4 — Verify nova user POSIX alignment on all nodes

All read and write operations on the backup target are performed as the nova user (nova:nova). The POSIX UID and GID of the nova user must be identical on every TrilioVault cluster node and every OpenStack compute node.

# Run on every TVM node and every compute node
id nova
# Expected output must match across all hosts, e.g.:
# uid=162(nova) gid=162(nova) groups=162(nova)

If any node reports a different UID or GID, realign them before proceeding. Mismatches will cause silent permission errors when writing to or reading from the backup target.

Step 5 — Configure the backup target mount

Mount the backup target on each TVM node so it is accessible to the nova user.

# Example: NFS backup target
mkdir -p /mnt/triliovault-backup
mount -t nfs <nfs-server>:<export-path> /mnt/triliovault-backup

# Verify write access as nova
sudo -u nova touch /mnt/triliovault-backup/.write-test && echo "Write OK"

Step 6 — Run the TrilioVault configurator

Use the triliovault-cfg-scripts Ansible playbooks (or the equivalent Salt states or Juju charms) to complete service installation. The configurator is idempotent and can be re-run at any time to apply changes.

# Example: run Ansible configurator
cd triliovault-cfg-scripts/
ansible-playbook -i inventory/hosts site.yml

Step 7 — First login and password change

The default TrilioVault Dashboard credentials are admin / password. You are required to change the password on first login.

URL:      https://<cluster-vip>/
Username: admin
Password: password  (change immediately after first login)

The following configuration areas directly affect how TrilioVault nodes and services operate. Each option is set during initial deployment via triliovault-cfg-scripts and can be changed by re-running the configurator.

Cluster topology

Service placement

wlm-api and wlm-scheduler are cluster-controlled by Pacemaker and run only on the master node. wlm-workloads runs on every TrilioVault node. This means all API and scheduling traffic is handled by the master, while data-movement work is distributed across all nodes. You do not configure this placement manually — Pacemaker enforces it automatically.

nova user POSIX identity

All backup target I/O runs as nova:nova. The UID and GID must match exactly across:

• All TrilioVault cluster nodes
• All OpenStack compute nodes

If you rebuild or add a node, verify alignment before mounting the backup target. There is no runtime fallback — a mismatch produces permission-denied errors at snapshot time.

Backup target

Cinder quota headroom

TrilioVault creates Cinder snapshots and temporary Cinder volumes during backup. For each disk being backed up, ensure your Cinder quotas allow:

• 2 additional Cinder snapshots
• 1 additional temporary Cinder volume

Insufficient quotas will cause backup jobs to fail mid-operation.

RBAC: TrilioVault Trustee role

The TrilioVault Trustee Keystone RBAC role is mandatory for all workload, snapshot, and restore operations. The OpenStack admin role does not substitute for it. Assign the Trustee role in Keystone before any tenant user attempts to create a workload.

Network topology capture (TrilioVault 3.0+)

From version 3.0 onward, every snapshot automatically captures the full tenant network topology (networks, subnets, routers, static routes, ports, and floating IPs). No configuration is needed to enable this. However, be aware of two restore-time constraints:

• The tenant's network space must be completely empty of networking components before a network topology restore; any conflict will abort the restore.
• After the restore completes, TrilioVault does not reconnect restored private networks to the public network — you must perform that final step manually.

Email notifications

Email notifications are configured per tenant and require:

• A valid email address on the tenant's OpenStack user account
• An SMTP server configured by the backup administrator in the TrilioVault settings

File Recovery Manager Glance image

If you use file-level restore (granular restore), the File Recovery Manager Glance image must have the property tvault_recovery_manager=yes set, otherwise it will not appear as a valid mount target in the Horizon UI.

openstack image set --property tvault_recovery_manager=yes <file-recovery-manager-image-id>

Once your TVM nodes are running and configured, the following workflows cover the most common day-to-day operations.

Checking service health

Verify that each service is running as expected on the master node and on all worker nodes.

# On the master TVM node — wlm-api and wlm-scheduler are Pacemaker-controlled
sudo crm status

# On every TVM node — wlm-workloads runs on all nodes
sudo systemctl status wlm-workloads

wlm-cron drives scheduled snapshot jobs. If scheduled snapshots are not firing, check its status:

sudo systemctl status wlm-cron

Assigning the Trustee role to a tenant user

Before a tenant user can create workloads or snapshots, they need the TrilioVault Trustee role in Keystone.

openstack role add --user <username> --project <project-name> TrilioVault_Trustee

Managing workloads from the CLI

The workloadmgr command-line tool (provided by the workloadmanager-client package) is the primary scripting interface.

# List all workloads visible to the current user
workloadmgr workload-list

# Show details of a specific workload
workloadmgr workload-show <workload-id>

# Trigger an on-demand snapshot of a workload
workloadmgr workload-snapshot <workload-id>

# List snapshots for a workload
workloadmgr snapshot-list --workload-id <workload-id>

Managing workloads from the Horizon dashboard

If the horizon-tvault-plugin is installed, navigate to Project → Workloads in the Horizon sidebar. From there you can create workloads, trigger snapshots, and initiate restores without using the CLI.

Verifying backup target access

Run this check after any infrastructure change (node rebuild, nova user change, NFS remount) to confirm the backup target is still accessible.

sudo -u nova ls <backup-target-mount-point>

Checking nova user alignment after adding a compute node

Each time you add a compute node to the OpenStack cloud, verify that its nova UID and GID match the rest of the cluster before the next scheduled snapshot.

# Run on the new compute node
id nova
# Compare against output from an existing TVM node and compute node

Example 1 — Confirm nova UID/GID alignment across nodes

Run this snippet on each TVM node and compute node. All outputs must be identical.

id nova

Expected output (must match on every node):

uid=162(nova) gid=162(nova) groups=162(nova)

If any node returns a different UID or GID, realign before the next snapshot window.

Example 2 — Verify NFS backup target is writable by nova

sudo -u nova touch /mnt/triliovault-backup/.write-test
echo $?

Expected output:

0

A non-zero exit code indicates a permission or mount problem. Check /var/log/workloadmgr/workloadmgr-workloads.log for details.

Example 3 — Check Cinder quota headroom before a large backup

For a workload with 5 VMs each having 2 attached volumes (10 disks total), you need headroom for 20 Cinder snapshots and 10 temporary volumes.

openstack quota show <project-name> | grep -E 'snapshots|volumes'

Sample output:

| backup-snapshots    | -1 |
| gigabytes           | 1000 |
| snapshots           | 50  |
| volumes             | 30  |

Confirm that snapshots and volumes have enough remaining capacity for the operation. A value of -1 means unlimited.

Example 4 — Assign TrilioVault Trustee role and verify

openstack role add --user jsmith --project acme-prod TrilioVault_Trustee
openstack role assignment list --user jsmith --project acme-prod --names

Expected output:

+--------------------+-------+--------+------------+--------+
| Role               | User  | Group  | Project    | Domain |
+--------------------+-------+--------+------------+--------+
| TrilioVault_Trustee| jsmith|        | acme-prod  |        |
+--------------------+-------+--------+------------+--------+

Example 5 — Set the tvault_recovery_manager property on the File Recovery Manager image

openstack image set --property tvault_recovery_manager=yes <file-recovery-manager-image-id>
openstack image show <file-recovery-manager-image-id> | grep tvault_recovery_manager

Expected output:

| properties | tvault_recovery_manager='yes', ... |

Without this property, the image will not appear in the Horizon file-level restore mount target list.

Example 6 — Confirm wlm-workloads is running on all TVM nodes

systemctl is-active wlm-workloads

Expected output:

active

If the output is inactive or failed, inspect the log:

tail -n 50 /var/log/workloadmgr/workloadmgr-workloads.log

Use the following log locations as your first reference for any issue:

Issue 1 — Snapshots fail with permission-denied errors on the backup target

Symptom: Snapshot jobs reach the data-movement phase and then fail. The wlm-workloads log shows Permission denied when writing to the backup target.

Likely cause: The nova user's POSIX UID or GID does not match between the TrilioVault node and one or more compute nodes, or the backup target mount permissions are incorrect.

Fix:

1. Run id nova on every TVM node and every compute node and confirm all outputs are identical.
2. If they differ, realign the UID/GID and remount the backup target.
3. Confirm the mount is writable: sudo -u nova touch <backup-target-mount-point>/.write-test

Issue 2 — Scheduled snapshots do not fire at the configured interval

Symptom: Workloads have a snapshot policy defined but automatic snapshots are not being created.

Likely cause: The wlm-cron service is stopped or has crashed.

Fix:

sudo systemctl status wlm-cron
sudo systemctl restart wlm-cron
sudo systemctl status wlm-cron

If the service fails to start, check the wlm-api log for configuration errors that may prevent the cron service from registering jobs.

Issue 3 — Backup jobs fail with Cinder quota exceeded errors

Symptom: A snapshot job starts but aborts mid-operation with a Cinder quota error visible in /var/log/workloadmgr/workloadmgr-workloads.log.

Likely cause: Cinder quotas for the project do not allow two snapshots and one temporary volume per disk being backed up.

Fix:

# Check current quota usage
openstack quota show <project-name> | grep -E 'snapshots|volumes'

# Increase quotas if needed
openstack quota set --snapshots <new-value> --volumes <new-value> <project-name>

Calculate the required headroom: multiply the number of disks in the workload by 2 for snapshots and by 1 for volumes.

Issue 4 — Tenant user cannot create workloads (authorization error)

Symptom: A tenant user receives a 403 or authorization-denied error when attempting to create a workload via the CLI or Horizon dashboard.

Likely cause: The user has not been assigned the TrilioVault Trustee Keystone role. The OpenStack admin role does not substitute for it.

Fix:

openstack role add --user <username> --project <project-name> TrilioVault_Trustee

Issue 5 — File Recovery Manager image does not appear in Horizon mount target list

Symptom: During a file-level restore, the File Recovery Manager Glance image is not listed as an available mount target in the Horizon UI.

Likely cause: The image is missing the tvault_recovery_manager=yes property.

Fix:

openstack image set --property tvault_recovery_manager=yes <file-recovery-manager-image-id>

Refresh the Horizon page after setting the property.

Issue 6 — Network topology restore fails immediately

Symptom: Initiating a restore that includes network topology fails with a conflict error.

Likely cause: The target tenant's network space is not empty. TrilioVault requires the tenant to have no existing networks, subnets, routers, ports, or floating IPs before a network topology restore.

Fix:

1. List and remove all networking components in the target project:

openstack router list --project <project-name>
openstack network list --project <project-name>

2. Delete floating IPs, router interfaces, routers, subnets, and networks in that order.
3. Re-attempt the restore once the network space is empty.
4. After the restore completes, manually reconnect the restored private networks to the public network — TrilioVault does not perform this final step automatically.

Issue 7 — wlm-api or wlm-scheduler not running after a node failover

Symptom: API calls fail with connection refused. The wlm-api and/or wlm-scheduler services are not running.

Likely cause: wlm-api and wlm-scheduler are Pacemaker-controlled and run only on the master node. After a failover, Pacemaker may need time to promote a new master, or the VIP may not have migrated cleanly.

Fix:

# Check Pacemaker cluster status
sudo crm status

# If resources are stopped or failed, clean and restart
sudo crm resource cleanup

Verify the cluster VIP is assigned to the new master node and that the Keystone service endpoint resolves to it before retrying API calls.