If you are upgrading the file server from one version to the next, note the following:

1. Any client accessing a new version of the file server must be sufficiently licensed for access; unlicensed clients or clients without a sufficient level of licensing will not be allowed access.
2. A higher-level license is required to access the new file server than is required to access the previous version of the file server.

The license required depends on the version of the server that the clients need to access, as listed in Table 1-1, File Server Licenses.

When you plan the migration of the file server, assess the environment and decide the best procedure to ensure that clients who need to access the file server are sufficiently licensed. Upgrade procedures for client-based licenses are described in the following sections:

• Section 2.5.1.1, Configuring Client License Upgrades Individually
• Section 2.5.1.2, Replacing All Licenses
• Section 2.5.1.3, Upgrading Client Licenses Automatically

Individually configuring specific clients to request a new license requires modifying the client configuration for the licenses the client requests. This procedure works best when:

• There are very few clients that will access the new version of the file server.
• Migration of clients to using the new version of the file server will be slow and done over a long period of time.

The procedure for configuring clients individually is described in Chapter 5, Configuring Client Software.

2.5.1.2 Replacing All Licenses

This procedure works best if you choose to remove all the old licenses from the license server system. If some old licenses are still needed on the license server system, in addition to new Client Access licenses, set up automatic license upgrading, as described in Section 2.5.1.3, Upgrading Client Licenses Automatically.

If new licenses have been loaded onto the license server system, the license server, through normal license version look-up procedures, will not find an old license, but will find a new license and assign it to the client instead. See Section 3.3, Controlling License Version Lookup, for a discussion of how license lookup works.

If the old license PAKs are removed from the license server system, all clients that had previously been assigned licenses by this server will automatically have their licenses revoked. The next time these clients attempt to verify their licenses, they will be informed that their previously assigned license is now invalid. The client license requester will automatically attempt to acquire a new license. (Some older client license requesters may need to be manually run again to request a new license.)

2.5.1.3 Upgrading Client Licenses Automatically

By default, the license server will not perform license upgrades. To configure a license server to upgrade licenses automatically, follow this procedure:

1. Load new license PAKs on the license server.
2. Edit the license server start-up command file
   SYS$STARTUP:PWRK$LICENSE_S_START.COM to include the appropriate logical name definition, depending on which licenses will be available:

   License PAK	Logical Name Definition
   PWLMXXXCA06.00	$ DEFINE PWRK$LS_V6_ACCESS_UPGRADE 1
   PWLMXXXCA07.02	$ DEFINE PWRK$LS_V7_ACCESS_UPGRADE 1

   
   Be sure to define the logicals before the following RUN command:

   $ RUN SYS$SYSTEM:PWRK$LICENSE_SERVER

If a logical name is undefined or defined to be zero, the license server will not upgrade licenses to the appropriate new license. If the logical name is defined to be any numeric value other than zero, clients requesting assignment or verification of old licenses will have their licenses upgraded to new licenses, provided sufficient new licenses exist. For more information, refer to your server release notes.

When an upgrade operation occurs, the license server logs both the assignment of the new license and the name of the license returned to the client in the license server log file
PWRK$LOGS:PWRK$LICENSE_SERVER_node-name.LOG.

Configuring the license server to automatically upgrade old license requests affects all clients requesting or verifying a license. If the license server is configured to automatically upgrade licenses, client-based licenses are upgraded to new licenses when either of the following occurs:

• A client requests assignment of an old license.
• A client requests verification of a previously assigned license.

The license server automatically assigns the client a new license (even if it has requested assignment or verification of an old license), and returns an equivalent new license to the client.

2.5.2 Virtual Licenses

Before the introduction of Client Access (CA) licenses, the file server required older style licenses (such as FP or CC licenses). Requests for these older style licenses will be upgraded properly. However, the client will only accept licenses of the type requested with the requested version number or higher. To get the client to accept a Client Access license, the license server returns a different name than that assigned.

If a client requests an earlier form of the PATHWORKS license (such as FP or CC licenses), the upgrade returns a "virtual license," that is, an equivalent Client Access license with a name that does not match the name of the license assigned to the client.

For example, if a client requests assignment of a PWLMXXXFP05.00 license from the license server, the license server upgrades the request to a Client Access license and assigns a new license (if one is available).

From the client's perspective, the license assigned is PWLMXXXFPmm.nn and the client will accept that. From the license server's perspective (as displayed by the License Manager), the client was assigned a PWLMXXXCAmm.nn license. Table 2-1, Virtual License Names, lists the names of the licenses returned to clients due to upgrade operations.

