Administrator's Reference
|
|
|
KeyServer ® Administrator's Reference |
| |||
| Home | Support | Legal | Contact Us |
|
Getting Started |
|
Welcome to the KeyServer. The KeyServer Package has been carefully designed to facilitate management of the licenses for an entire software library distributed throughout a network of computers. The KeyServer Package can be used to:
In this Getting Started document, "you" refers to the KeyServer Administrator, the person who will be setting up the KeyServer. You will find that KeyServer greatly simplifies software license management while promoting efficient utilization of the software assets that have been purchased for your site. It gives you the technology to enforce multiple license agreements, while it gives licensed users transparent access to managed software.
KeyServer 5.1 is distributed on a multi-format compact disk (CD) which is readable on Windows, Macintosh, Unix, and Novell NetWare systems. The CD mounts with the volume name "Sassafras Software" and you will see that it contains a single, date-stamped, folder named "KeyServer 5.1 (yyyy-mm-dd-image). The date stamp appended to the folder name is called the "image date" and it is used to identify the complete set of installers and documentation assembled together to form this particular "KeyServer 5.1 image".
The image folder includes complete documentation and a complete set of installers for all platforms. You can easily copy the entire contents (~12 MB) onto a hard disk or file server volume, or you can duplicate individual installers as needed.
 | When the Sassafras CD is mounted as a Macintosh volume, the Macintosh installers will be directly executable. But when the CD is mounted as a Windows volume, the Mac installers become data files with .bin appended to the Mac file names. Use Stuffit Expander to convert to or from MacBinary format whenever you move a Macintosh executable (e.g. an installer.sea) between a Macintosh and a non-Macintosh file system. |
The documentation folder in a KeyServer 5.1 image contains files in both HTML and PDF formats which constitute the "Administrator's Reference" for KeyServer. The organization and content is essentially identical in the two formats: HTML documents are formatted for computer viewing, while PDF documents are formatted for printing. The Administrator's Reference (HTML version) is also viewable on-line from the Sassafras web site.
Use the open command from any web browser (e.g., Netscape Navigator or Internet Explorer) to read the local HTML files which are identified by the .htm suffix. Use Acrobat Reader, available from www.adobe.com, to open and print files named with the .pdf suffix. Standard hypertext conventions are used within the documentation folders to link the various documents and to aid in navigation. Hence the documents are best kept in their folder hierarchy without change to document names or location.
The descriptions below give an overview of where to find information on various aspects of KeyServer:
When you need to go beyond the most basic KeyServer operation, and for details on how to fully implement a particular management strategy, the chapters included in the Getting Started book won't be sufficient -- consult "KeyServer in Detail" and subsequent chapters of the Administrator's Reference.
The more intricate procedures required to upgrade from old KeyServer 4.x versions are detailed in the appendix: "Upgrading from 4.x". Both the Upgrades chapter and the Upgrading appendix are included in the printed Getting Started book. Also included are appendices which outline new features and feature changes introduced in KeyServer 5.0 and 5.1.
Whenever possible, KeyServer documentation is generic so it applies to all supported platforms. Fortunately, the KeyServer process itself works in the same way without much, if any, interface on Windows, Macintosh, Linux, NetWare, and Mac OS X Server. Hence the only platform specific documentation needed is for installation. As a convenience during installation, the appendix documenting operating system specific details is included in the Getting Started book. But remember you only choose one of these platforms to host your KeyServer!
KeyServer's Administrative and Client components are restricted to Windows and Macintosh, where they are licensed for simultaneous use on multiple computers. The exact details of the user interface and component file names differ between operating systems, but most often these differences can be ignored.
 | When it is necessary to explicitly document operating system differences, the Windows and Macintosh icons will be used to tag the system specific details. In electronic versions of the documentation, details may sometimes be hidden behind hypertext links. In printed versions, you may want to treat the operating system icons as a signal to skip over the text, depending on your platform focus. |
The software component files created by various installers fall into three main categories depending on function:
The generic names KeyServer, KeyConfigure, and KeyAccess are used to refer to the software which implements server, administrator, and client functions respectively. On the Macintosh, the generic name matches the file name of the component implementing each function. On Windows, each function is typically implemented by several files with 8.3 formatted names, so the installer creates shortcuts named KeyServer, KeyConfigure, or KeyAccess for use from the Start Menu or Program Manager. (For a complete list of component file names with version information, consult the Component History document referenced from the readme.)
The word "server" is used to refer to the KeyServer process running on a single computer. When the KeyServer program is launched, the KeyServer process becomes active so license requests from client computers can be serviced. There is no "network operating system" or file server requirement. Run KeyServer on a single computer to turn it into a "license server" which supports both Windows and Macintosh clients.
The KeyServer computer may be an individual user's workstation, it may be a computer dedicated to running the KeyServer program, or it may be a general purpose network services computer that is simultaneously acting as a file server, print server, ftp server, web server, router, etc. The KeyServer process listens to the network wire much like a router process. It can respond to each client using the appropriate protocol: TCP/IP, IPX, or AppleTalk.
The "key" in the word KeyServer refers to approximately 1K of information which is excised from each "keyed program" and then stored on the KeyServer computer. When you launch a keyed program, its "key" must be received by the client computer and reassembled into the program before the launch can proceed -- the network KeyServer maintains tight control over the program launch. Details of the KeyServer implementation have evolved over the past 10 years to include many variations on this simple idea, but the functional behavior remains the same. One particular enhancement, introduced in KeyServer 5.0, allows you to control unkeyed programs in the same way you control keyed programs.
The word "client" is used to refer to each end-user computer that has KeyServer's client software, KeyAccess, installed. Without KeyAccess, a keyed program cannot run. Usually client computers are connected to the KeyServer through some form of network connection. This could be a local ethernet LAN connection, a global WAN connection, an Internet connection, a dial-up link, etc.
A "mobile client" or portable laptop computer must "check out" software licenses for use where there is no network connection (e.g. offsite). The KeyCheckout program lets the user specify a particular expiration time for "portable keys" used on the mobile client computer.
The word "network" refers to the physical system of wires, hubs, repeaters, bridges, routers, relays, and other hardware that conveys data packets from computer to computer. A "network connection" does not imply the existence of any file server or other network services. In particular, we are not implying the existence of a "network operating system" (NOS). A mixed network of Windows and Macintosh computers can communicate without any NOS and KeyServer does not require one. The common phrase "log onto the network" is actually a source of some confusion and should more accurately be "log onto the network file server" or "log onto the file server". Again, for us, the word network does not imply a file server.
While the server, administrator, and client functions are often thought of as running on three separate computers, this is not a requirement. A single computer can have software installed to perform all three functions. Typically the KeyConfigure administrative software will be installed on several computers that are also functioning as clients.
| It may be convenient to install KeyConfigure on the computer functioning as the KeyServer, but this is not necessary -- and it is only possible in cases where the KeyServer is hosted on Windows or Macintosh. |
In addition to the main component files described above, the KeyServer Package includes several utility components including:
There is a readme file at the top level of any KeyServer 5.1 image folder that links to a document describing the latest revision details (current as of the image date) for every component that may be installed using one of the installers. If your browser is connected to the internet when you open the readme, icons will inform you which, if any, of the installers in the image folder have become obsolete.
The readme includes a link to the Sassafras web site for downloading a compressed archive (~8 MB) containing the most recent KeyServer 5.1 image. When you expand a compressed image archive, it will look on your hard disk for a previous image folder named "KeyServer 5.1(yyyy-mm-dd-image)" so that obsolete items can be replaced. If a previous folder is found, the name will be changed to reflect the new image date. Otherwise a completely new folder is created.
The files and directory hierarchy created by expanding a downloaded image archive will match the file and directory structure in the CD. In particular, there will be a new README.htm which documents the new image contents. Regardless of its source, the README.htm inside each particular KeyServer 5.1 image gives you a quick way to check on revision status and to obtain updates when necessary. With the convenience of web updates, you should regard the CD and its README.htm file as only a starting point for obtaining KeyServer software.
When you purchase KeyServer and submit your e-mail address as the registered contact, a custom License Certificate file, server.lic, containing serial number and client count will be e-mailed to you. Without this file, any installer from the Server Installers folder (inside the KeyServer 5.1 image folder) will create a KeyServer operating only in "evaluation mode" -- the functionality and number of clients supported will be limited.
A custom server.lic file must be placed in the KeyServer Data Folder in order to upgrade your KeyServer installation from evaluation mode to a full function KeyServer with support for a custom number of clients. Read the "Server Install - KeyServer" section of the "Installation" chapter for detailed instructions.
| Even though the KeyServer 5.1 image contains installers for creating the server process on several different platforms, you must choose only one computer to host your KeyServer. Regardless of host platform, KeyServer will meter both Windows and Macintosh clients. |
The License Certificate, server.lic, and the KeyServer serial number are authorized for use on one single computer. You may not make copies except for backup purposes. It is the obligation of the licensee to protect the license certificate from theft, from unauthorized use or copying, and from use on more than one single computer.
| In addition to the legal prohibitions, usage of the same server.lic file on more than one computer can lead to erratic and unpredictable behavior for both client and administrative software components. |
If the KeyServer executable does not find a valid server.lic file in the KeyServer Data Folder, it will instead use the file named eval.lic which was created by default as part of the server install. As the name implies, the eval.lic file will enable KeyServer to run only in "evaluation mode". You can read the text of the eval.lic file for particular features restricted by the "evaluation license", but typically evaluation mode supports only 10 clients, some features are disabled, and you can control only a limited number of programs. The evaluation will stop supporting clients approximately two months after the release date of the image that produced it.
Except for the limitations imposed by the eval.lic, installation and operating instructions for a KeyServer evaluation are the same as for the fully licensed version. If you need to evaluate KeyServer without any size or feature restrictions, contact Sassafras Software.
Always start by using your browser to open the README.htm file at the top level of the KeyServer 5.1 image folder. This will point out any last minute cautions, notes, or corrections that may help avoid wasted time or aggravation. The readme also gives a short description of all the components in the image along with the revision status of each installer.
Note that you can tell which installer is appropriate to use on each platform based on the file extension:
| Most of this documentation is written from the point of view of the Windows or Macintosh operating systems. For specific information on Thin Client installs (WTS and WinFrame), other server platforms (NetWare, Linux, Mac OS X Server), and for command line switches etc., always check the OS Details section. |
 | If a Mac installer is stored on a non-Mac file system, it will be stored as data in MacBinary format with the extension .sea.bin. On a Macintosh, use Stuffit Expander to extract the .sea executable from the .sea.bin MacBinary file. |
The KeyServer image includes installers for several distinct functions:
All of these functions are implemented for both Windows and for Macintosh. In addition, the server function (KeyServer itself) is implemented for several other host operating systems. Each distinct function on each distinct operating system has its own installer. A complete set of installers (all functions, all platforms) together with a complete set of documentation (both HTML and PDF formats) constitutes a "KeyServer 5.1 image".
The Client Installers are typically required for use on several computers - perhaps thousands. It may be convenient to copy them onto a shared file server so that anyone can easily access the appropriate installer program to set up their own computer as a client. Access to the Admin installers should be restricted to appropriate personnel (perhaps just to yourself). You need only one of the server installers and it can be run directly from the CD (assuming it's current) with no need to copy it elsewhere.
The next sections give specific hardware and software requirements for each type of install.
| It is assumed in this chapter that you are installing for the first time. If a prior install exists on a target drive, the installers will attempt to replace obsolete components. See the "Upgrading" chapter for special cautions to avoid losing any of your custom configuration data, especially for the server process. |
A few Windows or Macintosh specific issues that you may need to consider before picking a server host are detailed below. As a general rule, Admin and Client components tolerate typical environments without any side effects.
A single KeyServer will effectively manage software licenses at sites supporting from 10 to 10,000 or more computers. KeyServer's scalability is achieved by directly accessing the basic network protocols (TCP/IP, IPX, and AppleTalk). Communication between the license server and its clients does not use any higher level file server or Network Operating System (NOS) services. Hence standard network wiring and routing between machines is all that is required to support clients spread across the globe. You don't need a file server.
To run the KeyServer process, you should choose a single computer (Windows, Macintosh, NetWare, Linux, Mac OS X Server) that is in a robust location on your network. Client computers must be able to exchange network packets reliably with the KeyServer machine at all times. This computer should be secure from unauthorized users. It should be turned on at all times and not subject to frequent restarts or reconfiguration. If you are already running a file server on some computer, this may be the logical place to put the KeyServer so that one secure machine is supporting multiple network services.
| If KeyServer will be supporting clients over TCP/IP, its address should be static. It will be convenient to register a name for this IP address with your Domain Name Server so clients can locate KeyServer using the DNS name instead of the raw IP address. |
KeyServer running on any platform will simultaneously support multiple network protocols serving both Windows and Macintosh clients. However, there are some restrictions on which protocols can be used by specific components on the various platforms.
| Windows clients can use IP or IPX (not AppleTalk). |
| Macintosh clients can use IP or AppleTalk (not IPX). |
| If KeyServer is run on Windows, all Macintosh clients must connect using TCP/IP. Even if you have AppleTalk installed under Windows NT, neither the Windows KeyServer nor the Windows client can make use of it. Of course these Macintosh clients can still use AppleTalk and IPX for other network services. |
The processor demands of KeyServer are minimal. A slow computer will suffice and there will typically be power left over to run user programs or other services at the same time. Many sites find it convenient to run the KeyServer process on a general purpose, network services computer that is also set up as a mail server, print server, file server, fax server, web server, etc. In such an environment, KeyServer will typically be the least demanding of processor overhead. An alternate strategy is to put only a few services on several inexpensive computers both for redundancy and so that reconfigurations and restarts don't affect all processes at once.
| Remember that we use the word "server" to mean any computer that is hosting a network service such as the KeyServer process. KeyServer does not require a "file server" or "network operating system", but it will manage license compliance for programs stored on multiple local volumes and multiple file server volumes. |
The amount of disk space required for logs is highly dependent on exactly how logging is configured, especially logging of unkeyed programs. A KeyServer supporting several thousand clients may generate several megabytes of log information per day. A several hundred client KeyServer will require proportionally less space, perhaps one megabyte per week. Eventually you may want to customize the level of logging detail or configure KeyServer to store logs on a remote volume, but it will be most convenient to initially set KeyServer up with space for at least several weeks' worth of standard logs.
The RAM requirement for KeyServer depends both on the number of clients it is configured to support and on the number of Controls that have been set up to manage programs. Allow 1.5 MB memory for up to 1,000 clients plus at least 0.5 MB for each additional 1,000 clients.
Since KeyServer is as a very 'light-weight' process and the implementation on all platforms is compiled from the same code base, the one criteria in choosing a host (other than AppleTalk or IPX support) is convenience.
Installation of the license server itself (that is, the KeyServer executable program) is unique in that you only do it once, and only on one computer. This one computer also requires a license certificate file, server.lic, in order to enable KeyServer with a unique serial number, proper client count, and other parameters. If you choose Windows or Macintosh as the server platform, you can install the administrative components on this same computer but this is not required since remote administration is just as effective.
|
It is important to emphasize that KeyServer runs on a single computer to
support both Windows and Macintosh clients. Use of the same license certificate
on two or more computers at once could lead to unpredictable behavior for both
client and administrative software.
If you are upgrading from version 4.x or 5.0, you will need a new version 5.1 server.lic file. Consult the "Upgrades" chapter below for details on how to avoid losing your existing configuration data or support for existing clients when upgrading. |
The first step in installing a new KeyServer is to choose a host platform and then run the appropriate installer from the Server Installers folder (in the KeyServer 5.1 image folder).
When the installer is finished, there is still one more step required before launching KeyServer: You must install your custom license certificate file, server.lic, in order to enable full KeyServer functionality with the proper number of clients.
| For evaluation you don't need a server.lic. Without it, KeyServer will use instead the default file, eval.lic, which was created by the installer. See the "KeyServer Evaluation" section above for a description of restrictions imposed by the default evaluation license. |
You obtain your custom license certificate from Sassafras as an e-mail message. The e-mail explains how to save the license certificate as a file named server.lic and then copy it into the KeyServer Data Folder. For the record, a printed copy of the server license is included along with the Getting Started book and the Sassafras CD when you order a new KeyServer. In theory you could recreate the server.lic file from the printed copy, but it is much easier to register your e-mail address when ordering so you can use the e-mailed license file.
| The server.lic is a text file readable by any text editor. You must not save it in any format other than text nor alter it in any way. If it does become altered, KeyServer will regard the file as "not valid". This will have the somewhat unexpected consequence that KeyServer will then attempt to find another valid license such as the eval.lic file to use instead. |
| If you have configured Windows to "hide file extensions for known file types", the actual name assigned when saving a file can be a surprise. When you instruct a save dialog to use the name "server.lic" while saving as text, what you end up with is a file named "server.lic.txt" -- even though in Windows Explorer it appears to be named "server.lic". KeyServer will not find the file until you remove the .txt extension from the full name. |
Regardless of platform, the server installer creates a folder containing the executable program, KeyServer, and a sub-folder, "KeyServer Data Folder". Copy the server.lic file into the KeyServer Data Folder. It is not necessary to remove the eval.lic file, since the server.lic will take precedence. If there is already a server.lic file in place, be careful! You will have to figure out whether to replace it. If this is an upgrade install, see the "Upgrades" chapter.
After installation, the KeyServer program must be launched (either manually or automatically) in order to begin supporting client connections. For robust service, make sure the operating system is configured to automatically launch the KeyServer program whenever the host is restarted. The installers for Windows and Macintosh automatically place a shortcut or alias into the system startup folder.
| It is important to consult the OS Details appendix in the Administrator's Reference for specific launch options available under each operating system and for details on which options are set up by the installer for automatic KeyServer startup (if any) when the host is re-started. |
When launched, the KeyServer process will activate in one of three states:
On some of the host platforms, there is a minimal status screen which displays the KeyServer state, but on others the state is only reported to a console or error log. On Windows and Macintosh, the installer lets you choose whether to run KeyServer in foreground or as a background service. For more information, read the OS Details appendix of the Administrator's Reference.
| Caution: if you launch KeyServer on a computer that is already running a KeyServer process (either in foreground or background), things can become confusing. Depending on the operating system, you may or may not get an error message and various network protocols may or may not communicate as expected. Always shut down any running KeyServer process before launching the KeyServer program. |
In addition to the states listed above, the KeyServer program has another behavior when there is a "shadow" license installed. You create a shadow.lic (based on your server.lic) in order to enable a "shadow" process for your KeyServer on a separate computer, thus giving clients emergency service in case of a network failure. Consult the "KeyShadow" chapter in the Administrator's Reference for details.
| Since the standard eval.lic, always has the same standard "eval serial number" it is not possible to "shadow" a standard evaluation KeyServer reliably. Hence an evaluation KeyServer will not allow you to make a shadow.lic file. |
If you are moving the server installation to a different computer which runs the same operating system, first copy the folder "KeyServer 5.1/Server". On the new host, create a Startup shortcut or alias so the KeyServer program will automatically launch whenever you restart. Be sure to remove the Startup shortcut from your old host computer. Now shut down the KeyServer program on the old host, copy the most recent log file into the Log Files folder on the new host, and then launch KeyServer on the new host. Remember that the KeyServer license certificate must only be in use by one KeyServer process.
| If the new KeyServer host has a different TCP/IP address or if it is located in a different AppleTalk zone, you will have to reconfigure everything that points to it. This includes clients, shadows, and possibly other KeyServers (if they are set up to "Refer" their clients to the KeyServer that moved). Consult the appropriate sections in the Administrator's Reference for details on how to specify the KeyServer address (all protocols) when setting up KeyAccess, KeyShadow, and Referrals from another KeyServer. |
If you are using the DNS name for the IP address of KeyServer, reconfigure the address resolution in the DNS server so that clients will now find the moved KeyServer. Alternately, you may be able to configure the new server computer to use the old TCP/IP address.
| Even though shadows will attempt to find KeyServer based on DNS name, it is not a good idea to assume DNS service will be available when for some reason KeyServer is not. It is best to re-install the shadow.lic license file for each KeyShadow process so that it includes the changed IP address information. If the zone of KeyServer has changed and you are shadowing AppleTalk, you will have to re-install shadow.lic files anyway. |
If the IP address remains the same and the AppleTalk zone (if any) is the same, no client or shadow reconfiguration will be necessary. If your old KeyServer was supporting Macintosh clients via AppleTalk and the new host is not a Macintosh, these clients will have to be reconfigured to use TCP/IP.
Existing Windows clients using IPX will look for KeyServer by name, so double check that the moved KeyServer is using the same name as before.
| When KeyServer is run under Windows NT, the KeyServer name (used by IPX clients) is converted to all ALL CAPS, even if you specify the name in lower case letters using KeyConfigure. Hence, if your old KeyServer was supporting IPX clients and had a name with lower case letters, a move to NT requires that these clients will have to be reconfigured to use ALL CAPS. |
Moving KeyServer to a different host operating system (not just a different computer) requires a little more understanding of exactly where KeyServer stores its configuration data. The basic procedure is to first do a clean server install on the new host platform and then move data files from the old KeyServer into the newly installed folder to replace the defaults.
KeyServer data files (license counts, network access requirements, etc.) are stored within the KeyServer Data Folder in a format readable on all supported host platforms. Also stored in the KeyServer Data Folder are several sub-folders containing authentication modules, KeyServer Log Files, etc. Except for the log files, the items in these sub-folders are platform specific code extensions. Therefore, to transfer configuration data, copy all of the files (not folders) at the top level of the old KeyServer Data Folder into the new KeyServer Data Folder replacing default files as necessary. You can transfer the Log Files sub-folder if you wish, but other sub-folders should not be transferred.
| If you are using the Text File authentication method, there is one more file to copy: the data file Text File Users, located inside the Authentication Modules folder within the KeyServer Data Folder. Note: this file is not backed up by the automatic backup procedure. |
When all the data files are in place, shut down KeyServer on the old platform, copy its most recent log file into the Log Files folder on the new computer, and then start up the new KeyServer. Remember to remove the KeyServer startup shortcut from the old host. Note that comments above concerning changes to the network address or network protocols apply here as well.
|
If you are copying to a volume that only supports short file names
(e.g., 8.3 format used by NetWare 4.x), the KeyServer Data Folder will
be called ksdata and you will have to rename several files as follows:
|
Although most of KeyConfigure's capabilities are identical on Windows and Macintosh, when "keying" a program for secure KeyServer control, you must run KeyConfigure on the same platform as the program to be "keyed". Hence, if your KeyServer is going to control keyed software on both platforms, you must install KeyConfigure on at least two computers: one Windows and one Macintosh.
| KeyConfigure for Windows requires Windows 95/98 or NT. It will not run under Windows 3.1. |
Except as noted above, the hardware and software requirements for running KeyConfigure are minimal and generally the same as for any client (see below).
Run the Admin Install on any client computer where it will be convenient for you to manage KeyServer. You may also find it convenient to install KeyConfigure on the KeyServer machine itself (assuming the server host is Windows or Macintosh), but this is not a requirement.
Both Admin installers (Windows and Macintosh) include a KeyAccess install since KeyConfigure (the main Admin component) communicates with KeyServer using the network protocol and services of the client.
| Before launching KeyConfigure for the first time, use the "Log On" button in the KeyAccess client component to verify that the network protocol and location of KeyServer are set up correctly. The default password for the administrative connection is Sassafras. |
Even though KeyAccess itself is included in the Admin install, you should still run the Client or Mobile Client Installer in order to have a complete set of client utilities available on the administrative computer (e.g., KeyVerify, KeyAudit).
In order to monitor KeyServer status and client connection integrity, you should install KeySentry on a few machines that have a network connection to KeyServer. Do not install KeySentry on the KeyServer computer itself. KeySentry will inform you of the following problems:
| KeySentry is installed when you run the Admin installer. You may want to create a shortcut named KeySentry in the Startup group and configure it to minimize at startup. Then monitoring will begin every time the computer is started up. |
| To install KeySentry on a Macintosh client, copy the KeySentry file into the Control Panels subfolder of the System Folder and restart. |
Client computers must be connected to the network and properly configured with one of the protocols, TCP/IP, IPX, or AppleTalk -- the only exception is for mobile clients, i.e., portable or laptop computers, which can be configured for use of controlled software while disconnected.
The client software, KeyAccess, is designed to have negligible impact on performance regardless of the specific operating system and hardware environment. KeyAccess is active briefly at startup time while it establishes a session with KeyServer, and then again whenever a program launches or quits. In addition, KeyAccess responds to session maintenance tickles from the KeyServer approximately every 5 minutes. With a properly functioning network connection to KeyServer, these transactions are essentially instantaneous.
|
An Intel 286 or higher microprocessor running Windows 3.1, Windows for
Workgroups, Windows 95, Windows NT, or OS/2 is required for clients. The NT 4
task manager will report from 1 MB to 2 MB of "Mem Usage" for KeyAccess,
depending on which shared system resources are included in the total. The
actual size of KeyAccess executable code (including its private transport
libraries and private data) is about 250 K.
Communication to the KeyServer requires either TCP/IP (WinSock 1.1 compliant) or IPX. When using IPX on Windows 3.1, you must have the NetWare Client for Windows installed; the NetWare Client for DOS is not sufficient. KeyAccess can use either Microsoft's or Novell's IPX drivers on Windows 95/98 and Windows NT. |
|
Any 68000 or PowerPC processor running any Macintosh OS version will run the
KeyAccess client software. This includes System 6 through System 9 running on
Macintosh or clones. KeyAccess also runs under A/UX, MAE and Mac OS X Server.
The system memory requirement is about 130 KB.
Communication to the KeyServer requires either TCP/IP or AppleTalk. If you are using Open Transport networking software you must use version 1.1.1 or better. If you are using Classic networking software, the AppleTalk version must be at least 58, and MacTCP must be at least 2.0.6. |
When KeyAccess is installed on a client computer, it will have to be configured with the desired network protocol and address to access the KeyServer. If your clients will be using TCP/IP, you will have to know the IP address or the DNS name of the KeyServer machine. For AppleTalk communication (available for Mac clients only), you will need to know the KeyServer name and the AppleTalk zone where KeyServer is located. For IPX connections, you need to know only the KeyServer name.
When first installed, the network name of your license server defaults to "KeyServer". IPX and AppleTalk clients will use this name to locate the KeyServer. If you want to change the name to a something more descriptive, e.g., "Engineering Group KeyServer", you should do so before installing KeyAccess on a large number of clients -- use the "Change Network Name" item in KeyConfigure's Admin menu. To avoid using a raw address for IP clients, make sure your DNS has a name registered for the KeyServer IP address.
KeyServer is licensed to support a fixed number of client computers which can be any mix of Windows and Macintosh. Each of these computers needs to have the client software, KeyAccess, installed in order to communicate with KeyServer. Run the Client Installer on all desktop computers that you wish to manage with KeyServer. Your KeyServer should be up and running so you can immediately use KeyVerify to test KeyAccess's network connection to KeyServer.
| During the Client install you will be asked to supply a DNS name, raw IP address, or IPX name for the KeyServer. You must also specify a name for each client computer so it can be identified in KeyServer's log files. Launch KeyAccess and log on to get a KeyServer connection. |
| The Macintosh Client Installer merely places the KeyAccess file into the extensions folder and extracts the KeyVerify and KeyAudit utilities into a KeyServer Client folder. You must use the Chooser to open KeyAccess and either select the KeyServer by name in the proper AppleTalk zone, or use the configure button to set up the IP Host address (raw IP or DNS name). Restart the Macintosh to activate the KeyServer connection. |
For mobile computers (laptops or portables) that will use controlled software off-line, use the Mobile Client Installer instead of the basic Client Installer. It installs the program KeyCheckout in addition to the basic client components. KeyCheckout is used to checkout a software license for use on a mobile computer that has no network connection. You must specify an expiration time when the license will be automatically reclaimed by the KeyServer.
| Depending on your management strategy, you may not want all mobile computers to use the KeyCheckout program. Use the basic Client Installer when you want to provide only on-line access for KeyServer managed software even for mobile computers. |
After installing KeyAccess on a client computer and configuring it to connect to your KeyServer, launch the KeyVerify utility in order to verify KeyServer's license control functionality. This test program is "keyed" so the launch will only succeed if KeyServer responds to the launch request by granting permission to run and by sending the key. When it does succeed, KeyVerify displays status information about where it got the key -- either from KeyServer, a KeyShadow, or from a checked-out key stored on a local disk.
If you get the error message, KA-280, it means that KeyAccess has failed to connect to either a KeyServer or a KeyShadow and no portable key for KeyVerify is available. Open KeyAccess and check that you have correctly selected the KeyServer name or correctly entered its address. Select the Log On button in KeyAccess -- if KeyServer is running and everything is set up correctly, you will get a message confirming a connection. Otherwise, double check the installation steps and make sure the network is functioning correctly. See the Trouble Shooting section in the Administrator's Reference for suggestions on how to isolate the problem. Don't hesitate to call Sassafras tech support for help.
This chapter gives an overview of basic KeyServer functionality and its underlying implementation. It describes KeyServer features and a conceptual framework that you will need in order to plan your license management strategy and to effectively deploy KeyServer at your site.
KeyServer uses TCP/IP, IPX, and AppleTalk to stay in contact with the various computers connected to your network. On each networked computer, the KeyServer client software, KeyAccess, handles communication with the KeyServer. When a client computer first starts up, KeyAccess automatically contacts the KeyServer and opens a session. KeyServer makes an entry in its session table and then tracks all software usage occurring on that client computer during the session.
When a user launches a program, the operating system passes the launch request to KeyAccess, which then conveys the request over the network to the KeyServer. It doesn't matter whether the application file being launched is stored on a local disk or on a remote file server; the transaction with the KeyServer is the same. KeyServer consults its database of software licensing information and its current software usage table in order to determine how to respond to the launch request. Possible responses from the KeyServer back to the client include:
Unlike other license management systems, KeyServer clients do not require a file server in order to query and register program usage information. With KeyServer, transactions between clients and the license server process are conveyed via a secure point-to-point protocol that is highly optimized for network and processor efficiency.
You use the KeyConfigure program to configure usage limits and license options for each software application that you want to manage with KeyServer. In its simplest configuration, you set a usage limit for each particular program to the number of software licenses that you own. Clients can use the software on a first-come, first-served basis until the number of simultaneous users reaches the licensed maximum that you have set.
Beyond its most basic operation, KeyServer offers a great deal of flexibility that lets you customize the way individual programs are managed and the particular level of access granted to specific users or computers. In this chapter, we focus on the basic configuration issues while leaving the details and advanced features to the "KeyServer in Detail" chapter.
All transactions between clients and KeyServer can be logged, so in addition to KeyServer's real-time control of current software usage, you can run historical usage reports based on the logged data. Although some sites find that software usage reports alone suffice to document license compliance, most sites will want to also use KeyServer's ability to actually control usage.
There are two distinct methods that KeyServer uses to bring a program under control:
Since a keyed program will not run without getting its key from the KeyServer, it can be freely distributed and copied without risk of piracy. KeyServer cannot protect an unkeyed program from piracy even if KeyServer is set to control its usage. KeyServer makes no attempt to lock down files or to prevent copying; users can copy keyed and unkeyed programs alike and transfer them to other computers or take them offsite. But the keyed programs will not run offsite without permission from KeyServer, while the unkeyed programs will.
Furthermore, KeyServer's ability to actually enforce the usage limit for an unkeyed program is dependent on KeyAccess being installed and active on the client computer. If a user removes KeyAccess, a keyed program simply can't run, but an unkeyed program will be free to launch regardless of any license limit set up in a Control.
| Several Macintosh programs use a technique called "Network Copy Detection" to ensure that a single serial number for a program can be used on at most one networked computer. Most of these programs turn off their serial number checking whenever you key the program. |
In versions of KeyServer prior to 5.0, usage control was only available for keyed programs and logging was either enabled for all programs or for keyed programs only. Starting with version 5.0, logging and other actions can be individually configured for each distinct unkeyed program, just as keyed programs are configured individually.
Whenever Unkeyed Actions is enabled, KeyServer begins accumulating the names and program signatures of all unkeyed software that is launched on client workstations. A sorted list is displayed in the Unkeyed Actions window where you can select each program name and individually specify an unkeyed action. There are three choices:
Ignored
Logged
Controlled
Since KeyServer's default action for unkeyed programs is set to "ignored" (or to "logged" if you have changed the default), usage is not limited or managed in any way.
| You must be very careful when setting an unkeyed action to "controlled". By default, unkeyed programs are identified by program signature only, so a Control item applies to all versions of a program and to everyone who has KeyAccess installed! Consult the "KeyConfigure" chapter for details on how to customize the Control options for distinct program versions so that individual users are given different access, depending on group membership or location. |
When you distribute a keyed program to your users, it is easy to communicate the clear understanding that usage may be subject to a usage limit or to other control options that you have set. In contrast, a new Control for an unkeyed program immediately imposes its usage limit and other control options on all existing copies of the program on all client computers. It may be quite an unwelcome surprise for a user to suddenly have their access to a program become controlled, especially if they personally installed it years ago. Of course a frustrated user could disable KeyAccess in order to run an unkeyed program without control, but then keyed programs would be disabled as well.
| Versions of KeyAccess prior to 5.0 do not support control of unkeyed software and will report the signature only, not the name, of an unkeyed program to the KeyServer log. In order to make sure everyone is using the new 5.0 client software, you can use KeyConfigure to set up the "KeyAccess Version Control" item in the Admin menu. |
KeyServer ships with unkeyed actions enabled, so as clients launch programs, the names will accumulate in the Unkeyed Actions window. The default action for programs as they are added to this window is "ignored". You can change this default to "logged" if you want the Unkeyed report to summarize usage of all programs on your client computers, but the additional log size requirements may be prohibitive. It is usually more efficient to selectively change the ignored action to logged for specific programs you are interested in.
New program names appear in red when first added to the Unkeyed Actions window. You should periodically examine this window and for each red program name, explicitly confirm the default action or change it to the log or control action. As you set the action, the font color will change to black so you can easily distinguish programs that have been explicitly configured from those that have not.
When an unkeyed program action is set to "logged", KeyServer makes a log entry every time it receives a launch or quit notification for the program. If a client computer crashes or the network connection fails, KeyServer may never receive these notifications. Missing log entries for launch or quit can make the Unkeyed program usage report somewhat inaccurate. In contrast, when a program is controlled (e.g., the unkeyed action is set to controlled or the program is keyed), KeyServer maintains a session table in RAM which tracks each user and all the controlled programs they are using. This gives you a real time view of current usage in the Active Controls window as opposed to a report-based view. The session table also gives KeyServer a way to notice and compensate for inconsistent information such as missing launch or quit notifications, thus making usage reports for controlled programs accurate.
KeyServer lets you pick a management strategy that is best suited to each program. It is perhaps easiest to decide which programs should be ignored (i.e., not logged and not controlled). A good example might be the system utility WordPad (SimpleText on Mac), which is used to read simple text files. Other system utilities may be interesting to log, even though from a licensing standpoint, tracking is unnecessary. An example might be Microsoft Internet Explorer.
Having decided to log a particular application, there are three different management strategies to choose from:
Each strategy has its pros and cons, depending on your goals. The Log Only strategy lets you run the "Unkeyed" report to produce an approximate summary of the program's usage. But in order to use KeyConfigure's complete set of report modules, and for greater reporting accuracy, you will need to create a Control either by keying the program or by setting its unkeyed action to "controlled" in the Unkeyed Actions window. In either case, the Control can be configured to allow infinite usage or it can be configured to enforce a usage limit.
As soon as you create a Control for the program, not only are there better reporting options, but you have the ability to manage usage based on group membership, network location, time of day, name, password, etc. The Control can also be grouped with others in a "Suite" so that all the member programs are controlled by the single usage limit and license options for the Suite. A custom message can be configured in the Control so that users are informed of important information such as the existence of a new upgrade. Access to the program can be disabled entirely, or only allowed at certain scheduled times or from certain locations.
When the controlled program is in fact "keyed", all of the Control options are securely enforced, both on networked computers and on mobile computers. Users cannot bypass KeyServer control either intentionally or unintentionally. Some software publishers require this level of security in exchange for using "concurrent use" licensing rights. Of course the secure control (achieved by "keying" each executable program) does require some extra effort beyond that required to control unkeyed copies.
| When you perform an upgrade of a keyed program to a later version, it is important to run the upgrade installer against a copy of the un-keyed program and then re-key the resulting new program version. It is generally not reliable to upgrade a keyed installation directly. Read the KeyConfigure chapter for hints on how to mange upgrades efficiently. |
The table below summarizes the features and requirements for each of the three management strategies:
Features |
Log Only | Log & Control Unkeyed |
Log & Control Keyed |
| log based usage reports |  |
|
|
| usage control |  |
|
|
| detailed reports | |
|
|
| real time usage view | |
|
|
| optional message displayed at launch | |
|
|
| distinct versions logged separately | |
|
|
| distinct versions controlled separately | |
|
|
| serial # checking defers to KeyServer | |
|
|
| existing program copies controlled | |
|
|
| easy management of version upgrades | |
|
|
| secure license control | |
|
|
| secure piracy prevention | |
|
|
| mobile client software check out | |
|
|
Requirements |
Log Only | Log & Control Unkeyed |
Log & Control Keyed |
| client must be running KeyAccess | |
|
|
| client must use keyed programs | |
|
|
When you set up a Control for an unkeyed program, you get most of the advantages of KeyServer's real time control and metering accuracy but without the security of keyed software. Control of keyed programs gives you security and version control but does not give you immediate control over existing unkeyed copies of the program. Most sites will use a combination of both the unkeyed and keyed control strategies -- even for the same program!. By keying some essential programs, the security level for control of unkeyed software is enhanced -- users cannot afford to remove KeyAccess as a workaround for gaining uncontrolled access to unkeyed programs.
The gradual approach to bringing a site into license compliance focuses metering and enforcement on new software installs. You may find it easiest to start by setting up Controls for several of your existing unkeyed programs with the usage limits set to infinite. Monitor software usage in the Active Controls window and run Summary and Histogram reports in order to gather usage statistics for each program. Based on these statistics, you can purchase the appropriate number of upgrade licenses to the latest version and then introduce the upgrade to your site as a keyed program only.
| To aid in the deployment of new programs or upgrades in the secure, keyed format, KeyConfigure includes the ability to "deputize" third party installers. When you use a deputized installer, the program will be automatically keyed as it is installed. The 5.1 version of KeyConfigure for Windows does not include the ability to deputize a third party installer. |
When you have a mix of old unkeyed program versions and new keyed upgrades, you can manage all of these as part of a "suite" with a single usage limit, or you can manage the unkeyed programs separately so they can be disabled after a reasonable time.
Some sites introduce KeyServer as part of an overall license compliance project that includes both license management and auditing components. The KeyAudit utility is included in the KeyServer package in order to help you quickly transform an unmanaged site into a KeyServer managed site.
KeyAudit has the unique ability to distinguish between keyed program copies and unkeyed copies. Furthermore, KeyAudit contacts KeyServer for a list of all the keyed programs that KeyServer is managing. If an audit of a user volume turns up an unkeyed copy of one of these programs, KeyAudit can be instructed to transform this copy into a keyed program, thus bringing it under secure KeyServer control. After you have keyed the basic software library for your site, use KeyAudit on client computers both to document your license compliance efforts and to clean up user volumes.
KeyConfigure is the administrative interface to the KeyServer process. It communicates with KeyServer using the network protocol and KeyServer address from the KeyAccess client configuration. Operation of KeyConfigure on the KeyServer computer itself is identical to remote operation over the network and KeyAccess is still required. Several copies of KeyConfigure can simultaneously view and modify the configuration options for KeyServer. There are master and assistant passwords so you can maintain secure control of licensing configuration while allowing reports and other features to be managed by assistants.
| The default password for both Administrator and Assistant is set to Sassafras for all new KeyServer installs. |
On a client machine that has been set up correctly with a KeyAccess connection, launch KeyConfigure and enter the default password: "Sassafras". Follow the instructions for changing to a custom password.
In the Admin menu, select "Show Current Users".
This brings up a display of KeyServer's session table which is tracking usage of controlled programs in real time. It shows each connected client followed by program names and running times for all controlled programs in use. You can watch KeyServer's usage tables change in response to the launch or quit of a controlled program on a client computer.
In the Controls menu, select "Show Active Controls".
You will see the names and status of the five standard Controls that are installed by default in a new KeyServer. If one of your clients is running KeyVerify, this will be reflected in the In Use counter in the first column on the line labeled KeyVerify.
Quit KeyVerify and watch its In Use count go to zero in the Active Controls window. Notice that in the Users window, the program name is no longer shown on the user line. KeyConfigure updates its display every few seconds so you can basically view your experiments in real time.
The usage limit for KeyVerify has the value "2" by default. This is displayed in the Active Controls window in the Enabled column. Try launching three copies of KeyVerify to see how KeyServer controls usage -- you can duplicate KeyVerify and run several copies on a single client or launch it from different clients. Two of your launches will succeed and the third attempt will be blocked with an invitation to be put in a waiting queue. When you quit one of the running copies of KeyVerify, the queued requestor will be notified.
Double click on the KeyVerify item in the Active Controls window.
In the dialog window named "Control Details for KeyVerify", the tabs labeled General, Licenses, Portable, etc. are used to group together related sets of configuration options.
Click on the Licenses tab to see how usage limits are configured.
The licensing configuration for the Control of KeyVerify is very simple. A single Global pool containing 2 licenses is available to all users at all times. There are no other groups. There are no other license pools. All licensing is Unscheduled, meaning there is no special different behavior at scheduled times.
Select the line item labeled Global under Unscheduled Times. The box labeled Licenses: will become highlighted. Change the license count to zero and confirm your edit by hitting the OK button. Now try to launch KeyVerify again. The custom message will be displayed on the client.
Double click on the KeyVerify line in KeyConfigure's Active Controls window to get back to the Licenses configuration dialog. Under the General tab, you will see the configuration for the Custom Message. It is configured to display On Deny -- that is, it will be displayed only if the license limit is set to zero. Typically, the custom deny message is used to inform clients that their program version is obsolete and it may give further instructions on where to get an update. In order to re-establish the usefulness of KeyVerify as a diagnostic tool, you should reset the license count (under the Licenses tab) to a nonzero value.
If you want to take a quick look at how your actions so far have been reflected in KeyServer's log file, use Control-R (Win) or Command-R (Mac) to bring up the choices for reports (also available from the Report Menu). The Summarize report will give you an overview of usage for programs that are controlled by KeyServer. Don't be alarmed if your most recent activity is not immediately reflected in a report. You may need to use "Flush Log to Disk" and then "Refresh Now" from the Admin menu in order to process the most recent log entries.
In the Controls menu, select "Show Unkeyed Actions".
The Unkeyed Actions window shows the names of unkeyed programs that have been launched on client computers. On a computer running KeyAccess, launch a few unkeyed programs and then click on the word Update at the bottom left of the window. The names of the programs that you just launched will appear in red with their action set to either ignored or logged, depending on the Default Action setting shown at the top right.
Every time KeyConfigure is launched this window is automatically updated, but unlike the Active Controls and Users windows, there is no scheduled refresh. You must initiate further updates explicitly. To completely rebuild the cached list of unkeyed programs, hold down the alt/option key while you click on Update.
Highlight a red program name in the list and then confirm the ignored action by clicking on the green Set Action button at the top right of the window. The red type will change to black to show that you have explicitly configured this unkeyed program action.
Now let's make a Control for an unkeyed program. In our example, we select FileMaker Pro and click on the blue Set Action button to create a Control.
Click OK. Then a new line labeled "FileMaker Pro Control" will appear in the Active Controls window. The blue square icon indicates that it is a Control for an unkeyed program.
Launch a copy of this newly controlled program on one of your client computers. You will see the default "post launch message" that confirms KeyServer control.
Now double click on the Control for this program in KeyConfigure's Active Controls window, or hold down the alt/option key while double clicking on the program name in the Unkeyed Actions window. You can customize or delete the post-launch message under the General tab. Customize the license limit under the Licenses tab.
If you want to change the action for an unkeyed program from controlled back to logged or ignored, you must first look in the Active Controls window to be sure that the In Use count is zero (blank). Then in the Unkeyed Actions window, select the program name and use the appropriate Set Action button -- the obsolete Control item will be deleted from the Active Controls window.
In order to key a Windows program, use the Windows KeyConfigure. To key a Macintosh program, use the Macintosh KeyConfigure. Under the Controls menu, select "Install Key...". The standard file selection dialog comes up so you can select the program file that you want to key for secure KeyServer control. The selected program is duplicated and the keying process proceeds on the duplicate.
KeyConfigure extracts a small "key" from the program file and this is transferred to KeyServer for storage in the Active Controls file on Windows. The key is tagged internally with the complete program signature, version, and creation date so it is sure to match the exact keyed program version.
| On Windows, the resulting keyed program retains the original name. The original unkeyed program is untouched except to rename it with the .BAK extension in place of .EXE. |
| On Macintosh, the resulting keyed program gets a new name formed by appending the § symbol to the original name. The original unkeyed program is untouched. |
A new Control is automatically created as you key a program. When you launch the new keyed program copy you will see the default post-launch message which confirms that the program is under KeyServer control. Use Configure to customize or delete the message and to set up licensing options as above.
| Unlike unkeyed programs, deleting the Control for a keyed program from the Active Controls window does not revert the program to its previous state. The only way to revert is to throw away the keyed program and use a backup copy - this is why the keying process begins by making a duplicate. |
If for any reason the Control for a particular keyed program is removed from the Active Controls file, all keyed copies of that particular keyed program will become useless. To regain functionality for the keyed program copies, you can either re-key an original unkeyed program (so your KeyServer once again has a key) or use a backup copy of the Active Controls file to restore the original key and Control. It is for this reason that you should always keep a backup of KeyServer's Active Controls file and a copy of each original unkeyed program.
| A single Macintosh program may exist in three different executable file formats: 68000 only, PowerPC only, and "Fat" (which runs on either processor). The PowerPC only case usually includes a 68000 "stub" to gracefully inform a user that the program won't run when launched on a 68000 machine. KeyConfigure must extract a key from both the 68000 and PowerPC sides of a Fat application (unless the 68000 side is merely a stub). KeyConfigure automatically groups the corresponding Controls together under a single "Suite Control" (see below) so all program versions are managed by a shared usage limit. |
Suites allow you to group several programs together under one license counter. Furthermore, if a user has opened one program within a suite, other programs in the suite may be launched by the same user without using up an additional license. The license is finally returned to KeyServer only after the user quits all programs from within the suite.
Members of a suite share more than the license counter. All control options with the exception of the Custom Message and Notes are inherited from the suite. Several common licensing scenarios are easily handled by grouping individual program Controls under a single Suite Control.
A Suite Control is created automatically when you key a "fat" Macintosh application, but more typically you use "New Suite Control" from the Controls menu. If some existing Controls are already selected when you create the new suite, they will automatically be moved into the suite. Otherwise, you just drag a program Control onto a Suite Control in order to add it to the suite, thus over-riding its individual licensing options.
| Make sure that the Controls window is properly set up to display suites and their members. Pull down the Controls menu, and verify that "Group Controls by Suite" is checked and "Hide Suite Members" is not checked. |
When Controls are grouped by suite, each member Control is indented underneath the Suite Control. Icons in the Active Controls window are also used to distinguish between seven different types of Control: suite, keyed Win 16 program, keyed Win 32 program, keyed Mac 68000 program, keyed Mac PowerPC program, unkeyed program, and deputized installer.
While support for TCP/IP connections enables KeyServer to manage software licensing throughout the worldwide Internet, it also means that you must protect your KeyServer from unauthorized clients. Support for IPX and AppleTalk may give your KeyServer similar undesired exposure but on a smaller scale. The first step in filtering out unauthorized clients is to restrict the allowable network addresses from which KeyServer will accept a connection. Further Authentication requirements can be imposed on any client that first passes through the Location Filter.
Use the "Network Access..." item under the Admin menu to bring up the Location Filter dialog.
The TCP/IP example above has All IP Addresses unchecked so worldwide access is disabled. Access from the address range 204.167.90.* (i.e., 204.167.90.1 - 204.167.90.254) is permitted. To allow additional access, click on the New button and type in an additional address range using a format like 129.170.16.1 - 129.170.16.23. You can edit an existing entry by double clicking on it.
Filtering under the AppleTalk and IPX tabs is configured in a similar way. The New button under the AppleTalk tab lets you enter an AppleTalk zone name. The New button under the IPX tab lets you enter a range of network numbers in a format like 0x20416790 - 0x20416791.
The Groups: text box allows you to name each address range (or set of address ranges). Under the Licenses tab, you can use the named group as a way of restricting a pool of licenses to users from a certain set of addresses. KeyServer's Authentication modules let you further restrict group membership based on additional criteria beyond location.
For basic KeyServer configurations, there is no need to define groups when setting up the Location Filter. However, group definitions based on Location Filter and possibly Authentication, coupled with the ability to create multiple license pools for a single program offers enormous flexibility in customizing access to KeyServer and to individual programs. Consult the Online Documentation for details.
| The KeyServer default is to accept all client logons over all network protocols enabled on the host computer. With TCP/IP enabled on KeyServer, this may include access from anywhere on the world-wide Internet. You will probably want to either disable a protocol entirely (using the KeyServer status screen), or impose Network Access restrictions and/or Authentication requirements to control KeyServer access. |
All the custom license management information (program keys, license counts, network access requirements, etc.) that you set up using KeyConfigure is stored within the KeyServer Data Folder on the KeyServer machine. You should always maintain a backup of this data so you can recover from a disaster such as a disk failure.
If some programs are "keyed" for secure control, it is most important that you back up at least the Active Controls file -- the keyed programs are useless without it. You should also keep backups of program files themselves, before they are keyed. Consult the "KeyConfigure" chapter for details on how to set up a schedule for automatic backups and how to configure a remote storage location.
This chapter documents the procedures for adding clients and upgrading version 5.0 or 5.1 components to the latest version. The more complex upgrade instructions from an older 4.x KeyServer are documented in an appendix.
The earlier section, "Web Updates", explains how to get the compressed archive for the latest image from the web. Expand the archive to update the contents of your previous image folder, thus replacing any installers that have become obsolete.
Upgrading a Client, the Admin software, or the Server itself from a previous 5.1 installation is nearly as easy: run the appropriate installer from the latest 5.1 image. If the components from a previous install remain in their default location (in the folder "KeyServer 5.1"), the installer will automatically replace the existing components.
In all cases, the installers do not touch your customized configuration data:
| If a component is "busy" or "in use" it will be moved to the trash folder in order for a new version to be put in place. The new component won't actually execute and the old component won't be deleted until you quit and re-launch the component you are installing. |
The sections below give some important details, especially for upgrading KeyServer itself.
In order to increase the number of clients supported by an existing KeyServer, you will need a new server.lic file from Sassafras that is configured with your KeyServer serial number (the same as your existing server.lic) but with an increased client count. Move the old server.lic out of the KeyServer Data Folder and replace it with the new one (a 5.1 license certificate will work with either a 5.0 or 5.1 KeyServer). The new license will take effect when you restart the KeyServer process.
| If you have a KeyShadow installed to protect clients in case KeyServer becomes unreachable, you should update its shadow.lic file whenever you increase the client count of your KeyServer. Instructions are detailed in the "Upgrading KeyShadow" section. |
When upgrading your license count, you should consider updating the server components at the same time. Check the readme document in your image folder to see if installers have been revised. The readme will point to an on-line Component History document with specific bug fix information.
Upgrading the server process itself (from version 5.0.x or 5.1.x) should be done with special care since a mistake could affect all of its clients. The server installers are designed to allow either replacement of components in an existing "KeyServer 5.1/Server" folder (so existing license configuration data remains in use), or creation of a new "KeyServer 5.1/Server" folder (so the new software can be tested with default configuration data).
|
Before replacing components in a running KeyServer 5.1 installation, it is best
to first quit KeyServer, move old log files (not the current log) to a
convenient storage location, and then archive the entire Server folder to a
backup location. If anything goes wrong with the update install, you can then
quickly revert to the archived backup.
When the KeyServer process is running as a service under Windows NT, the service must be stopped before a replacement version is installed. If you haven't already stopped the service before running an update installer, the installer itself will request permission to immediately stop KeyServer. |
If KeyServer 5.1 has never been installed before, replacing existing components is not an option but instead the installer will offer to search for an existing 5.0 KeyServer installation. If one is found, the installer will give you the option of importing your metering configuration files from the old KeyServer Data Folder into the newly created KeyServer Data Folder in "KeyServer 5.1/Server".
| If a 5.0 KeyServer installation is found and you choose to import its data, you must manually shut down the old 5.0 KeyServer before launching the new 5.1 KeyServer. Otherwise you would have two processes trying to use the same serial number, name, and network port! |
When using a server installer to upgrade from either 5.0 or 5.1, your existing Active Controls file is copied without changes to the new KeyServer Data Folder. Hence, you must manually add any Standard Controls that have been revised or added since your older KeyServer install. In particular, when upgrading from 5.0 you will have to Copy/Paste the new "Referral" control into the Active Controls window in order to take advantage of the new referral feature introduced with KeyServer 5.1.
| Whenever you upgrade KeyServer, check the component revision history to see if the Standard Controls file has changed. If it has, you should open Standard Controls with KeyConfigure, copy all the controls, and paste them into the Active Controls window. |
| If your existing KeyServer has special files (such as .lic files) supplied directly by a software publisher to support their product securely under KeyServer, these files must be duplicated "by hand" into any new KeyServer Data Folder. The server installers won't do it for you, even when claiming to "upgrade" a previous KeyServer installation. |
There are good reasons to keep the previous version of the KeyServer folder intact, either as a backup archive (when upgrading from a KeyServer 5.1 installation) or in the original folder (when upgrading from a KeyServer 5.0 installation). For Admin upgrades, just let the installer replace the existing 5.1 components while letting 5.0 Admin components remain. This way, if you need to revert the KeyServer to version 5.0, you will still have the required 5.0 KeyConfigure.
| Even though the Admin install gives the option of installing KeyAccess if it is not present, there is no option for updating existing client components. Run the Client Installer when you need to update KeyAccess and for the latest versions of the utility components. |
Since an install of 5.1 server and admin components leaves old 5.0 components in place, you can easily revert to the 5.0 software if necessary just by shutting down the 5.1 program and launching the 5.0 version. If you need to revert from an updated 5.1 install to a previous 5.1 install, you can reverse the upgrade just by re-running the previous installer.
| If you have multiple versions of a 5.1 program installed, you should check which instance of the target program any shortcut in the Start menu resolves to. To avoid confusion among KeyConfigure versions, it may be safest to double click on a particular KeyConfigure file in Windows Explorer, rather than trust the program menu. In the case of a Startup shortcut to KeyServer, make sure there is only one and that it points to the correct executable. |
One of the paramount goals in designing KeyServer 5.1 has been to maintain backward compatibility with all of the older versions of KeyAccess as well as copies of programs that are already keyed. Once you have upgraded your KeyServer, you do not need to upgrade all of your clients immediately. KeyServer will tolerate any mix of client versions, so you can update your users' systems gradually when convenient. Of course, if you want to use some of the new KeyServer 5.1 functionality, your users will need to run the latest KeyAccess, and you should check the revision history for known bugs or incompatibilities that might effect specific old client versions.
| If you want to use KeyServer's ability to manage unkeyed programs, clients must use version 5.0 or better of KeyAccess. Use KeyAccess 5.0.6.1 or better to distinguish versions of unkeyed programs. For simultaneous access to multiple KeyServers (i.e., KeyServer Referrals), clients must use KeyAccess version 5.1. |
Client installers place some components into standard system directories, so regardless of where you point the installer, the system components will be updated during every install. Consequently it is not possible to have more than one version of KeyAccess installed even though you can have multiple versions of the utility components (KeyVerify, KeyAudit, KeyCheckout).
| KeyAccess on Macintosh is a System Extension. Therefore an upgraded version will not actually begin running until the client computer is restarted. The old KeyAccess will be moved to the trash. |
| KeyAccess on Windows includes components named keyacc.exe and keyacc32.exe which are contained in the Windows directory. Both of these plus related .dll files will be replaced by a Client install regardless of the version of the existing KeyAccess installation. |
A client installer will not search for KeyAccess's utility programs (KeyVerify and KeyCheckout), so you may have to find and delete old versions of these yourself unless they have remained in their standard installed location.
Beginning with KeyServer 5.1, shadows can be hosted on any platform that can host the server process -- a shadow is just a server install that uses a shadow.lic license file in place of a server.lic file.
| The installer, the installed files, and the running process name which implement a KeyShadow are identical to those that implement a KeyServer. You can install the server software on several computers, but the server.lic must only be installed on one -- the rest must instead use a shadow license file, shadow.lic. |
Upgrading a KeyShadow process from an existing 5.1 version is essentially the same as upgrading KeyServer. Run the appropriate server installer to replace components with the latest revisions. The cautious steps to insure against loss of service or data loss when upgrading a KeyServer are not necessary when upgrading a KeyShadow. Except for the shadow.lic file itself, the contents of the so called "KeyServer Data Folder" on a shadow computer are automatically mirrored from the KeyServer being shadowed.
| If the IP address of KeyServer is changed or if KeyServer's enabled protocols are reconfigured, use KeyConfigure to make a new shadow.lic file and use it to replace the existing shadow.lic files on KeyShadow computers. |
Old style shadows installed with KeyServer 5.0 (Mac only) will continue to work when the KeyServer is upgraded to 5.1 (assuming the KeyServer address hasn't changed). However, you should replace them with version 5.1 shadows as soon as possible for more robust shadowing, especially when run under more recent Macintosh hardware and operating system versions.
| Don't install a 5.1 KeyShadow on a Mac that already has a file named "KeyShadow" in the Extensions folder. You must remove this old KeyShadow version first to avoid conflicts! |
To upgrade from a 4.x or 5.0 KeyShadow, first remove the old KeyShadow extension from the Extensions folder. Consult the "KeyShadow" chapter in the Administrator's Reference for detailed instructions.
| Note that KeyConfigure connected to an evaluation KeyServer (using eval.lic) does not support the KeyShadow menu so you won't be able to make a shadow.lic file. |
Run one of the server installers on a computer other than the KeyServer and then install the shadow.lic file instead of your server.lic. To make the KeyShadow program run invisibly, you may want to use the "Background-Only" Custom Install option. When installing the shadow.lic file or when replacing an older copy, you must enter the KeyShadow password the first time the shadow process (i.e., the KeyServer program) is launched.
| Unlike prior versions, when you are shadowing AppleTalk with 5.1 KeyShadows, each zone can have at most one AppleTalk shadow process. If you are running KeyShadow on multiple Macintosh computers within a single zone, make sure that you use the checkbox in the KeyShadow status screen to disable AppleTalk shadowing on all but one KeyShadow. IP and IPX shadowing are not effected by this restriction. |
| |||
| Home | Support | Legal | Contact Us |
|