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.

A file name can contain any printing character except comma (,), semi-colon (;), at-sign (@), or colon (:). For example, /somedirectory/somefilename.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, Kusari will look for the files nag.key, nag.licence and nagware.licence (in that order) firstly in the current working directory and secondly in the user's home directory. Depending on the software product it might also look for these files in the product's installation directory.

The environment variable may be set by the setenv command in the C-shell, e.g.

               setenv NAG_KUSARI_FILE mylicence.data

or by the export command in the Bourne shell, e.g.

               export NAG_KUSARI_FILE=mylicence.data

3 Single machine licences

Single machine licences are provided in licence files, 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
NPL6A71NA FULL "qfrdwhyMoQFkfpm5e6ESprJmtE"

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

! A licence for the NAG Library on this machine, Mark 29:
NLL6I29NA NODE 2024/01/01 "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.

NPL6A71NA 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,

NPL6A71NA 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:

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

The first line redirects Kusari to the named server for the product NPL6A71NA 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 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.