III. Options & Requirements

The “Quick Install & Tour” (previous section) includes an outline schematic and basic installation instructions, but you should check this document for options, cautions, details, etc. Always start by using your browser to open the README.html file at the top level of the K2 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.

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, XenApp, and Remote Desktop Server), other server platforms (Linux and Solaris), and for command line switches etc., always check the “OS Details” appendix.

In the Installers folder of any K2 image folder, you will find subfolders for each platform. The Admin function is only implemented for Macintosh and Windows, while other functions are implemented for all platforms. 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 constitutes an “image” which is identified by date, e.g. “K2 v7.4 (2016-08-10 image)”.

Server, Admin, & Client Functions

• Server

You need to run just one server installer. First choose a platform to host your KeyServer and then locate the appropriate K2Server installer. You will install KeyServer on this single computer in order to audit software, track program usage, and manage software licenses on all client computers.

• Admin

Use K2Admin.exe or K2Admin.pkg to install the administrative program, KeyConfigure, on workstations used by administrative personnel for management of the KeyServer process. KeyConfigure does not have to run on the same computer or even under the same operating system as KeyServer.

• Client

Use the appropriate K2Client installer to install the client program, KeyAccess, on every computer for which you want audit data, usage reports, and license management.

The various installers can be run directly from the archive and you can copy (or download) any installer (or the entire image folder) to any mounted volume. The client installer can be customized to include the address of the KeyServer and other options so that large scale deployment can be accomplished using general purpose file distribution tools. Smaller sites may simply make the customized installer available for users to download and install themselves.

You can install multiple functions on a single computer. For example, it may be convenient to enable management of the KeyServer process from several workstations that are also clients – so in addition to running the client installer you would then run the admin installer. If the KeyServer process is hosted on a Windows or Macintosh computer, all three functions (server, client, and admin) can be installed and used on this same computer.

It is assumed in this document that you are installing for the first time. If a prior install exists on a target drive, the installers will re-install any existing components. See the “Minor Updates” or “Major Upgrades” document 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 all typical environments without any special requirements or side effects.

Server Requirements

A single KeyServer will effectively manage software licenses at sites supporting from ten to tens of thousands of computers. KeyServer’s scalability is achieved by using the basic network protocol TCP/IP. 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 or database server or server OS.

To run the KeyServer process, you should choose a single computer (Windows, Macintosh, Linux, or Solaris) that is in a robust location on your network. Client computers must be able to exchange network packets reliably with the KeyServer machine. This computer should be secure from unauthorized users. It should be turned on at all times, configured to never sleep, and not be subjected 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.

The TCP/IP address of the server host must be static. It will be convenient to register a DNS alias for this IP address on your Domain Name Server. Then clients can be configured to locate KeyServer using this DNS alias instead of a raw IP address. This will make it easy to move the KeyServer process to a different IP address if you ever need to in the future.

If clients are accessing KeyServer through any firewalls, you will need to grant access to the KeyServer address through UDP port 19283. KeyConfigure will require TCP access on port 19283. Consult the Firewall Settings documentation for complete details (including time-out issues).

The processor demands of KeyServer depend on the number of client computers being supported and on the intensity of use for the various features. Basic license management services take precedence over admin responsiveness or report generation so client support will be transparent even when a very large KeyServer is busy running a complex report.

For basic license management and audit services, KeyServer’s processor demands 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. When a KeyServer supporting thousands of clients with many months of accumulated usage and audit data generates a complex report (at the request of KeyConfigure or an external reporting tool), the time required will be highly dependent on both the cpu and disk performance of the host. If KeyServer is managing data for tens of thousands of computers, fast report generation may be best achieved using KeyServer’s automatic data export feature. Then both KeyConfigure’s internal reports and any custom external reports can take advantage of a separate, high performance, SQL server. But even for such large scale reporting demands, KeyReporter, with its automatically scheduled report generation often makes the desire for “instant” reporting irrelevant.

Small to mid-sized sites often 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, except when running reports. An alternate strategy is to put only a few services on several inexpensive computers both for redundancy and so that reconfigurations and restarts will be independent and will not affect all services at once. A similar goal can be achieved by installing KeyServer and other services each within a dedicated virtual machine.

Remember that we use the word “server” to mean any computer (or virtual computer) that is hosting a network service such as the KeyServer process. KeyServer does not require a “file server”, a “network operating system”, or a "server OS. It will manage license compliance for clients that run software under multiple operating systems on both physical and virtual computers.

