I. Introduction

Welcome to K2 from Sassafras Software.

The K2 license management toolkit integrates software and hardware auditing with active license management and entitlement tracking in a single package. The KeyAuditor functionality allows for automatic, scheduled audits of all client computers while KeyServer functionality lets you log, meter, and manage usage of all application programs regardless of where the software is used or stored. A comprehensive collection of summary and detail reports is built into the administrative program, KeyConfigure. A web server component, KeyReporter, offers a customizable dashboard summary of K2 data.

A single admin program allows you to control all aspects of software auditing, purchase tracking, and license management functions. Flexible (but optional) integration with other management tools such as help desk, authentication services, software distribution, etc. is facilitated through standards based data export, authentication, and database query interfaces. K2 has been carefully designed to facilitate license management for Windows, Macintosh, Linux, and Solaris software deployed on laptops, desktops, file servers, virtual machines, and thin client servers.

In this Getting Started document, “you” refers to the K2 Administrator, the person who will be setting up the K2 server and configuring its services. You will find that K2 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 and monitor usage patterns, while it gives licensed users transparent access to managed software.

K2 is a powerful tool that will help you optimize software asset utilization throughout your entire enterprise:

The Quick Install & Tour will get you up and running as quickly as possible. If you are impatient, try skipping ahead to the tour but then come back for these introductory comments.

Versions & Updates

K2 is distributed as a downloadable archive from the Sassafras web site (~350 MB). Installers for Server, Admin, Reporter, and Client can also be downloaded individually for each target platform, but usually a download of the complete image (including all installers) will make it easier to keep things organized. Each release is named following this pattern: “K2 v7.4 (yyyy-mm-dd image)”. The date stamp which is part of the folder name is called the “image date” (e.g. 2015-07-10) and it is used to identify the complete set of installers and documentation assembled together to form a complete release of the “K2 image”.

The compressed image archive is available either as k2v73arch.zip (a zip archive for expansion on Windows or elsewhere) or as k2v73arch.dmg (a disk image for mounting on Macintosh). Regardless of which download format you use, it will expand to an image folder that includes complete documentation and a complete set of installers for all platforms. You can easily copy the entire contents (~350 MB) onto a hard disk or file server volume, or you can duplicate individual installers as needed.

Updates for the various components of the K2 toolkit are released as required to repair bugs, to add requested features, and to maintain compatibility with new operating system releases. The admin component, KeyConfigure, has the typical version check functionality built in. This feature will inform you of new versions for all components, not just KeyConfigure itself. While it is generally recommended to keep all components up to date with the latest minor bug fix release, compatibility between server, admin, and reporter only requires that they all are version 7.4.x.x.

Documentation Overview

The help documentation is viewable online from the Sassafras web site. Additions or corrections to the documentation are made frequently so www.sassafras.com is the best source for the most up to date information. Note: the admin installer also creates a static local copy of these documents in its Help folder.

The descriptions below give an overview of where to find information on various aspects of K2:

•  Getting Started

This is the document you are reading. It is a general overview of the K2 product, and is a good starting point for new users. In addition to installation instructions, it will give you a conceptual framework for thinking about various K2 configurations and for troubleshooting. The section describing some typical license management strategies should help you decide which K2 features will be useful at your site.

When you need to go beyond the most basic K2 operation, and for details on how to fully implement a particular management strategy, consult the rest of the on-line help documentation.

•  Upgrades

Owners of KeyServer 5.2, and K2 version 6.2 or earlier should definitely read the Server Upgrade: 6.x -> 7.4 page. It contains specific instructions on how to import existing license management data while being careful to avoid disabling programs or losing client support as you upgrade. There have been fewer significant changes between various major versions within 7.x, and users upgrading from 7.0 / 7.1 / 7.2 / 7.3 should use the Server Upgrade: 7.x -> 7.4 documentation.

•  Help

The K2 admin program, KeyConfigure, includes a help menu that will display the K2 documentation in your default browser. A right-click anywhere in the KeyConfigure interface will bring up a context menu that always has Help as the top item. Select this menu item to display the specific help document appropriate to the context.

