adding more on import / export

Author: CamDavidsonPilon

static/img/user-guide/export-system-dialog.png

@@ -0,0 +1,50 @@
+---
+id: backup-system-files
+title: Back up and restore Pioreactor system files
+slug: /backup-system-files
+description: Export and import a Pioreactor’s ~/.pioreactor directory from the Inventory page.
+---
+
+Each Pioreactor keeps its configuration, calibration data, and persistent state inside `~/.pioreactor`. The Inventory page now lets you export that directory as a zip for safekeeping and import it onto the same unit when you need to restore or clone a setup.
+
+![Manage Pioreactor menu showing export/import actions](/img/user-guide/export-system-menu.png)
+
+## Exporting system files
+
+1. Open the **Inventory** page, find the Pioreactor you want to back up, and click **Manage Pioreactor → Export system files**.
+2. Confirm the export when prompted. The UI downloads a file named `<pioreactor>_dot_pioreactor.zip`.
+3. Store the archive somewhere safe. It contains every file from that unit’s `~/.pioreactor` plus a `pioreactor_export_metadata.json` descriptor (hostname, version, export time).
+
+![Export confirmation dialog in the Inventory page](/img/user-guide/export-system-dialog.png)
+
+After you confirm, the browser saves a zip named `<pioreactor>_dot_pioreactor.zip`.
+
+#### Troubleshooting
+- If export is blocked, check whether the unit has the sentinel file `~/.pioreactor/DISALLOW_UI_FILE_SYSTEM`; removing it re-enables downloads.
+- Since the export is over http, you may need to "approve" your browser to download it (check the download tab in your browser).
+- For the leader Pioreactor, it's also exporting the sqlite database. This might take a while for very large databases.
+
+## Importing system files
+
+Use imports when you need to restore a backup, duplicate a Pioreactor after replacing hardware, or bring back calibration data after re-flashing an SD card.
+
+1. On the **Inventory** page, choose **Manage Pioreactor → Import system files**.
+2. Read the warning and confirm. You will be prompted to select a `.zip` generated by the export flow.
+3. Wait for confirmation in the snackbar. The UI shows a spinner while uploading and tells you when the Pioreactor begins rebooting.
+
+![Import confirmation dialog in the Inventory page](/img/user-guide/import-system-dialog.png)
+
+Important behaviour to note:
+
+- Hostnames must match. The worker compares the archive metadata to the target unit name and rejects mismatches during import.
+- The ZIP is validated to block absolute paths, symlinks, or other unsafe entries before anything is extracted.
+- An automatic backup of the existing `~/.pioreactor` is written to `/tmp/<hostname>_dot_pioreactor_backup_<timestamp>` before any files are replaced. You can manually restore from that folder if you need to undo the import.
+- After the files are moved into place, the worker schedules a reboot so the new configuration takes effect.
+- Imports and exports share the same guard: adding `~/.pioreactor/DISALLOW_UI_FILE_SYSTEM` disables both operations until the file is removed.
+
+## Advanced notes
+
+- For scripted workflows you can hit `/api/units/$broadcast/zipped_dot_pioreactor` to download archives for every worker in one request. The aggregated ZIP namespaces each unit under a folder that matches its hostname.
+- Imports are always per-unit. If you are automating restores, loop over your hosts and POST the zip to `/api/units/<pioreactor>/import_zipped_dot_pioreactor` one at a time.
+
+With these tools you can keep regular snapshots of your cluster, move calibrations between identical builds, or roll back quickly after testing changes.