Skip to main content

How to manage backup chains

When to use this​

When a cluster serves as backup storage: you need to create a location for a specific VM's backups, open a stream receiver, and later clean up the history or remove the entire chain. This procedure covers all operations on the backup storage cluster except sending historical data back, which is described in How to send a restore point from a chain.

The cluster's web interface has no screens for chains: the caller — GI or your own backup scheduler — manages the operations. The steps below therefore describe actions on objects without reference to screens. The subsystem model is described in Cluster-to-cluster backup.

Prerequisites​

  • privilege 14002 (backup chain management) — cluster-level scope; the VDC (virtual data center) administrator role cannot make these requests;
  • feature.backup in cluster.options on the backup storage cluster is 1; when it is 0, any subsystem operation returns -25420;
  • vStack Center version — 3.0.5;
  • the cluster has at least one consuming pool with an owner node that is up and enough free space for the backup;
  • all operations are addressed to the backup storage cluster: chains reside only there.

Steps​

Step 1. Create a chain​

Create a backup chain on the backup storage cluster. Specify only the leaf name — without the pool or the .backup prefix. The name must be 1 to 128 characters long and consist of Latin letters, digits, and the symbols _, ., -. The cluster rejects spaces, Cyrillic characters, slashes, and @ with code -25430. The cluster selects the pool itself. If the full backup size is known in advance, provide a size estimate. The cluster adds a 20 % margin for chain growth and excludes pools with less free space than that total. An estimate of 0 disables the filter.

In response, the cluster returns the full chain path in the form <pool>/.backup/<leaf>, along with the selected pool and the address of that pool's owner node.

Save the chain path in your own records: every subsequent operation needs it, and the subsystem has no way to list the cluster's chains. The pool and node address are informational — they show the current location and do not need to be stored.

Step 2. Open a stream receiver​

Open a receiver for the chain by specifying its full path. The timeout in seconds specifies how long the receiver waits for the sender to connect before closing the port.

The response arrives immediately and contains the receiver's connection details — the address of the pool's owner node and the allocated port number. This is where the sender connects: the source cluster with its VM, or another backup storage cluster sending a restore point. Pass the connection details to the sender and connect within the timeout: once it expires, the port closes, and the receiver must be opened again.

Step 3. Delete an outdated restore point​

Rotation removes one point at a time. Specify the chain path and the short snapshot name — the suffix after @, without the chain path.

Deletion is idempotent: repeating a request for a point that has already been deleted returns the same response. The response has no separate indicator that "the point existed and was deleted," so there is no need to check whether the snapshot exists beforehand.

Step 4. Delete the entire chain​

Deleting a chain removes it along with all restore points; they cannot be recovered afterward.

This operation is also idempotent. After deletion, remove the saved chain path from your catalog: the cluster no longer has any information about the chain.

Verify the result​

Check the response, but interpret it according to the operation. For chain creation and both deletion operations, a successful response confirms that the work was completed on the node: the chain path for creation, an acknowledgment for deletion.

Stream reception follows a different rule. The cluster allocates a port, relays the command to the storage agent on the pool's owner node, and immediately returns the connection details. A successful response therefore confirms that the command was relayed and the connection details were allocated — a nonempty node address and a port number — rather than that the stream has already been received. The data is actually received after the sender connects to that address and port.

There is no separate read operation for verification. An indirect way to verify that a chain was deleted is to open a receiver at its path: response -25432 confirms that the chain is indeed gone.

Troubleshooting​

-25420, the backup subsystem is disabled. The cluster's feature.backup in cluster.options is 0. The switch applies to the entire cluster and is checked before any pool operations, so this code is returned for any of the five operations. Workaround — enable the subsystem on this cluster; attempting to bypass it through another operation is pointless.

-25431 during creation, no pool has enough free space. The cluster found no consuming pool with an owner node that is up and enough free space for the size estimate plus the 20 % margin. A pool that barely fits the backup does not meet this condition and is also excluded. The cause may be either the estimate or the cluster's state. Workaround — refine the estimate or omit it entirely, free space in the pool, and check that the pools' owner nodes are up.

-25430, invalid chain path or snapshot name. The specified path is not of the form <pool>/.backup/<leaf>, or the chain or restore point name contains characters outside the set "Latin letters, digits, _, ., -." This check is intentional: only paths within .backup are relayed to nodes; otherwise, chain operations could reach VM datasets. Workaround — use the full path exactly as returned at creation, rather than constructing it manually.

-25432, chain not found. The path is valid, but no such chain exists on the cluster — most often it has already been deleted or was created on another cluster. Workaround — check the path against your catalog and verify which cluster the operation is addressed to.

-25434, the chain's pool is unavailable. The chain exists, but its pool's owner node is not responding. The data is not lost: the operation will become available when the node returns. Workaround — resolve the issue with the node; the subsystem cannot move the chain to another pool.

-25436, chain operation failed. A general failure code from the node. It covers different causes, which cannot be distinguished by the code. Workaround — retry the operation; if the failure persists, check the state of the pool's owner node.

-78 during creation, database error. The cluster dispatcher could not read the pool map to select a location for the chain. The chain was not created, and the state did not change. Workaround — retry the operation; if the failure persists, check the state of the cluster dispatcher.

See also​

API methods​

API operations covered on this page: backup-dataset-create, backup-dataset-receive, backup-snapshot-remove, backup-dataset-remove — see the API reference.