CLI reference

OpenStack CLI Plugin

The `openstack <resource> ...` commands this service adds

Description

The openstack share protection command group is the primary CLI interface for Trilio Share Protection for OpenStack (Abacá). It is provided by the python-abacaclient package, which registers itself as a python-openstackclient (OSC) plugin and adds openstack share protection … subcommands to the standard openstack CLI.

Use these commands to manage every aspect of the backup lifecycle: define backup target templates and register S3 buckets, create and manage protection policies, trigger on-demand backups, initiate restores, inspect jobs, and monitor fleet and coverage health. All commands authenticate with Keystone and discover the Abacá API endpoint from the service catalog, following standard OpenStack conventions.

Synopsis

openstack share protection <subcommand> [options] [arguments]

Authentication flags follow the standard openstack client conventions and can be supplied as flags or environment variables (see Environment Variables below):

openstack [--os-auth-url <url>] [--os-project-id <id>] [--os-token <token>] \
  share protection <subcommand> [options]

Flags

These flags apply to every openstack share protection subcommand. Subcommand-specific flags are listed in the Subcommands section and in each command's detailed reference below.

Flag	Short	Default	Description
`--limit <limit>`	—	(all)	Maximum number of results to return. Accepted by all `list` subcommands.
`--marker <marker>`	—	(none)	UUID of the last item from a previous page; use for pagination in `list` subcommands.

`openstack share protection template create`

Flag	Short	Default	Description
`<name>` (positional)	—	(required)	Name of the target template.
`--endpoint <url>`	—	(required)	S3 endpoint URL for this template.
`--bucket-scheme <scheme>`	—	`per_project`	Layout mode: `per_project` (one bucket per OpenStack Project, stronger isolation) or `shared` (one bucket for the whole Domain, enables cross-project deduplication). Immutable after creation.
`--region <region>`	—	(none)	S3 region.
`--provider <provider>`	—	(none)	S3 provider hint, e.g. `wasabi`, `aws-s3`, `minio`.
`--qos-ref <qos>`	—	(none)	Neutron QoS policy ID applied to worker VMs that use this template.

`openstack share protection template list`

Flag	Short	Default	Description
`--limit <limit>`	—	(all)	Maximum number of results.
`--marker <marker>`	—	(none)	Pagination marker.

`openstack share protection template show`

Flag	Short	Default	Description
`<template>` (positional)	—	(required)	Template ID.

`openstack share protection template set`

Note: --bucket-scheme is not available here — the API refuses changes to it after creation.

Flag	Short	Default	Description
`<template>` (positional)	—	(required)	Template ID.
`--name <name>`	—	(unchanged)	New name.
`--region <region>`	—	(unchanged)	New S3 region.
`--provider <provider>`	—	(unchanged)	New provider hint.
`--qos-ref <qos>`	—	(unchanged)	New Neutron QoS policy ID.

`openstack share protection template delete`

Flag	Short	Default	Description
`<template> [<template> …]` (positional)	—	(required)	One or more template IDs to delete. Refuses if any policy or registered bucket still references the template.

`openstack share protection bucket register`

Flag	Short	Default	Description
`<template>` (positional)	—	(required)	Template ID under which to register this bucket.
`--bucket-name <bucket>`	—	(required)	Name of the pre-provisioned S3 bucket.
`--project-id <project>`	—	(none)	Project this bucket serves. Required for `per_project` templates; refused for `shared` templates.
`--s3-access-key-ref <href>`	—	(none)	Barbican href of the S3 access key.
`--s3-secret-key-ref <href>`	—	(none)	Barbican href of the S3 secret key.
`--kopia-key-ref <href>`	—	(none)	Barbican href of the Kopia repository password. Supply when adopting a bucket that already holds a repository.
`--kopia-key-trust-id <trust>`	—	(none)	Keystone trust ID used to redeem the Barbican references.

`openstack share protection bucket list`

Flag	Short	Default	Description
`<template>` (positional)	—	(required)	Template ID whose buckets to list.

`openstack share protection bucket set`

Used to correct or complete credential references on an already-registered bucket. Enrollment starts automatically once all required references are present.

