OneDrive

Bacula Enterprise Microsoft 365 Plugin can protect OneDrive Business units associated to users, groups or sites. It is possible to utilize advanced selection methods to decide exactly what is backed up, as well as control precisely which items to restore and their destinations. The information protected with this service is:

• Files

• File versions

• Items M365 metadata (files and folders)

• Shared permissions

Files will keep their names in the catalog and will be included in a path like this:

• /@m365/tenant.name/entitykind/ownerentityname/drives/unitname/root:/path/to/file/name-file.extension

  (where entitykind can be users, sites or groups)

Version History

OneDrive and SharePoint can be configured to retain the history for files/items.

Onedrive hash check

Onedrive service stores a hash for every file hosted, using Microsoft algorithm QuickXOR. Bacula Enterprise Microsoft 365 Plugin calculates this hash and compares it to the Microsoft hashes at backup time, and also at restore time in order to ensure data integrity. Debug mode shows information about these hashes.

Onedrive shares

Bacula Enterprise Microsoft 365 Plugin is able to backup and restore shared elements. These kind of elements require a special treatment, as they are composed of two parts:

• In the source account, shared elements include special information about the permissions of the share (who and how the share must work)

• In the destination account, shared elements appear within an special category called ‘SharedWithMe’.

  • SharedWithMe elements are not directly accessible from the destination account, as they are links to the source account. Therefore, Bacula Enterprise Microsoft 365 Plugin will query the source account in order to get these elements when they are part of the backup target. The source of those files must be located inside the same tenant the plugin is protecting, otherwise it will not be able to access them.

  • SharedWithMe elements need ‘delegated permissions’ to be accessed. It means the account having the elements will need to login (during the backup or using the .query parameter=login method) in order to access those files. As a result, please, think carefully if you need to back up them with this mechanism or if it’s not necessary. By default, backing up these elements is disabled. Note that if you backup both accounts (source of share and destination of share), you don’t really need to enable this function. If you are backing up all users from your tenant, this is definitely not needed.

Shared permissions

Bacula Enterprise Microsoft 365 Plugin will query for the permissions of an item if this item has been shared directly. This means the plugin will not backup inherited permissions. In order to have inherited permissions in a backup, the top element where the original shared permissions were set needs to be included in the backup and in the restore. As an example, if a directory is shared but we restore only specific files contained in it, those files will not be shared as they were in originally. It is necessary to restore the whole directory in order to replicate the original inherited permissions as they were at the time of backup.

The method to store shared permissions is to include them as ‘extended_attributes’ of every file. This implies that permissions can only be restored directly to the Microsoft 365 service. A File Daemon restore to a local filesystem will only restore files, and shared permissions will not be restored.

Shared permissions can include links. Links are pre-generated URLs that can include, password, expiration dates and other configuration parameters as scopes, types, or affected identities. Shared permissions restores have special characteristics that must be considered and they are described below:

• Permission will be generated exactly as it was, but it will be a new permission object. This is similar to the situation with files. A restored file has the same contents as the original, but can include slightly different metadata because creation process was different.

  • If permission had a static link, a link will be generated, but the associated URL will be different from the original.

  • If a link had a password, the password will not be restored. Every link will be restored without a password (restore job log will warn about all links that had a password)

    • This is a limitation of OneDrive Business, as it does not allow passwords to be generated from APIs.

• Permissions can send a notification message to destination users.

  • This is configured at restore time with a parameter. Consequently, if different shares require different treatment, different restore sessions will be needed.

• Possible unexpected problems with permissions at restore time are treated as Warnings, not as Errors - as long as the file was restored successfully.

Shared permissions are not restored by default. You need to enable the option ‘drive_restore_shared_permissions’ during the restore session.

Shared with me

SharedWtihMe elements of each target account, if included in the FileSet, are backed up in a predefined directory called SharedWithMe inside the top folder of every selected account. For example, for a given account youraccout@yourdomain.com in a tenant called yourtenant:

SharedWithMe

``/@m365/yourtenant/users/youraccout@yourdomain.com/drive/onedrive/root:/sharedWithMe/``

At restore time, sharedWithMe elements are treated as any other regular file. However, it is important to note that sharedWithMe files, as we are in the receiver account, have no share permissions.

SharedWithMe elements included for backup are only the ones belonging to the current tenant. Backup of sharedWithMe elements from external tenants are not supported.

The plugin has an special parameter at restore time allowing it to skip sharedWithMe elements even if they are selected. This feature is intended to facilitate full restores where source and destination accounts are included. Please, note that a restore of a source account with share elements will present those elements to any receiver account if you enable the option to restore share permissions, as we have discussed in 3.2.1.

