DISCLAIMER

GREEN HILLS SOFTWARE MAKES NO REPRESENTATIONS OR WARRANTIES WITH RESPECT TO THE CONTENTS HEREOF AND SPECIFICALLY DISCLAIMS ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE. Further, Green Hills Software reserves the right to revise this publication and to make changes from time to time in the content hereof without obligation of Green Hills Software to notify any person of such revision or changes.

Copyright (c) 1983-2012 by Green Hills Software. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without prior written permission from Green Hills Software.

Green Hills, the Green Hills logo, CodeBalance, GMART, GSTART, INTEGRITY, MULTI, and Slingshot are registered trademarks of Green Hills Software. AdaMULTI, Built with INTEGRITY, EventAnalyzer, G-Cover, GHnet, GHnetLite, Green Hills Probe, Integrate, ISIM, u-velOSity, PathAnalyzer, Quick Start, ResourceAnalyzer, Safety Critical Products, SuperTrace Probe, TimeMachine, TotalDeveloper, DoubleCheck, and velOSity are trademarks of Green Hills Software.

All other company, product, or service names mentioned in this book may be trademarks or service marks of their respective owners.

PubID: license-463286

Branch: http://toolsvc/branches/release-branch-60

Date: April 24, 2012


Preface

This preface discusses the purpose of the manual, the MULTI documentation set, and typographical conventions used.


About This Book

The MULTI: Licensing book contains information about installing and administering Green Hills licenses for the MULTI IDE and Green Hills Compiler. The license keys used to access INTEGRITY and velOSity are discussed in the INTEGRITY Installation Guide.

This book is divided into the following parts:

  • "Information for End Users" provides licensing instructions for end users of MULTI.

  • "Information for System Administrators" provides more extensive information for system administrators who need to set up a License Manager, administer licenses, and configure license administration settings.

  • "Appendices" contains reference and troubleshooting material.

[Note] Note

New or updated information may have become available while this book was in production. For additional material that was not available at press time, or for revisions that may have become necessary since this book was printed, please check your installation directory for release notes, README files, and other supplementary documentation.


The MULTI 6 Document Set

The primary documentation for using MULTI is provided in the following books:

  • MULTI: Getting Started -- Provides an introduction to the MULTI Integrated Development Environment and leads you through a simple tutorial.

  • MULTI: Licensing -- Describes how to obtain, install, and administer MULTI licenses.

  • MULTI: Managing Projects and Configuring the IDE -- Describes how to create and manage projects and how to configure the MULTI IDE.

  • MULTI: Building Applications -- Describes how to use the compiler driver and the tools that compile, assemble, and link your code. Also describes the Green Hills implementation of supported high-level languages.

  • MULTI: Configuring Connections -- Describes how to configure connections to your target.

  • MULTI: Debugging -- Describes how to set up your target debugging interface for use with MULTI and how to use the MULTI Debugger and associated tools.

  • MULTI: Debugging Command Reference -- Explains how to use Debugger commands and provides a comprehensive reference of Debugger commands.

  • MULTI: Scripting -- Describes how to create MULTI scripts. Also contains information about the MULTI-Python integration.

For a comprehensive list of the books provided with your MULTI installation, see the Help->Manuals menu accessible from most MULTI windows.

Most books are available in the following formats:

  • A printed book (select books are not available in print).

  • Online help, accessible from most MULTI windows via the Help->Manuals menu.

  • An electronic PDF, available in the manuals subdirectory of your IDE or Compiler installation.


Conventions Used in the MULTI Document Set

All Green Hills documentation assumes that you have a working knowledge of your host operating system and its conventions, including its command line and graphical user interface (GUI) modes.

Green Hills documentation uses a variety of notational conventions to present information and describe procedures. These conventions are described below.

Convention | Indication | Example

bold type

Filename or pathname C:\MyProjects
Command | setup command
Option | -G option
Window title | The Breakpoints window
Menu name or menu choice | The File menu
Field name | Working Directory:
Button name | The Browse button

italic type

Replaceable text -o filename
A new term | A task may be called a process or a thread
A book title | MULTI: Debugging

monospace type

Text you should enter as presented Type help command_name
A word or words used in a command or example | The wait [-global] command blocks command processing, where -global blocks command processing for all MULTI processes.
Source code | int a = 3;
Input/output

> print Test
Test
A function | GHS_System()

ellipsis (...)

(in command line instructions)

 The preceding argument or option can be repeated zero or more times. debugbutton [name]...
greater than sign ( > ) Represents a prompt. Your actual prompt may be a different symbol or string. The > prompt helps to distinguish input from output in examples of screen displays.

> print Test
Test

pipe ( | )

(in command line instructions)

 One (and only one) of the parameters or options separated by the pipe or pipes should be specified. call proc | expr

square brackets ( [ ] )

(in command line instructions)

 Optional argument, command, option, and so on. You can either include or omit the enclosed elements. The square brackets should not appear in your actual command. .macro name [list]

The following command description demonstrates the use of some of these typographical conventions.

gxyz [-option]... filename

The formatting of this command indicates that:

  • The command gxyz should be entered as shown.

  • The option -option should either be replaced with one or more appropriate options or be omitted.

  • The word filename should be replaced with the actual filename of an appropriate file.

The square brackets and the ellipsis should not appear in the actual command you enter.


Licensing Models

To maximize flexibility, the MULTI products support four different licensing models:

  • Computer- and dongle-locked licenses -- These licenses are only supported on Windows and are not available over a network. They allow an unlimited number of instances of the licensed MULTI component to run on the licensed PC. For example, a single compiler license allows you to run an unlimited number of compilers.

    You can only move a computer-locked license to a new machine after contacting Green Hills Software, but a dongle-locked license becomes available on any PC to which the dongle (a hardware security device) is attached, and on which the license is installed.

    Computer- and dongle-locked licenses are only available to one user at a time. If more than one user is connected at once, the license is only available from the console.

  • Floating and named-user licenses -- These licenses are available over a network and are managed by a License Manager.

    Floating licenses are distributed on a first-come, first-served basis. Any end user may obtain as many floating licenses as are available in the license pool. For example, if a user obtains a floating license on one machine and wants to move to another, they can leave the licensed product running on the first machine and obtain another floating license--assuming one is available--for the same product on the second machine.

    Named-user licenses are accessible only to a defined set of end users, and each user may access only one license at a time.

    The License Manager reserves floating and named-user licenses for up to five minutes in case the client that last used the license needs it again within that time frame. Consequently, if a user obtains a named-user license on one machine, but wants to move to another, they must exit the licensed product on the first machine and then wait for the license reservation to expire (up to five minutes) before they are able to obtain a named-user license for the same product on the second machine.

    Regardless of whether you are using the floating or named-user license model, a single end user working at a single machine consumes only one license, even if they are running multiple instances of the licensed component. For example, a single compiler license allows the user to run an unlimited number of compilers. However, if a user is running the component on multiple displays of a single Linux/Solaris machine, a new license is required for each display.

    Floating and named-user licenses are locked to a particular license host. To rehost licenses from one license host to another, you must contact Green Hills Software.


More About Named-User Licenses

The main difference between floating and named-user licenses is that a named-user license can only be used by a single, unique user, whereas a floating license can “float” among users. Traditionally, customers tend to think of MULTI products as being offered in “seats”, where the number of seats for a product matches the number of end users of the product. Named-user licenses implement this concept: if a group has ten users of a product, then that group must have ten “seats,” or ten named-user licenses for that product.

A named-user license provides a unique user with the right to use a product, but the choice of which user this license is assigned to is the decision of the user's organization (system administrator, manager, etc.). The list of valid users for a particular product is managed through the lic_userlist command line utility (see "Managing User Lists with lic_userlist").


Information for End Users


Licensing for End Users

Before you can use the MULTI IDE and Green Hills Compiler, appropriate software licenses must be installed or accessible. When you first start the IDE, it checks for a valid MULTI license. If it cannot obtain a license, the MULTI Licensing Wizard automatically opens. You can use this wizard to request and install computer- or dongle-locked licenses (Windows only), or to obtain floating or named-user licenses, as documented in the following sections.

[Note] Note

This chapter assumes that you have installed MULTI 6 on your machine. If you have not, see the installation document located in the root directory of the installation CD for information.


Requesting Computer- or Dongle-Locked Licenses

