Restore in Exchange EWS Plugin

Exchange EWS plugin is able to restore to any local filesystem mounted over the host where the File Daemon is running, or to the Exchange environment. The restore method is selected based on the value of the where parameter at restore time:

Empty or ‘/’ (example: where=/) → Exchange EWS restore will be triggered
Any other path for where (example: where=/tmp) → Local file system restore will be triggered.

When using the Exchange EWS restore method, the following parameters are available to control the restore behavior under ‘Plugin Options’ menu during a bconsole restore session:

Option	Required	Default	Values	Example	Description
destination_user	No		Existing email address on the target Exchange service	AlexW@yourdomain.com	Destination User where restore data will be uploaded. If no user is set, every selected file will be restored in the original account
destination_archive	No		0, no, No, false, FALSE, false, off ; 1, yes, Yes, TRUE, true, on	yes	Restore using the in-place archving tree instead the regular mailbox tree
send_report	No	1	0, no, No, false, FALSE, false, off ; 1, yes, Yes, TRUE, true, on	0	Send an email to the destination user with a report containing the result of all restored (or failed) items
foreign_container_generation	No	1	0, no, No, false, FALSE, false, off ; 1, yes, Yes, TRUE, true, on	0	Generate a general folder to put inside restored items coming from different mailboxes. For example, if we restore emails from user a@domain.com into Mailbox of user b@domain.com, with this option enabled the plugin will generate an automatic folder a@domain.com inside the destination restore folder used over destination user b@domain.com
endpoint	No	Original backup value	A hostname or IP address	win19-cl1-exch	Cross-server restore: Hostname or IP address that matches the DN of the SSL Certificate of the Destination Exchange service
admin_domain	No	Original backup value	A domain name	MYEXCHANGEDOMAIN	Cross-server restore: The users domain name. If admin_user is including already the domain, this parameter must not be set
admin_user	No	Original backup value	Email address or username (with or without the domain prefix)	myadmin@mydomain.com	Cross-server restore: An email address, or the username of the admin user that has permissions to impersonate all the other users. The format can be an email address, a single username (then admin_domain needs to be filled in) or domainusername. For simplicity, it is recommended to use the email address
admin_password	No	Original backup value	A password string	G3934kdk!/0348	Cross-server restore: The password associated to the admin user
debug	No	0	0, 1, 2 ,3, 4, 5, 6, 7, 8, 9	3	Change debug level

Restore Use Cases

The following restore scenarios are supported:

Restore whole directories, specific items (email, task, contact, appointments or attachments) to original user or to a different user:
- Restore parameters implied: destination_user.
Restore directories, emails, or attachments to original path or to a different path:
- Restore parameters implied: destination_path.
Restore to the local filesystem (general restore where parameter must be set to a path).
It is possible to control replacement behavior (items are compared using exchange id) with the generic replace option of Bacula.
Restore to a different exchange server:
- Restore parameters implied: endpoint, admin_domain, admin_user, admin_password.

Some particularities to remark:

If no destination_user is set, every message will be restored into its original mailbox.
If no destination_path is set, every message will be restored into its original path.
If the selection contains messages from several users:
- Original user messages will be restored in their original location
- For other users, a special folder will be created with the email address of each of them, containing the full path and messages of the restored objects, unless the parameter foreign_container_generation is disabled
- Example: Restore of emails from 2 different users over a third mailbox without destination_path result in auto-generated Restore_date folder containing those 2 foreign users with the restored folder inside of them.

Restore Example Session

In the following restore example session, we restore into the original mailbox all the emails of the backup, inside the ‘restored’ folder.

Note

It is also possible to run backup or restore operations from any of the Bacula Graphical User Interfaces.

Restore bconsole session

Connecting to Director 127.0.0.1:8101
1000 OK: 10002 127.0.0.1-dir Version: 16.0.5 (05 April 2023)
Enter a period to cancel a command.
*restore
Automatically selected Catalog: MyCatalog
Using Catalog "MyCatalog"

First you select one or more JobIds that contain files
to be restored. You will be presented several methods
of specifying the JobIds. Then you will be allowed to
select which files from those JobIds are to be restored.

