Tweak License Server (tlm_server) Version 2.6

Audience

The License Server should be installed by a System Administrator or someone who is knowledgeable about how system processes work on your platform.

Overview

The Tweak License Server is capable of managing an arbitrary number of applications purchased from Tweak Software. If a network connection exists between a client and the server, and a valid license matching the client software is present, the server will grant the client permission to run the desired application. Managing license count, type, and function is all done transparently to the user. The Tweak License Server is most commonly run as a system service, but can also be run explicitly as a foreground or background process.

Recommended Installation Process

You’ll find platform specific notes on installing tlm_server as a daemon or service below. But we recommend that you first follow these steps to getting the server working:

Install the server by unpacking the package into a suitable directory (On OS X, run the installer - see below). Note that the server must run on a machine with a MAC address (host ID) that corresponds to that in the licenses that it will serve.
Run tlm_server from the command line with the -fg flag and no -log flag, like this:
```
tlm_server -fg -f <my_license_file>.gto
```
(Note: on windows you must use the .exe extension, or tlm_server will not run. On OSX the installer puts the tlm_server executable in /Applications/Utilities/tlm_server/bin.)

You should see something like this
```
Tweak License Server
Started: Fri Feb 26 15:17:41 2010
tlm_server running on host 'myhost' port 5436
Version: 2.6.0

License 1: rvsolo 3.*.* :: 0 in use, 5 available, 5 total
License 2: rvio 3.*.* :: 0 in use, 5 available, 5 total
```
Run RV or RVIO clients and watch the output from tlm_server. You should see licenses being APPROVED and RELEASED. (You may also see some rejections during normal operation, since RV tries to used the “least desirable” (IE least expensive) license types first.

Note that RV needs to know how to contact the license server. If you are running RV for the first time, it’ll start the license installer and you can use the Set License Server button at the bottom. Or you can install a site-wide or per-machine client license as described below in the Client Licenses section
If everything looks good, kill the running server (ctrl-C) and start a new server as a daemon (in the background), with logging:
```
tlm_server -f <my_license_file>.gto -log <my_log_file>
```
(Note: on windows you must use the .exe extension, or tlm_server will not run.)

The server process will print Running in background ... and you can then close the terminal in which you started tlm_server.
At this point the server is fully functional, and you can just check the tlm_server log file periodically to make sure that things are working as you expect. But eventually you’ll probably want to install the server so that it starts automatically when the server machine reboots. As this process is very platform-dependent please refer to the appropriate following section.

Linux Service Installation

Note: The service command mentioned below is common on linux dists derived from RedHat or Fedora, like CentOS. On others, such as Debian or Ubuntu, you may need to install the sysvconfig package.

Edit/Review the installation script (install_tlmserver). The installation should be edited (or just checked) to make sure it makes sense with your Linux system. By default it will install a script that calls the license server binary as a system service. If you did not install the package in /usr/local/tweak you will need to change the variables at the top of the file.
Edit/Review the start_tlmserver_init.sh script. Check the command line parameters below and make sure the start script is pointing at the correct place for the license file (for example). Note that if you rename this script when you install it in the init directory, be sure that the string "tlm_server" is not in the name, since tlm_server will refuse to run if there is any other process running with "tlm_server" in the name.
Run the installer script (or install by hand). The script should be run from the directory it lives in.
Start the Server. Use the service command to start the Server like this: "service start_tlmserver start", or "/etc/init.d/start_tlmserver start" if you’re not using the service interface.
On reboot the server should start automatically.

We test our license server internally on Ubuntu 8.04. tlm_server may run on other flavors of Linux. If you are not running a Debian or Red Hat derived distribution, we can work with you to get it installed.

Network Timeouts on Linux

If RV exits for any reason, the licenses should be released immediately. If the server looses contact with machine running RV (for example, if network service to that machine is interrupted), the connection will time out and the the license will be released in 2-3 minutes.

OS X Service Installation

The OS X installer installs the server binaries into /Applications/Utilities/tlm_server and creates a startup item in /Library/StartupItems. Before the server can successfully approve license requests from applications, it must find a valid license file in one of these locations:

/Applications/Utilities/tlm_server/etc/license.gto
/Library/Application Support/RV/license.gto
/Library/Application Support/TLM/license.gto
/var/tweak/license.gto

So during a first install, we advise that you first go through the Recommended Installation Process as described above. To run the command line examples above, use the server executable in /Applications/Utilities/tlm_server/bin/tlm_server.

After you’ve confirmed that the server works as expected, install a license file in one of the above locations and restart the server like this:

sudo /Library/StartupItems/TLMServer/TLMServer start

Once the server is running, ps will show you a command line that looks something like this:

tlm_server -f /Applications/Utilities/tlm_server/etc/license.gto -log /var/log/tlm_server.log

And you can monitor the behavior of the license server in the log file /var/log/tlm_server.log.

Network Timeouts on OS X

% sysctl -A |& grep net.inet.tcpkeep
net.inet.tcp.keepidle: 7200000
net.inet.tcp.keepintvl: 75000

The values shown here are typical, and will cause the license to be released in about 130 minutes. This should be fine in many cases, but if you want the license to be released sooner, you can

sudo sysctl -w net.inet.tcp.keepidle=60000
sudo sysctl -w net.inet.tcp.keepintvl=60000

This will cause the timeout and license release to happen after about 10 minutes. These numbers will be reset at the next system restart. To make them permanent, add these lines to the file /etc/sysctl.conf.

net.inet.tcp.keepidle=60000
net.inet.tcp.keepintvl=60000

Windows Service Installation

After you’ve installed the the server and confirmed that it works as you expect, you probably want to make a Windows Service from the tlm_server executable.

On all versions of windows, we recommend Ian Patterson’s "Non-Sucking Service Manager", available here.

Here are the steps (as Administrator):

Unpack tlm_server zip somewhere (c:\tlm_server-win32-x86-2.6.0 in what follows)
Download and install NSSM somewhere (c:\nssm-2-5 in what follows)
Create the service:
```
c:\nssm-2.5\win64\nssm.exe install TLM "c:\Program Files\tlm_server-win32-x86-2.6.0\bin\tlm_server.exe" "-log
\"c:\Program Files\tlm_server-win32-x86-2.6.0\log\" -f \"c:\Program Files\tlm_server-win32-x86-2.6.0\etc\license.gto\""
```
You should see "Service TLM installed successfully!". Please Note:
- The entire command above must be typed on a single line.
- You need those double quotes and you need the escaped double quotes too if your paths have spaces in them.
- Don’t forget to swap in the path to your actual log file and license file.
Now you can start the service explictly with the windows adminstrative tool "Services", or just reboot.

If anything goes wrong and you need to uninstall the service, you can:

Stop the service with the windows admin tools "Services".

Remove the service with NSSM:

c:\nssm-2.5\win64\nssm.exe remove TLM confirm

Network Timeouts on Windows

Getting a License File

The Tweak License Server requires a license file generated by Tweak Software in order to operate. The license will be keyed to the hostID of the machine the server is running on. The procedure for getting a license is:

Find the local Hardware ID (MAC address). There are a number of ways to obtain a Hardware Address for the machine you would like to host the Tweak License Server. The license server package contains a program called tlm_hostid that will list valid Hardware IDs. The best choice is the ID from a system component, like an on-board NIC used for et0. On a linux machine, the command /sbin/ifconfig passed with the parameter of the machine’s net- work card (eth0) will yield the HWaddr. On OS X, ifconfig will also work - or you use the Network Preferences to find the Ethernet ID. The Hardware ID should look something like this: 00:E0:81:25:C8:82.

Note that on many systems there will be several IDs since there are several network interfaces. In these cases any one of them should work.
Email the Hardware ID to Tweak.
Install the License File. The tweak license file can reside anywhere the License Server host can see. It may be easiest to place it in the same directory.

Command Line Parameters

-f: The path to the local license file. This can be relative to the Tweak License Server install directory, but an absolute path is safest.
-log: The path to the License Server log file. The license server can maintain a log of all its activity. Passing a filename to this parameter allows the information to be stored locally on the host machine. If no -log option is specified, the server prints to the standard output.
-fg: Runs the server in the foreground. If this parameter is not specified the server runs as a daemon or service.
-s: Shows the status of a currently running server. Lists the version/compile information for the running server, and lists each user who currently has a license checked out. To get the status from a remote machine You need to supply -h and -p options. The process will contact the other server and get a list of the available licenses and who is currently using them. Status information also contains expiration date and maintenance expiration date for licenses that have them.
-q: Contacts a running license server and requests it to shutdown. To shut down a remote server, you need to supply -h and -p options with the -q option.
-h: Specifies the host where the server will be run from. This defaults to localhost, and will only change in rare occasions. Also used with -s and -q options to contact a remote server.
-p: Specifies the port on which the local server will listen for incoming license requests. This defaults to port 5436. This is required with the -s and -q options. Note that on Windows the port can only be 5436.
-help: Prints out command line help.
-version: Show version.

Disabling the License Installer

By default, when RV cannot get a license, it will start the Tweak License Installer and prompt the user to install one. If you’re using the license server, you probably don’t want just anyone installing licenses, so you can disable this behavior by setting the environment variable TWEAK_NO_LIC_INSTALLER in the global environment.

Client Licenses

As noted above, the Tweak License Server requires a license file to be installed locally. Client processes (RV, RVIO, etc) each require their own license file that points to the server. This file can be stored on the network where the package is installed (one copy of the file for all clients) or locally on each machine (one copy per machine), and should look something like the following:

GTOa (3)

server : ServerLicense (1)
{
    id
    {
        string hostname = "servername"
        int port = 5436
    }
}

The hostname field is the address of the machine running the license server. The port field should match the port specified when running the License Server on the host.

Multiple and Fallback Servers

If you have multiple sets of licenses — for example two licenses each of which allows 10 copies to be checked out — you may want to run them on different servers. To specify multiple servers in a client file:

GTOa (3)

server1 : ServerLicense (1)
{
    id
    {
        string hostname = "servername1"
        int port = 5436
    }
}

server2 : ServerLicense (1)
{
    id
    {
        string hostname = "servername2"
        int port = 5436
    }
}

If the first server is unavailable or does not have any licenses left the client will attempt to contact the second server to obtain a license.

Getting Status

You can get the status of a running license server on an remote machine (or the local machine) by running another copy of tlm_server using the -s option:

shell> tlm_server -s -h hostmachine -p portnum
asking for status, hostmachine, portnum

RESPONSE: tlm_server running on host 'hostmachine' port portnum
Version: 2.6.0

License 1: rv *.*.* :: 1 in use, 0 available, 1 total, maint expires Sat Jun 16 12:13:00 2010
     -> alan@127.0.0.1 checked out at Sat Feb 27 16:15:40 2010

Status information includes, for each license, the users who currently have the license checked out, the number of available seats, and licenses expiration and maintenance expiration dates, if applicable.

Restrictions/Troubleshooting

There are a few restrictions which will prevent the server from running, or from serving a particular license:

The server will not accept a license whose host ID (MAC address) does not match any available host IDs on the server machine. Starting tlm_server in the foreground, with the -fg flag, will report errors related to the license file and enumerate valid host IDs.
```
shel>> tlm_server -f bad.gto -fg
LICENSE FAILURE: 00:11:22:33:44:55 not found on this machine
HOSTID #0 = 00:E0:81:57:3F:58
HOSTID #1 = 00:E0:81:57:3F:59
HOSTID #2 = 00:50:56:C0:00:08
HOSTID #3 = 00:50:56:C0:00:01
LICENSE FAILURE: Ignoring modified license 4be52c90ee74321999ca981db5affc5d7ed3d083
ERROR: license file contained no useful licenses or servers
Error reading bad.gto...
```
The server installation contains a program, tlm_hostid, that will list valid host IDs, and more information on finding the right host ID can be found in an article on the Tweak website.
Sometimes the license file has been corrupted by email or some other process. We usually send licenses as text files, since many facilities have email filters set up to reject zip files. If the file is corrupted (meaning extra characters are inserted into it) then you will get an error stating that this is "Not a Valid GTO file." If you have this problem, you can request a new license and we will send you a zipped version.
The name of the binary must be “tlm_server” (“tlm_server.exe” on Windows). Renamed binaries will not function.
You can only run one copy of tlm_server on a given machine.
tlm_server does not accept version 1 license files. The version is indicated by a number at the end of the license object. These licenses will work when used with the client as a node-locked licenses. tlm_server v2.4 accepts version 2 and 3 licenses.
```
GTOa (3)

832b961633628232d4ef8d3060a1c10693af08af : license (1) # <--- (1) is the version
{
 .
 .
 .
}
```
tlm_server will run in parallel with an older version of the license server (tweakLicenseServer) as long as they are using different ports.

Once a server is running and hosting at least one valid license, if you have trouble trouble acquiring licenses, check the server log output. The server will give a reason in the log output for each rejected license request. Note that a correctly set up license server will still have many REJECTED notes in the log, since Tweak apps will try to acquire the “least desirable” (least expensive) license types first.

Reasons for rejecting a license request that you may see in the log include:

Package Name Mis-Match: The most common reason, since Tweak software asks for several packages in hopes of consuming the least desirable licenses first.
Version Mis-Match: This request is for a version of the package that this license does not support.
Maintenance Expired: The compile date of the package requesting a license exceeds the maintenance expiration date of the license (this date is labeled updatesUntil in the license file).
Start Date Not Reached: Licenses may have a startDate field which prevents their use until that date is reached.
License Count Exceeded: Granting this license request would push the number of concurrent users above the allowed limit for this license (this is the count field in the license file).

If you want to take the license manager completely out of the equation, and use a given license directly from RV or RVIO, you can install licenses manually by naming them correctly, and placing them in right directory:

Manual License setup: You can install licenses manually on all operating systems. Rename the license file to "license.gto" and the place in the correct directory. On Linux and Windows, there is a directory named etc that can be found under the main RV directory (wherever RV is installed). You can copy the license.gto file into that directory. On the Mac, the license file is stored in the directory: /Library/Application Support/RV

Anatomy of a Tweak License File

A license file can hold any number of licenses. The server will examine them all to determine which can satisfy the incoming request and if a currently checked-out licenses can be used to satisfy the request without consuming an additional license.

If more than one license in the file could satisfy the requests, the license consumed with be the latest in the file, so you can order the licenses in the file to determine the order of consumption.

GTOa (3)

048340189d06b475b271bd090dce56fd77827c7e : License (2) # License Name : File Version
{
    license
    {
        string package =  "rv"                  # Name of licensed software package
        string version =  "3.4.*"               # Version licensed
        string expires =  "29-Apr-2008"         # Expiration date, can be "permanent"
        string updatesUntil =  "25-Apr-2008"    # Expiration date for update rights
        int count =  1                          # Number of seats licensed
        string hostID =  "00:17:F2:CA:09:1A"    # Host ID
        string issued =  "15-Apr-2008"          # Issue date
        string reason =  "eval"                 # Reason for license
        string licensee =  "Facility Name"      # Optional field
        string email =  "contact@facility.com"  # Optional field
        string machine =  "servername"          # Optional field
        string os =  "any"                      # Operating System licensed
        string card =  "cardname"               # Optional field
    }
}

a79302764e96c74e0064d6a652000a54288e5abd : License (2)
{
    license
    {
        string replaces =  "048340189d06b475b271bd090dce56fd77827c7e"
                                                # License superseded by this one.
                                                # Replaced license must be present
                                                # in the file or tlm_server will fail
        string package =  "rv"
        string version =  "3.4.*"
        string expires =  "permanent"
        string updatesUntil =  "25-Apr-2009"
        int count =  1
        string hostID =  "00:17:F2:CA:09:1A"
        string issued =  "25-Apr-2008"
        string reason =  "commercial"
        string licensee =  "Facility Name"
        string email =  "contact@facility.com"
        string machine =  "servername"
        string os =  "any"
        string card =  "cardname"
    }
}