Computer- and dongle-locked licenses are supported on Windows machines only. To request computer- or dongle-locked licenses, follow these steps:

  1. For dongle-locked licenses -- Insert the dongle into a USB port on your machine.

  2. If the MULTI Licensing Wizard is not already open, select Utilities->License Administrator from the MULTI Launcher.

  3. In the MULTI Licensing Wizard, select License my MULTI products (recommended for end users), and click Next.

  4. Choose the on-screen options for requesting licenses.

Customers submitting license requests via email or fax should use the appropriate email address or fax number, as listed below.

  • MULTI customers in the Americas, Australia, and New Zealand should send completed license requests to:

    • Email: license@ghs.com

    • Fax: (805) 965-6343 (Attn: Licensing)

  • MULTI customers from other parts of the world should send the completed license request to:

    • Email: license@ghs.nl

    • Fax: +31 (0)33 4613640

  • Ada/Safety-critical customers should send the completed license request to:

    • Email: adalicense@ghs.com

    • Fax: (727) 781-3915

License requests are processed as quickly as possible within business hours.

If you have questions, please call Green Hills' toll free licensing line (877-962-2950 in the U.S.), or call Green Hills Technical Support (+1 805-965-0124 worldwide).


Installing Computer- or Dongle-Locked Licenses

Computer- and dongle-locked licenses are supported on Windows machines only. To use the MULTI Licensing Wizard to install computer- or dongle-locked licenses, follow these steps:

  1. If the MULTI Licensing Wizard is not already open, select Utilities->License Administrator from the MULTI Launcher.

  2. In the MULTI Licensing Wizard, select License my MULTI products (recommended for end users), and click Next.

  3. Select Install a computer- or dongle-locked license file, and click Next.

  4. In the file chooser that appears, select the .ghslic license file that you received from Green Hills Software, and click Install.

To manually install computer- or dongle-locked licenses, follow these steps:

  1. Copy the Green-Hills-supplied .ghslic license file to the license file directory. The default license file directory on Windows is C:\GHS\licenses. To use a different directory, set the LICENSE_FILE_DIR configuration variable accordingly. For more information, see "Configuration Variables for Machines with Local Licenses".

  2. For dongle-locked licenses -- Install the appropriate drivers for your dongle. The installers for the SafeNet Sentinel dongle driver are included in the safenet directory of your MULTI IDE installation.


Obtaining Floating or Named-User Licenses