The K2 image includes KeyServer installers for 4 different operating systems: Windows (XP, 2003, Vista, 2008, 2008 R2, 7, 8, 8.1, 2012, 2012 R2, 10), Mac OS X (10.6 - 10.13), Linux (2.2 kernel or higher), and Solaris (10 or higher). The implementation on all platforms is compiled from the same code base. Since KeyServer is a very “light-weight” process, the criteria in choosing the host may depend on available Authentication methods and Export methods. Hardware performance is rarely a significant consideration except when supporting tens of thousands of clients – in which case, quick report generation will depend on a fast disk.

If you wish to use a particular Authentication or Export method this may force you to choose a particular platform for the KeyServer host computer, since certain modules only exist for one platform. Note: exporting and authentication are optional. See the Authentication and Export documentation for more details.

The amount of disk space required for K2 databases and log files is highly dependent on how many programs are being logged and on the number of computers being managed. A KeyServer supporting several thousand clients may generate 50 megabytes of log and usage data per day. A several hundred client KeyServer will require proportionally less space, perhaps 25 megabytes per week. Initially it will be most convenient to set KeyServer up with space for at least several months’ worth of data. Once you have configured Policies to Observe and Manage products and KeyServer has started to collect Usage data, you can get a better estimate of how much disk space is required per week or month of Usage data.

The RAM requirements for the KeyServer process are relatively small - even when supporting tens of thousands of clients, 1 GB should be more than enough.

Server Install – KeyServer

Installation of the K2 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 can lead to unpredictable behavior for both client and administrative software.

 When the server installer is run on computer hosting a pre-7.4 KeyServer, the old version will be stopped and set aside! To avoid losing your existing configuration data or losing support for existing clients, be sure to consult the “Major Upgrades” document. In addition to carefully following the upgrade steps, you will need a new version 7.4 license file, server.lic.

The first step in installing a new KeyServer is to choose a host platform and then run the appropriate Server installer from the K2 image folder. For platforms other than Windows and Macintosh, consult the “OS Details” appendix.

 On a 32 bit Windows OS, you must use K2Server.exe, the installer for the 32 bit ks.exe. But on 64 bit Windows you can use either installer: K2Server.exe or K2Server-x64.exe. The usual reason to choose one over the other occurs when ks.exe is configured to interface with an ODBC driver for data export in which case the bitness of ks.exe must match the supporting third party DLL. The functionality and performance of the 32bit and 64bit ks.exe compiles are identical.

After the installer is finished, there is still one more step: you must install your custom license certificate file, server.lic, in order to enable full KeyServer functionality with support for your licensed number of clients.

For evaluation you don’t need a server.lic. Without it, KeyServer will use instead the default file, eval.lic, which is created by the installer to support a limited number of clients until a fixed expiration date.

You obtain your custom license certificate from Sassafras as an e-mail attachment. 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.

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 the Windows Explorer or Macintosh Finder 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”. It may appear to be named “server.lic” but the actual file extension, ".txt", is hidden. KeyServer will not find the file until you remove the .txt extension from the full name.

The standard install location on Windows is C:\Program Files\Sassafras K2\Server\. On a 64 bit OS, it is C:\Program Files (x86)\Sassafras K2\Server\. Note: this same location is used regardless whether the 32 bit or 64 bit ks.exe is installed.

The standard install location on Macintosh is /Library/KeyServer/. There is an alias to this location installed as /Applications/Sassafras K2/Server.

Regardless of platform, the server installer creates a folder containing the KeyServer program and a sub-folder called “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, or you are adding clients to your K2 license, see the “Minor Updates” or “Major Upgrades” document.

The server installers set up the KeyServer so it will start automatically whenever the host is booted but you can also stop and start the ks process without rebooting (e.g. in order to load a new server.lic file):

On Windows, you can use the services control panel to start and stop the KeyServer process. For testing a new installation it is also possible to double click on ks.exe to run it as an application. But note: you will get an error message, “can’t load...”, if you attempt to run KeyServer simultaneously as a process and as an application.

On Mac OS X, the installer will bring up an Applescript applet for starting and stopping the KeyServer process.

It is important to consult the “OS Details” appendix for specific KeyServer launch options available under other operating systems and for details on which options are set up by the installer for automatic KeyServer startup (if any).

