Key Concepts

This page defines the core resources, services, and OpenStack concepts you need to understand before deploying, operating, or integrating with Trilio Share Protection for OpenStack (Abacá). Each term appears throughout the API, CLI, and configuration surface — knowing what these things are and how they relate to each other will help you make the right decisions about bucket layout, policy design, encryption, and fleet sizing.

BackupTarget

A BackupTarget (also: target, backup target) is a registered S3 bucket that Abacá uses to store encrypted backup data for a Domain. Targets are owned at the Domain level — not by an individual project — and contain exactly one Kopia repository. Before a bucket becomes a usable target, Abacá runs a preflight conformance check (see below) and initializes the Kopia repository inside it. The bucket's name follows the convention abaca-<domain_slug>-<target_slug>-<random> and lives in the per-Domain service project. Because every repository is client-side-encrypted with a tenant-owned key, the operator who owns the bucket cannot read the data inside it.

BackupTargetTemplate

A BackupTargetTemplate (also: target template, template) is a Domain-level configuration object created by a Domain owner that describes the S3 endpoint, region, provider, and bucket scheme (shared or per_project). Individual S3 buckets are registered as BackupTargets against a template. The template is the anchor for layout decisions: which bucket_scheme you choose here determines whether all projects in a Domain share one repository or each get their own.

bucket_scheme

The bucket_scheme is the layout mode declared on a BackupTargetTemplate. It controls how S3 buckets and Kopia repositories are allocated across projects in a Domain:

• shared — one S3 bucket and one Kopia repository for all projects in the Domain. This enables cross-project deduplication: identical data stored by different projects is written to S3 only once. The trade-off is that the Object Lock retention period on the shared repository must be set to the maximum across every policy using it, which may hold locked storage longer than some policies require.
• per_project — a separate bucket and repository for each project. This provides stronger isolation and lets each project's repository have an independent Object Lock period, which is useful when projects have very different retention requirements.

You cannot change a template's bucket_scheme after targets have been enrolled against it.

Policy

A Policy (also: protection policy, backup policy) is a per-share configuration that binds a Manila share to a BackupTargetTemplate, defines the backup schedule as a cron expression, and sets retention rules for how long backups are kept. When a policy is active, the conductor schedules backup jobs automatically according to the cron expression. Retention rules determine how long backup snapshots are kept in the Kopia repository and, by extension, how long their underlying content blobs must be held under Object Lock.

Job

A Job (also: backup job, restore job) is the internal record of a single unit of work — a backup, restore, target enrollment, or maintenance run. Every job has an associated error category (tenant_action_required or operator_action_required) on failure, so you know immediately who must act to resolve it. Jobs are tracked in the Abacá database, but the backup data they produce lives in the Kopia repository in S3, which is the durable source of truth.

Job state machine

Every job passes through a defined sequence of lifecycle states:

queued → provisioning_network → provisioning_source → connecting_repository
       → transferring → finalizing → releasing → available
                                                         ↘ error

Each stage can fail independently and triggers idempotent cleanup before transitioning to error. The conductor's reconciliation loop ensures no job stays in a non-terminal state indefinitely — it detects stuck jobs and either recovers or marks them as failed with an appropriate error category.

tenant_action_required / operator_action_required

When a job fails, Abacá sets an error category on the job record to indicate who must act:

• tenant_action_required — the failure is caused by something the tenant controls, such as invalid or expired S3 credentials, a misconfigured bucket, or a revoked Keystone trust.
• operator_action_required — the failure is caused by something only an operator can fix, such as no available worker fleet, a network routing problem, or a service configuration error.

This distinction appears in API error responses and in the Horizon admin panel, and it is the primary signal for triage.

Worker VM

A Worker VM (also: worker, abaca-worker) is a stateless virtual machine booted by Abacá in the Domain's per-Domain service project. Workers mount Manila shares, invoke Kopia to transfer data to and from S3, and register with the conductor over outbound HTTPS. They operate entirely within the tenant's network scope and hold secrets (S3 credentials, Kopia repository password) only in memory for the duration of a job — secrets are never written to disk and never appear in process arguments.

Workers are booted from the Worker VM image — a pre-baked RHEL image containing Kopia, NFS utilities, and the abaca-worker-agent — which must be uploaded to Glance with the abaca_worker_image=1 property. Worker VMs must not fetch packages from the internet at boot.

capacity_slots

capacity_slots is the number of concurrent jobs a single worker VM can run simultaneously. The conductor's fleet picker only assigns a new job to a worker whose count of running jobs is strictly below this limit. Setting this value appropriately for your flavor size prevents a single worker from being overwhelmed while keeping the fleet efficient. Configure it with the [worker] capacity_slots option in the worker agent's configuration.

Kopia repository

The Kopia repository (also: repository, repo) is the encrypted, deduplicated, content-addressed data store inside an S3 bucket where all backup data for a target lives. The repository is the source of truth for backup data; the Abacá database holds only pointers and metadata (snapshot manifest IDs). If the Abacá database is lost, the repository can be used to rebuild the catalog via the abaca-manage rebuild-from-repository disaster-recovery operation.

Kopia stores data as content-addressed blobs (~4 MB chunks packed into ~20 MB encrypted packs). Identical content across a tenant's shares is stored once; unchanged content across successive backups adds nothing. Every Kopia snapshot is a "full" from the perspective of a restore — there is no incremental chain to walk, because deduplication happens at the content level.

FIPS profile

The FIPS profile (also: FIPS crypto profile, FIPS mode) is a Kopia repository configuration that restricts all cryptographic operations to FIPS-approved algorithms:

• Encryption: AES256-GCM-HMAC-SHA256
• Block hash: HMAC-SHA256-128 (overriding Kopia's non-approved BLAKE2 default)
• Key derivation: PBKDF2 (if the pinned Kopia binary supports it; otherwise scrypt with a prominent warning)

The FIPS profile is applied at repository creation time and is immutable afterward — you cannot change the cryptographic profile of an existing repository. By default, [kopia] require_fips_profile = true; attempting to connect to a repository that was not created with the FIPS profile will fail when this option is set.

Enrollment

Enrollment (also: target enrollment, bucket enrollment, enroll) is the process of registering an S3 bucket as a usable backup target. Abacá runs a preflight conformance check, generates an encryption key stored in Barbican, and initializes a Kopia repository inside the bucket. Enrollment runs as a Job on a worker VM, so a worker must be available before enrollment can proceed. The [enrollment] dispatch configuration option controls whether enrollment is dispatched via RPC (rpc) or run inline (inline).

Preflight conformance check

The preflight conformance check (also: preflight, conformance check, bucket validation) is a set of automated checks Abacá runs before accepting an S3 bucket as a backup target. These checks verify:

• The bucket is reachable and the provided credentials have read/write access
• Versioning is enabled
• Object Lock is configured (if required by the template)
• No lifecycle rules exist that would delete live data before the retention window expires

If any check fails, enrollment is rejected with a tenant_action_required error, because the tenant controls the bucket configuration.

Object Lock

Object Lock (also: WORM, immutability, S3 Object Lock) is an S3 feature that makes backup objects immutable (write-once-read-many) for a defined retention period. When Object Lock is active, backup blobs cannot be deleted — even by a compromised tenant credential — until the lock period expires. Object Lock must be enabled at bucket creation time; it cannot be added to an existing bucket.

Because Kopia's content-addressed blobs are shared across snapshots and across sources within a repository, Abacá sets the Object Lock period at the repository level — specifically, the maximum retention period across every policy using that repository. This means a blob touched by any snapshot is held for as long as the longest-retaining policy, even if other policies have shorter retention. The practical implication: policies with very different retention requirements belong on different templates (and, under per_project, different buckets) so their Object Lock periods can be set independently.

Network attachment strategy

The network attachment strategy (also: network strategy, AttachToShareNetwork, StaticReachability) is the method Abacá uses to connect a worker VM to the network where a Manila share's export lives. The strategy is resolved per share at job time from share attributes:

• attach-to-share-network — used when the share has a share_network_id (DHSS=true backends). The conductor creates a Neutron port on the tenant share network, hot-plugs it into the worker, sets an access-allow rule for the worker's IP, mounts the share, and unwinds the attachment in reverse when the job completes.
• static-reachability — used for DHSS=false backends, where exports live on a provider or storage network that the worker fleet can reach permanently via an operator-maintained routing configuration. Per-job work is limited to toggling the access rule.

Snapshot access strategy

The snapshot access strategy (also: snapshot strategy, SnapDir, MountableSnapshot, CloneFromSnapshot, LiveBackup) is the method Abacá uses to obtain a point-in-time, read-only view of a share for backup. The strategy is selected automatically from share-type capabilities and runtime probes:

All snapshot-based strategies produce point-in-time backups. The live strategy produces a crash-consistent backup only.

Crash-consistent backup

A crash-consistent backup (also: crash consistency, crash-consistent) is a backup that reflects the on-disk state as if the system had lost power at that instant. Filesystem structures are recoverable, but application writes that were not yet flushed to the share at the moment of the snapshot may be missing — equivalent to the state you would find after an unexpected reboot. Applications requiring stronger guarantees should quiesce before the backup window. The crash-consistent guarantee applies specifically to the live snapshot strategy; all snapshot-based strategies (SnapDir, MountableSnapshot, CloneFromSnapshot) produce point-in-time backups.

Rebuild from repository

Rebuild from repository (also: rebuild-from-repository, DR rebuild) is a disaster-recovery operation that reconstructs the Abacá database catalog by reading the Kopia repositories in S3. You use this operation when the Abacá database has been lost but the backup data in S3 is intact. The operation is exposed via the abaca-manage rebuild-from-repository command. Because the Kopia repository is the source of truth for backup data, a complete catalog can be reconstructed from it without any prior database content.

Reconciliation loop

The reconciliation loop (also: reconciliation, reconciliation sweep) is a background process inside the conductor that periodically sweeps for orphaned queued jobs, dead workers, expired backups, and overdue repository maintenance. It ensures no job stays in a non-terminal state indefinitely. The sweep interval is controlled by [conductor] reconciliation_interval (default: 300 seconds). The reconciliation loop also logs warnings when a single outlier policy dominates a repository's Object Lock period — making the situation visible before it appears on a storage invoice.

Conductor

The Conductor (also: abaca-conductor) is the Abacá service component that drives the job state machine, schedules backups from policy cron expressions, manages the worker VM fleet lifecycle, and runs the reconciliation loop. It communicates with worker VMs over HTTPS and dispatches work to them via the RabbitMQ message broker. The conductor does not store secrets — it passes Barbican hrefs and Keystone trust IDs over the message bus, and the worker retrieves actual secret values from Barbican using those references.

Domain owner

The Domain owner (also: abaca_domain_owner, domain admin) is a user holding the abaca_domain_owner Keystone role in a specific Domain. Domain owners are authorized to create and manage BackupTargetTemplates and register S3 buckets as BackupTargets on behalf of all projects in that Domain. This role is scoped to a Domain, not a project, which is why target management is a Domain-level operation rather than a per-project one.

domain_service_projects

domain_service_projects (also: service project, per-Domain service project) is the registry table that maps each Keystone Domain to the dedicated OpenStack service project where that Domain's worker VMs, S3 bucket resources, and Barbican secrets physically reside. Worker VMs are booted in this project, not in the tenant's own project, which isolates the data plane from tenant-managed resources while keeping worker network attachments within tenant network scope.

Barbican

Barbican (also: OpenStack Barbican, key manager) is the OpenStack key management service where Abacá stores S3 credentials and Kopia repository passwords as secret references (hrefs). Abacá never stores the actual secret values in its own database — only the Barbican hrefs. For shared-scheme targets, secrets are stored in the Domain owner's <domain>-abaca-keys project; for per_project-scheme targets, they are stored in the tenant project's own Barbican. Secrets travel to worker VMs exclusively via environment variables — never via process arguments, disk, or log output.

Trust (Keystone trust)

A Trust (also: trust_id, Keystone trust, delegation) is a Keystone delegation that allows Abacá's service user to act on behalf of a tenant for specific operations — primarily reading Barbican secrets and managing Manila access rules — without requiring the tenant's password. The tenant grants the trust at policy creation time and can revoke it at any time, which immediately prevents Abacá from performing further delegated operations on that tenant's behalf.

Kopia

Kopia is the open-source backup engine that runs inside worker VMs. It creates encrypted, deduplicated, content-addressed snapshots of Manila share data and stores them in S3 repositories. Kopia's content-addressable storage means that unchanged data across successive backups of the same share — or identical data across multiple shares in a shared-scheme repository — is stored only once. Kopia is version-pinned and must be a FIPS-built binary; the default expected binary name is configured via [kopia] binary (default: kopia). Kopia is never invoked with secrets in its argument list; the repository password arrives via the KOPIA_PASSWORD environment variable.

The following examples show how key concepts surface in practice through the CLI and API. These are representative of the shapes involved — substitute your own IDs and credentials.

Inspecting a job and its error category

After requesting an on-demand backup, check the job's state and error category:

openstack share protection job show 3a7b1c2d-4e5f-6789-abcd-ef0123456789

Expected output (job in error state):

+------------------+------------------------------------------+
| Field            | Value                                    |
+------------------+------------------------------------------+
| id               | 3a7b1c2d-4e5f-6789-abcd-ef0123456789    |
| state            | error                                    |
| error_category   | tenant_action_required                   |
| error_message    | S3 credentials rejected by endpoint     |
| created_at       | 2025-03-14T09:26:53Z                     |
+------------------+------------------------------------------+

An error_category of tenant_action_required tells you the problem lies with the S3 credentials or bucket configuration — not with the Abacá service itself.

Listing backup targets for a Domain

openstack share protection target list

Expected output:

+--------------------------------------+-------------------+-----------+
| id                                   | name              | state     |
+--------------------------------------+-------------------+-----------+
| b9c4d7e2-1f3a-4b8c-9d0e-2f4a6b8c0e2f | prod-us-east      | available |
| 7e2b5a8c-3d1f-4e9a-8b2c-5d7f9a1c3e5f | dev-shared        | enrolling |
+--------------------------------------+-------------------+-----------+

Checking the job state machine for a restore

Polling a restore job while it is in progress:

openstack share protection job show d1e2f3a4-b5c6-7890-abcd-1234567890ab

Expected output (job mid-flight):

+------------------+------------------------------------------+
| Field            | Value                                    |
+------------------+------------------------------------------+
| id               | d1e2f3a4-b5c6-7890-abcd-1234567890ab    |
| type             | restore                                  |
| state            | transferring                             |
| error_category   | None                                     |
| created_at       | 2025-03-14T10:14:00Z                     |
+------------------+------------------------------------------+

The transferring state means the worker VM has mounted the target share and Kopia is actively streaming data from the S3 repository. The job will proceed to finalizing → releasing → available on success.

Viewing a policy's schedule and retention

openstack share protection policy show f7a2b3c4-d5e6-7890-fedc-ba9876543210

Expected output:

+---------------------+------------------------------------------+
| Field               | Value                                    |
+---------------------+------------------------------------------+
| id                  | f7a2b3c4-d5e6-7890-fedc-ba9876543210    |
| share_id            | 9a1b2c3d-4e5f-6789-abcd-ef0123456789    |
| target_template_id  | b9c4d7e2-1f3a-4b8c-9d0e-2f4a6b8c0e2f  |
| schedule            | 0 2 * * *                                |
| keep_last           | 30                                       |
| keep_weekly         | 12                                       |
| keep_monthly        | 12                                       |
| keep_annual         | 0                                        |
+---------------------+------------------------------------------+

The schedule field is a standard cron expression (here: daily at 02:00 UTC). Retention fields map directly to Kopia snapshot retention policy parameters on the repository source for this share.

• Deploy the control plane — how abaca-api and abaca-conductor are deployed as OpenShift pods and registered with Keystone, including service catalog setup and role assignment.
• Build and register the worker image — how the Worker VM image is built with virt-customize / guestfish, what the abaca_worker_image=1 Glance property means, and why worker VMs must not fetch packages at boot.
• Register a Domain and provision backup targets — step-by-step guide to assigning the abaca_domain_owner role, creating a BackupTargetTemplate, and enrolling an S3 bucket as a BackupTarget, including preflight conformance check requirements.
• Create a protection policy — how to bind a Manila share to a target template, set a cron schedule, and configure retention, including how the bucket_scheme choice affects Object Lock period calculation.
• Monitor backup coverage and fleet health — how the reconciliation loop surfaces overdue maintenance, how error_category guides triage, and how to interpret worker capacity_slots in the fleet status panel.
• Restore the control plane from database loss — detailed procedure for using abaca-manage rebuild-from-repository when the Abacá database is lost but S3 repositories are intact.
• Diagnose a degraded or stuck job — how to read the job state machine, interpret tenant_action_required vs operator_action_required, and identify stuck jobs via the reconciliation sweep logs.
• Data fidelity guarantees — what Abacá preserves on restore (file contents, mtimes, sparse files, POSIX permission bits) and current known gaps (numeric UID/GID, setuid/setgid bits), plus what is out of scope for phase 1 (POSIX ACLs, extended attributes).