CADSWES - RiverWare Viewer License Guide

Home > RiverWare > Viewer > License Guide

RiverWare Viewer License Guide

RiverWare Release: 4.x
Last Updated: March 19, 2004

This document describes how RiverWare software is license managed and instructions for how to set up your environment to run the RiverWare Viewer.

1.0 Introduction

Beginning with Release 2.0, RiverWare is a license controlled software product. It can be configured to run on a single specified computer or with a maximum of five concurrent users on a network of one or more computer systems.

All of the license management related programs are packaged together with each RiverWare release. You will have all of the files you need after installing RiverWare on your system (except the "cadswes.lic" file, which you need to request from CADSWES). Therefore, no special instructions are required for installing the licensing software.

All of the license management related programs are stored in a subdirectory named "license" from where you have installed RiverWare.

RiverWare uses the Flexible License Manager from Globetrotter Software to manage RiverWare licenses.

2.0 Types of License

2.1 Node-Locked License

A node-locked license means the licensed RiverWare can only be run on one particular machine specified in the CADSWES license manager configuration file "cadswes.lic." This type of license allows unlimited user to run RiverWare on the machine specified in the license file and does not require a running license manager daemon or the CADSWES license daemon.

2.2 Floating License

A floating license means up to five users on the network can run the licensed RiverWare. This type of license requires a running license manager daemon and the CADSWES license daemon to count the concurrent usage of the RiverWare license.

3.0 The License File "cadswes.lic"

A license file named "cadswes.lic" is required to run RiverWare. This file contains all site-specific information required by the RiverWare license manager.

3.1 Request a "cadswes.lic" from CADSWES

After you have signed the purchase aggrement and selected a machine, You need to acquire a "cadswes.lic" file from CADSWES that is issued specifically to your site. Use the following email or support number to request this file from CADSWES:

email: installsupport@cadswes.colorado.edu
phone: (303) 492-0908

If your license type is floating license, you must select which machine to run the RiverWare license manager daemons. This machine will be the license server which handles RiverWare license requests.

A RiverWare license file will be delivered to you as an attachment in an email. The instructions for downloading and installing RiverWare on your machine will be emailed to you and they are also available on CADSWES website.

Follow the instructions below to obtain the machine information in order for CADSWES to issue a license file to your site.

Solaris Platform

You need to supply a "host name" and the "host ID" (for the machine which RiverWare will run on) to CADSWES when requesting the license file. All Sun Microsystems, Inc. machines have a unique host ID. Use the following Unix command to obtain the host name and the host ID.

The following commands must be run on the machine on which you have physically logged into and is the same machine on which you will run the license manager daeman "lmgrd", "cadswes", and RiverWare.

Get the host name of your machine:
$ hostname

Get the host ID of your machine:
$ hostid

Windows Platform

You need to supply a "host name" and the "Ethernet Physical Address" (for the machine which RiverWare will run on) to CADSWES when requesting the license file. Follow the instructions below to obtain the host name and the Ethernet Physical Address.

Log on to your Windows machine.

Start the Command Prompt window. This can be done by:

Select Start -> Run, then enter "cmd" in the Run window.

If the Command Prompt is in your Program folder, Select Start -> Programs -> Command Prompt.

Type the following command in the Command Prompt window:
ipconfig /all

This will return some system configuration information. What we need is the value of the "Host Name" and the "Ethernet Physical Address." Ethernet Physical Address is a 6-byte quantity, with each byte specified as two hexadecimal digits. It is presented as a string containing a combination of twelve numbers and/or letters in the following format:

xx-xx-xx-xx-xx-xx

If there are more than one Ethernet Physical Address on your system, please verify which is the one you will use to run RiverWare.

3.2 License File Format

RiverWare license file is a regular text file, which contains the following lines:

SERVER Line:
The SERVER line specifies the host name and host ID of the license server, and the port number of the license manager daemon (lmgrd). This line is absent if the license type is node-locked license.

VENDOR (or DAEMON) Line:
The VENDOR line specifies the CADSWES daemon name (cadswes) and path. This line may also be called DAEMON. This line is absent if the license type is node-locked uncounted license.

