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
Installation
-
You will have received links containing the license server installation files.
Please download the .zip file for your corresponding operating system.
-
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-*.
-
Configure licenseusage.properties with:
- The persistent volume data directory location e.g. license.data.directory=data
- The UI HTTP port e.g.
user.interface.port=8050
user.interface.port.enabled=true
- (optional) The UI HTTPS port and certificates e.g.
user.interface.https.port=8051
user.interface.https.port.enabled=true
user.interface.https.jks.path=certs/user-interface-https.jks
user.interface.https.jks.password=trafficparrot
- The usage port that Traffic Parrot will connect to e.g.
license.usage.port=8040
license.usage.port.ssl.enabled=true
-
It is also possible for Traffic Parrot to connect to the UI port
on path /api/usage if you need to use a single port for both
the UI and license usage
- 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
-
Place a copy of your trafficparrot.usage.license file in the usage server working directory
-
Deploy the license usage server as a 24/7 application somewhere in your network that is visible to all Traffic Parrot instances
-
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
- Task Scheduler or NSSM service helper on Windows
Running in Docker
You may optionally use Docker to run the license server using the following steps:
-
Copy the trafficparrot-license-usage-*.zip release to the current directory.
- We recommend to use the bundled JRE distribution we provide per OS, which means you do not need a base image with Java installed. Linux is typically used for Docker.
- The examples below show how to use a Java base image, in case you are using the no-JRE bundle
- Copy the trafficparrot.usage.license file to the current directory.
-
Save the following Dockerfile content.
These are only example files, to help get you started, but you can modify them to suit your needs.
Eclipse Temurin OpenJDK 21 LTS base image example
FROM eclipse-temurin:21-jre
RUN apt-get update && apt-get install unzip -y
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
RUN chgrp -R 0 /opt/trafficparrot-license-usage && chmod -R g=u /opt/trafficparrot-license-usage
WORKDIR /opt/trafficparrot-license-usage
VOLUME ["/opt/trafficparrot-license-usage/data"]
CMD ["./start.sh"]
Alpine base image example with Java 21 LTS
FROM alpine:3
RUN apk add --no-cache openjdk21-jre bash libc6-compat gcompat
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
RUN chgrp -R 0 /opt/trafficparrot-license-usage && chmod -R g=u /opt/trafficparrot-license-usage
ENV LD_LIBRARY_PATH=/usr/lib:/opt/trafficparrot-license-usage/jre/lib/amd64/server:/opt/trafficparrot-license-usage/jre/lib/amd64
WORKDIR /opt/trafficparrot-license-usage
VOLUME ["/opt/trafficparrot-license-usage/data"]
CMD ["./start.sh"]
-
Build an image, for example:
docker build -t trafficparrot-license-usage:latest -t trafficparrot-license-usage:$(date '+%d-%b-%YT%H-%M-%S') .
-
Run a container, for example:
docker run -p 8050:8050 -p 8040:8040 -v /opt/data:/opt/trafficparrot-license-usage/data trafficparrot-license-usage:latest
-
In this example:
- The host persistent volume is /opt/data
- The container mount point is /opt/trafficparrot-license-usage/data
-
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.
Running in OpenShift
You may optionally use OpenShift to run the license server using the following steps:
- Follow the steps to build a Docker container and push to your OpenShift Docker registry
- Configure a persistent volume
- Configure a single pod deployment configuration with the persistent volume mounted
- Configure a service with TCP ports 8040, 8050, 8051
- Configure a health check GET /api/health on either of the UI ports HTTP 8050 or HTTPS 8051
- (optional) Configure an alerting check GET /api/activation on either of the UI ports HTTP 8050 or HTTPS 8051
- Configure a route for the UI
- Use Edge termination if routing to the HTTP UI port 8050
- Use Passthrough or Re-encrypt termination if routing to the HTTPS UI port 8051
-
It is also possible for Traffic Parrot to connect to the UI port
on path /api/usage if you need to use a single port for both
the UI and license usage
- Configure a route for the license usage port 8040. Your trafficparrot.license will be configured to support either a direct SSL/TLS binary connection to the license server or an HTTP(S) connection to allow for an on premise proxy server with path based routing (e.g. an F5 or NGINX proxy).
- Use Passthrough termination when using a direct SSL/TLS binary connection to the license server
- Use Re-encrypt termination when using an HTTPS proxy server and license.usage.port.ssl.enabled=true
- Use Edge termination when using an HTTPS proxy server and license.usage.port.ssl.enabled=false
-
In this example:
- The license usage port is 8040
- The HTTP UI port is 8050
- The HTTPS UI port is 8051
-
You must configure a persistent volume mount in the deployment configuration
so that the license server data is not lost if the pod is stopped.
-
If you receive an HTTP 502 response from an OpenShift route this can sometimes
mean you are incorrectly using insecure Edge termination for a secure target.
We also have a sample Helm chart that can be used to help you get started, you can download it here and follow the included instructions.
For the latest examples, check out our Traffic Parrot Helm Examples GitHub repository.
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 and the installation directory or Docker image
will no longer be changing.
Please follow the steps below to perform activation:
-
Visit the Traffic Parrot License Activation web page by clicking the link on the license server UI:
-
Follow the link, including the full URL that looks like https://license.trafficparrot.com?id=example
- (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
- Upload your trafficparrot.usage.license file
-
You will receive a response with an activation token that is valid for 72 hours to activate the running license server:
- This is the only time you will be shown this token, please take note of it
- If the license server is restarted before activation then the token will no longer be valid
-
Visit your local license server activation page:
- Enter your token and click submit
-
You will see a success message:
-
The server will remain activated unless any of the following occur:
- The license server data directory changes
- The license server installation directory changes
- The license server Docker image is rebuilt
which will require you to contact us to request activation of the new installation.
- 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:
- 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)
-
Configure trafficparrot.properties with the host and port of the usage server.
Your trafficparrot.license will be configured to support either a direct SSL/TLS binary connection to the license server or an HTTP(S) connection to allow for an on premise proxy server with path based routing (e.g. an F5 or NGINX proxy).
- When using a direct SSL/TLS binary connection to the license server e.g.
trafficparrot.license.usage.server=licensehost:8040
- When using an HTTPS proxy server with SSL e.g.
trafficparrot.license.usage.server=https://proxyhost/some/path
with the proxy server routing to https://licensehost:8040 and license server licenseusage.properties license.usage.port.ssl.enabled=true
- When using an HTTPS proxy server without SSL e.g.
trafficparrot.license.usage.server=https://proxyhost/some/path
with the proxy server routing to http://licensehost:8040 and license server licenseusage.properties license.usage.port.ssl.enabled=false
-
It is also possible for Traffic Parrot to connect to the UI port
on path /api/usage if you need to use a single port for both
the UI and license usage
-
(optional) Configure trafficparrot.properties to allow sending
custom headers to the proxy server, which may be necessary if your proxy server
requires header based authentication:
trafficparrot.license.usage.custom.headers=ExampleA:ValueA,ExampleB:ValueB
-
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
- Now when Traffic Parrot instances start up and shut down you should start to see data in the usage server
- 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
