A Detailed Licensing Information

Installing AVS/Express

A Detailed Licensing Information

The license server

Licenses that are use-limited require the use of a license server. The AVS license server is a fairly small Java-based program. It can be run on any machine that supports Java. The license server uses the Java logging API so it needs Java 1.4 or later. The license server software is totally independent of AVS/Express. AVS/Express does not have to be installed on the machine hosting the license server. However, the machines that are used to run AVS/Express must be able to make a TCP connection to the machine running the license server. This may present an issue if the license server machine and the AVS/Express client machine are separated by a firewall.

The license server itself is node locked to prevent running the license server on multiple machines. The port number is part of the license so that customers can choose their port if they want, but they are prevented from running multiple copies of the server on one machine using different port numbers. The default port number is 33333, but a different port number can be chosen when the license server license is generated.

The options for specifying the server hostid are similar, but not exactly the same, as with regular node locked AVS/Express licenses. None of the wildcard options for supporting a range of network addresses or all the hosts in a domain are supported. Using a standard Internet Address (IP4) is supported on all platforms. (The platform is the machine running the server software, which could be totally different from the machines running AVS/Express.) Using a MAC address or ethernet address is supported on Windows, Linux, and Mac OS X. Using the Volume Serial Number is supported on Windows.

The license file also contains a license for each "product" for the clients to use. The "LIMIT" keyword shows how many clients are allowed for each product. AVS/Express Developer's Edition, AVS/Express Visualization Edition, and AVS/Express runtimes all count as different products, so you can have different limits for each one. Along with a "HOSTID" keyword, a client license contains a "SERVID" keyword that specifies the server. Restrictions on which client can check out the floating license are dependent on the value of "HOSTID". For example, if hostid in the license is 0, then there are no restrictions on which client machine can use the license.

The way the license server works is that a TCP connection is opened between AVS/Express and the license server, and then AVS/Express downloads a license from the license server and the license is validated by AVS/Express. Every few minutes AVS/Express sends a small "heartbeat" message to the server to help determine if the connection is still active. TCP itself can do most of the work in determining whether or not either end of the connection has died unexpectedly. If the license server dies, AVS/Express will attempt to reestablish the connection. AVS/Express will exit if it can't reestablish the connection after 30 minutes. If AVS/Express dies, usually the license server will be able to detect that the connection has been broken and reclaim the license for reuse. In the (hopefully) unusual circumstance that the client dies without the server noticing, a "reaper" thread in the server will test for and close connections that have not seen activity for the last two hours.
The following shows an example license.dat file for a license server. The first license line is for the license server itself. The license server is node locked to the server machine.
The second license line is for the AVS/Express clients. The HOSTID of the client license uses network syntax, so it works on any machine on the local network. If the client HOSTID was 0, then it could be used from any machine that could make a TCP connection with the license server. A HOSTID 0 may be necessary to support mobile or remote users with changing IP addresses. The SERVID of the client license must match the HOSTID of the license server.
# License Server license. Node locked to one host.

AVS LICVER=1 PRODUCT=LICSERV DATE=30-dec-2005 HOSTID=192.138.23.163 PORT=33333 
CUSTID=AVSInc PASSWD=dc1981c9dd1261648db72c90518c2a4e



# Floating client license. Two users anywhere on the local network

AVS LICVER=1 PRODUCT=EXPRESS LIMIT=2 DATE=30-dec-2005 HOSTID=192.138.23.00/24 
SERVID=192.138.23.163 CUSTID=AVSInc PASSWD:4aacd9d6c8d21663cf39a68458f50170


 
Running the license server

You start the license server using a command like the following:
java -cp LmServer.jar com.avs.LmServer license.dat 
 
You can also use the slightly shorter syntax:
java -jar LmServer.jar license.dat
 
The last argument ("license.dat") is the name of the file that holds the license keys. It can be 
any filename you want. As mentioned in a previous section, it must be a plain text file without 
any word processor markup. The example assumes that the license file is in the same directory 
as the jar file, but there are no restrictions on the location as long as you correctly specify the 
file pathnames. The following will work as long as the directory names are accurate.
 
java -jar directory1\LmServer.jar directory2\license.dat 
 
The previous examples assume that the java executable is in your PATH. Here is another 
example showing explicitly specifying the location of the java executable
 
C:\Java\j2sdk1.4.2\jre\bin\java -jar lm\LmServer.jar lm\license.dat
 
You should see output like the following when it starts up. 
 
2004 Dec 8 13:27:8 LM Server starting on DeerIsle (192.138.253.162)                 
2004 Dec 8 13:27:8 LM Server Reading license file license.dat                        
2004 Dec 8 13:27:8 LM Server adding 2 licenses for EXPRESS                            
2004 Dec 8 13:27:8 LM Server adding 3 licenses for EXPRESS_VIZ                       
2004 Dec 8 13:27:8 LM Server adding 4 licenses for EXPRESS_RT                        
2004 Dec 8 13:27:8 LM Server listening on port 33333                                  
2004 Dec 8 13:27:8 LM Reaper thread starting
 