USE_SERVER Line:
The USE_SERVER line has no arguments. It improves performance when a license server is used. This line is absent if the license type is node-locked license.

FEATURE Line:
A FEATURE line describes the license for using the RiverWare Product. It contains a license key which is a 12 to 20 character hexadecimal number which authenticates the licensed RiverWare. This entire line can not be modified for any reason.

Comment line:
Lines starting with a "#" are comments, which contain CADSWES and license file information.

4.0 License for Solaris Platform

4.1 License File Location and Components

The RiverWare license file "cadswes.lic" must be stored in the subdirectory named "license" from where you have installed RiverWare. Normally you use the same license file for all of the RiverWare releases (until the license expires). Therefore we recommend you to save a copy of the license file to another location (in case you lose it when re-installing RiverWare).

By default, RiverWare searches license file from directory $RIVERWARE_HOME/license.

Solaris version of RiverWare contains six license management components:

License manager daemon - lmgrd

"lmgrd" is the main daemon program for managing the licenses of RiverWare. The daemon handles the initial contact with RiverWare, passing the connection on to the CADSWES daemon "cadswes". It also starts and restarts the CADSWES daemon. You do not need this daemon program if the type of the RiverWare license you have is "Uncounted Node-Locked License. "

CADSWES license daemon - cadswes
"cadswes" is the CADSWES daemon that keeps track of how many RiverWare licenses are checked out and who has them. If this daemon terminates for any reason, all users lose their licenses. This license daemon is started and stopped automatically by license manager daemon "lmgr." Users normally regain their license automatically when license manager daemon "lmgrd" restarts the CADSWES daemon.

License manager configuration file - cadswes.lic
The "cadswes.lic" file is a text file which stores the licensing data for a specific RiverWare user site. It is created and distributed to each site by CADSWES. It contains information about the license manager for RiverWare at the user site, the CADSWES daemon, and the RiverWare product licensed by CADSWES.

License administration tools - lmutil
"lmutil" is a utility program provided by Globetrotter Software to help manage the licensing activities on the network. It contains eleven individual utilities and can be run as following:

$ lmutil <utility-name>

License manager daemon start/stop script - rwlicense.rc

A script provided by CADSWES to simplify the procedure of starting and stopping the license manager daemon "lmgrd."

License Manager User's Guide - license_guide.txt

This document. This document is available in the subdirectory "license" from where you have installed RiverWare.

4.2 Node-Locked License

Following are the instructions for starting the RiverWare Solaris version using your node-locked license:

Save the "cadswes.lic" file to the subdirectory "license" from where you have installed RiverWare. This file should be saved exactly as it is delivered to you without any modifications.

By default, RiverWare searches license file from directory $RIVERWARE_HOME/license when you start RiverWare.

If RiverWare encounters any problems when trying to access a license file, an error message will be returned on the command line. Please save the error messages and email it to CADSWES for debugging.

4.3 Floating License

Floating license requires a running license manager daemon "lmgrd" and the CADSWES daemon "cadswes." These two files are included in the subdirectory "license" from where you have installed RiverWare. These two license manager daemons must be started, or stopped and then re-started, in the following two cases:

The first time after the RiverWare application and the RiverWare floating license file (the cadswes.lic) were installed. In this case, the new processes of license manager daemons must be started.

After a "new" RiverWare floating license file was installed. Normally this means the installation of a renewal floating license.
In this case, the currently running license manager daemons (which are running using the old RiverWare floating license file) must be stopped first and then the new processes of license manager daemons must be started using the new RiverWare floating license file.

Re-starting the license manager daemons is not necessary when a new release of RiverWare is installed, as long as the license file is still valid and the location of the license file has not been changed. It is only required when a new RiverWare floating license file needs to be used to run RiverWare.

Starting License Server from the Command Line

The instructions below describe how to start and stop the license manager daemons by manually executing the commands from the command prompt. All of the necessary programs for running license managed RiverWare are placed in a subdirectory named "license" from where RiverWare is installed.

