Migrating to v6
Atlas 6 stores Outlook and SharePoint backups under new paths and renames content objects in every workload. Backups written by v5 are not migrated: after the upgrade, commands that select a mailbox or site do not find them. Plan the upgrade as a fresh full backup of every mailbox and site.
Who is affected
| You use | Impact |
|---|---|
| Outlook backups | New full backup per mailbox. v5 backups stay readable by snapshot ID only |
| SharePoint backups | New full backup per site. v5 backups stay readable by snapshot ID only |
| OneDrive backups | No action. Existing snapshots stay usable, but the first backup stores every owner's content again |
atlas replicate or atlas rehydrate | Upgrade the replication host too, and replicate the new backups. See Replication targets |
| Scripts or SDK code that build object paths or compare owner IDs with email addresses | Update them. See step 7 |
What changed
| Area | v5 | v6 |
|---|---|---|
| Outlook owner ID in storage | Lowercased primary SMTP address | Microsoft Entra object ID of the mailbox |
| SharePoint site ID in storage | <hostname>,<site-guid>,<web-guid> | <site-guid>,<web-guid> |
| Content object names, every workload | Plain SHA-256 of the content | HMAC-SHA256 of the content, keyed from the tenant data key |
x-plaintext-sha256 metadata header on mailbox objects | Present | Removed |
| Commands that read existing SharePoint backups by site ID | Call Microsoft Graph | Work offline, including for sites already deleted from SharePoint |
The owner ID is part of every object path of that owner: content, snapshots, sync checkpoints (Microsoft Graph delta links), and replication state all move to the new path. Nothing is aliased, migrated, or read through a fallback.
Outlook: object ID instead of address
The object ID survives a primary address rename and a conversion to a shared mailbox. A renamed mailbox keeps its path, the next run stays incremental, and the catalog shows one mailbox instead of two. OneDrive already used object IDs, so both workloads now work the same way.
-m and the SDK mailboxId still accept an address. The address is kept only as display metadata on snapshots.
| You pass | Atlas does |
|---|---|
A value without @ | Uses it as the object ID, with no Microsoft Graph call |
| A UPN | Looks it up with GET /users/{address} |
| A primary SMTP address that is not the UPN | Looks it up with GET /users?$filter=mail eq '{address}' after the first lookup returns 404 |
A secondary alias (neither UPN nor primary mail) | Fails to resolve. Pass the object ID instead |
For restore, -m or -s selects the backup to read and -T, --target selects the mailbox to write into. -T accepts an address or an object ID.
SharePoint: site ID without the hostname
--site still accepts a site URL, or a site ID with or without the hostname. Storage uses only <site-guid>,<web-guid>, so a tenant hostname change no longer orphans backups.
save, verify, list-snapshots, list-versions, stats --site, and the restore source no longer call Microsoft Graph, so backups of a site already deleted from SharePoint stay reachable. backup and --target-site still look the site up in Microsoft Graph.
All workloads: keyed content object names
In v5, anyone with read access to the bucket could hash a known file and check whether an owner had stored it, without the passphrase. In v6, each content object is named by an HMAC-SHA256 of its content, keyed with a naming key that Atlas derives from the tenant data key (HKDF-SHA256, info atlas/object-name/v1). A name cannot be computed without the data key. See What object names reveal.
Snapshots still record the plain SHA-256 inside their encryption, and restore, save, and verify follow each snapshot entry to its object, so v5 objects stay readable from v5 snapshots.
What you must do
Upgrade every host that runs Atlas against the same bucket in the same window, including the host that drives replication. A host left on v5 keeps writing under the v5 paths, which v6 -m and --site commands do not see, and recreates the paths you delete in step 2.
Stop scheduled runs on every host. Disable cron entries, systemd timers, any service that calls the SDK on a schedule, and replication jobs. Then wait for running jobs to exit, so none finishes on the old version after the upgrade.
bashsudo systemctl disable --now atlas-outlook-backup.timer # each Atlas timer crontab -e # comment out each Atlas lineA v5 run between steps 2 and 3 recreates the v5 paths. A v6 run before you finish step 4 starts a full backup you did not plan for.
Decide whether to keep the v5 backups. To remove them, run these with v5, before upgrading:
bashatlas outlook delete -m user@example.com -y # one mailbox atlas sharepoint delete --site https://contoso.sharepoint.com/sites/finance -y atlas delete --purge # whole tenant bucketObjects still under Object Lock retention are reported as retained and the command exits
1. Keep v5 installed until a delete completes with no retained objects, or until retention expires. These commands act on the primary bucket only. To remove v5 data from a replication target too, see Replication targets.Upgrade
@wisecom/atlas-clior@wisecom/atlas-sdkto v6 on every host.Run a full backup of every mailbox and site:
bashatlas outlook backup -m user@example.com --full atlas sharepoint backup --site https://contoso.sharepoint.com/sites/financePassing the object ID to
-mskips the Microsoft Graph lookup.Replicate the new backups, if you use replication. The first run per mailbox and site copies the whole new path, about the volume of the full backup:
bashatlas replicate -m user@example.com --target-config ./offsite.json atlas replicate --site https://contoso.sharepoint.com/sites/finance --target-config ./offsite.jsonRe-enable scheduled runs, including the replication jobs stopped in step 1. Later runs are incremental.
bashsudo systemctl enable --now atlas-outlook-backup.timer # each Atlas timer crontab -e # restore each Atlas lineUpdate scripts and SDK callers that build object paths or compare owner IDs with email addresses. Owner IDs are now object IDs for Outlook and hostname-free site IDs for SharePoint.
Confirm the upgrade worked
atlas outlook list # new rows show the object ID as Owner ID
atlas outlook status -m user@example.com # reports the v6 backup as the last one
atlas sharepoint list-snapshots --site https://contoso.sharepoint.com/sites/financeThe first scheduled run after the full backup is incremental. If a mailbox address does not resolve, see Troubleshooting.
Working with v5 backups after the upgrade
| Situation | What happens |
|---|---|
Command with -m or --site | Finds only backups written by v6 |
Command with -s <snapshot-id> and without -m | Still reads v5 backups |
atlas outlook list | Shows each old address path as its own row, with the address in the Owner ID column |
| Storage use | Roughly doubles until the old paths are deleted. Deduplication is per owner path, so the first v6 backup is stored in full |
| First OneDrive backup | Stores each owner's content again, because no existing object matches a keyed name. Later runs deduplicate as before |
| Old objects | Stay in the bucket until deleted. Object Lock retention blocks deletion until it expires and never removes objects by itself |
To restore a v5 Outlook snapshot, pass its snapshot ID without -m. The ID is in the old snapshot path, manifests/{address}/{snapshot-id}.json.
atlas outlook restore -s <snapshot-id> -T user@example.comv5 object names stay guessable until deleted
v5 objects keep their plain SHA-256 names, so the file-confirmation check described above still works against them. Deleting a snapshot with -s removes only its snapshot record, not its content. To remove the objects, delete the owner's whole backup (atlas onedrive delete, or the v5 deletions in step 2) and take a fresh full backup.
Replication targets
Atlas 7 removes atlas replicate and atlas rehydrate, and replicas are made by the storage provider. See Migrating to v7. This section applies while you run v6.
Targets need no upgrade of their own: they are buckets, and only the host that runs atlas replicate or atlas rehydrate is upgraded. Replication copies one way and never deletes, so a target keeps every v5 snapshot it received, including those you delete from the primary bucket in step 2.
After the upgrade, replicated v5 snapshots follow the same rules as v5 snapshots on the primary bucket:
| Command | Reaches v5 snapshots |
|---|---|
atlas replicate -s <snapshot-id>, atlas rehydrate -s <snapshot-id> | Yes |
atlas rehydrate --all | Yes, every path |
atlas replicate and atlas rehydrate with -m or --site | No, v6 paths only |
restore, save, and verify read the primary bucket only. To restore a v5 snapshot held only on a target, copy it back first, then read it by snapshot ID:
atlas rehydrate -s <snapshot-id> --source-config ./offsite.json
atlas outlook restore -s <snapshot-id> -T user@example.comA disaster recovery drill brings deleted v5 data back
rehydrate --all copies back any v5 snapshot missing from the primary bucket, including every snapshot you deleted there in step 2. If you do not want to keep the v5 data, delete it on each target too. The delete commands have no target flags, so run the step 2 commands with v5, with ATLAS_S3_ENDPOINT, ATLAS_S3_ACCESS_KEY, and ATLAS_S3_SECRET_KEY set to the target's values for that shell.
Deleting on a target is permanent
Once deleted on a target, those snapshots can no longer be rehydrated from it. atlas delete --purge also removes the target's wrapped data key.
Replication between a v5 host and a v6 host is not supported. A v5 host keys mailboxes by address and sites with the hostname, so its -m and --site runs never select v6 snapshots, and the target silently stops receiving new backups.
See also
- Concepts for how owners and snapshots are organized.
- Storage layout for the full object path structure.
- Replication for copy order and rehydration.
- Scheduling and bandwidth for the cron and systemd setup the upgrade pauses.
- CLI reference and SDK reference.
- Troubleshooting for owner lookup and Object Lock errors.

