Introduction

What is the Traffic Parrot License Server?

The license server allows Traffic Parrot instances to start up and make use of the licenses that were purchased.

Each Traffic Parrot instance will consume one of the purchased licenses until it is shut down.

There are 3 key states of a Traffic Parrot instance when connecting to the usage server:

  1. Check out a license on startup
  2. (optional) Keep alive a license if it is used for an extended period
  3. Check in a license on shutdown (waits for check in before shutting down)

Architecture

Each Traffic Parrot instance connects to the Traffic Parrot License Server to check out a license on startup.
Traffic Parrot License Server Architecture

First Steps

Prerequisites

Traffic Parrot License Server has the following minimum requirements. Customers with a large number of Traffic Parrot instances or with intensive usage may exceed these minimum requirements.

  • 256MB RAM
  • 1GB persistent volume (SSD recommended)
  • Host with 24/7 availability
  • Host accessible from all Traffic Parrot instances
  • Each purchased license pool must be used with a separate single license server instance

Running in Docker

You may optionally use Docker to run the license server using the following steps:

  1. Copy the trafficparrot-license-usage-*.zip release to the current directory.
  2. Copy the trafficparrot.usage.license file to the current directory.
  3. Save the following Dockerfile content. These are only example files, to help get you started, but you can modify them to suit your needs.
    OpenJDK base image example
    FROM openjdk:8u282-jre
    
    WORKDIR /opt
    COPY trafficparrot-license-usage-*.zip trafficparrot-license-usage.zip
    RUN unzip trafficparrot-license-usage.zip && rm trafficparrot-license-usage.zip && mv trafficparrot-license-usage-* trafficparrot-license-usage
    COPY trafficparrot.usage.license /opt/trafficparrot-license-usage
    
    WORKDIR /opt/trafficparrot-license-usage
    VOLUME ["/opt/trafficparrot-license-usage/data"]
    CMD ["./start.sh"]
    Alpine base image example
    FROM alpine:3.14.2
    
    RUN apk add --no-cache openjdk8-jre bash libc6-compat
    
    WORKDIR /opt
    COPY trafficparrot-license-usage-*.zip trafficparrot-license-usage.zip
    RUN unzip trafficparrot-license-usage.zip && rm trafficparrot-license-usage.zip && mv trafficparrot-license-usage-* trafficparrot-license-usage
    COPY trafficparrot.usage.license /opt/trafficparrot-license-usage
    
    WORKDIR /opt/trafficparrot-license-usage
    VOLUME ["/opt/trafficparrot-license-usage/data"]
    CMD ["./start.sh"]
  4. Build an image, for example:
    docker build -t trafficparrot-license-usage .
  5. Run a container, for example:
    docker run -p 8050:8050 -p 8040:8040 -v /opt/data:/opt/trafficparrot-license-usage/data trafficparrot-license-usage
  6. In this example:
    • The host persistent volume is /opt/data
    • The container mount point is /opt/trafficparrot-license-usage/data
  7. You must always provide a persistent volume mount when starting the container so that the license server data is not lost if the container is stopped.

Installation

  1. You will have received links containing the license server installation files. Please download the .zip file for your corresponding operating system.
  2. Transfer the .zip file to the host machine and extract the contents. You will have a folder with a name starting with trafficparrot-license-usage-*.
  3. Configure licenseusage.properties with:
    • The persistent volume data directory location e.g. license.data.directory=data
    • The UI port e.g. user.interface.port=8050
    • The usage port that Traffic Parrot will connect to e.g. license.usage.port=8040
    • The number of minutes before a license is released if Traffic Parrot loses connectivity to the license server e.g. license.time.out.in.minutes=5
  4. Place a copy of your trafficparrot.usage.license file in the usage server working directory (this has already been done for you in the download links we provide)
  5. Deploy the license usage server as a 24/7 application somewhere in your network that is visible to all Traffic Parrot instances
  6. The start script will launch the license server in a foreground process. To detach the process you can use commands:
    • nohup ./start.sh >nohup.out 2>&1 </dev/null & on Linux
    • NSSM service helper on Windows

Activation

Before Traffic Parrot instances can successfully connect to the license server, it must be activated.

Please note that this is a one time only operation that should only be performed on a production ready license server that has been assigned a permanent persistent data volume.

