Problem:
I am a systems administrator responsible for licensing Server Express on Linux/UNIX systems, but I am having trouble understanding the licensing system. Where can I find an overview and a summary?
Solution:
Here is an overview of the Server Express LMF/Apptrack licensing system on Linux/UNIX. You should read this if you are responsible for administering Server Express on Linux/UNIX systems. This augments the official licensing documentation. Instructions for accessing the official documentation are included below.
DEVELOPMENT VERSUS RUNTIME LICENSES
For the LMF/Apptrack licensing system, there are two types of licenses: development licenses and runtime licenses [other types such as Enterprise Server licenses also exist, but consider just development licenses and runtime licenses for this discussion].
Development licenses control the use of the COBOL compiler. They are officially named "Server Express" licenses.
Runtime licenses control the execution of COBOL programs that have already been compiled. They are named "Server for COBOL" or "Micro Focus Server" or "Application Server for Server Express" licenses (all three names mean the same). Depending on which products you purchased, you may have one or more of these types of licenses.
PRODUCT NAMES
The product named "Server Express" is the main product. It includes both the compiler and the runtime system. The product named "Server for COBOL" includes only the runtime system. Think of "Server for COBOL" as a sub-set of "Server Express".
In early versions, the product "Server for COBOL" was named differently; it was named "Application Server for Server Express" or "Micro Focus Server".
Server for COBOL is meant to be installed on production machines where COBOL will run, but where COBOL should never be compiled. System administrators may want to prevent people from compiling COBOL on production machines. By installing Server for COBOL on a machine, a person can be assured the compiler is not present. This is the reason Micro Focus distributes the Server for COBOL product separately.
Because Server Express includes both the compiler and the runtime system, it can be used for development, production, or both. When Server Express is installed on a machine, it is not necessary to install Server for COBOL on the same machine. On a machine with Server Express installed, both types of license can be installed: development licenses and runtime licenses. In this way a single installation of Server Express can be licensed both for development and production.
DOCUMENTATION
It is important to read the licensing documentation. It is available at:
https://www.microfocus.com/documentation/server-express/sx51ws02/sx51ws02/sx51indx.htm
Development licensing and the License Management Facility (LMF) are documented in the section named "Development System Licensing Guide".
Runtime licensing and the "apptrack" utility are documented in the section named "Deployment License Management Guide". We recommend that you read these two sections of the documentation.
The $COBDIR/lmf directory
This document explains development licensing first; to read about runtime licensing first, look ahead to the section named APPTRACK.
In this discussion, $COBDIR means the location on disk where the product is installed. To use the COBOL compiler or to run COBOL programs, users need to have an environment variable named COBDIR pointing to where the product is installed. The default location is /opt/microfocus/cobol but the person who installed the product may have placed it somewhere besides the default.
Within a Server Express $COBDIR there is a subdirectory named "lmf". It contains files associated with development licensing. But $COBDIR/lmf is not the operative location of the License Management Facility (LMF). Instead, the shell script $COBDIR/lmf/lmfinstall copies files from $COBDIR/lmf into a separate location to create an operative LMF directory. $COBDIR/lmf contains files meant to be copied elsewhere.
When you install Server Express, the main install script invokes $COBDIR/lmf/lmfinstall, so if Server Express has been installed, an operative LMF directory already exists on your system. During installation, the user was given the choice of creating the operative LMF directory in any location. The default location that was offered was /opt/microfocus/mflmf.
DISCOVERING THE OPERATIVE LMF DIRECTORY
In order to view and manage development licenses, you need to know the operative LMF directory. One way of discovering this location is by invoking the command "lmfgetpv" from within $COBDIR/lmf. For example, enter:
$COBDIR/lmf/lmfgetpv
If the License Manager is running, lmfgetpv will produce output similar to:
License Manager version 129 Loaded from /opt/microfocus/mflmf
The "loaded from" location is the operative LMF location. In the above example, "/opt/microfocus/mflmf" was discovered to be the operative LMF location.
If the License Manager is not running, lmfgetpv will report:
License Manager is not running
In that case, a way of discovering the LMF location is by entering the following command:
grep COBDIR= /etc/mflmrcscript
The COBDIR returned from this 'grep' command is the operative LMF directory configured for automatic start at boot time. Note: in just this particular case, COBDIR does not mean the location where the product is installed, it means the operative LMF location.
When you discover the operative LMF location, change directories to that location and begin administering development licenses.
DEVELOPMENT LICENSE UTILITIES
In the operative LMF directory are files named "lmfgetpv", "mflmman", "mflmcmd", "mflmadm", and "lmfdbrecover". These are the commands for administering development licenses. They are fully documented in the "Development System Licensing Guide" as described above. Here are brief guidelines for each:
The "lmfgetpv" command without options shows whether the License Manager daemon process is running. Give it "?" as an option (that is, enter "./lmfgetpv ?"), and it will display its usage screen showing other possible options; for example the "k" option (for "kill") will stop the License Manager daemon.
The "mflmman" command will start the License Manager daemon process.
The "mflmcmd" command is a simple command-line utility (as opposed to a graphical utility) for installing development licenses. It is the recommended method of installing development licenses.
The "mflmadm" command is a full-screen character-mode graphical utility for installing, removing, and administering development licenses. It requires the terminal screen to be sized 80 columns by 25 rows, and the TERM environment variable to be set appropriately.
Please note that:
"mflmman" is a shell script that invokes "mflm_manager"
"mflmcmd" is a shell script that invokes "mflm_cmd"
"mflmadm" is a shell script that invokes "mflm_admin"
The shell scripts are the intended utilities. The underlying executables having "_" in their names are not intended to be invoked directly.
USING "mflmadm"
The "mflmadm" command can be invoked directly from within the operative LMF location, for example:
./mflmadm
Perhaps a more convenient way is to use the "mflicense" command. The "mflicense" command exists in $COBDIR/bin. If the COBDIR environment variable is set, you can execute "mflicense" by entering:
$COBDIR/bin/mflicense
and if $COBDIR/bin is already on your PATH, simply type "mflicense" from any directory. "mflicense" offers these choices:
Select the License system required
1. Development License System
2. Application Server License System
X. Exit
Option 1. "Development License System" invokes "mflmadm".
To be legible the screen must be sized 80 columns by 25 lines. You could resize the screen either by specifying a new size in the terminal emulator menu, or possibly by dragging a corner of the emulator window. For example using PuTTY as your terminal emulator, you can drag a corner of the window to resize it 80 x 25. It is also important that the TERM environment variable be set to the type of terminal being emulated.
Function keys within "mflmadm" may not work unless the terminal emulation is exactly correct, but you can use alternative keystrokes. Instead of F1, press /1 (that is, press and release the forward-slash key then press the 1 key). For F2, use /2, and for F3 use /3, etc.
Within mflmadm, the first screen does not show installed licenses. To show installed licenses, use F5=browse. Each license will be displayed on an individual screen. To move to the next license, use F3=next. The record number in the upper-right corner will change. If the record number does not change after pressing F3=next, it means you are positioned on the last license and there is no next license.
LICENSE KEYS
Licenses are distributed by E-mail, or on colored "license key cards" included in the product packaging. A license consists of two strings: a serial number and a license key, resembling this pattern:
Serial number: 600000123456AI
License key: 03050 2FAC0 055AC 62B0B 14C4 20080320
[the above is not actually a valid license, but resembles one]. You must know both strings: both the serial number and the key, in order to install or remove a license.
When mflmadm or apptrack display installed licenses, they show the last few characters of the key "dotted out", for example:
Serial number: 600000123456AI
License key: 03050 2FAC0 055AC 62B0B 14C4 200.....
This means you cannot discover the entire original key by looking in mflmadm or apptrack; you must refer to the license key cards or the E-mail by which the licenses were originally distributed. You may also ask your Micro Focus Sales representative to reveal the Key for a Serial number.
SERIAL NUMBER PLATFORM CODES
The serial number often ends with two alphabetic characters and a plus character, for example "AI+" or "TG+ ". This is a platform code. In some contexts, the serial number is shown without the platform code. However, the platform code including the "+" character must be entered when you enter a serial number into the licensing utilities, otherwise you will receive the error "this is not a valid license".
MULTIPLE VERSIONS
It is possible to have more than one version of Server Express installed and active on the same machine. But there can be only one active LMF. The LMF will control development licenses for all Server Express installations on the machine. The operative LMF directory should be placed outside and above any particular COBDIR.
DATABASE CORRUPTION
Development licenses are kept in a file named "mflmfdb". If you transfer the "mflmfdb" file (or other files in the operative LMF directory) to another machine or another disk so their inode numbers change, or if you perform a backup and restore that changes the inode numbers, the licensing system will assume you are making illegal copies of the license database. Licensing will stop working, and error messages will say the license database "has been moved or is corrupt".
The shell script "lmfdbrecover" can be used if the license database is corrupt. The script will delete the license database "mflmfdb", removing all existing development licenses. The script will then give you the choice of invoking either the command-line utility "mflmcmd" or the full-screen utility "mflmadm". At this time you must re-install your licenses, which means you must have your licenses (including serial numbers and keys) at hand.
Early Server Express versions do not include "lmfdbrecover". In that case, search the Micro Focus Knowledgebase using the phrase "Recovering a corrupt LMF database". Search also using the phrase "Recovering a corrupt aslmf database".
DEVELOPER USAGE RUNTIME LICENSES
When you install a development license, some runtime licenses are automatically installed into the runtime license system. In the runtime license utility "apptrack", these are indicated as being "Developer Usage", and they show the serial number of the development license. These are runtime licenses, but they were granted in conjunction with your having installed a development license in the LMF development license system. The rational is that developers need permission to run programs during development efforts, for debugging and application testing.
After you have installed new development licenses or recovered a corrupt license database, if the corresponding "Developer Usage" licenses do not automatically appear in "apptrack", run the utility named "devas" from the operative LMF directory; this will make certain the appropriate "Developer Usage" licenses appear in "apptrack".
APPTRACK
The shell script named "apptrack" found in $COBDIR/aslmf is the utility for managing Micro Focus runtime licenses. Using "apptrack", you can examine, install, and remove runtime licenses.
INVOKING APPTRACK
From the directory $COBDIR/aslmf, you can invoke apptrack directly by entering:
./apptrack
Perhaps a more convenient way is to use the "mflicense" command. The "mflicense" command exists in $COBDIR/bin. If the COBDIR environment variable is set, you can execute "mflicense" by entering:
$COBDIR/bin/mflicense
and if $COBDIR/bin is already in your path, simply type "mflicense" from any directory. "mflicense" offers these choices:
Select the License system required
1. Development License System
2. Application Server License System
X. Exit
To run apptrack, select option 2 "Application Server License System"
APPTRACK HAS NO DAEMON OR BACKGROUND PROCESS
Runtime licenses and the "apptrack" utility do not have a daemon or a "license manager" process that must be started. This is different than development licenses and the LMF, which do involve a License Manager daemon process. It is not necessary for a license manager process to be running, in order for runtime licensing to work.
CANNOT INSTALL DEVELOPMENT LICENSES INTO APPTRACK AND VICE VERSA
You cannot install a development license into apptrack, and also you cannot install a runtime license into mflmcmd or mflmadm.
If you are installing a license in apptrack and you get the error, "This is a development license!", it means you must install the license using mflmcmd instead.
If you are installing a license using mflmcmd and you see the error, "This is an Application Server license!", it means you must install the license using apptrack instead.
MULTIPLE VERSIONS
It is possible to have more than one version of Server Express (or Server for COBOL) installed on the same machine. When you install a runtime license, the license will become associated with a particular installation, based on the value of the COBDIR environment variable at the time you install the license. For example, if you have COBOL installations in these directories on disk:
/opt/lib/cobolv22
/opt/microfocus/se40
and if you intend to install a runtime license in association with /opt/microfocus/se40, first set COBDIR to /opt/microfocus/se40 and then run apptrack, for example:
COBDIR=/opt/microfocus/se40
export COBDIR
./apptrack
Then install the runtime license. After installation, apptrack will show the license as being associated with /opt/microfocus/se40.
APPTRACK PASSWORD
The first time you run "apptrack", it asks you to specify a password, or to enter six spaces. We recommend that you enter six spaces and avoid establishing a password because the password is often forgotten, and because there is no substantial security risk. If you have forgotten your apptrack password, search the Micro Focus Knowledgebase using the keywords "apptrack" and "password" to learn how to recover.
DATABASE CORRUPT
All runtime licenses are kept in a single file named "mfasdb" in /var/mfaslmf. This "mfasdb" file and other files in /var/mfaslmf cannot be accessed or modified directly; they must be accessed through the "apptrack" utility.
If you transfer the files in /var/mfaslmf to another machine or another disk so their inode numbers change, or if you perform a backup and restore to the same disk that changes the inode numbers of the files in /var/mfaslmf, the licensing system will assume you are making illegal copies of the license database. Runtime licensing will stop working, and "apptrack" will say the license database "has been moved or is corrupt".
The shell script $COBDIR/aslmf/aslmdbrecover can be used if the license database has been moved or is corrupt. The script will delete the license database in /var/mfaslmf, then the script will invoke "apptrack"; at this point you must re-install your licenses -- this means you must have your licenses (including serial numbers and keys) at hand.
Early Server Express versions do not include the "aslmdbrecover" utility. In that case, search the Micro Focus Knowledgebase for "Recovering a corrupt aslmf database".
DEVELOPER USAGE LICENSES
In the apptrack "License List" or "License Summary", some licenses might be described as "Developer Usage". These are runtime licenses, but they were granted in conjunction with your having installed a development license in the LMF development license system. They show the serial number of the development license. Whenever you install a development license, "Developer Usage" runtime licenses are automatically installed into apptrack. The rational is that developers need permission to run programs during development efforts, for debugging and application testing.
"Developer Usage" runtime licenses should be used only for development, not for system testing, production or deployment. If you are going to use an installation of COBOL for system testing, production, or deployment, then you are required to install an official runtime license into apptrack, associated with that COBOL location. You can recognize an official runtime license inside apptrack by the fact that it does not say "Developer Usage", and that it shows as being associated with a particular COBDIR directory.
TESTING THE LICENSING
After making changes to the licensing system, you can perform a simple test to prove that licensing is set up correctly and Server Express is capable of compiling and running COBOL. Follow the instructions in this Knowledgebase article:
#license