Please, be aware that restoring permissions from the plugin will generate automatic M365 reporting emails in the user Inbox as the following example shows:

Restored permissions warning message

Please, go to the Configuration section of this document to see how to set up the sharedWithMe skip option.

Note

If you enable the backup for file versions (Calendars) and sharedwithme elements, sharedwithme elements will include all their versions in the backup.

Backup parameters

The list below shows the specific backup parameters that can be set up in order to control the behavior of the drive module.

In order to select the drive module, the common service parameter must be equals or be containing the value drive.

Entities that can include one drive units are: users, groups or sites.

Option	Required	Default	Values	Example	Description
drives	No		Valid names or ids of existing drives on the selected tenant belonging to the selected entity (user, group or site) separated by ,	documents, images, b!12344490zcdfs09ewrqwf	Will backup only selected drive units belonging to the specified entity (user, group or site)
drives_exclude	No		Valid names or ids of existing drives on the selected tenant belonging to the selected entity (user, group or site) separated by ,	onedrive	Will backup all drives except the excluded in this lists, belonging to the specified entity (user, group or site)
drives_regex_include	No		Valid regex	*.pages	Backup matching drive units (based in the drive unit name)
drives_regex_exclude	No		Valid regex	^site.*	Exclude matching drive units (based in the drive unit name)
drive_files	No		Strings representing existing folders for the given users separated by ,	Customers, Partners	Backup only specified folders belonging to the selected users
drive_files_exclude	No		Strings representing existing folders for the given users separated by ,	Personal	Exclude selected folders belonging to the selected users
drive_files_regex_include	No		Valid regex	.*Company	Backup matching drive files or folders. If you provide list parameters (files + files_exclude) combined with regex ones, be aware that regex ones are applied after list parameters
drive_files_regex_exclude	No		Valid regex	.*Plan	Exclude matching drive files or folders from the selection. If you provide list parameters (files + files_exclude) combined with regex ones, be aware that regex ones are applied after list parameters. If this is the only parameter found for selection, all elements will be included and this list will be excluded.
drive_system_include	No	No	0, no, No, false, FALSE, false, off ; 1, yes, Yes, TRUE, true, on	Yes	Include system documentLibraries of sharepoint (sitepages, siteassets, etc).
drive_shared_with_me	No	No	0, no, No, false, FALSE, false, off ; 1, yes, Yes, TRUE, true, on	Yes	Include SharedWithMe elements of every target entity in the backup process
drive_version_history	No	No	0, no, No, false, FALSE, false, off ; 1, yes, Yes, TRUE, true, on	Yes	Include Onedrive former versions of every file into the backup process
drive_permissions	No	Yes	0, no, No, false, FALSE, false, off ; 1, yes, Yes, TRUE, true, on	No	Include Onedrive files sharing permissions as part of the backup. If you need higher performance, it is recommended to disable this option
drive_disable_hashcheck	No	No	0, no, No, false, FALSE, false, off ; 1, yes, Yes, TRUE, true, on	No	Disable the hash checking mechanism for each file downloaded. This is only recommended for documment libraries where the hash stored at M365 level is detected to be incorrect for an important number of files (specially in sharepoint jobs)

• Note: In previous versions, instead of drive_files* parameters, it was possible to use files_* parameters. They are deprecated parameters now as we recommend to use module specific parameters in order to have better control and more possibilities inside a single fileset. However, jobs using files_* parameters will still work.

• Note: In previous versions, drive_shared_with_me was enabled by default. However, Microsoft changed at some point the permissions of these elements and now they are only accessible through delegated permissions. Delegated permissions require a more complex operation, while sharedWithMe elements are only needed in some particular

use cases (such as protecting only a sub-set of users). Therefore, this now disabled by default (since Bacula 18.0.4)

Restore

The list below shows the subset of restore parameters that can be used to control the behavior of onedrive module restore operations:

• destination_user, destination_group, destination_site, destination_drive, destination_path, send_report, allow_duplicates

• drive_skip_sharedwitme, skip_versions, restore_share_permissions, drive_send_invitations, drive_invitations_message

• debug, foreign_container_generation

Use cases

The following restore scenarios are supported:

• Restore files, directories, or file versions to original entity drive or to a different entity drive

  • Restore parameters implied: destination_user, destination_group, destination_site

• Restore file(s)/dir(s) or file version(s) to original path or to a different path

  • Restore parameters implied: destination_path

• Restore file(s)/dir(s) or file version(s) to original drive unit or to a different drive unit

  • Restore parameters implied: destination_drive

• Restore file(s)/dir(s) or file version(s) to local file system (general restore where parameter must be set to a path)

• It is possible to make general restore selections, but avoid restoring versions

  • Restore parameters implied: skip_versions

