Migrating your server to a new version

How migration works

setup

LicensingServerBackups

• Linux:
  • Version 2.0 or later:

    /usr/share/unity3d/LicensingServerBackups

  • Version 1.x:

    ~/.config/unity3d/Unity/LicensingServerBackups

• Windows:
  • Version 2.0 or later:

    %PROGRAMDATA%\Unity\LicensingServerBackups

  • Version 1.x:

    %LOCALAPPDATA%\Unity\LicensingServerBackups

Before you begin

• Plan for downtime. Depending on the current and target versions, migrating can take several minutes. For example, in Unity's labs, migrating from a version before 1.11.0 to a version later than 1.11.0 took 15 minutes to complete on a 3 GB database.
• As part of your downtime, factor additional time, in case you need to abandon the migration and revert to the original version.
• Identify the folder where your current server is installed, and identify a separate location for the new server. Don't overwrite the older version with the newer version, otherwise you can't easily revert the upgrade.
• Decide how to control administrator access. If you're migrating from version 1.x, you might have an allow list that used IP addresses to control administrator access. If you're migrating to version 2.0 or later, you have two options for controlling administrator access:
  • To keep the current system that uses IP addresses, you don't need to take any explicit steps. Any IP addresses in the allow list can continue to access the

    admin

    endpoint of API and the administrator mode of the dashboard. When users with these IP addresses access the dashboard, they will automatically log in to the administrator mode, bypassing the login screen.
  • To use credentials instead of IP addresses to control administrator access, you need to take extra steps. These steps are included in the procedure that follows.

Procedure

1. Download the setup file for the new server version. Refer to Download the server setup.

2. If your server runs as a service, stop the Licensing Server service.
3. Open a Linux Terminal or Windows PowerShell with elevated privileges (Run as administrator). Make sure you use the same service account that you used to set up the server.
4. Change directories to the Licensing Server program files directory and run the following command:
   • Linux:

     sudo -H ./Unity.Licensing.Server setup

   • Windows:

     .\Unity.Licensing.Server.exe setup

   Important

   Migrations that are complex will prompt for confirmation before proceeding.
   
   
   Note

   The migration process writes detailed information to the server's log file, but it can take several minutes for new information to appear.
5. If you don't encounter any issues running the setup command, proceed to the next step. If you encounter issues that require you to abandon the migration and revert to the original version, skip the remaining steps and refer to Recovering from a failed migration.
6. When the setup completes, perform a final check:
   1. Start the server manually.
   2. Access one of the server endpoints to make sure the

      serverStatus

      is Healthy. For more information, refer to Testing the licensing server.
   3. Stop the server.
7. If your server runs as a service, you need to recreate the service. For details, refer to Set up a service.
8. If you're migrating from v1.x to 2.x, and you want to control administrator access using credentials exclusively (instead of IP addresses), follow these steps:
   1. Locate the licensing server configuration file for the new version of your server. For version 2.x, the full path to this file varies by platform:
      • Linux:

        /usr/share/unity3d/LicensingServer/config/licensing-server-config.json

      • Windows:

        %PROGRAMDATA%\Unity\LicensingServer\config\licensing-server-config.json

   2. Edit the file by removing the

      adminIpAllowlist

      key-pair value.
   3. Save the file.
9. Start the service, if applicable. Refer to Restarting the service.

Sample output

> .\Unity.Licensing.Server.exe setup- - - -Welcome to Unity Licensing Server setup command line interface.This setup will help you configure your license server and generate server registration request file.- - - -Upgrading from 1.10.0 to 1.11.0...This migration can take more than a few minutes. Are you sure you want to run it now? [y/N] yProceeding with migration...Backup installed version 1.10.0...DoneScripts to run: 1.11.0Executing 1.11.0...DoneStamping version 1.11.0...DoneSuccessfully migrated from 1.10.0 to 1.11.0Enter the server name (e.g. LicenseServer):

Recovering from a failed migration

setup

setup

setup

An error occurred while restoring a backup.

LicensingServerBackups/<your_old_server_version>

LicensingServer

├── LicensingServer│   ├── config│   │   ├── key-b4573620-ca22-423f-8d52-e3a767391234.xml│   │   ├── licensing-server-config.json│   │   └── unity.licensing.delegation.key│   ├── data│   └── wwwroot\v1\package\acl│└── LicensingServerBackups    └── 1.6.0        ├── config        ├── data        └── wwwroot

1. Put the existing database into the target folder, which varies depending on the server's operating system and the version of your licensing server:
   • Linux:
     • Version 2.0 or later:

       /usr/share/unity3d/LicensingServer/data/

     • Version 1.x:

       ~/.config/unity3d/Unity/LicensingServer/data/

   • Windows:
     • Version 2.0 or later:

       %PROGRAMDATA%\Unity\LicensingServer\data\

     • Version 1.x:

       %LOCALAPPDATA%\Unity\LicensingServer\data\

2. Rename the file to

   LicensingServerDb.sqlite

   .
3. If your server runs as a service, and you created a service for the newer server, make sure the path to the server binary file is correct. If the service is defined to run the wrong version of the server, recreate the service using the binaries for the server version you want to use. For details, refer to Set up a service.
4. Restart the service, if applicable.