On the client (AVS/Express) side, you simply have to set a single environment variable before starting AVS/Express. The following example uses Windows command shell syntax.
set XP_LICENSE_SERVER=deerisle.avs.com:33333 
 
You can change the port, but only after getting a new license server license.

License Server status queries

The license server contains minimal web werver functionality that is used to support accessing status information from any web browser. Two types of status queries are supported. Just use the URL of the license server to access the psuedo-file "STATUS" or the pseudo-file "LOG", and the server will return a small HTML page with the requested information. "STATUS" returns a page indicating how many licenses are in use and which machines are using them. For example:
http://deerisle.avs.com:33333/STATUS
 
"LOG" returns a page that contains timestamped messages from the server. There will be a record for every client connect and disconnect. A maximum of 500 log records is kept in order to limit memory usage for long-running servers. For example:

http://deerisle.avs.com:33333/LOG

License Server and node locked licenses

The primary use of the license server is to managed use-limited (floating) licenses, but some customers may find it convenient to use the license manager to control a site license or a pool of node locked licenses. If the license file contains no use-limited licenses, then no license server license is needed and there are no restrictions on running the server on multiple machines. There is no difference in how to run the license server, although some of the messages printed by the server will reflect that it is not trying to count license usage.

2004 Dec 16 17:40:40 LM Server starting on DeerIsle (192.138.23.163) 2004 Dec 16 17:40:40 LM Server Reading license file license.dat 2004 Dec 16 17:40:40 LM Server adding unlimited-use license for EXPRESS 2004 Dec 16 17:40:40 LM Server adding unlimited-use license for EXPRESS_VIZ 2004 Dec 16 17:40:40 LM Server listening on port 33333 2004 Dec 16 17:40:40 LM Reaper thread starting

On the client (AVS/Express) side, there is no difference from the case where the license server is used to control floating licenses. You just set XP_LICENSE_SERVER as before.
set XP_LICENSE_SERVER=deerisle.avs.com:33333
 
License Server limitations

The license server has two primary limitations in the mix of licenses that it can manage.

For a given product (e.g. "EXPRESS_VIZ"), it can mange only one use-limited license,

For a given product, it can manage either a use-limited license or unlimited-use licenses, but not both.

Note again that these limitations are per-product.
Here is an example of a combination that is allowed:

One node locked license for Developers Edition ("PRODUCT=EXPRESS")
Five floating licenses for Visualization Edition ("PRODUCT=EXPRESS_VIZ")
Ten floating licenses for Runtimes ("PRODUCT=EXPRESS_RT")

Here is an example of a combination that is not allowed.

Two node locked licenses for Visualization Edition ("PRODUCT=EXPRESS_VIZ")
Five floating licenses for Visualization Edition ("PRODUCT=EXPRESS_VIZ")

License Server as a Windows Service

There are a number of available solutions for turning the Java-based license server into a Windows Service that can be started and stopped using the Management Console. The license server is not a particulary demanding application and it requires no special procedures for starting it and stopping it.

Thus a number of off-the-shelf solutions will work. The following procedure is based on the freely available Java Service Wrapper from Tanuki Software.

The home page of the Java Service Wrapper project is http://wrapper.tanukisoftware.org. Downloads can be found on the following page on SourceForge.net: http://sourceforge.net/project/showfiles.php?group_id=39428. Download the Win32 version and unzip it. Copy the following four files to the same directory where you are keeping LmServer.jar and your license file.
WRAPPER_DIR/bin/Wrapper.exe                          WRAPPER_DIR/lib/wrapper.dll                         
WRAPPER_DIR/lib/wrapper.jar                       WRAPPER_DIR/src/conf/wrapper.conf
 
You now need to edit the wrapper.conf file. The following shows only the lines that are changed. It is not actually a requirement that all the files be placed in the same directory, but you will need to change some of the file paths shown below to match the directories you use.
wrapper.java.classpath.1=wrapper.jar wrapper.java.classpath.2=LmServer.jar           
wrapper.java.library.path.1=. wrapper.app.parameter.1=com.avs.LmServer 
wrapper.app.parameter.2=license.dat               wrapper.logfile=wrapper.log                              
wrapper.console.title=AVS License Manager               wrapper.ntservice.name=AVSLM                      
wrapper.ntservice.displayname=AVS License Manager                       
wrapper.ntservice.description=AVS License Manager for AVS/Express
 
Once you have edited the wrapper.conf file, you are ready to install and start the service. This assumes that the main "java" executable is in your PATH and you are able to start the license server by hand as shown in the previous section

Install the Service:
Wrapper -i wrapper.conf
 
