CLI reference

CLI Reference

Document exhaustively all the CLIs in python openstack client abaca plugin and their options.

Description

python-abacaclient ships as an OpenStackClient (OSC) plugin that extends the openstack CLI with a share protection command group. Use it to manage every Trilio Share Protection resource — backup targets, protection policies, backups, restores, jobs, workers, coverage, and usage — directly from your terminal or shell scripts. All commands communicate with the Abacá API over HTTP and require a valid Keystone token; no direct database or service-bus access is needed.

Synopsis

openstack share protection <resource> <action> [options] [arguments]

The full command tree is:

openstack share protection target    {enroll|create|list|show|set|delete}
openstack share protection policy    {create|list|show|delete}
openstack share protection backup    {create|list|show|delete}
openstack share protection restore   {create|list|show|delete}
openstack share protection job       {list|show}
openstack share protection usage     show
openstack share protection worker    list
openstack share protection coverage  list

Flags

Every command inherits the standard OpenStackClient global options (such as --os-cloud, --os-auth-url, --os-project-id, --format, and --column). The table below documents only the flags that are specific to python-abacaclient.

`openstack share protection target enroll`

Runs the full enrollment flow: stores S3 credentials in Barbican, creates a Keystone trust, calls POST /v1/targets, and (optionally) waits for the enrollment job to finish. S3 credentials must come from environment variables — never from command-line arguments (they would appear in ps output).

Flag	Required	Default	Description
`<name>` (positional)	Yes	—	Human-readable name for the new backup target.
`--endpoint <endpoint>`	Yes	—	S3 endpoint URL for the object store (e.g. `https://s3.us-east-1.amazonaws.com`).
`--bucket <bucket>`	Yes	—	Name of the S3 bucket that will hold the Kopia repository.
`--region <region>`	No	`us-east-1`	S3 region hint stored on the target.
`--ca-cert <path>`	No	—	Path to a PEM CA certificate file. The file is read and stored as a Barbican secret, then referenced by the target. Use this for S3 endpoints behind a private CA.
`--trust-role <role>`	No	`member`, `creator`	Role to delegate to the Abacá service user via the Keystone trust. Repeatable. Specify once per role.
`--wait`	No	`false`	Poll the enrollment job until it reaches a terminal state (`available` or `error`). Exits non-zero if the job ends in `error`.
`--wait-timeout <seconds>`	No	`120`	Maximum number of seconds to wait when `--wait` is set.
`--poll-interval <seconds>`	No	`2.0`	Seconds between job-status polls when `--wait` is set.

`openstack share protection target create`

Thin HTTP wrapper around POST /v1/targets. Use this when you have already stored credentials in Barbican and created a Keystone trust yourself. For the end-to-end flow, prefer target enroll.

Flag	Required	Default	Description
`<name>` (positional)	Yes	—	Name of the backup target.
`--endpoint <endpoint>`	Yes	—	S3 endpoint URL.
`--bucket <bucket>`	Yes	—	S3 bucket name.
`--region <region>`	No	—	S3 region hint (stored on `target.capabilities.region`).
`--trust-id <trust>`	No	—	Keystone trust ID delegating the roles Abacá needs.
`--barbican-secret-ref <href>`	No	—	Barbican secret href for an S3 credential. Repeatable.
`--barbican-secret-map <key=href>`	No	—	Named Barbican secret ref. Repeatable. Typical keys: `access_key`, `secret_key`.
`--ca-cert-ref <href>`	No	—	Barbican href of a CA certificate bundle for a private S3 endpoint.
`--addressing-mode <mode>`	No	auto-detected	S3 addressing mode: `virtual_hosted` or `path`. When omitted, Abacá auto-detects via preflight checks.

`openstack share protection target list`

Flag	Required	Default	Description
`--limit <limit>`	No	—	Maximum number of targets to return.
`--marker <marker>`	No	—	Pagination marker; returns results after this ID.

`openstack share protection target show`

Argument	Required	Description
`<target>` (positional)	Yes	Target ID to show.

`openstack share protection target set`

Updates a target via PATCH. Only the flags you supply are changed.

Flag	Required	Default	Description
`<target>` (positional)	Yes	—	Target ID to update.
`--name <name>`	No	—	New name.
`--endpoint <endpoint>`	No	—	New S3 endpoint URL.
`--bucket <bucket>`	No	—	New bucket name.
`--region <region>`	No	—	New region hint.
`--trust-id <trust>`	No	—	New Keystone trust ID.
`--barbican-secret-map <key=href>`	No	—	Replace the Barbican secret map. Repeatable.
`--ca-cert-ref <href>`	No	—	New Barbican CA certificate href.
`--addressing-mode <mode>`	No	—	New S3 addressing mode: `virtual_hosted` or `path`.

