# Kusari Installation Guide (Unix) Release 2.2

## 1 Introduction

This document is for system administrators. It describes the installation process of the Kusari Licence Management System.

## 2 Overview of Kusari

### 2.1 The `NAG_KUSARI_FILE` variable

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 on a USB key (`#@U`).

File names are for licence files containing keys for trial licences and machine-local (node) licences.

A licence server specification is a machine name or IP address followed by a colon, optionally followed by the port number (see below).

### 2.2 The `khostid` program

The `khostid` program produces the machine identification string.

This is needed for machine-local licences (node licences and perpetual licences); it must be run on the machine for which the licence is intended.

It is also needed for site licences (both floating licences and uncounted site licences); it must be run on the machine which is to be the licence server.

### 2.3 Licence server communications

In this release, the licence server will refuse to communicate with a machine on the other side of a NAT (network address translating) router. The `testserver` and `testclient` programs may be used to check that communication to a licence server can be successfully established.

## 3 Package Contents

The distributed Kusari licence server package contains the following subdirectories:

bin
  The executable files: `khostid`, `klcheck`, `kldctl`, `naglmd`, `testclient` and `testserver`. We recommend that these be installed into the directory `/etc/NAG`.
doc
  The documentation; this includes the Installation Guide in both PDF and HTML (`k-install.pdf` and `k-install.html`) and the User Guide in both PDF and HTML (`k-using.pdf` and `k-using.html`). It may also contain system-specific installation instructions in a file named `install-`systemname`.txt`; if this exists it will be a plain text file which should be read together with this Installation Guide.
other
  This subdirectory, if it exists, contains other system-specific files to help with Kusari installation and operation. They will be described in the system-specific installation guide in the `doc/` subdirectory.

## 4 Recommended procedure

The recommended installation procedure for a site licence, where no Kusari licence server is currently being run, is as follows:

1. Test the local network to ensure that licence server operation is possible, using the `testserver` and `testclient` programs.
2. Use the `khostid` program on the server machine and send its identification string, and the desired port number (if different from the default, see section 5.3), to NAG.
3. When you receive the licence key(s) from NAG, save them to the server control file.
4. Start the `naglmd` licence server on the server machine.
5. Update the server machine's boot or startup scripts so that `naglmd` will be run automatically.

If the server machine is already running `naglmd`, the procedure is simpler:

1. There is no need to test the local network, since it is already known to be working acceptably.
2. Use the `khostid` program on the server machine and send its identification string, and the port number that `naglmd` is already using (if different from the default, see section 5.3), to NAG.
3. When you receive the licence key(s) from NAG, append them to the server control file.
4. Stop and restart the `naglmd` licence server.

## 5 Testing the local network

Two programs are supplied for testing the local network, these are `testserver` and `testclient`.

### 5.1 The `testserver` program

The `testserver` program should be run on the server machine. If it starts successfully, it will produce the message

    [testserver started]

If the server cannot start, it will produce an error message. The most likely error messages are either

    ?Port number conflict: TCP port 7733 is already in use

or

    ?Port number conflict: UDP port 7733 is already in use

These indicate that the default Kusari communication port number is already in use by another application on the server machine, and that another port number should be chosen. The procedure described below (``Choosing different port numbers'') should be followed.

Once the `testserver` program is running successfully, the `testclient` program should be used to test communications. An initial test should be to run the `testclient` on the server machine; if the default port numbers are being used, simply run `testclient` with no arguments.

The `testserver` program will produce informative messages when `testclient` is run, if communications can be established. A message is produced for each of the TCP and UDP tests; for a completely successful test it will display

    TCP message test seems ok - reporting to testclient
    UDP test passed ok - reporting to testclient

If the TCP test passes but the UDP test fails, the second line will instead be

    UDP test ****** FAILED ******

The `testserver` program will exit on receiving an interrupt signal (`SIGINT`), e.g. by typing Ctrl-C on its terminal or into its window. The `testserver` program must be terminated before attempting to start `naglmd`.

