UniCon Software GmbH

Documentation

FELICS 2.x
Floating Extended Licence Server
06.06.00

 UniCon Software GmbH All rights reserved. No part of this manual may be reproduced or utilised in any form or by any means without the publishers's consent. The following text and Illustrations were written with great care, however, we cannot take warranty for any errors and consequences from those. The product titles found in this manual are registered trade marks of the producers. The authors will appreciate suggestions or remarks as to the text.

Preface We want to thank you for choosing the UniCon products and assure you that UniCon communication software combines best functionality with a maximum of user comfort. This detailed technical description will help you in getting used to work with the product. However, questions will still arise especially when communication components of other producers are also being used. In this case please contact us immediately. We will give you qualified support. FELICS, the Floating Extended Licence Server, dynamically monitors and supervises the application of software in NOVELL and TCP/IP networks. The software package contains the client and server components. Supported server platforms are: Netware-Server, Windows-NT, OS/2 as well as Unix Systems. The client software is availabe on Windows 3.x, Windows 95, OS/2 and Unix. The installation, configuration, application and interfaces for software programmers are described in this manual.

CONTENTS 1 Licence Management .............................................................................. 1 1.1 By FELICS.............................................................................................. 1 1.2 By Node Licencing (Software-Dongle).................................................... 2 2 FELICS...................................................................................................... 3 2.1 Installation .............................................................................................. 4 2.1.1 UNIX-Server ............................................................................. 4 2.1.2 NOVELL-Server ....................................................................... 5 2.1.3 Windows-NT............................................................................. 5 2.2 Start and Close....................................................................................... 6 2.2.1 UNIX-Server ............................................................................. 6 2.2.2 NOVELL-Server ....................................................................... 7 2.2.3 Windows-NT............................................................................. 8 2.3 Configuration (felics.cnf)......................................................................... 9 2.4 Diagnosis (felics.log) ............................................................................ 10 2.5 Backup Licence Server......................................................................... 11 3 FELICS-Tools ......................................................................................... 13 3.1 Installation ............................................................................................ 13 3.2 Licencing by FELICS ............................................................................ 13 3.2.1 BRANDLI (Unix) ..................................................................... 14 3.2.2 REMBRAND (Windows)......................................................... 18 3.3 Licence Monitoring ............................................................................... 19 3.3.1 RAMON (Unix)........................................................................ 19 3.3.2 WRAMON (Windows) ............................................................ 21 3.4 Licence Management by Node Licencing............................................. 21 4 FELICS Agent......................................................................................... 23 4.1 UNIX (felicscltd).................................................................................... 24 4.2 Windows 3.x (UCWATCH) ................................................................... 25 4.2.1 Installation .............................................................................. 25 4.2.2 Automatical Installation WATCHPUB (Novell) ....................... 26

4.3 Windows NT (NTfelclt) .......................................................................... 27 4.3.1 User-Controlled Licencing (NTclte)......................................... 29 4.4 Windows95 / Win32s (NTfelclt)............................................................. 30 4.4.1 User-Controlled Licencing (NTclte)......................................... 30 5 FELICS-SDK............................................................................................ 31 5.1 General Concept................................................................................... 31 5.2 Technical Concept ................................................................................ 32 5.3 UNIX...................................................................................................... 33 5.3.1 Installation............................................................................... 33 5.3.2 Application Programmers Interface (API) ............................... 34 FELICS_init..................................................................... 34 FELICS_quit.................................................................... 34 FELICS_getlicence ......................................................... 35 FELICS_freelicence ........................................................ 35 5.3.3 Demo Program ....................................................................... 36 5.4 WINDOWS 3.x...................................................................................... 37 5.4.1 Installation............................................................................... 37 5.4.2 Application Programmers Interface (API) ............................... 38 FELICS_init..................................................................... 38 FELICS_quit.................................................................... 38 FELICS_getlicence ......................................................... 39 FELICS_freelicence ........................................................ 39 FELICS_sdkversion ........................................................ 40 5.5 WINDOWS-NT / 95 and Win32s .......................................................... 42 5.5.1 Installation............................................................................... 42 5.5.2 Application Programmers Interface (API) ............................... 43 FELICS_init..................................................................... 43 FELICS_quit.................................................................... 43 FELICS_getlicence ......................................................... 44 FELICS_freelicence ........................................................ 44 FELICS_sdkversion ........................................................ 45 5.6 Key Generator WLIPRI (Windows) ....................................................... 47 5.6.1 DDE Server............................................................................. 48

List of Illustrations Index

UniCon
1 Licence Management

Licence Management

FELICS is based on the Client-Server technology. The main part is the licence server which is installed on the corresponding server system (Unix, Netware, Windows-NT) controlling the licencing-out. Each client has exactly one instance (FELICS Agent), which maintains the communication with the licence server. Every PC-application subject to licencing requests a licence from this agent. The FELICS Agent should therefore be activated when starting the client PC. 1.1 With FELICS

Using a central licence server has the following advantages: central administration and control of licences licencing-out on request (floating licence)

licence

licence

licence

licence

licence
FELICS Agent

licence
FELICS Agent

FELICS licence.db

Illustration 1: Licence Management with FELICS The FELICS Tools allow to administrate the licence server comfortably. Your own software can easily be connected to the FELICS Agent by means of FELICS-SDK.

Licence Management

UniCon

1.2 Node Licencing (Software-Dongle) Node licencing has been added to the licence management. Thus one can do without a central licence server, e.g. if there is no network. In case of node licencing the FELICS Agent manages the licencing-out and the monitoring of licences:

licence licence licence

FELICS Agent

licence licence licence

FELICS Agent

Illustration 2: Licence Management by node licencing You enter your licences with the FELICS tools on each node. All applications which are subject to licencing may use this licence mode without any restrictions or adjustment.

UniCon

FELICS

FELICS

The Floating Extended Licence Server (FELICS) enables you to install software in your network as often as you like without having to buy new licences. When starting the program the licence is provided by the licence server. The licences are held in the licence data base licence.db. The programs REMBRAND (Windows) and BRANDLI (Unix) serve to register or delete licences in the data base. All you need is a licence key which you receive from your software vendor. If you wish to increase the number of licences for a product, you only have to feed the data base with the corresponding licence key. Without restart, the licence server is informed about the new number of licences. If software products are installed on different PCs, all products can be licenced by one server, provided that the server can be reached via the network protocols IP or IPX. This version also offers the possibility to provide user-controlled licences. Thus you are free to licence your standard software according to your requirements. If you have decided to use the Node Licencing (Sofware Dongle), you do not need a licence server. In this case please see for chapter "FELICS Tools.