`openstack share protection target delete`

Argument	Required	Description
`<target> ...` (positional)	Yes	One or more target IDs to delete.

`openstack share protection policy create`

Flag	Required	Default	Description
`<name>` (positional)	Yes	—	Name of the protection policy.
`--share-id <share>`	Yes	—	UUID of the Manila share this policy protects.
`--target-id <target>`	Yes	—	ID of the backup target this policy writes to.
`--schedule <cron>`	Yes	—	Cron expression defining when backups run (e.g. `0 2 * * *`).
`--retention <key=count>`	No	—	Retention rule. Repeatable. Keys: `daily`, `weekly`, `monthly`, `yearly`. Each value is an integer count (e.g. `--retention daily=7 --retention monthly=12`).
`--disabled`	No	`false`	Create the policy in the disabled state (`enabled=false`). The schedule will not fire until the policy is re-enabled.

`openstack share protection policy list`

Flag	Required	Default	Description
`--limit <limit>`	No	—	Maximum number of policies to return.
`--marker <marker>`	No	—	Pagination marker.

`openstack share protection policy show`

Argument	Required	Description
`<policy>` (positional)	Yes	Policy ID to show.

`openstack share protection policy delete`

Refuses to delete a policy that has a backup currently in a non-terminal state. Historical backups retain the policy association in their records (shown as null after deletion).

Argument	Required	Description
`<policy> ...` (positional)	Yes	One or more policy IDs to delete.

`openstack share protection backup create`

Triggers an on-demand backup. Returns the backup record and a job_id you can use to track progress.

Flag	Required	Default	Description
`<share>` (positional)	Yes	—	Manila share ID to back up.
`--target-id <target>`	Yes	—	Backup target to write to.
`--policy-id <policy>`	No	—	Optional policy ID to record on the backup for scheduler audit purposes.

`openstack share protection backup list`

Flag	Required	Default	Description
`--limit <limit>`	No	—	Maximum number of backups to return.
`--marker <marker>`	No	—	Pagination marker.

`openstack share protection backup show`

Argument	Required	Description
`<backup>` (positional)	Yes	Backup ID to show.

`openstack share protection backup delete`

Argument	Required	Description
`<backup> ...` (positional)	Yes	One or more backup IDs to delete.

`openstack share protection restore create`

Triggers a restore from a backup. By default, files are written to a new share. Pass --in-place --force to overwrite the original share.

Flag	Required	Default	Description
`<backup>` (positional)	Yes	—	ID of the backup to restore from.
`--target-share-id <share>`	No	—	For new-share restores: an existing empty share to write into. When omitted, Abacá creates a new share.
`--in-place`	No	`false`	Restore in place, overwriting the original share. Requires `--force`. The API returns HTTP 400 (`category=tenant_action_required`) if `--force` is absent.
`--force`	No	`false`	Required when `--in-place` is set. Confirms the destructive intent.
`--sub-path <sub-path>`	No	—	Repository-relative sub-path to restore. When omitted the entire share tree is restored.

`openstack share protection restore list`

Flag	Required	Default	Description
`--limit <limit>`	No	—	Maximum number of restore records to return.
`--marker <marker>`	No	—	Pagination marker.

`openstack share protection restore show`

Argument	Required	Description
`<restore>` (positional)	Yes	Restore ID to show.

`openstack share protection restore delete`

Deletes the restore history record only. The data already written to the destination share is not affected. Refuses when the restore is still in a non-terminal state.

Argument	Required	Description
`<restore> ...` (positional)	Yes	One or more restore IDs to delete.

`openstack share protection job list`

Flag	Required	Default	Description
`--limit <limit>`	No	—	Maximum number of jobs to return.
`--marker <marker>`	No	—	Pagination marker.

`openstack share protection job show`

Argument	Required	Description
`<job>` (positional)	Yes	Job ID to show.

`openstack share protection usage show`

No resource-specific flags. Shows protected capacity (GB), bytes transferred per job, and restore counts for the current project.

`openstack share protection worker list`

Admin command. Lists all worker VMs known to the control plane.

Flag	Required	Default	Description
`--limit <limit>`	No	—	Maximum number of workers to return.
`--marker <marker>`	No	—	Pagination marker.