The KeyServer process will activate in one of three states:

i) full service with support for the licensed number of client accounts

(a valid version 7.4 server.lic is installed)

ii) service for a limited number of clients supported in evaluation mode

(there is an unexpired eval.lic file but no no valid server.lic)

iii) no service

(the eval.lic has expired and there is no valid server.lic)

On some of the host platforms you can inspect system startup information in various console or error logs. For more information, read the “OS Details” appendix.

Caution: if you launch a second 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 previously running KeyServer process before starting KeyServer.

Shadow Install – KeyShadow

In addition to the states listed in the previous section, the KeyServer program has another behavior when it is installed with a “shadow” license (shadow.lic) instead of a server license (server.lic). The installed service then becomes a “KeyShadow” which mirrors the KeyServer's data in order to take over service in the event of a network failure. KeyShadows are not necessary. Assuming K2’s defaults are accepted while setting up policies, then managed programs will be allowed to run when the client computer is off-line or when the KeyServer is unreachable for any reason. It is only when the default "Relaxed" Enforcement option is changed to "Strict" or when the optional "keyed" management method is used that KeyShadows become important.

Not only are shadows usually unnecessary, they also can result in KeyServer's reports being less accurate than they might be, since offline usage on a given client is loaded up to the KeyServer at next connection, and subsequently included in reports. Client usage accrued against shadows is, on the other hand, left on the shadows and consequently not included in reports.

If the optional “keyed” method of securing software against piracy has been employed for one or more applications, then installation of one or more KeyShadows is advisable. A keyed program is altered in such a way that it must obtain its key in order to run. Hence for keyed programs, KeyShadow's ability to provide an alternate path for a client computer to obtain a key can be a very important fail safe mechanism whenever the KeyServer is unreachable for any reason (e.g. network failure or hardware failure of the KeyServer host). Note: an unkeyed program that is managed by a KeyServer can be configured to use “Strict” enforcement - in this case, KeyShadow will be just as important for this managed unkeyed program as it is for keyed programs.

KeyServer will add a KeyShadow address to its “shadow hint list” when an installed KeyShadow first makes contact with its parent KeyServer. Clients will receive a list of shadow addresses automatically every time they login. KeyShadow is designed to automatically mirror all of KeyServer's configuration data (in an encrypted form). A KeyShadow will start serving whenever KeyServer doesn't respond to periodic status requests from the shadow process. If there is a network or hardware failure that prevents clients from reaching the KeyServer, they will then try to reach a KeyShadow.

Requirements for hosting a KeyShadow are similar to KeyServer but without the storage or performance requirements.

When the KeyServer component is running as a KeyShadow process, clients must be able to connect to the shadow host address using UDP port 19315 (instead of 19283 used by KeyServer).

Since the standard eval.lic does not have a custom serial number for unique identification, it is not possible to “shadow” a standard evaluation KeyServer. Hence KeyConfigure connected to an evaluation KeyServer will not allow creation of a shadow certificate.

To create a KeyShadow, choose a computer host that is strategically located so clients are likely to be able to reach it even when the network link to the KeyServer host is broken. Then:

1. Connect KeyConfigure to the running KeyServer and from the Config Menu, select “Create Shadow Certificate...”. The configuration dialog offers three ways to enter an address for the KeyServer. Like the configuration of the KeyAccess client, it is best to specify the DNS alias name for the KeyServer process (or, second best, the KeyServer host DNS name). Specifying a fixed ip address, while possible, can cause problems in the future as explained here. In order to prevent duplicated copies of the KeyShadow software from running on unauthorized computers, the shadow installation can be protected by a "shadow password".

2. Run the KeyServer installer to create a fresh install (never an upgrade!). The installer will finish up with a dialog suggesting that you start up the KeyServer process - choose "no, don't startup KeyServer".

3. Copy the shadow.lic file into the KeyServer Data Folder. [Note: the installation of a shadow.lic instead of the server.lic is what makes the process run as a KeyShadow instead of the KeyServer.]

If your KeyServer has in addition to its server.lic file, some special “vendor License certificates” (e.g. vendor_name.lic ), these must be copied to the shadows along with the shadow.lic. Note: if the vendor requires a dongle on the KeyServer, shadows will need one as well (along with dongle driver files).

4. If you are using a shadow.lic that was created without a password, start the ks process as you normally would start the KeyServer itself.