FELICS

UniCon

2.1

Installation

The installation procedures differ between the operation systems UNIX, NOVELL and Windows-NT. This is why they are described separately. 2.1.1 UNIX-Server

After installation, all files can be found in the directory '/usr/felics'. The FELICS installation disk has either the tar format or the DOS format (for UNIX systems without a disk drive). For installing the licence server please perform the following steps: In SUN-Sparc systems you must first switch off the vol-daemon by the kill command (kill vold). tar-Diskette cd / tar xvf /dev/fd0

(and the drive as installed in your system respectively)

DOS-Diskette Send the file felics.tz (felicss.tz in case of FELICS with SDK) to your UNIX system as a binary file and then enter the following commands: mv felics.tz felics.tar.Z uncompress felics.tar cd / tar xvf felics.tar

cd /usr/felics ./felics.install If desired the licence server can be started automatically by the above script. But it may also be started later (see "Start and Close").

UniCon
2.1.2 NOVELL-Server

FELICS

Installation is carried out by means of a Windows program. In this case the Novell system directory (e.g. f:\system) and the FELICS work directory (e.g. f:\felics) must be entered. The work directory should be on the system drive. For installation both directories must not have a WRITE protection. Therefore you should have Supervisor or Admin rights. For installation perform the following steps in Windows: a:setup The setup program guides you through installation. After the installation has been finished successfully the licence server can be started on the Novell server console (see "Start and Close"). 2.1.3 Windows-NT