To configure your machine to contact one or more License Managers from which you may obtain floating or named-user licenses, follow these steps:

  1. Make sure that your system administrator has set up a License Manager on the network. For more information, see "Configuring a License Manager and Installing Licenses".

  2. If the MULTI Licensing Wizard is not already open, select Utilities->License Administrator from the MULTI Launcher.

  3. In the MULTI Licensing Wizard, select License my MULTI products (recommended for end users), and click Next.

  4. On Windows, select Specify the network location of License Managers, and click Next.

  5. Specify one or more license hosts running a License Manager on the network by doing one of the following:

    • Click Search to browse a list of License Managers found on the local network. Select one more more entries in the list, and click OK. (Note that search results depend on your network configuration. If you do not find a License Manager appropriate for your use, contact your system administrator for the name or IP address of a License Manager that you can access.)

    • Manually enter the name or IP address of one or more license hosts. If specifying multiple license hosts, separate each with a comma.

    When specifying multiple license hosts, you may choose whether the license hosts are contacted in order (precede the list with @) or at random (precede the list with #).

    [Note] Note

    This step sets the GHS_LMHOST configuration variable in your license configuration file. For more information, see "Setting Configuration Variables".


Information for System Administrators


Managing Floating and Named-User Licenses

This chapter describes the installation and administration of license management tools on the license host and of floating and named-user licenses.

[Note] Note

Elan licensing, aka legacy licensing, is no longer supported.


Configuring a License Manager and Installing Licenses

The following steps outline how to set up a License Manager on a license host and install floating or named-user licenses:

  1. Install the licensing utilities on the machine that is to be used as the license host. The license host may be a Windows, Linux, or Solaris machine. See "Installing Licensing Utilities on the License Host".

  2. Request licenses via the MULTI Licensing Wizard. See "Requesting Floating or Named-User Licenses".

  3. Save the Green-Hills-supplied .ghslic license file to a local directory that the License Manager has read and write permissions to. The license file may have any name.

  4. For named-user licenses -- Optionally assign user lists via the lic_userlist utility. See "Managing User Lists with lic_userlist".

  5. Use the MULTI Licensing Wizard to specify the location of the license file and to configure and then start the License Manager. See "Configuring and Starting the License Manager from the GUI".

In order for client machines to obtain floating or named-user licenses, end users must complete the steps listed in "Obtaining Floating or Named-User Licenses".


Replacing or Adding Licenses

If you have already set up a License Manager and would like to install a new floating or named-user license file, follow these steps:

  1. Stop the License Manager if it is running. See "Stopping the License Manager".

  2. Save the Green-Hills-supplied .ghslic license file to a local directory that the License Manager has read and write permissions to. The license file may have any name.

  3. For named-user licenses -- Optionally assign user lists via the lic_userlist utility:

    • If the new license file replaces your old license file -- Use the -f option to replace the old user list.

    • If the new license file supplements the old license file -- Create a new user list for the new license file.

    See "Managing User Lists with lic_userlist".

  4. Specify the location of the license file and restart the License Manager:

    • If the new license file replaces your old license file -- Use the MULTI Licensing Wizard to specify the location of the new license file and to restart the License Manager. See "Configuring and Starting the License Manager from the GUI".

    • If the new license file supplements the old license file -- Run lic_lm with the -license option. See "Configuring and Starting the License Manager from the Command Line".


Installing Licensing Utilities on the License Host

The following should be taken into consideration when selecting a machine to serve as a license host:

  • The license host must be an easily accessible network machine that is up and running when users need licenses.

  • Avoid using DHCP or dial-up networking on the license host. Doing so may cause the license host to change its default IP address. The License Manager will detect this address change and may stop granting license requests for security reasons.

Before installing licensing utilities on Windows, ensure that the following prerequisites have been met:

  • The installing user has administrator privileges.

  • The Services applet in the Windows Control Panel is not active.

  • All running programs have been exited (recommended, not required).

For information about prerequisites that must be met before starting the License Manager, see "Before Starting the License Manager".

Install the licensing utilities from a MULTI 6 installation CD. Instructions are provided in the installation document located in the root directory of the installation CD.

[Note] Note

The MULTI 6 License Manager will continue to serve licenses to MULTI 4 and MULTI 5 clients, but earlier versions of the License Manager will not serve licenses to MULTI 6 clients.


Requesting Floating or Named-User Licenses

To request floating or named-user licenses, follow these steps:

  1. On the license host, run mlmadmin.exe (mlmadmin on Linux/Solaris) from the licensing utilities installation directory.

  2. In the MULTI Licensing Wizard that appears, select Set up a network License Manager (recommended for administrators), and click Next.

  3. Choose the on-screen options for requesting licenses.

Customers submitting license requests via email or fax should use the appropriate email address or fax number, as listed below.

  • MULTI customers in the Americas, Australia, and New Zealand should send completed license requests to:

    • Email: license@ghs.com

    • Fax: (805) 965-6343 (Attn: Licensing)

  • MULTI customers from other parts of the world should send the completed license request to:

    • Email: license@ghs.nl

    • Fax: +31 (0)33 4613640

  • Ada/Safety-critical customers should send the completed license request to:

    • Email: adalicense@ghs.com

    • Fax: (727) 781-3915

License requests are processed as quickly as possible within business hours.

If you have questions, please call Green Hills' toll free licensing line (877-962-2950 in the U.S.), or call Green Hills Technical Support (+1 805-965-0124 worldwide).


Managing User Lists with lic_userlist

[Note] Note

This section only applies to named-user licenses.

A user list defines a set of end users who may obtain a named-user license for a particular product. You can manage user lists by running the lic_userlist utility on the license host.

When named-user licenses are first installed (see step 3 in "Configuring a License Manager and Installing Licenses"), no user lists are assigned. You can assign user lists by running lic_userlist with arguments. See the fourth format of the lic_userlist command below. The resulting user lists are stored in a file named license_file.gul, which is located in the same directory as the license file.

If you do not assign a user list for a particular licensed product, or if the number of licenses available for that product exceeds the number of end users named in the product's user list, the user list auto-populates. That is, users who obtain a product license are automatically added to the user list for that product if they are not already on the list.

Once a user is added to a user list, whether by auto-population or by manual setting, the only way to remove them is to use the lic_userlist utility. See Example 2.1. Modifying Existing User Lists. Modifying a user list via means other than lic_userlist renders your licenses unusable.

Three runs of lic_userlist are allowed to the user lists during a 24-hour period. A maximum number of changes is imposed for security purposes. If a fourth change to the user lists is attempted, a message indicates that the maximum number of daily changes has been exceeded, and the user list changes are not saved. (If this policy hampers your development efforts, please contact Green Hills Technical Support.)

[Note] Note

If the License Manager is running, stop it before running lic_userlist (see "Stopping the License Manager"). Restart the License Manager to cause your user list changes to take effect (see "Restarting the License Manager").

The lic_userlist executable is available from the MULTI IDE and licensing utilities installation directories. You can run it from the command line in any of the following ways:

  • lic_userlist [-h]

  • lic_userlist [-q] -license license_file -f user_list_file

  • lic_userlist [-q] -license license_file -r reset_code

  • lic_userlist [-q] -license license_file product user_list_options

Options are described in the following table:

-h

Displays help information.

-q

Enables quiet mode, in which no questions are asked.

-license license_file

Specifies the license file (.ghslic) containing named-user licenses for which you want to assign user lists.

-f user_list_file

Replaces the license file's current user list (stored in license_file.gul) with the user list from user_list_file. For more information, see Example 2.2. Replacing a User List File.

-r reset_code

Applies reset_code, which allows you to change the license file's user lists more than 3 times in a 24-hour period. This may be useful if the user lists are damaged.

If you need a reset code, contact Green Hills Technical Support.

product user_list_options

Modifies the user list for the licensed product product. Licensed products are listed in the license file.

Valid user_list_options are:

  • -a user... -- Adds user to the list of licensed end users for product.

  • -d user... -- Deletes user from the list of licensed end users for product.

You may specify multiple -a and -d options to effect multiple changes at once. See the following example.

Running lic_userlist with no options creates an empty user list file (.gul).

Example 2.1. Modifying Existing User Lists

Given the following .ghslic file named mylicenses.ghslic, see the example commands below.

[...]

version: 20

serial: 2345
port: 2009
ethernet: 1.1.1.1

lm key: 45ac040
lm code: 10000
lm hostid: 102bce95

multi key: 46d0866b
multi code: 100
multi licenses: 5

simppc key: 350acd10
simppc code: 470
simppc licenses: 5

isimppc key: 330b0f39
isimppc code: 610
isimppc licenses: 5

ecomppc key: 58df0eba
ecomppc code: 2901
ecomppc licenses: 5

enable_MULTI_v6 key: 2533f55f
enable_MULTI_v6 code: 11101
enable_MULTI_v6 licenses: 5

Examples:

To remove the users “sam” and “bob” from the ecomppc user list and to add “jon” to the ecomppc and multi user lists:

   lic_userlist -license mylicenses.ghslic ecomppc -d sam -d bob -a jon multi -a jon

To add the user “susanna” to the ecomppc and multi user lists:

   lic_userlist -license mylicenses.ghslic ecomppc -a susanna multi -a susanna

[Note] Note

The above commands are only examples. Your installation may require you to specify product licenses other than the ones shown here.

Example 2.2. Replacing a User List File

The -f option to lic_userlist replaces the license file's current user list (if any) with the user list from the file you specify. This allows you to effect multiple user list changes with only one run of lic_userlist (three runs are permitted during a 24-hour period).

To create a new user list file:

  1. Copy:

    • The MULTI 6 file license_file.gul, located in the same directory as the license file, or

    • The MULTI 5 file userlist.txt. By default, userlist.txt is located in C:\GHS\licenses (Windows) or in green_hills_install_dir/licenses (Linux/Solaris).

  2. Open the copy in a text editor, and assign a user list for each product. In the following sample file, each of the first three lines specifies a user list for the product indicated. 100, 310, and 2901 are product codes. Available product codes are listed in your license file.

    100 seth<END>
310 kevin,joe<END>
2901 kevin,joe,dan<END>
<UPDATED 1316465457 0 0>
<DIGEST a54296e91660acd30c5ea3b395f0786c>
WARNING: DO NOT TOUCH OR EDIT THIS FILE. It will break your licenses.
If you want to edit the user lists, please use lic_userlist.


Controlling Access to Licenses

License access files allow you to control who can obtain floating and named-user licenses. There are two types of license access files: those containing whitelists and those containing blacklists. A whitelist specifies who may obtain licenses from a particular license file. A blacklist specifies who may not obtain licenses from a particular license file. For example, if you want to reserve the licenses in a license file for the exclusive use of one particular user group, you can create a whitelist containing the names of the users in that group. Only requests from the specified users will be granted. If, on the other hand, you want to allow all end users except a few to obtain licenses from a license file, you can create a blacklist containing the names of the users you want to bar from obtaining licenses. In this case, requests will only be granted if they do not come from the specified users.

In each whitelist and blacklist, you may specify user names and IP addresses. When a whitelist is used, only requests from the specified users on hosts with the specified IP addresses are granted. When a blacklist is used, any requests from the specified users or from hosts with the specified IP addresses are denied. If no user names are specified, all users are qualified to obtain licenses. If no IP addresses are specified, requests from all hosts are qualified to obtain licenses.

You may optionally define one license access file per license file. The license access file should be located in the same directory as the license file, and it should have the same base name. The extension must be .ghslac.

The License Manager must have read permissions to the license access file, which it checks for approximately once every 15 seconds. If a new license access file has been created or if an existing file has been changed, the License Manager loads it.

[Note] Note

If you are using named-user licenses, the user lists created via lic_userlist also specify who may obtain licenses. These lists are not automatically updated when you create or modify a license access file; you must update them manually by running lic_userlist with the appropriate options (see "Managing User Lists with lic_userlist"). If a license access file conflicts with an existing user list, you will see a warning similar to the following:

User "jerry" is blacklisted from accessing product "ecomppc".
Use "lic_userlist" to remove the user from the user list.


License Access File Format

Format your license access file as follows:

version = 1;

whitelist|blacklist {
    user = {"user_name", "user_name", ...}
    user += {"user_name", "user_name", ...}

    ip = {"IPv4_address", "IPv4_address", ...}
    ip += {"IPv4_address", "IPv4_address", ...}
}

where:

  • version is the version number of the license access file. At present, the version is 1.

  • whitelist or blacklist may be specified, but not both.

  • user and ip are lists. Note that you must enclose list values in curly braces {}.

  • The operator = overwrites existing list values (if any) with new list values, while += appends new list values to existing list values.

  • IPv4_address may indicate a range of IP addresses. For example:

    192.168.22-38.0-255

    matches all IP addresses whose first fields are 192 and 168, whose third field is between 22 and 38 (inclusive), and whose last field is any number (0-255 matches any value).

Example 2.3. Whitelist

version = 1;

whitelist {
    user = {"joe"}
    user += {"kahlil"}
    user += {"jasmine", "toby"}

    ip = {"192.168.102.195"}
    ip += {"192.168.11.195", "192.168.22-38.0-255"}
}

This whitelist only allows the users joe, kahlil, jasmine, and toby to obtain licenses from hosts whose IP address meets one of the following criteria:

  • The IP address is 192.168.102.195.

  • The IP address is 192.168.11.195.

  • The first two fields of the IP address are 192 and 168, the third field is between 22 and 38 (inclusive), and the fourth field is any number.

Example 2.4. Blacklist

version = 1;

blacklist {
    user = {"joe"}
    user += {"kahlil"}
    user += {"jasmine", "toby"}

    ip = {"192.168.102.195"}
    ip += {"192.168.11.195", "192.168.22-38.0-255"}
}

This blacklist blocks any license requests from the users joe, kahlil, jasmine, and toby, or from any host whose IP address meets one of the following criteria:

  • The IP address is 192.168.102.195.

  • The IP address is 192.168.11.195.

  • The first two fields of the IP address are 192 and 168, the third field is between 22 and 38 (inclusive), and the fourth field is any number.


Ignored License Access Files

A license access file will be ignored in any of the following cases:

  • It contains both a whitelist and a blacklist.

  • It contains a syntax error.

  • You started the License Manager with the -filter option or the equivalent IP Addr Filter option.

  • The corresponding license file is dedicated to serving requests from the local host.


Configuring and Starting the License Manager


Before Starting the License Manager

Before starting the License Manager, consider the following caveats:

  • You must configure and start the License Manager from the license host.

  • UDP port 2009--used by the MULTI License Administrator to locate the License Manager on the network--must not be blocked by firewall and must be otherwise available for listening.

  • The TCP port(s) specified by your license file(s) must be available. TCP ports are used to accept license requests from client machines. The default TCP port is 2009.

  • Windows -- Users with limited permissions are not able to modify the state of Windows services. To start the License Manager, you must be logged in with administrator privileges. Additionally, if you want to start the License Manager from the command line and you are using Windows 7 or Windows Vista with User Account Control (UAC) enabled (the default), the command prompt must be started using the Run as administrator option:

    1. From the Start menu, select All Programs->Accessories.

    2. Right-click Command Prompt and select Run as administrator.

  • Linux/Solaris -- Many Linux/Solaris systems set a hard limit on the number of open sockets per process (1024 by default). If you expect many client applications to try to connect with the License Manager simultaneously, you may need to increase this limit before starting the License Manager. For example, on bash, the command ulimit -n 5555 sets the limit to 5555.


Configuring and Starting the License Manager from the GUI

The License Manager Settings dialog box allows you to configure and start the License Manager. To open the dialog box, perform the following steps:

  1. Run mlmadmin.exe (mlmadmin on Linux/Solaris) from the licensing utilities installation directory.

  2. In the MULTI Licensing Wizard that appears, select Set up a network License Manager (recommended for administrators), and click Next.

  3. Select Configure the License Manager on this machine, and click Next.

To configure the License Manager, fill in the fields of the dialog box. The following table gives a description of each field. Command line equivalents are documented in "Configuring and Starting the License Manager from the Command Line".

After filling in the fields of the dialog box, you can click Start License Manager if the License Manager is not running. On Windows, a Windows service with the display name Green Hills License Manager and the service name ghs_lm is created for the License Manager if a service does not already exist. If the License Manager is running, you must click Restart License Manager for your changes to take effect.

License File

Specifies the license file (.ghslic) containing licenses to be served by the License Manager. This field is equivalent to the -license command line option to the License Manager.

[Note] Note

Only one license file is supported from the GUI.

Description

Specifies a description for the License Manager. The description has no purpose other than identification. It appears in the MULTI License Administrator, which lists available License Managers on the network. A description may be useful when a network has multiple License Managers in use, with each one serving a particular group of end users. For example, you could set the description to The Tools Group, or Firmware Development.

This field is equivalent to the -desc command line option to the License Manager.

Log File

Specifies the absolute path to a file that stores logging information for every significant licensing event, such as the acquisition and release of a license. An absolute path is recommended to avoid confusion over the location of the log file when the License Manager is started in different ways (for example, automatically at boot, from a command line script, etc.). If you do not specify a log file, debugging information is sent to stdout, which is not displayed by Windows GUI applications.

If the first character of this field is a pipe character (|), the License Manager will use the rest of the field as a command line to be spawned and the log file will be sent as stdin to that process. This log piping is useful for implementing log rotation, filtering, or other custom log processing.

[Note] Note

Because log piping can be used to execute programs on the license host, take care to properly set permissions to the License Manager's configuration file. A malicious or ignorant user could configure the License Manager to run a program with undesirable side effects.

Example Log File entries follow:

/usr/green/lm.log

Sends log output to the file /usr/green/lm.log on the license host.

|/usr/local/bin/rotate.py /usr/green/lm.log 5m

Sends log output to a Python script written by the user, located at /usr/local/bin/rotate.py. The script takes two command line arguments: /usr/green/lm.log and 5m.

This field is equivalent to the -log command line option to the License Manager.

User Tracking File

Specifies the absolute path to a file that stores distinct user names. This field is equivalent to the -track_users command line option to the License Manager.

IP Addr Filter

Specifies a dotted-decimal or 32-bit hex value IP address as a filter whose zero fields match all values and whose non-zero fields match only the non-zero value given. The License Manager uses this value to filter requests from external machines and to deny those that come from unauthorized IP addresses. For example, if the IP address filter is 192.168.100.0, any client on the 192.168.100 subnet, such as 192.168.100.10, can access the License Manager. Requests from other subnets, such as 192.168.101.10 will be denied.

Requests coming from the local host address 127.0.0.1 are not filtered and always reach the License Manager.

This field is equivalent to the -filter command line option to the License Manager.

[Note] Note

This field is deprecated in MULTI 6. Use a license access file instead (see "Controlling Access to Licenses").

Verbose Logging

Indicates whether the License Manager logs more or fewer events. Logging additional events may be useful for visualizing the activity of the License Manager.

This field is equivalent to the -verbose command line option to the License Manager.

Start License Manager or Restart License Manager

Starts or restarts the License Manager on the license host. If the operation fails, a dialog box displaying diagnostic information appears.

On Windows, this button does not function correctly if the Services applet in the Windows Control Panel is open.


Configuring and Starting the License Manager from the Command Line

[Note] Note

Windows users running the License Manager as a Windows service should configure the License Manager via the GUI or via the lmconfig.txt configuration file. See "Configuring and Starting the License Manager from the GUI" or "Configuring the License Manager via Its Configuration File".

The License Manager executable, lic_lm, is available from the MULTI IDE and licensing utilities installation directories. To start the License Manager as a stand-alone program, run lic_lm from the command line as follows:

lic_lm [options]

The following table gives a description of each option. For options with a GUI equivalent in the License Manager Settings dialog box, more information is available in the description of the GUI equivalent. See "Configuring and Starting the License Manager from the GUI".

-debug

-d

On UNIX, enables debug mode, in which the License Manager will not start up as a daemon.

On Windows, causes the log file to be output to stdout. See also the -log log_file_path option below.

-debug_level num

Specifies how much debugging information should be logged. Valid values for num are from 0 to 11. See also the -verbose option below.

-desc description

Specifies a description for the License Manager. If description contains a space, enclose it in quotation marks.

This command line option is equivalent to the Description field in the License Manager Settings dialog box.

-filter IP_filter

Specifies a dotted-decimal or 32-bit hex value IP address as a filter whose zero fields match all values and whose non-zero fields match only the non-zero value given.

This command line option is equivalent to the IP Addr Filter field in the License Manager Settings dialog box.

[Note] Note

This command line option is deprecated in MULTI 6. Use a license access file instead (see "Controlling Access to Licenses").

-help

-h

Displays help information.

-license license_filename ...

Specifies the license file (.ghslic) containing licenses to be served by the License Manager. If license_filename contains a space, enclose it in quotation marks.

To specify multiple license files, repeat -license before each new filename. See Example 2.5. Specifying Multiple License Files.

When multiple license files are specified, each of them must be locked to a different TCP port. (TCP ports can only be assigned by Green Hills Software.) Duplicate license files (identified by serial number) are ignored.

This command line option is equivalent to the License File field in the License Manager Settings dialog box.

-log log_file_path

-l log_file_path

Specifies the absolute path to a file that stores logging information for every significant licensing event, such as the acquisition and release of a license. If log_file_path contains a space, enclose it in quotation marks. See also the -debug option above.

This command line option is equivalent to the Log File field in the License Manager Settings dialog box.

-noudp

Disables the UDP broadcasting service that locates the License Manager. As a result, UDP port 2009 is not used.

-track_users user_file_path

Specifies the absolute path to a file that stores distinct user names. If user_file_path contains a space, enclose it in quotation marks.

This command line option is equivalent to the User Tracking File field in the License Manager Settings dialog box.

-verbose

-v

Causes the License Manager to log additional events. To set verbosity more precisely, use the -debug_level num option above.

This command line option is equivalent to the Verbose Logging field in the License Manager Settings dialog box.

An example use of the lic_lm command follows.

Example 2.5. Specifying Multiple License Files

> lic_lm -desc Development -log /tmp/lm.log -license ppclicenses.ghslic \
-license armlicenses.ghslic

This command specifies multiple license files for use with a single License Manager. Note that each license file must be unique. Duplicate files will be rejected by the License Manager.


Configuring the License Manager via Its Configuration File

The License Manager's configuration is normally managed via the License Manager Settings dialog box. (For more information, see "Configuring and Starting the License Manager from the GUI".) The configuration is stored in a file called lmconfig.txt, which is located in the MULTI IDE or licensing utilities installation directory. You may configure the License Manager by modifying this file directly or by creating it, if it does not exist.

lmconfig.txt should be in ASCII format, with one option per line. The same syntax is used for options specified in lmconfig.txt and for command line options to the License Manager. Options specified on the command line override those specified in lmconfig.txt even if multiple occurrences of an option (such as -license) are permitted. For options, see "Configuring and Starting the License Manager from the Command Line". Lines beginning with # are treated as comments, and blank lines are ignored.

You must restart the License Manager before changes to lmconfig.txt take effect. See "Restarting the License Manager".


Other Ways to Start the License Manager

  • Windows -- To register the License Manager as a Windows service that runs automatically upon Windows startup, enter the following on the command line:

    > wrap_svc -m auto register

    To start the License Manager service after it has been registered, enter:

    > wrap_svc start

    For more information, see "Controlling the License Manager with wrap_svc".

  • Windows -- If a Windows service exists for the License Manager, ensure that the MULTI License Administrator is not open, and then use the Services applet to start the License Manager. You can access the Services applet from the Windows Control Panel or by running services.msc.

  • Linux/Solaris -- Modify the startup scripts on the license host to launch lic_lm at boot time. As an example, a bare-bones script for Solaris might exist in a file named /etc/rc2.d/S99ghs_lm with the following contents.

    #!/bin/sh

LM_DIR="/usr/ghs/licensing"

# This file will be loaded by the host, with default
# values for log file, verbosity, etc. In MULTI 6, the
# mlmadmin utility can be used to change these settings,
# or you may modify the config file with any text editor.
# The new settings will take effect after the host is
# restarted. The location of this file is defined here
# only for the operator's reference; changing this value
# will not enable lic_lm to use a different config file.
LM_CONFIG_FILE="$LM_DIR/lmconfig.txt"

case "$1" in
'start')
        cd $LM_DIR
        ./lic_lm
        ;;

