Setting Up a Floating License Server for Oxygen XML Editor

Determine if you need to set up a license server

If you are using floating licenses for Oxygen XML Editor, you may need to set up a license server. If the computers that will be using the floating licenses are on different network segments, you must use an Oxygen XML Editor floating license server. A floating license server can be installed as one of the following:
Note: Oxygen XML Editor version 17 or higher requires a license server version 17 or higher. License servers version 17 or higher can be used with any version of a floating license key.

Activating Floating License Keys

To help you comply with the Oxygen XML Editor EULA (terms of licensing), all floating licenses require activation. This means that the license key will be locked to a particular license server deployment and no multiple uses of the same license key are possible.

During the activation process, a code that uniquely identifies your license server deployment is sent to the Oxygen XML Editor servers, which in turn will sign the license key.

Split or combine license keys to work with your license servers

A license server can only manage one license key (which can cover any number of floating licenses). If you have multiple license keys for the same Oxygen XML Editor version and you want to have all of them managed by the same server, or if you have a multiple-user floating license and you want to split it between two or more license servers, please contact support@oxygenxml.com and ask for a new license key.

Parent topic: Installation

Setting up a Floating License Server Running as a Java Servlet

Setting up the floating license server as a servlet.

Steps for Installing the Floating License Server as a Servlet
  1. Make sure that Apache Tomcat 5.5 or higher is running on the machine you have selected to be the license server. To get it, go to http://tomcat.apache.org.
  2. Download the Web ARchive (.war) license servlet from the Oxygen XML Editor website.
  3. Configure Tomcat to use a security Realm element. Refer to the Tomcat Documentation for more information.
  4. Edit the tomcat-users.xml file from your Tomcat installation and configure one user for each of the following roles: standard, admin, and manager.
  5. Go to the Tomcat Web Application Manager page and log-in with the user you configured with the manager role. In the WAR file to deploy section, choose the WAR file and click the Deploy button. The oXygen License Servlet is now up and running, but the license keys are not yet registered.
  6. Activate the license key. This process involves binding your license key to your license server deployment. Once the process is completed you cannot activate the license with another license server. Follow these steps to activate the license:
    1. Access the license servlet by following the link provided by the Tomcat Web Application Manager page. If prompted for authentication, use the credentials configured for the admin or manager users.

      Result: A page is displayed that prompts for a license key.

    2. Paste your license key into the form and press Submit. The browser used in the activation process needs to have Internet access.
      Result: You will be redirected to an online form hosted on the Oxygen XML Editor website. This form is pre-filled with an activation code that uniquely identifies your license server deployment, and your license key.
      Note: If, for some reason, your browser does not take you to this activation form, refer to the Manual Activation Procedure.
    3. Press Activate.

      If the activation process is successfully completed, your license server is running. Follow the on-screen instructions to configure the Oxygen XML Editor client applications.

  7. By default, the license server logs its activity in the /usr/local/tomcat/logs/oxygenLicenseServlet.log file. To change the log file location, edit the log4j.appender.R2.File property from the /usr/local/tomcat/webapps/oXygenLicenseServlet/WEB-INF/lib/log4j.properties configuration file.

Manual License Activation Procedure

  1. Access the license servlet by following the link provided by the Tomcat Web Application Manager page. You will be taken to the license registration page.
  2. Copy the license server activation code.
  3. Go to the activation page at http://www.oxygenxml.com/activation/.
  4. Paste the license server activation code and floating license key in the displayed form, then click Activate.
  5. The activated license key is displayed on-screen. Copy the activated license key and paste it in the license registration page of the servlet.

Upgrading Your Floating License Servlet

The goal of the following procedure is to help you minimize the downtime when you upgrade the Oxygen XML Editor floating license servlet to its latest version.

Follow this procedure:
  1. Access the license servlet by following the link provided by the Tomcat Web Application Manager page. If prompted for authentication, use the admin or manager credentials.
  2. Click the View license key link and copy the displayed license key to a file for later use.
  3. Go to the Tomcat Web Application Manager page, log in with the user you configured with the manager role, and Undeploy the floating license servlet.
  4. Go to Oxygen XML Editor website and download the license servlet.
  5. Deploy the downloaded license servlet.
  6. Access the license servlet by following the link provided by the Tomcat Web Application Manager page. If prompted for authentication, use the credentials configured for the admin or manager users.
  7. Paste the license key into the form and register it.

Replacing a Floating License Key in a Floating License Servlet

The following procedure assumes that your Oxygen XML Editor floating license servlet contains a previously activated license key and provides instructions for replacing it with another one. The goal of the procedure is to minimize the license servlet downtime during the activation step of the new license key.

This is useful if, for instance, you want to upgrade your existing license to the latest version or if you receive a new license key that accommodates a different number of users.

To replace a floating license key that is activated on your floating license servlet with a new one, follow these steps:
  1. Access the license servlet by following the link provided by the Tomcat Web Application Manager page.
  2. Click the Replace license key link. This will open a page that contains details about the license currently in use.
  3. Click the Yes button to begin the replacement procedure.
    Note: During the replacement procedure, new instances of Oxygen XML Editor cannot be licensed by the servlet until the process is completed.
  4. Paste the new floating license key in the displayed form, then click Submit. The browser used in the process needs to have Internet access.
    You will be redirected to an online form hosted on the Oxygen XML Editor website. This form is pre-filled with an activation code that uniquely identifies your license server deployment and your license key.
    Note: If for some reason your browser does not take you to this activation form, refer to the Manual Activation Procedure.
  5. Press Activate.

    If the activation process is completed successfully, your license servlet is now running using the new license key. You can click View license key to inspect the key currently used by the license servlet.

    Important: If the activation procedure fails, go to step 1 and click Cancel to revert to the last successfully activated license key.

Getting More Information From the Report Page

You can access a license server activity report at http://hostName:port/oXygenLicenseServlet/license-servlet/report.

It displays the following real time information:
  • License load - A graphical indicator that shows how many licenses are available. When the indicator turns red, there are no more licenses available.
  • Floating license server status - General information about the license server status, including the following information:
    • server start time
    • license count
    • rejected and acknowledged requests
    • average usage time
    • license refresh and timeout intervals
    • location of the license key
    • server version
  • License key information - License key data, including the following information:
    • licensed product
    • registration name
    • company name
    • license category
    • number of floating users
    • Maintenance Pack validity
  • Current license usage - Lists all currently acknowledged users, including the following information:
    • user name
    • date and time when the license was granted
    • name and IP address of the computer where Oxygen XML Editor runs
    • MAC address of the computer where Oxygen XML Editor runs
Note: The report is also available in XML format at http://hostName:port/oXygenLicenseServlet/license-servlet/report-xml.

Setting up a Floating License Server Running as a Standalone Process Using a 32-bit Windows Installer

Setting up the floating license server as a standalone process for Windows.

Steps for Installing the Floating License Server in Windows as a Standalone Process

  1. Download the license server installation kit for Windows from the Oxygen XML Editor website.
  2. Run the downloaded installer and follow the on-screen instructions.

    By default, the installer installs the license server as a Windows service. Optionally, you have the ability to start the Windows service automatically at Windows startup or create shortcuts on the Start menu for starting and stopping the Windows service manually. If you want to manually install, start, stop, or uninstall the server as a Windows service, run the following scripts from a command line as an Administrator:

    • installWindowsService.bat [serviceName] - Installs the server as a Windows service with the name serviceName. The parameters for the license key folder and the server port can be set in the oXygenLicenseServer.vmoptions file.
    • startWindowsService.bat [serviceName] - Starts the Windows service.
    • stopWindowsService.bat [serviceName] - Stops the Windows service.
    • uninstallWindowsService.bat [serviceName] - Uninstalls the Windows service.
    Note: If you do not provide the serviceName argument, the default name oXygenLicenseServer is used.
    If the license server is installed as a Windows service, the output and error messages are automatically redirected to the following log files that are created in the install folder:
    • outLicenseServer.log - Standard output stream of the server.
    • errLicenseServer.log - Standard error stream of the server.
  3. Manually add the oXygenLicenseServer.exe file in the Windows Firewall list of exceptions. Go to Control Panel > System and Security > Windows Firewall > Allow a program or feature through Windows Firewall > Allow another program and browse for oXygenLicenseServer.exe from the Oxygen XML Editor License Server installation folder.
  4. Floating licenses require activation prior to use. More details are available either on-screen (if the license server is started in a command line interface) or in the outLicenseServer.log log file.
    Note: A license server can only manage one license key (which can cover any number of floating licenses). If you have multiple license keys for the same Oxygen XML Editor version and you want to have all of them managed by the same server, or if you have a multiple-user floating license and you want to split it between two or more license servers, please contact support@oxygenxml.com and ask for a new license key.

Upgrading Your Floating License Server

The goal of the following procedure is to help you minimize the downtime generated when you upgrade the Oxygen XML Editor floating license server to its newest version.

Follow this procedure:
  1. Go to the Oxygen XML Editor website and download the latest floating license server.
  2. Run the installation kit.
  3. Leave the default Update the existing installation option enabled. This will ensure that some options set in the previous version (namely the installation folder, port number, and the floating license key in use) of the license server will be preserved.
  4. Follow the on-screen instructions to complete the installation process.

Replacing a Floating License Key in a Floating License Server

The following procedure assumes that your Oxygen XML Editor floating license server contains a previously activated license key and provides instructions for replacing the activated license key with another one. The goal of the procedure is to minimize the license servlet downtime during the activation step of the new license key.

This is useful if, for instance, you want to upgrade your existing license to the latest version or if you receive a new license key that accommodates a different number of users.

To replace a floating license key that is activated on your floating license server with a new one, follow these steps:
  1. Stop the service that runs the floating license server.
  2. Locate the folder that holds the previous activated license key (by default, it is named license and it is located in the installation directory of the license server).
  3. Remove the license.txt file and try to restart the server. Since the file that stores the license key is missing, the server will fail to start.
  4. Find the license activation procedure in the on-screen instructions (if the license server is started in a command line interface) or in the outLicenseServer.log log file.
  5. After you copy the activated license key in the license.txt file, restart the license server.

Common Problems

This section includes some common problems that may appear when setting up a floating license server running as a standalone process.

Windows Service Reports "Incorrect Function" When Started

The "Incorrect Function" error message when starting the Windows service usually appears because the Windows service launcher cannot locate a Java virtual machine on your system.

Make sure that you have installed a 32-bit Java SE from Oracle (or Sun) on the system: http://www.oracle.com/technetwork/java/javase/downloads/index.html.

When Started, the Windows Service Reports "Error 1067: The Process Terminated Unexpectedly"

This error message appears if the Windows service launcher quits immediately after being started.

This problem usually happens because the license key has not been correctly deployed (license.txt file in the license folder). For more information, see the Setting up a Floating License Server section.

Setting up a Floating License Server Running as a Standalone Process Using a Platform-independent Distribution

This installation method can be used for running the license server on any platform where a Java virtual machine can run (OS X, Linux/Unix, Windows).

Steps for Installing the Floating License Server as a Standalone Process with a Zip Archive

  1. Ensure that a Java runtime version 6 or later is installed on the server machine.
  2. Download the license server installation kit for your platform from the Oxygen XML Editor website.
  3. Unzip the installation kit into a new folder.
  4. Start the server using the startup script from a command line console.
    The startup script is called licenseServer.sh for OS X and Unix/Linux or licenseServer.bat for Windows. The following parameters are accepted:
    • licenseDir - The path of the directory where the license files will be placed. The default value is license.
    • port - The TCP port number used to communicate with Oxygen XML Editor instances. The default value is 12346.

    The following is an example of the command line for starting the license server on Unix/Linux and OS X:

    sh licenseServer.sh myLicenseDir 54321
  5. Floating licenses require activation prior to use. Follow the on-screen instruction to complete the license activation process.

Upgrading Your Floating License Server

The goal of the following procedure is to help you minimize the downtime generated when you upgrade the Oxygen XML Editor floating license server to its newest version.

Follow this procedure:
  1. Stop the current license server process.
  2. Locate and open the floating server startup script. It should look like:
    sh licenseServer.sh pathToLicenseDir 54321
  3. Make a note of the path to the license directory (in our example is pathToLicenseDir) and the port number (in our example is 54321).
  4. Go to the license directory and copy the license key file (license.txt) for later use.
  5. Go to the Oxygen XML Editor website and download the all-platforms floating license server installation kit.
  6. Unzip the archive and overwrite the content of your current floating license server installation.
  7. Copy the license key file (license.txt) saved in step 4 to license directory of the floating license server installation.
  8. Edit the floating server startup script and configure with the info you made note of in step 3.
  9. Start the floating license server process.

Replacing a Floating License Key in a Floating License Server

The following procedure assumes that your Oxygen XML Editor floating license server contains a previously activated license key and provides instructions for replacing the activated license key with another one. The goal of the procedure is to minimize the license servlet downtime during the activation step of the new license key.

This is useful if, for instance, you want to upgrade your existing license to the latest version or if you receive a new license key that accommodates a different number of users.

To replace a floating license key that is activated on your floating license server with a new one, follow these steps:
  1. Stop the process that runs the floating license server.
  2. Locate the folder that holds the previous activated license key (by default, it is named license and it is located in the installation directory of the license server).
  3. Remove the license.txt file and try to restart the server. Since the file that stores the license key is missing, the server will fail to start.
  4. Find the license activation procedure in the on-screen instructions.
  5. After you copy the activated license key in the license.txt file, restart the license server.