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 [grace period] 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