The roc-serve process can host a software license pool, allowing multiple computers to share licenses dynamically that are not locked to a specific roc_get_host_id.

Overview

The license server adheres to the following core concepts:

Local: The license server is run on your own machine, no communication traffic leaves your local network. If you prefer, Rank One can host the server, in which case an internet connection is required.

Floating: Client machines using the ROC SDK automatically connect to the license server using parameters specified in their License File. A license is obtained during roc_initialize and released during roc_finalize. Client machines can use the ROC SDK without being tied to specific Host ID. Instead a limit is imposed on the total number of clients concurrently using the ROC SDK.

Encrypted: Client/Server communication over TCP is end-to-end encrypted using SSL/TLS. If you prefer, communication can take place unencrypted, which simplifies the installation processes.

Metered: In cases where Usage Logging is required, the license server automatically collects this information from connected clients. See Usage Logging for details.

Requirements

To set up a license server you must first decide on the following items:

Hostname: The hostname may be either a static IPv4 address or a fully qualified domain name that client machines will use to connect to the license server.

Port: Port number that client machines will use to connect to the license server.

Host ID: While the SDK running on client machines is not Host ID restricted, the machine running the license server is.

Encrypted: Let us know whether or not client/server communication should be SSL/TLS encrypted, see Certificate Generation for details.

Instances: The maximum number of clients allowed to concurrently use the ROC SDK.

Timeout: The frequency (in seconds) in which a client will renew its license. If a client does not call roc_finalize to release its license, the license will be released automatically after the timeout. Unless your application warrants otherwise, we will set this value to 60 seconds.

Max Timeout: The time (in seconds), measured from the previous successful renewal, in which a client may continue to operate after failing to renew its license. Unless your application warrants otherwise, we will set this value to 60 seconds.

The above values must be provided to Rank One before a floating license can be issued.

Note: If any of these values needs to be changed, a new license must be issued.

Rank One will respond with two license files: ROC-server.lic for the license server, and ROC-client.lic for the client machines. For advanced deployments, a single roc-serve process and corresponding ROC-server.lic license is capable of supporting multiple distinct ROC-client.lic client instance types.

High Availability

Rank One suggests the following paradigms for customers seeking a high availability deployment.

Software Failure: Run roc-serve as a system service so that the operating system automatically restarts it in the unlikely event that it crashes or is accidentally killed. To monitor for a failure in the roc-serve process, check that you can use the client license file to templatize an image with roc-represent. Restart the server if this health check fails.

Hardware Failure: You can run two license servers in a master+backup configuration. All connections go to the master server by default, if the master server goes down then you update the license server DNS entry to point to the backup server. In this case, DNS TTL should be set to an appropriately short value so that client machines roll over to the backup server. Alternatively you could instruct your router to re-assign the IP address from the master to the backup server.

Network Failure: You can split your compute load into two physically isolated networks each with its own license server and client machines.

Automatic Failover: You have the option to purchase a single floating license that supports multiple servers with automatic failover. In this paradigm, each client machine has a stable random preference order of the license servers, and will sequentially request a license from each server until one of the requests succeeds. Future license refreshes will be sent to the server where the most recent request succeeded. No communication is performed between the license servers.

Certificate Generation

You can skip this step if you choose unencrypted communication.

In order to establish an encrypted SSL/TLS connection, a private key and certificate must be generated on the machine that will run the license server.

The following commands illustrate how to generate a private key and self-signed certificate using OpenSSL:

$ openssl genrsa -out my.key 2048
$ openssl req -new -key my.key -out my.csr -subj "/C=US/ST=Colorado/L=Denver/O=Rank One Computing/CN=license.rankone.io/emailAddress=josh@rankone.io"
$ openssl x509 -req -days 2000 -in my.csr -signkey my.key -out my.crt
$ rm my.csr

Please review and modify the above example according to your needs.

Note: It must be the case that the Common Name (CN) specified in the certificate request equals the hostname provided to Rank One.

Self-Signed/Untrusted Certificates

Self-signed certificates or certificates without a full chain of trust must be added to the system's certificate authority. Alternatively, inform the ROC SDK of the full path to the certificate file by setting the ROC_CERTIFICATE environment variable and it will added to the trust list at runtime.

OpenSSL Version

OpenSSL libraries are loaded at runtime and aren't packaged with our SDK due to export control of cryptographic software. OpenSSL 1.1 (released in 2016) introduced breaking API changes relative to OpenSSL 1.0. As we can't support both versions in the same software package, we've attempted to strike a middle ground and support the version we expect our users to most likely require, meaning OpenSSL 1.1 for our Linux SDKs and 1.0 otherwise. If you are running Linux with OpenSSL 1.0, a patch is available upon request.

When the license server receives a request, it will print to STDOUT the IP Address and SSL/TLS session protocol details. If the session protocol does not satisfy your organization's requirements then you should update your OpenSSL installation to allow for the use of a more modern protocol.

Usage Logging

Some licenses may require Usage Logging. Client usage logs are automatically transferred to the server when a license is obtained or released. The ROC SDK will manage client log files automatically by resetting them after transmission. The server will pool all client usage logs into a single log file. This log file should be preserved and sent to Rank One as contractually agreed to.

Shutdown

The license server is designed to gracefully shutdown on Ctrl+C / SIGINT events. New requests will be ignored and current requests will be completed.

Log File Migration

To transition to a new log file, Shutdown the server, rename the current log file, then restart the server. Clients can withstand temporary interruptions in server availability by design.