`openstack share protection coverage list`

Admin command. Lists protection coverage across all shares — which shares have a policy, how many backups exist, and whether each share is considered protected. No resource-specific flags.

Subcommands

Subcommand	Description
`target enroll`	Full end-to-end enrollment: store S3 credentials in Barbican, create a Keystone trust, register the target, and optionally wait for the enrollment job to complete. Preferred over `target create` for interactive use.
`target create`	Thin HTTP wrapper that registers a target when you have already prepared Barbican secrets and a Keystone trust ID yourself.
`target list`	List all backup targets visible to your project.
`target show`	Show the full detail record for a single backup target.
`target set`	Update mutable fields on an existing backup target (PATCH).
`target delete`	Delete one or more backup targets by ID.
`policy create`	Create a protection policy that binds a Manila share to a backup target and defines a cron schedule and retention rules.
`policy list`	List all protection policies visible to your project.
`policy show`	Show the full detail record for a single protection policy.
`policy delete`	Delete one or more protection policies. Refuses while a policy-triggered backup is in progress.
`backup create`	Trigger an on-demand backup of a Manila share to a backup target. Returns the backup record and a job ID for tracking.
`backup list`	List all backup records visible to your project.
`backup show`	Show the full detail record for a single backup.
`backup delete`	Delete one or more backup records by ID.
`restore create`	Trigger a restore from a backup, either to a new share or in-place onto the original share.
`restore list`	List all restore records visible to your project.
`restore show`	Show the full detail record for a single restore.
`restore delete`	Delete one or more restore history records. Does not undo data already written to the destination share.
`job list`	List all asynchronous jobs (backup, restore, enrollment, maintenance) visible to your project.
`job show`	Show full detail — including state, progress, error, and `error_category` — for a single job.
`usage show`	Show per-project usage meters: protected capacity (GB), bytes transferred, and restore counts.
`worker list`	(Admin) List all worker VMs in the fleet with their state, availability zone, and last heartbeat.
`coverage list`	(Admin) List protection coverage across all shares, showing policy association and backup count per share.

Environment variables

Variable	Default	Description
`ABACA_TARGET_ACCESS_KEY`	—	S3 access key ID used during `target enroll`. Takes precedence over `AWS_ACCESS_KEY_ID`. Required for enrollment; never pass this on the command line.
`ABACA_TARGET_SECRET_KEY`	—	S3 secret access key used during `target enroll`. Takes precedence over `AWS_SECRET_ACCESS_KEY`. Required for enrollment; never pass this on the command line.
`AWS_ACCESS_KEY_ID`	—	Fallback S3 access key ID when `ABACA_TARGET_ACCESS_KEY` is not set.
`AWS_SECRET_ACCESS_KEY`	—	Fallback S3 secret access key when `ABACA_TARGET_SECRET_KEY` is not set.
`OS_CLOUD`	—	Name of the cloud in `clouds.yaml` to authenticate against. Standard OSC variable; sets the Keystone endpoint and credentials used for all `openstack share protection` commands.
`OS_AUTH_URL`	—	Keystone authentication URL. Standard OSC variable; used when `OS_CLOUD` is not set.
`OS_PROJECT_ID`	—	Keystone project scope. The enrollment flow reads the project ID from the authenticated token; this variable sets it for non-interactive use.

Security note: S3 credentials are read exclusively from the environment variables above. They are stored immediately in Barbican during enrollment and are never written to disk, logs, or process arguments by python-abacaclient.

Exit codes

Code	Meaning
`0`	Command completed successfully.
`1`	General error — authentication failure, API error, network error, or an invalid combination of flags (e.g. `--in-place` without `--force`). The error message is printed to stderr.
`1`	Enrollment error — S3 credentials missing from the environment, CA cert file unreadable, Barbican secret storage failed, Keystone trust creation failed, or `POST /v1/targets` returned a non-2xx response.
`1`	Wait timeout — the enrollment job (or any polled job) did not reach a terminal state (`available` or `error`) within the `--wait-timeout` window.
`1`	Job ended in `error` state when `--wait` was used with `target enroll`. Check the job's `error` and `error_category` fields with `openstack share protection job show <job-id>` to determine whether `tenant_action_required` or `operator_action_required`.

Examples

Install the plugin

pip install python-abacaclient

After installation, verify the commands are registered:

openstack share protection --help

Enroll a backup target (recommended end-to-end flow)

Store your S3 credentials in environment variables first — never on the command line:

