PHPLicensewatcher installation HOWTO


This document has been initially written by Glenn Zenker. It has been edited, revised and complemented by Vladimir Vuksan. If you have any recommendations, additions and changes please send me an e-mail to

vuksan-php@veus.hr

Document Index


Where can PHPLicensewatcher run

PHPlicensewatcher can run on any machine that has network access to your license server(s). FlexLM allows you to query license servers remotely. In most cases all you have to do is download FlexLM binaries for your platform. You can download binaries from http://www.macrovision.com/services/support/flexlm/lmgrd.shtml. Once you download the binaries you can query any FlexLM server regardless of the platform ie. our license servers run on Solaris, Linux and Windows and PHPlicensewatcher runs under Linux. To test whether you have the proper binaries execute


lmstat -c port@licenseserv.domain.com


You should get something like this


lmstat - Copyright (C) 1989-2001 Globetrotter Software, Inc.
Flexible License Manager status on Thu 12/5/2002 11:15

License server status: 27000@licenseserv
License file(s) on licenseserv: /licenses/license.dat:

licenserv: license server UP (MASTER) v8.0

Vendor daemon status (on licenseserv):

snpslmd: UP v6.1


If you don't you have a problem and PHPlicensewatcher will not work. Try to resolve it then continue reading this document.

If you have a database and Apache installed

If you already have a database and apache installed you will need to check whether you have everything that's necessary installed.

Create a PHP file somewhere on your web server with following line in it
<?php phpinfo(); ?>
View the page in your browser. You will get a long page with all of PHP settings. Third row in the table at the start should say "Configure Command" and under it something like this

 './configure' '--with-mysql' '--with-apxs' '--enable-track-vars' '--with-gd' '--enable-gd-imgstrttf' '--with-ttf' '--with-ldap' '--enable-gd-native-ttf' '--with-pgsql'

You will have to have at least these options
If this checks out  jump to creating databases

RedHat/Fedora Linux installation instructions

RedHat 9.x

This assumes you are installing Apache/PHP/MySQL from RedHat 8.0 CD/DVD

Install following packages
rpm -ivh /mnt/cdrom/RedHat/RPMS/httpd-*.i386.rpm
rpm -ivh /mnt/cdrom/RedHat/RPMS/php-mysql-*.i386.rpm
rpm -ivh /mnt/cdrom/RedHat/RPMS/php-pear-*.i386.rpm
rpm -ivh /mnt/cdrom/RedHat/RPMS/php-[4-5]*.i386.rpm
rpm -ivh /mnt/cdrom/RedHat/RPMS/mysql-[3-5]*.i386.rpm
rpm -ivh /mnt/cdrom/RedHat/RPMS/mysql-server-*.i386.rpm
You also need to install these two PEAR packages
pear install HTML_Common
pear install HTML_Table

Reboot or type
/etc/rc.d/init.d/httpd restart (restart since it may already be running)
/etc/rc.d/init.d/mysqld restart (restart since it may already be running)
/sbin/chkconfig httpd on
/sbin/chkconfig mysqld on
Now  jump to creating databases


Generic instructions

These are generic UNIX instructions ie. if you don't have MySQL, Apache or PHP installed. 

What you need:

<>

Basic Install Process

Compiling Apache

Get an Apache version from www.apache.org. These instructions assume Apache 1.3.x. When compiling apache, you need to compile it so it can use mod_so. This allows other modules to be loaded (php) when you start the httpd server.

./configure –enable-module=so && make

before you do a make install, you should be able to find the httpd in the ./src directory.

Run ./src/httpd -l

you should get a list that shows you all the modules...the one we are looking for the most is, mod_so.c. If that is there, we are good to go for now.

Compiling php4

When compiling php4, you need to have in your $PATH where apxs is installed. It should be under the $PREFIX/apache/bin/apxs. If you don't have this, go back and reinstall apache.

./configure –with-mysql=/usr/local/mysql –with-apxs --enable-track-vars --with-gd --enable-gd-imgstrttf --with-ttf' –with-ldap –enable-gd -native-ttf --with-pgsql && make && make install

Compiling mysql

I downloaded the binary for it and simply untar'd it in a directory. The binary is available for all platforms so you don't need to compile it.

http://dev.mysql.com/downloads/

