______ Article Applicability This article is intended for use in environments where Veeam Backup _for Microsoft 365_ 8 is already installed. The information provided in this article outlines the process for migrating the Configuration and Cache Databases from one PostgreSQL instance to another, including situations involving migrating the databases to a newer version of PostgreSQL. For information about upgrading to Veeam Backup _for Microsoft 365_ version 8 from an older version, please review: Upgrading Veeam Backup for Microsoft 365 ## Purpose This article documents the procedure for migrating the Configuration and Cache Databases of Veeam Backup _for Microsoft 365_ verison 8 from one PostgreSQL instance to another, including migrating those databases to a newer supported version of PostgreSQL. ## Solution **Note:** This procedure is 56 steps long. It will require experience and knowledge of operating pgAdmin and basic PostgreSQL administration. Customers are advised not to undertake this process unless necessary. Please review each section's steps to understand what will be done, then go back and perform that section's steps. To the best of our ability, we have written this to document every step a customer must perform. If you find a step unclear, please highlight the step and press Ctrl+Enter to open the typo report form (this form is not for technical assistance). #### **Prepare for Migration** 1. Ensure all jobs and restore tasks are completed, stopped, and disabled. 2. On the primary Veeam Backup _for Microsoft 365_ server (aka controller) and all associated Proxies, stop the Veeam Backup _for Microsoft 365_ services: * **Veeam Backup _for Microsoft 365_ Server** Veeam Backup for Microsoft 365 Proxy Service Get-Service Veeam.Archiver.Proxy | Stop-Service Veeam Backup for Microsoft 365 Service Get-Service Veeam.Archiver.Service | Stop-Service * **Veeam Backup _for Microsoft 365_ Windows Proxy** Veeam Backup for Microsoft 365 Proxy Service Get-Service Veeam.Archiver.Proxy | Stop-Service * **Veeam Backup _for Microsoft 365_ Linux Proxy** Veeam.Archiver.Proxy systemctl stop Veeam.Archiver.Proxy 3. Review the Veeam Backup _for Microsoft 365_ configuration to identify the current database connection information. 1. On the machine where Veeam Backup _for Microsoft 365_ is installed open the following file in a text editor: C:\ProgramData\Veeam\Backup365\Config.xml 2. Look for the node named **ControllerPostgres**. On that line will be the current database connection information. * **Example 1:** Using VB365 Installer-deployed PostgreSQL Instance In this example, we can see that the PostgreSQL server is named **vb365srv** , the configuration database is named **VeeamBackup365** , and we can tell that **SSPI** authentication is being used because there is no _password=_ parameter. * **Example 2:** Using Remote Dedicated PostgreSQL Instance In this example, we can see that the PostgreSQL server is named **pgsqlsrv** , the configuration database is named **VeeamBackup365** , the user is named **veeam365svc** , and native password-based authentication is in use because there is a **passsword=** parameter configured. #### **Prepare pgAdmin** * The migration procedure documented in this article utilizes pgAdmin, a third-party management tool for PostgreSQL. * When managing the PostgreSQL instance included with Veeam Backup _for Microsoft 365_, it is recommend to deploy pgAdmin using the PostgreSQL installer from the _Redistr_ folder on the Veeam Backup _for Microsoft 365_ installer ISO. This ensures compatibility between pgAdmin and the PostgreSQL instance. * The most common cause of errors when restoring the configuration database using pgAdmin is an incompatibility between the PostgreSQL binaries that pgAdmin attempts to use and those associated with the PostgreSQL instance. Therefore, customers are encouraged to ensure that pgAdmin uses binaries that are compatible with the PostgreSQL instance being accessed. * As pgAdmin is a third-party application, Veeam Support can only provide best-effort assistance with troubleshooting errors or issues that may arise when utilizing pgAdmin. #### **Export from Source** Using pgAdmin, connect to the PostgreSQL server where the Veeam Backup _for Microsoft 365_ configuration database is located and export the following _(the sections that follow explain in detail how to export these)_ : * SQL Script files to recreate: * **Group Role:** proxy_role_ **Example Export Filename:**_proxyrole.sql_ * **User:** proxy_dbuser_ **Example Export Filename:**_proxyuser.sql_ * Database Backup Files * **Configuration Database:** VeeamBackup365 **Example Export Filename:** VeeamBackup365.backup * **Cache Database(s):** cache_ **Example Export Filename:** cache_.backup **Note:** When connecting to the default included PostgreSQL instance, the default authentication method for the postgres user is SSPI, and you may see the error "SSPI authentication failed for user." If this occurs, review KB4542. If prompted to specify a password after connecting, click OK with the password field empty. ##### **Export the Proxy Group Role** 4. Under Login/Group Roles, identify the Group Role named **proxy_role_veeambackup365** 5. Right-click on that Group Role and select **CREATE script**. ![Backup Role](https://cdn.veeam.com/content/veeam/en/knowledge-base/kb4676/_jcr_content/content-parsys/section-main/section-with-background-content/side_navigation_cont/side-navigation-container-grid/side-navigation-container-content/section-with-background-content/section_with_backgro_1219618935/section-with-background-content/image/file.web.ntfile.png/1.BackupRole.png?ck=1730235075889) 6. A query tool window will appear with an SQL query to recreate the Group Role. 7. In the Query Tool Toolbar, click the **Save** icon and save the SQL script as _proxyrole.sql_ for use later in the migration. ![Save SQL Role](https://cdn.veeam.com/content/veeam/en/knowledge-base/kb4676/_jcr_content/content-parsys/section-main/section-with-background-content/side_navigation_cont/side-navigation-container-grid/side-navigation-container-content/section-with-background-content/section_with_backgro_1219618935/section-with-background-content/image_841899129/file.web.ntfile.png/2.SaveRole.png?ck=1730235217285) ##### **Export the Proxy User** 8. Under Login/Group Roles, identify the User named **proxy_dbuser_veeambackup365** 9. Right-click on that Group Role and select **CREATE script**. ![Export Proxy User](https://cdn.veeam.com/content/veeam/en/knowledge-base/kb4676/_jcr_content/content-parsys/section-main/section-with-background-content/side_navigation_cont/side-navigation-container-grid/side-navigation-container-content/section-with-background-content/section_with_backgro_1219618935/section-with-background-content/image_copy/file.web.ntfile.png/3.ProxyUserCreate.png?ck=1730310270774) 10. A query tool window will appear with an SQL query to recreate the Proxy user. 11. In the Query Tool Toolbar, click the **Save** icon and save the SQL script as _proxyuser.sql_ for use later in the migration. ![Save SQL Role](https://cdn.veeam.com/content/veeam/en/knowledge-base/kb4676/_jcr_content/content-parsys/section-main/section-with-background-content/side_navigation_cont/side-navigation-container-grid/side-navigation-container-content/section-with-background-content/section_with_backgro_1219618935/section-with-background-content/image_841899129_copy/file.web.ntfile.png/4.saveuser.png?ck=1730310366495) ##### **Export Configuration Database** 12. Expand the **Databases** node. 13. Right-click on the Veeam Backup _for Microsoft 365_ Configuration Database, by default, named **VeeamBackup365**. 14. Select **Backup...** ![Backup DB](https://cdn.veeam.com/content/veeam/en/knowledge-base/kb4676/_jcr_content/content-parsys/section-main/section-with-background-content/side_navigation_cont/side-navigation-container-grid/side-navigation-container-content/section-with-background-content/section_with_backgro_1219618935/section-with-background-content/image_783904868/file.web.ntfile.png/5backupdb.png?ck=1730314732074) 15. In the _Backup_ dialog window that appears, provide a path where the database backup will be created, ensure that the format is set to **Custom** , and then click **Backup**. ![Backup Database Form](https://cdn.veeam.com/content/veeam/en/knowledge-base/kb4676/_jcr_content/content-parsys/section-main/section-with-background-content/side_navigation_cont/side-navigation-container-grid/side-navigation-container-content/section-with-background-content/section_with_backgro_1219618935/section-with-background-content/image_1469141871/file.web.ntfile.png/6custombackup.png?ck=1730314858672) ##### **Export Cache Databases** 16. If any database(s) are present named **cache__< guid>_**, back them up. **Tip:** If you right-click on the cache database and select **Properties** , you can copy the database name to the clipboard so that you can save the _.backup_ file with the database name to make it easier to recreate and restore the database with the correct name during the Import portion of the migration. ![cache db backup](https://cdn.veeam.com/content/veeam/en/knowledge-base/kb4676/_jcr_content/content-parsys/section-main/section-with-background-content/side_navigation_cont/side-navigation-container-grid/side-navigation-container-content/section-with-background-content/section_with_backgro_1219618935/section-with-background-content/image_1079051467/file.web.ntfile.png/7cachebackup.png?ck=1730315461992) ______ Tip If Veeam Backup _for Microsoft 365_ was using the included local PostgreSQL deployment, and that PostgreSQL instance will **not** be used by any other software, stop and disable the **postgresql **service. _This will prevent the software from mistakenly connecting to the old PostgreSQL instance if the configuration file is not updated correctly during the finalization stage of the migration._ #### **Import to Destination** ##### **Notes:** * The destination PostgreSQL instance can be hosted on either Windows or Linux. * When migrating the Configuration Database to a remote PostgreSQL instance, the authentication method Veeam Backup _for Microsoft 365_ uses to connect to the PostgreSQL instance must be switched to native password-based authentication. * Due to the variability of possible PostgreSQL configurations, this guide cannot account for all possible custom configurations that may occur when a PostgreSQL instance is already in use by other third-party software. This guide instead aims to document the configuration changes required to modify a default new deployment of PostgreSQL to allow it to host the Veeam Backup _for Microsoft 365_ Configuration and Cache databases. * Ensure that the destination PostgreSQL instance is running a version supported by Veeam Backup _for Microsoft 365_. ##### **Copy Generated Files to Destination** 17. Copy the generated .sql and .backup files to the new PostgreSQL server. ##### **Recreate the Proxy Group Role** 18. Using pgAdmin, connect to the destination PostgreSQL instance. 19. Right-click on any**** database and select **Query Tool**. ![Open Query Tool](https://cdn.veeam.com/content/veeam/en/knowledge-base/kb4676/_jcr_content/content-parsys/section-main/section-with-background-content/side_navigation_cont/side-navigation-container-grid/side-navigation-container-content/section-with-background-content/section_with_backgro_1219618935/section-with-background-content/image_999834695/file.web.ntfile.png/8openquerytool.png?ck=1730317011427) 20. In the Query Tool Toolbar, click the **Open** button. ![Open Query File](https://cdn.veeam.com/content/veeam/en/knowledge-base/kb4676/_jcr_content/content-parsys/section-main/section-with-background-content/side_navigation_cont/side-navigation-container-grid/side-navigation-container-content/section-with-background-content/section_with_backgro_1219618935/section-with-background-content/image_523890683/file.web.ntfile.png/9opensql.png?ck=1730319551341) 21. Open the exported Proxy Group Role SQL script, _proxyrole.sql_. 22. With the query now open in the Query Tool, click **Execute script** in the**Query Tool Toolbar **to recreate the Proxy Group Role. ![recreate proxy group role](https://cdn.veeam.com/content/veeam/en/knowledge-base/kb4676/_jcr_content/content-parsys/section-main/section-with-background-content/side_navigation_cont/side-navigation-container-grid/side-navigation-container-content/section-with-background-content/section_with_backgro_1219618935/section-with-background-content/image_464194590/file.web.ntfile.png/10executesql.png?ck=1730319684446) ##### **Recreate the Proxy User** 23. With the Query Tool still open from adding the Proxy Group Role, click the **Open** button again. ![Open Query File](https://cdn.veeam.com/content/veeam/en/knowledge-base/kb4676/_jcr_content/content-parsys/section-main/section-with-background-content/side_navigation_cont/side-navigation-container-grid/side-navigation-container-content/section-with-background-content/section_with_backgro_1219618935/section-with-background-content/image_523890683_copy/file.web.ntfile.png/9opensql.png?ck=1730319551341) 24. Open the exported Proxy User SQL script, _proxyuser.sql._ 25. Click **Execute** to recreate the Proxy User. ![recreate proxy user](https://cdn.veeam.com/content/veeam/en/knowledge-base/kb4676/_jcr_content/content-parsys/section-main/section-with-background-content/side_navigation_cont/side-navigation-container-grid/side-navigation-container-content/section-with-background-content/section_with_backgro_1219618935/section-with-background-content/image_464194590_copy/file.web.ntfile.png/11createuser.png?ck=1730321763616) ##### **Recreate and Restore the Configuration Database** 26. Right-click on the **Databases** node, and highlight **Create >**, then click **Database...** ![create new database](https://cdn.veeam.com/content/veeam/en/knowledge-base/kb4676/_jcr_content/content-parsys/section-main/section-with-background-content/side_navigation_cont/side-navigation-container-grid/side-navigation-container-content/section-with-background-content/section_with_backgro_1219618935/section-with-background-content/image_1756449468/file.web.ntfile.png/12createdatabase.png?ck=1730382637671) 27. Name the database after the Configuration Database that was backed up. ![create database name](https://cdn.veeam.com/content/veeam/en/knowledge-base/kb4676/_jcr_content/content-parsys/section-main/section-with-background-content/side_navigation_cont/side-navigation-container-grid/side-navigation-container-content/section-with-background-content/section_with_backgro_1219618935/section-with-background-content/image_1761960149/file.web.ntfile.png/12.5createdatabasename.png?ck=1730382990131) 28. Right-click on the new database and select **Restore...** ![Restore Database](https://cdn.veeam.com/content/veeam/en/knowledge-base/kb4676/_jcr_content/content-parsys/section-main/section-with-background-content/side_navigation_cont/side-navigation-container-grid/side-navigation-container-content/section-with-background-content/section_with_backgro_1219618935/section-with-background-content/image_1890793838/file.web.ntfile.png/13restoredatabase.png?ck=1730383045364) 29. Select the _.backup_ file created from the Configuration Database and click **Restore**. ![start restore](https://cdn.veeam.com/content/veeam/en/knowledge-base/kb4676/_jcr_content/content-parsys/section-main/section-with-background-content/side_navigation_cont/side-navigation-container-grid/side-navigation-container-content/section-with-background-content/section_with_backgro_1219618935/section-with-background-content/image_119588811/file.web.ntfile.png/14startrestore.png?ck=1730383137988) ##### **Recreate and Restore Cache Databases** If any databases named cache_ were backed up from the original PostgreSQL instance: 30. Create new cache_ database(s) with their original names. 31. Use the _.backup_ file from each cache_ database to restore the cache database(s). #### **Configure PostgreSQL Authentication** When the Veeam Backup _for Microsoft 365_ Configuration Database is hosted on a remote PostgreSQL Instance, you must configure authentication within the PostgreSQL configuration to allow Veeam Backup _for Microsoft 365_ to access the restored Configuration Database. ##### **Create a PostgreSQL User for Veeam Backup _for Microsoft 365_** 32. Using pgAdmin, connect to the new PostgreSQL instance. 33. Open the Query Tool. Right-click on a database and select Query Tool. 34. Paste the following query _(_don't_ execute it, after pasting read the next step for details on updating it)_. CREATE ROLE "vb365svc" WITH LOGIN SUPERUSER CREATEDB CREATEROLE INHERIT REPLICATION BYPASSRLS CONNECTION LIMIT -1 PASSWORD 'pa55word'; Copy 35. **Update** the role name (vb365svc) and password (pa55word) values in the query and **Execute** it. **Tip:** Remember which role name and password you specified, as you'll need that when reconfiguring Veeam Backup _for Microsoft 365_. **Note:** The password **must not contain** the following characters: * & * @ * < * > * ' * " ##### **Update PostgreSQL Configuration Files to Allow Authentication** 36. Open pg_hba.conf in a text editor. **Note:** If file exetnsions are disabled you won't see the '.conf' portion of the filename. * Windows default location: C:\Program Files\PostgreSQL\15\data\pg_hba.conf * Linux conf file location will depend on the distro and the method used to install PostgreSQL. 37. Add the following lines to the bottom of the pg_hba.conf file: This will enable access to the PostgreSQL Instance from any source and require sha-256 authentication. # Allow remote access using Password-based authentication. host all all 0.0.0.0/0 scram-sha-256 host all all ::/0 scram-sha-256 Copy 38. Save the pg_hba.conf file. 39. Restart the PostgreSQL service. #### **Reconfigure Veeam Backup _for Microsoft 365_ and Proxies** In this section you'll update the PostgreSQL connection settings on the Veeam Backup _for Microsoft 365_ machine and any associated Proxies. ______ Configuration Formatting All parameters within the discussed configuration files (Config.xml and Proxy.xml) are separated by a semicolon ( ; ) symbol. Ensure that the format of the xml file is preserved and that parameters are correctly separated using that semicolon. Any malformation in the configuration file may cause the service to fail to start. ##### **Update Connection Settings on Veeam Backup _for Microsoft 365_ Machine** 40. On the machine where Veeam Backup _for Microsoft 365_ is installed, navigate to: _C:\ProgramData\Veeam\Backup365\_ 41. Make a copy of Config.xml and Proxy.xml, just in case changes need to be reverted or a misconfiguration occurs. ##### **Update Config.xml** 42. Open Config.xml in a text editor. 43. On the line starting with _**< ControllerPostgres**_, review and update each parameter as needed: 1. **host=** -- Hostname of the new PostgreSQL machine. 2. **port=** -- Port to connect to the PostgreSQL instance. 3. **database=** -- Configuration Database name. _(This should**not** have changed if you followed the steps in this guide.)_ 4. **username=** -- Set the username= parameter to use the new user role you created in the previous section. 5. **password=** -- This value should be configured as follows: For more information on updating the password used by Veeam Backup _for Microsoft 365_ to connect to PostgreSQL, review KB4669. * If the **password=** parameter is _not_ present: 1. Add **;password= ** with the password in plaintext after the username parameter. **Note:** Once the service is started, the plaintext password in the file will be replaced with an encrypted value. **Example:** * If the **;password=** parameter is present: 1. Replace the encrypted password value with the new password in plaintext. **Note:** Once the service is started, the plaintext password in the file will be replaced with an encrypted value. 2. Remove the **;PasswordEncrypted=True** parameter from the end of the same line. 44. Using the formatting explanation from step 43, look for the line starting with _< RemoteProxyDeploymentSettings_, and review each parameter and update as needed. **Note:** Only the **host** and** port** values should need to be checked to make sure they are correct. Neither the username nor password should need to be updated since the proxy user role was exported and imported into the new PostgreSQL instance. 45. Save the updated Config.xml ##### **Update Proxy.xml** 46. Open Proxy.xml in a text editor. 47. Using the formatting explanation from step 43, look for the line starting with _< ProxyPostgres_, review each parameter and update as needed. **Note:** Only the **host** and **port **values should need to be checked to make sure they are correct. Neither the username nor password should need to be updated since the proxy user role was exported and imported into the new PostgreSQL instance. 48. On any line(s) starting with _< PersistentCachePostgres_, review and update each parameter as needed. **Note:** Only the **host** and **port **values should need to be checked to make sure they are correct. 49. Save the updated Proxy.xml ##### **Update Connection Settings on the Proxies** 50. On each Veeam Backup _for Microsoft 365_ Proxy, navigate to: * Windows: C:\ProgramData\Veeam\Backup365\ * Linux: /etc/veeam/backup365 51. Make a copy of Proxy.xml, just in case changes need to be reverted or a misconfiguration occurs. ##### **Update Proxy.xml** 52. Open Proxy.xml in a text editor. 53. On the line starting with _< ProxyPostgres_, review and update each parameter as needed. **Note:** Only the host and port values should need to be checked to make sure they are correct. Neither the username nor password should need to be updated since the proxy user role was exported and imported into the new PostgreSQL instance. 54. On any line(s) starting with _< PersistentCachePostgres_, review and update each parameter as needed. **Note:** Only the **host** and **port **values should need to be checked to make sure they are correct. 55. Save the updated Proxy.xml #### **Finalize Migration** 56. On the primary Veeam Backup _for Microsoft 365_ server (aka controller) and all associated Proxies, start the Veeam Backup _for Microsoft 365_ services: * Veeam Backup _for Microsoft 365_ Server Get-Service Veeam.Archiver.Proxy | Start-Service Get-Service Veeam.Archiver.Service | Start-Service * Veeam Backup _for Microsoft 365_ Windows Proxy Get-Service Veeam.Archiver.Proxy | Start-Service * Veeam Backup _for Microsoft 365_ Linux Proxy systemctl start Veeam.Archiver.Proxy