Application backup hooks

Prepare and resume applications around a coordinated disk capture.

Backup hooks let an application establish its supported recovery boundary before Infra captures a volume or consistency group. Hooks run inside the guest through an authorized guest agent.

Prepare and resumeCopy link

Open Project settings → Backup hooks → Create hook set. Attach its revision at Storage → Backup policies → Policy → Consistency → Application hooks.

A hook set defines a prepare command and a resume command. Prepare can flush application state, enter backup mode, or write a database checkpoint. Resume must leave that mode and restore ordinary writes.

Commands execute as argument arrays rather than interpolated shell strings. Use an explicit shell only when the application procedure requires one. Hook configuration belongs to the project and references permitted droplets or consistency groups; it does not grant arbitrary command execution across the fleet.

The following definition requires the two scripts to exist in the guest. Those scripts must implement the application's own backup procedure:

name: ledger-checkpoint
prepare:
  argv: [/usr/local/sbin/ledger-backup, prepare]
  timeoutSeconds: 60
resume:
  argv: [/usr/local/sbin/ledger-backup, resume]
  timeoutSeconds: 60

Each timeout is an integer from 1 through 300 seconds, inclusive, with default 60. A nonzero exit or timeout fails that hook. Output is bounded and redacted according to the guest-execution policy; hook output must not contain secrets.

Failure before captureCopy link

A failed required prepare prevents the capture. Infra does not downgrade an application-consistent request to crash consistency. If several guests participate, a successful prepare on one guest is followed by resume even if another guest cannot prepare.

A command can change application state before it times out. The prepare script must be safe to retry or detect its current state. A timeout means the desired result was not confirmed, not that the command had no side effects.

Failure after preparationCopy link

Infra schedules resume after capture, cancellation, or failure for every guest that began preparation. If a guest cannot be reached, its run result records resume_pending. Use Recover a pending resume to restore writes before clearing that condition.

Do not keep an application indefinitely frozen while retrying a remote upload. Capture and guest resumption happen before the independent backup transfer. A destination outage should leave the guest running while the copy reports failure.

Change and auditCopy link

Editing a hook creates a revision. A run pins the revision it selected at start; later edits affect future runs. Review commands and guest targets before assigning a hook to a policy that resolves many droplets by label.

Hook administration and execution are separately authorized and audited. Use Backup Run API to read per-guest preparation and resume results, and backup verification to prove the captured application data can actually be restored.

Recover a pending resumeCopy link

A repeated resume command must detect whether backup or freeze mode is still active and safely complete without repeating unrelated application work. Keep the guest and hook revision in the recovery record.

Open the affected backup run under Storage → Backup policies → Policy and record the guest ID and pinned hook revision from its preparation result. Connect to that guest through guest access and follow the application's documented exit-from-backup-mode procedure. If the hook froze a filesystem, confirm it is writable as well as checking the application.

Return to the run's recovery condition and acknowledge resume_pending only after those checks pass. Keep the commands and results in the recovery record. A later completed upload does not establish guest resumption, and rerunning prepare can freeze the application again.