This document is for system administrators. It describes the installation process of the Kusari Licence Management System.
NAG_KUSARI_FILE
variableNAG_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).
khostid
programkhostid
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.
testserver
and testclient
programs may be used to check that
communication to a licence server can be successfully established.
The distributed Kusari licence server package contains the following subdirectories:
khostid
, klcheck
,
kldctl
, naglmd
, testclient
and testserver
.
We recommend that these be installed into the directory /etc/NAG
.
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.
doc/
subdirectory.
The recommended installation procedure for a site licence, where no Kusari licence server is currently being run, is as follows:
testserver
and testclient
programs.
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.
naglmd
licence server on the server machine.
naglmd
will
be run automatically.
If the server machine is already running naglmd
, the procedure is
simpler:
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.
naglmd
licence server.
Two programs are supplied for testing the local network, these are
testserver
and testclient
.
testserver
programtestserver
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 useor
?Port number conflict: UDP port 7733 is already in useThese 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 testclientIf 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
.
testclient
programtestclient
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.
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.
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.
It is indicated by the SITE
or SITEG
keywords, and contains the
expiry date and a licence key.
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.
LOG
lineLOG
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.
PORT
linePORT
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.
'#'
or '!'
character,
and is completely ignored.
! 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.
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.
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.)
/etc/NAG/naglmd.ctl
.
naglmd
.
LOG
line in the server control file.
PORT
line in the server control file.
PORT
line in the server control file.
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.logthen the startup command can be as simple as
naglmd
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.
Further system-specific installation information may be available; see the appropriate document (e.g. for FreeBSD 5.x, see install-FreeBSD5.txt).