'stop')
        /usr/bin/pkill -x -u 0 lic_lm
        ;;

*)
        echo "Usage: $0 { start | stop }"
        exit 1
        ;;
esac
exit 0

    For information about how to modify startup scripts, consult your operating system documentation. If you have any problems, please contact Green Hills Technical Support.


Stopping the License Manager

[Note] Note

Windows users with limited permissions are not able to modify the state of Windows services. To stop the License Manager, you must be logged in with administrator privileges.

To manually stop the License Manager:

  • In the MULTI License Administrator, select License->Stop License Manager on This Machine. For information about how to access the MULTI License Administrator, see "Viewing License Information with the MULTI License Administrator".

  • Windows -- If a Windows service exists for the License Manager, ensure that the MULTI License Administrator is not open, and then use the Services applet to stop the License Manager. You can access the Services applet from the Windows Control Panel or by running services.msc.

  • Windows -- If you have started the License Manager via the wrap_svc utility, enter the following on the command line:

    wrap_svc stop

    For more information, see "Controlling the License Manager with wrap_svc".


Restarting the License Manager

If you make changes to the License Manager's configuration via the License Manager Settings dialog box or the file lmconfig.txt, you must restart the License Manager before your changes take effect. To restart the License Manager manually, perform one of the following operations:

  • In the License Manager Settings dialog box, click Restart License Manager. For information about how to access this dialog box, see "Configuring and Starting the License Manager from the GUI".

  • Windows -- If you have started the License Manager via the wrap_svc utility, enter the following on the command line:

    > wrap_svc restart

    For more information, see "Controlling the License Manager with wrap_svc".

  • Windows -- If a Windows service exists for the License Manager, ensure that the MULTI License Administrator is not open, and then use the Services applet to restart the License Manager. You can access the Services applet from the Windows Control Panel or by running services.msc.


