Unity Licensing Server administration

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

Checking the status of your server

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 checkDescription
HttpConfigHealthCheckKestrel configuration
ServerLicenseHealthCheckStatus of licenses and delegations
LicensingHealthCheckLicense configuration and signing key
DatabaseHealthCheckStatus of the connection to the database
PluginInformationProviderServer plug-ins

You can also view the status of these health checks on the Extended test report.

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+e81737f
Healthy
HttpConfig: Healthy
HTTP 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:80
ServerLicense: Healthy
Server 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 delegations
LicensingConfig: Healthy
Licensing 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 valid
Plugins: Healthy
Plugins
  [OK] PluginAssemblies: 0
  [OK] RegisteredPlugins: 0
Database: Healthy
Connection 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.

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

When you've completed a successful setup of your Unity Licensing Server, you can find the licensing-server-config.json file in the Licensing server data root directory.

To modify configuration not covered by the setup command, you can edit the licensing-server-config.json file. The following example includes all 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]"
}

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.

Advanced configuration keys

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

KeyDescription
floatingLeaseRenewIntervalInMinutesSpecifies 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.
floatingLicenseExpirationInMinutesSpecifies the expiration time of the issued client license.

The valid range is 60 to 1440 minutes.

The default setting is 480 minutes (8 hours).
licenseSigningCertificatePasswordThe encrypted password of the signing certificate in PFX format.

The import command automatically sets this value.
PluginsDirectoryThe full path of the directory the server reads plug-ins from.
defaultToolsetStores 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.
allowBorrowSpecifies whether users can check out a floating license to work offline.

Specify this value as a Boolean data type.
diskSpaceWarningThresholdMegabytesSpecifies 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.
accessControlListSpecifies 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.)
adminIpAllowlistSpecifies the permitted IP addresses that can access administrator endpoints as a semicolon separated string.

The Licensing Server doesn't support wildcard characters or subnets.

Additional resources

Unity logo Documentation
Copyright © 2024 Unity Technologies
"Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S. and elsewhere (more info here). Other names or brands are trademarks of their respective owners.