Flag	Short	Default	Description
`<template>` (positional)	—	(required)	Template ID.
`<bucket>` (positional)	—	(required)	Bucket ID.
`--s3-access-key-ref <href>`	—	(none)	Barbican href of the S3 access key.
`--s3-secret-key-ref <href>`	—	(none)	Barbican href of the S3 secret key.
`--kopia-key-ref <href>`	—	(none)	Barbican href of the repository password (only accepted if not already set).
`--kopia-key-trust-id <trust>`	—	(none)	Keystone trust ID used to redeem the references.

`openstack share protection bucket deregister`

Flag	Short	Default	Description
`<template>` (positional)	—	(required)	Template ID.
`<bucket>` (positional)	—	(required)	Bucket ID. Refuses while any backup references the bucket. S3 objects are left untouched.

`openstack share protection policy create`

Flag	Short	Default	Description
`<name>` (positional)	—	(required)	Name of the policy.
`--share-id <share>`	—	(required)	UUID of the Manila share this policy protects.
`--target-template-id <template>`	—	(required)	Target template to write backups to. The physical bucket is resolved per-project at dispatch.
`--schedule <cron>`	—	(required)	Backup schedule as a cron expression, e.g. `'0 2 * * *'`.
`--retention <key=count>`	—	(none)	Repeatable. Retention rule. Valid keys: `keep_latest`, `keep_hourly`, `keep_daily`, `keep_weekly`, `keep_monthly`, `keep_annual`.
`--disabled`	—	`False`	Create the policy in a disabled state (`enabled=False`). Scheduled backups will not run until enabled.

`openstack share protection policy list`

Flag	Short	Default	Description
`--limit <limit>`	—	(all)	Maximum number of results.
`--marker <marker>`	—	(none)	Pagination marker.

`openstack share protection policy show`

Flag	Short	Default	Description
`<policy>` (positional)	—	(required)	Policy ID.

`openstack share protection policy set`

Partial update — only the flags you pass are changed. --share-id and --target-template-id are not available here; the API refuses them because changing either would orphan the policy's existing backups.

Flag	Short	Default	Description
`<policy>` (positional)	—	(required)	Policy ID.
`--name <name>`	—	(unchanged)	New name.
`--schedule <cron>`	—	(unchanged)	New cron schedule.
`--retention <key=count>`	—	(unchanged)	Repeatable. Replaces the entire retention map, not merges. Valid keys: `keep_latest`, `keep_hourly`, `keep_daily`, `keep_weekly`, `keep_monthly`, `keep_annual`.
`--enable`	—	—	Enable the policy (resume scheduled backups). Mutually exclusive with `--disable`.
`--disable`	—	—	Disable the policy (stop scheduled backups; existing backups are kept). Mutually exclusive with `--enable`.

`openstack share protection policy delete`

Flag	Short	Default	Description
`<policy> [<policy> …]` (positional)	—	(required)	One or more policy IDs. Refuses if the policy has an in-flight backup still in `creating` state.

`openstack share protection backup create`

Flag	Short	Default	Description
`<share>` (positional)	—	(required)	Manila share ID to back up.
`--target-template-id <target>`	—	(required)	Backup target template to write to.
`--policy-id <policy>`	—	(none)	Optional policy ID, recorded on the backup for scheduler audit trail.

`openstack share protection backup list`

Flag	Short	Default	Description
`--limit <limit>`	—	(all)	Maximum number of results.
`--marker <marker>`	—	(none)	Pagination marker.

`openstack share protection backup show`

Flag	Short	Default	Description
`<backup>` (positional)	—	(required)	Backup ID.

`openstack share protection backup delete`

Flag	Short	Default	Description
`<backup> [<backup> …]` (positional)	—	(required)	One or more backup IDs to delete.

`openstack share protection restore create`

Flag	Short	Default	Description
`<backup>` (positional)	—	(required)	Backup ID to restore from.
`--target-share-id <share>`	—	(none)	For `new_share` mode: an existing empty share to write the restored data into.
`--in-place`	—	`False`	Restore in place, overwriting the original share. Requires `--force`.
`--force`	—	`False`	Required when `--in-place` is set. Confirms the destructive intent.
`--sub-path <sub-path>`	—	(whole tree)	Repository-relative sub-path to restore instead of the entire backup.

`openstack share protection restore list`