Please follow the steps below to perform activation:

  1. Visit the Traffic Parrot License Activation web page by clicking the link on the license server UI:
    Traffic Parrot License Activation Link
  2. Follow the link, including the full URL that looks like https://license.trafficparrot.com?id=example
    Traffic Parrot License Activation
  3. (optional) If you do not have access to the activation web page, contact support@trafficparrot.com and we will issue a token via email if you provide us with the link
  4. Upload your trafficparrot.usage.license file
  5. You will receive a response with an activation token that is valid for 72 hours to activate the running license server:
    Traffic Parrot License Activation success
  6. This is the only time you will be shown this token, please take note of it
  7. If the license server is restarted before activation then the token will no longer be valid
  8. Visit your local license server activation page:
    GUI Activation page
  9. Enter your token and click submit
  10. You will see a success message:
    GUI Activation page success
  11. If you encounter any issues or lose your activation token please contact support@trafficparrot.com

Connecting Traffic Parrot

Now the license server is deployed, we can connect Traffic Parrot instances to it:

  1. Place a copy of your trafficparrot.license file in the Traffic Parrot working directory (this has already been done for you in the download links we provide)
  2. Configure trafficparrot.properties with the host and port of the usage server e.g. trafficparrot.license.usage.server=localhost:8040
  3. Check logs/trafficparrot.log and you should see messages like this:
    Checking out initial license usage token
    Checked out initial license usage token PWEZWDW8S7E6EWOG with expiry 2020-11-15T13:37:54.465Z
    License usage token PWEZWDW8S7E6EWOG renewed with expiry 2020-11-15T13:42:54.523Z
    Checking in license usage token PWEZWDW8S7E6EWOG before shutdown
    Checked in license usage token PWEZWDW8S7E6EWOG
  4. Now when Traffic Parrot instances start up and shut down you should start to see data in the usage server
  5. Please ensure Traffic Parrot is shut down gracefully (in particular when using Docker) so that licenses can be released as soon as they are not in use, otherwise you will not be able to use the license until it has timed out

Upgrades

Upgrading only Traffic Parrot

  1. Stop Traffic Parrot
  2. Take a backup of the previous installation directory
  3. Copy the configuration that you would like to preserve from the previous installation to the new installation, for example this typically includes:
    • Compare trafficparrot.properties with the previous version and keep any custom property settings
    • Compare jvm.args with the previous version and keep any custom JVM settings
    • Copy ibm-mq-connections.json
    • Copy mappings directory
    • Copy ibm-mq-mappings directory
    • Copy data directory
    • Copy __files directory
    • Copy certificates certificate directory if you have custom certificates
    • Copy lib/external JAR directory if you have custom JARs
    • Compare the installation directory with the previous version to check for any other configuration differences
  4. Follow the instructions for connecting to the license server
  5. (optional) You can use the upgrade script (upgrade.sh on Linux/Mac or upgrade.exe on Windows) to help you perform the backup and configuration migration in the previous steps:
    • First, unzip the new release, and you will find the upgrade script there
    • For example on Linux/Mac in a terminal:
      ./upgrade.sh /path/to/previous-trafficparrot
    • For example on Windows at the command prompt:
      upgrade.exe "C:\path\to\previous-trafficparrot"
    • Your configuration changes from the previous installation will be merged into the new installation
    • (optional) Additional arguments can be used with the upgrade script:
      • --replace-existing will automatically replace the previous installation with the new installation, and backup the previous installation into a new folder
      • --interactive will prompt for user input to decide whether to stop the old instance and start the new instance
      • --automatic-stop will automatically stop a previously running instance before upgrading
      • --automatic-start will automatically start the new instance after upgrading
  6. Start Traffic Parrot

Upgrading only Traffic Parrot License Server

  1. Stop Traffic Parrot License Server
  2. Take a backup of the installation directory
  3. To preserve the usage history, copy the data directory from the previous installation to the new installation before starting
  4. Follow the instructions for installation
  5. Follow the instructions for activation
  6. Start Traffic Parrot License Server

Upgrading both Traffic Parrot and Traffic Parrot License Server

  1. Follow the instructions for upgrading Traffic Parrot License Server
  2. Follow the instructions for upgrading Traffic Parrot

Usage Reports

Hourly Peak Usage CSV Export

Customers with an on premise license server are requested to provide usage reports to Traffic Parrot via email. To export a CSV report:

  1. Visit the license server GUI Reports page:
    GUI Reports page
  2. Select the date range
  3. Click the "Load selected date range" button
  4. Click the "Peak license usage by hour" button
  5. A report with a file name similar to peak-usage-by-hour-16-Oct-2020-to-15-Nov-2020-Kq20bQre6MhgswfyG2RYFFIWr3FXTszZkDPnDq5FctL3wkxbb3KpGQ_.csv will be downloaded with content
    Date,Peak license usage in hour
    2020-10-16-00,3
    2020-10-16-01,2
    2020-10-16-02,2
    2020-10-16-03,0
    2020-10-16-05,1
    2020-10-16-06,4
    ...
  6. Please send a copy of the report to support@trafficparrot.com, keeping the same file name that was generated