• It is possible to restore sharing permissions of implied files

  • Restore parameters implied: restore_shared_permissions, drive_send_invitations, drive_invitations_message

• It is possible to make general restore selections, but specify if backed up shared elements must be considered

  • Restore parameters implied: drive_skip_sharedwitme

• It is possible to control whether or not duplicate elements are allowed (based on file id):

  • Restore parameters implied: allow_duplicates

Particularities:

• If no destination entity is provided, the destination entity will be looked for inside the backed up path, so the destination user will be the same as the original one

• If no destination_path is provided, the destination path will be the same as the original one

  • If a destination entity was provided, but no destination_path was provided and the selected file did not belong to the destination entity:

    • A new folder will automatically be created inside the target entity

    • For each ‘foreign’ entity, a new folder will be created

    • Inside each ‘foreign’ entity folder, the original path structure will be preserved when restoring the files

      • *Unless the parameter foreign_container_generation is disabled

For more details about the behavior of each parameter, please check the general section of restore parameters.

Fileset examples

Full OneDrive of one user:

Fileset Example

FileSet {
   Name = fs-m365-drive-adelev
   Include {
      Options { signature = MD5 }
      Plugin = "m365: service=drive tenant=57uia43-d107-17a2-a2g2-aa53c10tdahc objectid=56ddf1h9-eb5d-
   42nf-bac7-7b019fd284g5 user=adelev@baculaenterprise.onmicrosoft.com"
   }
}

Folders of one user, but include sharedWithMe elements:

Fileset Example

FileSet {
   Name = fs-m365-drive-adelev-shared
   Include {
      Options { signature = MD5 }
      Plugin = "m365: service=drive tenant=57uia43-d107-17a2-a2g2-aa53c10tdahc objectid=56ddf1h9-eb5d-
   42nf-bac7-7b019fd284g5 user=adelev@baculaenterprise.onmicrosoft.com drive_files=\"dir1,dir2\"
   drive_shared_with_me=yes"
   }
}

Full OneDrive of one group, include version history:

Fileset Example

FileSet {
   Name = fs-m365-drive-devteam-versions
   Include {
      Options { signature = MD5 }
      Plugin = "m365: service=drive tenant=57uia43-d107-17a2-a2g2-aa53c10tdahc objectid=56ddf1h9-eb5d-
   42nf-bac7-7b019fd284g5 group=\"Dev Team\" drive_version_history=true"
   }
}

Full OneDrive of one sharepoint site:

Fileset Example

FileSet {
   Name = fs-m365-drive-live
   Include {
      Options { signature = MD5 }
      Plugin = "m365: service=drive tenant=57uia43-d107-17a2-a2g2-aa53c10tdahc objectid=56ddf1h9-eb5d-
   42nf-bac7-7b019fd284g5 site=\"Live @ MyEnterprise\""
   }
}

Specific drives of a sharepoint site, including some system:

Fileset Example

FileSet {
   Name = fs-m365-drive-live-2-drives
   Include {
      Options { signature = MD5 }
      Plugin = "m365: service=drive tenant=57uia43-d107-17a2-a2g2-aa53c10tdahc objectid=56ddf1h9-eb5d-
   42nf-bac7-7b019fd284g5 site=\"Live @ MyEnterprise\" drive_system_include=yes drives=b!7Tf3z7izSES7kjOHD-YM-
   0kScgNXL6lFnL4O2LWLMy4yH2tqunhTSpSwmPR5a0hq,b!7Tf3z7izSES7kjOHD-YM-0kScgNXL6lFnL4O2LWLMy41XlWc2E0pTKfPzlKxhztE"
   }
}

Exclude directories of two users:

Fileset Example

FileSet {
   Name = fs-m365-drive-adjon-users-notemp
   Include {
      Options { signature = MD5 }
      Plugin = "m365: service=drive tenant=57uia43-d107-17a2-a2g2-aa53c10tdahc objectid=56ddf1h9-eb5d-
   42nf-bac7-7b019fd284g5 user=\"adelev@baculaenterprise.onmicrosoft.com,jonis@baculaenterprise.onmicrosoft.com\"
   drive_files_exclude=\".*.temporary\""
   }
}

Exclude mp3 files and avi files:

Fileset Example

FileSet {
   Name = fs-m365-drive-exclude
   Include {
      Options { signature = MD5 }
      Plugin = "m365: service=drive tenant=57uia43-d107-17a2-a2g2-aa53c10tdahc objectid=56ddf1h9-eb5d-
   42nf-bac7-7b019fd284g5 user=\"adelev@baculaenterprise.onmicrosoft.com,jonis@baculaenterprise.onmicrosoft.com\"
   drive_files_exclude=\".*.mp3|.*.avi\""
   }
}