Examples in this section assume you are running the C-shell; the exact commands will vary for other shells. They also assume that your environment variable "RIVERWARE_HOME" is set to "/usr/local/RiverWare" and all of the licensing programs are stored in the directory "/usr/local/RiverWare/license."

Each command example in this section starts with a command prompt "$" which represents an Unix command.

Set the environment variable, "RW_LICENSE_FILE." This is the full path to your RiverWare license file "cadswes.lic."

$ setenv RW_LICENSE_FILE /usr/local/RiverWare/license/cadswes.lic

Change to the directory which contains all of the license manager programs.

$ cd /usr/local/RiverWare/license

Start the main license manager daemon.

$ ./lmgrd -c $RW_LICENSE_FILE -l rw-lm-debug.log

Stop the main license manager daemon.

$ ./lmutil lmdown -q -c $RW_LICENSE_FILE -cadswes

Starting License Server Using the "rwlicense.rc" Script

The instructions below describe how to start and stop the license manager daemons by using the script provided by CADSWES. All of the necessary programs for running license managed RiverWare are placed in a subdirectory named "license" from where you have installed RiverWare.

Examples in this section assume you are running the C-shell; the exact commands will vary for other shells. They also assume that your environment variable "RIVERWARE_HOME" is set to "/usr/local/RiverWare" and all of the licensing programs are in the directory "/usr/local/RiverWare/license."

Each command example in this section starts with a command prompt "$" which represents an Unix command.

This script is provided by CADSWES to simplify the procedure of starting or stopping your license manager daemon.

Variable "RIVERWARE_HOME" must be set in your environment prior to running this script. It is the full path to the directory where you have installed RiverWare.

Make sure the required environment variable, "RIVERWARE_HOME", is set.
For example, if you have installed RiverWare in /usr/local/RiverWare, type the following commands from your command prompt to set this variable in your environment:

$ setenv RIVERWARE_HOME /usr/local/RiverWare

Change to the directory which contains all of the licencse manager programs.

$ cd /usr/local/RiverWare/license

Start the license manager daemon.

$ sh ./rwlicense.rc -start

Stop the license manager daemon.

$ sh ./rwlicense.rc -stop

Starting the License Server Automatically

Your systems administrator needs to set it up if you want to get the license manager daemon to restart automatically each time your system reboots (if the license type you have requires a license server). Following are a few things your administrator should keep in mind:

Create a script in "/etc/rc2.d" directory following the naming conventions of other startup scripts. For example, a script could be called "S95licmanager." The "S" denotes that the script is a startup script, and the number "95" indicates the order in which scripts are run.

For security reasons, the license manager daemon is best not run as "root." The UNIX "su" command can be used to run the script as a lesser privileged user.

Following are the contents of a sample boot startup script. In this example, RiverWare has been installed in "/usr/local/RiverWare" and the licensing related files and programs are in the subdirectory named "license."

---------------------------------------------------------------------------
RIVERWARE_HOME=/usr/local/RiverWare
RW_LIC_DIR=$RIVERWARE_HOME/license
RW_LIC_FILE=$RW_LIC_DIR/cadswes.lic
export RIVERWARE_HOME RW_LIC_DIR RW_LIC_FILE
/bin/su jhl -c "$RW_LIC_DIR/lmgrd -c $RW_LIC_FILE -l $RW_LIC_DIR/lmgrd.log"
---------------------------------------------------------------------------

Getting Information About License Activities

Globetrotter Software provides a utility in the FLEXlm software to help manage licensing activities on the network. This license administration tool is included in each RiverWare release (in the directory "license" from where you have installed RiverWare). It requires an active license manager daemon "lmgrd." (Refer to section Starting License Server from the Command Line or Starting License Server Using the rwlicense.rc Script for instructions.)

The following command allows you to monitor the status of all network licensing activities. It displays the RiverWare license server name, total available RiverWare licenses, RiverWare license type, and who is currently running RiverWare.

$ lmutil lmstat -a

5.0 License for Windows Platform