But if your shadow.lic is password protected, then from an account with administrative rights, start up the KeyShadow process in a special “user interface mode” so you can type in the “shadow first-run password”. Then restart the process as a normal “faceless” task:

For the first launch on Windows, rather than starting the KeyServer as a service, select ks.exe (in \Program Files\Sassafras K2\Server) and use right click to "Run As ...administrator". This will present a user interface where you can enter the “shadow first-run password” created above. Once this is done, you can quit the ks.exe program and start the KeyServer service using the services control panel.

For the first launch on Mac OS X, bring up a terminal window and type in the command:

       cd /Library/KeyServer; sudo /Library/KeyServer/ks -c

You will be asked for your admin password. Then several message lines will appear followed by a request for the “shadow first-run password” created above. After entering it and hitting the enter key, the shadow process will start and the terminal window will say “ready”. Use ctrl-c to quit the ks process so that you can then restart it as a faceless process (e.g. a daemon outside of any terminal session) using the ks-StartSop applet.
Or use the terminal command:

       sudo launchctl load /Library/LaunchDaemons/com.sassafras.KeyServer.plist

Admin Requirements

KeyConfigure’s capabilities are essentially identical when run on either Windows or Macintosh. Even when auditing or managing licenses for both platforms, KeyConfigure can be run on which ever platform is convenient. There is one exception to this rule. Due to KeyServer’s optional keying feature for secure management, the actual step of using KeyConfigure to transform a copy of a program file into a keyed version must be done on the program’s native platform.

KeyConfigure’s internal reports will require more or less memory and disk space depending on how each particular report is summarizing data and how many detail records must be downloaded from the KeyServer. One hundred megabytes of memory and half a gigabyte of disk space should suffice for most reports even when KeyServer is supporting thousands of clients. Extreme cases and more detailed resource estimates are documented in the “OS Details” appendix and the Reports documentation.

Except as noted above, the hardware and software requirements for running KeyConfigure are minimal and generally the same as for the client component (see below). The KeyServer hosts connections from KeyConfigure on UDP and TCP port 19283.

Admin Install – KeyConfigure

Run the Admin Install on one or more computers where it will be convenient for you to manage KeyServer. You may 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.

The default password for the KeyConfigure administrative connection is “Sassafras” (first letter capitalized). Communication is via UDP and TCP on the default port 19283. You will need to open this port in any firewall that is between the admin computer and the KeyServer.

Reporting – KeyReporter

KeyReporter provides a dashboard view of your K2 usage and configuration data. It also allows you to configure reports to be run automatically on a schedule, and gives web access to all the same reports which are available in KeyConfigure. It is installed with KeyServer, and can be configured to run on the standard http port or a non-standard port. For more details on installation, configuration, and use of KeyReporter, see the KeyReporter and KeyReporter Setup documentation.

Client Requirements

Client computers must be connected to the network and properly configured with TCP. Mobile clients, (i.e., portable or laptop computers), can be configured for use of managed software while disconnected but they must be on the network to gain a KeyServer account when the client software is first installed.

It is best to set up your DNS server with an alias name configured to resolve to the IP address of your KeyServer host computer. Then clients are configured using this DNS name instead of the hard IP address.

The client software, KeyAccess, is designed to have negligible impact on performance regardless of the specific operating system and hardware environment. If a client computer is configured to audit for installed software, mounted local disks will be scanned periodically by KeyAccess. Otherwise, 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.

The KeyAccess client software can be run under any 32 or 64 bit Windows operating system (Windows XP thru Windows 8.1). The task manager will report from 5 MB to 15 MB of “Mem Usage” for KeyAccess, but this total really only reflects which shared system resources are included. The actual size of KeyAccess executable code (including its private transport libraries and private data) is much less.

The KeyAccess client software can be run on any Intel processor running Mac OS X 10.6 or better.

Client Install – KeyAccess

When KeyAccess is installed on a client computer, it must be configured with the desired address to access the KeyServer. You will have to know the IP address or the DNS name of the KeyServer machine.

Run the Client Installer on all desktop computers that you wish to manage with KeyServer (and on Thin Client servers). KeyServer is licensed to support a fixed number of client records which can be any mix of Windows, Macintosh, and Thin Clients. Each of these computers needs to have the client software, KeyAccess, installed in order to communicate with KeyServer. When installing, your KeyServer should be up and running so you can immediately use KeyVerify to test KeyAccess’s network connection to KeyServer.