For installation both directories - Windows and Windows\system - must not have a WRITE protection. Furthermore, you must have the right to install NT services. For installation perform the following steps in Windows-NT: a:setup The setup program leads you through installation. When the installation has been finished successfully the licence server is availabe on your NT server. Click on the symbol Services in your System Control. FELICS is loaded via the service administration of Windows-NT (see "Start and Close).

FELICS

UniCon

2.2

Start and Close

Already registered licences are not deleted by terminating the licence server. Thus licenced programs will still run without any difficulties. The licence server itself has to be supplied with a licence key. If this has not been carried out yet, FELICS starts in the so-called 'administration mode'. In this case, please enter your FELICS licence directly after the start by means of the programs BRANDLI (Unix) or REMBRAND (Windows) (see chapter "Licencing"). 2.2.1 UNIX-Server

The licence server can be started or closed with the root authorization only. By default the licence server is found on /usr/felics. If you wish to use a different work directory, the environment variable FELICSENV has to be set. Start: cd /usr/felics ./felics Close: cd /usr/felics ./felics end Restart: cd /usr/felics ./felics restart

UniCon
2.2.2 NOVELL-Server

FELICS

Please enter the following commands on the console of the Novell server: Start: load felics <arbeitsverzeichnis> Enter the command in the file autoexec.ncf in order to automatically load the licence server during system initialisation The work directory need only be named if it differs from the default (<nwserver>/SYS:/FELICS). Close: unload felics

FELICS

UniCon

2.2.3

Windows-NT

The licence server can be started and closed via the service administration of Windows-NT. Please activate the symbol "Services in your System Control. Start: Mark the service FELICS and click on the switch "Start. Having started the licence server successfully the state of the service changes to "started. Close: Close the licence server with the switch "Close. If you want to remove the licence server from the service administration, start the server executable with the parameter "remove: z.B.: c:\win32app\felics\ntfelics.exe remove

UniCon
2.3 Configuration (felics.cnf)

FELICS

The configuration of the licence server is defined by the text file felics.cnf in the FELICS working directory. The following parameters may be set: Client Alive Mechanism The licence server requests a message from the client in regular intervals, in order to recognize if a licenced program has been aborted or a client system is missing (e.g. has been switched off). This so-called Alive Mechanism may be configured by the following parameters: MAXALIVE= If the number of Alive requests is not replied by a client, this client's licences are released again. Default: MAXALIVE=3 . Frequency (in seconds) in which the Alive requests are sent to the client systems. Default: ALIVEFREQ=20 .

ALIVEFREQ=

Thus the maximum period of time for FELICS to recognize an abortion amounts to MAXALIVE * ALIVEFREQ seconds. Diagnosis The status information written in the logfile felics.log (see chapter "Diagnosis") can be extended by the following parameter for the purpose of diagnosis: DEBUG= 0: no extended protocol 1: extended protocol in felics.log Backup Function The Backup Server (see chapter Backup Licence server) safeguards that the licences are still avaiblabe even if the master licence server should fail. The following parameters are only used by a backup server (FELICS with FELICSB licence). MFELICS= Host name of the master FELICS the failure of which is to be supervised. The parameter may be entered several times, i.e. a backup server may supervise several licence servers. PONG= Frequency (in seconds) in which the failure of the supervised master licence server is checked. Default: 20 seconds

FELICS

UniCon

Example: felics.cnf: MAXALIVE=3 ALIVEFREQ=20 DEBUG=0 Example: felics.cnf of the backup licence server ucfelics3 MAXALIVE=3 ALIVEFREQ=20 DEBUG=0 MFELICS=ucfelics1 MFELICS=ucfelics2 PONG=30

2.4

Diagnosis (felics.log)

As long as the licence server is active all necessary data are written in the text file felics.log in the FELICS work directory. When this file has grown to its maximum volume, writing is continued at the beginning of the file. By default the file contains generally the essential events of the licencing process. However, in some cases it may be useful to activate the extended mode (see chapter "Configuration"), because it supplies detailed status information of the licence server. Please note that the file cannot be read directly in the Novell environment. This is only possible with a file copy. copy felics.log felics.txt edit felics.txt

Windows-NT This allows to additionally show the status information of the licence server on the window of the licence server. Enter the parameter show when starting the FELICS service.

10

UniCon
2.5 Backup Licence Server

FELICS

In version 2.30 another essential function has been integrated into the licence management FELICS. Thanks to the Backup Licence Server the acquired licences are available at any time even if the licence server fails. Thus the Backup Licence Server takes over the tasks of the master licence server until it is ready again. Concept The Backup Server is installed on a second PC. It is the same software as on the primary system. However, the licence server is configured by a FELICSB licence as a backup server. The parameter MFELICS in the file felics.cnf (see chapter FELICS configuration) provides that the main licence server (master FELICS) is known to the backup licence server.

Agent

Agent

FEL ICS

FEL ICS Backup

The backup server is constantly in contact with one or several master servers (registered in felics.cnf) supervising their functionality. All information required for licencing-out are permanently transferred from the masterFELICS to the BackupFELICS:

The failure of the master FELICS is automatically recognized from the backup server in a configurable frequency (PONG-Parameter in felics.cnf). Firstly, the backup server informs all agents about the new server address.

Agent

Agent

FEL ICS

FEL ICS Backup

11

FELICS

UniCon

Agent

Agent

FEL ICS Backup

From now on the agents request all licences from the backup server. Newly started agents are already familiar with the backup server from their own local configuration. After the start the agent tries to contact its master FELICS first. If it does not succeed it applies to the Backup Server.

Now the Backup Server has exactly the same functions as a licence server. Licences may be entered or deleted by REMBRAND or BRANDLI. However, the Backup Server is not available for other master licence servers. In this case, every other minute the Backup Server checks if the master FELICS is ready again. As soon as the original master FELICS has been recognized, all status informations on the licence are transferred to the master, the agents are informed, and the (backup) licence server returns to the backup mode again.

Configuration Version 2.30 and further versions must include all licence components (FELICS and FELICS Agents). It is not necessary to change the configuration of the master FELICS. The Backup Server is to be installed on a second PC and equipped with a FELICSB licence. The parameters MFELICS and PONG have to be adjusted in the configuration file felics.cnf (see FELICS Configuration). When starting the Backup Licence Server the connection to the master FELICS must be assured of. The configuration of the FELICS Agents is extended by the Backup Server at the requested position (see FELICS Agent ).

12

UniCon
3 FELICS-Tools

FELICS-Tools

These programs (BRANDLI, REMBRAND) enable comfortable access to the functions of the licence server FELICS as well as to the licence data base. They also help to find out the actual need of licences (RAMON, WRAMON). Moreover, the FELICS Tools contain the FELICS SDK for Windows 3.x to handle your own software by means of the licence server. When installing the FELICS Tools you may select the licencing mode via node (software dongle) if you wish to manage your licences without a central licence server FELICS and without network connection (see chapter Licence Management).

3.1

Installation

The programs RAMON and BRANDLI are included in the delivery of FELICS/Unix (see "FELICS Installation"). Please install the Windows components by means of the setup program on the FELICS Tools disk: a:setup Your PC needs network support either by TCP/IP with Winsockets or by SPX/IPX (not in case of Node Licencing). The installation program creates the program group "FELICS Tools" with the corresponding program symbols. 3.2 Licencing by FELICS

The FELICS licence management differentiates between key-controlled and user-controlled licences. For this product, key-controlled licences must be acquired from your software producer or vendor respectively. These licences are provided by a licence key. User-controlled licences may be supplied by the system administrator for standard software in order to limit the number of applications or users. It is up to the system administrator to set the limit of licences.

13

FELICS-Tools
3.2.1 BRANDLI (Unix)

UniCon

BRANDLI is an efficient program, which enables you to register keycontrolled licences by licence keys very easily. command: /usr/felics/brandli

After the start (which is only possible with root authorization) the following menu is shown:

Illustration 3:

BRANDLI - main menu

Select "L" to licence a product. Then you are requested to enter the key:

14

UniCon

FELICS-Tools

Illustration 4:

BRANDLI - Entry of product key

If the key has been entered correctly this is being confirmed:

15

FELICS-Tools

UniCon

Illustration 5:

BRANDLI - Licence confirmation

Provided a licence server is active, it will be immediately informed by BRANDLI about the modification. Moreover BRANDLI is able to display the entries in the licence data base and thus offers a complete survey of all the licences acquired. You get this survey by selecting "D" in the main menu:

16

UniCon

FELICS-Tools

Illustration 6:

BRANDLI - Product survey

17

FELICS-Tools
3.2.2 REMBRAND (Windows)

UniCon

By means of REMBRAND you administrate your key-controlled and usercontrolled licences from your Windows application. Start the program via the icon FELICS Tools of the program group. Please make sure, however, that the licence server has been initialized.

Illustration 7:

REMBRAND

IMPORTANT: User-controlled licences can only be released if a FELICSE Licence (FELICS end-user licence) is available. REMBRAND offers online help for detailed information.

18

UniCon
3.3 Licence Monitoring

FELICS-Tools

The monitor programs RAMON(Unix) and WRAMON(Windows) keep you informed about the actual number of licences you need. Both programs require an active licence server. 3.3.1 RAMON (Unix)

RAMON (Running Application MONitor) is an additional product in order to "observe" running applications. To activate this product you need a licence key. Enter the following command: /usr/felics/ramon and you get the menu:

Illustration 8:

RAMON - info window

The command "m" leads you to the monitor mode. RAMON is updated automatically .

19

FELICS-Tools
Please select between two presentations with the option "o".

UniCon

1. All active applications and additional information such as the names of the station and the host on which the application is active. 2. The number of all active applications sorted by applications and the number of licences in use.

Illustration 9:

RAMON Monitor Window

Quit the monitor by entering the command "q".

20

UniCon
3.3.2 WRAMON (Windows)

FELICS-Tools

By means of WRAMON (Windows Running Application MONitor) you may "observe" running applications and thus find out the actual need of licences. Please start WRAMON by clicking on the icon "FELICS-Tools in the program group . Make sure that the licence server has been initialized.

Illustration 10:

WRAMON

WRAMON is equipped with online help, which gives you detailed explanations to the various functions. 3.4 Licence Management by Node Licencing

In case of node licencing (software dongle) the licence keys are registered on each node PC by means of the program WBRANDLI into the file ucwatch.ini. The licence keys you acquired are only valid for the corresponding node PC (identified by the Host ID). The Host ID can be obtained by calling the program UCHOSTID in FELICS Tools. WBRANDLI also shows the Host ID in the top line:

21

FELICS-Tools

UniCon

Illustration 11:

WBRANDLI

Please select [New] to enter a licence with a licence key. It is up to you to define the corresponding product name. The licences are available immediately after the entry. [Rename] to modify the product name [Delete] to delete the licences of a product [Quit] to quit the program. Important: Every node PC must be released by entering a FELICSN licence (Produkt-Id 66).

22

UniCon
4 FELICS Agent

FELICS-Agent

FELICS is based on the Client-Server concept. The main part is the licence server, which is installed on the corresponding server system (Unix, Netware, Windows-NT). Each client workstation has exactly one instance (FELICS Agent) which maintains the communication to the licence server. Every PC-application subject to key-controlled licencing requests a licence from this agent. For this reason the FELICS Agent should be activated when starting the client PC.

Windows-PC
Application Product-Id x Application Product-Id y

Unix
Application Product-Id x Application Product-Id y

msgqueue

ucwatch watch.dll

felicscltd

UDP/IP IPX

Novell / Unix
FELICS
licence.db

Illustration 12:

FELICS-Agent

23

FELICS-Agent

UniCon

4.1

UNIX (felicscltd)

The FELICS Agent is either obtained by installation of the FELICS-SDK or together with the software of software producers or vendors who protect their software by FELICS. The agent is responsible for the complete communication with FELICS. We therefore recommend to activate the daemon when starting your system (in /etc/rc). Program Parameters: felicscltd -s -s <licence server> -k <msgqueue> -d

enter the hostname of your licence server here If you use a backup server, it must also be entered here (e.g. felicscltd -s ucfelics -s ucfelicsb) -k The input of a message queue key is optional. By default we use FELICS_MSG (see FELICS-SDK/UNIX). -d activates the trace output of the agent. The trace configuration is defined in the file /etc/felicscltd.cnf. Example: TRACEFILE = <file name> TRACELEVEL=<trace level 0-5> TRACEFILE_COUNT=<max number of trace files> TRACEFILE_SIZE=<max size of a trace file in bytes> Example: TRACEFILE = felicscltd.log TRACELEVEL = 5 TRACEFILE_COUNT = 2 TRACEFILE_SIZE = 500000 Important: You need root authorization to start the FELICS Agent. If you need to close the daemon, you may do this by signal 15.

24

UniCon
4.2 Windows 3.x (UCWATCH)

FELICS-Agent

In addition to the server component (FELICS) you have to install the client component (UCWATCH) for user-controlled licencing on each PC which is to support this mode of licencing. UCWATCH informs your licence server about the events which are relevant for the user-controlled licencing (e.g. Start and Terminate Windows applications). If the number of licences should be exceeded , the user will be informed by a message. UCWATCH requires a network connection via TCP/IP-Winsockets or SPX/IPX-Netware. Alternatively, you may choose the Node Licencing (software dongle) during installation. In this case a licence server and a network connection are not necessary. The agent itself is performing the licence management. 4.2.1 Installation

The UCWATCH is shipped with the disk FELICS Agent. During the installation of FELICS Agent the UCWATCH program components are being copied into the target directory: watch.dll: ucwatch.exe: toolhelp.dll: ucwatch.ini: Dynamic library of functions client daemon (WINDOWS) Windows tools library configuration file

Before the first start of the agent the name of the licence server (and the name of the backup server respectively) must be entered into the configuration file ucwatch.ini in the Windows directory (unless you have chosen the Node Licencing). Example ucwatch.ini: FELICS=192.92.1.1 or FELICS=NWSERVER Please make sure that the program ucwatch.exe will be initialized automatically when starting Windows (entry in win.ini): Example win.ini: [windows] run=UCWATCH.EXE Please restart Windows.

25

FELICS-Agent

UniCon

4.2.2

Automatical Installation WATCHPUB (Novell)

The Novell environment allows an automatical installation procedure. The program watchpub.exe copies the UCWATCH files during the login procedure of the user into his Windows directory and modifies the win.ini. Call: -w -u watchpub -w <work directory> -u The mentioned directory must contain the following files: ucwatch.ini, ucwatch.exe, watch.dll, toolhelp.dll The modifications in the win.ini of the user are canceled.

We recommend the following approach: First copy the UCWATCH program files and the program watchpub.exe into an appropriate Novell server directory (e.g. <nwserver>/SYS:/PUBLIC/WATCH). Edit the file ucwatch.ini in the above directory as described in the chapter "Installation". Enter watchpub.exe into the system login script:
#<nwserver>/sys:/public/watch/watchpub -w <nwserver>/sys:/public/watch

Watchpub.exe can be called more than once without causing any difficulties.

26

UniCon
4.3 Windows NT (NTfelclt)

FELICS-Agent

Like the licence server itself the FELICS Agent is an NT service installed by the FELICS Agent installation program. Before the first start of the agent you have to modify the starting mode of the service: Starting mode [] Automatically Login as [] System account [] allow interactive relation by desktop After the starting procedure the service may be started and closed via the service management of Windows NT. We recommend the starting mode Automatically, because the agent will then be activated during system initialization. The FELICS Agent is configured in the file UCWATCH.INI in the Windows directory. If not already done during installation, please enter the name of the licence server here and - if required - the name of the backup licence server as well. Example ucwatch.ini: [UCWATCH] FELICS=ntserver FELICS1=ntserver2 FELICS2=ntserver3 : SHOW=<0|1> primary licence server 1st Backup-Server (optional) 2nd Backup-Server (optional)

If you have chosen the Node Licencing during the installation of the FELICS Agent, the agent uses this ini-file to save the acquired licences. The name of the licence server is ignored.

27

FELICS-Agent

UniCon

Service Start Parameter: show The FELICS Agent is made visible for debug purposes.

Command line Parameters: call: install ntfelclt.exe [ remove | install <exename> ] installs the exe file <exename> as FELICS Agent-Service. The exe file must be named together with the complete directory. Example: removes the FELICS Agent service from the service management of Windows-NT.
ntfelclt.exe remove

ntfelclt.exe install c:\win32app\felics\ntfelclt.exe

remove

28

UniCon
4.3.1 User-Controlled Licencing (NTclte)

FELICS-Agent

By means of the additional program NTCLTE, the FELICS Agent may be used for the control and the licencing of standard software (Winword, Access etc.). NTCLTE supervises the calls of every Windows application and requests a licence if necessary. If the limited number of licences is exceeded, the user is informed by a message window, and the Windows application is aborted:

Illustration 13:

Limit of licences exceeded

call:

ntclte

The program should be called in the users login script. The program requires an active FELICS Agent (Ntfelclt) and is not visible for the user. Windows applications are identified by their module names (e.g. MSACCESS) and licenced (see REMBRAND). To find out the module name of a Windows application, use the program NTWINAPP, which is included in the FELICS Tools package. Remark: The FELICS-E function must be released by a licence key on the licence server.

29

FELICS-Agent

UniCon

4.4

Windows95 / Win32s (NTfelclt)

In Windows95 / Win32s the FELICS Agent/NT is used. The installation is done by the FELICS/NT installation program. However, the agent cannot be installed as a service but should be integrated in the autostart group. When calling the agent the parameter noservice must be entered: Call: ntfelclt.exe /noservice

The FELICS Agent is configured in the file UCWATCH.INI in the Windows directory. If not already done during installation, please name the licence server und - if required - the backup server, too. Example ucwatch.ini: [UCWATCH] FELICS=ntserver FELICS1=ntserver2 FELICS2=ntserver3 : SHOW=<0|1> primary licence server 1st Backup-Server (optional) 2nd Backup-Server (optional)

If you have chosen the Node Licencing during the installation of the FELICS Agent, the agent uses this ini-file to save the acquired licences. The name of the licence server will then be ignored.

4.4.1

User-Controlled Licencing (NTclte)

The FELICS Agent also takes charge of the licencing of standard software (Winword, Access ...), provided you additionally start the program NTCLTE (see Windows-NT -> User-controlled Licencing).

30

UniCon
5 5.1 FELICS-SDK General Concept

FELICS-SDK

The Floating Extended Licence Server (FELICS) allows you to install software in the network as often as you like without having to acquire licences. When you start the application, you get an authentication from the licence server via the FELICS Agent. For the purpose of a dynamic licencing the licence server checks the licence data base containing the information on all licenced products. The end-user enters a licence key. Thus the licences are registered in the data base. This licence key includes a product ID, the number of licences and - if required the validation date of the licences. The software producer is the only one being able to generate keys for the corresponding product ID (see chapter key generating). Product-IDs are unique worldwide and are only provided by UniCon. A licence key is only valid for the server or node for which it has been created.

UniCon

Software Producer
Licence Key

Customer
BRANDLI / REMBRAND

Authentication Key Product Authentication FELICS Key

WLIPRI

FELICS Key

licence.db

FELICS Illustration 14: Providing a licence key

If further licences are requested, the user may increase the number of licences for his products by entering the new key even when the licence server is running. The application which is to be licenced (client) acquires an authentication from FELICS (Licence Server) and releases the licence when closing the application. As long as the application is active the licence is in use. After the application has been closed, the licence is available again for users in the complete network. The FELICS Agents provide for the entire communication between application and licence server.

31

FELICS-SDK

UniCon

In case the application has not been closed properly, e.g. by switching off the client PC, the licence will automatically be available after a defined period of time. Closing the licence server does not affect the running applications. After the restart of the licence server the active applications are recognized automatically. 5.2 Technical Concept

Each client PC has exactly one instance (FELICS-Agent) maintaining the communication to the licence server. Any client application to be licenced applies to the FELICS Agent via the SDK. The instance FELICS Agent provides the following services: INIT: GETLICENCE: FREELICENCE: QUIT: initializes the communication between the agent and the licence server orders a licence for the product ID releases the licence of a product ID The communication to the agent is closed.

The licence server controls all FELICS Agents in a period of time to be defined and thus all applications (ALIVE procedure). If applications or complete clients should be shut down abruptly (e.g. by program or system abortion), the licence server again releases all licences in use. In case the server PC has been aborted and restarted, all active licences are recognized in the whole network and registered again. Running applications are not affected. Remark: After the installation of the SDK you may first use the product ID 4711 (DEMO- product) for your own applications. FELICS provides 2 licences of this product for testing purposes.

32

UniCon

FELICS-SDK

5.3

UNIX

In this version the SDK under Unix consists of the following components: Software Development: wlipri: Key generator for product keys (WINDOWS) felicslib.a: Functions Library (UNIX) felicslib.h: Header File (UNIX) felicscltd: FELICS Agent (UNIX) sdkbsp.c: Demo Program (UNIX)

5.3.1

Installation

Make sure that the licence server is active before installation. If you have not yet acquired a FELICS licence key, please use the product ID 4711 (Demo product) for programming. FELICS provides 2 licences for this product ID: The installation of the Unix components is integrated in the FELICS installation (see chapter "FELICS Installation"). All files are copied into the file /usr/felics. Afterwards you copy the files which are important for the software development (felicslib.a, felicslib.h) to the corresponding directories and start the FELICS Agent felicscltd (see chapter "felicscltd"). The key generator WLIPRI (Windows) allows to produce licence keys for your products (see chapter "Key Generator WLIPRI"). We recommend defining a Windows program symbol to start with the work directory.

33

FELICS-SDK

UniCon

5.3.2

Application Programmers Interface (API)

The library "felicslib.a" offers simple and comfortable communication with the licence server FELICS via the FELICS Agent. felicslib.h contains prototypes and constants. Important: Before using API make sure that the FELICS Agent is active under Unix (e.g.: start by the file rc during system initialization)

FELICS_init Prototype: Parameters: extern int FELICS_init ( unsigned long msg ) msg: Message Queue Key, required for the communication with the FELICS Agent unter Unix (e.g. FELICX_MSG). ok Licence server does not answer Errors can be looked up via the errno

Rckgabewert: 0: 2: -1: Description: The function must be called to initialize the communication between application and FELICS Agent. The address of the licence server is defined by the agent.

FELICS_quit Prototype: Parameters: Return value: extern void FELICS_quit ( void ) -

Description: The communication to the FELICS Agent is closed, the resources are released. All licences which have not been released up to now by the application process, are being automatically released now.

34

UniCon

FELICS-SDK

FELICS_getlicence Prototype: extern int FELICS_getlicence ( unsigned long productid, char *text ) Parameters: Product identification additional text describing the application. The text must be unique within one application (e.g. Session 1). Max. Length: FELICS_MAXTEXT. 0: ok 1: No more licences available 2: Licence server not available 1: Errors can be looked up via errno productid: text:

Return value:

Description: The FELICS Agent registers the requested licence for the application. The licence is reserved until the function FELICS_freelicence or FELICS_quit is being called. If no licence is available, it is up to the application what to do (user infos, terminate etc.).

FELICS_freelicence Prototype: extern int FELICS_freelicence ( unsigned long productid, char *text ) Parameters: productid: text: 0: 2: -1: Product identification additional text which had been used in FELICS_getlicence

Return value:

ok Licence server not available Errors can be looked up via errno

Description: The specified licence is released again.

35

FELICS-SDK
5.3.3 Demo Program

UniCon

The following example shows how simple the procedure of licence request and licence authentication is:
#include <stdio.h> #include <stdlib.h> #include <unistd.h> #include "felicslib.h" int main (void); int main() { int rc; char buf[FELICS_MAXTEXT]; rc = FELICS_init(FELICS_MSQ); switch (rc) { case -1: perror("FELICS_init"); exit(1); case 2: fprintf(stderr, "FELICS not running!\n"); exit(1); case 0: break; } sprintf(buf, "Hallo Test from FELICS-SDK (%d)", getpid()); rc = FELICS_getlicence(4711L, buf); switch(rc) { case -1: perror("Error from FELICS_getlicence "); FELICS_quit(); exit(1); case 0: fprintf(stderr, "got licence\n"); break; case 1: fprintf(stderr, "no free licence\n"); FELICS_quit(); exit(0); case 2: fprintf(stderr, "FELICS not available\n"); FELICS_quit(); exit(0); break; } /* do your work here */ sleep (10); if (FELICS_freelicence(4711L, buf) < 0) { perror("Error from FELICS_freelicence"); FELICS_quit(); exit(1); } FELICS_quit(); return 0; }

36

UniCon
5.4 WINDOWS 3.x

FELICS-SDK

The SDK under Unix consists of the following components: Software Development: wlipri: Key generator for product-IDs (WINDOWS) watch.dll: Dynamic functions library (WINDOWS) watch.lib: Static link of the watch.dll (WINDOWS) watchs.lib: Static library with additional functions watch.h: Header file (WINDOWS) ucwatch.exe: FELICS Agent (WINDOWS) bsp.c: Demo program (WINDOWS) toolhelp.dll: Dynamic Windows tool library toolhelp.lib: Static Windows tool library The files ucwatch.exe, watch.dll, toolhelp.dll are absolutely necessary to guarantee the functions of the FELICS Agents. Therefore they must be included in the delivery.

5.4.1

Installation

If not done already, install your licence server FELICS (see chapter "FELICS Installation"). If you have not yet acquired a FELICS licence key, please use the product ID 4711 (Demo product) for programming. FELICS provides 2 licences for this product ID: The installation of the FELICS tools installation (see chapter FELICS Tools Installation) implies the installation of the Windows components. Then copy those files essential for the software development (ucwatch.exe, toolhelp.dll, toolhelp.lib, watch.dll, watch.lib, watch.h) into the corresponding development directories. Now configure and start the agent "ucwatch" under Windows (see chapter "FELICS Agent Windows"). The key generator WLIPRI (Windows) allows to produce licence keys for your products (see chapter "Key Generator WLIPRI"). We recommend defining a Windows program symbol to start with the work directory.

37

FELICS-SDK

UniCon

5.4.2

Application Programmers Interface (API)

The library "watch.dll" offers simple and comfortable communication with the licence server FELICS via the FELICS Agent. watch.h contains prototypes and constants. Important: Before using API make sure that the agent ucwach.exe is active under Windows.

FELICS_init Prototype: Parameters: Return value: extern int FELICS_init ( void ) 0: 2: -1: ok Licence server not available Error

Description: The function has to be started to initialize the communication of the appliaction to the FELICS Agent. The name of the licence server is specified by configuring the agent (in ucwatch.ini).

FELICS_quit Prototype: Parameters: Return value: extern void FELICS_quit ( void ) --

Description: The link to the FELICS Agent is quit again, the resources are released. All licences which have not been released so far by the application (process) are being automatically released now.

38

UniCon

FELICS-SDK

FELICS_getlicence Prototype: extern int FELICS_getlicence ( unsigned long productid, LPSTR *text ) Parameters: Product identification additional text describing the application. The text must be unique within this application (e.g. session 1). Max. Length: FELICS_MAXTEXT. 0: ok 1: No more licences available -1: Errorr productid: text:

Return value::

Description: The FELICS Agent registers the requested licence for the application. The licence is reserved until the function FELICS_freelicence or FELICS_quit is being called. If no licence is available, it is up to the application what to do (user infos, terminate etc).

FELICS_freelicence Prototype: extern int FELICS_freelicence ( unsigned long productid, LPSTR *text ) Parameters: productid: text: 0: -1: ok Error Produkt identification additional text which was used in FELICS_getlicence.

Return value:

Description: The specified licence is released again.

39

FELICS-SDK

UniCon

FELICS_sdkversion Prototype: extern int FELICS_sdkversion ( LPSTR dllname, WORD *version, LPSTR description)

Parameters: dllname:

version:

description:

Name of the SDK-DLL the version of which is to be found. You may enter NULL, then the default name WATCH.DLL is used. Pointer to a buffer variable to register the SDK version number. In case of entering NULL the parameter is ignored. The high-value byte contains the number of the main version, the low-value byte the number of the sub version. Buffer for a short description of the version. The buffer must be allocated by the calling program and should have a minimum length of 64 Bytes. If you enter NULL, the parameter is ignored.

Return value:

FELICS_OK:

The SDK-DLL was checked and the version found. FELICS_BADSDK: The SDK-DLL does not support this function or what we have is a nonauthorized library of a software vendor.

Description: This function finds out the actually valid SDK version and at the same time checks the SKD-DLL for authenticity. Remark: For reasons of security you do not find this function in the SDKDLL (WATCH.DLL) but in the static library WATCHS.LIB, which is used to link your program.

40

UniCon
5.4.3 Demo Program

FELICS-SDK

The following example shows how simple the procedure of licence request and licence authentication is:
#include #include #include #include <stdio.h> <stdlib.h> "windows.h" "watch.h"

int PASCAL WinMain(HANDLE, HANDLE, LPSTR, int); #define DEBUG(a) MessageBox((HWND)NULL,(LPSTR)a,(LPSTR)"BEISPIEL",MB_OK) #define PRODUCTID 4711L int PASCAL WinMain(hInstance, hPrevInstance, lpCmdLine, nCmdShow) HANDLE hInstance; HANDLE hPrevInstance; LPSTR lpCmdLine; int nCmdShow; { int rc; char buf[FELICS_MAXTEXT]; if ( FELICS_sdkversion(NULL,NULL,NULL) != FELICS_OK ) { DEBUG("FELICS-SDK DLL invalid"); return FALSE; } rc = FELICS_init(); switch (rc) { case -1: DEBUG("FELICS_init() failed"); return FALSE; case 2: DEBUG("FELICS unreachable"); return FALSE; case 0: break; } sprintf(buf, "Instanz=%d", hInstance); rc = FELICS_getlicence ( PRODUCTID, buf ); if ( rc == 0 ) { DEBUG("got licence"); } else { DEBUG("no free licence"); FELICS_quit(); return FALSE; } rc = FELICS_freelicence( PRODUCTID, buf ); DEBUG("licence freed"); FELICS_quit(); return TRUE; }

41

FELICS-SDK
5.5 WINDOWS-NT / 95 and Win32s

UniCon

The SDK presently consists of the following components: NTWATCH.dll: Dynamic Functions Library (Windows-NT) NTWATCH.lib: Static link to the NTWATCH.dll NTWATCHS.lib: Static library with additional functions WATCH.h: SDK Header-File ntbsp.c: Demo program (Windows-NT) ntbsp.exe: Demo program (Windows-NT) wlipri: Key generator for product IDs is integrated in the FELICS-Tools/Windows

5.5.1

Installation

Before installation make sure that the licence server is active. If you have not yet acquired a FELICS licence key, use the product ID 4711 for programming. FELICS provides 2 licences for the demo product. The installation of the Windows components is covered by the FELICS installation (see FELICS Installation/Windows-NT). The key generator WLIPRI (Windows) allows to produce licence keys for your products (see "Key Generator WLIPRI"). We recommend defining a Windows program symbol to start with the work directory. The link to the licence server can only be realized by the FELICS Agent for Windows-NT. Therefore make sure that the agent is active.

42

UniCon
5.5.2 Application Programmers Interface (API)

FELICS-SDK

The communication with the licence server FELICS runs via simple and comfortable functions of NTWATCH.dll. Prototypes, constants and variables are found in WATCH.h .

FELICS_init Prototype: Parameters: extern int FELICS_init ( HWND hwnd, UINT msg) hwnd: When the agent is closed this window receives the specified Windows messsage. If you do not need this function you may enter NULL. A message is sent when the agent is closed. This parameter is not evaluated unless hwnd != NULL. ok Licence server not available Agent not available

msg:

Return value:

FELICS_OK: FELICS_NO_SERVER: FELICS_NO_AGENT:

Description: The function must be called to initialize the communication of the application to the FELICS Agent.

FELICS_quit Prototype: Parameters: Return value: extern void FELICS_quit ( void ) -

Description: The link to the FELICS Agent is quit again, the resources are released. All licences which have not been released for now by the application (process) are being automatically released now.

43

FELICS-SDK

UniCon

FELICS_getlicence Prototype: extern int FELICS_getlicence ( unsigned long productid, char *text ) Parameter: productid: text: Max. Length: Product identificator additional text describing the application. The text must be unique within an application (e.g. "session 1" ). FELICS_MAXTEXT. Licence received No more licences available Agent not available Licence server not available

Return value: FELICS_OK: FELICS_NO_LICENCE: FELICS_NO_AGENT: FELICS_NO_SERVER:

Description: The FELICS Agent registers the requested licence for the application. The licence is reserved until the function FELICS_freelicence or FELICS_quit is being called or the process terminates itself. If no licence is available, it is up to the application what to do (user infos, terminate etc).

FELICS_freelicence Prototype: extern int FELICS_freelicence ( unsigned long productid, char *text ) Parameters: productid: text: Product identificator additional text used in FELICS_getlicence Licence released Agent not available Licence server not available

Return value:

FELICS_OK: FELICS_NO_AGENT: FELICS_NO_SERVER:

Description: The specified licence is released.

44

UniCon
FELICS_sdkversion Prototyps: extern int FELICS_sdkversion ( LPSTR dllname, WORD *version, LPSTR description)

FELICS-SDK

Parameter:

dllname:

version:

description:

Name of the SDK-DLL the version of which is to be found. You can enter NULL, then the default name NTWATCH.DLL is used. Pointer to a buffer variable to register the SDK version number. In case NULL is entered, the parameter is ignored. The high-value byte contains the main version number, the low-value byte the sub-version number. Buffer for a short description of the version. The buffer must be allocated by the calling program and should have a minimum length of 64 Bytes. If you enter NULL, the parameter is ignored.

Return value:

FELICS_OK:

The SDK-DLL was checked and the version found. FELICS_BADSDK: The SDK-DLL does not support this function or what we have is a nonauthorized library of a software vendor.

Description: This function finds out the actually valid SDK version and at the same time checks the SDK-DLL for authenticity. Remark: For reasons of security you do not find this function in the SDKDLL (NTWATCH.DLL), but in the static library NTWATCHS.LIB, which is used to link your program.

45

FELICS-SDK
5.5.3
#include #include #include #include

UniCon

Demo Program
<stdio.h> <stdlib.h> "windows.h" "watch.h"

int PASCAL WinMain(HANDLE, HANDLE, LPSTR, int); #define DEBUG(a) MessageBox((HWND)NULL,(LPSTR)a,(LPSTR)"BEISPIEL",MB_OK) #define PRODUCTID 4711L int PASCAL WinMain(hInstance, hPrevInstance, lpCmdLine, nCmdShow) HANDLE hInstance; HANDLE hPrevInstance; LPSTR lpCmdLine; int nCmdShow; { int rc; char buf[FELICS_MAXTEXT]; if ( FELICS_sdkversion(NULL,NULL,NULL) != FELICS_OK ) { DEBUG("FELICS-SDK DLL invalid"); return FALSE; } rc = FELICS_init(NULL,0); switch (rc) { case FELICS_NO_AGENT: DEBUG("FELICS-Agent unreachable"); return FALSE; case FELICS_NO_SERVER: DEBUG("FELICS unreachable"); return FALSE; case 0: break; default: DEBUG("FELICS_init() failed"); return FALSE; } sprintf(buf, "Instanz=%d", hInstance); rc = FELICS_getlicence ( PRODUCTID, buf ); if ( rc == 0 ) { DEBUG("got licence"); } else { DEBUG("no free licence"); FELICS_quit(); return FALSE; } rc = FELICS_freelicence( PRODUCTID, buf ); DEBUG("licence freed"); FELICS_quit(); return TRUE; }

46

UniCon
5.6 Key Generator WLIPRI (Windows)

FELICS-SDK

WLIPRI is the key generator which allows you to create the licence key for your customer.

Illustration 15:

Key generator WLIPRI

The key is generated based on the unique address (Host ID) of the licence server, the prouct ID, the number of licences and the validation date (if any). With the button per call you specify that every call of the application requests one licence. The button per workstation allows the multiple start of the application on one client requesting only one licence. After entering the data select "Create". Now you receive the required key. This is also written to the file 'lipri.log' and may be used for further process (e.g. fax) by Windows paste. Important: You can only use product IDs which have been licenced by UniCon Software. If you need another product ID, please request the authentication key from UniCon.

The key generator administrates all product IDs you have received from UniCon in the 'products.db' (in the work directory). At the same time WLIPRI creates the file 'newprod' (in the work directory). This file can be delivered to your user.

47

FELICS-SDK
5.6.1 DDE Server

UniCon

Starting with version 2.02 the key generator WLIPRI provides a DDE server and may be controlled by DDE commands from other Windows applications. This allows automatic licencing processes (e.g. in DDE connectivity with a database and a word processing application). The table below shows the DDE functions.
Topic: "System" Initiate Terminate Execute CreateKey

WLIPRI

Create the DDE connection Terminate connection Create licence key based on the specified data. Terminate Wlipri Hide Wlipri Show Wlipri in full size Show Wlipri as icon State the address of the licence server. Format Host-ID: xxxx-xxxx-xxxx Define number of licences Set test date Format: dd.mm.yy Name product. The name must be included in the list of the licenced products. Request the licence key. It is created with CreateKey.

Execute Execute Execute Execute Poke

Quit Hide Show Icon SrvAddr

Poke Poke

Licence Date

Poke

Product

Request

Key

48

List of Illustrations ILLUSTRATION 1: LICENCE MANAGEMENT WITH FELICS 1 ILLUSTRATION 2: LICENCE MANAGEMENT BY NODE LICENCING 2 ILLUSTRATION 3: BRANDLI - MAIN MENU 14 ILLUSTRATION 4: BRANDLI - ENTRY OF PRODUCT KEY 15 ILLUSTRATION 5: BRANDLI - LICENCE CONFIRMATION 16 ILLUSTRATION 6: BRANDLI - PRODUCT SURVEY 17 ILLUSTRATION 7: REMBRAND 18 ILLUSTRATION 8: RAMON - INFO WINDOW 19 ILLUSTRATION 9: RAMON MONITOR WINDOW 20 ILLUSTRATION 10: WRAMON 21 ILLUSTRATION 11: WBRANDLI 22 ILLUSTRATION 12: FELICS-AGENT 23 ILLUSTRATION 13: LIMIT OF LICENCES EXCEEDED 29 ILLUSTRATION 14: PROVIDING A LICENCE KEY 31 ILLUSTRATION 15: KEY GENERATOR WLIPRI 47

Index
A
agent....................................... 23 alive mechanism ....................... 9 ALIVEFREQ.............................. 9 FELICS_quit Unix......................................34 Windows 3.x ........................38 Windows-NT............................43 FELICS_sdkversion Windows 3.x ........................40 Windows-NT ........................45 FELICS-Agent .............23; 24; 32 felicscltd ..................................24 FELICSE ...........................29; 30 FELICSENV ..............................6 felicslib.a .................................34 FELICS-SDK ...........................31 FELICS-Tools..........................13

B
backup licence server11; 24; 27; 30 BRANDLI .......................... 13; 14

C
client ....................................... 32

D
DDE ........................................ 48 debug........................................ 9 diagnosis .................................. 9

K
key generator ..........................47 key-controlled licence........13; 25

E
exceeding licences ................. 25

L
licence database .....................31 licence in use ..........................19 licence key...............................13 licence need ............................19 licence server ..........................32 licencing ..................................13 logfile .......................................10

F
FELICS ..................................... 3 close...................................... 6 diagnosis ............................. 10 installation ............................. 4 start ....................................... 6 felics.cnf.................................. 10 felics.log.................................. 10 FELICS_freelicence Unix ..................................... 35 Windows 3.x........................ 39 Windows-NT ....................... 44 FELICS_getlicence Unix ..................................... 35 Windows 3.x........................ 39 Windows-NT ....................... 44 FELICS_init Unix ..................................... 34 Windows 3.x........................ 38 Windows-NT ....................... 43

M
MAXALIVE.................................9 monitoring................................19

N
node licencing .....................2; 21 NT service ...........................8; 27 NTCLTE...................................29 NTfelclt ..............................27; 30 NTWINAPP .............................29

P
product-id ................................31

R
RAMON .............................13; 19 REMBRAND ......................13; 18

U
UCWATCH.............................. 25 UNIX-SDK ............................... 33 user-controlled licence 13; 25; 30

S
SDK .........................................31 Unix......................................33 Win32s.................................42 Windows 3.x ........................37 Windows95 ..........................42 Windows-NT ........................42 software development kit.........31

W
WATCHPUB ........................... 26 WBRANDLI ............................. 21 WINDOWS-SDK ............... 37; 42 WLIPRI.................................... 47 working directory ................... 6; 7 WRAMON ......................... 13; 21

T
trace ..........................................9