Controlling the License Manager with wrap_svc

On Windows, the wrap_svc utility allows you to register the License Manager as a Windows service, and control the service once it is registered.

Before running wrap_svc on Windows, ensure that the following prerequisites have been met:

  • You are logged in with administrator privileges. Additionally, if you are using Windows 7 or Windows Vista and User Account Control (UAC) is enabled (the default), the command prompt must be started using the Run as administrator option:

    1. From the Start menu, select All Programs->Accessories.

    2. Right-click Command Prompt and select Run as administrator.

  • The Services applet in the Windows Control Panel is not active.

  • The MULTI License Administrator is not open.

  • All other running programs have been exited (recommended, not required).

The wrap_svc executable is available from the MULTI IDE and licensing utilities installation directories. You can launch it from the command line as follows:

wrap_svc [options] [action]

The following options can be used with wrap_svc.

-b 0|1

Determines whether or not wrap_svc creates Windows firewall exceptions for the License Manager. Passing 0 does not create firewall exceptions; passing 1 does. The default is 1.

-compat

Causes wrap_svc to act on the MULTI 5 License Manager instead of the MULTI 6 License Manager. See also the -new option below.

-e executable

Registers executable as the License Manager. The default is lic_lm.exe.

-m mode

Sets the startup mode to mode. The default is manual.

Supported modes are:

  • auto -- The service starts automatically at boot.

  • manual -- The service must be started manually.

  • disabled -- The service is marked as disabled.

-n service_name

Causes wrap_svc to act on the service registered with service_name. The default service name is ghs_lm.

-new

Causes wrap_svc to act on the MULTI 6 License Manager (the default). See also the -compat option above.

The following actions can be used with wrap_svc.

print

Print the current service registration information. This is the default action if none is specified.

register

Register the service with the operating system.

restart

Restart the service.

start

Start the service.

stop

Stop the service.

unregister

Unregister the service. Running services are unregistered when they are stopped.

Example 2.6. Registering the License Manager for Automatic Startup

To register the License Manager as a Windows service and schedule it to start automatically when Windows starts, enter the command:

wrap_svc -m auto register

Example 2.7. Starting the License Manager

To start the License Manager after it is registered, enter the command:

wrap_svc start

Example 2.8. Stopping the License Manager

To stop the License Manager, enter the command:

wrap_svc stop


License Manager Automatic Startup and Shutdown

If you are using Windows and you start the License Manager via the License Manager Settings dialog box, or if you create a service via the wrap_svc utility that is set to start up automatically, the License Manager automatically runs when the operating system is booted and shuts down when the operating system is shut down.

Likewise, if you are using Linux/Solaris and you modified the startup scripts on the license host to launch lic_lm at boot time, the License Manager automatically runs when the operating system is booted and shuts down when the operating system is shut down.


Configuring End User Machines

Certain license administration settings can be controlled by way of configuration variables set in the end user's installation or in the end user's environment. This chapter contains information about these variables and how to set them.


Setting Configuration Variables

Configuration variables should normally be set in the end user's license configuration file, license.cfg, making settings available for easy reference and allowing settings to be shared with colleagues. To maintain a single license.cfg file that affects the IDE and Compiler installations on the client machine, set the environment variable GHS_LICENSE_CFG_FILE to an absolute path. For more information about this variable, see the next section.

If you do not set GHS_LICENSE_CFG_FILE, MULTI searches for license.cfg in install_dir\config, where install_dir is the IDE installation directory if the MULTI IDE is in use, and the Compiler installation directory if the Green Hills Compiler is in use. This means that by default, license.cfg only affects the product in whose installation directory it is found, necessitating its maintenance in both the IDE and Compiler installation directories.

If license.cfg does not exist, you can create it. Each line of license.cfg should specify a single setting. A setting is of the form VARIABLE=VALUE. Valid variables are listed below.

While setting configuration variables in license.cfg is preferred, configuration variables may also be set in the user's environment. However, settings in the configuration file override environment settings. For information about setting environment variables, refer to your operating system documentation.


Configuration Variables for End User Machines

The following configuration variables are valid for use on client machines connecting to the License Manager, and on machines with computer- or dongle-locked licenses.

GHS_LICENSE_CFG_FILE

