Point-in-Time File Restore

Most hosting panels — including cPanel — only support full restores. If a customer accidentally deletes a single file, the only way to get it back is to restore the entire account from yesterday's backup, overwriting hours of unrelated changes.

Opterius solves this with Point-in-Time File Restore: you can browse the contents of any backup directly from the panel, pick the specific files you want, and restore only those — leaving the rest of the account untouched.

This is one of the features that makes hosting customers say "oh wow, this is actually better than cPanel."

How to Browse a Backup#

1. Open Backups in the admin sidebar.
2. Find the backup you want to inspect in the list.
3. Click the Browse button next to it.

The browse view shows the contents of the backup at the root level. You can navigate into subdirectories by clicking folder names — breadcrumbs at the top let you jump back up at any time.

The browser uses tar -tvzf to read the archive's index without extracting anything, so opening a 5 GB backup is just as fast as opening a 5 MB one.

Restoring Individual Files#

1. While browsing, tick the checkbox next to each file you want to restore. You can also tick the header checkbox to select everything in the current view.
2. (Optional) Edit the Restore destination field at the top. By default it's set to the user's public_html directory, but you can change it to restore files into a subdirectory or even a different account.
3. (Optional) Tick Overwrite existing files if you want to replace files that already exist at the destination. Without this, files that already exist are skipped.
4. Click Restore Selected.

The agent extracts only the chosen files into a temporary directory, then moves them into the destination with the correct ownership. The result message shows how many files were restored and how many were skipped.

Use Cases#

A customer deleted their wp-config.php#

1. Browse yesterday's backup.
2. Navigate to the WordPress folder.
3. Tick wp-config.php.
4. Tick Overwrite existing files (in case a fresh empty file was created).
5. Restore.

Done in 30 seconds. No full restore needed.

Recovering a single image#

A user uploaded a hero image to /wp-content/uploads/2026/01/hero.jpg, then accidentally deleted it from the media library three weeks ago.

1. Browse the backup from before the deletion.
2. Navigate to wp-content/uploads/2026/01/.
3. Tick hero.jpg.
4. Restore.

The image reappears in the media library on next page load.

Comparing the current code to a backup#

1. Browse the backup to a folder.
2. Restore the file you want to compare to a different destination — for example /home/user/restored-comparison/.
3. Use SSH or the file manager to diff the restored file against the live one.

You can use this as a poor-man's version control for sites that don't use git.

How It Works Under the Hood#

Opterius backups are standard tar.gz archives stored at /var/backups/opterius/. The browse and restore actions use the agent's filesystem access:

• Browsing: tar -tvzf backup.tar.gz parses the archive index without extracting any data. The agent groups entries by directory and returns the immediate children of the requested path.
• Restoring: tar -xzf backup.tar.gz -C /tmp/opterius-restore-XXX -- file1 file2 file3 extracts only the specified paths to a temporary directory. The agent then moves them into the destination with chown set to the original user.

The temporary directory is cleaned up automatically when the operation completes, even if some files failed to restore.

Safety Notes#

• Path validation: the agent rejects any restore request that includes .. or absolute paths in the file list. This prevents an attacker who somehow gets through the panel auth from extracting files outside the destination.
• Document root validation: the destination must be under /home/{user}/ (the original account owner). You can't restore files into another account, into /etc, or anywhere else on the filesystem.
• Overwrite is opt-in: by default, files that already exist at the destination are skipped, not overwritten. This protects against accidentally clobbering newer files with older ones.
• Ownership is preserved: restored files are chowned back to the original system user automatically.

Limitations#

• Only files inside the tar.gz archive are browseable. If your backup type is "files only", you won't see databases or email. If your backup is "full", you'll see all three sections.
• Restoring individual database tables is not supported via this UI. For partial database restores, use phpMyAdmin or mysqldump --tables. The backup browser only handles files.
• Symlinks are restored as-is. If a symlink points to an absolute path that no longer exists on the destination server, the restored symlink will be broken.
• Selection is per-page, not across breadcrumb navigation. If you select files in /folder1/, then navigate to /folder2/, your selection from /folder1/ is forgotten. Restore one folder at a time.

Troubleshooting#

"Could not read backup contents." The backup file may be corrupted or the agent doesn't have read access to /var/backups/opterius/. Check the agent logs at journalctl -u opterius-agent for the exact error.

"Restored 0 files. Skipped N (already existed — tick 'overwrite' to replace)." The files you selected already exist at the destination. Either delete them first, or re-run the restore with Overwrite existing files ticked.

Restored files have wrong permissions. The agent restores files with chown -R {user}:{user}, which sets ownership but not file modes. Permissions inside the tarball are preserved by tar itself. If you need to fix modes after a restore, run chmod -R u+rw {path} from SSH.