NLS Installation and Maintenance Guide This document describes the Network License Server (NLS), and provides instructions for installing, configuring, and using the NLS. You must use the NLS if you have purchased network licenses from Z-Code Software. If you have fixed (or node-locked) licenses, this document does not apply to you. This document has the following sections: About the NLS, which describes what the NLS is. Automatic Installation, which describes the procedure for installing the NLS using the installation script nlsinstall.sh. Manual Installation, which describes the procedure for installing the NLS "by hand," not using the installation script. Registering the NLS, which describes the procedure for registering your NLS software license. Backup Servers, which describes backup NLS servers, why you may want to use them, how to set them up and use them. Tuning the NLS, which describes the procedure for optionally adjusting timing settings of the NLS and logging NLS activity. File Installation Summary, which briefly lists the major steps described in detail in the Manual Installation section. Usage Summary, which summarizes how end users can set up their environment to use the NLS. RS/6000 Users Note If you are installing the NLS software on an RS/6000 system, wherever /usr/lib is specified in this document, use /usr/lpp instead. About the NLS The NLS is an optional software licensing system that allows users on networked computers to share from a pool of Z-Code product licenses. For example, if you have purchased 15 Z-Mail licenses, up to 15 users (but no more) may run Z-Mail simultaneously. The NLS runs on one machine on your network. Users may run Z-Mail with a network license on any machine that can contact the NLS. Network licensing differs from local, or "host," licensing in that a network license allows the users of Z-Code products to exercise their licenses on any networked machine, rather than being restricted to using their Z-Code products on a single machine. Note that the NLS is not needed if your product license is for local use of the product only, i.e., you have only purchased local licenses. The NLS server daemon, zcnlsd, requires only a single data file for operation. This file holds your Z-Code product activation keys, and is by default named /usr/lib/Zmail/license/license.data. This file is created during product installation and registration; you can specify a different location for this file if you wish. To allow the zcnlsd daemon to start automatically on the server machine, several other files need to be present and properly configured. The names and locations of these files vary among different UNIX systems and are described below. At the end of this document is a File Installation Summary, which lists the set of files that may need to be installed or modified. Your system may not require all of these files, and you may not need to make all of the changes listed. See the section Manual Installation on page\x115 for details. Before you start Before installing the NLS, you must unpack and install the Z-Code products you intended to use with the NLS. Refer to the Installation Guide provided with your software package. If you don't have them already, get your activation keys from Z-Code Software at telephone +1 415 898 8649 or e-mail keys@z-code.com. When you request your keys, you will need to provide the following information: The network address of the machine on which you will be running the license server daemon zcnlsd. You can find this out on most systems by executing the command arp `hostname` or grep `hostname` /etc/hosts or, if your system uses NIS, ypcat hosts | grep `hostname` The host id of the server machine. On most systems, you can find this by executing the command hostid. If your system doesn't have a hostid command, tell us the hostname (from the hostname command) instead. Motorola 88K users should usr the hostid program supplied with Z-Mail. RS/6000 users should supply us with the output of the command uname -a. SGI users running IRIX 5.2 (or later) should provide us with the hardware ID. Run the command /sbin/sysinfo, and supply us with the top item in each of the first four columns of output. If you have difficulty determining the ID, run the following command: register -p ZCNLSD Enter any file name when prompted, and then provide the number that appears in parentheses in the second prompt. The network port number that the server daemon will use for connections with Z-Mail. The NLS will be assigned port 2722 unless you specify a different one. You will be given two activation keys (each is a 16-character string of letters and digits). The first is the zcnlsd activation key, which allows the license server daemon to run at the host, network address, and port you have chosen. The second is the Z-Mail (or other product) activation key, which lets the server give permission to a particular version of Z-Mail (or other product) to run. Whenever you license a new Z-Code product or install a new version of a product, you will get a new activation key for it. This activation key is locked to the host id of the server machine, which means it can only be used by the server running there (or by backup servers chained to that machine, as explained in "Backup Servers"). Automatic Installation The NLS is normally installed with the zmail.platform/zcnls/nlsinstall.sh script, where platform is the type of the machine you are installing on. This script can be started for you by the Z-Mail installation script, doinstall.sh. If you chose not to install the NLS when you ran doinstall.sh, you can run the nlsinstall.sh script as follows: Step 1 Log in as root. Step 2 Type the commands (where unpack-dir is the directory where you unpacked your product media, and platform is the type of machine you are installing on): cd unpack-dir/zmail.platform/zcnls sh nlsinstall.sh and follow the instructions. See the section File Installation Summary for a list of the files that are installed or modified by nlsinstall.sh. NIS Users If your system uses the Network Information Service (NIS, formerly "Yellow Pages") to maintain its /etc/services, you'll need to modify the master /etc/services map and distribute it to client machines. Editing the /etc/services file on the NLS server itself will not work if you use NIS, unless the master NIS server is also the NLS server. See the Network Information Service section in your system's network administration manual, or Managing NFS and NIS published by O'Reilly and Associates., for instructions on updating and distributing the /etc/services NIS map. The nlsinstall.sh script will tell you what you need to enter in the master /etc/services NIS map. Manual Installation If you choose not to use the nlsinstall.sh script and instead wish to install the NLS manually, follow these instructions. These instructions assume that you are familiar with basic UNIX system administrative tasks, such as copying and editing files. RS/6000 Users Note that if you are installing the NLS on an RS/6000, replace /usr/lib with /usr/lpp wherever it occurs below. Step 1 Log in as root. Step 2 Copy the zcnlsd program (the NLS server daemon) to the desired location. This program is shipped in subdirectory zmail.platform/zcnls/license/bin, where platform is your system type. zcnlsd is typically copied to /usr/lib/Zmail/license/bin during installation of Z-Mail. The rest of these instructions assume that the zcnlsd binary been copied to /usr/lib/Zmail/license/bin/zcnlsd. If you chose a different directory, substitute its name wherever you see the name of the standard directory below. Step 3 Obtain from Z-Code, and register, your Z-Mail and NLS license activation keys. For details on how to register keys, see Registering the NLS. Step 4 Determine the network port number that the zcnlsd daemon should use for connections with Z-Mail. This port is 2722 unless you asked for a different one when you got your activation keys. The rest of these instructions assume port 2722; substitute yours if it is different. Step 5 If your system has a list of network services in the file /etc/services, and does not use the Network Information Service (NIS), append the following line to /etc/services: zcnls 2722/tcp zcnlsd zserver # Z-Code Network License Server where 2722 should be replaced by the port number that you have selected if it is different. This entry in /etc/services tells your system what service (zcnls) is listening at what port (2722), so that the appropriate daemon (zcnlsd) may be passed requests that arrive at the port. NIS Users If your system uses the Network Information Service (NIS, formerly "Yellow Pages") to maintain its /etc/services, you'll need to modify the master /etc/services map and distribute it to client machines. Editing the /etc/services file on the NLS server itself will not work if you use NIS, unless the master NIS server is also the NLS server. See the Network Information Service section in your system's network administration manual, or "Managing NFS and NIS" from O'Reilly and Assocs., for instructions on updating and distributing the /etc/services NIS map. Step 6 If you want the zcnlsd server daemon to start automatically, you have two options: If your system uses an inetd daemon to manage incoming network service requests, you can add an entry to your inetd.conf file. After you've made the appropriate entry in your inetd.conf, when the first NLS client request arrives on the port described in your /etc/services file, then inetd will automatically start the zcnlsd server to handle the request. Follow the instructions in Step 7 below and skip Step 8. If your system does not use inetd, or you wish to start to zcnlsd daemon when the system boots (not when the first request arrives), you can modify your system's boot-sequence files to cause the zcnlsd daemon to be started at boot time. Follow the instructions in Step 7 and skip Step 8 below. Step 7 To cause the inetd daemon to automatically start zcnlsd when the first NLS client request arrives, you'll need to add an entry to your NLS server machine's inetd.conf (or servers) file. Typically, this file resides in one of the following places: /usr/etc/inetd.conf /etc/inetd.conf /etc/servers Ultrix users Even though Ultrix supports inetd, the inetd for Ultrix version 4.2a and earlier cannot start a tcp service in wait mode as is required by zcnlsd. This means that if you're an Ultrix user, you'll need to follow the instructions in Step 8, which follows later, instead of modifying inetd.conf. Set inetd.conf Add the following line to inetd.conf or services (all on one line): zcnls stream tcp wait root /usr/lib/Zmail/license/bin/zcnlsd zcnlsd /usr/lib/Zmail/license/license.data -inet The paths to zcnlsd and license.data may be different on your system. RS/6000 users If you are modifying the inetd.conf file on an RS/6000, you must additionally issue the following two commands to cause the inetd daemon to accept your changes: inetimp refresh -s inetd RS/6000 users are now finished and should continue with Step 9. Other users should perform the steps in Signal inetd, below. Signal inetd After modifying inetd.conf (or servers), send a HUP signal to the inetd process by using the command kill -1 pid where pid is the process ID of inetd. (You do not need to perform this step on RS/6000 systems.) You can determine the process ID of inetd with the ps command; see your system's ps man page for the proper flags. Step 8 To automatically start zcnlsd during system boot you need to add an entry to your boot sequence file(s) that runs a script which starts zcnlsd. If you decide to use this technique for starting zcnlsd, you don't need to modify your inetd.conf file as described in Step 7. BSD variants If your NLS server machine is a BSD variant, the file /etc/rc starts programs and services during boot. Check that the file /etc/rc exists on your system. If it does not, skip to System V variants, below. First, place the following line in a new file called /usr/etc/rpc.zcnlsd (you can place rpc.zcnlsd in a different directory if you wish): exec /usr/lib/Zmail/license/bin/zcnlsd /usr/lib/Zmail/license/license.data 2722 The paths to zcnlsd and license.data may be different on your system. Replace 2722 with the port number you want zcnlsd to use; 2722 is the default. Make the file rpc.zcnlsd executable (again, note that it may reside in a directory other than /usr/etc) with the command: chmod +x /usr/etc/rpc.zcnlsd On some systems, the file /etc/rc.local is called by /etc/rc to start "local" services, such as zcnlsd. If the file /etc/rc.local exists on your system, add the following line to the end of that file. Otherwise, find the section of the /etc/rc file that runs "local" commands and add the following line to that section: /usr/etc/rpc.zcnlsd Again, the file rpc.zcnlsd may reside in a directory other than /usr/etc. Next, if you've previously installed an older version of the NLS, nlsinstall.sh may have erroneously modified your /etc/inetd.conf file. Examine /etc/inetd.conf, and comment out (or remove) any lines that refer to zcnlsd. After you have completed installation and registration of the NLS on your machine, you may start zcnlsd by issuing the command: /usr/etc/rpc.zcnlsd Continue with the instructions in Step 9. System V variants If you do not have the file /etc/rc on your system, then your system is a System V variant, and you should follow the instructions in this section. First, place the following line in a new file called /usr/etc/rpc.zcnlsd (you can place rpc.zcnlsd in a different directory if you wish): exec /usr/lib/Zmail/license/bin/zcnlsd /usr/lib/Zmail/license/license.data 2722 The paths to zcnlsd and license.data may be different on your system. Replace 2722 with the port number you want zcnlsd to use; 2722 is the default. Make the file rpc.zcnlsd executable (again, note that it may reside in a directory other than /usr/etc) with the command: chmod +x /usr/etc/rpc.zcnlsd Create a new file SXXXzcnls in the directory /etc/rc2.d if the directory exists. Otherwise, create the file in the directory /usr/etc/rc2.d. The XXX in the filename above is a three-digit number that determines in what order the file will be executed during system boot. Give the new file a number higher than all other numbers in the directory so that it executes last. In the new file, place the single line exec /usr/lib/Zmail/license/bin/zcnlsd /usr/lib/Zmail/license/license.data 2722 The paths to zcnlsd and license.data may be different on your system. Change 2722 to the port number on which you want zcnlsd to listen; 2722 is the default. Next, make the new file executable: chmod +x [/usr]/etc/rc2.d/SXXXzcnls After you have completed installation and registration of the NLS on your machine, you may start zcnlsd by issuing the command: /usr/etc/rpc.zcnlsd Thereafter, zcnlsd will be automatically restarted by the init daemon whenever the system is rebooted. Continue with Step 9. Step 9 NLS clients, such as Z-Mail, must be told where the NLS server resides and the port number on which it is listening. Each user of a network Z-Mail license must use one of the following two methods to tell Z-Mail where to obtain the license. Method 1: Use an environment variable. The environment variable ZCNLSERV can be set to the hostname-and- port pair where zcnlsd is listening. For example, in csh: setenv ZCNLSERV servername:port or, in sh or ksh: ZCNLSERV=servername:port; export ZCNLSERV where servername is the hostname of the machine that will be running the zcnlsd daemon and port should be replaced by the port number that you have selected. Depending on your UNIX, it may be possible to set the ZCNLSERV variable in a global initialization file, so all users will automatically have the proper setting without having to modify their personal files: The file /etc/profile is always available for sh users. There is sometimes a file /etc/cshrc or /etc/csh.login where the variable can be set for csh users. If you have backup NLS servers in use, they should be specified in the order they are to be contacted, separated by spaces, and enclosed in one set of double quotes: setenv ZCNLSERV "servername:port servername:port servername:port . . ." Method 2: Use a command line option. You may use the -zcnlserv option on the NLS client's command line. The -zcnlserv option takes the same arguments as the ZCNLSERV environment variable. For example, to tell Z-Mail where to find a network license: zmail -gui -zcnlserv servername:port In the command above, the -gui command-line option must come before any other command line options. Port is optional You can omit the colon and port number from the ZCNLSERV environment variable and -zcnlserv command-line option if at least one of the two following conditions applies: The machine running the client has an entry in its /etc/services file that maps the zcnls service to the port number of the zcnlsd daemon on the NLS machine, or the port number on which the zcnlsd daemon on the NLS machine is listening is 2722. Step 10 To start the zcnlsd daemon manually, give the command: /usr/lib/Zmail/license/bin/zcnlsd /usr/lib/Zmail/license/license.data 2722 where the paths to zcnlsd and license.data may be different on your system, and 2722 should be replaced by the port number on which you want zcnlsd to listen. Manual installation of the NLS is now complete. Registering the NLS If you don't have them already, get your activation keys from Z-Code Software by following the instructions in the section titled Before you start on page\x112. Step 1 If you are registering the NLS on an RS/6000, replace /usr/lib with /usr/lpp wherever it appears below. To register the NLS, you should be logged in to the server machine in an account that has permission to write to the license database file. The default location of this file is /usr/lib/Zmail/license/license.data, but you can change this location if you like. Currently, the name of the file must end in /license/license.data for registering; it can be moved to a different location afterwards if desired. To register the Z-Mail activation key, execute the command zmail -register -f path-to-license.data (replacing path-to-license.data with the name of the file you want to use) or zmail -register to use the default location, /usr/lib/Zmail/license/license.data. You will be prompted for the Z-Mail activation key. You may also be asked for a list of users allowed to use Z-Mail, if your license is user-limited. Follow the instructions the program gives. If you wish to change the user list at some later time, you can run zmail -register again, giving it the same activation key, which will allow you to interactively add and delete users. Editing the license.data file manually is not difficult, but is perilous, since this file is required to be in a strict format. See the section Format of license.data in the Z-Mail Installation Guide for a description of the format of license.data. If you want to run zmail -register non-interactively instead, you can just append the activation key and user names (if any) to the zmail -register command line, separated by spaces. Step 2 To register the NLS activation key, log in to the server machine and execute the command: /usr/lib/Zmail/license/bin/register -p ZCNLSD and enter the license server activation key at the prompt. Note that you should replace /usr/lib/Zmail in the command above with whatever directory you installed the Z-Mail library into during Z-Mail installation. You may also run the register program noninteractively by specifying the activation key on the command line: /usr/lib/Zmail/license/bin/register -p ZCNLSD activation-key If you also have backup servers, follow the instructions in the next section. Backup Servers You only need to read this section if you are licensing one or more backup servers to be automatically used when the primary server is down. About backup servers: The NLS allows a chain of NLS server host addresses to be set up, so that only the most superior zcnlsd daemon (the one nearest the front of the chain that is able to run) will issue licenses. The first address in this chain is the primary NLS; you register it as described above. Backup servers can be added to the end of the chain whenever your site configuration requires it. Common motivations for setting up a backup server chain are: Your server machines go down frequently, or you plan to take a server out of commission and you'd like to avoid reconfiguring everyone's ZCNLSERV environment variable afterwards. Before you start You will need to get an activation key from Z-Code Software corresponding to each backup server you wish to add. Just as for the primary server activation key, you will need to provide the network addresses, ports, and host ids (if they exist) for each additional server being added. Refer to the section titled Before you start for instructions on obtaining keys. You will also need to provide the host id (if it exists; otherwise the hostname) of the primary server machine; since the product licenses are locked to this host id, this will allow the backup servers to provide licenses on the primary server's behalf. The activation key for a server in the chain "knows" about all the superior servers in the chain, and a backup server will not issue licenses if any superior server is running. How to register In the following example, the activation keys for servers on machines named alpha, beta, and gamma have already been registered, and you want to add the machines delta and epsilon to the end of the chain. Hostname Hostid Port Activation Key alpha A_HOSTID 2722 beta 2722 gamma 2722 delta D_HOSTID 2722 D_KEY epsilon (none, use 0) 2722 E_KEY If your database file is ./license/license.data, you would run the following commands to register delta and epsilon, respectively. You may either run these commands on the primary server, and then copy the primary server's license.data to each of the backup servers; or you may run these commands on the backup servers themselves after having copied the primary server's license.data to each backup server. register -p ZCNLSD -v A_HOSTID -f ./license/license.data -hostname delta -hostid D_HOSTID D_KEY -n alpha:2722 beta:2722 gamma:2722 delta:2722 (all on one line), and then register -p ZCNLSD -v A_HOSTID -f ./license/license.data -hostname epsilon -hostid 0 E_KEY -n alpha:2722 beta:2722 gamma:2722 delta:2722 epsilon:2722 (all on one line). "-v A_HOSTID" is the "virtual hostid" of the primary machine alpha; it means the backup servers will give out licenses as if they were alpha. Since epsilon doesn't have a host id, 0 is given instead. Also note that in the register command, you must specify the port numbers of the NLS servers in the chain, even if they are 2722. Testing backup servers If you wish, you may test the operation of your backup servers by temporarily disabling the primary server. There are many ways to disable the primary server; some of them are: Shut the machine down. Disconnect the machine from the network. Comment out the entry in inetd.conf that restarts zcnlsd, send a hangup (HUP) signal to inetd, and kill any existing zcnlsd processes. This will shut down the NLS and prevent it from restarting until you re-enable the entry in inetd.conf and send another hangup signal to the inetd process. Using Backup Servers Set the backup servers up to run exactly as you did for the primary server. More than one server daemon in a chain can run concurrently, but if any of them except for the first running one is asked for authorization to run Z-Mail or Z-Fax, it will redirect the client program to connect to the first running server in the chain (as defined in license.data) to get the actual authorization. This redirection is invisible to the user, and it will only happen if the first server is temporarily not responding or if the user has set the ZCNLSERV environment variable incorrectly. The Z-Code product end user should specify in their ZCNLSERV environment variable every location that is ever likely to be used to contact a license server, so that users' environments will not have to change as the server machines go up and down. For the above example, the user's ZCNLSERV environment variable would be set to "alpha:2722 beta:2722 gamma:2722 delta:2722 epsilon:2722". If alpha and gamma are permanently down, those entries can be omitted, and so the appropriate ZCNLSERV would be "beta:2722 delta:2722 epsilon:2722". If the client machine's /etc/services file contains an entry for zcnls that indicates the port to use on the server, or the server port is 2722, then the port number can be omitted. So in this case, the ZCNLSERV variable could simply be "alpha beta gamma delta epsilon". Tuning the NLS Both the server daemon and the client Z-Code product enforce time limits on their conversation. This section describes the default time limits and how to change them. Server timeout By default, the server allows 31 seconds from the time the connection is established (the server has sent a greeting to the client) until the conversation is completed. You may change this default by invoking the server as zcnlsd -t timeout_value where timeout_value is a number of seconds. Note that -t timeout_value must occur before any other arguments to the zcnlsd command. Client timeouts An NLS client (such as Z-Mail) enforces time limits in three separate stages: time allowed to connect to a particular server port (default 3 seconds) then, time allowed to get greeting from the server daemon (default 20 seconds) then, time allowed to complete conversation after greeting is received (default 29 seconds). If any of these limits are exceeded, the conversation with that server is aborted and the client goes on to try the next server in the ZCNLSERV environment variable (if there is a next server). If no server meets all of the time limits, the client fails to obtain a license and notifies the user. You may adjust these time limits by setting their ZCNLS_TIMEOUT environment variable to the desired three values, separated by commas; the default is 3,20,29. On slow networks, such as global WANs, you may wish to increase these numbers (especially the first) to compensate. Avoid making them too large, however, or users will have to wait an excessive time for the next server in the chain to be consulted if a server is really down. Client logging While experimenting with these parameters, or if you are having trouble running a Z-Code client product with the NLS, try setting the client's environment variable LS_VERBOSE. This will make the client program display detailed information about which servers it is trying to contact and why it is failing. The information is displayed in the output area of the Z-Mail Main window. Server logging To assist in debugging or tuning your NLS setup, you may specify an optional NLS logfile by adding the -logfile log-file option to the command that starts the zcnlsd program. The logfile will contain a log of all transactions the NLS performs. If you send a HUP signal to the zcnlsd process (with the kill -1 UNIX command), it will close and reopen the log- file, removing the previous contents of the log-file. See Command line syntax on page19 for instructions on specifying the - logfile option on the zcnlsd command line. File Installation Summary This section summarizes the default NLS installation. For RS/6000 systems, replace /usr/lib with /usr/lpp wherever it appears below. License Server daemon (this binary may be moved elsewhere if desired): /usr/lib/Zmail/license/bin/zcnlsd License data file (with entries created by zmail -register, and/or register). See the section Format of license.data in the Z-Mail Installation Guide for a description of the format of this file. /usr/lib/Zmail/license/license.data Entry in /etc/services: zcnls 2722/tcp zcnlsd zserver # Z-Code Network License Server Entry in /etc/inetd.conf or /usr/etc/inetd.conf (note, this is a single line): zcnls stream tcp wait root /usr/lib/Zmail/license/bin/zcnlsd zcnlsd /usr/lib/Zmail/license/license.data -inet Usage Summary Specifying the license server and port In csh: setenv ZCNLSERV servername[:portnumber] In sh or ksh: ZCNLSERV=servername[:portnumber] ; export ZCNLSERV On zmail command line: zmail -zcnlserv servername[:portnumber] If you are using backup servers, see Using Backup Servers. Command line syntax The syntax of the zcnlsd daemon's command line is as follows (all on one line): zcnlsd [ -timeout seconds ] [ -logfile log-file ] [ -pid pid-file ] [ -inet ] [ -multithreaded ] license-file port-number Options can be abbreviated to one letter. See Server timeout for more information about the -timeout option, and Server logging for more information about the -logfile option. If -pid pid-file is specified, zcnlsd will write its process-id into the file named by pid-file. This allows you to more easily send signals to the running zcnlsd process. In particular, you may wish to periodically send a HUP (hangup) signal to the zcnlsd process with: kill -1 `cat pid-file` to empty and reopen the log-file (if you specified one when you started zcnlsd). See the kill(1) man page for more information about the kill command. See the ps(1) man page for more information about process- ids. If -inet is specified, then zcnlsd will assume that its standard input is connected to a port, and that it should not try to open the port itself. You should specify the -inet option if zcnlsd is being started by inetd (the method in Step 7), rather than during the boot process (the method in Step 8). If -multithreaded is specified, then every time an NLS client request arrives, zcnlsd will create a new copy of itself to service the request. This greatly improves the performance of zcnlsd when many users are attempting to connect over a large WAN, since they do not have to wait for each other's requests to get serviced. However, if -multithreaded is specified, zcnlsd will not serve floating licenses. DO NOT use -multithreaded if you have floating network licenses! The license-file contains the Z-Code product licenses and user lists; this file is usually /usr/lib/Zmail/license/license.data. This file is where the data you entered with the zmail -register and register programs is stored. The port-number specifies the port on which zcnlsd should listen for NLS client requests. If you do not specify a port-number, then zcnlsd will use the port number specified in the zcnls entry of the /etc/services file, if there is one. If there is no zcnls entry in /etc/services, port-number defaults to 2722.