Run the Service: (or use the Management Console)
Wrapper -c wrapper.conf
 
Uninstall the Service:
Wrapper -r wrapper.conf
 
Format of the license file

Earlier formats

Generation 1 licenses

The first generation of the non-FLEXlm licensing system was introduced in AVS/Express 5.1 for Linux and was used though AVS/Express 6.0 for Linux. These licenses were nothing but a 11 character password string. It contained no date information and no "plain text" information at all. Support for this 76style of license have been removed from AVS/Express.

Generation 2 licenses

Starting with AVS/Express 6.1 and continuing through AVS/Express 6.3, the license format was expanded slightly to allow for an expiration date. The new format had a date and then the 11 character password string. Multiple licenses were allowed in one file and blank lines and comment lines starting with '#' were skipped. The following shows an example.
# Example license file.

20-jun-2004 ABCDEFGHIJK
 
AVS/Express 7.0 format

AVS/Express 7.0 introduces a new license file format that has considerably more complex than the old system. These are sometimes called Generation 3 licenses, although that term is only used to help distinguish them from the older style of licenses discussed above. The G3 licenses support many more licensing options and features than the previous generation licenses and have the further advantage that all the information is in plain-text.

Here is an example license (all on one line).
AVS LICVER=1 PRODUCT=EXPRESS DATE=30-nov-2004 HOSTID=192.138.235.67 CUSTID=AVSInc 
PASSWD=6fed4ffc5eb83daf1544bcc905f9a293
 
The license has multiple fields, which are separated by whitespace (either tabs or spaces). With the exception of the leading "AVS", all the fields are of the form of keyword=value pairs. The license can be split into several lines by using a backslash as a continuation character. The following is the exact same license as shown above.
AVS LICVER=1 PRODUCT=EXPRESS DATE=30-nov-2004 \ HOSTID=192.138.253.162 
CUSTID=AVSInc \ PASSWD=6fed4ffc5eb83daf1544bcc905f9a293
 
The following gives details on what each field means.

LICVER: License Version. Currently fixed at 1.

PROD: Product Name.

EXPRESS for Developers Edition.
EXPRESS_VIZ, for Visualization Edition.
EXPRESS_RT, for a Runtime.
LICSERV, for the license server.

DATE: Expiration date.

No date or a date with year 0000 or 1900 means never expire.

HOSTID: Host Identification.

This is the most complex field. There are several different ways of specifying the host id.
1] Internet Address - should be 4 decimal numbers each in the range 0-255, separated by dots. Example 128.10.22.32. Do not use 127.0.0.1 as that is the special loopback address.
2] Internet Network Address - Similar to a Internet Address, but it has an extra parameter that allows distinguishing between the network address and the specific host address. The syntax is a forward slash then a number that give the number of bits in the network. For example, the address 128.10.22.00/24 specifies that the first 24 bits of the address (128.10.22) are for the network. The license is valid for any host on the network.

3]Internet Hostname or Domainname - Use the familiar dot notation to specify a hostname (e.g. foo.avs.com). Specify an entire domain (e.g. avs.com) by leaving off the hostname. The license is valid for evey host in the domain
4]Ethernet or MAC Address - should be 6 hex numbers, each 2 digits long, separated by colons. Example 00:12:34:45:78:9A. MAC stands for Media Access Control, it is a generalization of the idea of an ethernet address. Currently, Ethernet/MAC address are supported on Windows, Linux and Darwin only. On Windows, NetBIOS must be installed and enabled on the machine to reliably get the MAC address.
5] Windows Volume Serial Number - The Volume Serial Number of the C drive. Supported on Windows only. Should be 4 hex characters, a dash and 4 more hex characters. Example C123-B456
6] Unix hostid - Output of the Unix 'hostid' command. Should be eight hex characters. 0 means any host. 0 can also be used on Windows.

SERVID: Server Identification

Very similar to the hostid, although it has to be for a single host. Internet network addresses (case 2, above) and internet domain names are not allowed.

CUSTID: Customer Site Id.

Any string 31 characters or less in length that uniquely identifies the customer. Quotes can be used to put spaces in the Customer Id.

PASSWD: Checksum/Password

License checksum that consists of 32 hex digits.

LIMIT: This specifies the number of copies that are allowed be run at once.

When a limit is specified, then using a license server is required.

PORT: TCP port.

Used only for license server licenses. It specifies the TCP port that is used to communicate between the license server and AVS/Express. AVS/Express must use a matching port as controlled by the XP_LICENSE_SERVER environment variable. If omitted, it defaults to 33333.

FEATURES: Extra features (not shown above in example)

This is optional and can be omitted. Each product has a default set of abilities or "features". The feature flags enables fine-tuning of the allowed features for each license if necessary. For example, a standard feature of Developers Edition is that it can be used to generate runtimes. A feature flag could be use to disable this ability in Developers Edition or enable it in Visualization Edition.