diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 60254cb..11cdb41 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -138,3 +138,7 @@ jobs: run: tests/integration/full-restore-roundtrip.sh 35-apache mysql to-sqlite - name: Full restore of a SQLite backup onto PostgreSQL run: tests/integration/full-restore-roundtrip.sh 35-apache sqlite to-pgsql + - name: Full restore with a damaged database dump (--salvage) + run: tests/integration/full-restore-roundtrip.sh 35-apache sqlite salvage + - name: Full restore with a damaged and a missing pack (--salvage) + run: tests/integration/full-restore-roundtrip.sh 35-apache sqlite salvage-files diff --git a/CHANGELOG.md b/CHANGELOG.md index f162337..af889fc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,51 @@ Each heading starts with that ``, once: the app store shows a release t whose heading starts with its `x.y.z` and ignores anything after it, so `## [1.0.0-rc.6]` would be shown under 1.0.0. The git tag of a release candidate goes after the date. +## [1.0.2] - 2026-11-06 + +### Added +- A warning on the admin page and in `occ backup:status` when background jobs do not run on a + system cron, or the cron stopped, with a link to how to set one up. Backups, also the scheduled + ones, need it (#13). +- Without a working system cron, a backup started with "Back up now" moves on while the NG Backup + page stays open (#13). +- `--salvage` for `occ backup:restore` and `occ backup:restore:full`: restore whatever can be + read when a backup is damaged. Files that cannot be read or decrypted are left out and listed, + and the command exits with code 2. When the database cannot be restored, `backup:restore:full` + leaves the fresh database as it is and puts the data directory and config of the backup in + `ngb-salvage-` in the data directory, to put back by hand. +- The trash of restore points has a tab of its own, "Bin", instead of being shown below the + backups. + +### Changed +- A backup in its database phase shows how far it is, for example "running (db: 47/183 tables)", + and one that has not moved for 15 minutes says "waiting for background jobs" with when it last + took a step. Before, it only said "running (db)", which looked the same as being stuck (#13). +- Full restores from S3 read the packs ahead, eight ranges at a time, as restores over SFTP do + since 1.0.0-rc.4. Over SMB the packs are read in 8 MiB reads instead of 1 MiB: over a line with + a 130 ms round trip, reading was four times faster in a test (18 instead of 4.5 MiB/s). +- Over SMB the index files, which a new server reads in `backup:target:add`, take fewer round + trips: from Canada to a Hetzner Storage Box (130 ms), 0.66 instead of 1.05 s per file, so about + 5 instead of 8 hours for the 27,000 index files of a 1 TB repository. +- `occ backup:restore:full` that runs again after it stopped (`--force`) goes on where it was: data + files already in place with the size and modification time of the backup are left, and only + the rest is read from the location. Before, a stopped restore of 1 TB started over. + +### Fixed +- A full restore over SMB could hang at 100% CPU when the connection to the server dropped: a + failed read was counted as data. It is now read again over a new connection. Found in a + disaster recovery test of 1 TB from Canada to a Hetzner Storage Box, after 392 GiB. +- The read-ahead folder of a restore that was killed while it wrote is removed by the next run; + it kept one file of up to 8 MiB. +- `occ backup:target:add` only estimates the time left for reading the index once enough of it + is in. The first file also carries the time to connect, which made it say "about 642 min left" + for something done within a minute. +- A restore that stops because a file is gone from the location now points at `--salvage`, as it + already did for damaged data. + +### Known issues +- Empty folders are not backed up or restored; to be fixed in 1.0.3 (#27). + ## [1.0.1] - 2026-11-01 Fixes for what was reported after 1.0.0 (#22, #24) and small improvements. Nothing changes in diff --git a/PLAN.md b/PLAN.md index c3fd445..1b0028c 100644 --- a/PLAN.md +++ b/PLAN.md @@ -392,9 +392,59 @@ in README "Known limitations": gids (SFTP, Storage Box) → rc4 uitbrengen en om tests vragen → zelf een volledige DR van een productie-instantie van ~250 GB via S3 en via SMB. Drie volledige DR-restores vóór 1.0.0. Problemen of meldingen van gebruikers: rc5. -- **1.0.1** (klaar voor release 2026-11-01): alleen de kleine punten (besluit 2026-10-30): 4, 6–13. Punten 1, 2 en 5 gaan naar +- **1.0.2** (plan akkoord 2026-11-04): punten 1, 2 en 5 hieronder, de Bin, nieuwe screenshots en + het polish-punt over de schatting van `target:add`. Besluiten 2026-11-04: + - `--salvage` haalt ook bij een kapotte database terug wat kan: bestanden zijn per gebruiker + gescheiden en het waardevolst. Kan de database niet terug (dump onleesbaar, of past niet op + deze installatie), dan blijft de verse database staan en gaan data en config van de backup + naar `/ngb-salvage-/`; vanaf daar is het handwerk. Exitcode 2. + - De DR-test met een backup mét tabelstructuur, zonder `--skip-missing-tables` (punt 3), is + nog niet gedaan en wordt ingepland vóór de release van 1.0.2. Ingepland (2026-11-04): een + verse snapshot van nc01 (gemaakt met 1.0.1, dus met tabelstructuur) volgens de DR-gids + terugzetten op VM 980 met de 1.0.2-build, over **SMB** (Storage Box; besluit 2026-11-04: + SMB in plaats van SFTP, zodat de DR-test de nieuwe SMB-leescode op echte schaal en over de + echte lijn vanuit Canada test; vorige meting 2,6 MiB/s, verwachting ~1 dag voor 1 TB), zonder + `--skip-missing-tables`; daarna `--salvage` op een deel van de bestanden (moet hetzelfde + resultaat geven, exitcode 0). Uitvoeren met Dillard, die VM 980 klaarzet; deze week, vóór + de release. Screenshots akkoord (2026-11-04). + **DR-test 1.0.2 over SMB (VM 980, snapshot a86271ed van nc01, 983 GiB, gestart 2026-11-04):** + index lezen 8 uur (~1 bestand/s; daarna versneld naar 0,66 s/bestand, gemeten vanaf VM 980); + restore zonder opties (geen `--install-apps`, geen `--skip-missing-tables`) liep ~12 MiB/s + (SFTP eerder 2,8-7,6; SMB vóór 1.0.2 2,6). Na 392 GiB viel de SMB-verbinding weg en bleef de + restore op 100% CPU hangen: de smbclient-extensie geeft bij een mislukte read een string met + lengte -1. Opgelost (controle + nieuwe verbinding), plus hervatten: `--force` laat bestanden met + dezelfde grootte en mtime staan. Hervat 2026-11-05 07:21 UTC na `maintenance:mode --off` + volgens de gids; binnen 10 min voorbij de 392 GiB. SMB op sub5 na de test weer uitzetten. + **Resultaat (klaar 2026-11-06 02:11 UTC, nazorg 02:27):** hervatte run 18 u 50 min, exit 0, 150.755 + bestanden; 7-13 MiB/s (langzamer vanaf ~18 uur Duitse tijd, oorzaak niet vastgesteld). Vergeleken + met nc01: 150.467 van 150.758 bestanden gelijk in grootte en mtime, 397 op hash zonder verschil; + gebruikers, agenda's, contacten, shares en Deck gelijk; bestanden, agenda en contacten via WebDAV + getest als gebruiker. `backup:restore --salvage` op 16.904 bestanden: exit 0, geen verschil. Niet + vastgesteld: de 50.080 "updated" bij `files:scan`. Zonder `--install-apps` 51 van de 81 apps aan. + VM's 980-982 en de sim-backups op OVH en sub6 opgeruimd. + **Naar 1.0.3 (besluit 2026-11-06):** lege mappen komen niet terug (3.982 op nc01, 2.076 daarvan in + `files`, verklaart vrijwel zeker de 2.370 "removed" bij `files:scan`). De backup legt alleen + bestanden vast (`walk()`), dus oudere snapshots hebben ze niet. Voor een DR acceptabel, wel + fixen; issue #27. Daarna kleine volledige simulaties; een DR van 1 TB is hiervoor niet nodig. + **Salvage vóór de release getest (besluit 2026-11-06):** nieuwe modus `salvage-files` in + `full-restore-roundtrip.sh`, ook in CI: één pack beschadigd en één weg. Eerst stopt de restore, + daarna `--salvage --force` volgens de gids. Vond één fout: bij een ontbrekend bestand wees de + melding niet naar `--salvage` (opgelost). + Stand 2026-11-04 (`polish`, gepusht): cron-waarschuwing + tick vanaf de pagina + + voortgang van de db-fase; `--salvage` voor `backup:restore` en `backup:restore:full`; S3 + vooruitlezen (8 ranges tegelijk, met `SaveAs` naar de spool); SMB in leesacties van 8 MiB + (gemeten met netem, 130 ms RTT: 4,5 → 18 MiB/s per leesactie; een volledige restore over SMB + met vertraging is nog niet gemeten); Bin-tabblad; schatting `target:add`; nieuwe screenshots + (1–3 vervangen, 4-bin erbij; in `info.xml` bij de release naar tag v1.0.2 laten wijzen en + 4-bin toevoegen). Getest: unit (208), psalm, integratie NC35 sqlite/pgsql, S3/SFTP/FTP/SMB, + volledige restore met `--salvage`. Nog te doen: DR-test, release. +- **1.0.1** (uitgebracht 2026-11-01): alleen de kleine punten (besluit 2026-10-30): 4, 6–13. Punten 1, 2 en 5 gaan naar 1.0.2 (README-roadmap aangepast); punt 3 is een test, ingepland voor de week van 2 november, - niet aangekondigd en los van de release. + niet aangekondigd en los van de release. Voor 1.0.2 ook: nieuwe screenshots (het labelveld bij + "Back up now" en het tabblad Docs staan er nog niet op; besluit 2026-11-01), en de prullenbak + van herstelpunten naar een eigen tabblad "Bin" naast "Backup and restore", "Settings" en "Docs": + onder de lijst met herstelpunten vervuilt hij het scherm (vooral met wat het bewaarbeleid erin + zet; besluit 2026-11-01). Nieuwe screenshots daarna, zodat de Bin er ook op staat. 1. **Naar 1.0.2.** (Naar rc4: herstelsnelheid over SFTP.) S3 leest al 16 tegelijk bij index en tree, maar een restore leest de packs nog één voor één: ook vooruitlezen via de S3-client. 2. **Naar 1.0.2.** Achtergrondjobs zonder systeem-cron (issue #13; besluit 2026-10-19). De PR die dit diff --git a/README.md b/README.md index c94dbbb..8db57de 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ installations and hosted Nextcloud. (Choosing SMB as a storage backend is the on see "Storage backend experiences" below — that requirement comes from files_external, not from ng_backup, and applies to any Nextcloud app that writes to an SMB share.) -**Status: 1.0.1, stable.** Disaster recovery has been tested on real installations (see "Tested +**Status: 1.0.2, stable.** Disaster recovery has been tested on real installations (see "Tested disaster recoveries" below). See "Known limitations" below, `PLAN.md` for the design and `docs/HOWTO.md` for a step-by-step guide from setup to a tested restore. Server lost? See `docs/DISASTER-RECOVERY.md`. @@ -42,7 +42,8 @@ Need help restoring a backup after a crash? Ensembia offers paid restore assista background job, so a backup only moves forward when that job runs. Choosing "Cron" under **Administration settings → Basic settings → Background jobs** is not enough on its own: it tells Nextcloud that the system will call it, so you also need a cron line that does. Without - it a backup stays at "running (db)", and so does one started with "Back up now". + it scheduled backups do not run; the admin page and `occ backup:status` warn about it, and a + backup started with "Back up now" only moves on while the NG Backup page stays open. `occ backup:run` in a terminal works without cron (it runs in the foreground). - Regular server: `crontab -u www-data -e` and add `*/5 * * * * php -f /var/www/nextcloud/cron.php` (your Nextcloud path). @@ -167,6 +168,7 @@ Full restores onto a fresh server, following only [the guide](docs/DISASTER-RECO | Backup | Location | Database | Result | |---|---|---|---| | Production, about 1 TB, 150,000 files (Nextcloud All-in-One) | Hetzner Storage Box (SFTP), Germany → Canada | PostgreSQL → PostgreSQL | 150,622 files restored in about 25 h (13-14 MiB/s), sample identical | +| The same, 1.0.2 | Hetzner Storage Box (SMB), Germany → Canada | PostgreSQL → PostgreSQL | 150,755 files restored in about 29 h (7-13 MiB/s), going on after a lost connection; sample identical, empty folders not restored ([#27](https://github.com/dillardblom/ng_backup/issues/27)) | | 138 GB simulation: 20 users, calendars, contacts, mail, shares, team folders with an ACL, versions, trash | OVH S3, Warsaw → Canada | MariaDB → PostgreSQL | all 15,772 files and every database count identical | | The same | OVH S3 | MariaDB → MariaDB | all 15,772 files and every database count identical | | The same | Hetzner Storage Box (SMB), Germany → Canada | MariaDB → SQLite | all 15,772 files and every database count identical (27.6 h, about 1.5 MB/s) | @@ -263,14 +265,9 @@ What is planned, without dates. Ideas and votes are welcome in the [issues](https://github.com/dillardblom/ng_backup/issues); if something you need is listed here, a 👍 on its issue helps decide what comes first. -**1.0.2** -- A warning on the admin page and in `occ backup:status` when background jobs do not run on a - system cron, with how to set one up. Without cron, a backup started with "Back up now" moves on - while the NG Backup page is open, and the database phase of a backup shows its progress - ([#13](https://github.com/dillardblom/ng_backup/issues/13)). -- Faster full restores from S3 and SMB, reading ahead as restores over SFTP do since 1.0.0-rc.4. -- `--salvage` for a restore: restore what can be read, skip a file that cannot, and list those at - the end instead of stopping. +**1.0.3** +- Empty folders in the backup and the restore + ([#27](https://github.com/dillardblom/ng_backup/issues/27)). **1.1.0** - Restore without the recovery kit: the backup key from the location itself, opened with one of @@ -296,6 +293,9 @@ a 👍 on its issue helps decide what comes first. On the backlog; know them before you rely on NG Backup: +- **Empty folders do not come back.** A backup only records files, so a folder without files is + not restored. To be fixed in 1.0.3 + ([#27](https://github.com/dillardblom/ng_backup/issues/27)). - **Only the data directory is backed up.** Object storage as primary storage (`objectstore` in `config.php`) is not supported: a backup refuses to start there. Folders mounted through the External storage app are not in the data directory and are **not included**, without a warning. diff --git a/appinfo/info.xml b/appinfo/info.xml index 07ff03f..090d5a1 100644 --- a/appinfo/info.xml +++ b/appinfo/info.xml @@ -40,12 +40,12 @@ NG Backup needs Nextcloud's background jobs on system cron (a real cron line, no Read "Known limitations" in the README before you rely on it, and test a restore. Feedback is very welcome: use the "Share your experience" link on the admin page. -If you like NG Backup, don't forget to give the app a star in the app store and the -[repository](https://github.com/dillardblom/ng_backup) a star on GitHub! +**If you like NG Backup, don't forget to give the app a star in the app store and the +[repository](https://github.com/dillardblom/ng_backup) a star on GitHub!** Developed and sponsored by [Ensembia](https://www.ensembia.com). We can offer (paid) assistance if you need help with restoring a backup after a crash.]]> - 1.0.1 + 1.0.2 agpl Dillard Blom NgBackup @@ -56,9 +56,10 @@ you need help with restoring a backup after a crash.]]> https://github.com/dillardblom/ng_backup https://github.com/dillardblom/ng_backup/issues https://github.com/dillardblom/ng_backup - https://raw.githubusercontent.com/dillardblom/ng_backup/v1.0.1/screenshots/1-backups.png - https://raw.githubusercontent.com/dillardblom/ng_backup/v1.0.1/screenshots/2-restore.png - https://raw.githubusercontent.com/dillardblom/ng_backup/v1.0.1/screenshots/3-settings.png + https://raw.githubusercontent.com/dillardblom/ng_backup/v1.0.2/screenshots/1-backups.png + https://raw.githubusercontent.com/dillardblom/ng_backup/v1.0.2/screenshots/2-restore.png + https://raw.githubusercontent.com/dillardblom/ng_backup/v1.0.2/screenshots/3-settings.png + https://raw.githubusercontent.com/dillardblom/ng_backup/v1.0.2/screenshots/4-bin.png sodium diff --git a/appinfo/routes.php b/appinfo/routes.php index 10e7a5d..b058d68 100644 --- a/appinfo/routes.php +++ b/appinfo/routes.php @@ -24,6 +24,7 @@ return [ ['name' => 'AdminApi#testTarget', 'url' => '/api/targets/{id}/test', 'verb' => 'POST'], ['name' => 'AdminApi#setTargetLimit', 'url' => '/api/targets/{id}/limit', 'verb' => 'PUT'], ['name' => 'AdminApi#startBackup', 'url' => '/api/backups', 'verb' => 'POST'], + ['name' => 'AdminApi#tick', 'url' => '/api/tick', 'verb' => 'POST'], ['name' => 'AdminApi#setSchedule', 'url' => '/api/schedule', 'verb' => 'PUT'], ['name' => 'AdminApi#snapshots', 'url' => '/api/targets/{targetId}/snapshots', 'verb' => 'GET'], ['name' => 'AdminApi#browse', 'url' => '/api/targets/{targetId}/snapshots/{snapshotId}/browse', 'verb' => 'GET'], diff --git a/docs/DISASTER-RECOVERY.md b/docs/DISASTER-RECOVERY.md index 86e35fc..06a238f 100644 --- a/docs/DISASTER-RECOVERY.md +++ b/docs/DISASTER-RECOVERY.md @@ -103,12 +103,31 @@ mode on yourself before, it stays on: switch it off with `occ maintenance:mode - If it stops halfway, maintenance mode stays on (the instance may be partly restored). Fix the cause, then switch maintenance mode off and run the restore again with `--force`, in one line (the message prints it): `occ maintenance:mode --off && occ backup:restore:full --force`. -Leave out `--install-apps` this time, so that the instance is open only for the seconds until the +It goes on where it stopped: data files that are already in place with the size and modification +time of the backup are left, so only the rest comes from the location again (since 1.0.2; before, +it started over). The database is restored again in full, which takes minutes. Leave out `--install-apps` this time, so that the instance is open only for the seconds until the restore has switched maintenance mode on again; apps the first run could not install are listed at the end of the restore, install those afterwards. If occ then says that Nextcloud or one of the apps requires an upgrade, the database is already the old server's: run `occ upgrade` first, then the same command with `--force`. +**If the backup itself is damaged** (the restore stops with "Decryption failed", "Blob +verification failed" or a file that is missing on the location), try an older restore point +first. If none is better, `--salvage` restores whatever can be read: + + occ backup:restore:full offsite --install-apps --salvage + +- Files that cannot be read are left out and listed at the end; everything else is restored. +- If the database cannot be restored (its dump is damaged, or it does not fit this + installation), the database stays as the fresh installation made it, and the data directory + and config of the backup go to a folder of their own in the data directory, + `ngb-salvage-`. Each user's files are in `data//files` there: create the users + again and copy their files back by hand (then `occ files:scan --all`). Calendars, contacts and + shares are in the database and cannot be recovered this way. + +The command then ends with exit code 2 instead of 0. The same option exists for +`occ backup:restore`, to restore single folders. + **9. After the restore.** These worked in our tests: occ upgrade @@ -121,6 +140,9 @@ the old server's: run `occ upgrade` first, then the same command with `--force`. - From Nextcloud All-in-One to a regular server: also check the cache settings (`memcache.*`, `redis`), which point at AIO's containers. - Log in, open a few files, a calendar and a contact. +- Empty folders do not come back: a backup only records files (to be fixed in 1.0.3, see + [issue #27](https://github.com/dillardblom/ng_backup/issues/27)). `occ files:scan` then removes + them from the file cache, so it reports them as removed. - Start background jobs again (cron), as in step 2 in reverse. **10. Point your domain at the new server** and check that clients reconnect. diff --git a/lib/Backend/StorageBackend.php b/lib/Backend/StorageBackend.php index 984ecc6..7126f15 100644 --- a/lib/Backend/StorageBackend.php +++ b/lib/Backend/StorageBackend.php @@ -23,6 +23,11 @@ final class StorageBackend implements IBackend, IReadsAhead { private bool $s3Reads; /** S3 requests in flight at once for getMany() and getRanges(). */ public const S3_CONCURRENCY = 16; + /** + * Ranges readAhead() fetches at once over S3, each straight into a file in the spool (a range + * is at most ReadAheadPlan::MAX_RANGE: the spool holds at most this many times that). + */ + public const S3_READ_AHEAD = 8; /** Most ranges, and bytes, getRanges() holds in memory at once. */ private const RANGES_LOT = 64; private const RANGES_LOT_BYTES = 64 * 1048576; @@ -128,7 +133,7 @@ final class StorageBackend implements IBackend, IReadsAhead { /** * Over SFTP and S3 several at a time (SftpReadStream::readMany(), s3Fetch()); elsewhere one - * after the other. + * after the other, over SMB in fewer round trips (smbWhole()). */ public function getMany(array $paths): \Generator { $size = $this->s3Reads ? 16 * self::S3_CONCURRENCY : 8 * SftpReadStream::BATCH; @@ -144,7 +149,8 @@ final class StorageBackend implements IBackend, IReadsAhead { $fast = $fast === null ? null : array_combine($chunk, array_map(fn (string $a): ?string => $fast[$a] ?? null, $abs)); } foreach ($chunk as $path) { - $data = $fast[$path] ?? null; + // over SMB in fewer round trips, one after the other (smbWhole()) + $data = $fast[$path] ?? $this->smbWhole($this->abs($path)); if ($data === null) { // not read in the batch (or no batches here): the usual way, which also // reports a missing file as such @@ -211,15 +217,11 @@ final class StorageBackend implements IBackend, IReadsAhead { */ private function s3Fetch(array $requests): ?array { try { - /** @psalm-suppress UndefinedMethod, UndefinedThisPropertyFetch */ - [$client, $bucket, $sse] = (function (): array { - $sse = method_exists($this, 'getServerSideEncryptionParameters') ? $this->getServerSideEncryptionParameters() - : (method_exists($this, 'getSSECParameters') ? $this->getSSECParameters() : []); - return [$this->getConnection(), $this->getBucket(), $sse]; - })->call($this->storage); - if (!$client instanceof \Aws\S3\S3Client || !is_string($bucket)) { + $s3 = $this->s3Client(); + if ($s3 === null) { return null; } + [$client, $bucket, $sse] = $s3; $results = []; $keys = array_keys($requests); // the pool numbers results 0, 1, ...: mapped back below $commands = (function () use ($requests, $client, $bucket, $sse): \Generator { @@ -245,16 +247,111 @@ final class StorageBackend implements IBackend, IReadsAhead { } } + /** + * files_external's S3 client, bucket and server-side encryption parameters; null when the + * storage is not as expected. + * + * @return array{0: \Aws\S3\S3Client, 1: string, 2: array}|null + * @psalm-suppress UndefinedClass the AWS SDK comes with Nextcloud, not with this app + */ + private function s3Client(): ?array { + /** @psalm-suppress UndefinedMethod, UndefinedThisPropertyFetch */ + [$client, $bucket, $sse] = (function (): array { + $sse = method_exists($this, 'getServerSideEncryptionParameters') ? $this->getServerSideEncryptionParameters() + : (method_exists($this, 'getSSECParameters') ? $this->getSSECParameters() : []); + return [$this->getConnection(), $this->getBucket(), $sse]; + })->call($this->storage); + return $client instanceof \Aws\S3\S3Client && is_string($bucket) ? [$client, $bucket, is_array($sse) ? $sse : []] : null; + } + + /** + * readAhead() over S3: S3_READ_AHEAD ranges at a time, fetched together straight into files in + * the spool, then handed out in order. One request per range instead of one per blob (with a + * new HTTPS connection each), and several at once: a restore is no longer bound by the round + * trip. A range that could not be fetched is handed out as null (the caller reads it the + * usual way, which reports why). + * + * @param list $ranges + * @return \Generator|null + * @psalm-suppress UndefinedClass the AWS SDK comes with Nextcloud, not with this app + */ + private function s3ReadAhead(array $ranges, string $spool): ?\Generator { + // before anything is fetched: an invalid path throws + $keys = array_map(fn (array $r): string => trim($this->abs($r[0]), '/'), $ranges); + try { + $s3 = $this->s3Client(); + } catch (\Throwable) { + $s3 = null; + } + if ($s3 === null) { + return null; + } + [$client, $bucket, $sse] = $s3; + $this->idleCheck(); + return (static function () use ($client, $bucket, $sse, $ranges, $keys, $spool): \Generator { + $prefix = rtrim($spool, '/') . '/s3-' . bin2hex(random_bytes(4)) . '-'; + foreach (array_chunk(array_keys($ranges), self::S3_READ_AHEAD) as $lot) { + $files = []; + $commands = []; + foreach ($lot as $n => $i) { + $files[$i] = $prefix . $i; + $commands[$n] = $client->getCommand('GetObject', ['Bucket' => $bucket, 'Key' => $keys[$i], + 'Range' => 'bytes=' . $ranges[$i][1] . '-' . ($ranges[$i][1] + $ranges[$i][2] - 1), 'SaveAs' => $files[$i]] + $sse); + } + $fetched = []; + try { + (new \Aws\CommandPool($client, $commands, [ + 'concurrency' => self::S3_READ_AHEAD, + 'fulfilled' => function (mixed $result, int $n) use (&$fetched, $lot): void { + $fetched[$lot[$n]] = true; + }, + 'rejected' => static function (): void { + }, + ]))->promise()->wait(); + } catch (\Throwable) { + // what was not fetched is read the usual way + } + try { + foreach ($lot as $i) { + clearstatcache(true, $files[$i]); + $fh = isset($fetched[$i]) && @filesize($files[$i]) === $ranges[$i][2] ? @fopen($files[$i], 'rb') : false; + @unlink($files[$i]); // the open stream keeps its data + yield $i => is_resource($fh) ? $fh : null; + if (is_resource($fh)) { + fclose($fh); + } + } + } finally { + // stopped halfway: the rest of this lot + foreach ($files as $file) { + @unlink($file); + } + } + } + })(); + } + /** * Over SFTP: SftpRangeFetcher, on readAheadConnections new connections of its own (built with the - * reconnect function), so the storage's connection stays free for other requests. Elsewhere - * not (yet): null. + * reconnect function), so the storage's connection stays free for other requests. Over S3: + * S3_READ_AHEAD ranges at a time through the S3 client (s3ReadAhead()). Elsewhere not (yet): + * null. */ public function canReadAhead(): bool { - return $this->sftpReads && $this->reconnect !== null; + return ($this->sftpReads && $this->reconnect !== null) || $this->s3Reads || $this->smbNative(); + } + + private function smbNative(): bool { + return $this->storage instanceof \OCA\Files_External\Lib\Storage\SMB && extension_loaded('smbclient'); } public function readAhead(array $ranges, string $spool): ?\Generator { + if ($ranges !== [] && $this->s3Reads) { + return $this->s3ReadAhead($ranges, $spool); + } + if ($ranges !== [] && $this->smbNative()) { + return $this->smbReadAhead($ranges, $spool); + } $reconnect = $this->reconnect; if (!$this->sftpReads || $reconnect === null || $ranges === []) { return null; @@ -306,6 +403,18 @@ final class StorageBackend implements IBackend, IReadsAhead { } private function readRange(string $path, int $offset, int $length): string { + try { + $chunks = $this->smbChunks($this->abs($path), $offset, $length); + if ($chunks !== null) { + $data = implode('', iterator_to_array($chunks, false)); + if (strlen($data) === $length) { + return $data; + } + } + } catch (\Throwable) { + // read the usual way below, which reports what is wrong, over a new connection + $this->smbReconnect(); + } $fh = $this->get($path); try { if (fseek($fh, $offset) !== 0) { @@ -418,6 +527,218 @@ final class StorageBackend implements IBackend, IReadsAhead { * * @return list|null */ + /** + * Bytes per read over SMB (smbChunks()). libsmbclient keeps a large read in flight as many + * requests at once; icewind's stream reads 1 MiB at a time. Over a line with a 130 ms round + * trip: 4.5 MiB/s in 1 MiB reads, 18 MiB/s in 8 MiB reads (measured 2026-11-04, Samba in a + * container behind netem). Without latency it makes no difference. + */ + public const SMB_READ = 8 * 1048576; + + /** + * $length bytes of $abs from $offset over SMB, SMB_READ at a time straight through the native + * extension's state of files_external's SMB storage. Null when the storage is not SMB through + * the extension, or its internals are not as expected (the usual way reads it then). The + * generator throws when a read fails. + * + * @return \Generator|null + * @psalm-suppress UndefinedClass icewind/smb comes with files_external, not with this app + */ + private function smbChunks(string $abs, int $offset, int $length): ?\Generator { + $handle = $this->smbHandle($abs); + if ($handle === null) { + return null; + } + [$state, $url] = $handle; + /** @psalm-suppress MixedMethodCall the state is icewind's NativeState */ + return (static function () use ($state, $url, $offset, $length): \Generator { + $fh = $state->open($url, 'r'); + try { + $state->lseek($fh, $offset, SEEK_SET, $url); + for ($got = 0; $got < $length;) { + $want = min(self::SMB_READ, $length - $got); + $chunk = self::smbRead($state, $fh, $want, $url); + if ($chunk === '') { + throw new BackendException('Short read in ' . $url); + } + $got += strlen($chunk); + yield $chunk; + } + } finally { + $state->close($fh, $url); + } + })(); + } + + /** + * A whole (small) file over SMB in four round trips: open, read, read up to the end, close. + * files_external's fopen() first checks that the file exists (a stat with its attributes) and + * icewind's stream reads 1 MiB at a time: about 7 round trips, 1 s per index file from Canada + * to the Storage Box (130 ms), so ~8 h for the 27,000 index files of a 1 TB repository. Null + * when the storage is not SMB through the extension or anything fails: the usual way then + * reads the file and reports a missing one as such. + * + * @psalm-suppress UndefinedClass icewind/smb comes with files_external, not with this app + */ + private function smbWhole(string $abs): ?string { + $handle = $this->smbHandle($abs); + if ($handle === null) { + return null; + } + [$state, $url] = $handle; + try { + /** @psalm-suppress MixedMethodCall the state is icewind's NativeState */ + $fh = $state->open($url, 'r'); + } catch (\Throwable) { + return null; + } + $data = ''; + try { + do { + $chunk = self::smbRead($state, $fh, self::SMB_READ, $url); + $data .= $chunk; + } while ($chunk !== ''); + } catch (\Throwable) { + $data = null; + } + try { + /** @psalm-suppress MixedMethodCall */ + $state->close($fh, $url); + } catch (\Throwable) { + } + if ($data === null) { + $this->smbReconnect(); // a read failed: the usual way reads it over a new connection + } + return $data; + } + + /** + * One read of at most $bytes through the native state, checked. When libsmbclient fails a read + * (seen when the connection to the server dropped during a long restore), the smbclient + * extension does not return false but a string whose length is -1, because it stores + * smbc_read()'s -1 in an unsigned length; icewind passes it on. Counting that as data made + * the read loop go backwards forever at 100% CPU (DR test 2026-11-05, after 392 GiB). + * + * @param resource $fh + * @psalm-suppress MixedMethodCall, MixedArgument the state is icewind's NativeState + */ + private static function smbRead(object $state, $fh, int $bytes, string $url): string { + $chunk = $state->read($fh, $bytes, $url); + $n = is_string($chunk) ? strlen($chunk) : -1; + if ($n < 0 || $n > $bytes) { + throw new BackendException('Read failed in ' . $url); + } + return $chunk; + } + + /** + * After a failed read: drop icewind's connection state, so the next read (the usual way, or + * the next range) connects again instead of failing on a connection that is gone. + * + * @psalm-suppress UndefinedClass icewind/smb comes with files_external, not with this app + */ + private function smbReconnect(): void { + if (!$this->storage instanceof \OCA\Files_External\Lib\Storage\SMB) { + return; + } + try { + (function (): void { + /** @psalm-suppress UndefinedThisPropertyFetch */ + $share = $this->share; + if ($share instanceof \Icewind\SMB\Native\NativeShare) { + (function (): void { + /** @psalm-suppress UndefinedThisPropertyAssignment */ + $this->state = null; + })->call($share); + } + })->call($this->storage); + } catch (\Throwable) { + } + } + + /** + * icewind's NativeState and the smb:// URL of $abs behind files_external's SMB storage, reached + * through bound closures; null when the storage is not SMB through the native extension or its + * internals are not as expected. + * + * @return array{0: object, 1: string}|null + * @psalm-suppress UndefinedClass icewind/smb comes with files_external, not with this app + */ + private function smbHandle(string $abs): ?array { + if (!$this->storage instanceof \OCA\Files_External\Lib\Storage\SMB || !extension_loaded('smbclient')) { + return null; + } + try { + /** @var array{0: object, 1: string}|null $handle */ + $handle = (function (string $path): ?array { + /** @psalm-suppress UndefinedThisPropertyFetch */ + $share = $this->share; + if (!$share instanceof \Icewind\SMB\Native\NativeShare) { + return null; + } + /** @psalm-suppress UndefinedMethod */ + $sharePath = ltrim($this->buildPath($path), '/'); + /** @psalm-suppress UndefinedMethod */ + return (fn (string $p): array => [$this->getState(), $this->buildUrl($p)])->call($share, $sharePath); + })->call($this->storage, $abs); + } catch (\Throwable) { + return null; + } + return $handle; + } + + /** + * readAhead() over SMB: one range after the other, each in SMB_READ reads into a file in the + * spool. Not several at once (PHP cannot wait on more than one libsmbclient call), but whole + * ranges of up to ReadAheadPlan::MAX_RANGE in large reads instead of blob by blob in 1 MiB + * reads. A range that cannot be read is handed out as null. + * + * @param list $ranges + * @return \Generator + */ + private function smbReadAhead(array $ranges, string $spool): \Generator { + // before anything is read: an invalid path throws + $abs = array_map(fn (array $r): array => [$this->abs($r[0]), $r[1], $r[2]], $ranges); + return (function () use ($abs, $spool): \Generator { + $file = rtrim($spool, '/') . '/smb-' . bin2hex(random_bytes(4)); + try { + foreach ($abs as $i => [$path, $offset, $length]) { + $fh = null; + $out = false; + try { + $chunks = $this->smbChunks($path, $offset, $length); + $out = $chunks === null ? false : fopen($file, 'w+b'); + if ($chunks !== null && $out !== false) { + foreach ($chunks as $chunk) { + if (fwrite($out, $chunk) !== strlen($chunk)) { + throw new BackendException('Cannot write to the spool'); + } + } + $fh = ftell($out) === $length && rewind($out) ? $out : null; + if ($fh === null) { + fclose($out); + } + } + } catch (\Throwable) { + if (is_resource($out)) { + fclose($out); + } + $fh = null; // read the usual way, which reports why, over a new connection + $this->smbReconnect(); + } finally { + @unlink($file); // an open stream keeps its data + } + yield $i => $fh; + if (is_resource($fh)) { + fclose($fh); + } + } + } finally { + @unlink($file); + } + })(); + } + private function smbNames(string $abs): ?array { if (!$this->storage instanceof \OCA\Files_External\Lib\Storage\SMB) { return null; diff --git a/lib/Command/Restore.php b/lib/Command/Restore.php index 6ae877b..f22cd19 100644 --- a/lib/Command/Restore.php +++ b/lib/Command/Restore.php @@ -31,6 +31,7 @@ final class Restore extends Command { ->addArgument('path', InputArgument::REQUIRED, 'Path in the snapshot (see backup:browse)') ->addOption('mode', 'm', InputOption::VALUE_REQUIRED, 'new-folder, merge or replace (user files)', RestoreService::MODE_NEW_FOLDER) ->addOption('to-directory', 'd', InputOption::VALUE_REQUIRED, 'Write to this local directory instead (any path, raw files)') + ->addOption('salvage', null, InputOption::VALUE_NONE, 'Leave out a file that cannot be read or decrypted, list it at the end and go on, instead of stopping') ->setHelp(<<<'HELP' User files (data//files/...) are restored through Nextcloud, so versions, trash and the file cache stay correct. Modes: @@ -42,30 +43,59 @@ Examples: occ backup:restore offsite 537bf7e9... data/alice/files/Documents occ backup:restore offsite 537bf7e9... data/alice/files/Documents/plan.odt --mode=merge occ backup:restore offsite 537bf7e9... config --to-directory=/root/restored-config +With --salvage, a file whose data on the location is damaged or missing is left out and listed +at the end; everything else is restored. The command then exits with code 2. HELP); } protected function execute(InputInterface $input, OutputInterface $output): int { + $skipped = $input->getOption('salvage') ? [] : null; try { $target = $this->targets->get($input->getArgument('target')); $snapshot = $input->getArgument('snapshot'); $path = trim((string)$input->getArgument('path'), '/'); // CLI convenience; the service itself only accepts canonical paths if ($dir = $input->getOption('to-directory')) { - $n = $this->restore->restoreToDirectory($target, $snapshot, $path, $dir); + $n = $this->restore->restoreToDirectory($target, $snapshot, $path, $dir, false, null, $skipped); $output->writeln("Restored $n files to $dir."); - return 0; + return self::reportSkipped($skipped, $output); } $r = $this->restore->restoreUserFiles($target, $snapshot, $path, (string)$input->getOption('mode'), function (int $done, int $total, string $name) use ($output) { if ($output->isVerbose() || $done === $total || $done % 100 === 0) { $output->writeln(" $done/$total $name"); } - }); + }, $skipped); } catch (\Throwable $e) { $output->writeln('' . $e->getMessage() . ''); + if ($skipped === null && self::backupLooksDamaged($e)) { + $output->writeln('The data of a file on the location is damaged or missing. Run the same command with --salvage to restore everything else and list what could not be restored.'); + } return 1; } $output->writeln(sprintf('Restored %d files to %s%s.', $r['restored'], $r['target'], $r['trashed'] ? ", moved {$r['trashed']} extra files to the trash" : '')); - return 0; + return self::reportSkipped($skipped, $output); + } + + /** Damaged data, or a file that is gone from the location: what --salvage is for. */ + public static function backupLooksDamaged(\Throwable $e): bool { + return $e instanceof \OCA\NgBackup\Repository\RepositoryException + || $e instanceof \OCA\NgBackup\Crypto\CryptoException + || ($e instanceof \OCA\NgBackup\Backend\BackendException && str_starts_with($e->getMessage(), 'Not found')); + } + + /** + * The files --salvage left out; exit code 2 when there are any. + * + * @param array|null $skipped + */ + public static function reportSkipped(?array $skipped, OutputInterface $output): int { + if ($skipped === null || $skipped === []) { + return 0; + } + $output->writeln(sprintf('%d file%s could not be restored (damaged or missing on the location):', count($skipped), count($skipped) === 1 ? '' : 's')); + foreach ($skipped as $path => $reason) { + $output->writeln(" $path: $reason"); + } + return 2; } } diff --git a/lib/Command/RestoreFull.php b/lib/Command/RestoreFull.php index 6c804c6..6f2310e 100644 --- a/lib/Command/RestoreFull.php +++ b/lib/Command/RestoreFull.php @@ -36,6 +36,7 @@ final class RestoreFull extends Command { ->addOption('force', null, InputOption::VALUE_NONE, 'Also on an installation that already has more than one user, and without asking') ->addOption('install-apps', null, InputOption::VALUE_NONE, 'First install (from the app store) or enable the apps that were enabled at backup time and are missing here') ->addOption('skip-missing-tables', null, InputOption::VALUE_NONE, 'Older backups only: leave out tables that do not exist here and whose structure the backup does not record') + ->addOption('salvage', null, InputOption::VALUE_NONE, 'Restore what can be restored: leave out files that cannot be read, and when the database cannot be restored, put the files in a folder of their own') ->setHelp(<<<'HELP' For a FRESH Nextcloud installation only, same major version as the backup, right after occ maintenance:install, occ backup:key:import and occ backup:target:add -- before anyone else @@ -55,6 +56,12 @@ here. Other files under config/ (if any) are not restored. Afterwards: check trusted_domains and overwritehost/overwriteprotocol match this server, and occ maintenance:repair. +When the backup is damaged: --salvage restores what can be restored. Files whose data cannot be +read or decrypted are left out and listed. When the database cannot be restored (its dump is +damaged, or it does not fit this installation), the database stays as occ maintenance:install +made it, and the data directory and config of the backup go to ngb-salvage- in the +data directory instead: from there, the files can be put back by hand. The command then exits +with code 2. Example: occ backup:restore:full offsite 537bf7e9c1a4... @@ -82,29 +89,41 @@ HELP); $target = $this->targets->get($input->getArgument('target')); $snapshot = (string)$input->getArgument('snapshot'); $skipMissingTables = (bool)$input->getOption('skip-missing-tables'); + $salvage = (bool)$input->getOption('salvage'); if ($input->getOption('install-apps')) { - $check = $this->restoreFull->checkCompatibility($target, $snapshot, $skipMissingTables); + $check = $this->restoreFull->checkCompatibility($target, $snapshot, $skipMissingTables, $salvage); foreach ($check['missingApps'] as $app) { $this->installApp($app, $output); } } $output->writeln('Nextcloud is in maintenance mode while the restore runs; it is switched off when the restore completes.'); - $result = $this->restoreFull->restoreFull($target, $snapshot, $skipMissingTables); + $result = $this->restoreFull->restoreFull($target, $snapshot, $skipMissingTables, $salvage); } catch (\Throwable $e) { $output->writeln('' . $e->getMessage() . ''); if (\OCP\Server::get(\OCP\IConfig::class)->getSystemValueBool('maintenance', false)) { $output->writeln('The restore had started: the instance may be partly restored, and maintenance mode stays on so that nobody uses it like that.'); $output->writeln('Fix the cause, then switch maintenance mode off and run the same command again with --force, in one line:'); $again = 'occ backup:restore:full ' . escapeshellarg((string)$input->getArgument('target')) . ' ' . escapeshellarg((string)$input->getArgument('snapshot')) - . ($input->getOption('skip-missing-tables') ? ' --skip-missing-tables' : '') . ' --force --no-interaction'; + . ($input->getOption('skip-missing-tables') ? ' --skip-missing-tables' : '') . ($input->getOption('salvage') ? ' --salvage' : '') . ' --force --no-interaction'; $output->writeln(' occ maintenance:mode --off && ' . $again); $output->writeln('(Without --install-apps, so the instance is open only for the seconds until the restore starts again. Apps the first run could not install are listed at the end: install those afterwards.)'); } else { $output->writeln('If this happened after the restore had started, the instance may be partly restored: fix the cause and run the same command again with --force.'); } $output->writeln('If occ then says that Nextcloud needs an upgrade (the database is already the old server\'s), run occ upgrade first.'); + if (!$input->getOption('salvage') && Restore::backupLooksDamaged($e)) { + $output->writeln('The backup itself looks damaged here. --salvage restores everything that can be read and lists the rest.'); + } return 1; } + if ($result['dbError'] !== null) { + $output->writeln('Salvage: ' . $result['dbError'] . ''); + $output->writeln(sprintf('The database stays as occ maintenance:install made it. The data directory and config of the backup (%d data files) are in:', $result['dataFiles'])); + $output->writeln(' ' . $result['salvageDir']); + $output->writeln('Each user\'s files are in data//files there. Put back what is needed by hand, for example into the files of new users (then occ files:scan).'); + Restore::reportSkipped($result['skipped'], $output); + return 2; + } $output->writeln(sprintf( 'Database restored (%d tables, %d unchanged), config merged (%d keys), %d data files restored.', count($result['dbReport']['restored']), @@ -135,7 +154,12 @@ HELP); $output->writeln('Maintenance mode was on before the restore and stays on: switch it off with occ maintenance:mode --off when the instance is ready.'); } $output->writeln('Next: check trusted_domains and overwritehost/overwriteprotocol match this server, then occ maintenance:repair.'); - return 0; + $code = 0; + if ($result['configError'] !== null) { + $output->writeln('Salvage: config.php of the backup was not merged (' . $result['configError'] . '). Set at least \'instanceid\', \'passwordsalt\' and \'secret\' to the old server\'s values if you have them, or data encrypted with them (server-side encryption, stored passwords) cannot be read.'); + $code = 2; + } + return max($code, Restore::reportSkipped($result['skipped'], $output)); } /** Enable an app that is here but switched off, or install it from the app store. */ diff --git a/lib/Command/Status.php b/lib/Command/Status.php index 9d89678..65a1260 100644 --- a/lib/Command/Status.php +++ b/lib/Command/Status.php @@ -9,6 +9,7 @@ namespace OCA\NgBackup\Command; use OCA\NgBackup\Db\RunMapper; use OCA\NgBackup\Format; +use OCA\NgBackup\Service\CronHealth; use OCA\NgBackup\Service\KeyService; use OCA\NgBackup\Service\Schedule; use OCA\NgBackup\Service\TargetService; @@ -29,6 +30,7 @@ final class Status extends Command { private RunMapper $runs, private VerifyService $verify, private Schedule $schedule, + private CronHealth $cron, ) { parent::__construct(); } @@ -40,6 +42,10 @@ final class Status extends Command { protected function execute(InputInterface $input, OutputInterface $output): int { $zone = $this->schedule->get()['timezone']; + $cronProblem = CronHealth::describe($this->cron->check()); + if ($cronProblem !== null) { + $output->writeln('' . $cronProblem . ''); + } if (!$this->keys->isInitialized()) { $output->writeln('Key: not created (occ backup:key:init)'); } else { @@ -57,7 +63,7 @@ final class Status extends Command { $shown = $this->runs->findShown($all ? null : time() - self::RECENT_DAYS * 86400); foreach ($shown as $r) { $s = json_decode($r->getStats() ?? '{}', true)['files'] ?? []; - $rows[] = [$r->getId(), $names[$r->getTargetId()] ?? '#' . $r->getTargetId(), $r->getKind(), $r->getStatus() . ($r->getStatus() === 'running' ? ' (' . $r->getPhase() . self::percent($r) . ')' : ''), + $rows[] = [$r->getId(), $names[$r->getTargetId()] ?? '#' . $r->getTargetId(), $r->getKind(), $r->getStatus() === 'running' ? self::runningStatus($r) : $r->getStatus(), Format::time($r->getStartedAt(), $zone), $r->getFinishedAt() ? Format::duration($r->getFinishedAt() - $r->getStartedAt()) : '', $s['files'] ?? '', isset($s['bytes']) ? self::size((int)$s['bytes']) : '', isset($s['uploaded']) ? self::size((int)$s['uploaded']) : '', mb_strimwidth((string)$r->getError(), 0, 50, '…')]; @@ -88,8 +94,24 @@ final class Status extends Command { return sprintf('%.1f TiB', $b); } + /** " 47/183 tables" in the database phase, " 68%" or " ~68%" in the files phase; empty without a figure */ private static function percent(\OCA\NgBackup\Db\Run $r): string { $p = \OCA\NgBackup\Job\BackupRun::progressOf($r); - return $p === null ? '' : sprintf(' %s%d%%', $p['approximate'] ? '~' : '', (int)floor($p['fraction'] * 100.0)); + if ($p === null) { + return ''; + } + if (isset($p['tables'], $p['totalTables'])) { + return sprintf(': %d/%d tables', $p['tables'], $p['totalTables']); + } + return sprintf(' %s%d%%', $p['approximate'] ? '~' : '', (int)floor($p['fraction'] * 100.0)); + } + + /** "running (db: 47/183 tables)", or "waiting for background jobs (last step 12 min ago)" */ + private static function runningStatus(\OCA\NgBackup\Db\Run $r): string { + $waiting = $r->getKind() === \OCA\NgBackup\Service\BackupService::KIND_FULL ? CronHealth::waitingFor($r) : null; + if ($waiting !== null) { + return 'waiting for background jobs (' . $r->getPhase() . self::percent($r) . ', last step ' . CronHealth::ago($waiting) . ')'; + } + return 'running (' . $r->getPhase() . self::percent($r) . ')'; } } diff --git a/lib/Command/TargetAdd.php b/lib/Command/TargetAdd.php index b56d250..0d24c1b 100644 --- a/lib/Command/TargetAdd.php +++ b/lib/Command/TargetAdd.php @@ -88,19 +88,21 @@ HELP); * @return callable(int, int): void */ private static function progress(OutputInterface $output): callable { - $start = microtime(true); $shown = 0.0; + $first = null; // [time, files done] when the first files were in $inPlace = $output->isDecorated(); - return static function (int $done, int $total) use ($output, $start, &$shown, $inPlace): void { + return static function (int $done, int $total) use ($output, &$shown, &$first, $inPlace): void { $now = microtime(true); + if ($first === null && $done > 0) { + $first = [$now, $done]; + } if ($done < $total && $now - $shown < ($inPlace ? 1 : 30)) { return; } $shown = $now; $line = sprintf('Reading the index: %s/%s files (%d%%)', number_format($done), number_format($total), intdiv(100 * $done, max(1, $total))); - $elapsed = $now - $start; - if ($done < $total && $done > 0 && $elapsed >= 5) { - $left = (int)ceil($elapsed / (float)$done * (float)($total - $done) / 60.0); + $left = $first === null ? null : self::minutesLeft($now - $first[0], $done - $first[1], $total - $done, $total); + if ($left !== null) { $line .= $left <= 1 ? ', less than a minute left' : sprintf(', about %d min left', $left); } if ($inPlace) { @@ -110,4 +112,17 @@ HELP); } }; } + + /** + * Minutes left for reading the index, from the rate since the first files were in: the first + * file also carries the time to connect, which made an S3 location with 4,568 index files + * say "about 642 min left" for something done within a minute. No estimate until 5% of the + * files, or 50 files, came in after that, and at least 5 seconds passed. + */ + public static function minutesLeft(float $elapsed, int $done, int $left, int $total): ?int { + if ($left <= 0 || $done <= 0 || $elapsed < 5.0 || ($done < 50 && $done * 20 < $total)) { + return null; + } + return (int)ceil($elapsed / (float)$done * (float)$left / 60.0); + } } diff --git a/lib/Controller/AdminApiController.php b/lib/Controller/AdminApiController.php index 886e415..85a2683 100644 --- a/lib/Controller/AdminApiController.php +++ b/lib/Controller/AdminApiController.php @@ -48,6 +48,7 @@ final class AdminApiController extends Controller { private \OCA\NgBackup\Service\KeySlotService $slots, private \OCA\NgBackup\Service\PruneService $prune, private \OCA\NgBackup\Service\Schedule $schedule, + private \OCA\NgBackup\Service\CronHealth $cron, ) { parent::__construct(Application::APP_ID, $request); } @@ -75,9 +76,36 @@ final class AdminApiController extends Controller { 'recentDays' => \OCA\NgBackup\Command\Status::RECENT_DAYS, 'schedule' => $this->schedule->get()['time'], 'scheduleTimezone' => $this->schedule->get()['timezone'], + 'cron' => $this->cron->check(), ]); } + /** Seconds of backup work one tick() does: well within a normal web request. */ + public const TICK_SECONDS = 10.0; + + /** + * Move running backups forward from the open admin page, when background jobs do not run on a + * working system cron (#13). The page calls this while a backup runs, so "Back up now" works + * without cron as long as the page stays open; scheduled backups still need cron. With a + * working system cron this does nothing: the background job does the work. + */ + public function tick(): JSONResponse { + if ($this->cron->check()['ok']) { + return new JSONResponse(['stepped' => 0]); + } + $deadline = microtime(true) + self::TICK_SECONDS; + $stepped = 0; + foreach ($this->runs->findRunning(null, BackupService::KIND_FULL) as $run) { + if (microtime(true) >= $deadline) { + break; + } + // step() returns at once when the background job (or another tab) holds the run. + $this->backups->step($run, $deadline); + $stepped++; + } + return new JSONResponse(['stepped' => $stepped]); + } + #[PasswordConfirmationRequired] public function initKey(string $passphrase, int $deleteDelayDays = \OCA\NgBackup\Service\KeyService::DEFAULT_DELETE_DELAY, string $label = 'Slot 1'): JSONResponse { try { @@ -313,6 +341,7 @@ final class AdminApiController extends Controller { return ['id' => $r->getId(), 'targetId' => $r->getTargetId(), 'kind' => $r->getKind(), 'status' => $r->getStatus(), 'phase' => $r->getPhase(), 'snapshotId' => $r->getSnapshotId(), 'snapshot' => $snapshot, 'startedAt' => $r->getStartedAt(), 'updatedAt' => $r->getUpdatedAt(), 'finishedAt' => $r->getFinishedAt(), 'error' => $r->getError(), - 'stats' => json_decode($r->getStats() ?? 'null', true), 'progress' => \OCA\NgBackup\Job\BackupRun::progressOf($r)]; + 'stats' => json_decode($r->getStats() ?? 'null', true), 'progress' => \OCA\NgBackup\Job\BackupRun::progressOf($r), + 'waitingFor' => $r->getKind() === BackupService::KIND_FULL ? \OCA\NgBackup\Service\CronHealth::waitingFor($r) : null]; } } diff --git a/lib/Job/BackupRun.php b/lib/Job/BackupRun.php index 2c9e136..e7cc3f1 100644 --- a/lib/Job/BackupRun.php +++ b/lib/Job/BackupRun.php @@ -176,12 +176,12 @@ final class BackupRun { } /** - * progress() of a run, while it is in its files phase. + * progress() of a run in its files phase; in its database phase, the tables dumped so far. * - * @return array{fraction: float, approximate: bool}|null + * @return array{fraction: float, approximate: bool, tables?: int, totalTables?: int}|null */ public static function progressOf(\OCA\NgBackup\Db\Run $run): ?array { - if ($run->getStatus() !== \OCA\NgBackup\Db\Run::RUNNING || $run->getPhase() !== 'files') { + if ($run->getStatus() !== \OCA\NgBackup\Db\Run::RUNNING || !in_array($run->getPhase(), ['db', 'files'], true)) { return null; } try { @@ -189,6 +189,14 @@ final class BackupRun { } catch (\JsonException) { return null; } + if ($run->getPhase() === 'db') { + // Tables dumped so far, as of the last step (none known before the first step ends) + $tables = count($state['dump']['tables'] ?? []); + return $tables > 0 + ? ['fraction' => min(1.0, ($state['dump']['i'] ?? 0) / $tables), 'approximate' => false, + 'tables' => (int)($state['dump']['i'] ?? 0), 'totalTables' => $tables] + : null; + } return is_array($state['files'] ?? null) ? self::progress($state['files']) : null; } diff --git a/lib/Repository/Repository.php b/lib/Repository/Repository.php index e87a173..44be374 100644 --- a/lib/Repository/Repository.php +++ b/lib/Repository/Repository.php @@ -221,14 +221,21 @@ final class Repository { * "$target/" (disaster recovery: restoring e.g. "data/" or * "config/" directly into the real data/config directory, not a subdirectory * named after the prefix). Ignored when $prefix is '' (nothing to strip). + * @param array|null $skipped salvage: an array to collect the files that could + * not be read or decrypted (path => reason), which are then left out instead of + * stopping the restore; null (default) stops at the first such file + * @param bool $keepUnchanged leave a file that is already in place with the size and + * modification time of the snapshot, as a backup takes such a file as unchanged: + * a restore that was stopped and runs again goes on where it was, without reading + * what it already restored from the location again */ - public function restore(string $snapshotId, string $target, string $prefix = '', bool $stripPrefix = false, ?callable $heartbeat = null): int { + public function restore(string $snapshotId, string $target, string $prefix = '', bool $stripPrefix = false, ?callable $heartbeat = null, ?array &$skipped = null, bool $keepUnchanged = false): int { if ($prefix !== '' && !self::isSafePath(rtrim($prefix, '/'))) { throw new RepositoryException('Invalid path prefix'); } - $plan = $this->readAhead($snapshotId, $prefix, $target); + $plan = $this->readAhead($snapshotId, $prefix, $target, $stripPrefix, $keepUnchanged); try { - return $this->restoreEntries($snapshotId, $target, $prefix, $stripPrefix, $heartbeat, $plan); + return $this->restoreEntries($snapshotId, $target, $prefix, $stripPrefix, $heartbeat, $plan, $skipped, $keepUnchanged); } finally { $plan?->close(); if ($plan !== null) { @@ -242,13 +249,23 @@ final class Repository { * pass over the snapshot lists the ranges of packs it needs, in order. The spool is a * folder in the target, which has room for the restore anyway. */ - private function readAhead(string $snapshotId, string $prefix, string $target): ?ReadAheadPlan { + private function readAhead(string $snapshotId, string $prefix, string $target, bool $stripPrefix, bool $keepUnchanged): ?ReadAheadPlan { if (!$this->backend instanceof IReadsAhead || !$this->backend->canReadAhead()) { return null; } - // what a restore that was stopped left behind: empty, its files were unlinked when opened + // what a restore that was stopped left behind: its files are unlinked once opened, but one + // that was being written when the process was killed stays (8 MiB, DR test 2026-11-05) $stale = glob(rtrim($target, '/') . '/.ngb-restore-spool-*', GLOB_ONLYDIR); foreach ($stale === false ? [] : $stale as $dir) { + if (is_link($dir)) { + continue; + } + $files = glob($dir . '/*'); + foreach ($files === false ? [] : $files as $file) { + if (is_file($file) && !is_link($file)) { + @unlink($file); + } + } @rmdir($dir); } $plan = new ReadAheadPlan(rtrim($target, '/') . '/.ngb-restore-spool-' . bin2hex(random_bytes(4))); @@ -257,6 +274,9 @@ final class Repository { if (!self::underPrefix($entry['p'], $prefix)) { continue; } + if ($keepUnchanged && self::inPlace(self::destination($target, $entry['p'], $prefix, $stripPrefix), $entry)) { + continue; + } foreach ($entry['b'] as $id) { try { [$pack, $offset, $length] = $this->index->get($id); @@ -285,18 +305,20 @@ final class Repository { return $plan; } - private function restoreEntries(string $snapshotId, string $target, string $prefix, bool $stripPrefix, ?callable $heartbeat, ?ReadAheadPlan $plan): int { + /** @param array|null $skipped see restore() */ + private function restoreEntries(string $snapshotId, string $target, string $prefix, bool $stripPrefix, ?callable $heartbeat, ?ReadAheadPlan $plan, ?array &$skipped, bool $keepUnchanged): int { $count = 0; $cleaned = []; foreach ($this->streamEntries($snapshotId) as $entry) { if (!self::underPrefix($entry['p'], $prefix)) { continue; } - $relPath = $entry['p']; - if ($stripPrefix && $prefix !== '') { - $relPath = $entry['p'] === rtrim($prefix, '/') ? basename($entry['p']) : substr($entry['p'], strlen($prefix)); + $dest = self::destination($target, $entry['p'], $prefix, $stripPrefix); + if ($keepUnchanged && self::inPlace($dest, $entry)) { + // below the target as written by an earlier run of this restore (checked then) + $count++; + continue; } - $dest = rtrim($target, '/') . '/' . $relPath; if (!is_dir(dirname($dest))) { mkdir(dirname($dest), 0700, true); } @@ -317,16 +339,30 @@ final class Repository { if ($out === false) { throw new RepositoryException('Cannot create a temporary file for ' . $entry['p']); } - foreach ($entry['b'] as $id) { - fwrite($out, $this->restoreBlob($id, $plan)); - if ($heartbeat !== null) { - $heartbeat(); + try { + foreach ($entry['b'] as $id) { + fwrite($out, $this->restoreBlob($id, $plan)); + if ($heartbeat !== null) { + $heartbeat(); + } } - } - fclose($out); - if (filesize($tmp) !== $entry['s']) { - unlink($tmp); - throw new RepositoryException('Size mismatch restoring ' . $entry['p']); + fclose($out); + clearstatcache(true, $tmp); + if (filesize($tmp) !== $entry['s']) { + throw new RepositoryException('Size mismatch restoring ' . $entry['p']); + } + } catch (RepositoryException|BackendException|\OCA\NgBackup\Crypto\CryptoException $e) { + // What the location gave back for this file is missing or damaged. Writing to the + // target (below) is not part of this: a full disk must still stop the restore. + if (is_resource($out)) { + fclose($out); + } + @unlink($tmp); + if ($skipped === null) { + throw $e; + } + $skipped[$entry['p']] = $e->getMessage(); + continue; } if (!rename($tmp, $dest)) { @unlink($tmp); @@ -340,6 +376,26 @@ final class Repository { return $count; } + /** Where restore() writes the snapshot path $path. */ + private static function destination(string $target, string $path, string $prefix, bool $stripPrefix): string { + $relPath = $path; + if ($stripPrefix && $prefix !== '') { + $relPath = $path === rtrim($prefix, '/') ? basename($path) : substr($path, strlen($prefix)); + } + return rtrim($target, '/') . '/' . $relPath; + } + + /** + * A regular file (no link) at $dest with the size and modification time of the snapshot + * entry: what a backup takes as unchanged, and what a finished restore of it leaves. + * + * @param array{s: int, m: int, ...} $entry + */ + private static function inPlace(string $dest, array $entry): bool { + clearstatcache(true, $dest); + return !is_link($dest) && is_file($dest) && filesize($dest) === $entry['s'] && filemtime($dest) === $entry['m']; + } + /** $prefix is "" (everything) or ends with "/"; the path without that "/" is a file to restore too. */ private static function underPrefix(string $path, string $prefix): bool { return $prefix === '' || str_starts_with($path, $prefix) || $path === rtrim($prefix, '/'); diff --git a/lib/Service/CronHealth.php b/lib/Service/CronHealth.php new file mode 100644 index 0000000..11d560c --- /dev/null +++ b/lib/Service/CronHealth.php @@ -0,0 +1,97 @@ +coreString('backgroundjobs_mode', 'ajax'); + $lastRun = (int)$this->coreString('lastcron', '0'); + $stopped = $mode === 'cron' && $now - $lastRun > self::STOPPED_AFTER; + return [ + 'mode' => $mode, + 'lastRun' => $lastRun, + 'ok' => $mode === 'cron' && !$stopped, + 'stopped' => $stopped, + 'docs' => $this->urls->linkToDocs('admin-background-jobs'), + ]; + } + + /** + * Seconds since a running backup took its last step, when that is long enough to say it waits + * for background jobs; null while it moves (or when it is not running). + */ + public static function waitingFor(Run $run, ?int $now = null): ?int { + $idle = ($now ?? time()) - $run->getUpdatedAt(); + return $run->getStatus() === Run::RUNNING && $idle >= self::WAITING_AFTER ? $idle : null; + } + + /** One line for occ and the log; null when system cron runs. */ + public static function describe(array $health, ?int $now = null): ?string { + if ($health['ok']) { + return null; + } + $last = $health['lastRun'] > 0 ? 'last ran ' . self::ago(($now ?? time()) - $health['lastRun']) : 'never ran'; + $what = $health['stopped'] + ? 'Background jobs are set to system cron, but cron has not run for over an hour (' . $last . ').' + : 'Background jobs do not run on a system cron: they are set to "' . ($health['mode'] === 'webcron' ? 'Webcron' : 'AJAX') . '" and ' . $last . '.'; + return $what . ' Backups, also the scheduled ones, need a system cron that runs every 5 minutes: ' . $health['docs']; + } + + /** "12 min ago" style, for durations from a minute to days */ + public static function ago(int $seconds): string { + if ($seconds < 3600) { + return max(1, intdiv($seconds, 60)) . ' min ago'; + } + if ($seconds < 172800) { + return intdiv($seconds, 3600) . ' h ago'; + } + return intdiv($seconds, 86400) . ' days ago'; + } + + /** Core stores these with different value types across versions: read whatever is there. */ + private function coreString(string $key, string $default): string { + try { + return $this->appConfig->getValueString('core', $key, $default); + } catch (AppConfigTypeConflictException) { + return (string)$this->appConfig->getValueInt('core', $key, (int)$default); + } + } +} diff --git a/lib/Service/RestoreFullService.php b/lib/Service/RestoreFullService.php index 2a1978e..1749aa9 100644 --- a/lib/Service/RestoreFullService.php +++ b/lib/Service/RestoreFullService.php @@ -58,9 +58,12 @@ final class RestoreFullService { * - tables in the backup that do not exist here: a backup made from 1.0.0-rc.2 on records * their structure and the restore creates them, an older one cannot (missingTables). * - * @return array{ok:bool, currentMajor:string, snapshotMajor:string, missingApps:list, missingTables:list} + * With $salvage, a database dump that cannot be read does not block: dbUnreadable says why, and + * the restore then salvages the files instead (see restoreFull()). + * + * @return array{ok:bool, currentMajor:string, snapshotMajor:string, missingApps:list, missingTables:list, dbUnreadable?:string} */ - public function checkCompatibility(Target $target, string $snapshotId, bool $skipMissingTables = false): array { + public function checkCompatibility(Target $target, string $snapshotId, bool $skipMissingTables = false, bool $salvage = false): array { $repo = $this->targets->repository($target); $meta = $repo->snapshotMeta($snapshotId); $currentMajor = explode('.', $this->config->getSystemValueString('version'))[0]; @@ -69,8 +72,19 @@ final class RestoreFullService { $missingApps = array_values(array_diff(array_keys($meta['apps'] ?? []), array_keys($enabled), self::ENVIRONMENT_APPS)); $missingTables = []; $prefixMismatch = null; + $dbUnreadable = null; + $manifest = null; if (isset($meta['db'])) { - $manifest = json_decode($repo->getObject($meta['db']), true, 512, JSON_THROW_ON_ERROR); + try { + $manifest = json_decode($repo->getObject($meta['db']), true, 512, JSON_THROW_ON_ERROR); + } catch (\Throwable $e) { + if (!$salvage) { + throw $e; + } + $dbUnreadable = 'the database dump cannot be read: ' . $e->getMessage(); + } + } + if (is_array($manifest)) { $prefix = $this->config->getSystemValueString('dbtableprefix', 'oc_'); $sourcePrefix = DbDumper::dumpPrefix($manifest); if ($sourcePrefix !== null && $sourcePrefix !== $prefix) { @@ -87,11 +101,21 @@ final class RestoreFullService { 'missingApps' => $missingApps, 'missingTables' => $prefixMismatch === null ? $missingTables : [], 'prefixMismatch' => $prefixMismatch, - ]; + ] + ($dbUnreadable !== null ? ['dbUnreadable' => $dbUnreadable] : []); } - /** @return array{dbReport:array, dataFiles:int, configKeys:int, dbConsistent:bool, missingApps:list, maintenanceLeftOn:bool} */ - public function restoreFull(Target $target, string $snapshotId, bool $skipMissingTables = false): array { + /** + * With $salvage, restore whatever can be restored instead of stopping: + * - a file that cannot be read or decrypted is left out and listed (skipped); + * - when the database cannot be restored here (its dump is unreadable or damaged, or it does + * not fit this installation), the fresh database stays as it is, and the data directory and + * config of the backup go to a folder of their own (salvageDir) instead: the files are what + * matters most, and putting Nextcloud back together from there is work by hand; + * - a config.php that cannot be read is not merged (configError). + * + * @return array{dbReport:array, dataFiles:int, configKeys:int, dbConsistent:bool, missingApps:list, maintenanceLeftOn:bool, skipped:array, dbError:?string, salvageDir:?string, configError:?string} + */ + public function restoreFull(Target $target, string $snapshotId, bool $skipMissingTables = false, bool $salvage = false): array { // Maintenance mode for the whole restore: background jobs (cron.php stops in maintenance // mode), page visits (AJAX cron) and users must not write into tables or the data // directory while they are being replaced; a row written in between would collide with a @@ -114,17 +138,21 @@ final class RestoreFullService { } }; try { - $check = $this->checkCompatibility($target, $snapshotId, $skipMissingTables); + $check = $this->checkCompatibility($target, $snapshotId, $skipMissingTables, $salvage); } catch (\Throwable $e) { $reopen(); throw $e; } if (!$check['ok']) { - $reopen(); - throw new \RuntimeException($this->describeBlockers($check)); + if (!$salvage) { + $reopen(); + throw new \RuntimeException($this->describeBlockers($check)); + } + // The database cannot go into this installation; the files can. + $check['dbUnreadable'] = 'the database cannot be restored here: ' . $this->describeBlockers($check); } $appConfig->setValueInt(\OCA\NgBackup\AppInfo\Application::APP_ID, self::INTERRUPTED_KEY, time()); - $result = $this->restoreInMaintenance($target, $snapshotId, $skipMissingTables, $check); + $result = $this->restoreInMaintenance($target, $snapshotId, $skipMissingTables, $check, $salvage); $appConfig->deleteKey(\OCA\NgBackup\AppInfo\Application::APP_ID, self::INTERRUPTED_KEY); if (!$wasInMaintenance) { $this->config->setSystemValue('maintenance', false); @@ -132,55 +160,56 @@ final class RestoreFullService { return $result + ['maintenanceLeftOn' => $wasInMaintenance]; } - /** @return array{dbReport:array, dataFiles:int, configKeys:int, dbConsistent:bool, missingApps:list} */ - private function restoreInMaintenance(Target $target, string $snapshotId, bool $skipMissingTables, array $check): array { - return $this->withSharedLock($target, function (callable $refresh) use ($target, $snapshotId, $skipMissingTables, $check) { + /** @return array{dbReport:array, dataFiles:int, configKeys:int, dbConsistent:bool, missingApps:list, skipped:array, dbError:?string, salvageDir:?string, configError:?string} */ + private function restoreInMaintenance(Target $target, string $snapshotId, bool $skipMissingTables, array $check, bool $salvage): array { + return $this->withSharedLock($target, function (callable $refresh) use ($target, $snapshotId, $skipMissingTables, $check, $salvage) { $beat = LeaseService::throttled($refresh); $repo = $this->targets->repository($target); $meta = $repo->snapshotMeta($snapshotId); $dbReport = null; $manifest = []; - if (isset($meta['db'])) { - $manifest = json_decode($repo->getObject($meta['db']), true, 512, JSON_THROW_ON_ERROR); - $prefix = $this->config->getSystemValueString('dbtableprefix', 'oc_'); - // ng_backup's own tables (and its own rows in the shared appconfig table) must - // survive this restore untouched: they describe the backup/key/target that is - // actively performing it right now, on THIS installation, not the one that was - // backed up. Overwriting them mid-restore would pull the rug from under it. - foreach (array_keys($manifest['tables']) as $table) { - /** @var string $table */ - if (str_starts_with($table, $prefix . 'ngb_')) { - unset($manifest['tables'][$table]); - } - } - // Sequences are keyed separately from tables; excluding a table does not exclude - // its sequence, which would otherwise rewind a retained ngb_* table's sequence - // below its current ids (PostgreSQL only -- see DbDumper::restoreSequences()). - foreach (array_keys($manifest['sequences'] ?? []) as $seq) { - /** @var string $seq */ - if (str_starts_with((string)($manifest['sequences'][$seq]['table'] ?? ''), $prefix . 'ngb_')) { - unset($manifest['sequences'][$seq]); - } - } - $ownAppConfig = $this->preserveOwnAppConfig(); - $dumper = new DbDumper($this->db->getInner(), $prefix); + $dbError = $check['dbUnreadable'] ?? null; + $skipped = $salvage ? [] : null; + $dataDir = rtrim($this->config->getSystemValueString('datadirectory'), '/'); + if ($dbError === null) { try { - $dumper->restore($repo, $manifest, $dbReport, $beat, $skipMissingTables); - } finally { - $this->restoreOwnAppConfig($ownAppConfig); + $this->restoreDatabase($repo, $meta, $manifest, $dbReport, $beat, $skipMissingTables); + } catch (\Throwable $e) { + if (!$salvage) { + throw $e; + } + // DbDumper::restore() rolled its transaction back: the database is the fresh one. + $dbError = 'the database could not be restored: ' . $e->getMessage(); + $dbReport = null; } } + if ($dbError !== null) { + $salvageDir = $dataDir . '/ngb-salvage-' . substr($snapshotId, 0, 12); + $dataFiles = $this->restore->restoreToDirectory($target, $snapshotId, 'data', $salvageDir . '/data', stripPrefix: true, heartbeat: $beat, skipped: $skipped, keepUnchanged: true); + $this->restore->restoreToDirectory($target, $snapshotId, 'config', $salvageDir . '/config', stripPrefix: true, heartbeat: $beat, skipped: $skipped); + return ['dbReport' => ['skipped' => [], 'restored' => [], 'created' => [], 'missing' => []], 'dataFiles' => $dataFiles, 'configKeys' => 0, + 'dbConsistent' => true, 'missingApps' => $check['missingApps'], 'skipped' => $skipped ?? [], 'dbError' => $dbError, + 'salvageDir' => $salvageDir, 'configError' => null]; + } // Read (but do not yet apply) the backed-up config.php before touching the data // directory: once applied, 'secret' may differ from what ng_backup's own Target // options were encrypted with (see restoreFull()'s docblock), and every further // repository access through $this->targets would fail to decrypt them. - /** @var array $backupConfig */ - $backupConfig = $this->fetchBackupConfig($target, $snapshotId); + $configError = null; + try { + /** @var array $backupConfig */ + $backupConfig = $this->fetchBackupConfig($target, $snapshotId, $salvage); + } catch (\Throwable $e) { + if (!$salvage) { + throw $e; + } + $configError = $e->getMessage(); + $backupConfig = []; + } - $dataDir = rtrim($this->config->getSystemValueString('datadirectory'), '/'); - $dataFiles = $this->restore->restoreToDirectory($target, $snapshotId, 'data', $dataDir, stripPrefix: true, heartbeat: $beat); + $dataFiles = $this->restore->restoreToDirectory($target, $snapshotId, 'data', $dataDir, stripPrefix: true, heartbeat: $beat, skipped: $skipped, keepUnchanged: true); // Last step: nothing after this may need $this->targets->repository($target) again. if ($backupConfig !== []) { @@ -190,15 +219,63 @@ final class RestoreFullService { } return ['dbReport' => $dbReport ?? ['skipped' => [], 'restored' => [], 'created' => [], 'missing' => []], 'dataFiles' => $dataFiles, 'configKeys' => count($backupConfig), - 'dbConsistent' => (bool)($manifest['consistent'] ?? true), 'missingApps' => $check['missingApps']]; + 'dbConsistent' => (bool)($manifest['consistent'] ?? true), 'missingApps' => $check['missingApps'], + 'skipped' => $skipped ?? [], 'dbError' => null, 'salvageDir' => null, 'configError' => $configError]; }); } - /** @return array config.php's $CONFIG from the backup, minus the connection keys */ - private function fetchBackupConfig(Target $target, string $snapshotId): array { + /** + * Replace the database with the snapshot's dump (one transaction, see DbDumper::restore()). + * + * @param array $meta the snapshot's meta record + * @param array $manifest set to the dump's manifest + */ + private function restoreDatabase(\OCA\NgBackup\Repository\Repository $repo, array $meta, array &$manifest, ?array &$dbReport, callable $beat, bool $skipMissingTables): void { + if (!isset($meta['db'])) { + return; + } + $manifest = json_decode($repo->getObject($meta['db']), true, 512, JSON_THROW_ON_ERROR); + $prefix = $this->config->getSystemValueString('dbtableprefix', 'oc_'); + // ng_backup's own tables (and its own rows in the shared appconfig table) must + // survive this restore untouched: they describe the backup/key/target that is + // actively performing it right now, on THIS installation, not the one that was + // backed up. Overwriting them mid-restore would pull the rug from under it. + foreach (array_keys($manifest['tables']) as $table) { + /** @var string $table */ + if (str_starts_with($table, $prefix . 'ngb_')) { + unset($manifest['tables'][$table]); + } + } + // Sequences are keyed separately from tables; excluding a table does not exclude + // its sequence, which would otherwise rewind a retained ngb_* table's sequence + // below its current ids (PostgreSQL only -- see DbDumper::restoreSequences()). + foreach (array_keys($manifest['sequences'] ?? []) as $seq) { + /** @var string $seq */ + if (str_starts_with((string)($manifest['sequences'][$seq]['table'] ?? ''), $prefix . 'ngb_')) { + unset($manifest['sequences'][$seq]); + } + } + $ownAppConfig = $this->preserveOwnAppConfig(); + $dumper = new DbDumper($this->db->getInner(), $prefix); + try { + $dumper->restore($repo, $manifest, $dbReport, $beat, $skipMissingTables); + } finally { + $this->restoreOwnAppConfig($ownAppConfig); + } + } + + /** + * @return array config.php's $CONFIG from the backup, minus the connection keys + * @throws \RuntimeException with $salvage, when config.php itself cannot be read + */ + private function fetchBackupConfig(Target $target, string $snapshotId, bool $salvage = false): array { $tmp = sys_get_temp_dir() . '/ngb-restore-config-' . bin2hex(random_bytes(6)); try { - $this->restore->restoreToDirectory($target, $snapshotId, 'config', $tmp, stripPrefix: true); + $skipped = $salvage ? [] : null; + $this->restore->restoreToDirectory($target, $snapshotId, 'config', $tmp, stripPrefix: true, skipped: $skipped); + if (isset($skipped['config/config.php'])) { + throw new \RuntimeException('config.php cannot be read: ' . $skipped['config/config.php']); + } $path = $tmp . '/config.php'; if (!is_file($path)) { return []; // nothing to merge; the live config.php stays as occ maintenance:install made it diff --git a/lib/Service/RestoreService.php b/lib/Service/RestoreService.php index fc3e276..8df6e0a 100644 --- a/lib/Service/RestoreService.php +++ b/lib/Service/RestoreService.php @@ -84,8 +84,8 @@ final class RestoreService { * * @return array{restored:int, trashed:int, target:string} */ - public function restoreUserFiles(Target $target, string $snapshotId, string $logicalPath, string $mode = self::MODE_NEW_FOLDER, ?callable $progress = null): array { - return $this->withSharedLock($target, function (callable $refresh) use ($target, $snapshotId, $logicalPath, $mode, $progress) { + public function restoreUserFiles(Target $target, string $snapshotId, string $logicalPath, string $mode = self::MODE_NEW_FOLDER, ?callable $progress = null, ?array &$skipped = null): array { + return $this->withSharedLock($target, function (callable $refresh) use ($target, $snapshotId, $logicalPath, $mode, $progress, &$skipped) { $last = time(); // Keep the lease alive while files are being written. $beat = function (int $done, int $total, string $name) use ($refresh, $progress, &$last): void { @@ -97,11 +97,12 @@ final class RestoreService { $progress($done, $total, $name); } }; - return $this->doRestoreUserFiles($target, $snapshotId, $logicalPath, $mode, $beat); + return $this->doRestoreUserFiles($target, $snapshotId, $logicalPath, $mode, $beat, $skipped); }); } - private function doRestoreUserFiles(Target $target, string $snapshotId, string $logicalPath, string $mode, ?callable $progress): array { + /** @param array|null $skipped see Repository::restore() */ + private function doRestoreUserFiles(Target $target, string $snapshotId, string $logicalPath, string $mode, ?callable $progress, ?array &$skipped): array { if (!Repository::isSafePath($logicalPath) || !preg_match('#^data/([^/]+)/files(?:/(.*))?$#', $logicalPath, $m)) { throw new \InvalidArgumentException('Expected a path like data//files/'); } @@ -139,7 +140,16 @@ final class RestoreService { $this->cleaned = []; $restored = 0; foreach ($names as $relPath => $entry) { - $this->writeFile($repo, $dest, (string)$relPath, $entry); + try { + $this->writeFile($repo, $dest, (string)$relPath, $entry); + } catch (\OCA\NgBackup\Repository\RepositoryException|\OCA\NgBackup\Backend\BackendException|\OCA\NgBackup\Crypto\CryptoException $e) { + // Damaged or missing on the location (writeFile removed its temporary) + if ($skipped === null) { + throw $e; + } + $skipped[$entry['p']] = $e->getMessage(); + continue; + } $restored++; if ($progress !== null) { $progress($restored, count($names), (string)$relPath); @@ -159,15 +169,18 @@ final class RestoreService { * @param bool $stripPrefix write into $directory itself instead of $directory/$prefix (see * Repository::restore()); used to restore "data/" or "config/" straight into the * real data/config directory for occ backup:restore:full. + * @param bool $keepUnchanged leave files already in place with the snapshot's size and + * modification time (see Repository::restore()): a full restore that runs again + * goes on where it stopped */ - public function restoreToDirectory(Target $target, string $snapshotId, string $prefix, string $directory, bool $stripPrefix = false, ?callable $heartbeat = null): int { + public function restoreToDirectory(Target $target, string $snapshotId, string $prefix, string $directory, bool $stripPrefix = false, ?callable $heartbeat = null, ?array &$skipped = null, bool $keepUnchanged = false): int { if ($prefix !== '' && !Repository::isSafePath($prefix)) { throw new \InvalidArgumentException('Invalid path: ' . $prefix); } if (!is_dir($directory) && !mkdir($directory, 0750, true) && !is_dir($directory)) { throw new \RuntimeException("Cannot create $directory"); } - return $this->withSharedLock($target, function (callable $refresh) use ($target, $snapshotId, $prefix, $directory, $stripPrefix, $heartbeat): int { + return $this->withSharedLock($target, function (callable $refresh) use ($target, $snapshotId, $prefix, $directory, $stripPrefix, $heartbeat, &$skipped, $keepUnchanged): int { $own = LeaseService::throttled($refresh); $beat = static function () use ($own, $heartbeat): void { $own(); @@ -175,7 +188,7 @@ final class RestoreService { $heartbeat(); } }; - return $this->targets->repository($target)->restore($snapshotId, $directory, trim($prefix, '/') === '' ? '' : trim($prefix, '/') . '/', $stripPrefix, $beat); + return $this->targets->repository($target)->restore($snapshotId, $directory, trim($prefix, '/') === '' ? '' : trim($prefix, '/') . '/', $stripPrefix, $beat, $skipped, $keepUnchanged); }, 3600); } @@ -203,7 +216,7 @@ final class RestoreService { throw new \RuntimeException('Write failed for ' . $relPath); } if ($written !== $entry['s']) { - throw new \RuntimeException("Size mismatch restoring $relPath"); + throw new \OCA\NgBackup\Repository\RepositoryException("Size mismatch restoring $relPath"); } if ($folder->nodeExists($name)) { $existing = $folder->get($name); diff --git a/screenshots/1-backups.png b/screenshots/1-backups.png index 959607d..f5ad83a 100644 Binary files a/screenshots/1-backups.png and b/screenshots/1-backups.png differ diff --git a/screenshots/2-restore.png b/screenshots/2-restore.png index d8928b7..bee0170 100644 Binary files a/screenshots/2-restore.png and b/screenshots/2-restore.png differ diff --git a/screenshots/3-settings.png b/screenshots/3-settings.png index 2cf98da..61122a8 100644 Binary files a/screenshots/3-settings.png and b/screenshots/3-settings.png differ diff --git a/screenshots/4-bin.png b/screenshots/4-bin.png new file mode 100644 index 0000000..52ae8f4 Binary files /dev/null and b/screenshots/4-bin.png differ diff --git a/src/AdminSettings.vue b/src/AdminSettings.vue index a70cd42..258d301 100644 --- a/src/AdminSettings.vue +++ b/src/AdminSettings.vue @@ -12,11 +12,22 @@

{{ error }} + +

+ {{ status.cron.stopped + ? t('ng_backup', 'Background jobs are set to system cron, but cron has not run since {time}.', { time: lastCron }) + : t('ng_backup', 'Background jobs do not run on a system cron (they are set to "{mode}").', { mode: status.cron.mode === 'webcron' ? 'Webcron' : 'AJAX' }) }} + {{ t('ng_backup', 'Backups need a system cron that runs every 5 minutes, also the scheduled ones.') }} + {{ t('ng_backup', 'How to set up cron ↗') }} +

+

{{ t('ng_backup', 'Until then, a backup started with "Back up now" only moves on while this page is open.') }}

+