Unity Licensing Server administration

Explore common administration tasks you can perform on the Unity Licensing Server.

Read time 7 minutes

Last updated 2 days ago

After your Unity Licensing Server is up and running, here are some common administration tasks you might need to perform:

Checking if your service is running

To check the status of the service, run the following command:

Linux


sudo -H systemctl status unity.licensing.server.service

Look for

Active: active running

in the output in the Terminal:

Console output showing 'Active: active running'

Windows


sc.exe query Unity.Licensing.Server

Look for the

STATE

information in the output in the PowerShell window:


SERVICE_NAME: Unity.Licensing.Server        TYPE               : 10  WIN32_OWN_PROCESS        STATE              : 4  RUNNING                                (STOPPABLE, NOT_PAUSABLE, ACCEPTS_SHUTDOWN)        WIN32_EXIT_CODE    : 0  (0x0)        SERVICE_EXIT_CODE  : 0  (0x0)        CHECKPOINT         : 0x0        WAIT_HINT          : 0x0

If the

STATE

value shows anything other than

4 RUNNING

, open Windows Services and look for the

Unity.Licensing.Server

service to manage it.

Checking the status of your server

Important

If you set up your licensing server to run as a service, make sure you check if the service is running before checking its status.

Starting with Licensing Server v2.0, you can use the Licensing Server Dashboard to check the status of your server. To do this, log in to the dashboard as

admin

, then check the Server health report card on the Overview page. You can also select Download JSON to view the report as a file. For all versions of the Licensing Server, you can use the CLI to check the status of your server. To use the CLI to check the status, run the

status

command, which displays results for the following health checks:

Health check	Description
`HttpConfigHealthCheck`	Kestrel configuration
`ServerLicenseHealthCheck`	Status of licenses and delegations
`LicensingHealthCheck`	License configuration and signing key
`DatabaseHealthCheck`	Status of the connection to the database
`PluginInformationProvider`	Server plug-ins

You can also view the status of these health checks on the Extended test report. Go to the Licensing Server program files directory and run the

status

command with the following syntax:

Linux:
```
./Unity.Licensing.Server status
```
Windows:
```
.\Unity.Licensing.Server.exe status
```

The output looks similar to this:


Server Version: 2.0.0+e81737fHealthyHttpConfig: HealthyHTTP config is healthy  [OK] Kestrel: Found config section Kestrel  [OK] Kestrel:Endpoints:HTTP:Url: Found valid config Kestrel:Endpoints:HTTP:Url: http://10.192.192.255:80ServerLicense: HealthyServer license and delegation are valid  [OK] ServerLicense::Context::FirstPhysicalAddress: 48:2a:e3:87:3b:19  [OK] ServerLicense::Context::Platform: Win32NT  [OK] ServerLicense::Context::ProcessorCount: 12  [OK] ServerLicense::Context::MachineName: LAPTOP-2Q28U8QB  [OK] ServerLicense::ContextCount: Found 4 out of 4 context values  [OK] ServerLicense::EntitlementGroup::test-licenseServer_3573567292644_1: ... has valid server entitlements  [OK] ServerLicense::EntitlementGroupCount: Found 1 valid server license(s)  [OK] ServerLicense::Delegation::test-licenseServer-delegation-20200925_145658.xml: Found valid server delegation: <absolute_path>  [OK] ServerLicense::DelegationsCount: Found 1 valid server delegationsLicensingConfig: HealthyLicensing configuration is healthy  [OK] licensing:licenseSigningCertLoading: Successfully loaded license signing key  [OK] SyntaxValidation: Configuration syntax is valid  [WARNING] licensing:defaultToolset: The defaultToolset configuration is invalid or not set. Valid toolsets are: ...  [OK] licensing: Found config section licensing  [OK] LicenseAclConfigValidation: License access control list configuration is validPlugins: HealthyPlugins  [OK] PluginAssemblies: 0  [OK] RegisteredPlugins: 0Database: HealthyConnection state for Microsoft.Data.Sqlite.SqliteConnection is Open. Database is writable. Sufficient disk space available.  [OK] FloatingDbStatus: Connection state for Microsoft.Data.Sqlite.SqliteConnection is Open. Database is writable. Sufficient disk space available.  [OK] HistoricalDbStatus: Connection state for Microsoft.Data.Sqlite.SqliteConnection is Open. Database is writable. Sufficient disk space available.

