Introduction

Welcome to the Sassafras Software Product Suite.

The Sassafras Software license and asset management toolkit integrates software and hardware auditing with active license management and entitlement tracking and lifecycle management 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 data along with map visualization of your assets, as well as easy access to report information.

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. Sassafras products have been carefully designed to facilitate license management for Windows, MacOS and Linux software deployed on laptops, desktops, file servers, virtual machines, and thin client servers.

In this Getting Started document, “you” refers to the Sassafras Server Administrator, the person who will be setting up the Sassafras Server and configuring its services. You will find that the Sassafras Software KeyServer Suite 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. It also provides hardware reporting and lifecycle management including purchase tracking, and includes visualization tools for your users and other management and finance stakeholders.

The Sassafras KeyServer Platform is a powerful tool that will help you optimize software and hardware asset utilization throughout your entire enterprise (not all features available in LabSight or KeySight tiers):

The Deployment Overview provides a high level outline of considerations for implementing our software.

We have a Quick Install document for a very brief outline of setting up the solution.

The Full Walkthrough takes a more in depth look at all the steps of installation, configuration, and implementation.

Documentation Overview

The help documentation is viewable online from the Sassafras Software web site. Additions or corrections to the documentation are made frequently so www.sassafras.com/documentation 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 Sassafras products:

•  Getting Started

This is the document you are reading. It is a general overview of the Sassafras Software products, 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 configurations and for troubleshooting. The section describing some typical license management strategies should help you decide which features will be useful at your site.

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

•  Upgrades

There have been some significant changes between various major versions within 7.x, and users upgrading from 7.0 - 7.8 should use the Server Upgrade: 7.x -> 7.9 documentation.

•  Help

The Sassafras Server admin program, KeyConfigure, includes a help menu that will display 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. You may also press F1 to automatically take you to the help page for the active window in KeyConfigure.

•  Search

The html help system has a search box in the upper right of each page. Click the “?” icon for an explanation of the search syntax. Related pages to the one you are viewing will be shown at the end of the top navigation bar.

•  README.html

Every Sassafras Software 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 Sassafras Software image. Unlike other documentation, the readme is changed for every new image and therefore may contain information not found in the main documentation. You will find it at the top level of every image folder.

•  www.sassafras.com

There may be warnings, news, supplemental documentation, blogs, or add on 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 Software web site for new information.

Whenever possible, Sassafras Software documentation is generic so it applies to all supported platforms. Both the server process (KeyServer) and the web service (KeyReporter) work 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!

Sassafras’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 Sassafras Software 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, MacOS and Linux. The server process, KeyServer, supports both license management (KeyServer) and auditing (KeyAuditor) functions, as well as including the web component (KeyReporter).

•  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. While much management takes place in the web UI (especially as of 7.7) some functions require the use of KeyConfigure.

•  KeyAccess – client

KeyAccess and related components implement communication from each client computer to the KeyServer process. Windows, MacOS and Linux client computers (laptop, desktop, and server) are supported as well as virtual machines and thin-client sessions. Allocated client seats in KeyServer are what determine your Sassafras Software license use.

•  KeyReporter – web dashboard

The KeyReporter component implements a dedicated web server process that can automatically send schedule reports, display rich data dashboards, manage lab maps, and perform much of the KeyServer configuration. It includes many tools that are not in the older KeyConfigure desktop application. It is installed along with KeyServer, do not install the stand alone KeyReporter component along with KeyServer, it will cause conflicts when doubled up. KeyReporter is compiled for Windows, MacOS and Linux.

The names KeyServer, KeyConfigure, KeyAccess, and KeyReporter are used to refer to the software which implements server, administrator, client, and web/reporting functions respectively. “The Sassafras KeyServer Platform” refers to the complete system of components that implement the auditing, license management, and reporting functions included in each Sassafras Software product that can be licensed. AllSight, LabSight, and KeySight are the activated tiers of the platform depending on the purchased license.

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 along with the web and reporting service. 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 Sassafras Software 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 isn't necessary, and usage data is uploaded when the computer comes back online. If however you have a strict concurrent license enforced by KeyServer and no other first party license manager, this could a useful tool. The KeyCheckout program can be installed by a customized version of the client installer or as an option during interactive installation.

• 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).

Versions & Updates

Sassafras Software installers are distributed as a downloadable archive from the Sassafras Software 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: “KSP v8.0 (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 “Sassafras Software image”.

The compressed image archive is available either as KSP-v77.zip (a zip archive for expansion on Windows or elsewhere) or as KSP-v77.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 Sassafras Software toolkit are released as required to repair bugs, add requested features, and maintain compatibility with new operating system releases. The admin component, KeyConfigure, has built in version check functionality. 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 within the major version release (e.g. 8.0.x.x). To have full functionality, it is highly recommended you do upgrade the server and admin components at the same time. Clients can be any version forward or backward which allows for easy roll out of upgrades, but will also some times require a new version to take full advantage of all new features. See the Component History for any such relevant details.

Web Updates

There is a readme file at the top level of every Sassafras Software 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 Software web site for downloading a compressed archive (~350 MB) containing the most recent Sassafras Software image. The README.html inside each particular Sassafras Software 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 Software with any questions or to request an evaluation license supporting more clients.

When you purchase a Sassafras Software product 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 Sassafras Software 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, MacOS, Linux, Virtual, 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 version 8.0 specifies a version range going back to 7.6, so while valid and supported we urge updating to take advantage of many new features and bug fixes.

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

Introduction I. Walkthrough