Table 2-1 Virtual License Names

License Requested	License Returned by PATHWORKS for OpenVMS (Advanced Server)	License Returned by Advanced Server for OpenVMS
PWLMDOSCC nn. mm	PWLMDOSCC07.00	PWLMDOSCC07.00
PWLMWNTCC nn. mm	PWLMWNTCC07.00	PWLMWNTCC07.00
PWLMXXXFP05.00	PWLMXXXFP06.00	PWLMXXXFP07.02

When the license assigned is different from the license returned to the client, the license server log file contains two messages:

• One message indicates the name of the license assigned to the client.
• The other message indicates the name of the license returned to the client.

This chapter explains some license server configuration changes you may need to make and the impact of those changes on the client(s). The license server configuration information is explained in the following sections:

• Section 3.1, License Server State Files, describes the contents of the license server state file and describes how to create a new one.
• Section 3.2, Moving a License Server to a Different System, describes the options available to you when you move the license server to a different node.
• Section 3.3, Controlling License Version Lookup, describes how to control the "lookahead" function of the license server.
• Section 3.4, Controlling Where the License Server Runs in an OpenVMS Cluster, describes different configuration options that are available to control which system the license server runs on in an OpenVMS cluster environment.
• Section 3.5, Synchronizing the License Server Database with the LMF Database, describes how the database is synchronized with the LMF database updates that have occurred.

The license server stores information in a database called the license server state file, which exists on the system as:

PWRK$LICENSE:PWRK$LICENSE_SERVER_STATE.DAT

The information that is stored in the license server state file includes the following:

• The names used by the license server that enable clients access to it.
• Information about the types and quantities of client-based licenses that are available to assign to clients.
• License group information.
• A record of the licenses the license server has assigned to clients.

The following sections provide information about the license server state file and describe the procedure for recreating it.

3.1.1 License Server Names

The license server state file stores the name of the license server. This name is used to facilitate communication between the license server and clients. When a client is assigned a license, part of the license information saved by the client is the name of the license server that issued the license. This name is used to contact the license server when the client attempts to verify its licenses. The name is defined in the following format:

PWRK$Lname

When the license server is started for the first time, the template license server state file provided during installation does not contain any license server names. The license server determines its name as follows:

• On a node in an OpenVMS cluster, where an equivalence-name is defined for the logical SYS$CLUSTER_NODE, the node name portion of the value of the equivalence-name is used as the name portion of the license server names.
• On a standalone node, where the logical SYS$CLUSTER_NODE is not defined, the license server uses the value of the SYSGEN SCSNODE parameter as the name portion of the license server names.

In either case, the value chosen as the name portion of the license server names is used to form the license server name, which is then stored in the license server state file. Once established, the license server uses the name stored in the state file, even if the SYS$CLUSTER_NODE or SCSNODE values should change.

3.1.2 Creating a New License Server State File

If the license server state file is rendered unusable, the license server will not run. You must create a new license server state file if this happens. Follow these steps to create a new license server state file:

1. Shut down the license server.
   In a cluster, shut down the license server on all nodes.
2. If the license server state file exists, delete the current license server state file, or rename it to another filename.
   In a cluster, do this on only one node because the state file is common to all nodes.
3. Restart the license server.
   When the license server starts and does not find a license server state file, it creates a new state file, disables itself, and logs a message to the license server log file stating that a new state file has been created and that the license server has disabled itself.
4. To enable the license server:
   1. Invoke the License Manager.
   2. From the Main menu, choose Options.
   3. From the Options menu, choose Server Enable/Disable.
   4. Choose Enable Server.
   5. Choose OK.

Once enabled, the license server determines its name and initializes the license server state file before it responds to any client requests. Refer to Chapter 4, Managing Licenses on the OpenVMS Platform, for information about using the License Manager.

Because the license server begins running with a new license server state file, all information from any previous license server state file is lost, including the license server names, any group information, and all records of client licenses which were previously assigned. If license groups were being used, you must recreate the groups and allocate licenses to them.

When the license server starts with the new state file and determines its name, two possible problems may occur:

• The license server name is the same name as was previously used, but license groups are not defined.
  In this case, any client that was previously assigned a license by the license server fails on its next attempt to verify the license, because the assignment information stored in the previous state file was lost and the client's license is marked as invalid. In this case, the client should attempt to acquire a new license after you recreate the licensing groups.