Monitoring server status

There are two methods for monitoring the Licensing Server's status.

Dashboard: Starting with Licensing Server version 2.0, the dashboard is the primary method for monitoring the server. Administrators can log in with
```
admin
```
credentials to view the detailed Server health report on the Overview page.
API: For all versions, you can also use the
```
/v1/admin/status
```
API if you prefer or require API access. To use this endpoint and any API in the
```
admin
```
grouping, the requesting IP address must be in the administrator IP allow list. This requirement extends to computers that access the
```
admin
```
API through scripts or automation. For more information, refer to the
```
adminIpAllowlist
```
key in Advanced server configuration.

Licensing Server statuses

The Licensing Server has three possible statuses:

Healthy: This status indicates that the server can issue licenses and everything is functioning correctly.
Degraded: A server with this status can still issue licenses, but there are potential issues that need monitoring. These issues aren't critical yet, but they might become urgent, and therefore require attention. An example of an issue that causes a Degraded state is a server license that expires soon.
Unhealthy: This status indicates that the server is unable to issue licenses. The underlying issue requires immediate attention to restore functionality.

Renewing licenses on the server

At the end of the subscription term, if you choose to renew your subscription, you must update the license on the Licensing Server. To update the license, repeat the instructions on Downloading and importing the license archive file after you renew the subscription. If the Licensing Server version is earlier than 1.10, you must also manually delete the old delegation files. For details, refer to this support article.

Note

The new license becomes available for download from Unity ID only after the expiration of the current subscription term. Once the current subscription term has expired, there is a grace period of one month to renew the license on the server. If you don't renew the license before this grace period ends, the license stops working. You must download and update the license during the grace period to avoid service outages.

Impact of license renewals on client configuration

The same rules from Impact of license updates on client configuration apply when importing a license from a renewed subscription.

Applying changes to licenses on the server

If you negotiated a change to your Floating Licensing subscription with Unity, such as adding or removing seats, you'll need to repeat the process of importing the subscription's license to the server. Follow the process in Downloading and importing the license archive file.

Impact of license updates on client configuration

License updates don't affect clients that use the default toolset. For clients specifying a toolset:

With servers at version 1.10 and earlier, toolset values must match the
```
EntitlementGroupId
```
of the server license. This means that when you update the server license, you must update the toolset values accordingly on the client configuration.
Starting with version 1.11, license updates should have no impact on the toolset selection. The Licensing Server allows for variations in the incremental part of the toolset, which means that there should be no impact on the clients configured with a specific toolset.

The Licensing Server

import

command shows the new toolset, which is typically similar to the old one with an incremented number at the end. For example, after the first update, the

LicenseServer_3573461705080_1

toolset becomes

LicenseServer_3573461705080_2

Advanced server configuration

After you complete a successful setup of your Unity Licensing Server, you can find the

licensing-server-config.json

file in the Licensing server data directory. You can edit the

licensing-server-config.json

file to apply a modification to the server configuration that's not covered by the

setup

command.

Advanced configuration keys

The following table lists the advanced configuration keys and describes how to use them.