Flag	Short	Default	Description
`--limit <limit>`	—	(all)	Maximum number of results.
`--marker <marker>`	—	(none)	Pagination marker.

`openstack share protection restore show`

Flag	Short	Default	Description
`<restore>` (positional)	—	(required)	Restore ID.

`openstack share protection restore delete`

Flag	Short	Default	Description
`<restore> [<restore> …]` (positional)	—	(required)	One or more restore history record IDs to delete. Refuses if the restore is still `pending`. Deleting the record does not undo the restore against the destination share.

`openstack share protection job list`

Flag	Short	Default	Description
`--limit <limit>`	—	(all)	Maximum number of results.
`--marker <marker>`	—	(none)	Pagination marker.

`openstack share protection job show`

Flag	Short	Default	Description
`<job>` (positional)	—	(required)	Job ID.

`openstack share protection worker list` (admin)

Flag	Short	Default	Description
`--limit <limit>`	—	(all)	Maximum number of results.
`--marker <marker>`	—	(none)	Pagination marker.

`openstack share protection coverage list` (admin)

Flag	Short	Default	Description
(none)	—	—	No additional flags. Returns all shares with their protection coverage status.

`openstack share protection usage show`

Flag	Short	Default	Description
(none)	—	—	No additional flags. Returns usage for the currently scoped project.

Subcommands

The openstack share protection group is organised into resource families. Each row below is a complete subcommand name as you would type it.

Subcommand	Required Role	Description
`template create`	`abaca_domain_owner`	Define a new backup target template for the Domain.
`template list`	any authenticated user	List target templates available in your Domain.
`template show`	any authenticated user	Show details of a target template.
`template set`	`abaca_domain_owner`	Update mutable fields of a target template (`bucket_scheme` cannot be changed).
`template delete`	`abaca_domain_owner`	Delete a target template. Refuses while any policy or bucket references it.
`bucket register`	`abaca_domain_owner`	Register a pre-provisioned S3 bucket under a template and trigger enrollment.
`bucket list`	any authenticated user	List buckets under a template. Projects see only their own; Domain owners see all.
`bucket set`	`abaca_domain_owner`	Correct or complete credential references on a registered bucket.
`bucket deregister`	`abaca_domain_owner`	Deregister a bucket. S3 objects are left intact.
`policy create`	project member	Create a new protection policy binding a share to a template and schedule.
`policy list`	project member	List protection policies in the current project.
`policy show`	project member	Show details of a protection policy.
`policy set`	project member	Update name, schedule, retention, or enabled state of a policy.
`policy delete`	project member	Delete a policy. Refuses if a backup is in-flight.
`backup create`	project member	Trigger an on-demand backup of a Manila share.
`backup list`	project member	List backups in the current project.
`backup show`	project member	Show details of a backup.
`backup delete`	project member	Delete a backup record.
`restore create`	project member	Initiate a restore from a backup (new share, in-place, or sub-path).
`restore list`	project member	List restore operations in the current project.
`restore show`	project member	Show details of a restore operation.
`restore delete`	project member	Delete a restore history record.
`job list`	project member	List backup/restore/enrollment jobs visible to the current project.
`job show`	project member	Show full details and current state of a job.
`worker list`	admin	List worker VMs in the fleet (admin-only view).
`coverage list`	admin	List share protection coverage across the fleet.
`usage show`	project member	Show share-protection usage for the current project.

Environment variables

The openstack share protection commands inherit all standard python-openstackclient environment variables for Keystone authentication and endpoint discovery. The variables below are the ones most relevant to day-to-day use with Abacá.

Variable	Default	Description
`OS_AUTH_URL`	(none)	Keystone endpoint. Required unless passed as `--os-auth-url`.
`OS_PROJECT_ID`	(none)	Project scope for the token. Determines which backups, policies, and buckets you see.
`OS_PROJECT_NAME`	(none)	Alternative to `OS_PROJECT_ID`; resolved with `OS_PROJECT_DOMAIN_NAME`.
`OS_PROJECT_DOMAIN_NAME`	`Default`	Domain that contains `OS_PROJECT_NAME`.
`OS_USERNAME`	(none)	Keystone username.
`OS_PASSWORD`	(none)	Keystone password. Never put this on the command line; use the environment variable or a `clouds.yaml` entry.
`OS_USER_DOMAIN_NAME`	`Default`	Domain that contains `OS_USERNAME`.
`OS_TOKEN`	(none)	Pre-issued Keystone token. Use instead of username/password when you already have a token.
`OS_REGION_NAME`	(none)	Region for endpoint selection from the service catalog.
`OS_CLOUD`	(none)	Named entry in `clouds.yaml` / `secure.yaml`. When set, all other `OS_*` variables are sourced from that entry.
`OS_IDENTITY_API_VERSION`	`3`	Keystone API version. Abacá requires Keystone v3 with domain-scoped token support.
`OS_INTERFACE`	`public`	Endpoint interface (`public`, `internal`, or `admin`) used for service catalog discovery.

