---
title: CLI Reference
product: trilio-site-recovery-for-openstack
doc_type: cli_reference
version: master
source: git2docs (code-derived, validation-filtered)
canonical: https://git2docs.com/murali-balcha/docs/trilio-site-recovery-for-openstack/trilio-site-recovery-for-openstack/cli-reference
---

# CLI Reference

_Trilio Site Recovery implements a new OpenStack CLI plugin called dr. Users can use the DR plugin to manage the Trilio Site Recovery solution, including adding/removing sites and creating protection groups._

## Description

The `openstack dr` CLI plugin is the primary interface for managing Trilio Site Recovery operations. It extends the standard OpenStack client with a `dr` command group that covers the full DR lifecycle: registering sites, creating and populating Protection Groups, executing failover and failback, running non-disruptive DR tests, monitoring replication health, and administering tenant mappings. Install the plugin separately from the server package — it is distributed as the `triliositerecovery` Python package located in the `client/` subdirectory of the repository.

## Flags

Flags are grouped by command below. Standard OpenStack client output flags (`-f`, `-c`, `--sort-column`, `--fit-width`, etc.) apply to all commands and are not repeated here.

---

### `dr site create <name>`

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--site-type <PRIMARY\|SECONDARY>` | | *(required)* | Designates whether this site is the normal workload location (PRIMARY) or the DR target (SECONDARY). |
| `--auth-url <url>` | | *(required)* | Keystone authentication URL for this site. Must exactly match `keystone_authtoken.auth_url` in the site's `protector.conf`; the engine identifies which site it is running on by comparing this value as a string. |
| `--description <string>` | | | Human-readable description. |
| `--region <string>` | | | OpenStack region name on this site. |
| `--service-username <string>` | | | Keystone username of the cross-site service account. Strongly recommended — without it, scheduled and engine-initiated operations that run after the requesting user's token expires will fail. |
| `--service-password <string>` | | | Password for the service account. The API validates these credentials against the remote Keystone before saving. |
| `--service-project-name <string>` | | | Keystone project for the service account (typically `service`). |
| `--service-user-domain-name <string>` | | | Keystone user domain name (typically `Default`). |
| `--service-project-domain-name <string>` | | | Keystone project domain name (typically `Default`). |
| `--service-user-id <string>` | | | Keystone user ID of the service account on this site. Required for trust creation when the service account does not hold Keystone admin — without it the first tenant mapping fails with "Cannot resolve service user ID". Obtain it with `openstack user show protector -f value -c id` on the site being registered. |
| `--service-project-id <string>` | | | Keystone project ID (avoids domain-name ambiguity). |
| `--service-user-domain-id <string>` | | | Keystone user domain ID. |
| `--service-project-domain-id <string>` | | | Keystone project domain ID. |
| `--protector-api-url <string>` | | | Explicit Protector API URL (e.g. `https://protector.example.com:8788`) when the API runs on a different host than Keystone. |

> **Note:** The `--site-type`, `--auth-url`, and the site `<name>` positional argument are the only values `argparse` marks required. All service-credential flags are optional to the parser but strongly recommended in practice — see the `--service-username` description above. Consult `openstack dr site create --help` for the authoritative list.

---

### `dr site set <site>`

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--name <string>` | | | Rename the site. |
| `--description <string>` | | | Update description. |
| `--auth-url <string>` | | | Update Keystone URL. |
| `--region <string>` | | | Update region name. |
| `--status <ACTIVE\|MAINTENANCE\|ERROR>` | | | Override site status (admin only). |
| `--service-username <string>` | | | Update service account username. |
| `--service-password <string>` | | | Update service account password; triggers credential validation against the remote Keystone. |
| `--service-project-name <string>` | | | Update service project name. |
| `--service-user-domain-name <string>` | | | Update user domain name. |
| `--service-project-domain-name <string>` | | | Update project domain name. |
| `--service-user-id <string>` | | | Update service user ID. |
| `--service-project-id <string>` | | | Update service project ID. |
| `--service-user-domain-id <string>` | | | Update service user domain ID. |
| `--service-project-domain-id <string>` | | | Update service project domain ID. |
| `--protector-api-url <string>` | | | Update explicit Protector API URL. |

---

### `dr site delete [<site...>]`

*(No DR-specific flags. Accepts one or more site IDs or names.)*

---

### `dr site failover <site>`

Fails over **all** Protection Groups at a site simultaneously. Requires the `dr_site_admin` role.

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--failover-type <planned\|unplanned>` | | `planned` | Failover mode. `planned` gracefully shuts down VMs; `unplanned` skips shutdown for use when the primary is already down. |
| `--force` | | `false` | Force failover even if some Protection Groups have pre-check issues. |
| `--yes` / `-y` | `-y` | | Skip confirmation prompt. |

---

### `dr failover to this site`

Simplified site-level failover — fails over all Protection Groups that are **not** currently on this site, to this site. Requires `dr_site_admin` role.

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--failover-type <planned\|unplanned>` | | `planned` | Failover mode. |
| `--force` | | `false` | Force failover. |
| `--yes` / `-y` | `-y` | | Skip confirmation prompt. |

---

### `dr site operation list`

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--site <string>` | | | Filter by site ID or name. |
| `--status <pending\|running\|completed\|partial_success\|failed>` | | | Filter by operation status. |
| `--limit <number>` | | `50` | Maximum number of results to return. |

---

### `dr protection group list`

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--all-projects` | | `false` | Show Protection Groups from all projects (admin only). |

---

### `dr protection group show <protection_group>`

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--all-projects` | | `false` | Access a Protection Group from any project (admin only). |

---

### `dr protection group create <name>`

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--primary-site <string>` | | *(required)* | ID or name of the primary site. |
| `--secondary-site <string>` | | *(required)* | ID or name of the secondary (DR) site. |
| `--replication-type <async\|active_dr>` | | `async` | `async` uses periodic FlashArray Protection Group snapshots (RPO = replication interval). `active_dr` uses Pure Storage ActiveDR pod-based continuous replication (RPO ≈ 0, requires Purity//FA 6.0+). |
| `--volume-type <string>` | | | Cinder volume type ID or name. Required for `async` replication; the volume type must have `replication_enabled='<is> True'` set as an extra-spec. |
| `--description <string>` | | | Human-readable description. |

---

### `dr protection group set <protection_group>`

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--name <string>` | | | New name for the Protection Group. |
| `--description <string>` | | | New description. |
| `--status <active\|failed_over\|error>` | | | Force-set the Protection Group status (admin only). Use only to recover from an inconsistent state. |
| `--reset-to-primary` | | `false` | Reset `current_primary_site` to the original primary. Use after manual failback to sync state. |
| `--reset-to-secondary` | | `false` | Set `current_primary_site` to the secondary site. Use after manual failover to sync state. |

---

### `dr protection group delete [<protection_group...>]`

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--force` | | `false` | Force delete even if the Protection Group is in a transitional state. Resources that cannot be reached during forced deletion are listed in the output as "leftovers". |

---

### `dr protection group member add <protection_group>`

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--instance <string>` | | *(required)* | Nova instance UUID to add. The instance must boot from a Cinder volume; ephemeral boot disks are rejected with `InstanceNotCinderBoot` (HTTP 422). All attached volumes must use a Cinder volume type with `replication_enabled='<is> True'`; non-replicated types are rejected with `VolumeTypeNotReplicated` (HTTP 422). |
| `--boot-order <number>` | | `0` | Integer boot order for sequencing VM startup and shutdown during DR operations. VMs sharing the same value are processed in parallel; lower values complete before higher values begin. |

---

### `dr protection group member set <protection_group>`

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--member <string>` | | *(required)* | Member ID to update. |
| `--boot-order <number>` | | *(required)* | New boot order value. |

---

### `dr protection group member remove <protection_group>`

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--member <string>` | | *(required)* | Member ID to remove. Returns 202 Accepted with a pollable operation ID. |

---

### `dr protection group member validate <protection_group>`

Runs the same eligibility checks as `member add` without side effects. Returns a structured `errors` array. Use this before `member add` to surface problems early.

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--instance <string>` | | *(required)* | Nova instance UUID to validate. |

---

### `dr protection group sync <protection_group>`

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--dry-run` | | `false` | Show what would be synced without making changes. |
| `--volumes` | | `false` | Sync volume metadata only. |
| `--security-groups` | | `false` | Sync security group mappings only. |
| `--networks` | | `false` | Sync network mappings only. |

---

### `dr protection group mapping list <protection_group>`

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--type <string>` | | | Filter to one resource type: `network`, `subnet`, `security_group`, or `flavor`. |
| `--unmapped` | | `false` | Show only resources that were considered by auto-mapping but not mapped. |
| `--differing` | | `false` | Show only resources that are mapped but differ from the source. |

---

### `dr protection group mapping create <protection_group>`

Creates an explicit mapping that overrides auto-mapping. Auto-mapping will not overwrite an explicit mapping.

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--resource-type <string>` | | *(required)* | `network`, `subnet`, `security_group`, or `flavor`. |
| `--primary-resource-id <string>` | | *(required)* | Resource ID on the primary site. |
| `--secondary-resource-id <string>` | | *(required)* | Resource ID on the secondary site. |

---

### `dr recovery point list <protection_group>`

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--limit <number>` | | | Maximum number of recovery points to return. |

---

### `dr recovery point create <protection_group>`

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--suffix <string>` | | | Optional name suffix appended to the generated recovery point name. |

---

### `dr failover <protection_group>`

Moves a Protection Group's workloads from the primary site to the secondary site. A `planned` failover gracefully shuts down VMs and takes a final snapshot for zero data loss; an `unplanned` failover skips shutdown and accepts data loss up to the RPO.

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--failover-type <planned\|unplanned>` | | `planned` | Failover type. |
| `--recovery-point <string>` | | | Specific recovery point (snapshot) to restore from. Accepts the full name or a suffix. If omitted, creates a new snapshot of the current state. Use `openstack dr recovery point list <pg>` to see available points. Useful for recovery from ransomware or accidental data corruption. |
| `--force` | | `false` | Skip validation checks and primary site operations. Use with caution. |
| `--timeout <number>` | | `30` | Timeout in seconds for the primary site connectivity check. |
| `--wait` | | `false` | Block until the failover operation completes, polling operation status. |
| `--network-mapping <src-net>=<dst-net>` | | | Map a source network ID to a target network ID on the secondary site. Repeatable. If omitted, networks are resolved by name. |
| `--subnet-mapping <src-subnet>=<dst-subnet>` | | | Map a source subnet ID to a target subnet ID. Repeatable. |
| `--flavor-mapping <src-flavor>=<dst-flavor>` | | | Map a source flavor ID to a target flavor ID. Repeatable. If omitted, flavors are resolved by name. |
| `--all-projects` | | `false` | Access the Protection Group from any project (admin only). |

---

### `dr failback <protection_group>`

Returns a Protection Group's workloads to the original primary site after a failover.

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--resync` | | `false` | Force a full resync of data accumulated during the failover period before recreating VMs. |
| `--all-projects` | | `false` | Access the Protection Group from any project (admin only). |
| `--force` | | `false` | Force failback even if pre-checks fail. |
| `--failback-type <planned\|unplanned>` | | | Failback type. |
| `--network-mapping <src-net>=<dst-net>` | | | Map a network on the secondary site back to a network on the primary. Repeatable. |
| `--subnet-mapping <src-subnet>=<dst-subnet>` | | | Map a subnet. Repeatable. |
| `--flavor-mapping <src-flavor>=<dst-flavor>` | | | Map a flavor. Repeatable. |

---

### `dr test failover <protection_group>`

Non-disruptive DR validation. Clones replicated volumes from a recovery point on the secondary site and boots isolated test VMs with a `test-` prefix on a separate network. Production workloads are not affected. Either `--auto-network` or `--network-mapping` is required.

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--auto-network` | | | Automatically select an isolated network on the secondary site for test VMs. Required if `--network-mapping` is not provided. |
| `--network-mapping <string>` | | | Explicit network mapping for test VMs. Required if `--auto-network` is not provided. |
| `--recovery-point <string>` | | | Recovery point to clone from. Defaults to the most recent. |
| `--subnet-mapping <string>` | | | Subnet mapping for test VMs. |
| `--flavor-mapping <string>` | | | Flavor mapping for test VMs. |
| `--security-group-mapping <string>` | | | Security group mapping for test VMs. |
| `--availability-zone <string>` | | | Availability zone on the secondary site for test VMs. |
| `--instance-prefix <string>` | | `test-` | Name prefix for test VM instances. |
| `--all-projects` | | `false` | Access the Protection Group from any project (admin only). |

---

### `dr test failover cleanup <protection_group>`

Removes test VMs and cloned volumes created by a test failover. The required positional argument is a **Protection Group ID or name**, not an operation ID.

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--operation <string>` | | *(most recent test failover for the PG)* | Targets a specific test failover operation ID to clean up. |
| `--force` | | `false` | Force cleanup even if some resources fail to delete. |

---

### `dr operation list`

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--protection-group <string>` | | | Filter operations by Protection Group ID. |
| `--status <string>` | | | Filter by status (`pending`, `running`, `completed`, `failed`, etc.). |
| `--operation-type <string>` | | | Filter by operation type (`failover`, `failback`, `test_failover`, `test_cleanup`, `sync_volumes`, etc.). |

---

### `dr metadata sync <protection_group>`

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--force` | | `false` | Force metadata sync even if the remote site reports it is already up to date. |

---