export ABACA_TARGET_ACCESS_KEY="AKIAIOSFODNN7EXAMPLE"
export ABACA_TARGET_SECRET_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"

Then enroll the target, waiting for the enrollment job to complete:

openstack share protection target enroll my-primary-target \
  --endpoint https://s3.us-east-1.amazonaws.com \
  --bucket acme-share-backups \
  --region us-east-1 \
  --wait \
  --wait-timeout 180

Expected output (field order may vary):

+-------------------+--------------------------------------+
| Field             | Value                                |
+-------------------+--------------------------------------+
| bucket            | acme-share-backups                   |
| endpoint          | https://s3.us-east-1.amazonaws.com   |
| id                | a1b2c3d4-e5f6-7890-abcd-ef1234567890 |
| job_id            | f9e8d7c6-b5a4-3210-fedc-ba9876543210 |
| name              | my-primary-target                    |
| region            | us-east-1                            |
| status            | available                            |
+-------------------+--------------------------------------+

Enroll a target behind a private CA

export ABACA_TARGET_ACCESS_KEY="AKIAIOSFODNN7EXAMPLE"
export ABACA_TARGET_SECRET_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"

openstack share protection target enroll internal-target \
  --endpoint https://rgw.internal.example.com \
  --bucket tenant-backups \
  --region default \
  --ca-cert /etc/pki/ca-trust/source/anchors/internal-ca.pem \
  --wait

The CA certificate is read from disk, stored as a Barbican secret, and referenced on the target so worker VMs can validate the S3 TLS connection.

Register a target manually (when Barbican secrets already exist)

Use this when you have provisioned Barbican secrets and a trust ID through your own tooling:

openstack share protection target create my-target \
  --endpoint https://s3.us-east-1.amazonaws.com \
  --bucket acme-share-backups \
  --trust-id 7f3a1b2c-d4e5-6789-abcd-ef0123456789 \
  --barbican-secret-map access_key=https://barbican.example.com/v1/secrets/aaa \
  --barbican-secret-map secret_key=https://barbican.example.com/v1/secrets/bbb \
  --addressing-mode path

List and inspect targets

openstack share protection target list

+--------------------------------------+-------------------+-------------------------------------------+--------------------+-----------+
| id                                   | name              | endpoint                                  | bucket             | status    |
+--------------------------------------+-------------------+-------------------------------------------+--------------------+-----------+
| a1b2c3d4-e5f6-7890-abcd-ef1234567890 | my-primary-target | https://s3.us-east-1.amazonaws.com        | acme-share-backups | available |
+--------------------------------------+-------------------+-------------------------------------------+--------------------+-----------+

openstack share protection target show a1b2c3d4-e5f6-7890-abcd-ef1234567890

Update a target's name

openstack share protection target set a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  --name production-primary

Create a protection policy

Bind a Manila share to a target with a nightly backup schedule and a 7-daily / 4-weekly / 12-monthly retention:

openstack share protection policy create nightly-policy \
  --share-id d1e2f3a4-b5c6-7890-dcba-fedcba987654 \
  --target-id a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  --schedule "0 2 * * *" \
  --retention daily=7 \
  --retention weekly=4 \
  --retention monthly=12

Expected output:

+------------+--------------------------------------+
| Field      | Value                                |
+------------+--------------------------------------+
| enabled    | True                                 |
| id         | c3d4e5f6-a7b8-9012-cdef-012345678901 |
| name       | nightly-policy                       |
| schedule   | 0 2 * * *                            |
| share_id   | d1e2f3a4-b5c6-7890-dcba-fedcba987654 |
| target_id  | a1b2c3d4-e5f6-7890-abcd-ef1234567890 |
+------------+--------------------------------------+

Create a policy in a disabled state

Useful when you want to define a policy before its schedule should fire:

openstack share protection policy create staging-policy \
  --share-id d1e2f3a4-b5c6-7890-dcba-fedcba987654 \
  --target-id a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  --schedule "0 3 * * 0" \
  --disabled

Trigger an on-demand backup

openstack share protection backup create d1e2f3a4-b5c6-7890-dcba-fedcba987654 \
  --target-id a1b2c3d4-e5f6-7890-abcd-ef1234567890

Expected output:

+------------+--------------------------------------+
| Field      | Value                                |
+------------+--------------------------------------+
| created_at | 2024-06-01T02:00:00Z                 |
| id         | e5f6a7b8-c9d0-1234-efab-234567890123 |
| job_id     | f6a7b8c9-d0e1-2345-fabc-345678901234 |
| share_id   | d1e2f3a4-b5c6-7890-dcba-fedcba987654 |
| status     | creating                             |
| target_id  | a1b2c3d4-e5f6-7890-abcd-ef1234567890 |
+------------+--------------------------------------+

Poll a job until it completes

Use the job_id returned by backup create, restore create, or target enroll:

openstack share protection job show f6a7b8c9-d0e1-2345-fabc-345678901234

Expected output when the backup is transferring data:

+----------------+--------------------------------------+
| Field          | Value                                |
+----------------+--------------------------------------+
| error          | None                                 |
| error_category | None                                 |
| id             | f6a7b8c9-d0e1-2345-fabc-345678901234 |
| job_type       | backup                               |
| progress       | 62                                   |
| resource_id    | e5f6a7b8-c9d0-1234-efab-234567890123 |
| share_id       | d1e2f3a4-b5c6-7890-dcba-fedcba987654 |
| state          | transferring                         |
| target_id      | a1b2c3d4-e5f6-7890-abcd-ef1234567890 |
| worker_id      | b8c9d0e1-f2a3-4567-bcde-456789012345 |
+----------------+--------------------------------------+

If a job fails, check error_category to know who must act: tenant_action_required means you need to fix a configuration (for example, fix your S3 bucket settings); operator_action_required means the infrastructure or Abacá service needs attention.

Restore a backup to a new share

openstack share protection restore create e5f6a7b8-c9d0-1234-efab-234567890123

To restore into an existing empty share you have already created:

openstack share protection restore create e5f6a7b8-c9d0-1234-efab-234567890123 \
  --target-share-id 11223344-5566-7788-9900-aabbccddeeff

Restore a single sub-path from a backup

openstack share protection restore create e5f6a7b8-c9d0-1234-efab-234567890123 \
  --sub-path /reports/2024/q1

Restore in place (destructive — overwrites the original share)

--force is required alongside --in-place to confirm the destructive intent:

openstack share protection restore create e5f6a7b8-c9d0-1234-efab-234567890123 \
  --in-place \
  --force

List all restores and show one

openstack share protection restore list --limit 20

openstack share protection restore show a2b3c4d5-e6f7-8901-bcde-f01234567890

View usage meters for the current project

openstack share protection usage show

Expected output:

+----------------------+----------+
| Field                | Value    |
+----------------------+----------+
| protected_capacity_gb| 512      |
| restore_count        | 3        |
| transferred_bytes    | 10737418 |
+----------------------+----------+

View the worker fleet (admin)

openstack share protection worker list

+--------------------------------------+-----------------+-------+-------------------+--------------------------------------+---------------------+
| id                                   | hostname        | state | availability_zone | current_job_id                       | last_heartbeat_at   |
+--------------------------------------+-----------------+-------+-------------------+--------------------------------------+---------------------+
| b8c9d0e1-f2a3-4567-bcde-456789012345 | abaca-worker-01 | busy  | nova              | f6a7b8c9-d0e1-2345-fabc-345678901234 | 2024-06-01T02:03:10Z|
+--------------------------------------+-----------------+-------+-------------------+--------------------------------------+---------------------+

View protection coverage across all shares (admin)

openstack share protection coverage list

+--------------------------------------+--------------------------------------+-----------+--------------+
| share_id                             | policy_id                            | protected | backup_count |
+--------------------------------------+--------------------------------------+-----------+--------------+
| d1e2f3a4-b5c6-7890-dcba-fedcba987654 | c3d4e5f6-a7b8-9012-cdef-012345678901 | True      | 14           |
| a9b8c7d6-e5f4-3210-edcb-a98765432109 | None                                 | False     | 0            |
+--------------------------------------+--------------------------------------+-----------+--------------+

Delete resources

# Delete a policy (fails if a backup triggered by this policy is still running)
openstack share protection policy delete c3d4e5f6-a7b8-9012-cdef-012345678901

# Delete a backup record
openstack share protection backup delete e5f6a7b8-c9d0-1234-efab-234567890123

# Delete a restore history record (does not undo data written to the share)
openstack share protection restore delete a2b3c4d5-e6f7-8901-bcde-f01234567890

# Delete a backup target
openstack share protection target delete a1b2c3d4-e5f6-7890-abcd-ef1234567890

# Delete multiple targets at once
openstack share protection target delete \
  a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  b2c3d4e5-f6a7-8901-bcde-f01234567890