Configuration

Authorization

The first step in order to use the Bacula Enterprise Microsoft 365 Plugin is to authorize it to handle data of the target tenant to backup.

There are two possible strategies in order to allow the communication between the Bacula Enterprise Plugin and your tenant:

  • Method A (DEPRECATED): Common app model

    • Register the pre-existing Bacula Systems bacula-m365-plugin Azure AD app into your tenant.

    • The communication will happen through this multi-tenant application.

    • Application Id and associated secrets are internal to the plugin.

    • Microsoft Graph limits associated to an application are common for everyone using this application (multi-customer).

    • For future new permissions you just need to click on ‘Grant permissions’ from Azure AD enterprise apps section

  • Method B (RECOMMENDED): Standalone app model

    • Register the pre-existing Bacula Systems bacula-m365-registratror Azure AD app into your tenant. Then add a standalone application in your tenant.

    • Then add your own standalone application in your tenant calling the appropriate automatic command from bconsole

    • A bacula-m365-plugin-standalone Azure AD application will be created specifically for your tenant. The communication will happen through it.

    • Application Id and associated secrets need to be correctly set and they can be managed by you.

    • Microsoft Graph limits associated to an application are specific to your standalone application

    • For future new permissions you need to re-run the bconsole add-app command (which uses bacula-m365-registrator) or do it yourself manually

To walk through the process described in Method B with the help of a video, click on the image below:

M365 Video

Note

Authentication Method B is only available from Bacula Enterprise 12.8.2

The first method is simpler and faster to setup, however it is only advised for testing purposes. The second method needs a few extra variables to manage and it is recommended for medium or large environments. It is more secure and it can offer better performance.

Backup and restore operations will be using in general the ‘Application permissions’ model, where the application has enough privileges to perform all the operations without impersonating any user. However, some specific modules need to employ ‘Delegated permissions’. To know more about them, please go to delegated-permissions

Note

Starting from Bacula Enterprise version 14.0 you can also perform these authorization tasks directly using BWeb, to see more details, please go to section bweb-console

The sections below will show how to use both methods. For any of them, the first step is to find your Tenant ID:

How to find the Tenant ID

In order to find the Tenant ID you only need to login to the Azure portal (portal.azure.com) and take a look at the ‘Overview’ page of the service Azure Active Directory. Just click in the service as the below image shows:

Azure Active Directory

Once there, you will find the Tenant ID in the box highlighted in the below image:

Tenant ID

Authorization Method A: Common app model with ‘bacula-m365-plugin’ (DEPRECATED)

Bacula Systems has a registered application in Azure AD named bacula-m365-plugin. This section will show how to authorize it to perform backup and restore operations over your target tenant. All required steps to complete this authorization process are presented below.

Please, use this connection method for testing purposes as it is deprecated. For production systems, please go ahead with Authorization method B: Authorization Method B: Standalone app model with ‘bacula-m365-registrator’ (RECOMMENDED).

Most of the procedures described in this section must be done by a tenant administrator. A tenant administrator is a user who has been assigned the Azure AD role Global administrator.

Below we show a schema of how this authorization method works:

Authorization method A

A-1. Authorize bacula-m365-plugin

A tenant administrator must run the following query in a web browser, replacing {tenantId} with the value obtained in the first step:

Authorization URL
https://login.microsoftonline.com/{tenantId}/adminconsent?client_id=14a0b71a-d9ca-496c-b4c0-76a3cbb5dc33&state=12345&redirect_uri=https://www.baculasystems.com/m365-plugin-auth/common

You can get the exact same URL from the plugin command line itself, once you have installed it in a client named {your_client_name} using the following special Query command.

Authorization URL
*.query plugin="m365:" client={your_client_name} parameter=register:{tenantId}

Here is an execution example where the instructions are displayed and you need to open the provided URI:

Query command for tenant URL
*.query plugin="m365:" client=127.0.0.1-fd parameter=register:57uia43-d107-17a2-a2g2-aa53c10tdahc
console=---- M365 PLUGIN REGISTER COMMAND ----
console=-------------------------------------
console=-------------------------------------
info=Open the following URI in a browser with your tenant admin credentials
console=-------------------------------------
console=-------------------------------------
uri=https://login.microsoftonline.com/57uia43-d107-17a2-a2g2-aa53c10tdahc/adminconsent?client_id=14a0b71a-d9ca-496c-b4c0-76a3cbb5dc33&state=12345&redirect_uri=https://www.baculasystems.com/m365-plugin-auth/common
console=-------------------------------------
console=-------------------------------------
info=Once you have accepted the provided permissions to the bacula-m365-plugin app..
info=You can get your ObjectId using the command below
console=-------------------------------------
console=-------------------------------------
command=.query plugin="m365: tenant=57uia43-d107-17a2-a2g2-aa53c10tdahc" client={your_client_name} parameter=objectid
console=-------------------------------------

When opening the URI, Microsoft 365 will ask for credentials. You need to authenticate as a tenant admin:

Login

…and once they are correctly provided, the app will ask for all the required permissions to backup and restore all of the supported elements:

Confirm Permissions

The application needs all of the listed permissions to be able to work. If any of them is missing, backup or restore operationms will fail.

The image and list shown here are illustrative and some additional permissions may be needed as the plugin evolves. However, we provide also here a text list of current permissions needed:

  • Graph

    • Read and write user chat messages → Backup/Restore of Team Channels and Chats

    • Read and write user and shared calendars → Backup/Restore of group Calendars

    • Read and write all groups → Creation of Teams

    • Send user chat messages → Restore of Chats

    • Create, read, update and delete user’s tasks and task lists → Backup/Restore of Tasks

    • Read and write tags in Teams → For future support of Team tags

    • Read organization information → Find tenant name

    • Read and write files in all sites collections → Backup/Restore OneDrive and Sharepoint

    • Read and write all chat messages → Backup/Restore of Team Channels

    • Read all users full profiles → Find users to Backup/Restore

    • Read all channel messages → Backup of Team Channels

    • Read and write all user mailbox settings → Outlook categories and more future mailbox information

    • Read and write contacts in all mailboxes → Backup/Restore contacts

    • Read directory data → Security checks of objectid, list groups, etc

    • Read and write calendars in all mailboxes → Backup/Restore User Calendars

    • Read organizational contacts → Backup organizational contacts

    • Read and write tabs in Microsoft Teams → Backup of Microsoft Teams tabs

    • Read and write all OneNote notebooks → Backup/Restore OneNote service*

    • Have full control of all site collections → Backup/Restore Sharepoint

    • Add and remove members from all Teams → Backup/Restore of Microsoft Teams members

    • Create chat and channel messages with anyone’s identity and with any timestamp

    • Manage Teams apps for all chats → Backup of Microsoft Teams apps

    • Manage Teams apps for all teams → Backup of Chats apps

    • Read and write the names, descriptions, and settings of all channels of all Teams → Backup of Microsoft Teams Channels

    • Add and remove members from all channels → Backup of Microsoft Teams Channels

    • Read and write managed metadata → Security checks of objectid, list groups, etc

    • Sign in and read user profile → Ability to connect to the tennant

    • etc.

  • Sharepoint Online

    • Full management of all site collections → Backup/Restore Sharepoint (PnP)

    • Full management of Term Store → Backup/Restore Sharepoint (PnP)

Once it is confirmed, the browser will use the ‘redirect_uri’, which is a page on baculasystems.com that will confirm the result of the registration process.

Registration confirmation

The generated URI contains the parameter admin_consent=True if the action was successful, and you will see a confirmation message in that case. Otherwise, the operation may have not been successful for some reason and you will see an error message.

Once that action is done, the tenant where our app now has permissions will show the plugin in the Enterprise Apps section:

Plugin app in a new tenant

Clicking on the app, the tenant admin can always see the permissions assigned:

Plugin app permissions in new tenant

A-2. Grab Object ID

The plugin needs a final parameter that is unique to each tenant and the plugin app. This is ObjectID, and may be obtained from the Overview app page, once step 2 has been completed:

ObjectId of app inside a tenant

The plugin can also obtain it from the command line using another special Query command. You can see that this exact command is also suggested in the command that shows the register URL:

Authorization URL
*.query plugin="m365: tenant=57uia43-d107-17a2-a2g2-aa53c10tdahc" client={your_client_name} parameter=objectid

Here is an execution example:

Authorization URL
*.query plugin="m365: tenant=57uia43-d107-17a2-a2g2-aa53c10tdahc" client=127.0.0.1-fd parameter=objectid
console=---- M365 PLUGIN OBJECTID COMMAND ----
console=-------------------------------------
objectid=56ddf1h9-eb5d-42nf-bac7-7b019fd284g5
console=-------------------------------------

Check permissions

It is possible to check if the service principal of the target tenant (this is shown under ‘enterprise applications’ in Azure AD) has all the needed permissions to perform plugin operations.

You just need to run the following command:

Check permissions
.query client={your-client} plugin="m365: tenant={yourTenantId} objectid={yourobjectid}" parameter=permissions

The ouput will report if everything is ok around permissions, or if there is any missing one:

Check permissions: ok output
.query client={your-client} plugin="m365: tenant={yourTenantId} objectid={yourobjectid}" parameter=permissions
info=All permissions are correctly set
Check permissions: some is missing
.query client={your-client} plugin="m365: tenant={yourTenantId} objectid={yourobjectid}" parameter=permissions
error=Delegated permission Chat.ReadWrite was not found in your Azure service principal 8cee7605-0d5e-42b6-b269-c39f3411b5b9
error=Please review your app permissions

In case you are using the standalone application, you will need to run the command with appid and secret too:

Check permissions
.query client={your-client} plugin="m365: tenant={yourTenantId} objectid={yourobjectid} appid={yourappid} secret={yoursecret}" parameter=permissions

Please, run this command at any time you have doubts about the correct app permissions.

Please note though, that the command is unable to check if you have activated or not ‘Protected APIs’ for Teams and Chats. It will check the presence of those permissions, but it is up to Microsoft to enable those particular ones and they do not show (at the time of writing) any flag indicating if they are enabled or not.

Migration from Authenticaton Method A to Authentication Method B

Perhaps you started to use this plugin using Method A and now you want to switch to Method B in order to enjoy its advantadges. This section will show the steps needed in order to complete such migration.

Migration - Step 1: Remove bacula-m365-plugin from your tenant

The first step is to remove the common app ‘bacula-m365-plugin’ from your tenant. In order to do it, you need to go to your Azure portal and open the ‘Azure Active Directory’ application as usual.

From there, please go to ‘Enterprise applications’ and locate bacula-m365-plugin app. You need to select the application and enter into ‘Properties’ section. From there, you need to click on the ‘Delete’ button:

Delete common app

Migration - Step 2: Perform Authentication Method B

Once you have removed the common application, you simply need to follow all the steps explained in this documment for authentication method B. In case you are using BWeb and you have already registered you tenant, it is recommended to remove it first, and then add it also using method B. Otherwise, for manual configuration, simply follow the steps mentioned in this document: Authorization Method B: Standalone app model with ‘bacula-m365-registrator’ (RECOMMENDED).

Migration - Step 3: Update your filesets

Once you have your new app in your tenant, you need to update all your filesets and: - Replace objectid with the new value associated to your app in your tenant - Add appid and secret associated to your app in your tenant

Fileset Configuration

Once the plugin is successfully authorized, it is possible to define regular filesets for backup jobs in Bacula, where we need to include a line similar to the one below, in order to call the M365 Plugin:

Fileset M365
Fileset {
   Name = FS_M365
   Include {
      Options {
        signature = MD5
        ...
      }
      Plugin = "m365: <m365-parameter-1>=<m365-value-1> <m365-parameter-2>=<m365-value-2> ..."
   }
}

It is strongly recommended to use only one ‘Plugin’ line in every fileset. The plugin offers the needed flexibility to combine different modules backup inside the same plugin line. Different tenants, in case of existing, should be using different filesets and different jobs.

Below sub-sections list all the parameters you can use to control M365 Plugin behavior.

In this plugin, any parameter allowing a list of values can be assigned with a list of values separated by ‘,’.

Note

This activity module is available since Bacula 18.0.1.

Common parameters

These parameters are common and applicable to all the modules of the M365 Plugin.

Option

Required

Default

Values

Example

Description

abort_on_error

No

No

No, Yes

Yes

If set to Yes: Abort job as soon as any error is found with any element. If set to No: Jobs can continue even if it they found a problem with some elements. They will try to backup or restore the other and only show a warning

config_file

No

Path pointing to a file containing any combination of plugin parameters

/opt/bacula/m365.settings

Allows to define a config file where configure any parameter of the plugin. Therefore you don’t need to put them directly in the Plugin line of the fileset

log

No

/opt/bacula/working/m365/m365-debug.log

Existing path with enough permissions for File Daemon to create a file with the provided name

/tmp/m365.log

Generates additional log in addition to what is shown in job log. This parameter is included in the backend file, so, in general, by default the log is going to be stored in the working directory.

debug

No

0

0, 1, 2, 3, 4, 5, 6, 7, 8, 9

Debug level. Greater values generate more debug information

Generates the working/m365/m365-debug.log* files containing debut information which is more complete with a greater debug number

path

No

/opt/bacula/working

Existing path with enough permissions for File Daemon to create any internal plugin file

/mnt/my-vol/

Uses this path to store metadata and temporary files

tenant

Yes

Valid tenant id string

57uia43-d107-17a2-a2g2-aa53c10tdahc

The tenant ID where the plugin will connect to in order to run backups or restores. Please, check section 5.1 of this paper for more information

objectid

Yes

String representing the objectid related to bacula-m365-plugin Azure app and the provided tenant id

56ddf1h9-eb5d-42nf-bac7-7b019fd284g5

The object ID of the plugin app of the plugin in Azure, once this is registered in the target tenant. Please, check section 5.1 of this paper for more information

appid

No

String representing the appid associated to bacula-m365-plugin-standalone Azure app registered in the configured tenant id

89tt4hu7-r4h7-kied-56gu-0895kf94jr9d

A valid appid string associated to bacula-m365-plugin-standalone Azure app registered in the configured tenant id. Please, check section 5.1 of this paper for more information

secret

No

String representing the associated appid secret

Jn8.lU-B.3P5gIRTGY6M.Xl3e29oQ6Xaf~

The secret associated to the m365 Azure app corresponding the configured appid string. Please, check section 5.1 of this paper for more information

token_cache_file

No

token_cache.json

File name located in a valid existing path (it’s possible to put only the name of the file and ‘working’ dir will be used)

my_cache_file.json

The path that will be used to store the login cache for the device code flow authenticated users, wich is relative to the working tenant folder (working/tenant-name/token_cache.json)

service

No

email, drive, sharepoint, contact, calendar, onenote, tasks, teams, chat, activity (list parameter: it can contain 0, 1 or more elements separated by ‘,’)

drive

Establish the service or services that will be backed up. If this is not set, the plugin will try to backup all supported services. It is recommended to split the work among different jobs when several services need to be applied. Therefore, even if this field is not required, it is strongly recommended to use it in every backup job.

owner_restore_protection

No

No

Yes, No

Yes

Enable owner restore protection feature, where the owner of the data being restored will be notified with an email and the restore job will be blocked until he/she enters a code and his/her M365 credentials to approve the operation

proxy_host

No

String representing DNS Name or IP address of the http(s) proxy

myproxy.example.com

Set up a proxy to make any plugin HTTP connection

proxy_port

No

Integer

3981

Set up the proxy port

proxy_user

No

String of proxy user

admin

Set up the proxy user

proxy_password

No

String of proxy password

myPass123

Set up the proxy user password

Note

The path option is adjustable while M365 jobs are in progress. The running jobs will continue to use the current spool area, and new jobs will use the new spool area defined by the path option. If specifying more than one service in the fileset, note that they will run in parallel. Because of that, we suggest reducing the concurrency slightly.

Below some multi-services fileset examples:

Fileset for all data belonging to a user
Fileset {
   Name = fs-m365-adelev-user
   Include {
      Options { signature = MD5 }
      Plugin = "m365: service=drive,email,calendar,contact,onenote,tasks,chat tenant=57uia43-d107-17a2-a2g2-aa53c10tdahc objectid=56ddf1h9-eb5d-
   42nf-bac7-7b019fd284g5 user=adelev@baculaenterprise.onmicrosoft.com concurrent_threads=2"
   }
}
Fileset for all data belonging to a group
Fileset {
   Name = fs-m365-devteam-group
   Include {
      Options { signature = MD5 }
      Plugin = "m365: service=drive,calendar,onenote,tasks,teams tenant=57uia43-d107-17a2-a2g2-aa53c10tdahc objectid=56ddf1h9-eb5d-
   42nf-bac7-7b019fd284g5 group=DevTeam concurrent_threads=2"
   }
}
Fileset for all data belonging to a site
Fileset {
   Name = fs-m365-mysite-site
   Include {
      Options { signature = MD5 }
      Plugin = "m365: service=sharepoint,drive,onenote tenant=57uia43-d107-17a2-a2g2-aa53c10tdahc objectid=56ddf1h9-eb5d-
   42nf-bac7-7b019fd284g5 site=MySite sharepoint_include_drive_items=no sharepoint_system_include=yes drive_system_include=yes concurrent_threads=2"
   }
}

Note

Activating proxy mody will route all the requests through the proxy. However, it is needed DNS resolution to be working separately. Hence, the client where the FD is running will need to have a proper and working DNS Server configured. Other option is to setup the /etc/hosts file manually with the IP addresses of Microsoft authentication servers, but they could change over time. At the time of writing they are: 40.126.31.2 login.microsoftonline.com 20.190.160.131 login.microsoft.com

Advanced common parameters

Following parameters are common to all M365 modules (and even with some other plugins), but are advanced ones. They should not be modified in most common use cases.

Option

Required

Default

Values

Example

Description

stream_sleep

No

1

Positive integer (1/10 secconds)

5

Time to sleep when reading header packets from FD and not having a full header available

stream_max_wait

No

120

Positive integer (seconds)

360

Max wait time for FD to answer packet requests

time_max_last_modify_log

No

86400

Positive integer (seconds)

43200

Maximum time to wait to ovewrite a debug log that was marked as being used by other process

logging_max_file_size

No

50MB

String size

300MB

Maximum size of a single debug log fileGenerates the working/m365/m365-debug.log* files containing debut information which is more complete with a greater debug number

logging_max_backup_index

No

25

Positive integer (number of files)

50

Maximum number of log files to keep

log_rolling_file_pattern

No

m365.log.%d{dd-MMM}.log.gz”

No, Yes

Yes

Log patter for rotated log files

split_config_file

No

=

Character

:

Character to be used in config_file parameter as separator for keys and values

opener_queue_timeout_secs

No

1200

Positive integer (seconds)

3600

Timeout when internal object opener queue is full

publisher_queue_timeout_secs

No

1200

Positive integer (seconds)

3600

Timeout when internal object publisher queue is full

The internal plugin logging framework presents some relevant features that we are going to describe:

  • The “.log” files are rotated automatically. Currently each file can be 50Mb at maximum and the plugin will keep 25 files.

    • This behavior can be changed using the internal advanced parameters: logging_max_file_size and logging_max_backup_index

  • The “.err” file can show contents even if no real error happened in the jobs. It can show contents too even if debug is disabled. This file is not rotated, but it is expected to be a small file in general. If you still need to rotate it, you can include it in a general rotating tool like ‘logrotate’.

  • Backups in paralel and also failed backups will generate several log files. For example: m365-debug-0.log, m365-debug-1.log…

Tuning parameters

These set of parameters are common to all modules and they are advanced ones. They should not be modified in general. They can be used to tune the behavior of the plugin to be more flexible in particular bad network environments or when significant job concurrency is happening, etc.

Option

Required

Default

Values

Example

Description

backup_queue_size

No

100

0-500

1

Number of maximum enqueued internal operations between service static internal threads (there are 3 communicating through queues with the set size: service fetcher, service opener and general publisher to bacula core). This could potentially affect graph api concurrent requests and consequently, Graph throttling. It is only needed to modify this parameter, in general, if you are going to run different jobs in parallel

concurrent_threads

No

10

0-100

1

Number of maximum concurrent backup threads running in parallel in order to fetch or open data for running download actions. This means every service fetcher and service opener will open this number of child concurrent threads. This will affect graph api concurrent requests. Graph API can throttle requests depending on a variety of circumstances, but this parameter impacts it directly. It is only needed to modify this parameter, in general, if you are going to run different jobs in parallel. If you want to have a precise control of your parallelization through different jobs, please set up this value to 1. Please be careful also with the memory requirements, multi-threaded increases very significantly memory consumption per job

concurrent_listing_threads

No

5

0-20

1

Number of maximum concurrent backup page listing threads running in parallel in order to fetch sets of data for some modules. Currently it’s only used in the email module. This parameter will also affect graph api concurrent requests. Graph API can throttle requests depending on a variety of circumstances, but this parameter impacts it directly. It is only needed to modify this parameter, in general, if you are going to run different jobs in parallel. If you want to have a precise control of your parallelization through different jobs, please set up this value to 1. Please be careful also with the memory requirements, multi-threaded increases very significantly memory consumption per job

graph_list_page_size

No

200

1-500

350

Number of maximum elements got from Graph API for each page of objects. Higher number implies less requests, but more memory and more time for each request

graph_timeout

No

9000

Positive integer (milliseconds)

60000

Graph call timeout inside HttpClient

graph_read_timeout

No

300

Positive integer (milliseconds)

30000

Graph read timeout inside HttpClient

graph_retries

No

5

Positive integer (number of retries)

10

Graph number of retries for retry-candidate requestsInclude some stats information in the joblog. Useful to measure task times

graph_retry_delay

No

5

Positive integer (seconds)

10

Graph delay between retries

general_network_retries

No

5

Positive integer (number of retries)

10

Number of retries for the general M365 external retry mechanism

general_network_delay

No

50

Positive integer (seconds)

100

General M365 Plugin delay between retries

throttled_wait_time

No

300

Positive integer (seconds)

600

Extra wait time for throttled situations where the timeout is not provided or not got from MS API. In onenote module this is multiplied by 2. Once MS throttles a request is better to not retry too soon or the changes to continue with rejected requests will increase significantly

stats

No

No

No, Yes

Yes

Include some stats information in the joblog. Useful to measure task times

Note

graph_list_page_size had default value 500 before BEE 14.0.7. A higher value for this parameter can improve the performance at it reduces the number of API calls done to M365 service. However, the service can also be overloaded and return more HTTP 503 errors (Bad Gateway), especially for the email module. Starting from version 16.0.3, default values for backup_queue_size and concurrent_threads have been increased, also the allowed ranges.

Entity parameters

The following list of parameters are commonly shared through any module used into the same fileset line and are intended to select the target entities to backup. Every module subsection mentions what entities are supported too.

Option

Required

Default

Values

Example

Services

Description

user

No

Valid email addresses of existing users on the selected tenant separated by ‘,’

AlexW@yourdomain.com, LeeY@yourdomain.com

email, drive, contact, calendar, onenote, chat, tasks

Backup mailboxes, drive unit spaces, categories, or whatever service is selected of this list of users. If no user is provided: - The backup will be done for all accessible users of the given tenant if no other entry has value either (group or site parameters)

user_exclude

No

Valid email addresses of existing users on the selected tenant separated by ‘,’

LauraG@yourdomain.com, AmandaT@yourdomain.com

email, drive, contact, calendar, onenote, chat, tasks

Exclude selected mailboxes or onedrive spaces. If this is the only parameter found for selection, all elements will be included and this list will be excluded

user_regex_include

No

Valid regex

.*@management\.mydomain.com

email, drive, contact, calendar, onenote, chat, tasks

Backup matching user mailboxes or onedrive spaces. Please, only provide list parameters (user + user_exclude) or regex ones. But do not try to combine them

user_regex_exclude

No

Valid regex

.*@guests\.mydomain.com

email, drive, contact, calendar, onenote, chat, tasks

Exclude matching user mailboxes or onedrive spaces from the selection. Please, only provide list parameters (user + user_exclude) or regex ones. But do not try to combine them. If this is the only parameter found for selection, all elements will be included and this list will be excluded

site

No

Valid names of existing user sharepoint sites on the selected tenant separated by ‘,’

Communication site, Dev site

drive, sharepoint, onenote

Backup onedrive site library space (OneDrive service) belonging to this list of sharepoint sites or the site itself (Sharepoint service). If no site name is provided: - OneDrive: user and site variables will be checked. If no one has value either, backup will be done for all accessible users, groups or sites of the given tenant - Sharepoint: all accessible sites of the tenant will be backed up

site_exclude

No

Valid names of existing user sharepoint sites on the selected tenant separated by ‘,’

Test site

drive, sharepoint, onenote

Exclude listed sites from backup. If this is the only parameter found for selection, all elements will be included and this list will be excluded

site_regex_include

No

Valid regex

.*site

drive, sharepoint, onenote

Backup matching sites. Please, only provide list parameters (site + site_exclude) or regex ones. But do not try to combine them

site_regex_exclude

No

Valid regex

Test.*

drive, sharepoint, onenote

Exclude matching sites from the selection. Please, only provide list parameters (site + site_exclude) or regex ones. But do not try to combine them. If this is the only parameter found for selection, all elements will be included and this list will be excluded

group

No

Valid names of existing user groups on the selected tenant separated by ‘,’

Dev Team, Bacula Users

drive, onenote, calendar, teams, tasks

Backup onedrive sharepoint library spaces or notebooks of this list of groups. If no group is provided, user and site variables will be checked. If no one has value either, backup will be done for all accessible users, groups or sites of the given tenant

group_exclude

No

Valid names of existing user groups on the selected tenant separated by ‘,’

Monitoring, External

drive, onenote, calendar, teams, tasks

Exclude selected group. If this is the only parameter found for selection, all elements will be included and this list will be excluded

group_regex_include

No

Valid regex

.*Management

drive, onenote, calendar, teams, tasks

Backup matching group onedrive spaces. Please, only provide list parameters (group + group_exclude) or regex ones. But do not try to combine them

group_regex_exclude

No

Valid regex

.*External

drive, onenote, calendar, teams, tasks

Exclude matching groups from the selection. Please, only provide list parameters (group + group_exclude) or regex ones. But do not try to combine them. If this is the only parameter found for selection, all elements will be included and this list will be excluded

Backup parameters

Please, check the specific module pages in order to see backup parameters that are applicable only to each of them:

Deprecated parameters