You should choose the appropriate installer to match your OS - K2Client.exe for a 32 bit OS or K2Client-x64.exe for a 64 bit OS.

During the Client install you will be asked to supply a DNS name or raw IP address for the KeyServer. Don’t enter the Windows NT server name into the KeyAccess Setup “Connection” field! The address field in the setup dialog is for the raw IP address or a DNS name of the KeyServer host.

When a new client first connects to the KeyServer, a new computer record is created and it shows up in the "Computers window" in KeyConfigure - click on the word "refresh" at the bottom of the window to see new items immediately. You can inspect this window to confirm that clients are logging on correctly.

For a large scale client deployment, the client installer can be pre-configured with the KeyServer host address and customized preferences for silent installation or upgrade of the client components. General purpose software deployment tools (including image cloning, logon scripts, network install, Group Policy Objects, NetBoot, etc.) can also be used. For more information, consult the following help pages: Deployment, Cloning, Customizing Mac Installer, and Customizing Win Installer

KeyCheckout

For mobile computers (laptops or portables) that will use managed software off-line, you may want to install the optional component, KeyCheckout. This can be done by customizing the K2Client installer (Win,  Mac). KeyCheckout is used to manually “checkout” a software license for use on a mobile computer that won't always have a network connection. An end user must specify an expiration time when the license will be automatically reclaimed by the KeyServer. During the entire checkout period, the managing license policy is regarded as "issued" and "in use".

By default, an unkeyed program in a product will be allowed to launch when offline, regardless of the license limits specified in any Policy managing the product. The offline usage will be recorded by KeyAccess and uploaded to KeyServer when the client returns to the network. But if the Enforcement option has been changed to “Strict” for a concurrent use policy that manages the product, then the unkeyed program will behave like keyed – it will not run unless granted a license. The license can come from an active network connection to the KeyServer or it can be granted in advance for some period of time using KeyCheckout.

A client using programs from a Product that is managed by a node locked or leased metric (instead of a concurrent use metric) will always cache the "license key". Therefore the key will be available for use offline for some period of time without using KeyCheckout. This cached key must be refreshed, however, by reconnecting to the KeyServer periodically (and for a leased metric, a program launch is required to renew the lease). The default Enforcement setting of "Relaxed" will allow an unkeyed program to run even after the cached key has expired – but of course this does not apply to a keyed program which won't run after the cache expires.

In today's world of ubiquitous network connectivity, most sites have no need for the legacy KeyCheckout program. Even very slow connections are completely adequate to support a remote client session with the KeyServer (assuming that traffic incoming to KeyServer on port 19283 is not being blocked by a firewall). To support users that are sometimes completely disconnected, a leased metric policy configured for use offsite may provide more transparent and convenient software access than using KeyCheckout.

Testing KeyAccess connection – KeyVerify

After installing KeyAccess on a client computer and configuring it to connect to your KeyServer, bring up the KeyAccess Setup window:

In the Windows Control Panel folder click on the item named KeyAccess.

On Mac OS X, open System Preferences and click on the KeyAccess preference pane.

Select the Logon button in the KeyAccess Setup window – 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 with no firewalls blocking UDP port 19283.

Use the KeyVerify button in the setup window to further test and verify KeyServer’s policy management functionality. You can find the KeyVerify policy listed in KeyConfigure's Policies window. Play with its policy configuration parameters and usage reports while running the KeyVerify test from various client machines. This is a good way to test complex configurations using a managed program (KeyVerify) that is always installed on all client computers.

The KeyVerify test program is not only managed but it was created using the “keyed” option so it will launch only if KeyAccess is successful in obtaining its key. When the launch 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 the KeyAccess Setup interface and check that you have correctly selected the KeyServer name or correctly entered its address.

Backup

All the custom license management information (program keys, policy 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 management, it is most important that you back up at least the Product Database file – keyed programs are useless without it. You should also keep backups of the original program files themselves, before they are keyed. Consult KeyConfigure’s built in Help for details on how to set up a schedule for automatic backups and how to configure a remote storage location.

There is a backup option under Config Menu of KeyConfigure, but by default the Backup folder is located inside the KeyServer Data Folder itself. Change the backup location to a different disk by creating an alias link in place of the the Backup folder.