One thing I did notice about the binary was when I tried to run ./bin/safe_mysqld –user=mysql it gave me an error about no libexec directory or var directory. After further review, the ./bin/safe_mysqld, which is a shell script, had some incorrect data. Simply edit safe_mysqld, and look for libexec and substitue it for bin, then look for var and substitue it for data.

To continue:

AS ROOT: (assuming you are installing in /usr/local)

This is documentation quoted directly from the INSTALL-BINARY by mysql.

groupadd mysql
useradd -g mysql mysql
cd /usr/local
gunzip < /path/to/mysql-VERSION-OS.tar.gz | tar xvf -
ln -s mysql-VERSION-OS mysql
cd mysql
scripts/mysql_install_db
chown -R root /usr/local/mysql
chown -R mysql /usr/local/mysql/data
chgrp -R mysql /usr/local/mysql
chown -R root /usr/local/mysql/bin
bin/safe_mysqld --user=mysql &
** my note ** Don't give the database a password just yet.

Getting lmutil/lmstat:

You can download the binaries at the address below. They are available for almost any platform.

http://www.macrovision.com/services/support/flexlm/lmgrd.shtml


Download lmutil since that is the "super binary" that implements a lot of the other binaries ie. lmcksum and lmstat

mv lmutil /usr/local/bin/
chmod 755 /usr/local/bin/lmutil
ln -s /usr/local/bin/lmutil /usr/local/bin/lmstat

Working with phplicensewatcher

Ok, now you have a working apache, php4, mysqld, lmutil and you're ready to get what you've been wanting for over about an hour now.

Making sure that safe_mysqld is running:

ps -ef | grep mysqld |grep -v grep

If you get something, you should be alright.


Creating databases

Become the mysql user (or root) then

mysqladmin create licenses

This creates the database called licenses.

Then run

mysql -f licenses < phplicensewatcher.sql

Please ignore "Unknown table" errors (if tables with same name are found they are dropped). This populates the database with tables and such.

I recommend creating a MySQL user with only INSERT or SELECT privileges to the tables. To create a user called lic_user with password secretpass type

mysql mysql

Then type or paste following

GRANT SELECT,INSERT ON licenses.* TO lic_user@"%";
GRANT SELECT,INSERT ON licenses.* TO lic_user@localhost;
SET PASSWORD FOR lic_user@"%" = PASSWORD("newpass");
SET PASSWORD FOR lic_user@localhost = PASSWORD("newpass");

Ok, now we are ready to set the password on the mysql database and in this case, you actually want to use the apostrophe with new-password being your new password and not the word new-password.

mysqladmin -u root password 'new-password'
mysqladmin -u root -h $HOSTNAME password 'new-password'

Configuring PHPlicensewatcher

There is a sample-config.php in the phplicensewatcher directory. Copy it to config.php ie .


cp sample-config.php config.php

then edit it in your favorite editor. You want to keep an eye on the following:



$lm_home = "/usr/local/bin"; // location of lmutil and lmstat
$servers[] = "27000@hostname";
$description[] = "Synopsys License";

If you have more then one host, or more then one port active, just keep adding a $servers line and a $description line.


$servers[] = "5280@hostname";
$description[] = "Cadence Licenses"; // and so on and so on

By default you will be warned 10 days ahead of time whether licenses are expiring. If you want to prolong that or shorten that adjust the $lead_time variable ie.

$lead_time = 10;

You now have to configure your database settings. This assumes you are using MySQL. You could use other databases but you would need to modify the


$db_hostname = "localhost"; // localhost should work if it is in /etc/hosts
$db_username = "mysql"; // name of the user who starts the safe_mysqld
$db_password = "mysecretpassword"; // whatever you changed your password to
$db_database = "licenses"; // name of the database.
# Leave $dsn as it is if you are using MySQL.
$dsn = "mysql://$db_username:$db_password@$db_hostname/$db_database";
# Uncomment following if you are using PostGresSQL and comment out one with MySQL
# $dsn = "pgsql://$db_username:$db_password@$db_hostname/$db_database";

PHPLicensewatcher will record utilization for all the licenses listed on the servers you are watching. However in most cases you will want to keep an eye on couple. That is why you need to specify couple features you want graphed on the utilization page. To do that you have to add $license_feature and $feature_description pairs. License feature is the actual name of the feature as used on the license server ie. Al_viewer while feature description is a more detailed description of the feature


