Migrating your server to a new version

Newer server versions can often require a different server database or configuration. For example, if you have version 1.6 installed and you want to run version 1.9, your server requires a different configuration.

The migration process checks the serverVersion property in the server configuration file. If the migration process detects the current version of the Unity Licensing Server is incompatible with the new version, it displays the following message and then stops:

Cannot start the licensing server. Incompatible version is already installed. Please, make sure to stop existing Licensing.Server service (if it is running) and run setup command.

To resolve this incompatibility, run the command that matches your operating system from the Linux Terminal or the Windows PowerShell:

Linux: ./Unity.Licensing.Server setup
Windows: .\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.6.0 to 1.9.0...
Backup installed version 1.6.0...Done
Scripts to run: 1.9.0
Executing 1.9.0...Done
Stamping version 1.9.0...Done
Successfully migrated from 1.6.0 to 1.9.0

Important

Make sure that the Licensing Server isn't running before running the setup command.
Before starting any licensing server migration, be sure to 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.
Migrations that are complex will prompt for confirmation before proceeding.

Example of migration that requires confirmation (Windows):

> .\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] y

Proceeding with migration...
Backup installed version 1.10.0...Done
Scripts to run: 1.11.0
Executing 1.11.0...Done
Stamping version 1.11.0...Done
Successfully migrated from 1.10.0 to 1.11.0
Enter the server name (e.g. LicenseServer):

Note

The migration process logs detailed information in the server's log file, but it can take several minutes for new information to appear.

How migration works

The setup command detects your current server version and copies your server data to the LicensingServerBackups directory before migration begins. The location of this directory depends on the server's operating system:

Linux: ~/.config/unity3d/Unity/LicensingServerBackups
Windows: %LOCALAPPDATA%\Unity\LicensingServerBackups

The migration continues by converting your data to be compatible with the new server version. When the migration is complete, it begins the configuration process, using the information you provided in the previous setup of server. However, since you already configured your server and successfully migrated your settings, you can use the Ctrl+C keyboard shortcut to exit the command.

Note

If the command encounters any problems during the migration, it cancels the migration and restores your data to its state before the migration.

Restore database

When you migrate your server to a higher version, the setup command automatically creates a backup copy of your database file. If the restoration fails, the following critical error message appears:

An error occurred while restoring a backup.

This indicates that your server is in an invalid state which might prevent you from continuing to use your previous server version. To fix this error, copy the contents of the LicensingServerBackups/<your_old_server_version>/ directory to the LicensingServer directory to manually restore the backup data. For example:

  ├── 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

To restore the server to a previous version, follow these steps:

Put the existing database file into the following folder:
- Linux: ~/.config/unity3d/Unity/LicensingServer/data/
- Windows: %LOCALAPPDATA%\Unity\LicensingServer\data\
Rename the file to LicensingServerDb.sqlite.