172 lines
4.9 KiB
Markdown
172 lines
4.9 KiB
Markdown
# Backups
|
|
|
|
Holesail Browser can create `tar.gz` snapshots of all persistent state and certificates. Backups can be created manually from the dashboard or restored at any time.
|
|
|
|
## What is backed up
|
|
|
|
Each backup archive contains:
|
|
|
|
| Path in archive | Source |
|
|
|-----------------|--------|
|
|
| `storage/state.json` | All virtual hosts, server tunnels (with labels), service tunnels, SSH connections (with `passwordB64`), RDP connections (with `passwordB64`), and settings |
|
|
| `certs/ca.key.pem` | Root CA private key |
|
|
| `certs/ca.cert.pem` | Root CA certificate |
|
|
| `certs/wildcard.hole.sail/` | Wildcard cert for the default `.hole.sail` TLD |
|
|
| `certs/wildcard.<parent>/` | One directory per custom TLD parent (e.g. `wildcard.my.internal/`, `wildcard.haha.wooo/`) |
|
|
|
|
The entire `holesail-browser-certs/` directory is archived — all wildcard cert directories are included, not just the default one. Backups do **not** include the binary itself, the log file, or other backup archives.
|
|
|
|
The default backup retention is **5 backups** (configurable in Settings via `backupRetention`).
|
|
|
|
## Storage location
|
|
|
|
Backups are stored at:
|
|
|
|
```
|
|
~/.holesail-browser/holesail-browser-storage/backups/
|
|
```
|
|
|
|
Each backup is a `tar.gz` file named with a timestamp:
|
|
|
|
```
|
|
holesail-browser-backup-2026-02-28T12-00-00.tar.gz
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Creating a backup
|
|
|
|
1. Open the dashboard → **Backups**
|
|
2. Click **Create Backup**
|
|
3. The backup is created immediately and appears in the list
|
|
|
|
### Restoring a backup
|
|
|
|
1. Open the dashboard → **Backups**
|
|
2. Find the backup you want to restore
|
|
3. Click **Restore**
|
|
4. The native host extracts the archive, overwrites the current state and certs, and reloads state from disk
|
|
|
|
> After restoring a backup that contains different certificates, you may need to reinstall the root CA (dashboard → Proxy & CA → Install Root CA) and restart Chrome.
|
|
|
|
### Deleting a backup
|
|
|
|
1. Open the dashboard → **Backups**
|
|
2. Click **Delete** next to the backup you want to remove
|
|
|
|
### Retention
|
|
|
|
Backups are automatically pruned after each new backup is created. The default retention is **5 backups**. To change it:
|
|
|
|
1. Open the dashboard → **Settings**
|
|
2. Set **Backup Retention** to the desired number
|
|
3. Click **Save**
|
|
|
|
---
|
|
|
|
## Native host commands
|
|
|
|
### `createBackup`
|
|
|
|
Create a new backup.
|
|
|
|
**Request payload:** `{}`
|
|
|
|
**Response payload:**
|
|
```json
|
|
{
|
|
"ok": true,
|
|
"filename": "holesail-browser-backup-2026-02-28T12-00-00.tar.gz",
|
|
"path": "/Users/you/.holesail-browser/holesail-browser-storage/backups/holesail-browser-backup-2026-02-28T12-00-00.tar.gz"
|
|
}
|
|
```
|
|
|
|
### `listBackups`
|
|
|
|
List all available backups.
|
|
|
|
**Response payload:**
|
|
```json
|
|
{
|
|
"ok": true,
|
|
"backups": [
|
|
{
|
|
"filename": "holesail-browser-backup-2026-02-28T12-00-00.tar.gz",
|
|
"size": 12345,
|
|
"createdAt": "2026-02-28T12:00:00.000Z"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### `restoreBackup`
|
|
|
|
Restore a backup by filename.
|
|
|
|
**Request payload:**
|
|
```json
|
|
{ "filename": "holesail-browser-backup-2026-02-28T12-00-00.tar.gz" }
|
|
```
|
|
|
|
**Response payload:**
|
|
```json
|
|
{ "ok": true }
|
|
```
|
|
|
|
### `deleteBackup`
|
|
|
|
Delete a backup by filename.
|
|
|
|
**Request payload:**
|
|
```json
|
|
{ "filename": "holesail-browser-backup-2026-02-28T12-00-00.tar.gz" }
|
|
```
|
|
|
|
**Response payload:**
|
|
```json
|
|
{ "ok": true }
|
|
```
|
|
|
|
---
|
|
|
|
## Implementation details
|
|
|
|
### Creating a backup
|
|
|
|
1. A staging directory is created in the backups folder
|
|
2. `state.json` is copied to `staging/storage/state.json`
|
|
3. All cert files are copied to `staging/certs/`
|
|
4. `tar czf <output.tar.gz> -C staging .` creates the archive
|
|
5. The staging directory is removed
|
|
6. Old backups exceeding the retention count are deleted (oldest first)
|
|
|
|
### Restoring a backup
|
|
|
|
1. The archive is extracted to a staging directory
|
|
2. If `storage/state.json` exists in the archive, it overwrites the current `state.json`
|
|
3. If `certs/` exists in the archive, cert files are copied to the certs directory
|
|
4. The staging directory is removed
|
|
5. The native host reloads state from disk
|
|
|
|
### Legacy archive support
|
|
|
|
Backups created by older versions of Holesail Browser used a flat layout (files at the root of the archive rather than under `storage/` and `certs/` prefixes). These are still supported for restore.
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
**Backup creation fails**
|
|
|
|
- Check that `~/.holesail-browser/holesail-browser-storage/backups/` is writable
|
|
- Check `~/.holesail-browser/holesail-browser.log` for error details
|
|
- Ensure `tar` is available on the system
|
|
|
|
**Restore doesn't take effect**
|
|
|
|
After restoring, the native host reloads state from disk. If tunnels don't reconnect, open the dashboard — the Overview page will show the current state. You may need to manually reconnect tunnels if the restored state references different `hs://` keys.
|
|
|
|
**CA mismatch after restore**
|
|
|
|
If the restored backup contains different CA certificates than what is currently installed in the OS keychain, `*.hole.sail` sites will show certificate errors. Go to dashboard → Proxy & CA → click **Install Root CA** to reinstall the correct CA, then restart Chrome.
|