To select the JobIds, you have the following choices:
   1: List last 20 Jobs run
   2: List Jobs where a given File is saved
   3: Enter list of comma separated JobIds to select
   4: Enter SQL list command
   5: Select the most recent backup for a client
   6: Select backup for a client before a specified time
   7: Enter a list of files to restore
   8: Enter a list of files to restore before a specified time
   9: Find the JobIds of the most recent backup for a client
   10: Find the JobIds for a backup for a client before a specified time
   11: Enter a list of directories to restore for found JobIds
   12: Select full restore to a specified Job date
   13: Select object to restore
   14: Cancel
Select item:  (1-14): 5
Automatically selected Client: 127.0.0.1-fd
Automatically selected FileSet: FS_E2WS
+-------+-------+----------+------------+---------------------+-------------------+
| jobid | level | jobfiles | jobbytes   | starttime           | volumename        |
+-------+-------+----------+------------+---------------------+-------------------+
|     1 | F     |       32 | 10,632,924 | 2023-04-17 12:52:41 | TEST-2023-04-17:0 |
+-------+-------+----------+------------+---------------------+-------------------+
You have selected the following JobId: 1

Building directory tree for JobId(s) 1 ...
31 files inserted into the tree.

You are now entering file selection mode where you add (mark) and
remove (unmark) files to be restored. No files are initially added, unless
you used the "all" keyword on the command line.
Enter "done" to leave this mode.

cwd is: /
$ mark *
31 files marked.
$ done
Bootstrap records written to /tmp/regress/working/127.0.0.1-dir.restore.2.bsr

The Job will require the following (*=>InChanger):
   Volume(s)                 Storage(s)                SD Device(s)
===========================================================================

   TEST-2023-04-17:0         File                      FileStorage

Volumes marked with "*" are in the Autochanger.


31 files selected to be restored.

Using Catalog "MyCatalog"
Run Restore job
JobName:         RestoreFiles
Bootstrap:       /tmp/regress/working/127.0.0.1-dir.restore.2.bsr
Where:           /tmp/regress/tmp/bacula-restores
Replace:         Always
FileSet:         Full Set
Backup Client:   127.0.0.1-fd
Restore Client:  127.0.0.1-fd
Storage:         File
When:            2023-04-17 13:16:33
Catalog:         MyCatalog
Priority:        10
Plugin Options:  *None*
OK to run? (Yes/mod/no): mod
Parameters to modify:
   1: Level
   2: Storage
   3: Job
   4: FileSet
   5: Restore Client
   6: When
   7: Priority
   8: Bootstrap
   9: Where
   10: File Relocation
   11: Replace
   12: JobId
   13: Plugin Options
Select parameter to modify (1-13): 9
Please enter the full path prefix for restore (/ for none): /
Run Restore job
JobName:         RestoreFiles
Bootstrap:       /tmp/regress/working/127.0.0.1-dir.restore.2.bsr
Where:
Replace:         Always
FileSet:         Full Set
Backup Client:   127.0.0.1-fd
Restore Client:  127.0.0.1-fd
Storage:         File
When:            2023-04-17 13:16:33
Catalog:         MyCatalog
Priority:        10
Plugin Options:  *None*
OK to run? (Yes/mod/no): mod
Parameters to modify:
   1: Level
   2: Storage
   3: Job
   4: FileSet
   5: Restore Client
   6: When
   7: Priority
   8: Bootstrap
   9: Where
   10: File Relocation
   11: Replace
   12: JobId
   13: Plugin Options
Select parameter to modify (1-13): 13
Automatically selected : e2ws: service=email endpoint=w16-cl02-exch admin_user=ex-admin@testlab.local admin_password=Bacula18 debug=4 user="ex-admin@testlab.local" folder="REGRESS_20230417125041"
Plugin Restore Options
Option                         Current Value        Default Value
destination_user:              *None*               (*None*)
destination_path:              *None*               (*None*)
send_report:                   *None*               (1)
foreign_container_generation:  *None*               (1)
send_invitations_mode:         *None*               (AllCopy)
endpoint:                      *None*               (*None*)
admin_domain:                  *None*               (*None*)
admin_user:                    *None*               (*None*)
admin_password:                *None*               (*None*)
debug:                         *None*               (*None*)
Use above plugin configuration? (Yes/mod/no): mod
You have the following choices:
   1: destination_user (Destination User)
   2: destination_path (Destination Path in Exchange)
   3: send_report (Send report of the restore operation to the affected user)
   4: foreign_container_generation (Generate a general container (usually a folder) to put inside restored objects coming from different entities)
   5: endpoint (Destination Exchange endpoint)
   6: admin_domain (Destination Exchange endpoint admin user domain)
   7: admin_user (Destination Exchange endpoint admin user)
   8: admin_password (Destination Exchange endpoint admin password)
   9: debug (Change debug level)
Select parameter to modify (1-10): 2
Please enter a value for destination_path: restore
Plugin Restore Options
Option                         Current Value        Default Value
destination_user:              *None*               (*None*)
destination_path:              restore              (*None*)
send_report:                   *None*               (1)
foreign_container_generation:  *None*               (1)
endpoint:                      *None*               (*None*)
admin_domain:                  *None*               (*None*)
admin_user:                    *None*               (*None*)
admin_password:                *None*               (*None*)
debug:                         *None*               (*None*)
Use above plugin configuration? (Yes/mod/no): yes
Run Restore job
JobName:         RestoreFiles
Bootstrap:       /tmp/regress/working/127.0.0.1-dir.restore.2.bsr
Where:
Replace:         Always
FileSet:         Full Set
Backup Client:   127.0.0.1-fd
Restore Client:  127.0.0.1-fd
Storage:         File
When:            2023-04-17 13:16:33
Catalog:         MyCatalog
Priority:        10
Plugin Options:  User specified
OK to run? (Yes/mod/no): yes
Job queued. JobId=3

Restore job result

*llist joblog jobid=3
time: 2023-04-17 13:16:57
logtext: 127.0.0.1-dir JobId 3: Start Restore Job RestoreFiles.2023-04-17_13.16.54_11

time: 2023-04-17 13:16:57
logtext: 127.0.0.1-dir JobId 3: Restoring files from JobId(s) 1

time: 2023-04-17 13:16:57
logtext: 127.0.0.1-dir JobId 3: Connected to Storage "File" at 127.0.0.1:8103 with TLS

time: 2023-04-17 13:16:57
logtext: 127.0.0.1-dir JobId 3: Using Device "FileStorage" to read.

time: 2023-04-17 13:16:57
logtext: 127.0.0.1-dir JobId 3: Connected to Client "127.0.0.1-fd" at 127.0.0.1:8102 with TLS

time: 2023-04-17 13:16:57
logtext: 127.0.0.1-fd JobId 3: Connected to Storage at 127.0.0.1:8103 with TLS

time: 2023-04-17 13:16:57
logtext: 127.0.0.1-sd JobId 3: Ready to read from volume "TEST-2023-04-17:0" on File device "FileStorage" (/tmp/regress/tmp).

time: 2023-04-17 13:16:57
logtext: 127.0.0.1-sd JobId 3: Forward spacing Volume "TEST-2023-04-17:0" to addr=260

time: 2023-04-17 13:16:57
logtext: 127.0.0.1-fd JobId 3: e2ws: Plugin log of this job available in: /tmp/regress/working/e2ws/e2ws-debug-0.log

time: 2023-04-17 13:16:57
logtext: 127.0.0.1-fd JobId 3: e2ws: Backend connection to testlab.local stablished

time: 2023-04-17 13:16:57
logtext: 127.0.0.1-fd JobId 3: e2ws: Jar Version: 1.0.0 | Java version: 11.0.18

time: 2023-04-17 13:16:57
logtext: 127.0.0.1-fd JobId 3: e2ws: Starting backend restore process

time: 2023-04-17 13:16:57
logtext: 127.0.0.1-fd JobId 3: e2ws: Restore to Microsoft Exchange Service

time: 2023-04-17 13:16:57
logtext: 127.0.0.1-fd JobId 3: e2ws: No destination entity provided. Trying to restore each item into its original owner entity

time: 2023-04-17 13:16:57
logtext: 127.0.0.1-fd JobId 3: e2ws: Destination Path: restore

time: 2023-04-17 13:16:57
logtext: 127.0.0.1-fd JobId 3: e2ws: Generate report: enabled

time: 2023-04-17 13:16:57
logtext: 127.0.0.1-fd JobId 3: e2ws: Foreign container generation: enabled