•  Search

The html help system has a box in the upper right of each page which contains related links and a search form. Click the “?” icon for an explanation of the search syntax.

•  README.html

Every K2 image contains a README.html file which documents the date of release (the “image date” ) as well as important warnings and revision information. Use a browser to open the readme whenever you get a new K2 image. Unlike other documentation, the readme is changed for every new image and therefore lies outside of the Administrator’s Reference – you will find it at the top level of every image folder.

•  www.sassafras.com

There may be warnings, news, supplemental documentation, or new components that are announced and made available only from the web site. In addition to documentation included with every image, you should occasionally check the Sassafras web site for new information. You may want to subscribe to the RSS feed, www.sassafras.com/RSS/news.rss. To be notified of minor releases, subscribe to www.sassafras.com/RSS/tech.rss.

Whenever possible, K2 documentation is generic so it applies to all supported platforms. Fortunately, both the server process (KeyServer) and the reporter process (KeyReporter) work without any visible interface on Windows, Macintosh, and Linux. Hence for these processes, the only platform specific documentation needed is for installation. Windows and Macintosh installation is documented on the Install page, while details for other host platforms are covered in the appendix, OS Details. But remember - you choose only one of these platforms to host your KeyServer!

K2’s Administrative and Client components are licensed for use on multiple administrative and client computers. The Administrative component is restricted to Windows and Macintosh. Component file names and directory locations differ between operating systems, but most often these differences are slight and can be ignored.

When it is necessary to explicitly document operating system differences, the appropriate platform icons will be used to tag the system specific details. You may want to treat the operating system icons as a signal to skip over the text, depending on your platform focus.

Components & Terminology

The software component files created by various K2 installers fall into four main categories depending on function:

•  KeyServer – server process

KeyServer and related components implement the central auditing and license server process that runs from a single host. KeyServer is compiled for Windows, Macintosh, Linux, and Solaris. The server process, KeyServer, supports both license management (KeyServer) and auditing (KeyAuditor) functions.

•  KeyConfigure – administrator's console

KeyConfigure and related components implement remote management and configuration of the KeyServer from a Windows or Macintosh computer. KeyConfigure includes hundreds of built in templates for reports that summarize purchase data, software usage, license compliance, hardware configuration, and installed software.

•  KeyAccess – client

KeyAccess and related components implement communication from each client computer to the KeyServer process. Windows, Macintosh, Linux, and Solaris client computers (laptop, desktop, and server) are supported as well as virtual machines and thin-client sessions.

•  KeyReporter – reporter process

The KeyReporter component implements a dedicated web server process that can be scheduled to produce management reports automatically and publish them in html format. It is installed along with KeyServer. KeyReporter is compiled for Windows, Macintosh, Linux, and Solaris.

The names KeyServer, KeyConfigure, KeyAccess, and KeyReporter are used to refer to the software which implements server, administrator, client, and reporter functions respectively. K2 refers to the complete system of components that implement the auditing, license management, and reporting functions.

Actual executable names don't match the full names listed above. For a complete list of component file names on each OS platform, including 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. Whenever the KeyServer program is activated (launched as a program, started as a service, or launched as a daemon), client computers can connect, upload audit data, and exchange license management information. There is no “network operating system” or file server requirement. Simply install the KeyServer component on some host computer in order to turn it into a “license management and audit server”. Install the client software on all computers that you want to manage.

The KeyServer host may be a computer dedicated to running the KeyServer program, a high performance virtual computer, 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 opens port 19283 and listens for incoming connections from both KeyAccess clients (using UDP) and from the KeyConfigure admin program (using UDP and TCP). Clients must simply have an active network interface with an IP address that can communicate with the KeyServer host IP address. All of the intricacies of switching, routing, bridging, VPN tunnels, verbalization, etc. are invisible to these simple requirements.

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 plus the optional reporter function. It is typical for the KeyConfigure administrative software to be installed on several computers that are also functioning as clients.

It may be convenient to also install KeyConfigure on the computer functioning as the KeyServer host, 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 K2 Package includes several utility components:

• ks-prs

The ks-prs utility is installed along with KeyServer and is used for the Product Recognition Service.

• KeyVerify

The KeyVerify client utility is useful as a diagnostic tool to verify the connection between a client computer and the KeyServer. When launched, its interaction with KeyServer is similar to any managed program. When KeyVerify is running, it displays information about the KeyServer connection.

• KeyCheckout

KeyCheckout is used primarily on portable computers that need to check out a license for long term off-line use. For many license management policies, KeyCheckout functionality is actually unnecessary since managed programs are allowed to run off-line by default. Usage data is uploaded when the computer comes back online. The KeyCheckout program can be installed by a customized version of the client installer, but it has been made almost obsolete by newer mechanisms for observing and managing software usage offline.

• KeyShadow

The KeyShadow server utility is actually just the KeyServer software enabled by a shadow license instead of the standard license. A KeyShadow process provides a fail-safe backup to the KeyServer process. It will take over service in case the KeyServer is unreachable due to network, software, or hardware failure.

• Reporting Tools & ODBC connectivity

The KeyConfigure admin program includes several built in reports which send SQL queries to KeyServer using the proprietary “ks” protocol. The KeyServer ODBC driver, “ksODBC”, is supplied to support connections directly to the KeyServer from third party reporting tools such as Crystal Reports, MS Access, FileMaker, etc. so that you can augment the built in reports with custom reports that join to other data sources. KeyServer can also be configured to export its management databases to a third party SQL dbms such as Oracle, SQL Server, MySQL, etc.. Then both built in and custom reports can connect to the remote data server using its ODBC driver (and a correctly configured DSN).

Web Updates

There is a readme file at the top level of every K2 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 (~350 MB) containing the most recent K2 image. The README.html inside each particular K2 image gives you a quick way to check on revision status of the image and to obtain updates when necessary. You may also check for new versions from within KeyConfigure at any time.

License Certificate File

When installing KeyServer on any platform, an evaluation license certificate, eval.lic, will be created by the installer. Typically an eval.lic will support only seven clients with an expiration date that limits use to a month or two. You can open the eval.lic as a text file and see these values expressed as “feature.seat” and “feature.expires”. If you downloaded the installer months ago, you may have to download a more recent copy in order to obtain an eval.lic that has not already expired. Don't hesitate to call Sassafras with any questions or to request an evaluation license supporting more clients.

When you purchase K2 and submit your e-mail address as the registered contact, a custom License Certificate file, server.lic, containing serial number and specified client limit will be e-mailed to you. To upgrade your KeyServer from evaluation mode to a full function KeyServer supporting your licensed number of client accounts, you must place your custom server.lic file into the KeyServer Data Folder and restart the server process. Read the “Server Install – KeyServer” section of the Install page for detailed instructions.

Even though the K2 image contains installers for creating the server process on several different platforms, you must choose only one computer to host the KeyServer and then install your custom server.lic file only on this computer. Regardless of the host platform chosen, KeyServer will manage Windows, Macintosh, Linux, Solaris, and thin client computers.

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, multiple KeyServers identifying themselves with the same server id (obtained from the server.lic file) could lead to erratic and unpredictable behavior for both client and administrative components.

The server.lic file is readable as text so you can inspect the number of clients it supports (“feature.seat”), the server versions supported (“license.range”), etc. The first two significant digits of the KeyServer version number must be supported within the license range specified in the certificate. The license certificate provided with K2 version 7.4 has license.range=5.2-7.4 so it will support the previous KeyServer versions from 5.2.x.x up through 7.4.x.x.

A version 7.3 or earlier license certificate will not support a 7.4 KeyServer – if present, these older certificates will be ignored. Unless there is a valid 7.4 license certificate present (such as an unexpired 7.4 evaluation license), the 7.4 KeyServer process will not start. Before upgrading to version 7.4 from an older version, a new license certificate must be obtained.

I. Introduction continue