Skip to main content

How to send a restore point from a chain

When to use this​

When a VM needs to be restored from a backup: data flows back from the backup storage cluster to the cluster where the VM will run. In this procedure, the backup storage cluster is the sender, and its job is to retrieve one historical point from the chain and send it to the specified receiver.

The order is the reverse of the usual one: receiver first, sender second. The restore cluster opens a receiver on its side and returns its node's connection details. Only then does the backup storage cluster start the transfer. The transfer is asynchronous: the cluster acknowledges the relay immediately, and the transfer result arrives in a callback.

The cluster's web interface has no screens for chains: the caller — GI or your own restore scheduler — starts the transfer. Operations on the chain itself — creation, stream reception, and rotation — are described in How to manage backup chains.

Prerequisites​

  • privilege 14002 (backup chain management) on the backup storage cluster;
  • feature.backup in the backup storage cluster's cluster.options is 1; when it is 0, the transfer returns -25420;
  • vStack Center version — 3.0.5;
  • the chain exists and its owner node is up;
  • the receiver's connection details are known — the node address and port returned by the restore cluster when it opened its receiver;
  • the short name of the restore point to send is known.

Steps​

Step 1. Obtain the receiver's connection details​

The restore cluster opens the receiver, rather than the backup storage cluster. Take the receiver node's address and port from its response: these become the transfer parameters. Starting a transfer before the receiver is open is pointless — the stream has nowhere to connect.

Step 2. Identify the restore point​

Specify the short snapshot name — the suffix after @, without the chain path. 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 @ within the name with code -25430. A transfer sends an existing point and does not create a new snapshot: anything absent from the chain cannot be transferred.

The subsystem does not provide a list of points within a chain, so keep their names in your own catalog alongside the chain path returned at creation.

Step 3. Start the transfer​

Start the transfer on the backup storage cluster. Specify the full chain path, the short restore point name, and the receiver's connection details — its node address and port.

The optional timeout in seconds limits the time to establish the TCP connection to the receiver, rather than the transfer duration. Incremental transfers are reserved and do not work in the current version: transfers are always full.

The response arrives immediately — it is a relay acknowledgment: the request has been sent to the pool's owner node. No data has been transferred at this point.

Step 4. Wait for the result​

The transfer result arrives in a callback from the node, with the same identifier as the request. The subsystem has no operation that returns the transfer status on demand, so the callback is the only source of the result. Match it to the request by identifier, and do not treat the relay acknowledgment as success.

Verify the result​

Success is confirmed on both sides. On the backup storage cluster's side — by the callback with the transfer result. On the restore cluster's side — by the state of the receiver it opened: this is where the data arrives and from where the VM is deployed.

The chain's state does not change after the transfer: the point remains in place, and no new snapshots are created. The same point can be sent again to a new receiver.

Troubleshooting​

-25420, the backup subsystem is disabled. The backup storage cluster's feature.backup in cluster.options is 0. The check occurs before the relay, so there will be no callback at all. Workaround — enable the subsystem on the cluster sending the data.

-25430, invalid chain path or snapshot name. The specified path is not of the form <pool>/.backup/<leaf>, or the restore point name contains characters outside the set "Latin letters, digits, _, ., -." The cluster relays only paths within .backup to nodes, so attempts to transfer a VM dataset through this operation are rejected. Workaround — use the full path exactly as returned at chain creation, and take the point name from your catalog.

-25434, the chain's pool is unavailable. The pool's owner node is not responding, so there is no node to send the stream. The data is intact. Workaround — bring the node back into service; the subsystem cannot move the chain to another pool.

-25436, chain operation failed. A general failure code. It covers different causes, which cannot be distinguished by the code. Workaround — retry the transfer; if the failure persists, check the pool's owner node and the receiver's availability at the specified address and port.

Only the relay acknowledgment arrived, with nothing afterward. The response to an asynchronous transfer is not the result. If no callback arrives for a long time, check that the receiver is open and has not closed because its connection wait timeout expired: in that case, open the receiver again and restart the transfer.

The point name is incorrect. There is no way to check it in advance — the subsystem has no way to list the chain's snapshots. The error becomes apparent only in the transfer result. Workaround — maintain a catalog of points on your side and pass the name from there rather than typing it manually.

See also​

API methods​

API operations covered on this page: backup-dataset-send, vm-backup-restore — see the API reference.