time: 2023-04-17 13:16:57
logtext: 127.0.0.1-fd JobId 3: e2ws: Send invitations mode for appointments: AllCopy

time: 2023-04-17 13:17:03
logtext: 127.0.0.1-sd JobId 3: End of Volume "TEST-2023-04-17:0" at addr=10694381 on device "FileStorage" (/tmp/regress/tmp).

time: 2023-04-17 13:17:03
logtext: 127.0.0.1-sd JobId 3: Elapsed time=00:00:06, Transfer rate=1.780 M Bytes/second

time: 2023-04-17 13:17:19
logtext: 127.0.0.1-fd JobId 3: e2ws: Report sent to:ex-admin@testlab.local

time: 2023-04-17 13:17:19
logtext: 127.0.0.1-fd JobId 3: e2ws: No more items to restore. Restore ended

time: 2023-04-17 13:17:19
logtext: 127.0.0.1-dir JobId 3: Bacula 127.0.0.1-dir 16.0.5 (05Apr23):
   Build OS:               x86_64-pc-linux-gnu ubuntu 22.04
   JobId:                  3
   Job:                    RestoreFiles.2023-04-17_13.16.54_11
   Restore Client:         "127.0.0.1-fd" 16.0.5 (05Apr23) x86_64-pc-linux-gnu,ubuntu,22.04
   Where:
   Replace:                Always
   Start time:             17-abr-2023 13:16:57
   End time:               17-abr-2023 13:17:19
   Elapsed time:           22 secs
   Files Expected:         31
   Files Restored:         31
   Bytes Restored:         10,669,371 (10.66 MB)
   Rate:                   485.0 KB/s
   FD Errors:              0
   FD termination status:  OK
   SD termination status:  OK
   Termination:            Restore OK

time: 2023-04-17 13:17:19
logtext: 127.0.0.1-dir JobId 3: Begin pruning Jobs older than 6 months .

time: 2023-04-17 13:17:19
logtext: 127.0.0.1-dir JobId 3: No Jobs found to prune.

time: 2023-04-17 13:17:19
logtext: 127.0.0.1-dir JobId 3: Begin pruning Files.

time: 2023-04-17 13:17:19
logtext: 127.0.0.1-dir JobId 3: No Files found to prune.

time: 2023-04-17 13:17:19
logtext: 127.0.0.1-dir JobId 3: End auto prune.

            jobid: 3
              job: RestoreFiles.2023-04-17_13.16.54_11
             name: RestoreFiles
      purgedfiles: 0
             type: R
            level: F
         clientid: 1
       clientname: 127.0.0.1-fd
        jobstatus: T
    jobstatuslong: Completed successfully
        schedtime: 2023-04-17 13:16:33
        starttime: 2023-04-17 13:16:57
          endtime: 2023-04-17 13:17:19
      realendtime: 2023-04-17 13:17:19
    realstarttime: 2023-04-17 13:16:57
         jobtdate: 1,681,730,239
     volsessionid: 3
   volsessiontime: 1,681,728,758
         jobfiles: 31
         jobbytes: 10,669,371
        readbytes: 10,629,087
        joberrors: 0
  jobmissingfiles: 0
           poolid: 0
         poolname:
       priorjobid: 0
         priorjob:
        filesetid: 0
          fileset:
         hascache: 0
          comment:
         reviewed: 0
    isvirtualfull: 0
             rate: 485
    compressratio: 0
       statusinfo:
     writestorage:
      writedevice:
  lastreadstorage: File
   lastreaddevice: FileStorage

User Restore Report

Files and emails can represent very sensitive information for end-users. For that reason, information included in backup/restore logs is not exhaustive by default. For example, email restores do not include information such as the subject or sender when they are displayed in the backup log. However, for reporting and controlling purposes, the information of what has been exactly restored, what permissions have been applied, and other information can be useful and necessary for the affected user.

Bacula Enterprise Exchange EWS Plugin includes an option to generate a restore report in the user mailbox destination. The restore report contains detailed information about the items that have been restored successfully, if any of them had any trouble during the restore, and it also reports the date when the action was performed.

The generation of the report can be enabled/disabled in the bconsole restore session. If enabled, depending on the service, the report can generate an HTML file or an email in the Inbox of the affected user.

The image below shows an example report from an Email restore session: