--- title: CLI Reference product: trilio-share-protection doc_type: cli_reference version: master source: git2docs (code-derived, validation-filtered) canonical: https://git2docs.com/murali-balcha/docs/trilio-share-protection/trilio-share-protection-/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 [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 | |---|---|---|---| | `` (positional) | Yes | — | Human-readable name for the new backup target. | | `--endpoint ` | Yes | — | S3 endpoint URL for the object store (e.g. `https://s3.us-east-1.amazonaws.com`). | | `--bucket ` | Yes | — | Name of the S3 bucket that will hold the Kopia repository. | | `--region ` | No | `us-east-1` | S3 region hint stored on the target. | | `--ca-cert ` | 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 ` | 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 ` | No | `120` | Maximum number of seconds to wait when `--wait` is set. | | `--poll-interval ` | 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 | |---|---|---|---| | `` (positional) | Yes | — | Name of the backup target. | | `--endpoint ` | Yes | — | S3 endpoint URL. | | `--bucket ` | Yes | — | S3 bucket name. | | `--region ` | No | — | S3 region hint (stored on `target.capabilities.region`). | | `--trust-id ` | No | — | Keystone trust ID delegating the roles Abacá needs. | | `--barbican-secret-ref ` | No | — | Barbican secret href for an S3 credential. Repeatable. | | `--barbican-secret-map ` | No | — | Named Barbican secret ref. Repeatable. Typical keys: `access_key`, `secret_key`. | | `--ca-cert-ref ` | No | — | Barbican href of a CA certificate bundle for a private S3 endpoint. | | `--addressing-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 ` | No | — | Maximum number of targets to return. | | `--marker ` | No | — | Pagination marker; returns results after this ID. | --- ### `openstack share protection target show` | Argument | Required | Description | |---|---|---| | `` (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 | |---|---|---|---| | `` (positional) | Yes | — | Target ID to update. | | `--name ` | No | — | New name. | | `--endpoint ` | No | — | New S3 endpoint URL. | | `--bucket ` | No | — | New bucket name. | | `--region ` | No | — | New region hint. | | `--trust-id ` | No | — | New Keystone trust ID. | | `--barbican-secret-map ` | No | — | Replace the Barbican secret map. Repeatable. | | `--ca-cert-ref ` | No | — | New Barbican CA certificate href. | | `--addressing-mode ` | No | — | New S3 addressing mode: `virtual_hosted` or `path`. | --- ### `openstack share protection target delete` | Argument | Required | Description | |---|---|---| | ` ...` (positional) | Yes | One or more target IDs to delete. | --- ### `openstack share protection policy create` | Flag | Required | Default | Description | |---|---|---|---| | `` (positional) | Yes | — | Name of the protection policy. | | `--share-id ` | Yes | — | UUID of the Manila share this policy protects. | | `--target-id ` | Yes | — | ID of the backup target this policy writes to. | | `--schedule ` | Yes | — | Cron expression defining when backups run (e.g. `0 2 * * *`). | | `--retention ` | 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 ` | No | — | Maximum number of policies to return. | | `--marker ` | No | — | Pagination marker. | --- ### `openstack share protection policy show` | Argument | Required | Description | |---|---|---| | `` (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 | |---|---|---| | ` ...` (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 | |---|---|---|---| | `` (positional) | Yes | — | Manila share ID to back up. | | `--target-id ` | Yes | — | Backup target to write to. | | `--policy-id ` | No | — | Optional policy ID to record on the backup for scheduler audit purposes. | --- ### `openstack share protection backup list` | Flag | Required | Default | Description | |---|---|---|---| | `--limit ` | No | — | Maximum number of backups to return. | | `--marker ` | No | — | Pagination marker. | --- ### `openstack share protection backup show` | Argument | Required | Description | |---|---|---| | `` (positional) | Yes | Backup ID to show. | --- ### `openstack share protection backup delete` | Argument | Required | Description | |---|---|---| | ` ...` (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 | |---|---|---|---| | `` (positional) | Yes | — | ID of the backup to restore from. | | `--target-share-id ` | 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 ` | 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 ` | No | — | Maximum number of restore records to return. | | `--marker ` | No | — | Pagination marker. | --- ### `openstack share protection restore show` | Argument | Required | Description | |---|---|---| | `` (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 | |---|---|---| | ` ...` (positional) | Yes | One or more restore IDs to delete. | --- ### `openstack share protection job list` | Flag | Required | Default | Description | |---|---|---|---| | `--limit ` | No | — | Maximum number of jobs to return. | | `--marker ` | No | — | Pagination marker. | --- ### `openstack share protection job show` | Argument | Required | Description | |---|---|---| | `` (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 ` | No | — | Maximum number of workers to return. | | `--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 ` to determine whether `tenant_action_required` or `operator_action_required`. | ## Examples ### Install the plugin ```console pip install python-abacaclient ``` After installation, verify the commands are registered: ```console 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: ```console 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: ```console 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 ```console 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: ```console 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 ```console 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 | +--------------------------------------+-------------------+-------------------------------------------+--------------------+-----------+ ``` ```console openstack share protection target show a1b2c3d4-e5f6-7890-abcd-ef1234567890 ``` --- ### Update a target's name ```console 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: ```console 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: ```console 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 ```console 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`: ```console 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 ```console openstack share protection restore create e5f6a7b8-c9d0-1234-efab-234567890123 ``` To restore into an existing empty share you have already created: ```console 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 ```console 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: ```console openstack share protection restore create e5f6a7b8-c9d0-1234-efab-234567890123 \ --in-place \ --force ``` --- ### List all restores and show one ```console openstack share protection restore list --limit 20 ``` ```console openstack share protection restore show a2b3c4d5-e6f7-8901-bcde-f01234567890 ``` --- ### View usage meters for the current project ```console openstack share protection usage show ``` Expected output: ``` +----------------------+----------+ | Field | Value | +----------------------+----------+ | protected_capacity_gb| 512 | | restore_count | 3 | | transferred_bytes | 10737418 | +----------------------+----------+ ``` --- ### View the worker fleet (admin) ```console 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) ```console 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 ```console # 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 ```