# 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.