Key	Description
`floatingLeaseRenewIntervalInMinutes`	Specifies how long the server holds a lease for the client. If the server doesn't receive a ping for a specific lease before the end of this interval, it will release the license associated to that lease. The valid range is 5 to 60 minutes. The default setting is 15 minutes.
`floatingLicenseExpirationInMinutes`	Specifies the expiration time of the issued client license. The valid range is 60 to 1440 minutes. The default setting is 480 minutes (8 hours).
`licenseSigningCertificatePassword`	The encrypted password of the signing certificate in PFX format. The import command automatically sets this value.
`PluginsDirectory`	The full path of the directory the server reads plug-ins from.
`defaultToolset`	Stores the identifier of the default product license. If multiple product licenses are available on the server and the client doesn't request a specific product license, the server allocates the default license. If the default value isn't set, the server allocates the first available license from the list. To find all available product identifiers, open the Extended test report and locate the `licenseEntitlementGroupId` field in the `serverLicenses` section.
`allowBorrow`	Specifies whether users can check out a floating license to work offline. Specify this value as a Boolean data type.
`diskSpaceWarningThresholdMegabytes`	Specifies the warning threshold for available disk space on the Licensing Server. Note: This key is available starting with server version 2.0. Specify this value in megabytes. When the disk space falls below this threshold, the status of the server changes to `Degraded` , and the administration dashboard's status indicator changes to yellow. When the server runs out of disk space, it's unable to lease licenses to client computers.
`accessControlList`	Specifies a list to control whether specified users or computer names can request a license. Note: This key is available starting with server version 2.0. Specify the following keys: ● Which toolset to control. Currently, the only valid value is `allToolsets` . ● A `type` key with a value of either `allow` or `deny` . If you specify `allow` , only the specified users or computers can access floating licenses. If you specify `deny` , all users or computers except the ones you specify can access licenses. ● A `bindings` key with an array of `userName` strings, or an array of `machineName` strings, or both. You must specify at least one `userName` or `machineName` . If values are specified in both arrays, users are affected if their value matches either array. The values for `userName` and `machineName` are not case sensitive. Important: Avoid these configuration mistakes: ● The following errors cause the server to start in a `Degraded` state and allows access for all users and computers: ○ Omitting the `allToolsets` key. ○ Specifying an empty `allToolsets` object key. ○ Specifying neither an `allow` nor a `deny` key. ● Specifying an `allow` value without specifying any `bindings` causes the server to start in an `Unhealthy` state, because no user or computer can request a license. Unsuccessful license access attempts due to access control are written to the server log ( `Unity.Licensing.Server.log` ) and the client log ( `Unity.Licensing.Client.log` ). The log messages include the user's `userName` , `machineName` , and the reason why the license access attempt failed. Sample log entry: `API Error 403 while processing request (...) License access denied (The user (userName: jsmith, machineName: P4DSFHTE) does not have license access because the userName is on the access control list's deny bindings.)`
`adminIpAllowlist`	Specifies the permitted IP addresses that can access administrator endpoints as a semicolon separated string. The Licensing Server doesn't support wildcard characters or subnets.

Advanced configuration example

The following example includes all advanced configuration parameters:


{    "Logging": {        "LogLevel": {            "Default": "Warning"        }    },    "AllowedHosts": "*",    "Kestrel": {        "Endpoints": {            "HTTPS": {                "Url": "https://[* or IP address - see Warning below]:[Port]",                "Certificate": {                    "Path": "[Full path of HTTPS PFX certificate - see Warning below]",                    "Password": "[Password for HTTPS PFX certificate]"                }            }        }    },    "licensing": {        "serverId": "[Server name, to be set by setup CLI command]",        "licenseUsernameObfuscation": false,        "floatingLeaseRenewIntervalInMinutes": "15",        "floatingLicenseExpirationInMinutes": "480",        "licenseSigningCertificatePassword": "[Encrypted password of license signing certificate]",        "PluginsDirectory": "Plugins",        "defaultToolset": "[default license entitlement group Id]",        "allowBorrow": true,        "diskSpaceWarningThresholdMegabytes": 50,        "accessControlList": {            "allToolsets": {                "type": "deny",                "bindings": {                    "userName": ["john", "alice"],                    "machineName": ["LAPTOP-A", "LAPTOP-B"]                }            }        }    },    "adminIpAllowlist": "127.0.0.1;10.20.30.40;localhost",    "serverDirectory": "[Full directory path for Licensing Server executable]",    "serverVersion": "[Licensing Server version]"}

Note

For the

Url

key, the value must be an asterisk (

) or an IP address, not a server name. Valid examples include

https://*:443

and

https://10.20.30.40:443

.For the

Path

key on Windows, when using backslashes in a string with double quotes, you must use two backslashes for every instance of a backslash.

Server analytics

Starting with version 2.1.0, the Licensing Server collects and sends analytics to Unity. Analytics includes anonymized usage details and results of server performance checks. Unity uses these analytics to assist with troubleshooting and support, and to identify performance improvements for future updates. To learn more about server analytics, contact your Unity Sales or Support representative.

Documentation

Development

User Acquisition

Monetization

Industry