Skip to content

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 useImpact
Outlook backupsNew full backup per mailbox. v5 backups stay readable by snapshot ID only
SharePoint backupsNew full backup per site. v5 backups stay readable by snapshot ID only
OneDrive backupsNo action. Existing snapshots stay usable, but the first backup stores every owner's content again
atlas replicate or atlas rehydrateUpgrade 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 addressesUpdate them. See step 7

What changed ​

Areav5v6
Outlook owner ID in storageLowercased primary SMTP addressMicrosoft Entra object ID of the mailbox
SharePoint site ID in storage<hostname>,<site-guid>,<web-guid><site-guid>,<web-guid>
Content object names, every workloadPlain SHA-256 of the contentHMAC-SHA256 of the content, keyed from the tenant data key
x-plaintext-sha256 metadata header on mailbox objectsPresentRemoved
Commands that read existing SharePoint backups by site IDCall Microsoft GraphWork 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 passAtlas does
A value without @Uses it as the object ID, with no Microsoft Graph call
A UPNLooks it up with GET /users/{address}
A primary SMTP address that is not the UPNLooks 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.

  1. 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.

    bash
    sudo systemctl disable --now atlas-outlook-backup.timer   # each Atlas timer
    crontab -e                                                # comment out each Atlas line

    A 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.

  2. Decide whether to keep the v5 backups. To remove them, run these with v5, before upgrading:

    bash
    atlas 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 bucket

    Objects 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.

  3. Upgrade @wisecom/atlas-cli or @wisecom/atlas-sdk to v6 on every host.

  4. Run a full backup of every mailbox and site:

    bash
    atlas outlook backup -m user@example.com --full
    atlas sharepoint backup --site https://contoso.sharepoint.com/sites/finance

    Passing the object ID to -m skips the Microsoft Graph lookup.

  5. 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:

    bash
    atlas replicate -m user@example.com --target-config ./offsite.json
    atlas replicate --site https://contoso.sharepoint.com/sites/finance --target-config ./offsite.json
  6. Re-enable scheduled runs, including the replication jobs stopped in step 1. Later runs are incremental.

    bash
    sudo systemctl enable --now atlas-outlook-backup.timer    # each Atlas timer
    crontab -e                                                # restore each Atlas line
  7. Update 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 ​

bash
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/finance

The 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 ​

SituationWhat happens
Command with -m or --siteFinds only backups written by v6
Command with -s <snapshot-id> and without -mStill reads v5 backups
atlas outlook listShows each old address path as its own row, with the address in the Owner ID column
Storage useRoughly doubles until the old paths are deleted. Deduplication is per owner path, so the first v6 backup is stored in full
First OneDrive backupStores each owner's content again, because no existing object matches a keyed name. Later runs deduplicate as before
Old objectsStay 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.

bash
atlas outlook restore -s <snapshot-id> -T user@example.com

v5 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:

CommandReaches v5 snapshots
atlas replicate -s <snapshot-id>, atlas rehydrate -s <snapshot-id>Yes
atlas rehydrate --allYes, every path
atlas replicate and atlas rehydrate with -m or --siteNo, 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:

bash
atlas rehydrate -s <snapshot-id> --source-config ./offsite.json
atlas outlook restore -s <snapshot-id> -T user@example.com

A 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 ​