License Server

The ReqView Floating License Server is a web service providing floating licenses for ReqView products. It communicates with client applications using secure HTTPS connections, so it must be started with a TLS/SSL certificate and its private key.

The ReqView Floating License Server comes with a set of certificates so that it is easily started out of the box. However, you may wish to use existing certificates or generate your own. For more information on using existing certificates or generating your own, see TLS/SSL Certificates.

Note: The license server must run at the exact address and port for which the ReqView floating licenses were generated. The server’s TLS certificate must be issued for this address. Multiple DNS names and wildcards are not permitted.

Command Line Interface

Basic Usage and Arguments:

reqview_license_server [-h] [--host HOST [HOST ...]]
--port PORT
--certfile CERTFILE
[--adminpwfile ADMINPWFILE]
[--license LICENSE [LICENSE ...]]
OptionNecessityDescription
-h, --helpShow help message and exit
--hostoptionalHost(s) to bind to; defaults to 0.0.0.0 (all interfaces)
--portrequiredPort to serve on
--certfilerequiredFile in PEM format containing the server TLS/SSL certificate
--adminpwfileoptionalFile containing the password that protects the admin site (username is always admin), the password will be set to admin if not provided
--licenseoptionalReqView floating server license file(s) to serve; licenses will be stored until expiration

Example:

Start the ReqView Floating License Server on port 8000 with a TLS/SSL certificate stored in file server.pem:

reqview_license_server --port 8000 --certfile server.pem --license server-license.key

Run as Windows Service

Run the ReqView Floating License Server as a Windows service using NSSM (the Non-S***ing Service Manager).

Configuration

Run an Administrator command prompt and change the directory to a folder that will permanently contain the reqview_license_server.exe binary and files needed by it.

Install the service by using the provided service.cmd script. Change it based on your needs, if necessary.

...
nssm install reqview-license-server "%exepath%"
nssm set reqview-license-server AppParameters --port 8000 --certfile server.pem --adminpwfile adminpw.txt --license server-license.key
nssm set reqview-license-server DisplayName "%dispname%"
nssm set reqview-license-server Description "Provides floating licenses to ReqView clients."
nssm set reqview-license-server DependOnService Tcpip
nssm set reqview-license-server Start SERVICE_DELAYED_AUTO_START
nssm set reqview-license-server AppRestartDelay 900000
nssm set reqview-license-server AppThrottle 10000
nssm set reqview-license-server AppNoConsole 1
nssm set reqview-license-server AppStdout "%~dp0stdout.log"
nssm set reqview-license-server AppStderr "%~dp0stderr.log"
...

The arguments present on the second line will be used when the server is started or restarted, the service will not be able to start unless they are correct. Do not move or delete the directory or any files in it after the service is installed. The file nssm.exe must also be kept as it is the executable registered for the service.

Note: Quotes must be used when paths containing spaces are involved. Moreover, the quotes themselves must be quoted to be preserved for the AppParameters setting – we do not recommend using paths with spaces for this reason. Standard output and error streams are appended to the files given by AppStdout, resp. AppStderr parameters.

The program is allowed through the Windows Firewall by the netsh advfirewall command in the service.cmd script. You must allow the reqview_license_server.exe binary manually if you use any other firewall solution.

The service is started under the LocalSystem account by default (a predefined service account). To review or edit the service configuration using the NSSM GUI, run the nssm edit reqview-license-server command.

After the service is started, check the stderr.log file for errors. The service manager will keep restarting the server without success if invalid parameters or certificate files are provided, server database file cannot be created or a similar error occurs.

Note: If necessary, it is possible to run under the NetworkService account (a predefined service account with minimum privileges) by adding the line nssm set reqview-license-server ObjectName NetworkService to the service.cmd file before installing the service. This account cannot access most directories unless it is explicitly allowed to – read, write, and execute permissions for the server folder must be granted manually to this account. For more information, see Service User Accounts.

Service Management

The service starts automatically after system boot. Afterwards, you can manage the service (start, restart, stop, or query its status) using the following commands:

nssm start reqview-license-server
nssm restart reqview-license-server
nssm stop reqview-license-server
nssm status reqview-license-server

If necessary, stop the service and then uninstall it using the nssm remove reqview-license-server confirm command.

Run in Docker

Run the ReqView Floating License Server as a Docker Container using Docker Compose.

Configuration

Make sure that Docker is configured to start on boot – see Docker post-installation steps for Linux. Run a console with sufficient privileges and change the directory to the location of the reqview_license_server binary, certificate, and license files needed by it. This directory will be mounted as a volume in the Docker container and must be writable for the server instance.

The service is defined in the provided docker-compose.yml file. Change it based on your needs, if necessary.

version: "2"
services:
reqview-license-server:
image: debian:buster-slim
ports:
- "8000:8000"
restart: always
volumes:
- .:/app
working_dir: /app
entrypoint: ["/app/reqview_license_server", "--port", "8000",
"--certfile", "/app/server.pem",
"--adminpwfile", "/app/adminpw.txt",
"--license", "/app/server-license.key"]

Use the provided service.sh script to start the service:

$ ./service.sh

After starting the service, execute docker-compose logs to see that the service is running correctly. Docker compose will keep restarting the server without success if invalid parameters or certificate files are provided, server database file cannot be created or a similar error occurs. Make sure that your firewall and antivirus software are not blocking access to the license server.

Container Management

docker-compose start reqview-license-server
docker-compose restart reqview-license-server
docker-compose stop reqview-license-server
docker-compose logs reqview-license-server

If necessary, you can stop the service and then uninstall it using the docker-compose rm reqview-license-server command.

Update License or Server Binary

The following steps are necessary to update your server license or the license server binary to a newer version:

  1. Stop the service using the appropriate command
    • on Windows:
      nssm stop reqview-license-server
      
    • with Docker:
      docker-compose stop reqview-license-server
      
  2. Replace the license server executable and/or server-license.key files
  3. Start the service
    • on Windows:
      nssm start reqview-license-server
      
    • with Docker, pull the latest image beforehand:
docker-compose pull reqview-license-server
docker-compose start reqview-license-server

Note: The client license doesn’t need to be replaced after updating the server license. The clients will check out the new license once the server is up and running.

Migrating to a Different Server

If the need arises, the license server can be migrated to a different server.

DNS records in your network will probably have to be updated if you wish to keep the same URL. If you intend to change the server’s URL, both server and client license files will need to be regenerated – please contact us.

To migrate, follow these steps:

  1. Stop and uninstall the service using the appropriate command on the old server:
    • on Windows:
      nssm stop reqview-license-server
      nssm remove reqview-license-server confirm
      
    • with Docker:
      docker-compose stop reqview-license-server
      docker-compose rm reqview-license-server
      
  2. Set up the service on the new machine – see instructions for Windows or Docker.

Administration Web Page

You can check the Floating License Server status using the administration web page located at https://<license-server-url>/admin

Note: The <license-server-url> address must be the full address and match the address present in the server certificate exactly.

Note: Only Chrome and Firefox are supported when viewing the administration web page. Internet Explorer cannot display the page.

The administration web page is protected by a login form where the only correct username is "admin" and the password is taken from the file supplied by the --adminpwfile argument. The password is set to "admin" if no password file is provided.

The Licenses page shows the served licenses and current checkouts/borrows by ReqView users. If a ReqView user cannot check in a floating license (in exceptional circumstances), the license administrator can manually cancel the checkout/borrow by clicking the Cancel button.

The Log page shows all server events that have occurred during the last two weeks. The most recent event is listed at the top.

To refresh the website for updated information, press F5.

Querying License Server Status

You can query the server status in the console using curl tool on the https://<license-server-url>/status URL:

curl -k https://reqviewlicense.intranet.mycompany.com:8000/status

which will produce the following output in JSON format:

{
"my-reqview-floating-license": {
"issued": 10,
"in_use": 3
}
}

You can easily implement a script processing the JSON output and run it periodically. For example, the following Python script status.py outputs a message stating the currently available number of licenses:

import sys
import json
try:
data = json.load(sys.stdin)
except Exception:
data = {}
issued = 0
in_use = 0
for lic in data.values():
issued += lic['issued']
in_use += lic['in_use']
print("Total %d issued, %d in use" % (issued, in_use))

You can run the status.py script and curl command in a pipe:

curl -s -k https://reqviewlicense.intranet.mycompany.com:8000/status | python status.py

which will print:

Total 10 issued, 3 in use
Updated for version 1.1.3