5.1 License File Location and Components

The RiverWare license file "cadswes.lic" must be stored in the same directory from where you have installed RiverWare. Normally you use the same license file for all of the RiverWare releases (until the license expires). Therefore we recommend you to save a copy of the license file to another location (in case you lose it when re-installing RiverWare).

By default, RiverWare searches license file using the value(s) of "CADSWES_LICENSE_FILE" recorded in the registry. If RiverWare cannot find the license file, a dialog is presented to user asking for the license file location (for node-locked license), or the name of the system running the license server (for floating license).

Windows version of RiverWare contains six license management components:

License manager daemon - lmgrd.exe

"lmgrd.exe" is the main daemon program for managing the licenses of RiverWare. The daemon handles the initial contact with RiverWare, passing the connection on to the CADSWES daemon "cadswes". It also starts and restarts the CADSWES daemon. You do not need this daemon program if the type of the RiverWare license you have is "Uncounted Node-Locked License.

CADSWES license daemon - cadswes.exe
"cadswes.exe" is the CADSWES daemon that keeps track of how many RiverWare licenses are checked out and who has them. If this daemon terminates for any reason, all users lose their licenses. This license daemon is started and stopped automatically by license manager daemon "lmgr." Users normally regain their license automatically when license manager daemon "lmgrd" restarts the CADSWES daemon.

License manager configuration file - cadswes.lic

"cadswes.lic" file is a text file which stores the licensing data for a specific RiverWare user site. It is created and distributed to each site by CADSWES. It contains information about the license manager for RiverWare at the user site, the CADSWES daemon, and the RiverWare product licensed by CADSWES.

License administration tool - lmutil.exe

"lmutil.exe" is a command line utility program provided by Globetrotter Software to help manage the licensing activities on the network. It contains eleven individual utilities and can be run as following:

$ lmutil <utility-name>

License administration tool - lmtools.exe

"lmtools.exe" is a utility program with graphical user interactive interface provided by Globetrotter Software to help managing the licensing activities on the network.

License Manager User's Guide - license_guide.txt

This document. This document is available in the subdirectory "license" from where you have installed RiverWare.

5.2 Node-Locked License

Following are the instructions for starting the RiverWare Windows version using your node-locked license:

Save the "cadswes.lic" file to the subdirectory "license" from where you have installed RiverWare. This file should be saved exactly as it is delivered to you without any modifications.

The first time you start RiverWare after the installation, you will be asked to enter the RiverWare license file location.

Log on to the machine as a user with the "administrator" privileges.

Start RiverWare.

From the "FLEXlm License Finder" window, choose the "Specify the License File" option and then click on the "Next" button.

Use the browse button to select your "cadswes.lic" file and then click on the "Next" button.

Click on the "Finish" button.

When the license file is successfully located, RiverWare application will start running.

If RiverWare encounters any problems when trying to access a license file, a window will show up and display an error message. Please save the error messages and email it to CADSWES for debugging.

5.3 Floating License

Floating license requires a running license manager daemon "lmgrd.exe" and the CADSWES daemon "cadswes.exe." These two files are included in the subdirectory "license" from where you have installed RiverWare. These two license manager daemons must be started, or stopped and then re-started, in the following two cases:

The first time after the RiverWare application and the RiverWare floating license file (the cadswes.lic) were installed. In this case, the new processes of license manager daemons must be started.

After a "new" RiverWare floating license file was installed. Normally this means the installation of a renewal floating license.
In this case, the currently running license manager daemons (which are running using the old RiverWare floating license file) must be stopped first and then the new processes of license manager daemons must be started using the new RiverWare floating license file.

Re-starting the license manager daemons is not necessary when a new release of RiverWare is installed, as long as the license file is still valid and the location of the license file has not been changed. It is only required when a new RiverWare floating license file needs to be used to run RiverWare.
Configuring and Starting the License Server
Following are the instructions for configuring and starting the license server on your machine (the host name listed in your floating license file):

To configure a license server as a service, you must have Administrator privileges.