### 5.2 The `testclient` program

The `testclient` program tests the communication between a client machine (one that will be running the software product) and the licence server machine. First, the `testserver` program should be running on the licence server machine. Then, the `testclient` program should be run. Its command line is:

`testclient` server-spec

The server-spec takes the same form as in the `NAG_KUSARI_FILE` variable, i.e. the server machine name followed by a colon, optionally followed by the port number. If no server-spec is present, it is treated as `localhost:`.

If the `testclient` program cannot connect to the `testserver` program, it will produce the message:

    ?Test FAILED - cannot connect to server
    (Perhaps it is not running, or on a different machine?)

You should check that you have specified the right machine name, and that either you are using the default port numbers or have specified the same port number for `testclient` as you did for `testserver`.

If both the TCP and UDP tests pass, `testclient` will display

    TCP message test passed ok.
    UDP message test passed ok.

If the UDP test fails, the second line will be replaced by

    UDP message test ****** FAILED ******

If your site has multiple sub-nets, the `testclient` program should be run on a machine in each sub-net to confirm that it will work.

If you cannot get the `testserver` and `testclient` programs to communicate successfully, you should contact NAG with the exact messages that were produced.

### 5.3 Choosing different port numbers

Decide which port number to test; you should avoid any port number that is already in use or which may be in use; see the list maintained by the Internet Assigned Numbers Authority for guidance: this may be found at http://www.iana.org/assignments/port-numbers.

The procedure specified above for using `testserver` and `testclient` should be followed, but with the port number specified. For `testserver`, use the -port option; for example, to test port 7734, do

      testserver -port 7734

For `testclient` program, specify the port number as part of the server name; for example, to communicate with the server on port 7734 on the local host do

      testclient localhost:7734

Note: The server licence key you will receive is always for a specific port number, and will not work with any other port number.

## 6 The server control file

The server control file contains all of the licences that will be controlled by the `naglmd` licence server, and may contain other control information as detailed below. This file is only read by the `naglmd` licence server, not by user applications, and should therefore not be referred to by the `NAG_KUSARI_FILE` variable.

### 6.1 Server licence key lines

There are two kinds of server licence: uncounted and floating.

#### 6.1.1 Uncounted Licences

An uncounted licence authorises the licence server to allow any number of concurrent uses of the software.

It is indicated by the `SITE` or `SITEG` keywords, and contains the expiry date and a licence key.

#### 6.1.2 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.

By default, products will queue for a licence if all the licences are currently checked out. An informative message may be produced (depending on the software product) when this happens.

A floating licence key line is indicated by the `FLOATING` or `GFLOATING` keywords, and contains the number of licences available, the expiry date, and a licence key.

### 6.2 The `LOG` line

The `LOG` line specifies the log file for `naglmd`. It begins with the `LOG` keyword, which is followed by a blank and then the filename. If the `naglmd` command line contains the `-log` option, the `LOG` line will be ignored.

If no `LOG` line is present, and the `-log` option is not used, `naglmd` will log any errors and information messages (such as licence requests) using the syslog facility. Errors will be logged with level `LOG_ERR`, warnings with `LOG_WARNING`, and information messages with `LOG_INFO`. Whether and how `syslogd` records these messages is governed by its own configuration: see the man pages on syslog, syslog.conf and syslogd for further information.

Any errors writing the log file will be reported to syslog, and execution will continue.

### 6.3 The `PORT` line

The `PORT` line specifies which TCP and UDP port numbers are used by `naglmd` for communication. This line is only very rarely needed, when there is a conflict between the default port numbers used by `naglmd` and another application running on the server machine. It begins with the `PORT` keyword, which is followed by a blank and then the TCP port number (this number must lie between 1025 and 49151). If the UDP port number differs from the TCP port number, it should be specified on the same line; it is separated from the TCP port number by a comma, and consists of the letter `'U'` followed by a number between 1025 and 49151.

Licence keys issued for one pair of port numbers will not work on any other ports.

### 6.4 Comments

