volume_backup

The volume_backup domain has 14 actions. On the meta surface they are all reached through arcane_volume_backup; on the individual surface each one is its own tool; on the dynamic surface run them with arcane_execute_action and the canonical ID.

Summary

Action	Title	Kind
`volume_backup.browse_files`	Browse files in a volume backup	read
`volume_backup.create`	Create volume backup	write
`volume_backup.delete`	Delete volume backup	destructive
`volume_backup.discover`	Discover volume backups on an S3 destination	write
`volume_backup.download`	Download volume backup	read
`volume_backup.files`	List files in a volume backup	read
`volume_backup.has_path`	Check if backup contains path	read
`volume_backup.list`	List volume backups	read
`volume_backup.policy_get`	Get volume backup policies	read
`volume_backup.policy_update`	Update volume backup policies	write
`volume_backup.restore`	Restore volume backup	destructive
`volume_backup.restore_files`	Restore specific files from a volume backup	destructive
`volume_backup.upload`	Upload and restore volume backup	destructive
`volume_backup.upload_to_s3`	Upload volume backup	write

Actions

`volume_backup.browse_files`

Browse files in a volume backup

Kind: read
Required parameters: backupId
Meta tool: arcane_volume_backup with "action": "browse_files"
Individual tool: arcane_volume_backup_browse_files
Arcane route: GET /api/environments/{id}/volumes/backups/{backupId}/files/browse
Operation ID: browse-volume-backup-files
Usage: One directory level of the backup (backupId from volume_backup.list, path relative to the root, default the root, and a failed backup answers 500 as in volume_backup.files) as entries with path and isDirectory, paged with start and limit (default 20). search matches full paths case-insensitively across the whole backup, ignoring path. The paths returned are what volume_backup.restore_files takes.
Related actions: volume_backup.list, volume_backup.files, volume_backup.restore_files

`volume_backup.create`

Create volume backup

Kind: write
Required parameters: volumeName
Meta tool: arcane_volume_backup with "action": "create"
Individual tool: arcane_volume_backup_create
Arcane route: POST /api/environments/{id}/volumes/{volumeName}/backups
Operation ID: create-volume-backup
Usage: Starts a backup of one volume (volumeName from volume.list) and returns at once with the new entry (id, status running). Poll volume_backup.list until its status is succeeded or failed. With no body it backs up locally. policyId (from volume_backup.policy_get) uses that policy’s local/S3 targets, S3 destination, stopContainers and retention (older backups of the policy beyond retentionCount are deleted), and destination local, s3 or local_s3 overrides the targets. Without policyId, s3 and local_s3 need s3DestinationId from s3_destination.list. With policyId the policy’s S3 destination is used and s3DestinationId is ignored. Fails with 409 while another backup of the volume runs. Needs volumes:backup. Not backup.create, which backs up Arcane itself.
Related actions: volume.list, volume_backup.list, volume_backup.policy_get, s3_destination.list, backup.volume_run

`volume_backup.delete`

Delete volume backup

Kind: destructive — requires confirm: true
Required parameters: backupId
Meta tool: arcane_volume_backup with "action": "delete"
Individual tool: arcane_volume_backup_delete
Arcane route: DELETE /api/environments/{id}/volumes/backups/{backupId}
Operation ID: delete-volume-backup
Usage: Permanently deletes one volume backup (backupId from volume_backup.list): its local snapshot or archive, its S3 copy if it has one, and the record. Needs volumes:backup, fails with 404 for an unknown backupId and fails (does not wait) while a backup, S3 upload or delete of the same volume is running. If the S3 copy cannot be removed the record stays with only that copy.
Related actions: volume_backup.list, volume_backup.download

`volume_backup.discover`

Discover volume backups on an S3 destination

Import existing volume backups stored on the destination by this or other Arcane instances

Kind: write
Required parameters: s3DestinationId
Meta tool: arcane_volume_backup with "action": "discover"
Individual tool: arcane_volume_backup_discover
Arcane route: POST /api/environments/{id}/volumes/backups/discover
Operation ID: discover-volume-backups
Since: Arcane v2.12.0
Usage: Imports the volume backups found on an S3 destination (s3DestinationId from s3_destination.list), written by this or another Arcane instance, so volume_backup.list shows them and volume_backup.restore can use them. Needs the recovery key set with backup.recovery_key_set. Returns count of new records and per-instance errors, skipping ones already known. Arcane system backups are discovered with backup.discover.
Related actions: s3_destination.list, backup.recovery_key_set, volume_backup.list, volume_backup.restore, backup.discover

`volume_backup.download`

Download volume backup

Kind: read
Required parameters: backupId
Meta tool: arcane_volume_backup with "action": "download"
Individual tool: arcane_volume_backup_download
Arcane route: GET /api/environments/{id}/volumes/backups/{backupId}/download
Operation ID: download-volume-backup
Usage: Returns the backup (backupId from volume_backup.list) as a .tar.gz archive blob. Only backups with a local copy can be downloaded, not S3-only ones, and a failed backup (status failed, no snapshot) answers 500 rather than a 4xx. An archive larger than ARCANE_MCP_MAX_DOWNLOAD_BYTES (default 4 MiB) is not returned at all: the result only holds truncated true and a note.
Related actions: volume_backup.list, volume_backup.files, volume_backup.upload

`volume_backup.files`

List files in a volume backup

Kind: read
Required parameters: backupId
Meta tool: arcane_volume_backup with "action": "files"
Individual tool: arcane_volume_backup_files
Arcane route: GET /api/environments/{id}/volumes/backups/{backupId}/files
Operation ID: list-backup-files
Usage: Flat list of every file path in the backup (backupId from volume_backup.list), relative to the volume root. A failed backup (no snapshot) answers 500 ‘volume backup has no Rustic snapshot’ rather than a 4xx. For one directory level at a time with paging and search use volume_backup.browse_files.
Related actions: volume_backup.list, volume_backup.browse_files, volume_backup.restore_files

`volume_backup.has_path`

Check if backup contains path

Kind: read
Required parameters: backupId
Meta tool: arcane_volume_backup with "action": "has_path"
Individual tool: arcane_volume_backup_has_path
Arcane route: GET /api/environments/{id}/volumes/backups/{backupId}/has-path
Operation ID: backup-has-path
Usage: Answers exists true or false for one relative file path (e.g. sub/b.txt) in the backup, e.g. before volume_backup.restore_files, with backupId from volume_backup.list. A failed backup answers 500 as in volume_backup.files.
Related actions: volume_backup.files, volume_backup.restore_files

`volume_backup.list`

List volume backups

Kind: read
Required parameters: volumeName
Meta tool: arcane_volume_backup with "action": "list"
Individual tool: arcane_volume_backup_list
Arcane route: GET /api/environments/{id}/volumes/{volumeName}/backups
Operation ID: list-volume-backups
Usage: Paged backups of one volume (volumeName required, limit defaults to 20) with id, status (running, succeeded, failed), trigger (manual, scheduled, safety), destination, format, size, snapshot IDs and policyId. The id is the backupId the other volume_backup actions take. type=system keeps backups made by the centralized backup.volume_* policies, type=volume the rest. Restores leave trigger=safety backups here. For backups of every volume at once use backup.history.
Related actions: volume_backup.create, volume_backup.browse_files, volume_backup.restore, volume_backup.delete, backup.history

`volume_backup.policy_get`

Get volume backup policies

Kind: read
Required parameters: volumeName
Meta tool: arcane_volume_backup with "action": "policy_get"
Individual tool: arcane_volume_backup_policy_get
Arcane route: GET /api/environments/{id}/volumes/{volumeName}/backup-policy
Operation ID: get-volume-backup-policy
Usage: Scheduled backup policies of one volume (volumeName from volume.list), each with id, enabled, schedule, retention, targets and its last run. The ids are what volume_backup.policy_update keeps and volume_backup.create takes as policyId. Centralized policies covering many volumes are in backup.volume_config_get.
Related actions: volume_backup.policy_update, volume_backup.create, backup.volume_config_get

`volume_backup.policy_update`

Update volume backup policies