$license_feature[] = "Al_viewer";
$feature_description[] = "Allegro Viewer";

If you want license denials and checkout statistics you need to define where FlexLM logs are kept ie.

$log_file[] = "/mnt/flexlm/27000-at-licenserv.log";


There is a number of other options you can change. Read through the comments in the config.php. When you are done you can check your installation for common configuration errors by opening up check_installation.php page ie.

http://localhost/phplicensewatcher/check_installation.php

If everything worked without errors, then you should be able to point your browser to http://localhost/phplicensewatcher/index.php.



Crontab setup

License alerts e-mail

This is probably the most important part of managing licenses :-). Being notified when licenses are due to expire. E-mails come as HTML mail since I wanted to use tables and colors.

The way I use it is to run license_alert.php report every night at 2 a.m. This report will query all specified license servers and figure out which licenses are due to expire. There are two ways to run license_alert.php script. You can use PHP interpreter directly if you have it installed in on your machine ie. RedHat distributes php interpreter as php-*.rpm packages. You can then have one of the following entries in your crontab

0 2 * * * php /var/www/html/phplicensewatcher/license_alert.php >> /dev/null

The other way to invoke it is to use wget which is a web retrieval tool. You can also use curl if you prefer that

0 2 * * * wget -O - http://your.apachehost.com/phplicensewatcher/license_alert.php >> /dev/null

License utilization

To get license utilization stats you need to set up data collection crontabs. There are two scripts that need to be executed ie. license_util.php and license_cache.php.

My crontab looks like this


0,15,30,45 * * * * wget -O - http://your.apachehost.com/phplicensewatcher/license_util.php >> /dev/null
15 0 * * * wget -O - http://your.apachehost.com/phplicensewatcher/license_cache.php >> /dev/null

License denials / per user usage

An important metric in evaluating your licenses is license denials ie. how many people were denied access to a certain feature because we were out of licenses. To do that we have to analyze FlexLM logs. FlexLM logs are enabled during FlexLM start up. For example we start our FlexLM servers with following options


su nobody -c '/tools/lmgrd -l /usr/tmp/27000-at-licenserv.log -c /tools/license/license.dat'

This will create /usr/tmp/27000-at-licenserv.log which will contain information such as when the license has been checked out, when it was checked in plus any time a license has been denied ie.

16:01:20 (daemond) DENIED: "viewer" jack@server  (Licensed number of users already reached (-4,342))

We want to capture this information since a high number of denials would indicate that we should consider getting additional licenses since a lot of people are being denied access. 

Same log file contains check out and check in information that we also store in the database so we can retrieve it later.

FlexLM logs can be very large so it may take a long time to analyze them. I run the analysis scripts around 2 a.m. every morning. To run them put something like this in your crontab


0 2 * * *  wget -O - http://your.apachehost.com/phplicensewatcher/parselog.php >> /dev/null

Additional configuration options

General

$disable_autorefresh

On the current usage page there is a drop down box that will allow people to select auto refresh a page. By default refresh is enabled. However that could introduce overhead on your server so you may want to turn it off. Set $disable_autorefresh to  1 to disable

$disable_license_removal

Disable ability to remove licenses from the web interface.  Set to $disable_license_removal  1 to disable

$adminusername and $adminpassword

By default Admin page ie. admin.php is not password protected so anyone can access it. If that is not what you want you can set admin username and password. You need to specify those two variables to enable authentication ie.

$adminusername="admin";
$adminpassword="mypassword";

If you do you should also change permissions on config.php to be only readable to the web user (if you have not already done that).

Graphing

$smallgraph and $largegraph

 Defines sizes of the graph. XY size ie. 300,200.

$collection_interval

Time interval between data collections ie. 15 minutes

$xlegendpoints

How many point on the X axis you want for a 24 hr period ie. show legend every for every 2 hours = 12 so you will see 2,4,6,8,10 etc.


Troubleshooting

1. I go to license utilization page and I can't see any graphs ie. not even the grid shows up

There couple reasons

2. DB Error: connect failed

Either lic_user doesn't have appropriate privileges or you are pointing to the wrong database