Exit codes

Code	Meaning
`0`	Command completed successfully.
`1`	General error: invalid arguments, failed API call, or the API returned an error response. Details are printed to stderr.
`2`	Usage error: unrecognised flag or missing required argument (raised by argparse before any API call is made).

Examples

The examples below progress through the primary workflows: onboarding a Domain, creating a policy, running an on-demand backup, monitoring a job, and restoring.

All examples assume you have sourced a valid clouds.yaml entry or exported OS_* variables.

1. Create a backup target template (Domain owner)

A Domain owner defines where backup data for the Domain will be stored. The bucket_scheme is immutable after creation, so choose carefully: per_project gives each OpenStack project its own encrypted Kopia repository; shared uses one repository for the whole Domain and enables cross-project deduplication.

openstack share protection template create primary-wasabi \
  --endpoint https://s3.wasabisys.com \
  --bucket-scheme per_project \
  --region us-east-1 \
  --provider wasabi

Expected output:

+---------------+--------------------------------------+
| Field         | Value                                |
+---------------+--------------------------------------+
| id            | a1b2c3d4-e5f6-7890-abcd-ef1234567890 |
| name          | primary-wasabi                       |
| endpoint      | https://s3.wasabisys.com             |
| bucket_scheme | per_project                          |
| status        | active                               |
+---------------+--------------------------------------+

2. Register a pre-provisioned S3 bucket

Abacá does not create S3 buckets or credentials — your onboarding process does. Pass Barbican hrefs here; no secret values transit this command.

openstack share protection bucket register a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  --bucket-name acme-project-backup-01 \
  --project-id f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  --s3-access-key-ref https://barbican.example.com/v1/secrets/aaa111 \
  --s3-secret-key-ref https://barbican.example.com/v1/secrets/bbb222 \
  --kopia-key-trust-id e3b0c44298fc1c149afb

Expected output:

+------------+--------------------------------------+
| Field      | Value                                |
+------------+--------------------------------------+
| id         | c9d8e7f6-a5b4-3c2d-1e0f-9a8b7c6d5e4f |
| project_id | f47ac10b-58cc-4372-a567-0e02b2c3d479 |
| bucket_name| acme-project-backup-01               |
| status     | enrolling                            |
+------------+--------------------------------------+

The status will move to available once the conductor completes the enrollment job (preflight checks, Kopia repository initialisation). Track progress with openstack share protection job list.

3. List available templates

openstack share protection template list

Expected output:

+--------------------------------------+----------------+--------------------------+---------------+--------+
| id                                   | name           | endpoint                 | bucket_scheme | status |
+--------------------------------------+----------------+--------------------------+---------------+--------+
| a1b2c3d4-e5f6-7890-abcd-ef1234567890 | primary-wasabi | https://s3.wasabisys.com | per_project   | active |
+--------------------------------------+----------------+--------------------------+---------------+--------+

4. Create a protection policy

Bind a Manila share to a template with a daily backup schedule. The policy is enabled by default; use --disabled to create it paused.

The --retention flag is repeatable and replaces the whole retention map when used with policy set. Valid keys are keep_latest, keep_hourly, keep_daily, keep_weekly, keep_monthly, and keep_annual. Kopia keeps the union of all categories, so to mean "keep exactly 7 daily backups and nothing else", zero out every category you don't want.

openstack share protection policy create nightly-share-backup \
  --share-id 7d6e5f4a-3b2c-1d0e-9f8a-7b6c5d4e3f2a \
  --target-template-id a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  --schedule '0 2 * * *' \
  --retention keep_latest=7 \
  --retention keep_daily=7 \
  --retention keep_monthly=12