• The license server name is different than the name previously used, but the client license data file is not updated.
  In this case, clients cannot locate the license server to verify their license because they are attempting to contact the license server using the license server's old name. You should delete the license data file on the client and reboot it so that it attempts to acquire a new license. If the licensing configuration template file specifies a license server name, the configuration file must be changed. Then, when the client looks for a new license, it finds its new name, and it can acquire a new license.

There are two recommended methods for changing the system on which the license server is run. You can move the license server and retain the same server name or you can move the license server and change the server name.

When you move the license server and retain the server name, it is transparent to users. Clients will not notice that the license server has moved.

When you move the license server and change the server name, there is an impact on both server administration and clients:

• You must re-enter all license group information on the new system using the License Manager and you must allocate licenses to each of the groups.
• The original license server revokes client licenses so clients cannot validate assigned licenses on the new server.
• You must keep the original license server running (even though it does not have any licenses it can assign) until all the clients find the new license server.
• The clients must acquire a new license from the new license server.

Use the following procedures for moving the license server and retaining the server name or moving the license server and changing the server name.

3.2.1 Moving the License Server and Retaining the License Server Name

For the purposes of this example, the license server is currently running on a system called SYS1, and the license server is to be moved to a system called SYS2, which is not currently running a license server:

1. Shut down the license server on SYS1.
2. Reconfigure file server on SYS1 so that the license server is not started when the file server is started.
3. Unload and delete all the client-based license PAKs from LMF on SYS1.
4. Register and load all the client-based license PAKs that were deleted from LMF on SYS1 into LMF on SYS2.
5. Install the file server software on SYS2, if not already done.
6. Configure the file server on SYS2 to run the license server, but do not start the license server.
7. Delete any template license server state files on SYS2. For more information, refer to Section 3.1, License Server State Files.
8. Copy the license server state file from the PWRK$LICENSE directory on SYS1 to the PWRK$LICENSE directory on SYS2.
9. Start the license server on SYS2. The license server finds and reads the license server names it was previously using on SYS1 in the state file and continues to use them while running on system SYS2.
   Clients that were assigned licenses by the license server running on SYS1 continue to verify their licenses (or get new licenses) from the license server named "SYS1" running on system SYS2.

For the purposes of this example, the license server is currently running on a system called SYS1, and the license server is to be moved to a system called SYS2, which is not currently running a license server.

1. Install the file server on SYS2, if not already done.
2. Configure the file server on SYS2 to run the license server, but do not start the license server.
3. Shut down the license server on SYS1.
4. Unload and delete all the client-based license PAKs from LMF on SYS1.
5. Register and load all the client-based license PAKs that were deleted from LMF on SYS1 into LMF on SYS2.
6. Start the license server on SYS2, causing the license server on SYS2 to form the license server names using "SYS2" as the node portion of the license server names. These new names are stored in the license server state file on SYS2.
7. Using the License Manager, load the licenses into the license server and define any groups which were defined for the license server on SYS1. This recreates a similar license server state file on SYS2 as was on SYS1, with the exception of the client licenses assigned on SYS1. Refer to Chapter 4, Managing Licenses on the OpenVMS Platform, for information about how to use the License Manager.
8. Start the license server on SYS1, causing the license server on SYS1 to synchronize the count of assignable licenses with LMF. Since all the client-based licenses have been removed from LMF, all licenses previously assigned by the license server on SYS1 are automatically revoked.
9. Leave the license server on SYS1 running until all clients who were issued licenses by the license server on SYS1 discover their licenses have been revoked. Notification that the license has been revoked and is invalid occurs when clients boot and attempt to verify their license. After a client's license is revoked, the SYS2 license server can assign a new license.
   It may be necessary to modify the client template license server state files if the license server name SYS1 was specified.

If there are no available licenses for the version of the server that the client requests, the licensing software looks for a license for a higher version.

By default, the software looks for licenses for subsequent major and minor releases up to 4.3 versions beyond the requested version.

For example, if the request is for Version 5.1, and no licenses are available, the license server looks for the following license versions in the LMF database:

• 5.2, 5.3
• 6.0, 6.1, ..., 6.3
• 7.0, 7.1, ..., 7.3
• 8.0, 8.1, ..., 8.4

You control the version limits by defining the following logical name in the system wide logical name table before starting the licensing software:

PWRK$LICENSE_VERSION_LIMIT

You can define the logical name in two different formats:

• "+MM.mm"
• "MM.mm"

For MM substitute the major release number; for mm substitute the minor release number. The + means that the version is incremental. For example, the highest version searched is the current version plus the incremental version. Without the +, the release number is the absolute value and the search ends at the specified version.