Specifies the location of the license configuration file. Unlike other configuration variables, which should optimally be set in the license configuration file, but which may be set in the user environment, GHS_LICENSE_CFG_FILE can only be set in the environment. Valid values are:

  • unset -- [default] Uses the default location for the license configuration file: install_dir\config, where install_dir is the IDE installation directory if the MULTI IDE is in use, and the Compiler installation directory if the Green Hills Compiler is in use. For more information, see "Setting Configuration Variables".

  • absolute_path -- Uses a specific configuration. Do not begin the path with a tilde (~).

GHS_LMDEBUG

Specifies the level of debugging information to be generated. Valid values are from 0 to 11.

By default, debugging information is sent to stdout. Windows GUI applications, however, do not display stdout. To redirect debugging output to an accessible file, use the GHS_LMINFO_DIR variable (see below).

GHS_LMINFO_DIR

Specifies an existing directory in which to create an .lmi file that contains debugging output. This variable implies the GHS_LMDEBUG variable.


Configuration Variables for Client Machines

The following configuration variables are valid for use on client machines connecting to the License Manager.

GHS_LMDELAY

Specifies the maximum acceptable time to elapse (in seconds) before receiving a response from a License Manager once a connection has been successfully established. This number should account for the overall transit speed of Ethernet communication on your network.

The default is 15.

GHS_LMHOST

Specifies the name(s) or IPv4 address(es) of the license host(s) running a License Manager on the network, and, if there are multiple license hosts, the way in which MULTI products attempt to contact License Managers when trying to obtain a license. This variable can be set in one of the following ways:

  • Single license host:

    license_host_name_or_ip

  • Multiple license hosts, attempt contact in order:

    @license_host_name_or_ip,license_host_name_or_ip,...

    For example:

    GHS_LMHOST=@192.168.100.10,192.168.100.11,host3

  • Multiple license hosts, attempt contact at random:

    #license_host_name_or_ip,license_host_name_or_ip,...

    For example:

    GHS_LMHOST=#fee,fie,192.168.100.12,fum
[Note] Note

Multiple license hosts should be specified in a comma-separated list.

For more information, see "Specifying a Floating or Named-User License Pool".

GHS_LMNOCACHE

Suppress the default behavior of using cached licenses when available. Due to its negative impact on performance, this variable should only be set for diagnostic purposes. Valid values are:

  • unset [default]

  • 1

GHS_LMPORT

Specifies the Green-Hills-assigned TCP port that the License Manager(s) listen(s) on. If the default port (2009) is not the port in use, this variable must be set to the correct port to ensure that the client programs connect to it. Every License Manager running on a license host specified by GHS_LMHOST is assumed to be listening on this port.

For more information, see "Specifying a Floating or Named-User License Pool".


Configuration Variables for Machines with Local Licenses

The following configuration variables are valid for use on machines with computer- or dongle-locked licenses.

GHS_LM_EXPECTED_MAC

Specifies the MAC address (for example, B8-AC-6F-97-5A-5F or B8:AC:6F:97:5A:5F) to use when validating licenses against the Ethernet hardware. This can be used to tell MULTI products not to use an Ethernet adapter that is commonly removed from the system. The specified value must match the Ethernet address of an installed adapter.

You can display MAC addresses by:

  • Windows -- Running ipconfig /all from a command prompt. MAC addresses are listed under Physical Address.

  • Linux/Solaris -- Running ifconfig -a.

By default, the first adapter in the system is used.

LICENSE_FILE_DIR

Specifies the directory where the license files reside. By default, the MULTI products look for the license files in C:\GHS\licenses on Windows. To instruct the products to look in a different directory for the license files, specify an absolute path.


Specifying a Floating or Named-User License Pool

When a licensed MULTI product runs on a client machine, the product attempts to obtain a floating or named-user license from a license pool. A license pool is a set of licenses specified in a license file (.ghslic). The licenses in a given license pool are served by a particular License Manager running on a license host on the network and listening on a particular TCP port. The preferred license pool can be identified by:

  • the license host that the License Manager is running on

  • the TCP port that the License Manager is listening on

End users are instructed to specify the license host by setting the GHS_LMHOST configuration variable in the GUI (see "Obtaining Floating or Named-User Licenses"), but the license host may also be specified by setting GHS_LMHOST in the client's license configuration file (license.cfg) or in the client's environment. For more information, see "Setting Configuration Variables". If there are multiple license hosts, see "Using Multiple License Hosts".

The TCP port that the License Manager listens on is assigned by Green Hills Software. If a TCP port other than the default (2009) is assigned, the GHS_LMPORT configuration variable on the client machine should be set to the corresponding port number. Only one TCP port can be specified via GHS_LMPORT, and this port number is assumed to be in use by every License Manager running on a license host specified via GHS_LMHOST. If GHS_LMPORT is not set, the default port number (2009) is used.

Example 3.1. Using a Single License Host and TCP Port

Suppose there is one license host, which is named host1 and which is running a License Manager that is listening for license requests on TCP port 2009. On client machines, GHS_LMHOST should be set as follows:

GHS_LMHOST=host1

Since the default TCP port is in use, GHS_LMPORT does not need to be set.

Example 3.2. Using a Single License Host and Multiple TCP Ports

Suppose now that there is still one license host named host1, but that it is running a License Manager that is listening for license requests on TCP ports 2009, 3000, and 4000. A license pool of MULTI for Power Architecture licenses is bound to port 2009, a pool of MULTI for ARM licenses is bound to port 3000, and a pool of MULTI for MIPS licenses is bound to port 4000. On client machines requiring access to Power Architecture licenses, GHS_LMHOST should be set as follows:

GHS_LMHOST=host1

Since the Power Architecture license pool is bound to the default TCP port, GHS_LMPORT can remain unset.

On clients requiring access to ARM licenses, GHS_LMHOST and GHS_LMPORT should be set as follows:

GHS_LMHOST=host1
GHS_LMPORT=3000

Finally, on clients requiring access to MIPS licenses:

GHS_LMHOST=host1
GHS_LMPORT=4000


Using Multiple License Hosts

If there are multiple license hosts, GHS_LMHOST should be set to a comma-separated list of license host names or IP addresses. Clients attempt contact in a designated order if the comma-separated list is prepended with an @ character, or at random if the comma-separated list is prepended with a # character.

For example, suppose there are three license hosts whose IP addresses are 192.168.100.10, 192.168.100.11, and 192.168.100.12. Suppose further that you want clients to attempt to contact the License Manager running on 192.168.100.10 first, then on 192.168.100.11, and finally on 192.168.100.12. On client machines, GHS_LMHOST should be set as follows:

GHS_LMHOST=@192.168.100.10,192.168.100.11,192.168.100.12

Randomly selecting license hosts implements a rudimentary form of load balancing. To indicate that the License Managers should be tried at random, GHS_LMHOST should be:

GHS_LMHOST=#192.168.100.10,192.168.100.11,192.168.100.12
[Note] Note

The # character is a comment character for many shells. If set in an environment variable, it should be escaped.

Example 3.3. Using Multiple License Hosts and Multiple TCP Ports

Suppose that the following are true:

  • There are two license hosts named host1 and host2.

  • A license pool of MULTI for Power Architecture licenses is bound to host1, port 2009. A second pool of Power Architecture licenses is bound to host2, port 2009.

  • A license pool of MULTI for MIPS licenses is bound to host1, port 3000. A second pool of MIPS licenses is bound to host2, port 3000.

  • A license pool of MULTI for ARM licenses is bound to host2, port 4000.

  • You prefer the License Manager running on host1 to be contacted first, if applicable.

On client machines requiring access to Power Architecture licenses, GHS_LMHOST should be set as follows:

GHS_LMHOST=@host1,host2

GHS_LMPORT would remain unset.

On clients requiring access to MIPS licenses, GHS_LMHOST and GHS_LMPORT should be set as follows:

GHS_LMHOST=@host1,host2
GHS_LMPORT=3000

Finally, on clients requiring access to ARM licenses:

GHS_LMHOST=host2
GHS_LMPORT=4000


Viewing License Information

Licensing information is accessible from the MULTI License Administrator and via certain license administration utilities. This chapter contains information about using the MULTI License Administrator and about running the lic_find_licenses and lic_log_summary.py utilities.


Viewing License Information with the MULTI License Administrator

