Cluster-to-cluster backup
Problem and purpose
A disk snapshot resides in the same pool as the virtual machine itself. This copy protects against an error inside the VM, but not against the loss of the pool or its owner node: the original and the copy are lost together. For a copy to survive a storage layer failure, it must be moved to another cluster.
The cluster-to-cluster backup subsystem handles this. One cluster sends the VM's data stream; the other receives it and stores its history. Both ends are regular vStack Center clusters; the setup has no dedicated backup server.
vStack Center provides a set of primitives for this, rather than a complete backup product. A cluster can create a chain, open a stream receiver, send a historical restore point, and remove what is no longer needed. The caller — GI, the cluster federation — maintains the schedule, backup catalog, and retention policy. The cluster itself does not schedule anything or track backup history.
Model and entities
A backup chain is a service dataset on the backup storage cluster. Its full
name consists of the pool, a service prefix, and a leaf name:
<pool>/.backup/<leaf>. The caller chooses the leaf name, and the cluster
validates its characters: 1 to 128 characters, consisting of Latin letters,
digits, and the symbols _, ., -. Spaces, Cyrillic characters, slashes, and
@ are rejected with code -25430. The cluster does not interpret the name's
meaning. A chain is not a VM: it does not belong to any VDC (virtual data center)
and does not appear in VM lists.
A restore point is a snapshot within a chain. It is addressed by its short
name, the suffix after @, rather than its full path. A chain holds as many
points as are added to it: the cluster neither limits their number nor removes
old ones automatically.
The cluster selects the pool for the chain itself, without involving the caller. It considers consuming pools whose owner nodes are up and selects the one with the most free space. A backup size estimate, if provided at creation, acts as a prefilter. The cluster adds a 20 % margin to the estimate for chain growth and excludes pools with less free space than that total. The filter is enabled when the estimate is greater than zero.
| Entity | Addressed by | Who sets the name |
|---|---|---|
| Chain | full path <pool>/.backup/<leaf> | the caller sets the leaf name; the cluster selects the pool |
| Restore point | short snapshot name (the suffix after @) | the party that wrote the stream |
The chain path is the only safeguard against unintended access to the storage
layer: only paths of the form <pool>/.backup/<leaf> are relayed to nodes. The
cluster rejects any other path with error -25430 before the request reaches
the node. Attempting to address a VM dataset through chain operations therefore
fails by design.
Cluster roles
Up to three clusters participate in one procedure, and one cluster can serve several roles at once.
| Role | What it does |
|---|---|
| Source | sends its VM's data stream to the receiver on the backup storage cluster |
| Backup storage (target) | holds chains, receives streams, sends historical data, rotates snapshots, and deletes chains |
| Restore | receives the stream back and deploys a VM from it |
The backup storage role is the focus of this page. It is the only role with chains: the source keeps data in the VM dataset, and the restore cluster keeps it in a quarantine receive dataset.
How it works
Data travels directly between clusters over TCP, rather than through the caller. This determines the order: receiver first, sender second. The backup storage cluster opens a receiver for the chain: it allocates a port and returns the receiver's connection details — the address of the pool's owner node and the port number. The sender connects to that address and port and sends the stream. The receive timeout specifies how long the receiver waits for a connection before closing the port.
This response arrives immediately and only means that the request has been sent to the node. It acknowledges that the request was relayed, rather than reporting the transfer result.
Operations fall into two groups by execution mode. Synchronous operations return their result immediately: a chain is created, a port is allocated, or a snapshot is deleted. An asynchronous transfer returns a relay acknowledgment, and the transfer result arrives in a callback from the node.
| Operation | Mode | What it does | Response |
|---|---|---|---|
| Create a chain | synchronous | creates a chain after selecting a pool | chain path, pool, node address |
| Open a receiver | synchronous | opens a stream receiver for the chain | node address and receive port |
| Send a restore point | asynchronous | sends a restore point to an external receiver | relay acknowledgment; the result arrives in a callback |
| Delete a restore point | synchronous | deletes one restore point | acknowledgment |
| Delete a chain | synchronous | deletes the entire chain | acknowledgment |
Both forms of deletion are idempotent: repeating a request for an object that has already been deleted does not disrupt the state or require special handling by the caller.
Access and enabling
All five subsystem operations require the same privilege — 14002, backup
chain management. Its scope is the cluster: a chain is not tied to a VDC, so the
VDC administrator role cannot make these requests. The privilege model is
described in the
Roles and privileges reference.
In addition to the privilege, there is a cluster-level switch: the
feature.backup parameter in cluster.options. Its default value is 0, in
which case any of the five operations returns error -25420. Each cluster has
its own switch: the subsystem can be enabled on the backup storage cluster while
remaining disabled on the other clusters.
Scope
The subsystem handles data transfer and storage, but not backup management. What it does not do:
- Maintain a catalog. The subsystem has no operations to list a cluster's chains or the snapshots within a chain. The caller keeps the records: save the chain path returned at creation, or you will not be able to access the chain again. The pool and node address in the same response are informational — they change when the pool's location changes, so do not rely on them.
- Schedule operations. There are no cluster-level schedules or retention policies. An external scheduler handles rotation by deleting outdated restore points one at a time.
- Send increments. Transfers from a chain in the current version are always full: incremental transfers are reserved and do not work.
- Create snapshots during a transfer. A transfer sends an existing point by name. If the required point is absent from the chain, it will not be created — the operation fails with an error.
- Display chains in the interface. The cluster's web interface has no screens for chains: the caller manages the operations.
See also
- How to manage backup chains — creation, stream reception, rotation, and deletion.
- How to send a restore point from a chain — transferring a historical snapshot to the restore cluster.
- Roles and privileges — privileges and scopes.
API methods
API operations covered on this page: backup-dataset-create, backup-dataset-receive,
backup-dataset-send, backup-snapshot-remove, backup-dataset-remove,
vm-backup-send, vm-backup-restore — see the
API reference.