Example 1:

$ DEFINE/SYSTEM PWRK$LICENSE_VERSION_LIMIT "+1.3"

In this example, the license software looks for licenses for one major release beyond the requested version, and for licenses for point releases up to and including .3. If the request is for Version 5.1, and no licenses are available, the license server or License Registrar looks for licenses in the LMF for the following versions:

• 5.2, 5.3
• 6.0, 6.1, 6.2, 6.3

Example 2:

$ DEFINE/SYSTEM PWRK$LICENSE_VERSION_LIMIT "6.2"

In this example, the license software looks for licenses for major software versions up to and including Version 6, and for licenses for point releases up to and including .2. If the request is for Version 5.1, and no licenses are available, the license server or License Registrar looks for licenses in the LMF for the following versions:

• 5.2
• 6.0, 6.1, 6.2

In the case where a client is attempting to acquire a client-based PATHWORKS for OpenVMS (Advanced Server) license and no PATHWORKS for OpenVMS (Advanced Server) licenses are available on the local system, the license lookup function may find an Advanced Server for OpenVMS license for the client if one is available. (Advanced Server for OpenVMS licenses are valid for accessing both PATHWORKS for OpenVMS (Advanced Server) servers and Advanced Server for OpenVMS servers.)

• If the license server determines that no PATHWORKS for OpenVMS (Advanced Server) licenses are available, the license server will begin the lookup process again, looking for Advanced Server licenses (PWLMXXXCAnn.mm).
• If the license server finds an available Advanced Server license, it is assigned to the client and returned to the client.

Installing the license server in an OpenVMS cluster environment provides license service failover in the event that license services terminate on the node running the active license server.

Normally, the license server process (PWRK$LICENSE_S) is started on every node of the OpenVMS cluster that starts the file server, but only one license server process is active at any one time. The other license server processes remain dormant until an event, such as system shutdown or a system failure, causes the active license server process to stop. When the active license server stops, one of the dormant license servers becomes active and continues to provide license services to clients.

In most cases, Compaq Computer Corporation recommends that you run the license server on all nodes of the cluster that run the file server, for maximum availability. The exception is the case where the license server will serve licenses to WAN clients. Then you will want to limit the license server to running on one node of the cluster.

In an OpenVMS cluster environment, the license server state file is maintained cluster-wide. The file server directory tree starting at PWRK$ROOT must be on a disk that is common to all nodes on the OpenVMS cluster.

There are a number of ways to determine which node is running the active license server:

• Use the SHOW SYSTEM command.
  This command displays status information about current processes running on your system. The active license server process is listed as PWRK$LICENSE_S with the state listed as HIB as shown in the following example:

  $ SHOW SYSTEM Pid Process Name State Pri I/O CPU Page . . . 00000230 PWRK$LICENSE_S HIB 6 191 0 00:00:01.67 777 . . .

  
  This example shows only the license server process. A dormant license server is shown with its state indicated as LEF. When you enter the SHOW SYSTEM command, all of the currently running processes on the system are displayed.

• Use the PWSHOW command.
  This command displays information about file server processes that are running on the system. The information is displayed in the same format that the SHOW SYSTEM command produces.
  The PWSHOW command accepts arguments to show processes on a specific node in a cluster and to show all nodes in a cluster as follows:
  • The SHOW CLUSTER command shows all file server processes running on each node in the OpenVMS cluster.
  • The PWSHOW NODE command shows the Advanced Server processes running on system nodename in the OpenVMS cluster.
  
  This command is available after you invoke the PWRK$DEFINE_COMMANDS command procedure. To invoke this command procedure, enter the following command:

  @SYS$STARTUP:PWRK$DEFINE_COMMANDS.COM

• Start the License Manager on a node that is not running the license server and an error message states that the server is running on the nodename system. The License Manager must be run on the same node as the active license server.
  For example, enter the command ADMIN/LICENSE. If the license server is not running on that node, the message shown in Figure 3-1, License Server Startup Error Message, is displayed:

  Figure 3-1 License Server Startup Error Message

  ---

  
• Look in PWRK$LOGS.
  The latest file that matches PWRK$LICENSE_SERVER_OpenVMS-cluster-name.LOG is produced by the active license server and displays the message:

  License server cluster-alias is now processing LAN Manager license requests on node active-node

  
  (The OpenVMS-cluster-name may not be a cluster name, although it most likely is one.)
  You use the TYPE or SEARCH commands to examine the file while it is still open.