The MULTI License Administrator is a graphical interface to the License Managers on the network and to licenses available locally (computer- and dongle-locked) or over the network (floating and named-user). To open the MULTI License Administrator, follow these steps:

  1. Start the MULTI Licensing Wizard by:

    • Selecting Utilities->License Administrator from the MULTI Launcher, or by

    • Running mlmadmin.exe (mlmadmin on Linux/Solaris) from the MULTI IDE or licensing utilities installation directory.

  2. In the MULTI Licensing Wizard, select View license information, and click Next.


Viewing License Managers on the Network

By default, the MULTI License Administrator displays License Managers on the network. Whether all License Managers are displayed depends upon your network configuration. To specify additional License Managers for display:

  1. Click Specify License Managers.

  2. Enter a comma-separated list of the license hosts on which a License Manager is running.

By default, the MULTI License Administrator displays only those License Managers on the network that are serving licenses to enable MULTI 6. To display License Managers that are serving licenses to enable another version of MULTI:

  • Clear Only show License Managers for MULTI v6.

For information about the items available in the MULTI License Administrator, see "The MULTI License Administrator Window".


Viewing Floating and Named-User Licenses

To view the floating or named-user licenses served by a particular License Manager:

  1. Display available License Managers (the default) in the MULTI License Administrator by selecting License->View Network Licenses. (If this menu item is not available, you are already viewing available License Managers.)

  2. Do one of the following:

    • Double-click an entry in the MULTI License Administrator.

    • Right-click an entry in the MULTI License Administrator, and select View License Information.

To view the floating or named-user licenses served by all License Managers listed in the MULTI License Administrator, do one of the following:

  • In the MULTI License Administrator, click Show License Info.

  • In the MULTI License Administrator, select License->View Network License Details.

For information about the resulting License Information window, see "The License Information Window".


Viewing Computer- and Dongle-Locked Licenses

To view the computer- or dongle-locked licenses that are installed locally:

  • Select License->View Local Licenses in the MULTI License Administrator. (If this menu item is not available, you are already viewing local licenses.)

For information about the items available in the MULTI License Administrator, see "The MULTI License Administrator Window".


Listing Floating and Named-User Licenses with lic_find_licenses

The lic_find_licenses utility lists floating and named-user licenses served by License Managers on the network. The lic_find_licenses executable is available from the MULTI IDE and licensing utilities installation directories. You can launch it from the command line as follows:

lic_find_licenses [options]

By default, the utility will contact the License Managers running on license hosts specified by GHS_LMHOST and list information about them. See "Configuration Variables for Client Machines".

The following options can be used with the lic_find_licenses command.

-a

Displays an alternative format (suitable for grep and other line-oriented text processors).

-b

Broadcasts to find license hosts running a License Manager on the network.

-l list

(This option begins with a lowercase L.)

Uses list as the comma-separated list of license hosts. Ports may be specified by appending :port to the license host name.

-o

Only shows licenses currently in use. The default is to show all installed licenses.

-product product_name | product_code

Specifies the product that a License Manager must serve in order to be found by a broadcast.

-s

Displays license sources, but not the licenses found on those sources. A license source can be a local directory or a License Manager that is checked for licenses by the MULTI products. This option implies the -x option.

-w

Includes information about who is using licenses. See "Output Format with -w".

-x

Does not start with the default License Managers, which are those running on license hosts specified by GHS_LMHOST. This option implies the -b option.

Example 4.1. Using lic_find_licenses

Assuming GHS_LMHOST has been set to TARPON, and you want to list information about licenses served by the License Manager running on TARPON, enter the command:

lic_find_licenses

This generates output similar to:

Server TARPON: 2009 (169.254.139.247):
  ecomppc (2901): 10 installed, 2 in use, 7 hwm

This indicates that the License Manager running on TARPON is listening on port 2009 and has 10 licenses for ecomppc (the Power Architecture C/C++ compiler). Of those 10, 2 are currently in use. Since the License Manager was started, the most licenses that have been in use at any time (hwm--the high water mark) is 7.


Output Format with -w

When the -w option is specified with lic_find_licenses, user information is formatted in one of two ways:

  • The following format indicates that the license is not actively in use, but the License Manager is temporarily reserving the license for the specified previous user:

    ! user@host {client_id}

    where:

    • user is the login of the end user that requested the license.

    • host is the IP address of the computer from which the license was requested. @host may be omitted if the specified user has a named-user license reserved to their use, but has not yet requested a license.

    • client_id is an internal, hexadecimal number used by the License Manager to keep track of the license.

  • The second format indicates that the specified user is actively using the license:

    user@host time_in_use {client_id}

    where:

    • user, host, and client_id are the same as above.

    • time_in_use indicates how long the license has been checked out. For example, 35m26s indicates that the license has been checked out for 35 minutes and 26 seconds.


Summarizing License Manager Logs with lic_log_summary.py

The lic_log_summary.py utility is a Python script that serves as a reference implementation of a log summarizing tool. This utility processes a License Manager log file and produces a summary of the license usage by product and date. The output is in a comma-separated values (CSV) format, which can easily be imported into spreadsheet and database applications for advanced reporting and graphing capabilities. With this data, it should be easy to produce reports in different formats to suit your needs.

The lic_log_summary.py script is available from the MULTI IDE and licensing utilities installation directories. You can launch it from the command line as follows:

lic_log_summary.py [options] [products]

The following arguments can be used with lic_log_summary.py:

--help

Print usage information.

-m

Total usage by month, rather than by day

-f file

Read the log file from file, rather than stdin.

products

Only display information about the specified products. If no products are specified, all products will be included.

Example 4.2. Using lic_log_summary.py

The command:

lic_log_summary.py -m -f ghs_elmd.log

will display a summary of license usage from the log file named ghs_elmd.log, with usage totaled by month and product.

[Note] Note

The lic_log_summary.py utility is written in the Python language, and requires a Python v2.x interpreter to run. It is not compatible with Python v3. The MULTI IDE installation (but not the licensing utilities installation) includes a complete Python 2.3.3 installation for your platform. For more information, see Python Installation. The utility is provided as a script so that its source code can be examined and modified to suit the needs of the end user. It should be simple to study the script and implement the same concepts in another language if desired.


Appendices


GUI Reference


The MULTI License Administrator Window

By default, the MULTI License Administrator displays available License Managers, as shown next.

Each field in the window is described in the following table.

Available License Managers

Lists information about each License Manager running on the network, where:

  • Host Name -- Specifies the name of the machine on which the License Manager is running.

  • Serial Number -- Uniquely identifies the license file that the License Manager is reading from.

  • Port -- Specifies the TCP port that the License Manager is listening on.

  • Description -- Provides a description of the License Manager.

  • Model -- Specifies the type of network license--floating or named-user--that the License Manager is serving.

  • License Manager Information -- Lists version information for the License Manager.

  • Start Time -- Lists the date and time that the License Manager was started.

N/A indicates that information is not available from the License Manager because it predates MULTI 6.

Refresh

Populates or refreshes the list of License Managers running on the network. The MULTI License Administrator performs a broadcast to find available License Managers on the network.

Only show License Managers for MULTI v6

Toggles the display of all License Managers on the network or only those License Managers serving licenses to enable MULTI 6 (the default).

Specify License Managers

Allows you to provide a comma-separated list of license hosts. The MULTI License Administrator will attempt to contact License Managers running on these license hosts.

This setting is necessary if the license hosts cannot be reached by broadcast.

Show License Info

Displays information about all product licenses served by License Managers shown in the MULTI License Administrator, and provides access to lists of license users. For more information, see "The License Information Window".

Selecting License->View Local Licenses in the MULTI License Administrator displays locally available computer- or dongle-locked licenses. A sample window is shown next.

Each field in the window is described in the following table.

Local License Files

Displays information about the computer- or dongle-locked licenses in the specified license file(s).

Refresh

Refreshes local license information.

Licenses from the above license file

Lists information about the licenses, where each row specifies:

  • Product Name -- The type of product license.

  • Product Code -- The internal ID used by Green Hills Technical Support to identify the licensed product.

  • Expiration -- The expiration date for the license.

  • File -- The license file (.ghslic) containing the license.


MULTI License Administrator Menus


The File Menu

The File menu of the MULTI License Administrator contains the following options:

Licensing Wizard