Kind: write
Required parameters: volumeName, policies
Meta tool: arcane_volume_backup with "action": "policy_update"
Individual tool: arcane_volume_backup_policy_update
Arcane route: PUT /api/environments/{id}/volumes/{volumeName}/backup-policy
Operation ID: update-volume-backup-policy
Usage: Replaces the volume’s whole list of policies: entries with an id from volume_backup.policy_get update that policy, entries without one are created, and omitted policies are deleted ([] removes all). Each needs enabled, schedule (six-field cron with seconds, e.g. 0 0 3 * * ), retentionCount, localEnabled and s3Enabled (with s3DestinationId). stopContainers is optional. An enabled per-volume policy makes the centralized backup.volume_ backups skip this volume.
Related actions: volume_backup.policy_get, s3_destination.list, backup.volume_config_update

`volume_backup.restore`

Restore volume backup

Kind: destructive — requires confirm: true
Required parameters: volumeName, backupId
Meta tool: arcane_volume_backup with "action": "restore"
Individual tool: arcane_volume_backup_restore
Arcane route: POST /api/environments/{id}/volumes/{volumeName}/backups/{backupId}/restore
Operation ID: restore-volume-backup
Usage: Overwrites the whole volume with the backup (volumeName must be the backup’s volume, backupId from volume_backup.list): stops the running containers using the volume, takes a safety backup, restores (files not in the backup are removed) and starts the containers again. A missing volume is created first (no safety backup then). Refused when a running Arcane-managed container mounts the volume. Runs to completion before answering. To put back only some paths use volume_backup.restore_files.
Related actions: volume_backup.list, volume_backup.restore_files, volume_backup.browse_files, volume.workspace_get

`volume_backup.restore_files`

Restore specific files from a volume backup

Kind: destructive — requires confirm: true
Required parameters: volumeName, backupId
Meta tool: arcane_volume_backup with "action": "restore_files"
Individual tool: arcane_volume_backup_restore_files
Arcane route: POST /api/environments/{id}/volumes/{volumeName}/backups/{backupId}/restore-files
Operation ID: restore-volume-backup-files
Usage: Restores only the given paths (relative, from volume_backup.browse_files or volume_backup.files) of the backup into its volume (volumeName must be the backup’s volume). A directory path is restored as a whole, removing files in it that the backup lacks. selectAll with search restores every path containing the search text, selectAll alone restores everything like volume_backup.restore, but paths cannot be combined with selectAll. Like a full restore it stops the containers using the volume, takes a safety backup first and restarts them. Other files stay as they are.
Related actions: volume_backup.browse_files, volume_backup.files, volume_backup.has_path, volume_backup.restore, volume.workspace_file_get

`volume_backup.upload`

Upload and restore volume backup

Restore a volume from a complete chunked upload session containing a tar.gz backup archive. multipart/form-data bodies are still accepted for backward compatibility. That form is deprecated and will be removed in a future release.

Kind: destructive — requires confirm: true
Required parameters: volumeName, uploadId
Meta tool: arcane_volume_backup with "action": "upload"
Individual tool: arcane_volume_backup_upload
Arcane route: POST /api/environments/{id}/volumes/{volumeName}/backups/upload
Operation ID: upload-volume-backup
Usage: Replaces the contents of a volume with a .tar.gz archive uploaded first with upload.session_create (kind volume-backup) and upload.chunk_put. Pass its uploadId. A safety backup is taken first, but containers using the volume are not stopped.
Related actions: upload.session_create, upload.chunk_put, volume_backup.download, volume_backup.restore

`volume_backup.upload_to_s3`

Upload volume backup

Upload an existing local volume backup to the selected S3 destination

Kind: write
Required parameters: backupId, s3DestinationId
Meta tool: arcane_volume_backup with "action": "upload_to_s3"
Individual tool: arcane_volume_backup_upload_to_s3
Arcane route: POST /api/environments/{id}/volumes/backups/{backupId}/upload
Operation ID: upload-retained-volume-backup-to-s3
Usage: Copies an existing succeeded local backup (backupId from volume_backup.list, a failed one is refused with 500) to an S3 destination (s3DestinationId from s3_destination.list). The returned backup has destination local_s3 and a remoteSnapshotId. A backup already on S3 is refused. To back up straight to S3 use volume_backup.create with destination s3.
Related actions: volume_backup.list, s3_destination.list, volume_backup.create