1 Introduction

This document describes the Kusari Licence Management System for the user of products which it controls.

2 Where Kusari looks for licence information

Kusari looks for licence information based on the NAG_KUSARI_FILE environment variable. This variable should contain a file name (path), a licence server specification, or a comma-separated list of file names and licence servers. It can also specify that the licence is in the registry (#@R) or on a USB key (#@U).

A file name can contain any printing character except comma (,), semi-colon (;) or at-sign (@). A colon (:) is permitted only following a single drive letter at the beginning of the filename. For example, c:\somedir\somefile.something.

A licence server specification consists of a server name (or IP number) followed by a colon, and optionally by a port number. For example, some-machine.some-company.com:.

When a product requests a licence, Kusari will visit each file, or ask each server, in turn, until it finds one with a potential licence. It will then attempt to check out a licence from that source; if this fails the failure will be reported and no further sources will be checked.

If the environment variable NAG_KUSARI_FILE is not set, or if no potential licence has been found, Kusari will then look in the default locations for a licence; these are

1. the Windows Registry;
2. the files nag.key, nag.licence and nagware.licence (in that order) in the current directory;
3. the same files in the user's home directory (found via HOME or HOMEPATH);
4. depending on the software product, the same files in the product's installation directory;
5. for a USB key.

The environment variable may be set as follows:

1. Open System in the Control Panel (this may be under the performance and maintenance category).
2. On the Advanced tab, click Environment Variables, click New, insert NAG_KUSARI_FILE as the variable name and the name of the licence file, e.g. c:\somedir\somefilename.something, as the value.

If Kusari searches the registry, it will look for product AASYSVVPC using the registry key SOFTWARE\Numerical Algorithms Group\AASYSVVPC under first HKEY_CURRENT_USER and then HKEY_LOCAL_MACHINE. If found, it will either use a licence (stored as Licence) or access a server specification (stored as Server). The klreg program can be used to store or display a licence key or server specification.

3 Single machine licences

A single machine licence is provided in a licence file; this may be stored in the registry using klreg (see later section) or accessed directly by the software as determined by the NAG_KUSARI_FILE environment variable (see above).

A licence file may contain blank lines, comment lines (beginning with a '#' or '!' character, and licence key lines. Here is a sample licence file:

! Licence file for Fred Nurke's Machine.

! A full licence for the NAG Fortran Compiler, Release 7.1
NPW3271NA FULL "qfrdwhyMoQFkfpm5e6ESprJmtE"

! A trial licence for the NAG Fortran Compiler, Release 7.1
NPW3271NA TRIAL 2023/07/31 "EMnxidA3oeojOFlYvi5ibxPjB7"

! An annual licence for the NAG C Library, Mark 26:
NLW6I29XE NODE 2024/08/31 "xhhhTkzEiUPgdIpwIbCHgrBjjv"
! That's all folks.

Depending on the specific hardware features of a machine, a licence key line may contain multiple key specifications, e.g.

NPW3271NA FULL "xhhhTkzEiUPgdIpwIbCHgrBjjv" "EMnxidA3oeojOFlYvi5ibxPjB7"

The purpose of the additional key(s) is to ensure that the licence software functions correctly even for machines with unusual hardware, and has no significance for the user. On some machines the key specifications take up more than one line, in which case each line except the last will end with an ampersand (&), and each line but the first will start with an ampersand; for example,

NPW3271NA FULL "GiioUjNInkfkuBl8HgbLgunh5y" "iBdlgdsxn9vl1Qggfc4NaPDkpK" &
& "BVe3We9slESmL=glKl8fiXReQY"

3.1 Trial (Demo) Licences

A trial licence provides limited access to the specified software for an evaluation period. It is indicated by the "TRIAL" keyword, and contains an expiry date and a licence key.

When the evaluation is finished, it is recommended that the trial licence key lines be deleted from the licence file.

3.2 Node Licences

A node licence provides full access to the specified software, on a single machine, for the duration of the licence period. The identification of the machine on which the software is to be run is required for the generation of a licence key; this is produced by the khostid program.

A node licence is indicated by the "NODE" or "NODEG" keyword, and contains an expiry date and a licence key.

When a licence is renewed, the old licence key line must be deleted and the new licence key line inserted.

3.3 Perpetual Licences

A perpetual licence provides full access to the software, on a single machine, for an indefinite period. This requires the machine identification produced by khostid. (Also, perpetual licences are only available for some software products.)

A perpetual licence is indicated by the "FULL" keyword, and contains a licence key but no expiry date.

3.4 Server Redirections

A server redirection line in a licence file instructs Kusari to ask a licence server; it consists of an optional product code, followed by the SERVER keyword and finally a licence server specification. Example server redirection lines are:

NPW3271NA SERVER some-machine.some-company.com:
SERVER another-machine.some-company.com:

The first line redirects Kusari to the named server for the product NPW3271NA only. The second line redirects Kusari to the named server for all products.

4 Licence Servers

Site licences are provided by licence servers; the licences provided by a particular server are contained in its control file.

All site licences provide access to the software to anyone at a site who can communicate with the licence server (over the local network).

Thus successful use of a site licence from a user program requires the following:

1. The licence server must be running on the server machine.
2. The licence key line for the site licence must appear in the control file for that licence server.
3. The user program must have the NAG_KUSARI_FILE environment variable set to refer to the licence server. For example, if the licence server is running on machine ls.fred.co.uk, with the default port number, the NAG_KUSARI_FILE environment variable should contain ls.fred.co.uk:. (Alternatively, NAG_KUSARI_FILE could point to a licence file that contained a redirection line for the server ls.fred.co.uk:.)

The installation process for a licence server is described in the Kusari Installation Guide.

4.1 Floating Licences

A floating licence authorises the licence server to permit up to a specified number of concurrent users of the software.

One licence is required for each combination of user id and machine for which concurrent use is required; for example, two different users on the same machine will require two licences, as will the same user on two different machines. However, only one licence is required for multiple uses by the same user on a single machine.

If the licence server cannot grant a licence request for a product because all of its floating licences have already been checked out, the product will either queue for a licence to become available or terminate with an error message. The default action is to queue for a licence, unless a product-specific option has been used (e.g. for the f95 compiler the -noqueue option) or the NAG_FLOATING_NOQUEUE environment variable is set.

When a program has to wait for a floating licence, it may (depending on the software product) display an informative message indicating that it is queued. This message also indicates the position in the queue. When a licence is finally received, an informative message may be produced; the program will then continue its normal execution.

5 Windows Registry Handling

The klreg program is provided for handling Kusari licences in the Windows Registry. Note that Administrator privilege is required for modifications that affect all users (and that is their default), non-administrator users can only affect the settings for themselves.

This program is a command-line program that must be executed from a command prompt.

5.1 Storing licence information

• To install a node-locked or TRIAL licence for the product AASYSVVPC, stored in the file licence.dat:
  klreg AASYSVVPC licence.dat
• If the licence is stored on a USB key:
  klreg AASYSVVPC @#U
• If the licence is a floating or site licence accessible on server.name.edu:
  klreg AASYSVVPC server.name.edu:

Also, if several licences are in the file licence.dat, they may all be loaded with the single command
klreg -load licence.dat

5.2 Deleting licence information

To delete the information in the registry about product AASYSVVPC:
klreg -delete AASYSVVPC

5.3 Displaying licence information

To display the information in the registry about product AASYSVVPC:
klreg -show AASYSVVPC

To display the information in the registry about all NAG products:
klreg -show

5.4 Options

The following options may be specified for any klreg command.

/allusers

Store, delete or show information for all users (i.e. in HKEY_LOCAL_MACHINE). This is the default for Administrator for the product store commands.

/all_and_current_user

Delete or show information for all users and for the current user (i.e. in both HKEY_LOCAL_MACHINE and HKEY_CURRENT_USER). This is the default for Administrator for the -delete and -show commands.

/current_user

Store, delete or show information for the current user only (i.e. in HKEY_CURRENT_USER). This is the default for non-Administrators.

/help

Display help information.

/overwrite

Overwrite the registry key if it already exists.

/quiet

Suppress informative messages.

/verbose

Produce informative messages. This is the default.

6 Troubleshooting

If the application reports ``Error: Licence file not found'', check

1. The environment variable NAG_KUSARI_FILE is set correctly.
2. The environment variable contains the full pathname of the licence file.
3. The file is readable.