The following parameters have been deprecated since version 12.8.3, in order to provide more flexibility. General shared parameters have been transformed in specific ones for each service

  • files -> email_files, drive_files, calendar_files, contact_files

  • files_exclude -> email_files_exclude, drive_files_exclude, calendar_files_exclude, contact_files_exclude

  • files_regex_include -> email_files_regex_include, drive_files_regex_include, calendar_files_regex_include, contact_files_regex_include

  • files_regex_exclude -> email_files_regex_exclude, drive_files_regex_exclude, calendar_files_regex_exclude, contact_files_regex_exclude

  • multilevel_attach -> email_multilevel_attach, calendar_multilevel_attach

  • exclude_attachments -> email_exclude_attachments, calendar_exclude_attachments

  • system_include -> drive_system_include, sharepoint_system_include

  • version_history -> drive_version_history, sharepoint_version_history

  • backup_threads -> backup_queue_size

Restore parameters

The plugin is able to restore to the local file system on the server where the File Daemon is running or to the Microsoft 365 environment. The method is selected based on the value of the where parameter at restore time:

  • Empty or ‘/’ (example: where=/) → Microsoft 365 restore will be triggered

  • Any other path for where (example: where=/tmp) → Local file system restore will be triggered

When using the Microsoft 365 restore option, the following parameters may be modified by selecting ‘Plugin Options’ during the bconsole restore session:

Option

Required

Default

Values

Example

Services

Description

destination_user

No

Existing email address on the target Azure AD Tenant

AlexW@yourdomain.com

email, drive, contact, calendar, onenote, tasks, chat

Destination User where restore data will be uploaded. If no user is set, every selected file will be restored in the original account

destination_group

No

Existing group name address on the target Azure AD Tenant

Marketing

drive, calendar, onenote

Destination Group where restore data will be uploaded. If no group is set, every selected file will be restored in the original group

destination_site

No

Existing site name/display name on the target Azure AD Tenant

live @ contoso

drive, sharepoint, onenote

Destination Site where restore data will be uploaded. If no site is set, every selected file will be restored in the original site

destination_path

No

Existing path on the selected user (mailfolder path or onedrive folder path)

Inbox

email, drive, contact, calendar, sharepoint

Destination folder where all selected files to restore will be restored. If no path is set: - If no user is set either, every element will go to its original location - If a user is set using the variable destination_user: - Elements belonging to destination_user will be restored in their original location - Elements belonging to different users than destination_user will be restored in a new folder using the email address of the original user of the element

destination_drive

No

Existing drive name or drive id in the destination entity

documents

drive

Destination drive where restore data will be uploaded. If no drive is set, every selected file will be restored in the original drive

send_report

No

0

0, no, No, false, FALSE, false, off ; 1, yes, Yes, TRUE, true, on

1

email, drive, contact, calendar, sharepoint, tasks

Send a report to the user where every restore action is listed (generated emails, generated onedrive files..). - In the email service this will be an email in the user Inbox - In onedrive service this will generate a new text file in the top restore folder

allow_duplicates

No

1

0, no, No, false, FALSE, false, off ; 1, yes, Yes, TRUE, true, on

0

email, contact, calendar

In Email services indicates if we want to allow to create duplicate emails or if we want to skip emails that are already in place. Important: This is done using the Microsoft Message ID. Therefore, non intuitive situations can happen. For example, if the original message is deleted and we restore several times using this option, we will see duplicate emails anyway

drive_skip_sharedwitme

No

0

0, no, No, false, FALSE, false, off ; 1, yes, Yes, TRUE, true, on

1

drive

Skip restoring shared with me elements even if they are selected.

skip_versions

No

1

0, no, No, false, FALSE, false, off ; 1, yes, Yes, TRUE, true, on

0

drive

Skip restoring former file versions (tagged with ‘###date’) even if they are selected. Important: Notice that this parameter is enabled by default, as we consider not restoring file versions the most common case. You need to disable it in order to have this kind of files restored

restore_share_permissions

No

0

0, no, No, false, FALSE, false, off ; 1, yes, Yes, TRUE, true, on

1

drive, calendar

Restore share permissions of every element in order to regenerate sharing information as allowed identities, shared links, etc. Please note that this parameter is disabled by default.**Important**: Notice that this parameter is disabled by default, as we consider not restoring sharing permissions the most common case. You need to enable it in order to haver shared permissions restored

drive_send_invitations

No

0

0, no, No, false, FALSE, false, off ; 1, yes, Yes, TRUE, true, on

1

drive

Send email invitations for restored OneDrive shares - Note you need to enable drive_restore_share_permissions in order to this parameter to have any effect

drive_invitations_message

No

String

I’m sharing with you automatically restored shares

drive

Set invitations message for restored OneDrive shares - Note you need to enable drive_restore_share_permissions in order to this parameter to have any effect

calendar_name

No

String

RestoredCalendar

calendar

Set the name of restored(s) calendar(s)

sharepoint_list_name

No

String

documentsCopy

sharepoint

Set the name of restored(s) sharepoint list(s)

sharepoint_newsite_name

No

String

Restored Site

sharepoint

Set the name of restored sharepoint new site

sharepoint_newsite_owner

No

String

bill@your.tennantname.com

sharepoint

Set the owner of the new restored sharepoint site

sharepoint_skip_system

No

1

0, no, No, false, FALSE, false, off ; 1, yes, Yes, TRUE, true, on

0

sharepoint

Skip restoring system lists even if they are selected. This is particularly useful to restore complete sites when using the sharepoint_newsite_name and sharepoint_newsite_owner restore parameters, as system lists are already included in the site template

sharepoint_local_template_path

No

String

/tmp/my-restores/company meeting.site.template.xml

sharepoint

Set the local path of the PnP Sharepoint Site template you want to be using instead of the one contained in the backup itself.

notebook_name

No

String

myRestoredNotes

onenote

Set the owner of the new restored sharepoint site

notesection_name

No

String

Technology

onenote

Set the name of restored onenote notebook

notesection_group_name

No

String

ForWork

onenote

Set the name of restored onenote section

team_name

No

String

MyRestoredTeam

teams

Set the name of restored team (it will create also a new associated group)

team_channel_name

No

String

MyRestoredChannel

teams

Set the name of restored channel

team_private_channels_mode

No

DELEGATED

DELEGATED, PUBLIC, SKIP

PUBLIC

teams

Set the private channels restore mode

team_guest_members_enable

No

0

0, no, No, false, FALSE, false, off ; 1, yes, Yes, TRUE, true, on

1

teams

Enable restore of team members with role ‘guest’. That kind of external user needs delegated permissions to be added, so potentially the restore could ask for user interaction (of first team owner found)

chat_topic

No

String

MyRestoredChat

chat

Set the topic of restored chat (supported only for group chats)

tasklist_name

No

String

ProjectA

tasks

Set the name of restored task list

tasklist_skip_sharedwithme

No

1

0, no, No, false, FALSE, false, off ; 1, yes, Yes, TRUE, true, on

0

tasks

Skip shared with me tasks in the restore process

plan_name

No

String

RestoredPlan

tasks

Set the name of restored planner plan

plan_create_tab

No

1

0, no, No, false, FALSE, false, off ; 1, yes, Yes, TRUE, true, on

0

tasks

Create or not an associated tab inside the associated team

local_path_json_objects

No

{path}/bacula-restores

String

/home/me/restores

onenote, sharepoint

Set local path to restore objects that cannot be restored directly into the M365 service

foreign_container_generation

No

1

0, no, No, false, FALSE, false, off ; 1, yes, Yes, TRUE, true, on

0

email, drive, contact, calendar

Generate a general container (usually a folder) to put restored objects coming from different entities inside. For example, if we restore emails from user a@tenant.com into Mailbox of user b@tenant.com, this option enabled will generate an automatic folder a@tenant.com inside the destination restore folder used over destination user a@tenant.com

tenant

No

A valid tenant id string where some bacula m365 plugin app is registered

57uia43-d107-17a2-a2g2-aa53c10tdahc

email, drive, contact, calendar, sharepoint, onenote, tasks, teams, chat

Set the destination tenant id for a cross-tenant restore

appid

No

Appid of bacula-m365-plugin-standalone app registered in the provided tenant

56ddf1h9-eb5d-42nf-bac7-7b019fd284g5

email, drive, contact, calendar, sharepoint, onenote, tasks, teams, chat

Set the destination appid of bacula-m365-plugin-standalone for a cross-tenant restore

objectid

No

Object id associated to set up appid

89tt4hu7-r4h7-kied-56gu-0895kf94jr9d

email, drive, contact, calendar, sharepoint, onenote, tasks, teams, chat

Set the objectid associated to the appid in a cross-tenant restore

secret

No

Valid secret associated to appid

Jn8.lU-B.3P5gIRTGY6M.Xl3e29oQ6Xaf~

email, drive, contact, calendar, sharepoint, onenote, tasks, teams, chat

Set the secret associated to the appid set in the above parameter

debug

No

0

0, 1, 2 ,3, 4, 5, 6, 7, 8, 9

3

email, drive, contact, calendar, sharepoint, onenote, tasks, teams, chat

Change debug level

Go back to Microsoft 365 (M365) Plugin article.