# NG Backup how-to Step by step: from first install to a tested restore. All commands run as the web user (`sudo -u www-data php occ ...`, or `docker exec -u www-data php occ ...` in All-in-One and Docker setups). Replace names in `` with your own. ## 1. Create the key and the recovery kit ``` occ backup:key:init --label="Main" --delete-delay-days=7 occ backup:key:kit --output=/var/tmp/ng_backup-kit.json occ backup:key:confirm -u --code= --confirm="Yes, I confirm" ``` - The passphrase protects the backup. Keep it somewhere other than this server. - Optional: extra passphrases for other people with `occ backup:key:slot:add --label="..."`. Any one passphrase is enough to restore. - The recovery kit (`/var/tmp/ng_backup-kit.json` above) is also required for disaster recovery. The web user writes it there; then move it off the server as root, next to the passphrase, and delete the copy in `/var/tmp`. Without the kit and a passphrase, the backup cannot be read. ## 2. Add a backup location NG Backup uses Nextcloud's External storage backends. Check what your server supports first: ``` occ backup:target:backends ``` Examples: ``` occ backup:target:add offsite amazons3 -a amazons3::accesskey -o bucket= -o key= -o secret= occ backup:target:add nas sftp -a sftp::password -o host= -o user= -o password= -o root=home occ backup:target:add local local -a null::null -o datadir=/mnt/backup ``` - **SFTP on a Hetzner Storage Box sub-account:** use `-o root=home`, not `/` (see README). - **FTP:** use a server that accepts absolute paths (for example `pure-ftpd`). - **SMB:** requires the native `smbclient` PHP extension. The CLI binary alone is not enough (see README). `backup:target:add` refuses SMB when the extension is missing. - **NFS:** not a backend of its own. Mount the export on the server and use the `local` backend with the mount point as `datadir`. Verify the location before relying on it: ``` occ backup:target:list occ backup:status ``` ## 3. Run the first backup ``` occ backup:run offsite -l first occ backup:list ``` Later runs upload only changed data. An unchanged run uploads (almost) nothing; the output shows the number of uploaded bytes, so check that value when you test incremental behaviour. Schedule `occ backup:run` from system cron (or use the Administration settings, if you prefer). ## 4. Check the backup regularly ``` occ backup:verify offsite # shallow: all blocks are present occ backup:verify offsite --deep # also downloads and decrypts every block ``` Run the deep check at least once after setting up a location, and after changing it. ## 5. Restore files and folders In the web interface, or with occ: ``` occ backup:browse offsite occ backup:restore offsite data//files/Docs --mode=new-folder occ backup:restore offsite data//files/Docs --mode=merge occ backup:restore offsite data//files/Docs --mode=replace occ backup:restore offsite config --to-directory=/var/tmp/restore-config ``` - `new-folder` (default): puts the files in "Restored " next to the original. Safest choice. - `merge`: adds missing files, keeps current ones. - `replace`: overwrites the folder. Replaced files keep their old content as a version, and removed files go to the trash. - `--to-directory`: writes raw files to a local directory (for example `config/`). ## 6. Back up and restore one user Needs the `user_migration` app. NG Backup asks before installing it: ``` occ backup:user:backup offsite occ backup:user:restore offsite users// # replace (default) occ backup:user:restore offsite users// --mode=as-backup ``` - If `user_migration` is missing, the command asks to install and enable it. For non-interactive use, add `--install-user-migration` to approve that explicitly. The command stops after the installation; run it once more. - `replace` first makes a safety export of the current account, then recreates the user under the same id. `as-backup` restores into `-bak` and leaves the original untouched. - A restore onto a server where the user does not exist works. Calendars and address books are placed in `migrated-personal` and `migrated-contacts`, not in the original names. - **Settings:** on restore, `user_migration` imports only the app settings on its own allowlist (for example calendar view and reminder settings). Other app settings of the user are skipped. NG Backup reuses `user_migration`'s importer, so this list is not extended. - Keep the last few exports per user: `occ backup:retention --user-last=3`. ## 7. Disaster recovery: restore the whole server Use a fresh Nextcloud installation of the same major version, with NG Backup installed and the same location available: ``` occ backup:key:import /path/ng_backup-kit.json --passphrase-file=/path/passphrase occ backup:target:add offsite ... # same details as on the original server occ backup:list offsite # the snapshots must be listed occ backup:restore:full offsite ``` Afterwards, check that users, files and the database are complete, and run a backup of the restored server. The restored installation keeps its own app configuration and secret. ## 8. Retention ``` occ backup:retention --last=3 --daily=7 --weekly=4 --monthly=12 occ backup:prune offsite --dry-run # show first occ backup:prune offsite # apply the policy; forgotten snapshots go to the trash first occ backup:trash # list the trash occ backup:trash:restore offsite ``` Snapshots are kept according to the policy, and their data is deleted only after the deletion delay (set with `backup:key:init --delete-delay-days`). `occ backup:prune offsite --dry-run` shows what would be removed without changing anything. ## 9. Checklist before you rely on it - [ ] Key created, passphrase stored off-server, recovery kit stored off-server - [ ] Location added; `backup:status` shows it reachable - [ ] First backup done and listed in `backup:list` - [ ] `backup:verify --deep` succeeds - [ ] One file restore tested (`new-folder`) - [ ] Disaster recovery tested on a second, fresh installation (or in a test environment)