bkp_m365_restore --to-tenant writes a backed-up run back into Microsoft 365: mails, events, contacts and tasks into the mailboxes, files into OneDrive and the SharePoint libraries. By default to the original place; what is already there stays unchanged. Without Microsoft 365, --export gets the same contents as files (Chapter 18, “Exporting”).
19.1 Restore app in Entra ID#
The backup app may only read. Writing back needs a second app registration with write permissions; so a backup run can never change anything in the tenant. Without it, --to-tenant refuses with a sentence that says what is missing.
- In the Entra admin center register another app (this tenant only), e.g. “AegisGrid Restore”.
- Under API permissions add the application permissions of Microsoft Graph and grant admin consent:
Mail.ReadWrite,Calendars.ReadWrite,Contacts.ReadWrite,Tasks.ReadWrite.All,Files.ReadWrite.All,Sites.ReadWrite.All– only those needed for the sections to be written back. - Create a certificate of its own and upload the
.crtfile under Certificates & secrets (as for the backup). - Enter the application ID of the new app in the job's section of
bkp_m365.cfg:
The restore app in the job (the tenant is the same)
[m365-contoso]
tenant=contoso.onmicrosoft.com
client-id=00000000-0000-0000-0000-000000000000 # backup (read only)
client-cert=/etc/bkp/m365-contoso.pem
restore-client-id=11111111-1111-1111-1111-111111111111 # restore app (writing)
restore-cert=/etc/bkp/m365-contoso-restore.pem # or restore-secret=file:/etc/bkp/m365-restore.secret
...restore-client-id must be a different app from client-id. Instead of the certificate restore-secret= works (file:<path> or kms: as for api-key); restore-key= names the private key if it is not in the file of restore-cert. If Microsoft 365 refuses a change, the message names the missing permission.
Tip: As for the backup, the restore app can be limited: in Exchange Online with RBAC for Applications to certain mailboxes, in SharePoint with Sites.Selected (permission write) instead of Sites.ReadWrite.All. If the app is only meant for an emergency, its certificate can be kept in a safe place until then.
19.2 Writing back#
Check first, then write back
bkp_m365_restore --name m365-contoso --list
bkp_m365_restore --name m365-contoso --browse alice@contoso.com/onedrive --json
bkp_m365_restore --name m365-contoso --to-tenant --user alice@contoso.com --section mail --folder 'Inbox*' --dry-run
bkp_m365_restore --name m365-contoso --to-tenant --user alice@contoso.com --section mail --folder 'Inbox*'
bkp_m365_restore --name m365-contoso --run <run> --to-tenant --item-file /tmp/ids.txt --into-folder "Restored"The choice works as for the export: --run (default the newest run), --user, --site, --section, --folder, --path, --from and --to, or exactly chosen folders and items with --item <id> or --item-file <file> (--browse --json shows the ids; a folder takes everything below it). --dry-run writes nothing and counts what a restore would do.
| Option | Effect |
|---|---|
--to-user <upn> | into this user's mailbox or OneDrive instead of the original one |
--to-site <url> | SharePoint libraries into this site instead of the original one |
--into-folder <name> | everything below a new top folder of this name, the original structure below it (events and tasks: one calendar or list of this name) |
--conflict skip | default: an existing item stays as it is |
--conflict copy | written as well; files are then called “Name (restored <date>).ext” |
--conflict overwrite | mails, events, contacts and tasks are replaced (the old one is deleted only once the new one is complete), files get a new version |
--with-attendees | events invite their attendees again |
--json | the result as JSON on stdout (counts, failures with their reason, notes) |
Existing items are recognised like this: mails by their Internet message ID in the destination folder, events by their iCalUId (also after an earlier restore), contacts by name and first mail address, tasks by title and due date, files by their path. Existing folders are always merged.
19.3 What comes back#
- Mails with read state, received and sent time as received mails (not drafts), attachments of any size; missing folders are made by their path.
- Events single and as series in their time zone; changed and deleted occurrences of a series are applied again, attachments come along. By default without invitations: organizer and attendees are listed at the top of the event's text, nobody gets a mail. Only with
--with-attendeesdo invitations go out. - Contacts with their photo, in their contact folders; tasks in their To Do lists. Missing calendars, folders and lists are made.
- Files in OneDrive and SharePoint with folder structure and modification time; large files in pieces. A library goes into the same library of the site, else into one of the same name, else into a folder of its name in the default library.
Note: Sharing links and permissions of files are not restored. Whoever had shared a file shares it again after the restore. An event whose attachment could not be written back is removed again and reported as failed; item attachments (a mail in an event) and references to files cannot be written back.
19.4 Result and exit codes#
At the end it says per kind how many items were written back, skipped and failed; every failure with its path and a reason people understand. A single failure does not stop the restore.
| Exit code | Meaning |
|---|---|
| 0 | everything written back or skipped as existing |
| 3 | partly: some items failed (each one in the log and the result); export: some items not exported |
| 1 | nothing written back (logon, restore app, destination, choice) |
| 4 | --browse: the run, source, section or folder does not exist |
19.5 In the administration console#
For a Microsoft 365 job of a Linux scheduler, “Job” › “Restore Microsoft 365...” opens the dialog for it (token with the role admin; if allowed-commands= in the section [api] of bkp_sched.cfg does not name m365-restore, the dialog says so when starting).
- Backup: the runs, newest first; incomplete ones are marked.
- User or site and below it the tree “What to restore”: the sections with their folders, calendars, lists and libraries. A checked folder brings back everything in it; OneDrive and libraries show their folders when opened.
- Into Microsoft 365 with “Into another user” or “Into another site”, “Into a folder of its own” (default “Restored <date>”), the rule for existing items, invitations and “Only check”. “Overwrite” asks first.
- Save as files on the client: a folder on the scheduler's computer, standard files (
.eml,.ics,.vcfand the files themselves) or JSON.
“Restore” creates the job <name>-restore and starts it; the log opens. Result and history are in the run list as for any job, “Partial” with the items that failed.