Expected output:

+--------------------+--------------------------------------+
| Field              | Value                                |
+--------------------+--------------------------------------+
| id                 | 11223344-5566-7788-99aa-bbccddeeff00 |
| name               | nightly-share-backup                 |
| share_id           | 7d6e5f4a-3b2c-1d0e-9f8a-7b6c5d4e3f2a |
| target_template_id | a1b2c3d4-e5f6-7890-abcd-ef1234567890 |
| schedule           | 0 2 * * *                            |
| enabled            | True                                 |
+--------------------+--------------------------------------+

5. Disable and re-enable a policy

Disabling a policy stops scheduled backups but keeps all existing backup history.

# Disable
openstack share protection policy set 11223344-5566-7788-99aa-bbccddeeff00 \
  --disable

# Re-enable
openstack share protection policy set 11223344-5566-7788-99aa-bbccddeeff00 \
  --enable

6. Trigger an on-demand backup

Backups can be triggered outside the schedule at any time. The response includes both the backup record and the job_id to track progress.

openstack share protection backup create 7d6e5f4a-3b2c-1d0e-9f8a-7b6c5d4e3f2a \
  --target-template-id a1b2c3d4-e5f6-7890-abcd-ef1234567890

Expected output:

+------------------+--------------------------------------+
| Field            | Value                                |
+------------------+--------------------------------------+
| id               | 55667788-99aa-bbcc-ddee-ff0011223344 |
| share_id         | 7d6e5f4a-3b2c-1d0e-9f8a-7b6c5d4e3f2a |
| target_bucket_id | c9d8e7f6-a5b4-3c2d-1e0f-9a8b7c6d5e4f |
| status           | creating                             |
| created_at       | 2025-06-01T02:00:00Z                 |
| job_id           | aa112233-4455-6677-8899-aabbccddeeff |
+------------------+--------------------------------------+

7. Monitor a job

Jobs walk through the state machine: queued → provisioning_network → provisioning_source → connecting_repository → transferring → finalizing → releasing → available (or error).

openstack share protection job show aa112233-4455-6677-8899-aabbccddeeff

Expected output (in-progress):

+----------------+--------------------------------------+
| Field          | Value                                |
+----------------+--------------------------------------+
| id             | aa112233-4455-6677-8899-aabbccddeeff |
| job_type       | backup                               |
| state          | transferring                         |
| progress       | 42                                   |
| resource_id    | 55667788-99aa-bbcc-ddee-ff0011223344 |
| share_id       | 7d6e5f4a-3b2c-1d0e-9f8a-7b6c5d4e3f2a |
| target_bucket_id | c9d8e7f6-a5b4-3c2d-1e0f-9a8b7c6d5e4f |
| worker_id      | wk-deadbeef-cafe-1234-5678-abcdef012345 |
| executed_by    | abaca                                |
| error          | None                                 |
| error_category | None                                 |
| started_at     | 2025-06-01T02:00:05Z                 |
| ended_at       | None                                 |
| created_at     | 2025-06-01T02:00:01Z                 |
+----------------+--------------------------------------+

If error_category is tenant_action_required, you must act (for example, invalid S3 credentials). If it is operator_action_required, escalate to the operator (for example, no worker VMs available).

8. List all jobs

openstack share protection job list --limit 20

Expected output:

+--------------------------------------+----------+-----------+----------+--------------------------------------+--------------------------------------+
| id                                   | job_type | state     | progress | resource_id                          | worker_id                            |
+--------------------------------------+----------+-----------+----------+--------------------------------------+--------------------------------------+
| aa112233-4455-6677-8899-aabbccddeeff | backup   | available | 100      | 55667788-99aa-bbcc-ddee-ff0011223344 | wk-deadbeef-cafe-1234-5678-abcdef012345 |
+--------------------------------------+----------+-----------+----------+--------------------------------------+--------------------------------------+

9. Restore a whole share to a new share

By default, restore create creates a new share from the backup. You can optionally pin the destination to an existing empty share with --target-share-id.

openstack share protection restore create 55667788-99aa-bbcc-ddee-ff0011223344

Expected output:

