OpenLM Broker Installation Guide: Comprehensive – KB4004b
This document presents the OpenLM 4.5 Broker software module. It elaborates the module’s installation process for version 4.5, and conveys basic information regarding the OpenLM Broker functionality and configuration options. The OpenLM Broker is an optional though highly recommended component. It provides accurate license statistics, and facilitates communication between the OpenLM Server and the License Manager. The image below is a schematic block diaoptiongram, clarifying the said constellation:
The OpenLM Broker tool is an optional Java software module that should be installed on the License Manager Server.
The Broker interacts directly with the License Manager Server, initiating queries in order to get the current License Server status. It communicates the answers for these queries to the OpenLM Server. Being a Java component, the OpenLM Broker can run on any Java-supported platform.
OpenLM Broker benefits
The OpenLM Broker provides the following services to the OpenLM server:
- Locally querying license usage information from the license manager.
- Buffering transmission in order to overcome communication failure
- Log files’ information (e.g. license denials, accurate license usage logging, offline licenses etc)
- Maintenance of FlexLM Options files from the OpenLM EasyAdmin interface.
- License files’ information (e.g. license packaging, license pools, Named licenses, DUP_GROUP)
- Remote file fetching
- Uploading of license files to the license server machine
- Starting / Stopping / Rereading of the license server.
OpenLM Broker– Installation Guide
The OpenLM System components are available for download on the OpenLM site. After filling in User name and email, the User will be directed to the download section. Select the OpenLM Version 3.0 section
In order to install the OpenLM Broker module on Windows platforms:
1. Please go over the installation prerequisites for the OpenLM Broker on the OpenLM site.
2. Download the OpenLM Broker for windows from the OpenLM version 3.0 section (see above), and follow the installation instructions. OpenLM will install the Java Run-time Environment (JRE) as part of the Broker installation.
3. Open the OpenLM Broker configuration tool (Windows ‘Start’ → “All Programs” → OpenLM → Broker → “OpenLM Broker configuration tool ”). Note that the Broker automatically detects the settings of FlexLM license managers installed on the machine. The existence and location of FlexLM Options files is not automatically configured; Setting their names and paths remains to be done manually.
Unix / Linux
In order to install the OpenLM Broker module on Unix/Linux platforms:
1. Review the installation prerequisites for the OpenLM Broker. The installation requires root user privileges.
2. Download the Broker for Unix/Linux file (e.g. openlmbroker_18.104.22.168.tar.gz) from the OpenLM site, Downloads section.
3. CD to the directory where to the OpenLm Broker is to be installed (e.g. /usr/local), and copy the file there.
4. Type sudo tar xvf <filename> (e.g.: sudo tar xvf openlmbroker_22.214.171.124.tar.gz) . This will extract the installation file to the current directory, creating the openlm/broker folder.
5. CD to the recently created openlm folder. Give (read | write | execute) permissions to the broker folder and all its sub folders: sudo chmod -R 777 broker
6. CD to the broker folder, and run the configuration tool by typing: java -jar BrokerConfigurator.jar broker.xml. The configuration tool GUI application opens.
7. Run the “OpenLM Broker” by typing: java -jar OpenLMBroker.jar start broker.xml
OpenLM Broker silent installation
System administrators in organizations that employ multiple Broker entities may find it easier to deploy Broker installations or update silently, through their domain controller. OpenLM facilitates this capability, as elaborated on this document.
Installation of two OpenLM Broker versions side-by-side
During a period of evaluating new OpenLM versions, it may be beneficial to have both versions up and running;
- The OpenLM Server of the newer version will be installed on a separate machine than that of the older, production OpenLM Server.
- The OpenLM Broker of the newer version will need to be installed on the same license server machine, side by side with the older, production OpenLM Broker.
Please refer to this document for an elaborated explanation on the “side by side” installation process.
OpenLM Broker – Configuration Tool
The next stage will be to configure the OpenLM Broker to address the OpenLM Server, License Servers and access server files .
1a. Adding a new OpenLM Server on premise
The OpenLM Server is the hub of the OpenLM system. It integrates the info from OpenLM peripheral components (i.e. OpenLM Brokers and OpenLM Agents).
1. Select the “OpenLM Servers” directory icon.
2. Click the Add button.
3. Select OpenLM Server from the selection list.
4. Configure the OpenLM Server’s parameters:
4a. OpenLM Server: The server’s name or IP address .
4b. Port: The OpenLM port dedicated for the Broker (7016 by default). This is the same port number as appears in the “OpenLM Server Configuration” tool, under the “Port Settings” tab, in the “License Managers Reporting Port” text box.
4c. Sending Timeout: The Broker’s sending timeout limit (e.g.: 45 sec).
4d. Activate Buffering (Enabled by default): Check this box in order to enable the Broker’s offline mode which keeps the information coming from the broker when not connect to the OpenLM server. All messages buffered will be sent to the OpenLM server when the connection is recovered.
4e. Messages in Buffer: The number of messages saved in one buffer file. Note that it is the user’s responsibility to clear the file system.
4f. Check connectivity to OpenLM Server: This button performs a connectivity check.
4g. Apply: Saves the information entered.
4h. Detect: Click this button to automatically detect FlexLM license managers on the OpenLM Broker machine. This action will delete all configured license managers and look for new ones. The existing configuration will be backed up, and the new configuration will become active.
5. Click the Restart Broker button.
1b. Adding a new OpenLM SAAS Server:
OpenLM has developed a cloud based license management service: The OpenLM SAAS. We offer comprehensive installation and configuration assistance in bringing up such a service for our customers. In order to enjoy the benefits of the OpenLM SaaS, please contact support [at] openlm.com, and our team will be glad to assist.
2. Adding a License Server
Upon first startup in Windows’ installations, the Broker automatically detects FlexLM License Managers on the host machine. The Broker displays a list of these license managers under the License Servers folder on the left pane. Several ports can be configured for each license server.
In order to add a license server manually, follow these steps:
1. Select License Servers on the left side of the screen.
2. Click the Add button. A drop-down list appears.
3. Enter the Hostname \ IP of the new License Server. Make sure the hostname or IP as configured on the OpenLM Server Configuration tool and on the Broker configuration tool (e.g. my_license_server) are the same.
3. Adding a license manager port
3a. Highlight the newly named License Server and click Add.Click OK.
3b. Click on the Port under the new License Server key symbol. The License Manager Port form appears.
3c. Submit the License manager Port parameters:
Port Number: This Number is the same as the one configured in the OpenLM Server Configuration Window, under the License Servers tab.
License Manager Type: Type of License server.
4. Reading a license file (License Manager Port → ‘Advanced’)
OpenLM can obtain license information via license usage records or via the license file. Some of the information (e.g. license pool membership, license expiration date and license packaging) is obtained solely from the license file. OpenLM is capable of reading FlexLM License file information and apply it to its reports. For instance, Packaging information can be applied automatically.In order to do so, the OpenLM Server and OpenLM Broker must be configured to relate to the license file.
Please follow this procedure:
4a. Open the OpenLM Server configuration tool, and select the “License Servers” tab.
4b. Select the specific FlexLM License Server, and click the “Advanced settings” link. Check the “Read License file” box. See the image below for clarification.
4c. Open the OpenLM Broker configuration tool, and select relevant port number. Click the ‘Advanced’ blue hyperlink, to open the “License information” dialog.
4d. Check the “Watch License File” box. License file will be checked for changes periodically as defined in the “Watch Interval”. If a change is found, the Broker will propagate the new license file information to the OpenLM server.
4e. Set the “Watch interval” value: This is the Interval at which the License File is read. It is recommended to keep the 300 sec default value.
4f-1. License file path, Automatic method:
- On Windows’ installations, FlexLM license file paths are acquired automatically during startup. They are obtained by invoking the “lmutil lmstat” command, and extracting the license file path from the output.
- If a license file’s name or path is changed, OpenLM will apply the required modifications according to the respective changes in the “lmutil lmstat” output.
4f-2. License file path, Manual method:
- The license file path may be configured manually by checking the “Set Path Manually” box and filling in the license path in the textbox beneath it.
- Multiple license files may be configured with a semicolon separator, as such:
- The system will now only refer to the path as given in the License File Path text box, and will not apply any changes to the path automatically.
4g. Click the ‘Show’ button to present the relevant license file on a new textbox
Sorting the license file according to pools is done as part of OpenLM’s multiple-pool monitoring mechanism. Please refer to this article for more information.
- The “Allow to sort license file” box must be checked in order to enable attribution of used licenses to their respective license pools.
- The ‘Sort’ button will manually apply license file sorting by pools.
4i. Click the ‘Apply’ button on the bottom-right corner of the Broker Configuration window and then the “Restart broker Button” in order to apply new License Server configurations.
5. License servers – Commands
The Commands menu sets the path to License manager commands. These commands are License Manager specific, and the paths for these commands may be set for each License server or vendor (port) individually, or globally – in the Advanced Settings configuration (see below).
Upon installation, the default search path for FlexLM commands would be automatically detected through the system registry. Other license managers’ command paths are set by default to: C:\Program Files\OpenLM\OpenLM Broker\tools\
5a. Changing command paths
Click the Commands bullet under the New License Server’s Port icon.
There are 2 options for changing the command paths:
5a-1. In order to set all the License manager’s commands globally, per a specific license manager type (e.g. FlexLM), check the Update according to Advanced Settings radio button and click the Update button. When applied, the globally declared License manager’s command paths listed in the Advanced settings menu (Indicated by the wrench icon) on the selected port.
5a-2. In order to set all the License manager’s commands of a certain port, check the Update to the following path radio button, type the required path in the adjacent text box, and click the Update button.
Use Service (Checked by default): This configuration affects FlexLM Start / Stop commands. When selected, the netstart / netstop windows services commands are used. Otherwise, FlexLM specific ‘lmgrd’ and “lmutil down” are applied.
5b-1. Click the Status bullet under Commands.
5b-2. The Status command line appears in the Command Line text box. it is assembled and executed according to the selected license manager type. The Status command queries the License Server for its status; Up or idle.
5b-3. Execute: Click this button to execute the Status command line.
5b-4. Restore default: Revert changes made to the command line prior to clicking the Apply button.
5b-5. Interval: This is the time period between Status command executions. It is recommended to keep the default value presented in this form.
5c. Data Inquiry
5c-1. Click the Data Inquiry bullet under Commands.
5c-2. The Data Inquiry command line appears in the Command Line text box. This command is assembled and executed according to the selected license manager type. The Data Inquiry command periodically queries the License Manager for license usage information. The OpenLM Broker then forwards this information to the OpenLM Server.
5c-3. Execute: Click this button to execute the Data Inquiry command line.
5c-4. Restore default: Revert changes made to the command line prior to clicking the ‘Apply’ button.
5c-5. Interval: This is the time period between Status command executions.
5d. Start and Stop
5d-1. Click the Start or Stop bullets under Commands bullet. The respective command definition form appears on the right-hand side of the window.
5d-2. The Start and Stop command lines appears in the Command Line text box. These commands are assembled and executed according to the selected license manager type. The Start and Stop commands literally start and stop the the License Manager Server’s activity.
5d-3. In the case of FlexLM only, the Use Service (Change Command section listed above) configuration also affects FlexLM Start / Stop commands. When selected, the netstart / netstop windows services commands are used. Otherwise, FlexLM specific ‘lmgrd’ and “lmutil down” are applied.
5e-1. Click the Reread bullet under Commands.
5e-2. The Reread command line appears in the Command Line text box.The Reread command forces the license manager to re-read Option files or License files that have been edited, and relate to newly introduced information.
6. License server – Vendors
Click the Vendors bullet. The Vendor definition form is opened in the right pane. This form handles the vendor specific License and Option files. Click Add from the top of the screen and select Vendors.
1. Vendor Name (e.g.: ARCGIS, adskflex, ptc_d, MLM, ugslmd): The vendor’s name should be EXACTLY as provided by vendor. You can usually find the vendor name in the Broker’s ‘data inquiry’ command execution output (see above).
2. Option File Description: A descriptive name of the user’s choice (e.g.: my_OptionFile).
3. Option File Path: The option file related to the vendor, stated with its full path.
- Watch Option File: This box should be checked in order to sample the Option file for local changes. Please consult OpenLM Support before checking this box.
- Watch interval: The Interval at which the Option file is read. It is recommended to keep the 600 sec default value.
- Click Apply and Restart Broker
For more on Options files maintenance in OpenLM, please follow this document.
For more information on automatic maintenance of FlexLM Options files via the EasyAdmin web application, please refer to this article:
7. License Server-Log file:
The OpenLM Broker is capable of reading license server log files, as they are continuously written in real time, and transfer the data additive data to the OpenLM Server. Such data includes:
- Accurate 1-sec resolution usage reports,
- Denied License requests
- Offline (borrowed) license information.
Click the Log Files bullet . The Log Files Definition form is opened in the right pane. These log files are produced by the license manager, which are read by the OpenLM Broker, and forwarded to the OpenLM server for further analysis of license usage. Click Add from the top of the screen and select Log file.
From the drop-down menu, select the log file type. The currently supported types are:
7a-1 FlexLM Debug log:
provides accurate license check – out / check – in timing information
7a-2. ESRI (FlexLM) Audit log provides the identity of borrowed licenses’ users. ESRI license administrators have long noticed that license borrowers are not identified by license server querying, i.e. by running lmutil lmstat commands. Instead, the borrowed user is identified as “Activated License(s)”, which isn’t very helpful in understanding who is holding the required license. In order to display borrowed licenses’ users’ identity, the Broker should be configured to read the Audit log.
At the time of writing this article, “Other” log types included DSLS and Reprise RLM license logs, to provide license denials and report offline licenses.
7b. Name: Name of the new License Server’s log file.
7c. Path: Fill in the Path on which to locate the License Log file.
Click the ‘Advanced>>’ link to reveal more configurable parameters. It is recommended not to change the default values of these parameters:
7d. Set data size limit: Data chunk size that is read from the log file.
7e. Read file every: Configurable time period for reading the log file.
7f. Watch file by patterns: DSLS logs may be configured to change names periodically. In order to continue acquiring DSLS logs’ information, check the “Watch files by pattern” to intelligently seek for the subsequent log files.
For more information about monitoring and reporting license denials, please refer to this article:
For more information about monitoring and reporting the borrowing of ESRI licenses, please refer to this article:
8. Advanced Settings
Click the Advanced Settings wrench icon, to open the Advanced Settings form in the right pane. This form handles vendor specific executable files.
8a. Executable files: Input the path for each license manager’s executable file, e.g.: lmutil.exe for FlexLM. This is the executable file that will be used by default for each FlexLM port, unless explicitly changed in the port’s command lines (see section “5. License servers – Commands” above).
8b. OpenLM Broker Log levels: Set the log file’s notification level for the Broker service and Broker configuration tool; i.e.: Should it only present Error messages or more verbose (‘ALL’) information.
8c. Reset: This will delete all OpenLM Broker configurations. Please read the warning prior to applying ‘Reset’.
8d. Recording:This is a debugging capability, meant to record transactions and reproduce problematic scenarios in lab conditions. Configuration of the Record option is quite straightforward: Select the ports to be recorded, set the record duration and the location of recorded archive file, and hit the record button.
Troubleshooting: Setting the Broker’s Character set
At times we have witnessed cases in which the OpenLM Broker and Server were correctly apparently configured, and connectivity between these two modules was fine, but no usage information was presented in the EasyAdmin web application. The cause for this malfunction was a mismatch between the license server’s character set definitions, and those of the OpenLM Broker. Please follow the procedure below to verify the Character set
1. Close the broker configuration tool
2. Open a cmd prompt window and type : chcp. you will get an output : The output should be similar to Active code page: 850 . This is your machine’s Character set.
3. Locate the machine’s Character set in this table. The Character set encoding can be seen on the left column of the table, e.g. in this case IBM850
4. Open the broker.xml file in the Broker installation folder. This file is normally located under:
C:\Program Files (x86)\OpenLM\OpenLM Broker
5. Change the <charset> parameter of the corresponding port in the broker.xml file, e.g.: <charset>IBM850</charset>
6. Open the broker configuration tool again. Execute the “Data inquiry” command, and verify that the output format is correct.
OpenLM Broker on the EasyAdmin “License servers” window
The OpenLM Brokers’ status may be monitored from the EasyAdmin web application.
- Open the EasyAdmin web application.
- Click EasyAdmin Start → Widgets→ License servers. The “License Servers” window appears. Verify that the configured license managers appear on the list.
- A green circle node indicates an active connection to a license server.
- Click the + icon to expand the server indicator and view Broker related information:
NO BROKER: OpenLM server did not receive any information from broker. No broker was installed on the license server.
Up X days, Y hours, Z minutes: broker is up and running successfully. Time provided is how long the license manager is up, (since broker sampling)
BROKER DOWN: broker is installed but does not send information to the OpenLM server (license server indicator also becomes Yellow).
LM DOWN: License manager on this port is not working properly (license server indicator also becomes Yellow).
TIME DIFF ERROR: The time configured in the OpenLM server and the time received by the broker is not synchronized.
BROKER SYNC – while the openlm server is in offline mode the broker stores the information until reconnect to the OpenLM server. When the messages buffered are send to OpenLM server after the connection recovers the broker status will be BROKER SYNC.
NOT CONFIGURED/UNKNOWN – information interrupted. Broker is active but OpenLM does not get any information from the relevant port.
License server redundancy
When multiple license servers are configured in a redundancy constellation (e.g. ‘Triad’ in FlexLM terminology), the respective brokers will appear enclosed under the same descriptive server name, as in the example below; License server NX is comprised of physical servers srv01, 02 and 03, and communicating on ports 28000, 28100 , 28200 respectively.
The OpenLM Server interfaces each of the OpenLM Brokers installed on each of the physical servers, and obtains the required information from them.
The “License servers” window provides additional information via the installed Brokers, such as:
- Current time on the License server machine,
- Broker version , and
- The Java JRE version employed by the OpenLM Broker.
Importing files, and updating FlexLM license files
EasyAdmin users may choose to import any of the files utilized by the OpenLM Broker to the local machine. This may be useful when access to the license server is restricted, and is done by clicking the blue ‘Files’ hyperlink in the image above.
Furthermore, EasyAdmin users may choose to edit, update and upload FlexLM license file from their local workstation.
For more information about these capabilities, please refer to the following article:
Action buttons – Start, Stop and Restart
EasyAdmin users may invoke License server’s ‘Start’ ‘Stop’ and ‘Reread’ functions through the EasyAdmin “License servers” window. Simply click the respective buttons shown in the image above to send the respective command to the OpenLM Broker, which will apply the respective command as elaborated in the “License servers – Commands” section above.
OpenLM Broker – OpenLM Server communication
Here are a few facts regarding OpenLM Broker → Server communication
- The OpenLM Broker communicates over HTTP with one or more designated OpenLM Servers.
- The default port number set for this communication is 7016, although this may be changed. An appropriate outbound communication rule should be set in the OpenLM Broker machine’s Firewall security table. Please refer to this document for more information: OpenLM Port numbers
- The OpenLM Broker communication may be set to work in SSL (Secure Socket) mode. It is up to the user to obtain and activate the appropriate certificate keys. Switching to SSL is done on
- OpenLM Server configuration tool, port settings tab.
- OpenLM Broker configuration – per target license server.
- The OpenLM Broker packets are compressed in order to minimize network traffic
- The Broker improves the OpenLM system stability by means of a message buffering mechanism:
- When a packet transfer fails, the Broker will attempt to resend it two more times.
- If the transfer remains obstructed after the 3rd attempt, the Broker will resort to storing subsequent messages in buffer files on the Broker machine’s memory.
- The size of each buffer file is configurable on the Broker configuration tool.
- When communication is restored, the Broker will commence sending Broker packets according to their timely order, beginning with the 1st stored buffer file.
- During the buffering and restoration periods the OpenLM real-time usage presentation will not be up-to-date.