115 lines
6.0 KiB
Markdown
115 lines
6.0 KiB
Markdown
# Backups, import, restore and export
|
|
|
|
## Backup policy
|
|
|
|
Each instance supports manual backups and one V1 cron schedule using a standard five-field expression plus an IANA timezone. The UI provides common presets and a preview of upcoming runs. `retention_count` is the number of eligible automatic backups to retain.
|
|
|
|
V1 retention deletes oldest successful `scheduled` backups beyond the count. It does not silently delete manual, imported or safety backups. Failed/incomplete artifacts are cleaned by a separate short operational policy.
|
|
|
|
## Consistency strategies
|
|
|
|
The template declares backup sources and one strategy:
|
|
|
|
- `online_save`: call the module's `save_world`, wait for success, then archive declared data while running if safe.
|
|
- `stop_then_archive`: gracefully stop, archive, then restart only if it was running before the operation.
|
|
|
|
The module only requests the game to flush state. The main application owns traversal, archive, checksum, retention and metadata.
|
|
|
|
## Archive format
|
|
|
|
A DoGaMa-native backup is a `tar.zst` containing:
|
|
|
|
```text
|
|
manifest.json
|
|
data/<mount-id>/...
|
|
```
|
|
|
|
The outer database metadata stores SHA-256, size and final path. `manifest.json` stores schema version, backup ID, instance/template/game versions, origin, creation time, included mount IDs, relative paths and per-file or archive integrity information. It contains no secrets.
|
|
|
|
Write to a unique temporary file, flush, compute checksum and atomically rename. Never mark a backup available before finalization.
|
|
|
|
## Manual and scheduled workflow
|
|
|
|
1. Acquire the instance operation lock.
|
|
2. Check writable destination and conservative free-space estimate.
|
|
3. Reach a consistent game state according to the template.
|
|
4. Traverse only declared sources without following escaping links.
|
|
5. Build and finalize the archive.
|
|
6. Restore the prior running state if the workflow stopped it.
|
|
7. Persist success and apply retention.
|
|
8. Audit manual requests and notify configured failures/successes.
|
|
|
|
## Import staging
|
|
|
|
All external data first enters:
|
|
|
|
```text
|
|
/var/lib/dogama/imports/staging/<import-id>/
|
|
```
|
|
|
|
Validation enforces global and template limits for upload size, extracted size, file count, nesting and operation time. Reject absolute paths, `..`, Windows drive paths, NULs, device/FIFO/socket entries, hard links, and symlinks that escape staging. Extraction uses create-new semantics and never overwrites application files.
|
|
|
|
Supported formats are declared by the template. Importers handle data only; imported content is never executed.
|
|
|
|
## Import modes
|
|
|
|
### At instance creation
|
|
|
|
Choose `new_world` or `import`. For import, validate and preview before creating directories or a container. After the deployment plan is approved, create the instance layout and copy normalized data into declared destination mounts before first start.
|
|
|
|
### Existing instance
|
|
|
|
An authorized actor may:
|
|
|
|
- validate only;
|
|
- restore once from staging without retaining the upload;
|
|
- add the validated upload to managed backups, origin `imported`, then optionally restore.
|
|
|
|
The preview reports detected game/type, file count, expanded size, world/player hints when safely available, destination and confidence: `confirmed`, `probable`, `recognized_unknown_version` or `unrecognized`.
|
|
|
|
## Restore
|
|
|
|
1. Verify permission and recent authentication.
|
|
2. Verify archive checksum, manifest and compatibility.
|
|
3. Show overwritten destinations and compatibility confidence.
|
|
4. Create a `pre_restore` safety backup by default; disabling it is an administrator-only exceptional action.
|
|
5. Stop the instance gracefully.
|
|
6. Extract into a new validated sibling staging directory, not the live directory.
|
|
7. Swap or copy using a recoverable plan; preserve the previous data until success.
|
|
8. Apply required ownership within approved roots.
|
|
9. Start only if requested and verify readiness.
|
|
10. On failure, restore the previous data when safe; otherwise keep the server stopped and mark intervention required.
|
|
|
|
## Export
|
|
|
|
- Backup export downloads an existing integrity-verifiable archive.
|
|
- Instance configuration export is versioned YAML containing template identity, non-secret settings, resource limits, port intent, mount categories, mods and policies. Host-specific paths may be redacted or expressed as logical roots.
|
|
- Normal exports omit passwords, tokens, API credentials, encrypted blobs, internal agent metadata and session data.
|
|
- A later explicit encrypted disaster-recovery export may be designed separately; it is not V1.
|
|
|
|
## Palworld import note
|
|
|
|
The reference template recognizes dedicated-server world layouts with `Level.sav` and `Players/`. A local hosted-world import may require player identity conversion. V1 must preserve the upload, warn about this possibility and never perform undocumented silent conversion. A future game-specific data converter remains separate from the WebAssembly API adapter because modules have no filesystem access.
|
|
|
|
## Implemented foundation
|
|
|
|
The V1 backup foundation persists policies, archives and import-validation
|
|
records in SQLite. Manual backups, listing, integrity-checked export, restore
|
|
and five-field cron policy APIs are protected by the stable instance permission
|
|
identifiers. Restore and backup-policy mutation use the existing recent-session
|
|
safeguard.
|
|
|
|
Until an integration module is activated, the generic engine uses the safe
|
|
`stop_then_archive` behavior even when a template advertises `online_save`.
|
|
The later WebAssembly milestone supplies the capability call; modules will
|
|
still never traverse or archive files.
|
|
|
|
ZIP, tar, tar.gz and tar.zst imports are copied to a unique staging directory
|
|
before validation. Extraction uses create-new files and rejects absolute or
|
|
Windows paths, traversal, links, special files, excessive nesting, excessive
|
|
file counts and expanded-size overflow. A compatible validated import can be
|
|
selected in an administrator creation preview. Its normalized data is copied
|
|
through a create-new sibling directory into the template-declared destination
|
|
immediately before first container creation; validation itself never creates a
|
|
container or writes into live player data.
|