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:

• Linux: Use the Linux Terminal to run ./Unity.Licensing.Server setup as sudo
• Windows: Open the Windows PowerShell as administrator and run .\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

> .\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):

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 and the version of your licensing server:

• 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

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.

Administrator access using an allow list#

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, there are no explicit steps to take to keep administrator access. 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'll automatically log in to the administrator mode, bypassing the login screen.

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:

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.

Additional resources#

• Running setup command (version 2.0 or later)
• Running setup command (version 1.x)