Architecture and requirements

Ferry uses managers to schedule backups, movers to transfer data and optional compute agents to freeze guests and access local disks. It stores backups in a repository, typically S3-compatible object storage.

Deployment names use ferry: commands, components, images, configuration, metrics, charts, charms, the Keystone user and the database. You can set a product name for the console.

Components

The service has three components. Two are required.

Component	Runs on	Does
Manager (ferry-manager)	Control nodes, two or more replicas	Serves the API and the console, schedules backups, talks to Keystone, Nova, Cinder and Neutron, and owns the database. Replicas are identical and need no leader election.
Mover (ferry-mover)	Hosts with bandwidth to the storage and to the repository, two or more	Reads disks, splits them into chunks, compresses, deduplicates and encrypts them, and writes them to the repository. Movers pull work from the managers, hold no database or OpenStack credential, and scale with bandwidth.
Compute agent (ferry-compute)	Every hypervisor	Freezes a guest's filesystems through the QEMU guest agent for filesystem-consistent backups. Optionally reads and writes disks that live on the hypervisor. Without it, backups are crash-consistent.

The managers keep their state in a MariaDB 10.6+ or MySQL 8.0.16+ database. Backup data lives only in the repository. Every backup in it describes itself, so a fresh installation can read a repository back after the database is lost.

Backup sequence

A scheduled backup of a server on Ceph with filesystem consistency follows this sequence:

The freeze covers only the snapshots, which are metadata operations, so the guest is paused for about a second. The snapshot taken now is kept as the starting point of the next backup's comparison.

Network connections

From	To	Port	Protocol
Users, the dashboard, the CLI	Manager API and console	9776	HTTP behind the cloud's load balancer, Keystone tokens
Mover	Manager	9777	mTLS, internal only
Manager	Compute agent	9779	mTLS, internal only
Mover	Ceph	Ceph's ports	librbd: a read-only cephx user for backups, a separate one for restores
Mover	Repository	the S3 endpoint's port	S3
Manager	Keystone, Nova, Cinder, Neutron, Glance	internal endpoints	OpenStack APIs

Each component also has a loopback-only admin listener for /metrics, /healthz and /readyz: 9775 for the manager, 9782 for the mover and 9780 for the compute agent.

The manager registers itself in the Keystone catalog under the service type backup. The console, the OpenStack dashboard panel and the openstack backup CLI all find the service there.

Requirements

• An OpenStack cloud on libvirt/KVM, 2025.1 or newer for kolla-ansible deployments.
• A database: MariaDB 10.6+ or MySQL 8.0.16+. The manager refuses older versions at start.
• S3-compatible object storage for the repository, with a bucket the service may write to. For immutable backups, a bucket created with Object Lock enabled.
• For Ceph storage: the cluster's ceph.conf, and three cephx users (see the install pages).
• Optionally, Barbican or HashiCorp Vault, to encrypt backups. See Encryption.
• Optionally, a Ceph RADOS Gateway, to protect object storage buckets.

Choose an installation method

Use the deployment method that manages your OpenStack cloud:

Your cloud is deployed with	Use
kolla-ansible	Install with kolla-ansible
OpenStack-Helm, Atmosphere, Genestack, StarlingX, Mirantis MOSK, Yaook, Red Hat OpenStack Services on OpenShift	Install with Helm
Charmed OpenStack, Canonical OpenStack (Sunbeam)	Install with Juju

A deployment backs up nothing until a repository is registered and a policy is written. After installing, register a repository, then write protection policies and offer vaults.

Operator access

Operator tasks require the admin role with a system-scoped Keystone token. Project-scoped roles grant access within that project. See Access control.