Save the RiverWare floating license file "cadswes.lic" to the directory where you have installed RiverWare.

Run "lmtools.exe". It is in the directory "license" from where you have installed RiverWare.

Click the Config Services tab.

In the Service Name, type the name of the service that you want to define; for example, RiverWare Floating License.

In the Path to the "lmgrd.exe" file field, enter or browse to the "lmgrd.exe" in the directory "license" from where you have installed RiverWare.

In the Path to the license file field, enter or browse to the RiverWare floating license file "cadswes.lic" you have saved in the directory where you have installed RiverWare.

In the Path to the debug log file field, enter or browse to the debug log file that this license server writes. We recommend that this file be saved in the same directory where you have installed RiverWare. You can name it anything you want.

To make this license server a Windows service, click in the Use Services check box.

Click next to Start Server at the Power Up check box so that the license service will start on boot time.

To save this configuration, click the Save Service button.

To start the license server, click the Start/Stop/Reread tab. You should see the service name (RiverWare Floating License) you just created displayed in the Service list. Select this service and click Start Server button. In the lower status bar, you will see the message "Services started successfully."

To verify the running status of the license server you just started, click the Server Status tab. Click the Display Everything button and then click the Perform Status Enquiry button. You should see a status report similar to the following in the output window (where server_name is the machine name listed in your license file):

**********************************************************
* --------
* Status
* --------
* Flexible License Manager status on Tue 3/5/2002 11:12
*
* [Detecting lmgrd processes...]
* License server status: 27000@server_name
* License file(s) on server_name: C:\Program Files\
* CADSWES\RiverWare 4.0.4\cadswes.lic:
*
* server_name: license server UP (MASTER) v8.1
*
* Vendor daemon status (on server_name):
*
* cadswes: UP v8.1
*
* Feature usage info:
*
* Users of riverware: (Total of 5 licenses available)
*
**********************************************************

Starting RiverWare and Setting the License Path

Following are the instructions for starting the RiverWare Windows version using your floating license:

Starting RiverWare the first time after the installation requires administrator privileges in order to update the license information in the registry.

If RiverWare has been installed on this machine before, the following steps are required in order to clean up the RiverWare license environment variable recorded in the registry database.

Start a Registry Editor. This can be done by selecting Start -> Run and then entering "regedit" in the Run window.

In the Registry Editor, click HKEY_LOCAL_MACHINE -> SOFTWARE -> FLEXlm License Manager.

Delete the variable "CADSWES_LICENSE_FILE" and then close the Registry Editor.

Start RiverWare. When you are installing RiverWare on a machine that already has a RiverWare installed, you will get a Setup Maintenance Program window. Select "Remove - Remove all installed features" to uninstall the previously installed RiverWare on the machine. Then re-run the RiverWare install program to install the new release.

You will be presented with a dialog that asks for the license file location. Click on Specify the License Server button in the FLEXlm License Finder dialog and then click Next.

Enter the machine name (the name of the machine that you just configured for running RiverWare license server) in the input box. Click Next and then click Finish.

RiverWare will start when the license server is successfully connected. The path to the RiverWare license server will also be recorded in the registry. Therefore, you will not be asked to enter the license information when you start RiverWare on this machine the next time.

If RiverWare encounters any problems when trying to access a license server or a license file, a window will show up and display an error message. Please save the error messages and email it to CADSWES for debugging.

Getting Information About License Activities

The GUI utility program "lmtools.exe" also provide the feature for getting system information and license activities.

Run "lmtools.exe". It is in the directory "license" where RiverWare is installed.

Click the Server Status tab. Click the Display Everything button and then click the Perform Status Enquiry button. The status report is displayed in the output window.

CADSWES - Center for Advanced Decision Support for Water and Environmental Systems
cadswes.colorado.edu -- edit September 8, 2005 -- e-mail webmaster

Overview People Visitor Information Related Websites

Journal Articles Conference Papers Books / Chapters M.S. & Ph.D. Theses

About HDB User Access Documentation

About RiverWare Licensing Training User Group Publications User Access

Contents: