Floating 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 valid TLS/SSL certificate and its private key.

The ReqView Floating License Server comes with a set of certificates so that it can be started out of the box easily. 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 license was 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]

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

Run as Windows Service

You can run the ReqView Floating License Server as a Windows service using NSSM (the Non-S***ing Service Manager). At least Windows 8.1 or Windows Server 2012 are required.

Follow these steps:

1. Configure Windows Service
2. Start Windows Service
3. Import ReqView License

Configure Windows Service

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

Edit the password that will protect the Administration web page in the adminpw.txt file.

Change the provided service.cmd script defining the service based on your needs:

...
nssm install reqview-license-server "%exepath%"
nssm set reqview-license-server AppParameters --port 8000 --certfile server.pem --adminpwfile adminpw.txt
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"
...

Notes:

• The service name reqview-license-server is not valid on certain Windows configurations. Remove the dashes from the service name in the service.cmd file if you encounter this error.
• 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.
• 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 service.cmd script configures the Windows Firewall to allow access to the server using the netsh advfirewall command. 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). 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.

To review or edit the service configuration using the NSSM GUI after installing the service, run

$ nssm edit reqview-license-server

After reviewing and updating the service.cmd script, start the service.

Start Windows Service

Use the provided service.cmd script to set up and start the service:

$ service.cmd

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.

After you’ve configured and started the service successfully, import the server license(s) into it.

Manage Windows Service

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

The server outputs access log messages into stdout.log file and logs all errors into stderr.log file. These file are never overwritten, they are always appended to, check them in case of any issues.

If necessary, stop the service and then uninstall it using the following command:

$ nssm remove reqview-license-server confirm

Run in Docker

You can run the ReqView Floating License Server in a Docker container using Docker Compose.

Follow these steps:

1. Configure Docker Service
2. Start Docker Service
3. Import ReqView License

Configure Docker Service

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.

Edit the password that will protect the Administration web page in the adminpw.txt file.

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:bullseye-slim
    ports:
      - "8000:8000"
    restart: unless-stopped
    volumes:
      - .:/app
    working_dir: /app
    entrypoint: ["/app/reqview_license_server", "--port", "8000",
                 "--certfile", "/app/server.pem",
                 "--adminpwfile", "/app/adminpw.txt"]

Note: We do not recommend building your own image using a custom Dockerfile and copying any of the license server files into it or into an existing container.

Start Docker Service

Use the provided service.sh script to set up and 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.

After you’ve configured and started the service successfully, import the server license(s) into it.

Manage Docker Service

You can manage the service (start, restart, stop, or query its status) using the following commands:

$ docker-compose start
$ docker-compose restart
$ docker-compose stop
$ docker-compose logs

The server outputs access log messages to standard output (stdout) and errors to standard error (stderr) streams. Use docker-compose logs to check logs in case of any issues. To see only the stderr stream, use docker-compose logs 1>/dev/null.

If necessary, you can stop and uninstall the service (i.e. stop and remove the docker container) using the following command

$ docker-compose down

Administration Web Page

With the service up and running, you can check the server status or import licenses using the administration web page located at
https://<hostname>:<port>/admin:

Notes:

• The <hostname> must be the fully qualified domain name and match the hostname field in the server certificate.
• The <port> must be included when entering the URL in your browser’s address bar.
• The URL must end with /admin, the root URL without this will only show 404: Not Found.
• The scheme (protocol) must be https://.
• Only Chrome, Edge 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.

Import or Update License

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 ❌ button. The number of cancellation requests in a given amount of time is limited.

Click Import or update a license button to choose the server license file (server-license.lic) that should be imported. If a license with the same ID is already present, the submitted license will replace (update) it.

The client license doesn’t need to be replaced after updating the server license if the license ID and the server’s address haven’t changed. The clients will check out the new license automatically right after it’s updated.

Check Server Log

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.

Update TLS/SSL Certificate

The following steps are necessary to update the TLS/SSL certificate after a renewal:

1. Run a console with sufficient privileges and change the directory to the location of the license server files
2. Replace the server.pem certificate file with the renewed one
3. Restart the service using the appropriate command
   • on Windows:

     $ nssm restart reqview-license-server

   • with Docker:

     $ docker-compose restart

Update Server Binary

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

1. Run a console with sufficient privileges and change the directory to the location of the license server files
2. Stop the service using the appropriate command
   • on Windows:

     $ nssm stop reqview-license-server

   • with Docker:

     $ docker-compose down

3. Replace the license server executable file reqview_license_server or reqview_license_server.exe with the new version
4. Start the service
   • on Windows:

     $ nssm start reqview-license-server

   • with Docker:

     $ chmod +x reqview_license_server
     $ docker-compose pull && ./service.sh

Note: The above instructions might not be suitable if the service was configured differently than using the provided defaults, e.g. a custom Dockerfile might require rebuilding of your image.

Migrate 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. Run a console with sufficient privileges and change the directory to the location of the license server files
2. 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 down

3. Set up the service on the new machine – see instructions for Windows or Docker.

Query 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

Troubleshooting

If you’re seeing only 404: Not Found when accessing the Administration web page, please ensure that the input address is correct.

Error messages can be seen in ReqView application when using a floating license, see below for their explanations and tips on what to do:

• A network or SSL certificate error was encountered when contacting the license server at <location>
  • The server is inaccessible or is using an invalid TLS/SSL server certificate. Verify that the server is reachable by running ping <location>.
• Invalid license ID
  • The server license with the given ID was not found on the server. Check that the server license was imported into the server after installation.
• All licenses are in use
  • The maximum number of allowed floating licenses has already been checked out. Contact us to upgrade your license if this prevents you from working effectively.
• The floating license borrow/checkout has been invalidated because the ReqView License Server configuration has changed
  • Your borrow/checkout was cancelled or the server was restarted and checkouts deleted. The app will try to check out a license automatically if it’s available.
• Invalid or expired server license
  • The server license has expired or is not yet valid. Contact us to renew your license.
• Server TLS/SSL certificate and license file mismatch
  • The DNS name found in the TLS/SSL certificate installed on the server does not match the address present in the server license. See the note about addresses at the top of this page.
• Error during checkout
  • The server ran into trouble when processing the checkout. Check the server error logs for file permission issues etc. or contact us for assistance.