+-----------+--------------------------------------+
| Field     | Value                                |
+-----------+--------------------------------------+
| id        | ffeeddcc-bbaa-9988-7766-554433221100 |
| backup_id | 55667788-99aa-bbcc-ddee-ff0011223344 |
| mode      | new_share                            |
| status    | pending                              |
| created_at| 2025-06-01T03:00:00Z                 |
| job_id    | 99887766-5544-3322-1100-ffeeddccbbaa |
+-----------+--------------------------------------+

10. Restore a single sub-path from a backup

Restore only a specific directory from the backup tree without overwriting the rest of the share.

openstack share protection restore create 55667788-99aa-bbcc-ddee-ff0011223344 \
  --sub-path projects/finance/q1-reports

11. Restore in place (destructive — requires --force)

In-place restore overwrites the original share. The --force flag is required to confirm the destructive intent.

openstack share protection restore create 55667788-99aa-bbcc-ddee-ff0011223344 \
  --in-place \
  --force

12. Check fleet health and coverage (admin)

# List worker VMs
openstack share protection worker list

Expected output:

+--------------------------------------+---------------------+-------+-------------------+--------------------------------------+---------------------+
| id                                   | hostname            | state | availability_zone | current_job_id                       | last_heartbeat_at   |
+--------------------------------------+---------------------+-------+-------------------+--------------------------------------+---------------------+
| wk-deadbeef-cafe-1234-5678-abcdef012 | abaca-worker-node-1 | ready | nova              | None                                 | 2025-06-01T03:05:00Z|
+--------------------------------------+---------------------+-------+-------------------+--------------------------------------+---------------------+

# List share protection coverage
openstack share protection coverage list

Expected output:

+--------------------------------------+--------------------------------------+-----------+--------------+
| share_id                             | policy_id                            | protected | backup_count |
+--------------------------------------+--------------------------------------+-----------+--------------+
| 7d6e5f4a-3b2c-1d0e-9f8a-7b6c5d4e3f2a | 11223344-5566-7788-99aa-bbccddeeff00 | True      | 3            |
+--------------------------------------+--------------------------------------+-----------+--------------+

13. Show project usage

openstack share protection usage show

Expected output:

+-------------------+-------+
| Field             | Value |
+-------------------+-------+
| backup_count      | 3     |
| protected_shares  | 1     |
+-------------------+-------+

OpenStack CLI Plugin

openstack share protection template create

openstack share protection template list

openstack share protection template show

openstack share protection template set

openstack share protection template delete

openstack share protection bucket register

openstack share protection bucket list

openstack share protection bucket set

openstack share protection bucket deregister

openstack share protection policy create

openstack share protection policy list

openstack share protection policy show

openstack share protection policy set

openstack share protection policy delete

openstack share protection backup create

openstack share protection backup list

openstack share protection backup show

openstack share protection backup delete

openstack share protection restore create

openstack share protection restore list

openstack share protection restore show

openstack share protection restore delete

openstack share protection job list

openstack share protection job show

openstack share protection worker list (admin)

openstack share protection coverage list (admin)

openstack share protection usage show

1. Create a backup target template (Domain owner)

2. Register a pre-provisioned S3 bucket

3. List available templates

4. Create a protection policy

5. Disable and re-enable a policy

6. Trigger an on-demand backup

7. Monitor a job

8. List all jobs

9. Restore a whole share to a new share

10. Restore a single sub-path from a backup

11. Restore in place (destructive — requires --force)

12. Check fleet health and coverage (admin)

13. Show project usage

`openstack share protection template create`

`openstack share protection template list`

`openstack share protection template show`

`openstack share protection template set`

`openstack share protection template delete`

`openstack share protection bucket register`

`openstack share protection bucket list`

`openstack share protection bucket set`

`openstack share protection bucket deregister`

`openstack share protection policy create`

`openstack share protection policy list`

`openstack share protection policy show`

`openstack share protection policy set`

`openstack share protection policy delete`

`openstack share protection backup create`

`openstack share protection backup list`

`openstack share protection backup show`

`openstack share protection backup delete`

`openstack share protection restore create`

`openstack share protection restore list`

`openstack share protection restore show`

`openstack share protection restore delete`

`openstack share protection job list`

`openstack share protection job show`

`openstack share protection worker list` (admin)

`openstack share protection coverage list` (admin)

`openstack share protection usage show`