A server control file may also contain blank lines and comment lines. Each comment line begins with a `'#'` or `'!'` character, and is completely ignored.

### 6.5 A sample server file

    ! This is where we want the log file to be written.
    !
    LOG /var/log/naglmd.log

    ! We have a site licence for the NAG FL90 library (Mark 4) on Linux,
    ! using the NAGWare f95 compiler.
    !
    FNLUX04DN SITEG 2006/12/31 "AidmYczVlY+hF9c1qhDydOja"

    ! We have 10 floating licences for the NAGWare f95 compiler on Linux:
    !
    NPLUX50NA FLOATING=10 2006/12/31 "vKmOEjxwkeVjcjjkJgGuoW0k"

    ! And that's all folks.

## 7 Running the licence server

Each `naglmd` licence server can only be run on its specified server machine, and the server machine can only run one `naglmd` server at a time. When run, it reads its server control file (by default this is located in `/etc/NAG/naglmd.ctl`).

If no errors are detected in the options or the control file, it will then detach from the controlling terminal and run in the background as a daemon; this will return you to the shell command prompt. No output is produced if the startup is successful; any errors encountered after startup will be written to the log file or reported to syslog.

The process id of the `naglmd` daemon is stored in `/tmp/naglmd.pid`.

`naglmd` normally logs all licence requests (whether granted or not), and any errors that might occur.

`naglmd` can be shut down by using the `STOP` command to `kldctl`. `naglmd` can also be shut down by sending it an interrupt signal (SIGINT) or terminate signal (SIGTERM), but this is not recommended.

### 7.1 User id

`naglmd` need not be run under the `root` user id; it will run successfully as long as it can read its control file and write messages to its log file. (However, it is safe to run `naglmd` as `root` because it only reads from its own control file and writes to its own log file.)

### 7.2 Options

-file slfile
  Read the server control file slfile instead of `/etc/NAG/naglmd.ctl`.
-help
  Display brief help message listing the possible options for `naglmd`.
-log logfile
  Write log messages to logfile. Errors attempting to write to the log file will be reported to syslog. This option overrides any `LOG` line in the server control file.
-nodetach
  Run the licence server directly on the controlling terminal, do not detach and run as a daemon.
-nolog_requests
  Do not write information about licence requests to the log file, only error and status messages.
-port number
  Use TCP port number instead of 7733. This option is overriden by any `PORT` line in the server control file.
-uport number
  Use UDP port number instead of 7733. This option is overriden by any `PORT` line in the server control file.
-V
  If this option is supplied as the only option to naglmd it will display version information consisting of the Kusari Release numbers, and then exit. It cannot be supplied at the same time as any other option.

### 7.3 Automatic startup

It is recommended that `naglmd` be started automatically on the server machine. This can typically be achieved by adding its startup command to a system initialisation file such as `/etc/rc.local` (details vary depending on which version of Unix is being used). If the server control file is in the default location (`/etc/NAG/naglmd.ctl`), and contains a suitable `LOG` line, e.g.

    LOG /var/log/naglmd.log

then the startup command can be as simple as

       naglmd

## 8 Utility Programs

The `klcheck` program takes a single argument which is a NAG product code. It then attempts to check out that product and reports whether it was successful, and if successful the type of licence it obtained and from where.

The `kldctl` program is provided for controlling `naglmd`. It takes a command as its first argument. The `PLIST` command lists the product which are controlled by a particular `naglmd`. The `PINFO` command has a product code argument, and lists the details for that product on `naglmd`. The `REREAD` command causes `naglmd` to reread its control file. Finally, the `STOP` command shuts `naglmd` down.

The `PLIST` and `PINFO` commands can be used anywhere by anyone, but the `STOP` command can only be used on the machine running `naglmd`, and only by the same user.

The optional second argument is a licence server specification, as defined above, which only needs to be provided for a remote server or a non-default port number on a local server.

## 9 System-specific Installation

Further system-specific installation information may be available; see the appropriate document (e.g. for FreeBSD 5.x, see install-FreeBSD5.txt).