diff --git a/apps/docs/content/docs/concepts/backups.mdx b/apps/docs/content/docs/concepts/backups.mdx index 37b40a31..5ac023dd 100644 --- a/apps/docs/content/docs/concepts/backups.mdx +++ b/apps/docs/content/docs/concepts/backups.mdx @@ -134,7 +134,11 @@ The first backup uploads all data and may take longer. Subsequent backups are si ## Restoring data -To restore files from a backup: +Zerobyte lets you browse snapshots, restore them back to a filesystem path, or download the selected contents directly. + +For the complete restore workflow, overwrite modes, custom-target guidance, and mounted-volume permission caveats, see [Restoring Data](/docs/guides/restoring). + +At a high level, restoring works like this: diff --git a/apps/docs/content/docs/guides/meta.json b/apps/docs/content/docs/guides/meta.json index 209e8071..1f6a6767 100644 --- a/apps/docs/content/docs/guides/meta.json +++ b/apps/docs/content/docs/guides/meta.json @@ -2,6 +2,7 @@ "title": "Guides", "pages": [ "3-2-1-backup-strategy", + "restoring", "notifications", "recovery-key-and-repository-passwords", "repository-maintenance", diff --git a/apps/docs/content/docs/guides/restoring.mdx b/apps/docs/content/docs/guides/restoring.mdx new file mode 100644 index 00000000..c94d995b --- /dev/null +++ b/apps/docs/content/docs/guides/restoring.mdx @@ -0,0 +1,263 @@ +--- +title: Restoring Data +description: Restore files and folders from snapshots, choose the right destination, and avoid common restore pitfalls +--- + +Zerobyte lets you recover data in two ways: + +- **Restore**, writes files back to a filesystem path +- **Download**, retrieves the selected contents without restoring them directly into a mounted destination + +This guide covers when to use each option, how the restore form works, and what to do when a destination rejects ownership or permission changes. + +## Before you restore + +Before starting a restore, check these basics: + +- the repository is reachable and unlocked +- the target path is writable +- the destination has enough free space + +If you are restoring into a path that is bind-mounted into the container, make sure it is **not** mounted read-only. Read-only mounts can be backed up, but they cannot accept restores back into the original location. + + +If you are not fully sure about the target, restore to a custom staging path first. It is safer, easier to verify, and reduces the chance of overwriting live data. + + +## Restore vs Download + +Use **Restore** when you want Zerobyte to write files back onto a filesystem path. + +Use **Download** when you want to recover the contents without restoring them directly into the current mounted destination. + +As a rule of thumb: + +- use **Restore** for normal recovery back to a server path +- use **Download** for one-off recovery to your workstation, or when a mounted destination keeps failing on permissions or metadata + +In the current UI, **Download** is available when you select a single item, or when you leave the selection empty and download the snapshot contents directly. + +## Standard restore workflow + + + + +### Open the backup job + +Go to **Backups** and open the job that contains the data you need. + + + + + +### Choose the snapshot + +Select the snapshot from the time period you want to recover. + + + + + +### Browse and select data + +Use the file browser to inspect the snapshot and optionally select specific files or folders. + +If you leave the selection empty, Zerobyte restores the full snapshot scope that is currently being viewed. + + + + + +### Choose the destination + +Pick either: + +- **Original location**, to put the data back where it came from +- **Custom location**, to restore into another path + + + + + +### Review overwrite behavior + +Choose how Zerobyte should handle files that already exist at the target. + + + + + +### Start the restore + +Click **Restore** and wait for the progress indicator to finish. When it completes, verify that the recovered files are present and usable. + + + + +## Choosing the restore location + +### Original location + +Original-location restore is convenient when you want to put the snapshot back exactly where it came from. + +Use it when: + +- the original path still exists +- the path is writable +- you are intentionally restoring back in place + +Be careful with it because it targets live paths. + +### Custom location + +Custom-location restore writes the recovered data to another path that you choose. + +This is the safer default when: + +- you want to inspect the recovered files first +- you are restoring onto a different server or container +- the original location is no longer correct +- you expect permission or metadata problems on the final destination + + +If the snapshot was created from non-POSIX paths, or from source paths that do not match the current Zerobyte server or linked volume, original-location restore is unavailable. Restore to a custom location instead. + + +## Overwrite modes + +Zerobyte exposes Restic's overwrite behavior in the restore form. + +### Always overwrite + +Replace existing files with the snapshot version. This is the most direct in-place restore mode. + +### Only if content changed + +Overwrite existing files only when their content differs from the snapshot. This avoids replacing identical files unnecessarily. + +### Only if snapshot is newer + +Overwrite existing files only when the snapshot version has a newer modification time. + +### Never overwrite + +Restore only missing files. Existing files are left in place. + +## Advanced option: excluding extended attributes + +The restore form includes an **Exclude extended attributes** field under **Advanced options**. + +Use it only when the destination accepts file contents but rejects specific xattrs. Common examples include: + +- `security.*` +- `system.*` +- ACL-related attributes + +This is useful for narrowly targeted compatibility problems. It does **not** fix ownership or mode failures like `lchown` or `chmod`. + +## Why some restores fail on permissions or ownership + +If you see errors like these: + +```text +lchown /path/to/file: operation not permitted +lchown /path/to/file: permission denied +chmod /path/to/file: operation not permitted +failed to restore timestamp +``` + +the data copy often succeeded. The failure usually happens afterward, when Restic tries to re-apply the original metadata from the snapshot. + +Restic restores more than file contents. It also restores metadata such as: + +- owner and group +- file mode +- timestamps +- extended attributes and ACL-related metadata + +That works well on a normal local Linux filesystem. It gets more complicated when the target is a mounted or translated filesystem such as: + +- SFTP volumes mounted through SSHFS +- SMB or CIFS shares +- WebDAV volumes +- rclone-mounted cloud storage +- Windows systems accessed through SFTP +- NAS or appliance-managed shares that do not allow arbitrary ownership changes + +These destinations may let Zerobyte write file contents while still rejecting `chown`, `chmod`, timestamp, or xattr updates. + + +In Zerobyte today, SFTP, SMB, and WebDAV mounts pass the container process `uid` and `gid` to the mount command. If the container runs as root, those mounts can appear as `0:0` inside the container even when the remote system stores ownership differently. A backup taken from that mounted view can therefore record synthetic ownership in the snapshot. + + +## What Zerobyte can and cannot change + +Zerobyte can: + +- restore to another target path +- restore selected files or folders +- let you download data instead of restoring it directly +- exclude specific extended attributes during restore + +Zerobyte cannot currently tell Restic to restore file contents while completely skipping owner, group, mode, and timestamp restoration. Restic supports xattr filtering, but it does not provide a general "ignore metadata" restore mode. + +That means a restore directly into a metadata-rejecting mount cannot be made fully reliable without using a different destination or a second manual copy step. + +## Reliable workarounds + +### Restore to a different place first + +This is the most reliable workaround. + +Restore to a local Linux path or another writable POSIX filesystem first, verify the recovered files, then move or copy them to the final destination manually. + +This works because: + +- Restic finishes on a filesystem that accepts metadata updates +- the later copy step only has to match what the final destination actually supports + +### Use Download for small recoveries + +If you only need one file or one folder quickly, use **Download** instead of **Restore**. + +This avoids asking the mounted destination to accept snapshot ownership and permission metadata. + +### Exclude failing xattrs when that is the only problem + +If the failure is limited to extended attributes, exclude the failing xattr under **Advanced options** and retry. + +Do not expect this to solve `lchown` or `chmod` failures. + +### Prefer host mounts or native paths + +If you control the Docker host, a more reliable pattern is: + +1. mount the remote share on the host +2. bind-mount that host path into the Zerobyte container +3. restore to that bind-mounted path or to another local staging path first + +This often behaves better than restoring straight through a FUSE-based mount created inside the container. + +### Use a filesystem that supports POSIX metadata when exact restore fidelity matters + +If you need the restored data to keep Unix owner, group, and mode information exactly, restore to a destination that supports those semantics end-to-end. + +That is usually a local Linux filesystem or a properly configured NFS share, not a translated or appliance-managed mount. + +## Practical recommendations + +- Test restores regularly, not just backups +- Prefer a custom restore path for routine verification +- Keep at least one fast local repository for quick recovery +- Use **Download** for ad-hoc recovery to your own machine +- Verify recovered files before deleting or overwriting the originals + +## Related guides + +- [Quick Start](/docs/quickstart) +- [3-2-1 Backup Strategy](/docs/guides/3-2-1-backup-strategy) +- [Recovery keys and repository passwords](/docs/guides/recovery-key-and-repository-passwords) +- [Troubleshooting](/docs/troubleshooting) + +import { Callout } from "fumadocs-ui/components/callout"; +import { Step, Steps } from "fumadocs-ui/components/steps"; diff --git a/apps/docs/content/docs/quickstart.mdx b/apps/docs/content/docs/quickstart.mdx index 5c8b13dc..4f3ba4ba 100644 --- a/apps/docs/content/docs/quickstart.mdx +++ b/apps/docs/content/docs/quickstart.mdx @@ -691,6 +691,10 @@ Click **Restore All** to restore everything, or select specific files first and + + For the full restore workflow, overwrite modes, download vs restore, and mounted-volume permission caveats, see [Restoring Data](/docs/guides/restoring). + + ### Pausing a Backup Job To temporarily stop a backup from running: diff --git a/apps/docs/content/docs/troubleshooting.mdx b/apps/docs/content/docs/troubleshooting.mdx index 01d2fff8..a4378aa7 100644 --- a/apps/docs/content/docs/troubleshooting.mdx +++ b/apps/docs/content/docs/troubleshooting.mdx @@ -223,6 +223,12 @@ Rclone volumes (mounting cloud storage as a data source) require: ## Backup Issues +### Restore Fails with `lchown` or `operation not permitted` + +If you restore directly to SFTP, SMB, WebDAV, rclone, or another mounted filesystem, the destination may accept file contents but reject ownership, mode, timestamp, or xattr updates. + +See [Restoring Data](/docs/guides/restoring) for the full restore workflow, the explanation, and the safest workarounds. + ### Backup Failed: Permission Denied Ensure the volume directory has proper permissions: