OpenLM Broker installation on Windows

Introduction

OpenLM Broker facilitates communication between OpenLM Software License Management (further in the document SLM) or Software License Management Cloud (SLMC) and the license manager to provide enhanced license statistics and functionality. It interacts directly with the license manager, querying it regularly for license information and relaying this data to the OpenLM SLM. While OpenLM Broker is an optional component, it is highly recommended for enhancing the license management experience and capabilities of the OpenLM system.

OpenLM Broker installation

OpenLM Broker is Java-based and can run on any Java-supported platform. The Broker needs to be installed on the same machine as the license manager. As the Java environment is required, Java Runtime Environment (JRE) is bundled as part of the installation (available only for the Broker installation). Before starting the installation, it is advisable to check the system requirements. This document covers the installation of the OpenLM Broker on Windows in both standard wizard installation (see A. Install OpenLM Broker with the installation wizard) and through the silent installation (see B. OpenLM Broker silent installation). To install on Linux or Unix, see OpenLM Broker installation on Linux/Unix.

Both methods of installation require the OpenLM Broker installer. It can be located in the download area (https://www.openlm.com/downloads/). The downloads require an OpenLM Platform account: to register, sign in, and find the Broker on the V26 tab, see Download Version 26 installers. The installer file is named OpenLM_Broker_<version>.msi.

A. Install OpenLM Broker with the installation wizard

1. Open the installer file (OpenLM_Broker_#.#.#.#.msi) to initiate installation. A "Preparing to install" screen (see Figure 1) will appear briefly before the installation Welcome screen (see Figure 2).

Figure 1: Installation preparation screen.

Figure 2: Installation welcome screen.

2. Select [Next] to continue with the installation. The License Agreement screen will appear (see Figure 3).

Figure 3: License agreement screen.

3. If you agree to the terms and want to continue with the installation, select the "I Agree" radio button (see Figure 4). Selecting the radio button will enable the [Next] button. Selecting [Cancel] will exit the installer without any changes.

Figure 4: License agreement with "I Agree" checked.

4. Select [Next]. The Java selection screen will appear. Either accept the bundled OpenJDK distribution (Install Broker with Java 11 OpenJDK) or select Already have Java 11 installed? and point to a path where Java 11 is already installed (see Figure 5). On a machine without Java, the bundled OpenJDK option is selected by default.

Figure 5: The Java selection screen.

Select [Next]. The Select Installation Folder screen will appear with the default installation path, C:\Program Files\OpenLM\OpenLM Broker\ (see Figure 6).

Figure 6: Select the Installation Folder screen.

5. [Optional] Select [Browse] to select a different installation path. The default path is recommended.

6. Select [Next]. An installation confirmation screen will appear (see Figure 7).

Figure 7: Installation confirmation screen.

7. Select the [Next] button to continue with the installation. An installation progress screen will appear (see Figure 8). The installation will continue until completion. The Success screen (see Figure 9) will appear at the end of a successful installation. Before it appears, the installer opens the Broker UI in your default browser, at http://localhost:5090, on the Broker Initial Setup page.
   

Figure 8: Installation progress screen.

Figure 9: Notification of successful installation. Broker Initial Setup window

8. Select the [Close] button to exit the installer.

9. Go to the Broker and select where the Broker will report the data: into your Cloud Account or your on-premise installation:

The Broker Initial Setup page in the Broker UI.

On-premise installation:

1. Select the "Local OpenLM Installation" option then select [Continue]
2. Indicate the URL to the EasyAdmin. The Url field starts with http://localhost:5015, the address of an OpenLM SLM on the same machine:
   
3. Select [Continue]. The Broker will attempt to make the connection to the EasyAdmin

If you are connected to the OpenLM SLM through the Identity Service:

1. Go to EasyAdmin -> Start Menu -> Administration -> System & Security -> Authorization -> Add
   
2. From the dropdown list select [Broker]
3. Type in a suitable description:
   
4. Select [Save]
5. Make sure you read carefully the "Attention" about the Client Secret and Client ID message then select [OK].
   
6. In the next prompt, the Client Secret and Client ID will be displayed. These must be imported into the Broker. There are two options to perform this action: either by downloading the JSON file or using the Copy&Paste command. Select the convenient one then go back to the Broker:
   
7. Select [Import Broker Authorization File]. Indicate the path where the Authorization File has been downloaded.
8. After importing the Authorization File, the fields will be automatically populated. The same actions can be done with the Copy&Paste commands. Select [Continue].
   

After you select [Continue], the Broker tests the connection and scans the machine for license managers. Then approve the license servers that the Broker reported: in the OpenLM user interface, open the License Servers window, open each Pending entry, and select Approve.

The last Broker Initial Setup page

At this point, the OpenLM Broker installation is complete. Once you select OpenLM User Interface the EasyAdmin will open. Detailed explanation of the configuration is presented in the OpenLM Broker configuration document.

B. OpenLM Broker silent installation

System administrators who need to deploy multiple installations may find it easier and more efficient to perform a silent installation. This method allows users to install OpenLM Broker with predefined options and no on-screen 'wizard' assistance. The installation will also run Broker's autodetect functionality to automatically detect and configure certain license managers (for example, FlexLM).

1. Open a command prompt with administrative privileges (see Figure 10). The command prompt can be run in several ways:

• Type cmd in the taskbar search field and press [ENTER]. Open the context menu of "Command Prompt" in the results list and select "Run as administrator" from the popup menu.
• Launch EXE directly by right-clicking (for example, from C:\Windows\System32\cmd.exe) and selecting "Run as administrator" from the popup window.
• Open Windows PowerShell from the Start Menu. Open the context menu of Start then select Windows PowerShell (Admin). This will open Windows PowerShell in administration mode.

Figure 10: Command Prompt screen opened with Administrator role.

2. Launch msiexec with the required parameters for installation in the command prompt using the following format:

msiexec /i "<full Broker MSI file path>" /qn TRANSFORMS=":I01" MSINEWINSTANCE="1" <parameters>

The TRANSFORMS and MSINEWINSTANCE flags indicate the instance ID of the installation. Change the number if installing additional instances of Broker (for example, ":I02" and "2" if it's a second installation on the same machine and so on). MSINEWINSTANCE="1" also works for every additional instance, for example together with TRANSFORMS=":I03".

The following parameters are available:

• INSTALLLOCATION - specifies the installation folder. Use if you want to change from the default one. If the folder does not exist, it will be created. If this parameter is omitted, the default installation folder will be used (for example, C:\Program Files\OpenLM\OpenLM Broker)
• OPENLMLOCATION - specify the default OpenLM SLM connection that the Broker will connect to. Use the PORT@IP format (for example, 5015@10.0.0.201)
• BROKERXML - specify a Broker.xml file to be copied in the Broker folder and used as the default configuration file
• AUTH_FILE_PATH - specify the full path of a Broker authorization file to import during the installation, for example the file you downloaded in EasyAdmin (see step 9 of A. Install OpenLM Broker with the installation wizard). Use a full path, because a relative path is resolved against the installation folder. The installer records the result of the import in logs\auth_import.log in the installation folder: check it as described in step 5
• USE_OPENLM_JAVA - "true", the default, runs the Broker with the OpenJDK that the installer brings. Set it to "false" to use a Java that is already installed on the machine, and give its folder in JAVA_PATH
• JAVA_PATH - specify the folder of the Java to use when USE_OPENLM_JAVA is "false"

For example, the command for a silent installation with a log file would look like the following:

msiexec /i "C:\Users\admin\Desktop\OpenLM_Broker_22.3.30.1312.msi" /qn TRANSFORMS=":I01" MSINEWINSTANCE="1" USE_OPENLM_JAVA="true" /l*v "C:\Users\admin\Desktop\log.txt"

To import a Broker authorization file in the same step, add AUTH_FILE_PATH:

msiexec /i "C:\Users\admin\Desktop\OpenLM_Broker_<version>.msi" /qn TRANSFORMS=":I01" MSINEWINSTANCE="1" AUTH_FILE_PATH="C:\Users\admin\Desktop\broker-authorization.json" /l*v "C:\Users\admin\Desktop\log.txt"

3. After entering the installation command, press [Enter] to launch the installation. The command prompt will advance to a new line and installation will be completed in the background.

4. Close the command prompt.

5. Check the result. The installation succeeded when the log file contains MainEngineThread is returning 0 and the OpenLM Broker service runs in Windows Services. If you used AUTH_FILE_PATH, also open logs\auth_import.log in the installation folder. The import worked when the log ends with auth_import SUCCESS (exit=0).

   The installation reports success even when the import fails. If the log ends with auth_import FAILED, import the file again, then restart the service:

   "C:\Program Files\OpenLM\OpenLM Broker\auth_import.bat" "C:\Users\admin\Desktop\broker-authorization.json"
   net stop "OpenLM Broker"
   net start "OpenLM Broker"

As this is a silent installation, no additional user input is required. Older OpenLM Broker versions will be upgraded if an earlier version is registered on the machine with the same instance ID (TRANSFORMS). The installer doesn't look at the contents of the installation folder. If that instance already has the same version, msiexec stops with exit code 1639, and the log shows "MSINEWINSTANCE requires a new instance that is not installed."

Installation of two or more OpenLM Broker instances

It's possible to install two or more instances of OpenLM Broker. This deployment requires the following:

• Each new installation of OpenLM Broker should be configured to connect to a different OpenLM SLM.
• Each new installation of OpenLM Broker must be installed on the same license server machine as the production installation of OpenLM Broker.

The following series of steps assumes that one instance of Broker is already installed on the targeted license server. Use the following steps to install additional instances of OpenLM Broker.

1. Open the installer file to initiate installation. The wizard welcome screen will appear. Previous installation(s) will be detected, and the screen offers three buttons: Upgrade, Install, and Modify (see Figure 11). Upgrade is available only when an installed instance is older than the installer, and Modify only when an installed instance has the same version as the installer. Install is always available. The correct option for parallel installation is Install.

Figure 11: OpenLM Broker wizard setup screen.

2. Select [Install] to continue with the installation. The License Agreement screen will appear (see Figure 12).

Figure 12: License agreement screen.

3. Select the "I Agree" radio button (see Figure 13). Selecting the radio button will enable the [Next] button.

Figure 13: License agreement with "I Agree" checked.

4. Select [Next]. The Java selection screen appears again: keep the bundled OpenJDK, or choose a Java that is already installed, as in Figure 5, then select [Next]. Select Installation Folder screen will appear with the default installation path and automatically will add a digit to the Broker folder name, for example C:\Program Files\OpenLM\OpenLM Broker 2\ (see Figure 14).

Figure 14: Select Installation Folder screen with installation path.

5. [Optional] Select [Browse] button to select a different installation path. The default path is recommended.

6. Select [Next] button. Confirm Installation screen will appear (see Figure 15).

Figure 15: Confirm Installation screen.

7. Select [Next] to continue with the installation. An installation progress screen will appear (see Figure 16). The installation will continue until completion. Success screen (see Figure 17) will appear at the end of a successful installation.

Figure 16: Installation progress screen.

Figure 17: Installation success screen.

8. Select [Close] to exit the installer.

9. Repeat Step #1 to Step #8 to install additional instances of Broker.

The parallel installation is complete.

Each instance runs as its own Windows service, named after the instance: OpenLM Broker 2 for the second instance, OpenLM Broker 3 for the third, and so on. Each instance also serves its own Broker UI on the next free port, for example http://localhost:5091 for the second instance, and gets its own Start menu folder, OpenLM Broker 2, with numbered shortcuts. Connect each new instance to its OpenLM SLM in its own Broker UI, as in step 9 of A. Install OpenLM Broker with the installation wizard.

Uninstalling OpenLM Broker

Uninstalling the OpenLM Broker component can be initiated through the Windows Control panel (Option A), by launching OpenLM Broker Setup Wizard and selecting the option to modify OpenLM Broker (Option B), or by doing a silent uninstall through the Windows Shell.

Option A: Uninstall using Windows Control Panel

1. Open the Windows Control Panel.

2. Locate and select the "Uninstall a program" option under Programs (see Figure 18). Programs and Features screen will appear.

Figure 18: Windows Control Panel with the Uninstall a program link under Programs.

3. Locate and select OpenLM Broker in the list of names (select Name to sort the list alphabetically). Action options for the program will appear at the top of the list (see Figure 19). For OpenLM Broker, the options are Uninstall and Repair. Each instance has its own entry, for example OpenLM Broker 2.

Figure 19: Programs and Features screen with OpenLM Broker selected.

4. Select Uninstall. This will open a confirmation screen (see Figure 20).

Figure 20: Uninstall confirmation screen.

5. Select [Yes] to confirm uninstall. A progress screen will appear (see Figure 21). The progress screen will close when the process is complete.

Figure 21: OpenLM Broker uninstall progress screen.

6. Close the Programs and Features screen by selecting [x] in the upper right part of the window to close the Control Panel.

At this point the uninstall through the Control Panel Programs and Features function is complete. Uninstalling will leave configuration files for OpenLM Broker intact and they must be deleted manually. They are left so that OpenLM Broker can be reinstalled without losing previous configurations. They can be found by default in C:\Program Files\OpenLM\OpenLM Broker (#). The folder keeps broker.xml, broker.id, broker.xml.backup, application.properties, and the bufferfiles, logs, and markerfiles folders. The uninstall removes the Windows service, the Start menu folder, and the program files. When you reinstall into the same folder, the Broker starts with the kept broker.xml and broker.id. The installer can then open the Broker UI before the service is ready: if the browser shows that localhost refused to connect, refresh the page after a few seconds.

Option B: Uninstall using the OpenLM installer package

1. Locate the installer file and open it. OpenLM Broker Setup Wizard screen will appear (see Figure 22) with the Upgrade, Install, and Modify buttons. Modify is available only when the installer is the same version as an installed instance.

Figure 22: OpenLM Broker Setup Wizard screen.

2. Select Modify to select the option for removing the installation (see Figure 22).

3. The Select Instance screen will appear (see Figure 23). It lists each instance with its version.

Figure 23: Select Instance screen.

4. Select the instance by selecting it in the list (the first instance in the list is highlighted already).

5. Select the [Remove] button.

6. A progress screen will appear
   

Figure 24: Removed OpenLM Broker progress screen.

7. If any processes linked to OpenLM Broker are still running, an error screen will appear with information on the process(es) involved. These processes can be stopped using Windows Services (for example, run C:\WINDOWS\system32\services.msc or type "Services" in the Windows search on the taskbar and select Services App from the result), and removal can be continued by selecting [Try Again]. When removal is complete, the removal success screen will appear (see Figure 25).

Figure 25: Removal success screen.

8. Select [Close] button to exit the Setup Wizard.

At this point the removal process using the OpenLM Broker Installer wizard is complete. Uninstalling will leave configuration files for OpenLM Broker intact and these must be deleted manually. They are left so that OpenLM Broker can be reinstalled without losing previous configurations. They can be found by default in C:\Program Files\OpenLM\OpenLM Broker (#).

Option C: OpenLM Broker silent uninstallation

System administrators who would like to uninstall silently can do so with the following method.

1. Open a command prompt with administrative privileges (see Figure 26). The command prompt must be run as an administrator. Instructions for eliciting the command prompt can be found in section "B. OpenLM Broker Silent Installation" under the OpenLM Broker Installation heading.

Figure 26: Command Prompt screen opened in the Administrator role.

2. At the command prompt, enter the desired parameters for the uninstall. This will be in the format as follows:

msiexec /x "<msi installation file path>" /qn TRANSFORMS=":I##"

The MSI file path is the location of the MSI file downloaded for the installation. A simple uninstall might look like the following (includes the 'TRANSFORMS' parameter which refers to the number of the instance [:I##] to be uninstalled):

msiexec /x "C:\Users\admin\Desktop\OpenLM_Broker_22.3.30.1312.msi" /qn TRANSFORMS=":I01"

The MSI must be the same version as the instance you remove. Otherwise the installer doesn't find the instance, and it logs "Failed to detect Broker instance to uninstall."

3. After entering the uninstall command, press [Enter] to launch the uninstall. The command prompt will advance to a new line and the uninstall will complete in the background.

4. Close the command prompt by selecting the [x] in the upper right of the window.

As this is a silent uninstall, there is no additional user input. Uninstalling will leave the configuration files for OpenLM Broker intact and these must be deleted manually. They are left so that the OpenLM Broker can be reinstalled without losing previous configurations. They can be found by default in C:\Program Files\OpenLM\OpenLM Broker (#).