OneDrive backup, self-hosted
By Lucas Flores, IT Systeme Flores UG. Last updated
Restow backs up the OneDrive of every protected user of a Microsoft 365 tenant through the Microsoft Graph API. It runs on your own server and writes to storage you choose. After the first full run, each run reads only what changed, deletions included, and gives a restore point from which you restore a file, a folder, an earlier version or a whole OneDrive. A restore never overwrites an existing file. OneDrive backup has been in every edition, Community included, since 0.1.0. It was tested against a simulated Microsoft Graph, not against a real Microsoft 365 tenant: Restow is a beta.
How a OneDrive is found and protected
Users, mailboxes and OneDrives come in automatically through the Entra ID directory sync. The protected scope is set per source: everyone, the members of one group, everyone except an exclusion list, or only the objects you select. Each OneDrive is a protected object of its own, named by its person, and runs in the mail jobs next to mailboxes and IMAP accounts. A newly protected object gets its first backup queued at once. A OneDrive for Business belongs to exactly one user.
In the scope "only selected objects", nobody is protected until an administrator includes them. A new object of a user who is already included is not included by itself, for example a OneDrive that Microsoft creates when the user first opens it.
How a backup runs
Restow reads the drive's changes with Microsoft Graph's delta query: the first run delivers everything, later runs only changes, including deletions. Files are downloaded from the short-lived URLs Graph hands out and streamed in pieces, never held whole in memory. Everything is cut into chunks, deduplicated within the tenant and encrypted (AES-256-GCM, one key per tenant) before it reaches your storage.
Microsoft throttles the Graph API, especially for the first backup of a
large tenant. Restow honours the wait Microsoft asks for, adds jitter and
shows the wait instead of hiding it. A OneDrive shows "X items so far"
until it is fully listed. A first backup that takes days continues after
an interruption: if it is stopped by its time limit of 23 hours or by a
worker restart, after it saved a checkpoint, it continues without using up
one of its retries, for up to 21 days after it first started (since 0.3.5),
and a Graph request that gets no answer within 5 minutes is retried.
Since 0.4.7 a backup that Microsoft Graph or the storage still holds back
after all its retries reads "Held back by the service, retried" in amber
instead of "Failed" in red: it is left out of the failed counts, raises no
backup.failed alert and no job.failed webhook, and
the next scheduled run tries again (an object held back for longer is caught
by the overdue and readiness rules). A background job also honours a
Retry-After of up to 5 minutes (before 0.4.7, about a minute).
Items that Microsoft reports incompletely, without a name or without their folder, are listed as warnings with the cause "Microsoft reported the item incompletely"; this usually happens while an item is being moved, renamed or uploaded, and the next run tries again. A user without a OneDrive that Restow can reach, because there is no licence that includes OneDrive or the user never opened it, is reported as "This user has no OneDrive that Restow can reach", with what to do.
A OneDrive that Microsoft locked is a related case, and a licence that was
removed is the usual reason for both. Microsoft locks the OneDrive of an
unlicensed account after a while and then answers every request with HTTP
423 ("Access to this site has been blocked"). Since 0.4.7 such a OneDrive no
longer fails every night as "Microsoft rejected the request": after one cheap
read confirms the lock, it reads "Not backed up: locked", a neutral state
with no retries, no failed count, no red readiness because of age, not
overdue and no backup.failed alert, and the scheduler stops
planning it. Existing backups are kept. The directory sync resumes the
OneDrive only when a read of the drive succeeds again, and otherwise keeps
the lock. A 423 that this read does not confirm stays a counted failure, and
a 423 on a single file stays a problem of that item. Like every object
Restow stops backing up, a locked OneDrive first reads amber "Not backed up
any more, please confirm" until an administrator confirms "Yes, intended"
(readiness stays at least yellow until then); a confirmed one reads grey
"Intentionally no longer backed up", and backups resume by themselves when
the lock is lifted. A restore into the original location of a locked
OneDrive is refused with the reason: restore into another account or
download the data instead.
A OneDrive whose drive Microsoft Graph no longer finds (the user was deleted, or the retention period is over) is reported with the cause "This user has no OneDrive that Restow can reach" as a permanent error that is not retried, instead of as a failed item (since 0.4.7). An item that failed and came through later in the same run, listed twice in a delta feed or retried, no longer stays among the failures. Files that a host sends compressed are no longer taken for truncated downloads, and cancelling a job during a throttling wait no longer records items as failed.
Restore
In the Restore explorer (since 0.4.2) each person is one entry: mailbox, OneDrive and an assigned IMAP account together, with "OneDrive" in the second column next to mail, calendar and contacts, each with the restore points of its own object. The OneDrive of an account that was deleted stays in the list under its owner's name, marked "Account deleted", with every restore point it ever made. Since 0.4.4 the folder lists of a large OneDrive come from an index and open in milliseconds, not in seconds to minutes. A search covers names and paths at the selected point in time.
- Original location. The file goes back into the OneDrive it came from. If a file of that name exists, "Keep both" (the default) restores it under a new name and "Skip existing" restores only what is missing.
-
Another account. Into the OneDrive of another user of the
same tenant (the user's UPN or the drive ID; add
:/Folderto restore into a subfolder). Offered to restore operators and tenant administrators. - Download as ZIP. Files as they are, with a checksum list, from a link that is valid for 24 hours.
A restore never overwrites a file that exists in a OneDrive. Large files go up in upload sessions, and Restow compares size and hash of what it wrote with the backup; an item whose confirmation does not match is shown as "Not confirmed". An earlier version that OneDrive itself kept is offered as a download only. A user with the role "user" restores only their own OneDrive. When an administrator restores someone else's data, the dialog asks for a reason, and the audit log records the restore as done on behalf of that person.
Proven restorable, and watched for ransomware
A restore check, set in the backup job (weekly by default), reads a random sample of the latest restore point back through the restore path, up to 20 files of a OneDrive, and compares their size and hash with the manifest. Each OneDrive is rated in Recovery readiness next to mailboxes and machines; see the verification page.
Every new restore point is also judged for signs of ransomware. For a OneDrive all signal families are available: the amount of change, deletions, renamed extensions, file names and entropy, and compression and deduplication. Details on the ransomware detection page. With immutable backups switched on for the tenant's repository, the data of OneDrives is locked like that of mail (see storage).
What it needs
- A Microsoft 365 source. It connects in one of three ways: through the consent invitation of the shared backup app; through a Graph app of your own for that source (since 0.2.2); or, for the tenant the backup app itself lives in, with a direct connection that needs no consent link (provider owners only). The details are on the overview page, under connecting a Microsoft 365 source.
-
The permission
Files.ReadWrite.All(OneDrive backup and restore through upload sessions), next to the other application permissions of a Microsoft 365 source, with an administrator's consent. A permission that an administrator grants to the app later takes effect without a new client secret: since 0.4.7, when Graph answers 401 or 403, Restow fetches a new token once and sends the request again, at most once a minute per tenant or source. -
Network. Outbound HTTPS (443) from the Restow server to
login.microsoftonline.com,graph.microsoft.comand the tenant's SharePoint hosts, for OneDrive<tenant>-my.sharepoint.com, where Graph hands out the short-lived download URLs and the upload sessions. - A licence that includes OneDrive for each user, and a OneDrive that was provisioned (the user opens it once). If the licence is removed, Microsoft locks the OneDrive after a while (see above).
Stated limits, not hidden ones
- OneDrive backup and restore have not yet been run against a real Microsoft 365 tenant in the release checks. They are covered by tests against a simulated Graph API, the detection of a locked OneDrive included. An answer of Microsoft that Restow does not recognise as a lock stays a counted failure. Restow is a beta: run it beside your existing backup, and restore a few files by hand before you rely on it.
- The sharing and the permissions of OneDrive items are saved as information and never restored.
- Restore never overwrites an existing file, and an earlier version that OneDrive kept can only be downloaded.
- The first backup of a large OneDrive or tenant can take days because of Graph throttling, and the run shows the wait. A backup that Microsoft or the storage still holds back after all its retries reads "Held back by the service, retried" and is tried again at the next scheduled run.
- Only the OneDrives of the users of a connected Microsoft 365 tenant are sources. A OneDrive of a personal Microsoft account is not.
Editions
OneDrive backup and restore are part of the Community core and therefore in every edition: Community, Business and Service Provider. The Community edition is free and has no mailbox limit. For what each edition adds, see pricing.
Frequently asked
Does Restow back up OneDrive?
Yes, since 0.1.0 and in every edition. It backs up the OneDrive of each protected user of a Microsoft 365 tenant through Microsoft Graph, incrementally with Graph's delta queries, into storage you choose, and restores a file, a folder or a whole OneDrive. It was tested against a simulated Microsoft Graph, not against a real Microsoft 365 tenant, and Restow is a beta.
Is the backup incremental, and how long does the first one take?
After the first full run, a run reads only what changed since the last one, deletions included. The first backup of a large OneDrive or tenant can take days, because Microsoft throttles the Graph API; Restow respects the wait Microsoft asks for and shows it. The run shows "X items so far" until the OneDrive is fully listed, because Microsoft names the item count only after the full listing. A backup that is interrupted by its time limit of 23 hours or by a worker restart, after it saved a checkpoint, continues without using up a retry, for up to 21 days (since 0.3.5). Since 0.4.7 a backup that Microsoft Graph or the storage still holds back after all its retries reads "Held back by the service, retried" (amber, not counted as failed) and is tried again at the next scheduled run.
Does Restow keep older versions of a file?
Each backup run gives a restore point, and the Restore explorer shows how a file looked at each of them (identical content in consecutive restore points is shown once). Where Restow captured the earlier versions that OneDrive itself keeps, they are listed as "Earlier versions kept by OneDrive" and can be downloaded; they cannot be restored in place.
Can I restore a file that was deleted from OneDrive?
Yes, from a restore point made before the deletion. In the version history a deleted file is marked "Deleted" from the restore point in which Microsoft reported the deletion, and you restore it from an earlier one. How long restore points are kept is set by the retention of the backup job.
Does a restore overwrite files in OneDrive?
No. Restore is built to be non-destructive: when a file already exists, "Keep both" (the default) restores it under a new name and "Skip existing" leaves it as it is and restores only what is missing. There is no mode that overwrites an existing file in a OneDrive, and the API refuses one.
Which permissions and network access does it need?
The backup app needs the Microsoft Graph application permission Files.ReadWrite.All (OneDrive backup and restore through upload sessions) next to the other permissions of a Microsoft 365 source, and an administrator's consent. The Restow server needs outbound HTTPS (443) to login.microsoftonline.com and graph.microsoft.com and to the tenant's SharePoint hosts, for OneDrive <tenant>-my.sharepoint.com, where Graph hands out short-lived download URLs and upload sessions. A permission that an administrator grants to the app later takes effect without a new client secret (since 0.4.7).
Can users restore their own files?
Yes. A tenant member with the role "user" signs in and sees and restores only their own mailbox, OneDrive and IMAP account, matched by e-mail address. An administrator who restores someone else's OneDrive gives a reason, and the audit log records the restore as done on behalf of that person.
What if a user has no OneDrive?
Restow reports it with the cause "This user has no OneDrive that Restow can reach": the user has no licence that includes OneDrive, or OneDrive was never provisioned because the user never opened it. Give the user a licence and let them open OneDrive once, or exclude the drive from protection. A OneDrive that Microsoft locked is a related case, usually after the licence was removed: Microsoft then answers every request with HTTP 423. Since 0.4.7 Restow confirms the lock with one cheap read, reads "Not backed up: locked" (neutral, no retries, no failed count, no backup.failed alert), stops planning the OneDrive and keeps its existing backups; the directory sync resumes it only when a read of the drive succeeds again. Like every object Restow stops backing up, it first reads amber "Not backed up any more, please confirm" until an administrator confirms "Yes, intended". The detection of locked objects was tested against a simulated Graph API, not a real tenant.
Does it back up a private OneDrive of a personal Microsoft account?
No source type exists for it. Restow connects Microsoft 365 tenants, with an administrator's consent, and backs up the OneDrives of the users of that tenant; it does not connect a OneDrive of a personal Microsoft account.
Is OneDrive backup in the Community edition?
Yes. It is part of the Community core and therefore in every edition, and the Community edition has no mailbox limit. Restow is a beta: run it beside your existing backup until you have restored from it yourself.
Documentation
The documentation has the details: connecting sources, backup and restore, the Entra walkthrough with every permission under first steps and the destinations the server must reach under network and ports.