Launches the MULTI Licensing Wizard.

Save Local License Information to File

Allows you to save license information displayed in the MULTI License Administrator to a file. This option is only available if you are viewing local licenses.

Close

Closes the MULTI License Administrator.


The License Menu

The License menu of the MULTI License Administrator contains the following options. The appearance of certain options is dependent upon whether you are viewing local or network licenses.

View Local Licenses

Displays information about local computer- and dongle-locked licenses.

View Network Licenses

Displays information about License Managers found on the network.

View Network License Details

Displays all floating and named-user product licenses served by License Managers shown in the MULTI License Administrator, and provides access to lists of license users. For more information, see "The License Information Window".

Stop License Manager on This Machine

Stops the local License Manager.

Diagnose License Problems

Allows you to test whether you can obtain a license for a particular MULTI product. You should only need to use this feature if prompted by Green Hills Technical Support.


The Help Menu

The Help menu of the MULTI License Administrator contains the following options:

Help

Opens online help for the MULTI License Administrator. You may also press F1 to access online help.

Manuals

Opens the Manuals submenu, which displays a list of all manuals included in your MULTI installation. Choose a manual to open its online help.

About

Opens a dialog box that contains basic information about the MULTI License Administrator, such as its version and copyright information.

Troubleshooting Info

Launches the gbugrpt utility, which collects information about your MULTI installation and allows you to save it or email it. In the event of problems, it can be useful to email the information to Green Hills Technical Support or to your product support contact.


Shortcut Menu

When you are viewing network licenses, and you right-click an Available License Manager entry, a shortcut menu opens. The shortcut menu contains the following item:

View License Information

Displays all floating and named-user product licenses served by the License Manager, and provides access to lists of license users. For more information, see "The License Information Window".


The License Information Window

The License Information window contains the following items:

License Manager

Displays information about the floating or named-user licenses served by the License Manager(s) running on the specified machine.

Refresh

Updates the license usage snapshot.

Close

Closes the window.

Product List

Lists information about product licenses, where each row identifies:

  • LM Host -- The machine from which the License Manager is running and serving licenses.

  • Product Name -- The type of product license being served.

  • Product Code -- The internal ID used by Green Hills Technical Support to identify the licensed product.

  • Installed -- How many product licenses are installed.

  • Current Usage -- How many product licenses are currently in use.*

  • Peak Usage -- The greatest number of product licenses that have been in use at any one time since the License Manager was started.*

  • Expiration -- The product licenses' expiration date. If the product licenses do not expire, nothing is displayed in this column. If the expiration is not available because the License Manager predates MULTI 6 and does not provide this information, N/A is displayed in this column.

*A named-user product license is not considered to be in use until it is actually granted to the named user for whom it is reserved.

Selected Product's User List

Lists information about the entry selected in the Product List, where each row specifies:

  • User -- An end user to whom a floating product license has actually been granted, or an end user for whom a named-user product license is reserved. Named user licensees are displayed whether or not the named-user license has been granted.

  • Host -- The end user's machine (the client machine) if the end user has been granted a license. If a license has not been granted, this column is empty.

  • Length -- The length of time that the license has been in use, if granted. If a license has not been granted, this column is empty.


The License Information Window's File Menu

The File menu of the License Information window contains the following options:

Save Viewed License Information to File

Allows you to save the license usage snapshot in the License Information window to a file.

Close

Closes the License Information window.


Administration Utilities

This appendix provides information about administration utilities. Unless otherwise noted, these utilities are supported on Windows and on Linux/Solaris.

Utilities are further documented in relevant sections of this book or, if no applicable context exists elsewhere, in this appendix.

lic_find_licenses

Lists licenses served by License Managers on the network. For more information, see "Listing Floating and Named-User Licenses with lic_find_licenses".

lic_log_summary.py

A Python script that serves as a reference implementation of a log summarizing tool. This utility processes a License Manager log file and prints a comma-delimited summary of license usage by product and date, suitable for importing into a spreadsheet for graphing and further analysis. For more information, see "Summarizing License Manager Logs with lic_log_summary.py".

lic_userlist

Utility for named-user licenses, which manages user lists on the license host. For more information, see "Managing User Lists with lic_userlist".

mlmadmin

Program used for displaying license information. For more information, see "Viewing License Information with the MULTI License Administrator".

servecode

Prints valid server codes for the machine upon which it is run. For more information, see "Determining Server Codes with servecode".

wrap_svc

Windows only

Wrapper executable that allows the License Manager to act as a Windows service. Windows services can be launched automatically at system startup, and can be controlled through the Services applet. For more information, see "Controlling the License Manager with wrap_svc".


Determining Server Codes with servecode

Licenses are locked to a server code, which defines where the licenses can be installed (computer- and dongle-locked) or where the License Manager serving the licenses can run (floating and named-user). When Green Hills Software grants license requests, it is important for it to have the correct server code from the correct machine.

The servecode utility determines valid server codes for the machine upon which it is run. While a valid server code is automatically determined when you request licenses via the MULTI Licensing Wizard, there are a few cases when you may want to run servecode directly.

The servecode executable is available from the MULTI IDE, Compiler, and licensing utilities installation directories. You can launch it from the command line as follows:

servecode [options]

The following table provides descriptions of the servecode options.

--help

-h

Displays usage information.

--verbose

-v

Displays all available server codes. If this option is not specified, only the first available server code is printed.


Troubleshooting


Floating and Named-User Licensing Problems

  • If you see a dialog box with the following message:

    No MULTI licenses available.
[There are no local licenses and there are no License Managers to contact]
MULTI Licensing Wizard will be launched.

    You have not specified a License Manager from which to obtain licenses, or the specified License Manager cannot be contacted. If the former, follow the instructions in "Obtaining Floating or Named-User Licenses". If you have already specified a License Manager, ask your system administrator to investigate the problem.

  • If you are unable to obtain floating or named-user licenses and you have determined that the information above is not applicable, you can set the variable GHS_LMDEBUG to 11, and the variable GHS_LMINFO_DIR to an existing directory. This causes MULTI to output diagnostic information to .lmi files created in the specified directory. For more information, see "Setting Configuration Variables".


Dongle Problems

Most dongle problems are due to the following issues:

  • The installed license was not issued for use with your dongle.

    To determine whether this is the cause of the problem, locate the SERVER CODE comment in your installed license file (.ghslic), and compare it to the output of the servecode utility (see "Determining Server Codes with servecode"). While servecode's output begins with num#0x and the license file's code begins with num/, the codes should otherwise match. num at the beginning of the servecode output and num at the beginning of the license file code should also match. The most common cause of mismatch is use of the wrong license file.

  • There are incompatibilities with other devices or certain hardware.

    GHS uses the SafeNet Sentinel SuperPro as our hardware security device (dongle). Dongle drivers are installed by default if you use the MULTI Licensing Wizard to request or install licenses. If you experience conflicts or incompatibilities after the drivers are installed, Green Hills recommends that you:

    1. Run the SetupSysDriver.exe utility (typically located in C:\Program Files\Common Files\SafeNet Sentinel\Sentinel System Driver\).

    2. Configure the drivers to use only the device to which the dongle is attached.

    For example, you might:

    1. Run the utility.

    2. Click the Configure Driver button to get to the configuration screen.

    3. Select any lines not corresponding to the USB port where the dongle is attached.

    4. Click Edit so that the drivers do not use the selected port(s).

    SafeNet maintains a list of known incompatibilities, accessible from their main corporate Web site.

  • Dongle drivers are outdated or are not installed correctly.

    Insert the dongle into a USB port on your machine. If you run the servecode utility (see "Determining Server Codes with servecode") and the output does not begin with a 2#, dongle drivers are outdated or are not installed correctly. You can use the Sentinel Medic program from SafeNet to further diagnose the problem. SafeNet is the manufacturer of the dongles and dongle drivers used by MULTI products. We recommend downloading the latest version of the drivers and the Sentinel Medic application from the SafeNet Web site.

  • There is more than one dongle installed.

    MULTI products only recognize one dongle at a time. Dongles from other vendors are not visible to our products, so they should not pose a problem.

SafeNet maintains additional dongle troubleshooting information on their Web site. If you have further questions, please contact Green Hills Technical Support.


MULTI: Licensing

Green Hills Software

DISCLAIMER