StarLicense for UNIX Release 1.07 Release Notes
April 2008
Copyright 1994-2008 StarQuest Ventures, Inc.
All Rights Reserved.
StarQuest Ventures, Inc.
PO Box 1076
Point Reyes Station, CA 94956
Telephone: 415-669-9619
FAX: 415-669-9629
Sales: contact@starquest.com
Support: contact@starquest.com
URL: http://www.starquest.com
StarLicense for UNIX is a license server for StarQuest products,
including StarSQL. A client uses TCP/IP to connect to the server
to obtain a product license. The client may be an application running
on the local or another UNIX system, an application running on a
Windows system, or a Java application running locally or remotely.
StarLicense includes a management application that can be
used to configure and monitor StarLicense Servers running on
the local or remote machines.
StarLicense may be used in the following modes:
* as a license server
* as a client to a license server
* using a client (local) license in counted mode
* using a client (local) license in uncounted mode
The type of license is embedded in the license key itself and can only
be used for that mode; e.g. you cannot use a client license key in a
client/server mode.
====================
SYSTEM REQUIREMENTS:
====================
* IBM AIX 4.3.3 or later
* Sun Solaris 8 or later (SPARC)
* Red Hat Linux 9 or later (i386)
* SUSE Linux 9 or later (i386)
* HP-UX 11.11 (PA-RISC)
* FreeBSD 6.1 or 7.1 (i386)
You also can run StarLicense on HP-UX Itanium if the calling application is
a 32-bit PA-RISC binary, on a 64 bit Linux (x64) system if the calling
application is a 32-bit x86 binary, or on a 64-bit FreeBSD (x64) computer
if the calling application is a 32-bit x86 binary and you install the
FreeBSD 32-bit runtime compatibility libraries.
QUICK INSTALLATION INSTRUCTIONS
===============================
* Logon to UNIX as root.
* cd to the directory containing the StarLicense installer for your UNIX
platform.
e.g.
# cd /mnt/cdrom/starlic/linux
3. Execute the shell script "setup":
* ./setup
This will install StarLicense to the default location for your platform:
AIX: /usr/lpp/starlicense
Solaris & HP-UX: /opt/starlicense
Linux: /usr/share/starlicense
FreeBSD: /usr/local/share/starlicense
If you wish to install StarLicense to a different location, copy the setup
directory and modify the setup shell script. You may also need to modify
the configure, sqlicd.sh and uninstall scripts after installation.
* At the end of installation, you can run the "configure" script for license
administration - adding a license key, starting and stopping the license
server daemon, etc. You can also perform these operations by invoking
starlic-admin directly.
* You will need to contact StarQuest support with the IP address or the
hostid of your server to obtain a license key.
Note that typically you will choose only one of the following scenarios,
depending on the type of license you have received from StarQuest:
* Configure a License Server and a client connection
to a License Server (options 2 and 1 of configure)
and start the License Server daemon (option 4)
* Install a local (node-locked) license (option 3)
If you choose to not use the configure script, here are the minimum
steps to:
* set up a license server:
-- Add the license key with:
# starlic-admin -add server-key-add
e.g.
# cd target_dir
# ./starlic-admin server-key-add 67A63B58DF5C031A868176FD4E4774C6
-- Add a server listener
e.g.
# ./starlic-admin server-listener-add 0.0.0.0 4999
-- Start the server
# ./sqlicd &
-- Connect with a client application, and display the status
of the license server:
# ./starlic-admin show
* Set up a counted client license:
-- Add the license key with:
# starlic-admin -add client-key-add
-- Start the server
# ./sqlicd &
(no need to configure a listener; the daemon will listen on the local loopback
127.0.0.1)
* Set up an uncounted client license:
-- Add the license key with:
# starlic-admin -add client-key-add
(no need to configure a listener or start the daemon)
* Configure a client connection to a license server:
# starlic-admin client-server-add
If you wish the server to start automatically when your UNIX system boots,
use the supplied sqlicd.sh start/stop script. Refer to the StarQuest
tech document " tech doc "How to Add StarLicense to the Boot Process"
(available from http://www.starquest.com) for details.
Uninstallation:
For tar-based installers:
* Run the script "uninstall" in the program directory. You may need to
copy this script elsewhere so the script itself and the program directory
are deleted.
For RPM installer (Linux):
* To determine if you originally installed starlicense with the RPM installer
rather than the tar-based installer:
# rpm -q starlicense
* First uninstall any applications such like StarSQL or CAUNIX that depend
on starlicense.
# rpm -e starsql
* Remove the symbolic links in /usr/lib:
# cd /usr/lib; rm libstarlicense.so libjstarlicense.so
* Optionally remove the configuration file /etc/starlicense.rc:
# rm /etc/starlicense.rc
* Use rpm -e:
# rpm -e starlicense
StarLicense Usage
=================
Overview
--------
StarLicense for UNIX contains the following applications:
- starlic-admin -- a command line tool to manage license file and license
server daemon
- sqlicd -- starlicense server daemon
Managing License File and Server
--------------------------------
Using starlic-admin, you can manage the license file and start/stop the
starlicense server daemon.
The usage line of the command is as follows:
Options:
show
Client configuration options:
client-show
client-key-show
client-key-add
client-key-remove
client-server-show
client-server-add
client-server-remove
client-loglevel-show
client-loglevel-set
Server Configuration options:
server-show
server-service-show
server-service-start
server-service-stop
server-key-show
server-key-add
server-key-remove
server-primary-show
server-primary-add
server-primary-remove
server-listener-show
server-listener-add
server-listener-remove
server-loglevel-show
server-loglevel-set
server-journallevel-show
server-journallevel-set <0..3>
server-journalretain-show
server-journalretain-set <# days>
"?" after any option provides detailed help
You can use this tool to:
- Configure a license server
- Start/stop a license server
- Configure a license client
To configure a license server, you use server-key-add, server-listener-add,
server-loglevel-set, server-journallevel-set, and server-journalretain-set
options. Use other server- options to display or remove server configuration
items in the license file.
To configure a license client, you use client-key-add and client-server-add.
Use other client- options to display or remove client configuration items in
the license file.
You can also use server-service-start and server-service-stop to start/stop
the license server daemon.
To configure a listener to listen on all IP addresses, use the IP address
0.0.0.0.
See below for a limitation on using this address on Linux.
License File
------------
The StarQuest license file, /etc/starlicense.rc is an ASCII flat file
with the following format:
[ServerLicense0]
Cookie=string32
Grace=nnn
[ServerLicense1]
Cookie=string32
Grace=mmm
[ServerListener0]
IP=a.b.c.d
Port=nn
[ServerListener1]
IP=a.b.c.d
Port=nn
[Global]
ServerLogLevel=FFFFFFFF
ClientLogLevel=0
JournalLevel=3
JournalRetain=1
PrimaryFailoverListenIP=0.0.0.0
PrimaryFailoverListenPort=50300
The following sections are used if your server is functioning as a backup
server for another StarLicense server; enter the hostname of the primary
server for which you are acting as a backup.
[PrimaryServer0]
Hostname=192.168.8.100
[PrimaryServer1]
Hostname=192.168.8.100
The following sections in the starlicense.rc file are used by a client, and
are not needed for configuring the StarLicense for UNIX server:
[ClientLicense0]
Cookie=string32
[ClientLicense1]
Cookie=string32
[ClientServer0]
ProdID=xx
IP=a.b.c.d
Port=yy
Pri=0
[ClientServer1]
ProdID=xx
IP=a.b.c.d
Port=yy
Pri=1
License Server Daemon
---------------------
License server usage:
$ ./sqlicd -h
StarLicense Server version v1.0.418
Usage: sqlicd [-f log-file] [-l log-level] [-p lic-file-dir] [-v] [-h | -?]
where:
-f log-file, specify a logfile to use. If you use -f syslog, then the
UNIX syslog will be used.
-l log-level, specify log level, overrides what's specified in
starlicense.rc.
-v prints starlicense server version.
-h, -? print usage line.
CLIENTS:
A client of a StarLicense Server will need to configure the hostname or
IP address and the listener port of the server.
The default port is 4999.
In StarSQL for Windows, StarSQL for Java (on Windows), and SQDR, the
configuration of the client is done with the License Configuration
application (StarLic.exe).
In StarSQL for UNIX, StarSQL for Java (on UNIX), client Access for UNIX,
and other UNIX products, configure a client connection with option 1
of the configure script, or:
$ ./starlic-admin client-server-add
Note that if you are using a node-locked (local) license, you do not
need to configure a client connection.
CLEANING UP CONNECTIONS:
The StarLicense server uses the system TCP/IP KeepAlive settings to clean
up connections from clients that have disconnected uncleanly without
releasing their license checkouts.
The default values should be sufficient for most users, but if you wish
faster cleanup, you can change the system values. Refer to the StarQuest
tech note "Configuring TCP KeepAlive parameters":
http://www.starquest.com/Supportdocs/techSL/SQV00SL003_TCPKeepAlive.html
LIMITATIONS:
On Linux, if you configure both a server license and a counted client-license,
then you cannot specify a wild card address (* or *ANY* or 0.0.0.0) for the
listener. The counted-client listener is implicitly using the loopback
interface of 127.0.0.1. A client trying to connect to a License Server
running on Linux configured with the wild card will get a "server is
unavailable" message.
In this situation, you must specify an interface address when configuring the
listener.
==============
CHANGE HISTORY
==============
1.07.0428 4/28/08
10298 Client: Revisit lookup order (starlic vs local and configured licenses)
8455 Zombie checkouts remain after client loses connectivity
10382 UNIX installer: create symlink in /usr/lib32 (FreeBSD x64)
10350 clarify UNIX client-server configuration