Server configuration

This section will cover common customization options for License Server.

Note

The ZeroTurnaround License Server is an application built on the Play framework. It runs on on a Netty server. Most of the standard configuration options of Play are available for the License Server. In this chapter we only document the configuration details we confirm as useful. If you are looking for something more specific, please refer to the Play framework information sources.


License Server properties file

The License Server properties file license-server.properties can be found in the conf folder. This file is initially named license-server.properties.sample. To use it for storing License Server configuration parameters, rename this file to license-server.properties and save.

The file contains examples of supported configuration parameters. Uncomment these parameters and specify the desired values. Save the file

Note

Avoid editing the license-server.properties file when License Server is running.


Port

Specify a custom port for License Server to bind to via system property -Dhttp.port=<custom port>.

This parameter can be configured in the configuration file license-server.properties by using http.port=<custom port>.

Note

This value defaults to 9000.


Context path

Specify a custom context path for License Server to use via system property -Dapplication.context=/<custom context>. This path will also be used when generating new Group URLs.

For example, change the License Server root URL from http://localhost:9000 to http://localhost:9000/my.context by specifying -Dapplication.context=/my context. Doing this will also change the Group URL from http://localhost:9000/111-222-333 to http://localhost:9000/my.context/111-222-333.

This parameter can be configured in the configuration file license-server.properties by using application.context=/<custom context>.

Note

This value defaults to /.


Listen address

This is useful when you have multiple network cards with different listening addresses on your server, and you want the License Server to be reachable only on one of them. This can be achieved by setting the system property -Dhttp.address=<custom listen address>. For example, if one of your network cards has the address 44.44.44.44 and you want just that one to serve the requests, you could start the License Server by:

$ bin/license-server -Dhttp.address=44.44.44.44

If you have configured an alias for that IP within your /etc/hosts, you can also use that hostname as the value of -Dhttp.address.

This parameter can be configured in the configuration file license-server.properties by using http.address=<custom listen address>.


Simple HTTPS

Use the configuration option -Dhttps.port=<custom port> to run the server with out-of-box HTTPS. A self-signed keystore will be generated into the conf directory, HTTPS connections will be accepted from the port you specified.

This parameter can be configured in the configuration file license-server.properties by using https.port=<custom port>.

Note

The self-signed certificate does not unleash the full power of HTTPS. The traffic will be encrypted, but no end-point validation can be done, leaving you open to man-in-the-middle attacks. To be totally safe on public networks, you should still use an external HTTPS provider with a trusted certificate.


Override License Server host name or IP address

Use the configuration option -Drebel.ls.host=<hostname|IP:port> to override the default License Server host name or IP address for Group URL generation. The specified host name or IP will be used for all Group URLs that are generated for this License Server. Specifying the port is optional. The override command is valid until the License Server is restarted.

This parameter can be configured in the configuration file license-server.properties by using ls.host=<hostname|IP:port>.

Note

The License Server host name or IP override command can also be specified using the configuration file conf/license-server.properties. Edit this configuration file and specify the desired host name or IP using the parameter rebel.ls.host=<hostname|IP:port>.


Front-end HTTP(S) proxy

You can configure a reverse proxy in front of the license server. For configuring an appropriate HTTPS, this is in fact highly recommended. License Server supports de facto standard proxy headers X-Forwarded-For, X-Forwarded-Host and X-Forwarded-Proto.

Example configuration for Apache 2:

LoadModule proxy_module modules/mod_proxy.so

...

<VirtualHost *:80>
  # HTTPS
  # RequestHeader set X-Forwarded-Proto "https"

  ProxyPreserveHost On
  ServerName license-server.mycompany.com
  ProxyPass / http://127.0.0.1:9000/
  ProxyPassReverse / http://127.0.0.1:9000/
</VirtualHost>

When the reverse proxy is used for providing HTTPS, be sure to configure the proxy to add the X-Forwarded-Proto "https" request header. Otherwise, the system would work, but the Group URLs shown in the GUI would have HTTP as the protocol instead of HTTPS.


Location of License Server data

It is possible to customize the location for the License Server data (H2 database, activation file and database backups, if created). Many administrators wish to do this in order to separate the application itself (easily re-downloadable) from its data (unique to your installation and impossible to recover unless backed up).

The default location for License Server data is the folder data in the LS root directory. To override this, use the JVM argument -Drebel.ls.dataDir. For example:

$ ./bin/license-server.sh run -Drebel.ls.dataDir=/var/license-server

This folder has to be writable for the user under which LS is executed.


Automatic scheduled backups

The License Server prepares automatic backups of its current database every Sunday at 3 AM (License Server time). Two backups will be kept at all times.

rebel.ls.backup=<true|false>

Note

This value defaults to true.


License Server backup location

The License Server backups are kept in the data/backup/ folder within the License Server root folder. This location can be overridden by using configuration parameter rebel.ls.backup.dir. This location is used for both manual and automated backups.

rebel.ls.backup.dir=./data/backup

Note

This value defaults to ./data/backup.


Logging

License Server uses Logback as the logging framework. Please refer to Logback documentation for details.


Customizing the log level

You can customize the logging level of License Server using a JVM argument and within the license-server.properties file. The JVM argument for logging is -Drebel.ls.loglevel=<level>. Logback’s valid levels are TRACE, DEBUG, INFO, WARN, ERROR, ALL or OFF. The default logging level is set at INFO. Here is an example of the logging parameter setting logging to trace level:

$ ./bin/license-server.sh run -Drebel.ls.loglevel=TRACE

This parameter can be configured in the configuration file license-server.properties by using rebel.ls.loglevel=<level>.


Customizing the logfile path

You can customize the location of the logfile. Set the -Drebel.ls.logfile=<your-custom-path> JVM argument for this.


Configuring log file rotation

You can configure the License Server log file rotation using the -Drebel.ls.logRotate=true|false argument. The default value of this argument is set to true.

To further configure the log file rotation setting, adjust the <minIndex> (default is 1) and <maxIndex> (default is 5) values. To adjust the maximum log file size, configure the <maxFileSize> value.


Further customizations

To fully customize logging, you can provide a custom Logback configuration file via system property -Dlogger.file=<file path>.

Note

You can alternatively add either of the mentioned properties to your JAVA_OPTS environment variable, from where it will be forwarded to the License Server Java process by our startup scripts.

Default logger configuration file used is:

<configuration>

  <conversionRule conversionWord="coloredLevel" converterClass="play.api.Logger$ColoredLevel" />

  <!-- special parameter to disable log Rotation (on by default) -->
  <if condition='property("rebel.ls.logRotate").equals("false")'>
    <then>
      <appender name="FILE" class="ch.qos.logback.core.FileAppender">
        <file>${rebel.ls.logfile:-${application.home}/logs/application.log}</file>
        <encoder>
          <pattern>[%d{yyyy-MM-dd HH:mm:ss.SSS}] %level [%logger{0}] [%thread] - %message%n%xException</pattern>
        </encoder>
      </appender>
    </then>

    <!-- If not explicitly disabled, use Log Rotate -->
    <else>
      <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${rebel.ls.logfile:-${application.home}/logs/application.log}</file>

        <rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy">
          <fileNamePattern>${rebel.ls.logfile:-${application.home}/logs/application.log}.%i.zip</fileNamePattern>
          <minIndex>1</minIndex>
          <maxIndex>5</maxIndex>
         </rollingPolicy>

        <triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
          <maxFileSize>20MB</maxFileSize>
        </triggeringPolicy>

        <encoder>
          <pattern>[%d{yyyy-MM-dd HH:mm:ss.SSS}] %level [%logger{0}] [%thread] - %message%n%xException</pattern>
        </encoder>
      </appender>
    </else>
  </if>

  <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
      <pattern>[%d{HH:mm:ss.SSS}] %coloredLevel [%logger{0}] [%thread] - %message%n%xException</pattern>
    </encoder>
  </appender>

  <logger name="play" level="INFO" />
  <logger name="application" level="${rebel.ls.loglevel:-INFO}" />

  <logger name="controllers" level="${rebel.ls.loglevel:-INFO}" />
  <logger name="models" level="${rebel.ls.loglevel:-INFO}" />
  <logger name="com.zeroturnaround" level="${rebel.ls.loglevel:-INFO}" />

  <logger name="com.zeroturnaround.ls.service.LiberalHttpClient" level="WARN" />

  <!-- also enable logging for tests -->
  <logger name="com.zeroturnaround.ls.test" level="DEBUG" />

  <!-- special logger for performance. only turned on with the special JVM argument -->
  <if condition='property("rebel.ls.logPerformance").equals("true")'>
    <then>
        <logger name="rebel.ls2.performance" level="DEBUG" />
    </then>
    <!-- If not explicitly enabled, use the overall log level -->
    <else>
      <logger name="rebel.ls2.performance" level="${rebel.ls.loglevel:-INFO}" />
    </else>
  </if>

  <!-- log liquibase db upgrades -->
  <logger name="liquibase" level="INFO" />

  <root level="ERROR">
    <appender-ref ref="STDOUT" />
    <appender-ref ref="FILE" />
  </root>

</configuration>

It is easiest to use this as a starting point in creating your own tailor-made logger configuration, should you need it.


Mail service

In order to allow License Server to send out various email notifications, you need to select using either the ZeroTurnaround provided email service or using your own SMTP mail server.

../_images/mail-settings.png

When using your own SMTP mail server, you need to configure the SMTP server settings through which the outgoing e-mails can be sent.

For example, the working settings for a Gmail account include:

  • host: smtp.gmail.com
  • username: [your gmail username]
  • TLS: [true]
  • SSL: [true]
  • port: 465

E-mails sent out by the license server include:

  • Verification emails for when a developer is trying to re-use his seat on another computer.
  • Notifications about licenses about to expire soon.
  • License server Group URLs, sent out to developers by the administrator via the License Server GUI.

Miscellaneous settings

The miscellaneous settings sections contains the following options.

  • Forbid offline tokens for this server - completely disables using offline tokens for this License Server instance. This option is disabled by default.
  • Report usage statistics - allow the License Server to send anonymous data for analysis and development to ZeroTurnaround. This option is enabled by default.
  • Notify administrator when running low on seats – allow the License Server to email the administrator when the license pool is running low.
  • Specify the average redeploy time for your developers (in seconds) – override the default redeploy time value that is used to generate License Server statistics. This value is used to override the default redeploy time from the JRebel agent (unless specified by the JRebel user).

Password recovery

As a last resort, you can override any License Server user password by executing the bin/reset-password.sh|cmd script. User email and a new password will be asked for interactively. If you do not recall the user email, type list instead of the email for a list of all registered users.

Note

Make sure the License Server is stopped before executing this script.

Warning

This also means that anyone able to execute this script has complete control over the License Server!


Upgrading the License Server

To upgrade the License Server to the latest version, do the following:

  1. Stop your License Server application.

Note

Backup the database before the upgrade. Just in case.

  1. Download the latest version of the License Server.
  2. Extract the new version into your License Server directory.

Note

The files you extract from the ZIP only overwrite application binaries. Your database and other data files are not overwritten.

  1. Restart the License Server application.
  2. Done!

Note

The License Server will require re-activation when the upgrade takes place in a new network environment (for example when the server’s IP address has changed).

You can always see the currently installed version number for the License Server in the footer of every License Server application page.

Do you need to upgrade your License Server from version 1.x? Learn more here.