### `dr tenant mapping list`

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--all-tenants` | | `false` | List mappings from all tenants (admin only). |
| `--remote-site <string>` | | | Filter by remote site ID. |
| `--status <active\|pending_validation\|validation_failed\|disabled>` | | | Filter by mapping status. |

---

### `dr tenant mapping create`

Creates a cross-site tenant mapping. The API validates both tenant IDs against their respective Keystone deployments before saving, then propagates the reverse mapping to the remote site. Port 8788 must be reachable bidirectionally for the sync to succeed.

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--local-tenant <string>` | | *(required)* | Project UUID on this site. |
| `--remote-site <string>` | | *(required)* | Remote site ID. |
| `--remote-tenant <string>` | | *(required)* | Project UUID on the remote site. |
| `--description <string>` | | | Human-readable description. |
| `--skip-validation` | | `false` | Skip Keystone tenant validation (admin only). |

---

### `dr tenant mapping delete [<mapping...>]`

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--no-sync-remote` | | `false` | Delete only the local mapping record, leaving the remote site's reverse mapping in place. |

---

### `dr usage report`

| Flag | Short | 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. `json` writes to stdout unless `--output` is given. |
| `--output <file>` | | *(auto-named for PDF, stdout for JSON)* | Output file path. |

## Subcommands

Commands are grouped by the resource they operate on.

| Subcommand group | Description |
|------------------|-------------|
| `dr site …` | Register, update, delete, and query OpenStack sites. Includes site-level failover (fails over all Protection Groups at once). |
| `dr site operation …` | Query site-level DR operations spawned by `dr site failover`. |
| `dr protection group …` | Create and manage Protection Groups and their members, resource mappings, and metadata sync. |
| `dr protection group member …` | Add, remove, update, validate, and list VMs inside a Protection Group. |
| `dr protection group mapping …` | Inspect and override the auto-derived resource mappings (networks, subnets, flavors, security groups) used during failover. |
| `dr replication health …` | Report live replication link status, RPO compliance, and failover readiness for a Protection Group. |
| `dr recovery point …` | List and manually create point-in-time snapshots selectable during failover or test failover. |
| `dr failover` | Execute a planned or unplanned Protection Group failover to the secondary site. |
| `dr failback` | Return a failed-over Protection Group to its original primary site. |
| `dr test failover` | Run a non-disruptive DR test by booting isolated clones on the secondary site. |
| `dr test failover cleanup` | Remove test VMs and cloned volumes left by a test failover. |
| `dr operation …` | List, inspect, and cancel individual DR operations (failover, failback, test failover, etc.). |
| `dr metadata sync` | Push Protection Group metadata from this site to the remote site. |
| `dr tenant mapping …` | Create and manage cross-site project identity translations required for multi-tenant DR. |
| `dr protection group reconcile` | Recover a Protection Group from an interrupted or partially-completed operation. |
| `dr failover to this site` | Site-level "big red button": fail over all Protection Groups not already on this site, to this site. |
| `dr usage summary` | Show current per-tenant usage (admin only). |
| `dr usage report` | Generate a usage/billing report in PDF or JSON format (admin only). |

## Environment variables

The `openstack dr` plugin authenticates and locates endpoints through the standard OpenStack client environment variables. No DR-specific variables are required beyond these.

| Variable | Default | Description |
|----------|---------|-------------|
| `OS_AUTH_URL` | | Keystone endpoint for the local site. The value here must match the `--auth-url` you register for this site, or the engine will not be able to identify which site it is running on. |
| `OS_USERNAME` | | OpenStack username. |
| `OS_PASSWORD` | | OpenStack password. |
| `OS_PROJECT_NAME` | | OpenStack project (tenant). DR operations are scoped to this project unless `--all-projects` is given. |
| `OS_PROJECT_DOMAIN_NAME` | `Default` | Domain containing `OS_PROJECT_NAME`. |
| `OS_USER_DOMAIN_NAME` | `Default` | Domain containing `OS_USERNAME`. |
| `OS_REGION_NAME` | | Region name, used when the catalog contains multiple regions. |
| `OS_IDENTITY_API_VERSION` | `3` | Must be `3`; Keystone v2 is not supported. |
| `OS_PROTECTOR_API_VERSION` | `1` | Selects the protector API major version. The maximum supported microversion is `1.1`. |

> **Note:** The `openstackclient` snap is incompatible with the `triliositerecovery` CLI plugin. Install `python-openstackclient` via `pip`, not snap.

## Exit codes

The plugin returns standard OpenStack client exit codes.

| Code | Meaning |
|------|---------|
| `0` | Command completed successfully. |
| `1` | Command failed. The error message printed to stderr contains the HTTP status code and the API error body, including the `type` field (exception class name), `code`, and `message`. |
| `2` | Incorrect command usage — unknown flag, missing required argument, or invalid argument value. The OpenStack client prints usage help. |