bkp_m365 backs up Exchange mailboxes (mails of all folders as MIME, calendars with attachments, contacts, To Do tasks), OneDrive and SharePoint document libraries through Microsoft Graph. A job covers single accounts or sites (scope=single) or a whole tenant (scope=tenant). Every run is a complete point in time; only what has changed since the previous run is downloaded.
18.1 App registration in Entra ID#
- In the Entra admin center register an app (this tenant only).
- Under API permissions add the application permissions of Microsoft Graph:
User.Read.All,Mail.Read,Calendars.Read,Contacts.Read,Tasks.Read.All,Files.Read.All,Sites.Read.All– and grant admin consent. - Create a certificate and upload the
.crtfile under Certificates & secrets (see below). - Note the tenant ID or domain and the application ID (client ID) for the configuration.
Certificate for the logon
openssl req -x509 -newkey rsa:3072 -nodes -days 730 -subj "/CN=AegisGrid-m365" -keyout m365.key -out m365.crt
cat m365.crt m365.key > /etc/bkp/m365-contoso.pem && chmod 600 /etc/bkp/m365-contoso.pemTip: With scope=single the app should only see the accounts backed up: in Exchange Online with RBAC for Applications, in SharePoint with Sites.Selected instead of Sites.Read.All and a grant per site.
18.2 Setting up a job#
/etc/bkp/bkp_m365.cfg (template: packaging/bkp_m365.cfg.example)
[m365-contoso]
tenant=contoso.onmicrosoft.com
client-id=00000000-0000-0000-0000-000000000000
client-cert=/etc/bkp/m365-contoso.pem
scope=tenant
content=all
exclude=*@ext.contoso.com, svc-*
target=srv1
target-dir=m365
api-key=file:/etc/bkp/m365.key
encryption=aes-256-gcm
encryption-key=file:/etc/bkp/m365-contoso.enc
retention=90dWith --dry-run bkp_m365 only logs on and lists the accounts and sites that would be backed up. After that bkp_m365 --name m365-contoso backs up; regularly by cron or bkp_sched (command=m365, profile=m365-contoso).
| Exit code | Meaning |
|---|---|
| 0 | everything backed up |
| 2 | partly: single accounts, folders or files kept the state of the previous run (messages in the log) |
| 1 | nothing backed up (logon, destination, configuration) |
18.3 Storage, retention and checking#
Every job has an object store of its own (<out>/<job>.m365 or on the server <storage>/<target-dir>/<job>.m365). Identical contents are stored only once; encryption happens at the client, the server sees no key. bkp_maintenance prune --search-dir <directory> deletes expired runs (the newest stays) and then the objects no run needs any more; bkp_maintenance scrub --store <dir>/<job>.m365 checks a store. repair, mirror and export work as with block stores (Chapter 10).
18.4 Exporting#
Runs, contents and export
bkp_m365_restore --name m365-contoso --list
bkp_m365_restore --name m365-contoso --browse alice@contoso.com/mail/Inbox
bkp_m365_restore --name m365-contoso --export /srv/export --user 'alice*' --section mail --from 2026-09-01Mails are exported as .eml, files as a file tree with modification time, events and tasks as .ics, contacts as .vcf (with photo) for Outlook, Thunderbird, Apple and Google; --export-format json gives the Graph JSON. --item/--item-file limit the export to chosen folders and items. Back into Microsoft 365: Chapter 19.