OpenStack CLI Plugin
The `openstack <resource> ...` commands this service adds
The openstack dr command family is the primary operator interface for Trilio Site Recovery for OpenStack. It is installed by the python3-triliositerecovery Debian package as an OpenStackClient plugin and integrates with the standard openstack CLI, inheriting its authentication (via OS_* environment variables or clouds.yaml), output formats, column selection, and help system. Use these commands to register DR sites, create and manage protection groups, add VMs to protection, execute and monitor failover and failback operations, manage resource and tenant mappings, and inspect replication health.
openstack dr <resource> <action> [<positional-args>] [--flags]
All commands follow the openstack dr <resource> <verb> pattern. Run openstack help dr to list every command, or append --help to any command for its specific usage.
Every openstack dr command inherits the global OpenStackClient output flags listed below. Command-specific flags are documented per-command in the Subcommands section.
| Flag | Short | Default | Description |
|---|---|---|---|
--format <string> | -f | table | Output format: table, json, yaml, value, csv |
--column <string> | -c | (all) | Column(s) to include in output; repeatable |
--max-width <number> | terminal width | Maximum display width for table output | |
--fit-width | off | Fit table to terminal width | |
--print-empty | off | Print an empty table if there is no data | |
--noindent | off | Disable JSON indentation | |
--prefix <string> | Add a prefix to all column names | ||
--sort-column <string> | Sort results by this column; repeatable | ||
--sort-ascending | Sort ascending (default) | ||
--sort-descending | Sort descending | ||
--quote <string> | nonnumeric | CSV quoting style | |
--help | -h | Show help and exit |
Commands are grouped by resource. Each entry shows the full command, required positional arguments, key flags, and the minimum role needed.
Site management
| Command | Description |
|---|---|
openstack dr site list | List all registered DR sites |
openstack dr site show <site> | Show full details of one site |
openstack dr site create <name> | Register a new DR site |
openstack dr site set <site> | Update a site's credentials or metadata |
openstack dr site delete <site...> | Delete one or more sites |
openstack dr site failover <site> | Site-level failover: fail over all protection groups at a site simultaneously |
openstack dr replication audit | List volumes being replicated by the arrays that belong to no protection group |
openstack dr site list
List every site registered on this service instance. The table shows ID, Name, Status, Auth URL, and Region.
openstack dr site list
openstack dr site show <site>
Show all stored fields for one site, including service account details and capabilities. <site> is an ID or name.
openstack dr site show london-primary
openstack dr site create <name>
Register a new DR site. The site name is positional; --auth-url is the only required flag. There is no --site-type: primary/secondary is a per-protection-group role, not a property of the site.
Provide --service-username, --service-password, and --service-user-id in every production registration. Without them the service has no credentials to use once your token expires, and the first tenant-mapping creation fails with "Cannot resolve service user ID". Each site runs its own Keystone, so the protector user has a different UUID on each cluster — read the ID from the site you are registering:
# On the site being registered:
openstack user show protector -f value -c id
Register each site on both clusters with identical --auth-url values. The two peers recognise each other by this string; a mismatch breaks cross-site tenant mapping.
| Flag | Required | Description |
|---|---|---|
--auth-url <url> | Yes | Public Keystone endpoint of this site |
--description <text> | Human-readable description | |
--region <name> | OpenStack region name | |
--service-username <name> | Recommended | Keystone username for cross-site operations |
--service-password <pass> | Recommended | Keystone password for the service account |
--service-user-id <id> | Recommended | Keystone user UUID of the service account on this site |
--service-project-name <name> | Project for the service account (default: service) | |
--service-user-domain-name <domain> | User domain (default: Default) | |
--service-project-domain-name <domain> | Project domain (default: Default) | |
--service-project-id <id> | Project UUID (avoids domain ambiguity) | |
--service-user-domain-id <id> | User domain UUID | |
--service-project-domain-id <id> | Project domain UUID | |
--protector-api-url <url> | Explicit Protector API URL when it differs from Keystone's host |
Requires: dr_site_admin role.
# Register the local site (run on the primary cluster)
SVC_USER_ID=$(openstack user show protector -f value -c id)
openstack dr site create london-primary \
--auth-url https://keystone.london.example.com:5000 \
--region RegionOne \
--service-username protector \
--service-password "$PROTECTOR_PASSWORD" \
--service-user-id "$SVC_USER_ID" \
--service-project-name service
openstack dr site set <site>
Update any site field. All flags are optional; only supplied flags are changed.
| Flag | Description |
|---|---|
--name <name> | New site name |
--description <text> | New description |
--auth-url <url> | Updated Keystone URL |
--region <name> | Updated region name |
--status <ACTIVE|MAINTENANCE|ERROR> | Manually set site status |
--service-username / --service-password / --service-user-id | Update service credentials |
--service-project-name / --service-project-id | Update service project |
--service-user-domain-name / --service-user-domain-id | Update user domain |
--service-project-domain-name / --service-project-domain-id | Update project domain |
--protector-api-url <url> | Update the explicit API URL |
Requires: dr_site_admin role.
openstack dr site set london-primary --status MAINTENANCE
openstack dr site delete <site...>
Delete one or more sites by ID or name. The API refuses deletion with HTTP 409 (SiteInUse) while protection groups, tenant mappings, or operations reference the site. Pass --force to bypass this check; orphaned references are left pointing at a site that no longer resolves, which breaks failover for the affected groups.
| Flag | Description |
|---|---|
--force | Delete even if references exist (leaves orphans) |
Requires: dr_site_admin role.
openstack dr site failover <site>
Site-level failover: fail over all protection groups at a site simultaneously. The server starts each group's failover in parallel. Use this as the "big red button" when an entire site must be evacuated. Each group's individual operation appears in openstack dr operation list; there is no single site-wide operation record — progress is tracked per group via openstack dr site operation show.
| Flag | Default | Description |
|---|---|---|
--failover-type <planned|unplanned> | planned | Failover mode applied to every group |
--force | off | Skip validation for all groups |
--yes / -y | off | Skip the confirmation prompt |
Requires: dr_site_admin role.
openstack dr site failover london-primary --failover-type unplanned --yes
openstack dr replication audit
List volumes the storage arrays are actively replicating that belong to no protection group. These volumes consume replication capacity but have no managed recovery points and no service-coordinated failover path. Use this to find "shadow" replication that predates the service, or to audit for orphaned replicas after a protection group is deleted.
Requires: dr_site_admin role.
openstack dr replication audit
Site operations
Site-level failover dispatches individual protection-group operations and records progress in site operation objects.
| Command | Description |
|---|---|
openstack dr site operation list | List site-level operations |
openstack dr site operation show <operation> | Show one site operation with per-group child operations |
openstack dr site operation list
| Flag | Description |
|---|---|
--site <id> | Filter by site ID |
--status <pending|running|completed|partial_success|failed> | Filter by status |
--limit <number> | Maximum results |
openstack dr site operation show <operation>
Shows the site operation and its child_operations list — one entry per protection group that was started.
Protection groups
A protection group is a named set of VMs whose volumes are replicated together as a crash-consistent unit.
| Command | Description |
|---|---|
openstack dr protection group list | List protection groups in this project |
openstack dr protection group show <pg> | Show protection group details |
openstack dr protection group create <name> | Create a new protection group |
openstack dr protection group set <pg> | Update a protection group |
openstack dr protection group delete <pg...> | Delete one or more protection groups |
openstack dr protection group sync <pg> | Sync VM state into the group and push to the DR site |
openstack dr protection group reconcile <pg> | Repair a group left inconsistent by an interrupted failover or failback |
openstack dr protection group member add <pg> | Add a VM to a protection group |
openstack dr protection group member set <pg> | Update a member's boot order |
openstack dr protection group member remove <pg> | Remove a VM from a protection group |
openstack dr protection group member list <pg> | List members of a protection group |
openstack dr protection group member validate <pg> | Validate that a VM can be added without adding it |
openstack dr protection group mapping list <pg> | List resource mappings (networks, flavors, floating IPs) |
openstack dr protection group mapping create <pg> | Create an explicit resource mapping |
openstack dr protection group mapping delete <pg> <mapping> | Delete a resource mapping |
openstack dr protection group floating ip prepare <pg> | Allocate and map a DR floating IP for every unmapped address |
openstack dr protection group list
List protection groups in your project. The table shows ID, Name, Status, Primary Site, Secondary Site, member count, and creation time. Site columns display the site name, falling back to the site ID.
| Flag | Description |
|---|---|
--all-projects | Show groups from all projects (admin only) |
openstack dr protection group list
openstack dr protection group list --all-projects -f json
openstack dr protection group show <pg>
Show all fields including member list, resource mappings summary, replication coverage, and a next_step hint when the group is in error state after an interrupted operation. <pg> is an ID or name.
| Flag | Description |
|---|---|
--all-projects | Access a group from any project (admin only) |
openstack dr protection group show prod-web-tier
openstack dr protection group create <name>
Create a protection group. Both --primary-site and --secondary-site are required; the API never infers the secondary. For async replication, --volume-type is also required; for active_dr it is not (the CLI enforces this client-side and exits before sending any request).
| Flag | Required | Description |
|---|---|---|
--primary-site <site> | Yes | Primary site ID or name |
--secondary-site <site> | Yes | Secondary site ID or name |
--replication-type <async|active_dr> | Replication mode (default: async) | |
--volume-type <type> | For async | Cinder volume type with replication_enabled=True |
--description <text> | Description |
# Async replication — volume type required
openstack dr protection group create prod-web-tier \
--primary-site london-primary \
--secondary-site frankfurt-dr \
--replication-type async \
--volume-type replicated-ssd
# ActiveDR continuous replication — no volume type needed
openstack dr protection group create prod-db-tier \
--primary-site london-primary \
--secondary-site frankfurt-dr \
--replication-type active_dr
openstack dr protection group set <pg>
Update a protection group's metadata or, with admin credentials, manually reset its status after a manual recovery.
| Flag | Description |
|---|---|
--name <name> | New name |
--description <text> | New description |
--status <active|failed_over|error> | Force status (admin only — use only to recover from inconsistent state) |
--reset-to-primary | Reset current_primary_site to the original primary |
--reset-to-secondary | Set current_primary_site to the secondary site |
# After manual recovery, re-synchronise service state:
openstack dr protection group set prod-web-tier \
--status active --reset-to-primary
openstack dr protection group delete <pg...>
Delete one or more protection groups. If the delete cannot clean up resources on the peer (for example, the peer is unreachable when --force is used), the response includes a leftovers list of items that were not removed — the CLI prints them because they are the only record of their existence once the local row is gone.
| Flag | Description |
|---|---|
--force | Delete even if the group is in a transitional state |
openstack dr protection group sync <pg>
Detect changes to member VMs (new volumes, changed security groups, changed networks) and push an updated metadata snapshot to the DR site. Run this after adding or removing members or after any infrastructure change that must be reflected on the recovery site before the next failover.
| Flag | Default | Description |
|---|---|---|
--dry-run | off | Report changes without applying them |
--volumes | on | Include volume changes |
--security-groups | on | Include security group changes |
--networks | on | Include network changes |
# Full sync after adding a VM
openstack dr protection group sync prod-web-tier
# Preview only
openstack dr protection group sync prod-web-tier --dry-run
openstack dr protection group reconcile <pg>
Repair a protection group left inconsistent by an interrupted failover or failback. Reconcile inspects storage, VMs, and operation history to fix the group's status, relink discovered VMs, restart SHUTOFF workloads on the writable site, and synchronise the corrected state to the peer. It works even when the primary site is unreachable. Each reconcile is recorded as an operation of type reconcile in the operation list.
Use this when openstack dr protection group show reports status: error and the next_step field suggests reconciliation, or when a failover or failback was interrupted mid-operation.
openstack dr protection group reconcile prod-web-tier
# Monitor the resulting reconcile operation
openstack dr operation list --protection-group prod-web-tier \
--operation-type reconcile
openstack dr protection group member add <pg>
Add a VM to a protection group. The VM must boot from a Cinder volume, and every attached volume must use a volume type with replication_enabled='<is> True'. LUKS-encrypted volumes are rejected; use array-side encryption (Pure data-at-rest) instead.
boot_order is an integer: lower values start first during recovery; VMs sharing a value start in parallel.
| Flag | Required | Description |
|---|---|---|
--instance <id> | Yes | Instance UUID to add |
--boot-order <n> | Boot order priority (default: 0) |
# Add the web server first, then the app server
openstack dr protection group member add prod-web-tier \
--instance 8abe6b31-d704-4728-931d-4d6ab25540ce \
--boot-order 1
openstack dr protection group member add prod-web-tier \
--instance c3f12345-aaaa-4000-bbbb-000000000001 \
--boot-order 2
openstack dr protection group member set <pg>
Update an existing member's boot order.
| Flag | Required | Description |
|---|---|---|
--member <id> | Yes | Member ID (from member list) |
--boot-order <n> | Yes | New boot order |
openstack dr protection group member remove <pg>
Remove a VM from a protection group. The CLI prints what will be removed on the DR site and prompts for confirmation; --yes skips the prompt.
| Flag | Description |
|---|---|
--member <id> | Member ID to remove (required) |
--yes | Skip confirmation prompt |
openstack dr protection group member list <pg>
List all members of a protection group with their status and boot order.
openstack dr protection group member list prod-web-tier
openstack dr protection group member validate <pg>
Run all eligibility checks for a VM without adding it. Returns detailed feedback about why an instance may not be eligible — useful before a planned add during a maintenance window.
| Flag | Required | Description |
|---|---|---|
--instance <id> | Yes | Instance UUID to validate |
openstack dr protection group member validate prod-web-tier \
--instance 8abe6b31-d704-4728-931d-4d6ab25540ce
openstack dr protection group mapping list <pg>
List all resource mappings for a protection group and show why each was resolved as it was. Auto-mapping runs during metadata sync; this command lets you audit its decisions, including resources it deliberately left unmapped (recorded with no target and a reason rather than left absent).
The Status column has three values: ok (mapped and validated), DIFFERS (mapped but the shapes differ between sites — worth investigating before a failover window), and not mapped.
The Set By column shows whether the mapping was created by an operator (operator), derived by auto-map (adopted or auto-map), or created automatically as a new resource (created).
| Flag | Description |
|---|---|
--type <type> | Filter by type: network, subnet, security_group, flavor |
--unmapped | Show only resources that were considered but not mapped |
--differing | Show only mapped resources that differ from the source |
# Review all mappings before a failover
openstack dr protection group mapping list prod-web-tier
# Find anything that might cause problems
openstack dr protection group mapping list prod-web-tier --differing
openstack dr protection group mapping list prod-web-tier --unmapped
openstack dr protection group mapping create <pg>
Create an explicit resource mapping. An explicit mapping outranks anything auto-map derives and auto-map will not overwrite it. Use this when the two sites name the same resource differently, or when auto-map adopted a resource you did not intend.
Accepted --resource-type values: network, flavor, floating_ip_pool, floating_ip. Note that subnet and security_group return HTTP 400 (Unsupported resource type) — these are managed automatically.
After creating a mapping, run openstack dr protection group sync so the DR site receives it before the next failover.
| Flag | Required | Description |
|---|---|---|
--resource-type <type> | Yes | network, flavor, floating_ip_pool, or floating_ip |
--primary-resource-id <id> | Yes | Resource ID (or address for floating_ip) on the primary site |
--secondary-resource-id <id> | Yes | Resource ID (or address) on the secondary site |
# Map a network that has different names on each site
openstack dr protection group mapping create prod-web-tier \
--resource-type network \
--primary-resource-id london-internal-net \
--secondary-resource-id frankfurt-internal-net
# Map a floating IP one-to-one
openstack dr protection group mapping create prod-web-tier \
--resource-type floating_ip \
--primary-resource-id 203.0.113.10 \
--secondary-resource-id 198.51.100.10
openstack dr protection group mapping delete <pg> <mapping>
Delete a resource mapping, here and on the DR site. An adopted mapping (network, flavor) is re-derived by the next auto-map, so this is also how you hand an explicit mapping back to auto-map.
openstack dr protection group floating ip prepare <pg>
For each floating IP on the group's VMs that has no floating_ip mapping yet, allocate a floating IP in this project on the DR site and create the mapping, then sync the group. Print the pairs so DNS can be prepared before any failover. Already-mapped addresses are left alone; run again after adding VMs or new floating IPs.
The DR addresses are the project's — failback never releases them.
| Flag | Description |
|---|---|
--dr-network <network> | DR external network to allocate from (ID or name). Defaults to the DR side of the floating_ip_pool mapping, then the DR site's only external network |
--dry-run | Show what would be allocated and mapped; change nothing |
--no-sync | Skip the automatic sync after mapping (run protection group sync manually before the next failover) |
# Prepare DR addresses for all unmapped floating IPs
openstack dr protection group floating ip prepare prod-web-tier
# Preview only
openstack dr protection group floating ip prepare prod-web-tier --dry-run
DR operations
| Command | Description |
|---|---|
openstack dr failover <pg> | Execute protection-group failover |
openstack dr failback <pg> | Execute protection-group failback |
openstack dr test failover <pg> | Non-disruptive DR test |
openstack dr test failover cleanup <pg> | Clean up test failover resources |
openstack dr operation list | List DR operations |
openstack dr operation show <operation> | Show operation progress and results |
openstack dr operation cancel <operation> | Cancel a running operation |
openstack dr metadata sync <pg> | Trigger metadata synchronisation between sites |
openstack dr failover <pg>
Execute failover for a protection group. Two failover types are available:
planned(default): Orderly failover with graceful VM shutdown and a final synchronisation snapshot. On partial failure, all changes are rolled back.unplanned: Emergency failover when the primary site is down. On partial failure, continues with successfully migrated VMs.
The command accepts --wait to block until the operation completes. Without it the command returns as soon as the operation is accepted (status pending), and you poll it with openstack dr operation show.
The --network-mapping and --flavor-mapping flags use = as the separator (source=destination). The source side of a network mapping must be the network name as it appears in openstack dr operation show output — instance metadata carries names, not UUIDs, so a source UUID here matches nothing.
Recovered instances are created as <original-name>-failover.
| Flag | Default | Description |
|---|---|---|
--failover-type <planned|unplanned> | planned | Failover mode |
--recovery-point <point> | latest | Specific recovery point (snapshot) to restore to. Use openstack dr recovery point list to see available points. Accepts full name or suffix. Use for ransomware or corruption recovery |
--force | off | Skip validation and primary site operations |
--timeout <seconds> | 30 | Timeout for the primary site connectivity check |
--wait | off | Block until the operation finishes |
--wait-timeout <seconds> | 1800 | How long --wait polls before giving up. Giving up does not cancel the operation on the server |
--network-mapping <src-name>=<dst> | Map a source network name to a different network on the target site. Repeatable | |
--subnet-mapping <src-id>=<dst-id> | Map a source subnet to a different subnet. Repeatable | |
--flavor-mapping <src-id>=<dst-id> | Map a source flavor to a different flavor. Repeatable | |
--all-projects | off | Access protection group from any project (admin only) |
# Planned failover, wait for completion
openstack dr failover prod-web-tier \
--failover-type planned \
--wait
# Unplanned failover with explicit network mapping
openstack dr failover prod-web-tier \
--failover-type unplanned \
--network-mapping london-internal=frankfurt-internal \
--wait --wait-timeout 3600
# Failover to a specific recovery point (ransomware recovery)
openstack dr failover prod-web-tier \
--failover-type planned \
--recovery-point prod-web-tier.2024-01-15T14:30:00
# Monitor a failover that was started without --wait
openstack dr operation show <operation-id>
openstack dr failback <pg>
Fail a protection group back to its primary site after a failover. The service plans the failback before starting it; the plan is shown so you can verify what will happen. Use --dry-run to see the plan without starting anything, or --yes to confirm and start without being prompted.
Failback creates recovered instances as <original-name>-restored. Note that a full round-trip (failover then failback) does not restore the original instance name — DNS, monitoring, and runbooks keyed on instance names need updating after both operations.
Failback waits for each DR volume's Nova attachment to release before unmanaging it (up to 120 seconds per volume). A slow detach makes the failback take longer but does not abort it.
| Flag | Default | Description |
|---|---|---|
--failback-type <planned|unplanned> | planned | Failback mode |
--dry-run | off | Show the failback plan; start nothing |
--yes | off | Confirm without being prompted (non-interactive use) |
--resync | off | Force a resync before failing back |
--force | off | Skip validation |
--network-mapping <src-name>=<dst> | Network mapping for the restored VMs. Repeatable | |
--subnet-mapping <src-id>=<dst-id> | Subnet mapping. Repeatable | |
--flavor-mapping <src-id>=<dst-id> | Flavor mapping. Repeatable | |
--wait | off | Block until the operation finishes |
--wait-timeout <seconds> | 1800 | How long --wait polls before giving up |
--all-projects | off | Access protection group from any project (admin only) |
# Preview the failback plan
openstack dr failback prod-web-tier --dry-run
# Planned failback, non-interactive
openstack dr failback prod-web-tier \
--failback-type planned \
--yes --wait
openstack dr test failover <pg>
Execute a non-disruptive DR test. Test failover creates copies of the protected VMs on the DR site in an isolated environment without promoting the replicated volumes or affecting production. Run openstack dr test failover cleanup when done to remove the test instances.
| Flag | Description |
|---|---|
--auto-network | Automatically create an isolated test network |
--network-mapping <src-name>=<dst> | Map networks for the test instances. Repeatable |
--subnet-mapping <src-id>=<dst-id> | Map subnets. Repeatable |
--flavor-mapping <src-id>=<dst-id> | Map flavors. Repeatable |
--security-group-mapping <src>=<dst> | Map security groups. Repeatable |
--availability-zone <az> | Target availability zone for test instances |
--instance-prefix <prefix> | Prefix for test instance names |
--recovery-point <point> | Specific recovery point to test against |
--wait | Block until the operation finishes |
--wait-timeout <seconds> | How long --wait polls (default: 1800) |
--all-projects | Access protection group from any project (admin only) |
# Run a test failover and wait
TEST_OP=$(openstack dr test failover prod-web-tier \
--auto-network \
--wait \
-f value -c id)
# Inspect the test instances on the DR site, then clean up
openstack dr test failover cleanup prod-web-tier
openstack dr test failover cleanup <pg>
Clean up all resources created by a test failover — instances, volumes, and test networks.
| Flag | Description |
|---|---|
--operation <id> | Specific test failover operation to clean up |
--force | Force cleanup even if the test is still in progress |
openstack dr test failover cleanup prod-web-tier
openstack dr operation list
List DR operations, optionally filtered. The table shows ID, Protection Group, Operation Type, Status, Progress (as a percentage), and Started At. Progress is an integer 0–100; there is no estimated completion time.
| Flag | Description |
|---|---|
--protection-group <id> | Filter by protection group ID |
--status <status> | Filter by status |
--operation-type <type> | Filter by operation type |
openstack dr operation list
openstack dr operation list --protection-group prod-web-tier --status running
openstack dr operation list --operation-type reconcile
openstack dr operation show <operation>
Show full details of one operation. Columns include source_site and target_site (shown as site names, falling back to IDs), progress (percentage), error_message, and, when present: warnings, floating_ips, floating_ip_plan, restore_point, and diverged_copy from result_data.
There is no estimated completion time; track progress with repeated calls to this command.
openstack dr operation show 7c3d2a18-1111-4444-aaaa-000000000001
# Poll until done (bash example)
while true; do
STATUS=$(openstack dr operation show $OP_ID -f value -c status)
PROGRESS=$(openstack dr operation show $OP_ID -f value -c progress)
echo "Status: $STATUS Progress: $PROGRESS"
[[ "$STATUS" =~ ^(completed|failed|cancelled|error|partial_success)$ ]] && break
sleep 5
done
openstack dr operation cancel <operation>
Request cancellation of a running operation. Not all operations or operation stages support cancellation; the engine will cancel at the next safe point.
openstack dr operation cancel 7c3d2a18-1111-4444-aaaa-000000000001
openstack dr metadata sync <pg>
Manually trigger metadata synchronisation from one site to the other. The engine runs this automatically on a schedule; use this command to force an immediate sync after a configuration change.
| Flag | Description |
|---|---|
--direction <primary_to_secondary|secondary_to_primary> | Direction of sync |
openstack dr metadata sync prod-web-tier --direction primary_to_secondary
Replication health and recovery points
| Command | Description |
|---|---|
openstack dr replication health <pg> | Show replication health metrics for a protection group |
openstack dr recovery point list <pg> | List available recovery points |
openstack dr recovery point create <pg> | Create an on-demand recovery point |
openstack dr replication health <pg>
Return a replication health report for a protection group: link status, sync status, replication lag, recovery point summary, transfer performance, and failover readiness.
The --probe flag asks the recovery site — live, over the network — whether the group's networks, security groups, and flavors resolve there, as the project the group recovers into. A resource that exists on the recovery site under a different project is correctly reported as missing. This is a resource-resolution check, not a storage or replication-lag check, and it is slower than the plain command because it queries the peer. Run it before a planned failover window, not as a routine polling command.
| Flag | Description |
|---|---|
--probe | Also query the recovery site for resource resolution |
# Basic health check
openstack dr replication health prod-web-tier
# Full pre-failover check including resource resolution on the DR site
openstack dr replication health prod-web-tier --probe
openstack dr recovery point list <pg>
List available recovery points (snapshots) for async replication. Use the point name or suffix with openstack dr failover --recovery-point to restore to a specific point.
| Flag | Default | Description |
|---|---|---|
--limit <n> | 20 | Maximum number of points to return |
openstack dr recovery point list prod-web-tier
openstack dr recovery point list prod-web-tier --limit 50
openstack dr recovery point create <pg>
Create an on-demand recovery point immediately, outside the scheduled interval.
| Flag | Description |
|---|---|
--suffix <text> | Optional snapshot suffix |
openstack dr recovery point create prod-web-tier --suffix pre-maintenance
Tenant-wide operations
Fail over or fail back every protection group in your project with a single command. The server starts all eligible groups in parallel. Groups this site cannot act on are listed as skipped, with a reason.
| Command | Description |
|---|---|
openstack dr tenant failover | Fail over all protection groups in this project |
openstack dr tenant failback | Fail back all protection groups in this project |
openstack dr tenant failover
Run on the DR site. Starts a failover of each active protection group whose DR site is the current site. Groups that are already failed over, in an error state, or whose DR site is elsewhere are listed as skipped.
| Flag | Default | Description |
|---|---|---|
--failover-type <planned|unplanned> | planned | Applied to every group |
--group <protection-group> | (all groups) | Act on only this protection group (name or ID); repeat for several. Default: every group in the project. |
--dry-run | off | List what would be started, and why anything would be skipped; start nothing. |
--wait | off | Block until every operation finishes; without it the command returns once all are accepted. |
--wait-timeout <seconds> | 3600 | How long --wait polls before giving up; giving up does not cancel anything. |
# On the DR site:
openstack dr tenant failover --failover-type planned
openstack dr tenant failback
Run on the primary site. Plans the failback of every failed-over group whose primary is the current site, displays the plans, then starts them all. If any plan is refused, or needs confirmation that has not been given, none is started — a tenant half failed back is worse than one not failed back at all.
| Flag | Default | Description |
|---|---|---|
--failback-type <planned|unplanned> | planned | Applied to every group |
--yes | off | Confirm all plans that need it without prompting |
--group <protection-group> | (all groups) | Act on only this protection group (name or ID); repeat for several. Default: every group in the project. |
--dry-run | off | List what would be started, and why anything would be skipped; start nothing. |
--wait | off | Block until every operation finishes; without it the command returns once all are accepted. |
--wait-timeout <seconds> | 3600 | How long --wait polls before giving up; giving up does not cancel anything. |
# Interactive: review plans and confirm
openstack dr tenant failback
# Non-interactive (CI/runbook):
openstack dr tenant failback --yes
Tenant mappings
Tenant mappings tell the engine how to translate a project UUID from one site to its counterpart on the peer. Without a mapping the engine assumes the project UUID is identical on both sites — correct for shared or federated Keystone deployments, and almost never correct for two independent clusters. An absent mapping fails during a cross-site operation rather than at setup time, which can surface as a confusing error mid-failover.
dr_site_admin is a cloud-wide role: a holder can create tenant mappings for every project regardless of which project the role is granted on. Grant it to a cloud operator on the admin project, not per DR project.
| Command | Description |
|---|---|
openstack dr tenant mapping list | List tenant mappings |
openstack dr tenant mapping show <mapping> | Show one mapping's details |
openstack dr tenant mapping create | Create a new tenant mapping |
openstack dr tenant mapping delete <mapping...> | Delete one or more mappings |
openstack dr tenant mapping validate <mapping> | Re-validate a tenant mapping |
openstack dr tenant mapping list
List tenant mappings. The table shows Local Tenant, Local Domain, Remote Site, Remote Tenant, Remote Domain, and Status. Domain columns are included because a project name is not unique across domains.
| Flag | Description |
|---|---|
--all-projects | List mappings from all projects (admin only). --all-tenants is accepted as an alias |
--remote-site <id> | Filter by remote site ID |
--status <active|pending_validation|validation_failed|disabled> | Filter by status |
openstack dr tenant mapping create
Create a tenant mapping. All three ID flags are required.
| Flag | Required | Description |
|---|---|---|
--local-tenant <id> | Yes | Local project UUID |
--remote-site <id> | Yes | Remote site ID |
--remote-tenant <id> | Yes | Remote project UUID on that site |
--description <text> | Description | |
--skip-validation | Skip tenant validation (admin only) |
Requires: dr_site_admin role.
openstack dr tenant mapping create \
--local-tenant aabbccdd-0000-1111-2222-333344445555 \
--remote-site frankfurt-dr \
--remote-tenant 99887766-ffff-eeee-dddd-ccccbbbbaaaa
openstack dr tenant mapping delete <mapping...>
Delete one or more tenant mappings by ID.
| Flag | Description |
|---|---|
--no-sync-remote | Do not delete the mapping on the remote site |
openstack dr tenant mapping validate <mapping>
Re-run validation for a mapping that is in pending_validation or validation_failed status.
Requires: dr_site_admin role.
openstack dr tenant mapping validate <mapping-id>
Usage and billing reports
Admin-only commands that report current protection coverage and generate billing data.
| Command | Description |
|---|---|
openstack dr usage summary | Show protected VM and volume counts per tenant |
openstack dr usage report | Generate a usage report as PDF or JSON |
openstack dr usage summary
Show current usage per tenant: protected VM count, protection group count, and total volume capacity in GB.
openstack dr usage summary
openstack dr usage report
Generate a usage report for a billing period.
| Flag | Default | Description |
|---|---|---|
--period <monthly|quarterly|annual> | monthly | Report period |
--start-date <YYYY-MM-DD> | Explicit start date (overrides --period) | |
--end-date <YYYY-MM-DD> | Explicit end date (overrides --period) | |
--format <pdf|json> | pdf | Output format |
--output <file> | auto-named for PDF; stdout for JSON | Output file path |
# Monthly PDF report
openstack dr usage report --period monthly --format pdf
# Custom date range as JSON
openstack dr usage report \
--start-date 2024-01-01 \
--end-date 2024-03-31 \
--format json
Failover to this site
openstack dr failover to this site
Simplified site-level failover: fail over every protection group that is not currently on this site, bringing everything to the site the command runs on. Groups already here are unaffected. Requires dr_site_admin.
| Flag | Default | Description |
|---|---|---|
--failover-type <planned|unplanned> | planned | Failover mode |
--force | off | Skip validation |
--yes / -y | off | Skip confirmation prompt |
# From the DR site — bring everything here
openstack dr failover to this site --failover-type unplanned --yes
The openstack dr commands use the standard OpenStackClient environment variables for authentication and endpoint discovery.
| Variable | Default | Description |
|---|---|---|
OS_AUTH_URL | (none) | Keystone endpoint URL |
OS_USERNAME | (none) | OpenStack username |
OS_PASSWORD | (none) | OpenStack password |
OS_PROJECT_NAME | (none) | Project (tenant) name |
OS_PROJECT_ID | (none) | Project UUID (alternative to name) |
OS_USER_DOMAIN_NAME | Default | User domain name |
OS_PROJECT_DOMAIN_NAME | Default | Project domain name |
OS_REGION_NAME | (none) | OpenStack region |
OS_CACERT | (none) | Path to CA certificate bundle for TLS verification |
OS_INSECURE | false | Disable TLS certificate verification |
OS_CLOUD | (none) | Named cloud from clouds.yaml (alternative to individual variables) |
OS_PROTECTOR_API_VERSION | 1 | Protector API version to request |
Source your site's RC file before running any command:
source ~/drtest-cluster1-openrc.sh
openstack dr protection group list
| Code | Meaning |
|---|---|
0 | Success |
1 | General error (authentication failure, API error, invalid arguments, --wait timed out) |
When --wait times out, the command exits with code 1 and prints a message including the operation ID and a openstack dr operation show command to continue tracking. The operation continues running on the server — timing out the client does not cancel it.
When a tenant-wide failover or failback (dr tenant failover / dr tenant failback) starts some groups successfully but others fail, the table is printed to stderr and the command exits with code 1, naming the failed groups. Successfully started operations are not rolled back.
Register two sites and create a protection group
# Source credentials for the primary cluster
source drtest-cluster1-openrc.sh
# Get the service account user ID from the primary site
SVC_USER_ID_1=$(openstack user show protector -f value -c id)
# Register the local (primary) site
openstack dr site create london-primary \
--auth-url https://keystone.london.example.com:5000 \
--region RegionOne \
--service-username protector \
--service-password "$PROTECTOR_PASSWORD" \
--service-user-id "$SVC_USER_ID_1" \
--service-project-name service
# Register the DR site (run on the same cluster;
# the user ID must come from the DR cluster's Keystone)
source drtest-cluster2-openrc.sh
SVC_USER_ID_2=$(openstack user show protector -f value -c id)
source drtest-cluster1-openrc.sh
openstack dr site create frankfurt-dr \
--auth-url https://keystone.frankfurt.example.com:5000 \
--region RegionOne \
--service-username protector \
--service-password "$PROTECTOR_PASSWORD" \
--service-user-id "$SVC_USER_ID_2" \
--service-project-name service
# Verify
openstack dr site list
Create a protection group and add VMs
source drtest-cluster1-openrc.sh
# Create the group (async replication requires --volume-type)
openstack dr protection group create prod-web-tier \
--primary-site london-primary \
--secondary-site frankfurt-dr \
--replication-type async \
--volume-type replicated-ssd \
--description "Production web tier"
# Add VMs in boot order (database first, app second, web third)
DB_ID=$(openstack server show prod-db -f value -c id)
APP_ID=$(openstack server show prod-app -f value -c id)
WEB_ID=$(openstack server show prod-web -f value -c id)
openstack dr protection group member add prod-web-tier \
--instance "$DB_ID" --boot-order 1
openstack dr protection group member add prod-web-tier \
--instance "$APP_ID" --boot-order 2
openstack dr protection group member add prod-web-tier \
--instance "$WEB_ID" --boot-order 3
# Sync state to the DR site
openstack dr protection group sync prod-web-tier
Pre-failover health check
# Basic replication health
openstack dr replication health prod-web-tier
# Full check: also verify resources resolve on the DR site
# as the project this group recovers into
openstack dr replication health prod-web-tier --probe
# Review resource mappings for anything that differs between sites
openstack dr protection group mapping list prod-web-tier --differing
openstack dr protection group mapping list prod-web-tier --unmapped
# List recent recovery points
openstack dr recovery point list prod-web-tier
Execute a planned failover and monitor it
# From the DR site
source drtest-cluster2-openrc.sh
openstack dr failover prod-web-tier \
--failover-type planned \
--wait --wait-timeout 3600
# If you omit --wait, track it manually:
OP_ID=$(openstack dr failover prod-web-tier --failover-type planned \
-f value -c id)
openstack dr operation show "$OP_ID"
Failover with explicit network and flavor mappings
# Network source must be the name as it appears in operation show output
openstack dr failover prod-web-tier \
--failover-type planned \
--network-mapping london-internal-net=frankfurt-internal-net \
--flavor-mapping a3f2b1c0-aaaa-bbbb-cccc-ddddeeee0001=m1.large \
--wait
Ransomware recovery: failover to a specific recovery point
# List available recovery points
openstack dr recovery point list prod-web-tier
# Fail over to the last known-good snapshot
openstack dr failover prod-web-tier \
--failover-type planned \
--recovery-point prod-web-tier.2024-01-15T14:30:00 \
--wait
Non-disruptive DR test
source drtest-cluster2-openrc.sh
# Run the test
openstack dr test failover prod-web-tier --auto-network --wait
# Verify the test instances look correct, then clean up
openstack dr test failover cleanup prod-web-tier
Reconcile an inconsistent protection group
# A group shows status: error after an interrupted failover
openstack dr protection group show prod-web-tier
# Reconcile repairs it even when the primary site is unreachable
openstack dr protection group reconcile prod-web-tier
# Monitor the reconcile operation
openstack dr operation list \
--protection-group prod-web-tier \
--operation-type reconcile
Create a tenant mapping
# Cloud-operator task — requires dr_site_admin on the admin project
source admin-openrc.sh
LOCAL_PROJECT=$(openstack project show myproject -f value -c id)
REMOTE_PROJECT=99887766-ffff-eeee-dddd-ccccbbbbaaaa
DR_SITE=$(openstack dr site show frankfurt-dr -f value -c id)
openstack dr tenant mapping create \
--local-tenant "$LOCAL_PROJECT" \
--remote-site "$DR_SITE" \
--remote-tenant "$REMOTE_PROJECT"
Prepare DR floating IPs before a failover
source drtest-cluster1-openrc.sh
# Preview what would be allocated
openstack dr protection group floating ip prepare prod-web-tier --dry-run
# Allocate and map, then sync to DR site automatically
openstack dr protection group floating ip prepare prod-web-tier
Script: automated DR test with status polling
#!/bin/bash
set -e
PG="prod-web-tier"
source drtest-cluster2-openrc.sh
echo "Starting test failover for $PG ..."
OP_ID=$(openstack dr test failover "$PG" --auto-network -f value -c id)
echo "Operation: $OP_ID"
while true; do
STATUS=$(openstack dr operation show "$OP_ID" -f value -c status)
PROGRESS=$(openstack dr operation show "$OP_ID" -f value -c progress)
echo "$(date -u +%H:%M:%S) status=$STATUS progress=$PROGRESS"
case "$STATUS" in
completed) echo "Test failover completed."; break ;;
failed|error|cancelled) echo "Test failover did not complete."; exit 1 ;;
esac
sleep 5
done
echo "Cleaning up test resources ..."
openstack dr test failover cleanup "$PG"
echo "Done."