K2 – Getting Started Installation Guide & Technology Overview

     – Server, Admin, Client Install — on a single host computer
     – Explore KeyConfigure — basic functionality
     – Program Actions & Rules — Audited, Logged, or Controlled
     – License Types — Floating versus Node Locked
     – Group Definitions — node list, divisions, network location, authentication
     – Key an Application — file modification for Secure Control
     – Software Audits — scheduled, centralized, data collection
     – Computer Divisions, Program Folders — discover / acknowledge / filter / hide
     – Web Reports — scheduling reports, browser-based reports
     – Clean-up — removing the K2 demo files

Quick Setup & Demo Tour

To demonstrate how the Server, Admin, and Client components interact, the steps below outline a first-time installation of all three functions on a single host computer. If you have a previous version of the server component (KeyServer) already installed, you should read the Upgrades chapter before proceeding.

The tour is most effective if you install the client software on a second computer as well, but this is not absolutely necessary. It is important, however, to follow the tour sequence exactly since each step depends on the context set up by the previous steps.

Our tour will generally describe Windows file naming conventions and file locations. The file names for Windows installers end with .exe. The corresponding Macintosh installer file names end with .app or .mpkg. Differences between Windows versus Macintosh install locations and component file names will be explained by the installer dialogs. Consult the “Installation” chapter and the “OS Details” appendix for more complete OS specific comments, including system requirements, network requirements, installer customizations, and cautions.

For this tour, client and admin functions can be installed on the same host and/or on some other computer(s) where convenient. It will be fine to use your desktop or laptop computer for this demo, but make sure the server process is hosted on a computer that is not configured to “sleep” during your testing! If you are installing within a virtualized environment (e.g. vmware, parallels, etc.), set up the virtual machine to use bridged networking.

You can run the installer for any K2 function (Server, Reporter, Admin, and Client) directly from any mounted volume, local or remote (or from within a .zip or .dmg archive).

Server, Admin, Client Install — on a single host computer

1. Install the KeyServer process.

Logon to the host computer with full administrative privileges. Inside the K2 image folder, there is a folder containing installers for all components on all platforms. Open the “Server Installers” sub-folder and run the appropriate installer for the KeyServer process (“K2Server.exe” for Windows or “K2Server.app” for Mac). It will create a folder named “Sassafras K2” in the Program Files directory with a shortcut installed in the Start menu. KeyServer (ks.exe) and its “KeyServer Data Folder” will be installed in the sub-folder named “Server”.

If you have a custom License Certificate (server.lic), don’t start the KeyServer process yet! Wait until completing step 2 below.

Without a custom license, you can skip over step 2 – KeyServer will use the default evaluation license file named eval.lic, which is created by the installer. If the evaluation license has already expired and you don’t have a custom license (to use in its place), you will have to download a more recent server installer.

2. Install your custom License Certificate and start KeyServer.

If you have received by e-mail a custom server.lic license file, place it into the KeyServer Data Folder (inside the Server folder). On Windows, use the services control panel to start the KeyServer process (stop and restart the process if it is already running). Note that you will get an error message if you start the KeyServer process using both the services control panel and by double clicking the ks.exe file.

Steps 1, and 2 above are nearly the same for a Macintosh host but must be modified somewhat for other operating systems. Specific issues when hosting KeyServer on Linux or NetWare are dealt with in the Appendix: OS Details. But remember, you only install the server process on one computer. This one install will provide license management services throughout your network and across the Internet to all your client computers (Windows, Macintosh, and Thin Client).

The next steps will assume that KeyServer has been successfully installed and the process has been started, either with a custom license or with an unexpired evaluation license. Before proceeding with the Admin and Client installs, you will need to know the IP address of your KeyServer host. To find the IP address on Windows, type “ipconfig” at the command prompt. On Macintosh you can consult “About this Mac” from the Apple menu.

3. Install KeyConfigure, the Administrative interface for K2.

From the Admin Installers folder in the K2 image, run the appropriate admin installer (“K2Admin.exe” for Windows or “K2Admin.mpkg” for Mac). You can accept all of the installer defaults.

Note that it is not actually necessary to install KeyConfigure on the same computer that is hosting the KeyServer process, but it is convenient to run it here for this demo tour. In a typical installation, KeyConfigure might be installed on several computers for the convenient remote administration of the KeyServer process by one or more people.

4. Test an Admin connection to KeyServer.

Launch KeyConfigure. Use the KeyConfigure shortcut in the “Sassafras K2” group from the Start menu or just double click on the executable in the Admin folder. A Login dialog will be displayed.

In the topmost field, enter the IP address (or DNS name) of the computer hosting the KeyServer process. You just looked up this “Server” address in your preparation for step 3. Login using the account name, “Administrator”, with the default password, “Sassafras” (first letter capitalized).

KeyConfigure will bring up three windows named Computers, Programs, and Licenses in their “standard” position. If you move windows around you can always return to this standard view by selecting “Standard” from the Window menu.

These three windows display the basic building blocks for the configuration of software auditing, license management, and report generation. As soon as you install and connect a client computer with the K2 client software (below), it will automatically show up in the Computers window. All programs discovered on each client computer will automatically show up in the Programs window. The Licenses window, however, will never acquire new items automatically.

Initially the Licenses window will include only the items named KeyCheckout License and a KeyVerify License. These are created by default to give KeyServer control over its own utility programs. Double click on the KeyVerify License and you will see that it controls two programs, KeyVerify for Windows and KeyVerify for Macintosh. In its initial state, the Programs window lists four items: a Windows and Macintosh program item for each of these two utilities.

You will use the Licenses window to explicitly create new licenses for controlling the use of programs on computers. A single license can be configured to control one or more programs. Usage for the license can be enabled for all client computers (usually subject to a maximum limit), or restrictions can be imposed based on network location, time, specific computer node ID, etc.

Before you start experimenting with KeyConfigure to explore K2 features, you should be aware that some of KeyConfigure’s actions cannot be undone. In particular, the optional feature that lets you transform a program into a “keyed” copy is not reversible – only a backup or reinstall will restore the original. Rather than experiment blindly, it is best to carefully follow the steps in this tour and then read subsequent chapters and help documents for more detailed and specific information.

In the next steps, the client component, KeyAccess, will be installed and verified. For the purposes of this demo tour, you can install the client on the same computer where you have installed KeyServer (and/or KeyConfigure) even though in many typical installations, the KeyServer host computer would not be treated like a regular client workstation (e.g., it may not need to be audited or controlled).

5. Install KeyAccess client software - then reboot

From the Client Installers folder in the K2 image, run the appropriate client installer (“K2Client.exe” for Windows or “K2Client.dmg” for Mac). Enter the IP address or a DNS name for the computer hosting the KeyServer process. Note: normally the KeyServer must be hosted on a computer with a static IP address, but as long as the address doesn’t change during the demo tour, a dynamically assigned address (DHCP) will be fine.

6. Test Client connection to KeyServer.

After the restart with the client software installed, run the diagnostic utility, KeyVerify:

Click on the KeyVerify button in the KeyAccess control panel. The control panel can be opened by clicking the Start menu and choosing Control Panel, then double-clicking on the KeyAcccess icon.

Click on the KeyVerify button in the KeyAccess preference panel. The preference panel can be opened by choosing System Preferences from the Apple menu, then clicking on the KeyAccess icon.

Assuming that the KeyServer process is running and the KeyAccess client software is configured correctly, KeyVerify’s window will indicate a valid KeyServer connection.

If you don’t get confirmation of a valid connection, double check the KeyServer address that was entered during the client install. On a Windows computer, use the Run... item from the Start menu and enter “keyacc32”. On a Macintosh, use the KeyAccess System Preference panel. Assuming the KeyServer address is entered correctly in KeyAccess, the next thing to check is that the KeyServer process is started (check KeyServer the Services control panel on Windows, or look for “ks” in Activity Monitor on Mac), and that the KeyServer Data Folder contains an unexpired license certificate. You can open the eval.lic or server.lic file as a text document and read the expiration date.

A similar client install sequence must eventually be run on all computers that will access K2’s software auditing and license management services. Both the Windows and Macintosh client installers can be pre-configured with your target KeyServer address and other options to help automate a large scale deployment using standard deployment or computer image management techniques.

Explore KeyConfigure — basic functionality

7. License Details.

With KeyVerify still running from step 6, the Licenses window will show one in use for the KeyVerify license (launch KeyVerify again if it’s not running). Double click on this license to see details. Notice that the license is set up for a maximum of 2 Concurrent users. One out of two (1/2) of these licenses are in use.

8. Send a Bulletin to a Current User.

In the License Details for KeyVerify, click on the button labeled “Current User List (1/2)”. Double click on a user in the list to bring up the detail window, “User Details for...”, and click on the “Send Bulletin...” button. Type a message and Click OK to send. Your message will pop up on the client computer.

It should be pointed out that bulletin service is not always available for every client listed in the Computers window. Only clients that are currently connected to KeyServer can receive bulletins.

Before proceeding, let’s close up all of the various detail windows. Then select “Standard” in the Window menu to get back to the standard view.

9. Computer Details.

Click on the word “Refresh” at the bottom of the Computers window. The computer that you verified in step 6 will show up in the computer list. Double click on the computer name to bring up the Computer Details window where you can see the basic hardware properties for this computer. Assuming that the software audit has not finished, the time stamp field for “last audit” will not be filled in. Close the window for now - we will open it up again later after the software audit has had time to complete.

Now we will illustrate how KeyServer can manage any application according to a licensing policy that you specify. We will use Calculator as an example application for testing. On Windows, you will find a Calculator shortcut in Accessories from the Start Menu. On Macintosh, look in the Applications folder. First we need to locate the appropriate program record in the Programs window:

10. Discover Calculator.

Launch Calculator. Even if no client has had enough time to complete an audit, the launch will immediately add this new “Discovered” program to KeyServer’s programs database. In order to make Calculator show up in the Programs window, you will have to click on the word “Refresh” at the bottom of the window and in the Actions pane (top left of Programs window) click the double check mark to the left of the word Actions. This will select all four actions for display in the program list to the right.

Because KeyAccess has been busy auditing, the Refresh may also bring in hundreds of other discovered program items. If Calculator is hard to spot in the program list, use the Find command from the Edit menu to locate it. You can also use “type ahead”: With the Programs list in foreground, just start typing the first few letters of the program name. Unfortunately, on many Windows systems the official name for Calculator is “Windows Calculator application” so typing “C” (or even “W”) won’t suffice – this time you are better off using Find.

Note: the check marks in the left column of the Programs window determine which items will actually be displayed. The calc.exe program on windows is usually located in the system32 directory so its action is set to ignored by default. To see Calculator in the list, we are assuming that ignored items are being selected for display - if you can’t find Calculator included in the display list, make sure you have check-marked all four Actions and unchecked any Folder or Filter items below (in the Folders and Filters panes).

The data behind all of KeyConfigure’s list windows (like the Programs window and the Computers window) is cached locally so that searches and column sorts will be quick. The refresh button at the bottom of various windows will turn red when the there is new data available to be fetched from the KeyServer. You must click the word “Refresh” whenever you want to update KeyConfigure’s display to show new discoveries: new audit data, new programs, new computers, or new offline usage information (when it is uploaded from a returning client).

In the subsequent steps, the name “Windows Calculator Application” will be cumbersome, so let’s take a moment to customize the name.

11. Assign a new name for a discovered Program.

Select the “Windows Calculator Application” item in the Programs window and double click. At the top of the Program Details window you can edit the name. Change it to the single word, “Calculator”. Note: we have just changed the value of a name field in one record belonging to the programs database. This has no effect on actual program files stored on client computers – the shorter name in our database (as displayed in the Programs window) will make for simpler instructions in the steps that follow. [On Macintosh, the official name for our example program is already Calculator so you won’t need to change it.]

Program Actions & Rules — Audited, Logged, or Controlled

If your installed KeyAccess client has finished its audit (click the Refresh button to retrieve newly discovered programs), you will notice that the client sends information about all executable programs to KeyServer. The great majority are set to “Ignored” by the default rules. Ignored programs are excluded from display in Audit reports to avoid uninteresting clutter.

In K2’s initial configuration, the “Win Programs” rule sets Windows programs found in the “Program Files” directory to Audited rather than Ignored. Likewise the “Mac Applications” rule sets Macintosh programs found in the “Applications” folder to Audited. Of course, these default rules can be customized, and new rules can be added in order to further automate the categorization of newly discovered programs.

In addition to deployment data, Audited programs report their Last Usage time on each computer with every incremental update to the Software Audit Database. An extensive set of Audit reports (available from the Reports menu) provides both summary and detailed views which include the last usage times. Deployment and last usage information is actually collected for all programs, even those set to Ignored. Programs that are marked as Ignored can be promoted to Audited at any time in order to include them in Audit reports. Audit reports also include all programs set to a higher level action: Audited, Logged, or Controlled. For some IT asset management purposes, the Audited action assigned by the default rules may be sufficient for an audit-only compliance strategy.

Audit information is updated automatically so that information from each client computer will not become out of date. The update interval is configurable with the initial default set to 4 weeks. Whenever a client computer contacts the KeyServer with stale audit data it will be instructed to perform an audit and upload ASAP. As part of the Audit upload, each program that has been launched since the last audit will report its new “Last Used” time stamp.

Some usage patterns will be apparent based on the Last Usage shown in audit reports, but this usage information is updated infrequently and gives no insight into usage duration or history. You can easily raise your level of interest for some programs up to Logged or Controlled so that all launches an quits will be recorded in KeyServer’s Usage Log.

12. Set Action to Logged.

Select the Calculator item in the Programs window. Then drag & drop onto the word “Logged” in the Actions area on the left side of the window. Calculator’s icon in the Action column will change to the a yellow triangle (Logged). Note: if this action caused Calculator to disappear from the Programs window, it is likely that Logged programs have been hidden from display. To display logged items, click next to the Logged icon in the Actions area on the left side of the window.

So far, the only program usage reported to KeyServer has been the launch of KeyVerify in step 6. Now that Calculator is being logged, let’s generate some events in the usage database.

13. Launch and Quit a logged program.

Quit any running copies of Calculator. Then launch Calculator, let it run for 5 seconds or more, and quit. Do this three times.

14. Report on Program Usage.

From the Reports menu, in the Usage sub-menu select the “Usage (PROG x comp)” report and click OK to run it. Under the Calculator heading will be listed all the computers on which Calculator has run with total usage time and launch count.

Did you ever quit from KeyVerify (launched in step 6)? If not, quit KeyVerify now and click the Refresh button at the bottom of the report window. Program usage for KeyVerify will be added to the report. Leave this report window open.

Whenever a program’s action is set to “Logged” or “Controlled”, clients will send launch and quit messages to KeyServer. As you perform experiments to see how program usage is reflected in various reports, don’t expect to see any changes until a program is quit and the report is refreshed (and don’t expect to see any usage events for “Ignored” or “Audited” programs!) Most reports summarize usage based on the quit events only, so the “Total Count” field is actually the count of program quits and the “Total Hours:mins” does not include programs that are still running.

15. Report on License Usage.

Select the “Usage (LIC x comp)” report from the Reports menu, and click OK. Under each license heading will be listed all computers that have used the license.

Place the License usage report from step 15 next to the Program usage report from step 14 so you can compare them. It is important to understand the difference between Programs and Licenses. The License usage report shows just one group heading for usage of the KeyVerify License. No information concerning usage of Calculator is included in the License report because the Calculator program is not controlled by any License – usage for Calculator is only Logged.

The Program usage report shows group headings for both the Calculator program (Logged) and the Windows KeyVerify program (Controlled). Program usage events are reported in essentially the same way for both Logged and Controlled programs. But for Controlled programs, in addition to the usage events for the program, there are corresponding events reporting usage for the controlling license. The license reports summarize only the license usage events, not the underlying program usage events.

In this simple tour, usage for KeyVerify (in the PROG report) and for KeyVerify License (in the LIC report) look essentially the same, but recall from step 5 that the KeyVerify License actually controls two distinct programs, not just one. If you were to launch this second program (on a Mac client) and refresh, the distinction between these reports would become more apparent. The License report would still show summary information for the one KeyVerify license, but the Program report would show distinct usage for the Windows versus the Mac copies of KeyVerify.

The KeyVerify License is an example of a cross-platform “suite” license. In general, a license can be configured to control an entire suite of programs under a single license policy and limit. Usage reports for the license will be an aggregate of usage for all the individual controlled programs in the suite.

When the Calculator action is changed from Ignored to Logged, KeyServer immediately begins collecting the usage data that forms the basis for usage reports. Now, to add control over the Calculator program in addition to logging, let’s change the Action to Controlled. First, close up any open detail windows and return to the Standard view (Window menu). Click on the Action column in the Programs window so Calculator (Logged) will sort near the top where it will be easy to find.

16. Set Action to Controlled.

Select Calculator in the Programs window and then drag & drop it into white space inside the License window (below the existing items). The “Create License” dialog will pop up with a proposed name for the new license. Click OK to accept the name, “Calculator License”. A License Details window will be displayed showing the default configuration for the license.

Quit and relaunch the Calculator program and leave it running. As with KeyVerify in step 7, you will see in the Licenses window that the “In Use” count for the newly created License has changed to 1. In the “License Details for the Calculator License”, click on the Computer List button. You may have to click “Refresh” at the bottom of the window to see that your client computer has been added to the “Computer Node List for Calculator License”.

The default behavior of a new license (unlimited) is almost the same as KeyServer’s simpler “Logged” Action. If all you want to do is log usage and run reports, then stick with Logged. To make our new license actually control its program(s) in a useful way, we need to change some settings in the license details.

First, it is important to emphasize that as soon as you set a program’s action to “Controlled”, it cannot be run unless there is a license configured to allow the launch.

When you make any change to the default Unlimited (Site License) by adding a group restriction, node limit, or user limit, you are in general prohibiting usage wherever the restricting conditions can’t be met. Be careful to avoid blocking use of a program unintentionally.

You should always configure program actions and license control in the simplest way possible in order to promote efficient allocation of assets without risk of disabling legitimate use. It is probably also worth mentioning here that there is a good reason why the default action for discovered programs is set to Ignored or Audited – if you were to Log or Control all programs (including system startup utilities etc.), the usage database would grow very quickly. Extracting important information would then be slowed by the sheer volume of the data.

The next few steps require a second computer in order to effectively demonstrate Node Locked and Floating license behavior. Even without actually doing a second client install, reading through these steps will clarify the very different control policies enforced by these two license types.

Computers Window — Discovering new clients

Every computer on which you install KeyAccess will appear in the Computers window. Once a client computer is Discovered you can change how it is treated by K2, what level of information is gathered, and which licenses the computer may access.

17. Install and test the KeyAccess client on a second computer.

On a second computer, run the client installer and then launch KeyVerify (i.e., repeat step 5 and 6). In order to see the new client in KeyConfigure, click on the word “Refresh” at the bottom of the Computers window.

A new client computer is displayed in the Computers window after a new client install when KeyVerify is run or the computer is restarted. The default action when new clients are discovered is to assign the Login status of “Full” (brown disk). Full clients have all K2 services available to them. These computers are fully audited for installed software, and flexible licensing policies can be assigned and managed.

You might have some computers for which you prefer not to gather audit data. In these cases, the computer can be assigned the “Basic” login status. Program usage on Basic computers is fully managed by K2’s licensing services, but audit data will not be maintained.

Lastly, “Prohibited” computers are not allowed to make any use of K2 services. These computers do not require a K2 client license, and are not included in K2’s usage or audit reports.

Just like Programs, newly discovered Computers can be automatically categorized according to Filters and Rules that you set up. These rules will usually be specific to your site. For example you might decide to direct computers on a certain subnet into the Basic or Prohibited categories by default, while other computers are given Full login status.

License Types — Floating versus Node Locked

18. Change to Computer Limit (Node Locked License).

In the “License Details for Calculator License”, use the radio buttons to change from “Unlimited (Site License)” to “Computer Limit (Node Locked License)”. Set the “Computer Limit” to 1, save changes, and close the window. Launch Calculator, let it run for 5 seconds, and quit. Now on a second computer with KeyAccess installed, try to launch Calculator - we are assuming for this step that both computers are Windows or both are Macintosh so we are trying to launch the same program on two computers.

You will be told that there is no license available. It does not matter whether Calculator is currently running on the first computer or not. The one available license for Calculator has been locked onto the first computer and it cannot float elsewhere.

19. Remove a node from Calculator’s list of licensed computers.

Right-click on the Calculator License (in the Licenses window), and choose “Show Computers” from the drop down menu. You will see the licensed computer listed in the window, “Computer Node List for Calculator License”. With a computer limit of 1, the second computer cannot be added to this list.

Select the one computer in the Node List and delete it. Now go back to the second computer launch Calculator, let it run for 5 seconds, and then quit. Assuming that the second computer has been refreshed into the Computer’s window (step 17), now use the refresh button at the bottom of the Node List - you will see that the license has now locked onto the second computer. Calculator usage will be denied on other computers, again, regardless of whether it is actually running on the licensed computer.

For any controlled program, KeyServer accumulates a node list of all the distinct computers where the program has been launched. When a controlling license is set to “Computer Limit (Node Locked)”, new computers will “Auto-add” to the list until the specified limit has been reached. Launch attempts on unlisted computers will then be denied as you just saw in step 16.

As an alternative to letting “Auto-add” build the node list you can explicitly drag items into a Node List from the Computers Window. A named list of computer nodes can also be built in the Groups window and then referenced in several License configurations as a common group restriction.

Let’s pause to look at the actual usage events that are being recorded by the KeyServer. The dump of all events is not itself very interesting but it is useful as a diagnostic which can clarify our understanding of KeyServer’s actions.

20. Run the Event Dump Report

From the Reports menu under Miscellaneous, select the Event Dump report and run it on the entire data set. You should be able to trace the history of this demo tour. Now select a computer logon item in the event dump window and right-click to run a sub-report just for the selected computer. You can select other event items and run a separate Event Dump sub-report for each computer, each program, and each license.

In general, a right-click in any window (computer, programs, groups, licenses, etc.), will give a context menu listing all sub-reports that make sense when restricted to the selected item. Notice also that whenever you right click, there is a context sensitive Help item available.

Before returning to our tour of different license types, let’s clean up. Quit all running copies of Calculator on all client computers. Close up all KeyConfigure windows and then click on “Standard View” from the Window menu to re-open the three main windows in standard position.

21. Change to Concurrent Use Limit (Floating License).

Open the “License Details for Calculator License” window again, and use the radio buttons to change to a “Concurrent Use Limit (Floating License)”. Set the User Limit to 1 and save the changes. Launch Calculator and leave it running.

Now on a second computer (with KeyAccess installed), if you try to launch Calculator, a dialog will come up offering to put you in a waiting queue. Calculator is controlled by one floating license and this one license is in use by the first user. When the first user quits, the waiting user will be notified. Try it.

You can examine the list of current users of a license by clicking on the “Current User List” button in the License Details window. For a Concurrent Use (Floating License), the button label will also show the fraction currently in use, e.g., 3/7. When the license type is Computer Limit (Node Locked License) the “Computer List” button shows the fraction of the license total that has been allocated (locked to a node). In either case, a fraction equalling 1 (e.g., 7/7) means there are no more licenses available.

Group Definitions — node list, divisions, network location, authentication

Rather than allow the Concurrent Use license created in the previous step to float among all computers, we will now restrict it to float only among a specified group. The ability to restrict license access to a specific group is one of KeyServer’s more powerful (and hence dangerous) features:

22. Add a Group restriction to a License.

In the “License Details for Calculator License”, type in a new group name, “TryThis”, into the Group field. Now try to launch Calculator. The launch will be denied on all computers that have KeyAccess installed!

Increasing the User Limit or changing the license type won’t help. The problem is that there is no definition of what it means to be a member of the “TryThis” group. The group has no membership criteria and therefore the license is not available anywhere.

It is obvious that a program will be completely disabled when controlled by a license that has the limit set to zero. Achieving the same result by restricting a license with an empty or non-existent group is perhaps surprising!

It is usually safer to define a group first and then drag it onto the group icon in a license details window, rather than type the name of a group directly into a license details window:

23. Define a Group.

Use the Window menu to open the Groups window. Create a new group using a right click to bring up the context menu (or use “Create New” in the Edit menu). Let’s name this new group “Graphics Group”, and hit OK. Now select a computer from the Computers window – drag & drop it onto the newly created group item, “Graphics Group”, in the Groups window. To check that this computer node was successfully added to the group definition, double click to open “Group Details for Graphics Group” and look in the Nodes panel.

24. Drag & Drop onto the Group icon in License Details.

You will see the old group restriction, “TryThis”, replaced by “Graphics Group”. Save the changes. Now you can experiment with Calculator launches on the various clients to demonstrate how the license is enabled only for the computers listed within the Graphics Group.

Rather than add individual computers to a Group, you may want to include a pre-defined set of computers, e.g., the set of all computers owned by the Art department. The Computers window lets you divide the list of computers into named a subsets for just this purpose.

25. Create a Computer Division for inclusion in a Group definition.

In addition to specifying computers for Group inclusion (referenced under its Nodes or Divisions panes), membership can also be granted based on location (e.g., network address ranges configured in the Locations window). If the KeyServer is configured to consult some external authentication server (such as an NT domain server) then group membership can be further augmented by reference to an external group name. In this case, the complete list of externally defined groups may not appear in the Groups window and it is for this reason that a License Details window accepts a typed in group name as well as supporting drag & drop.

After deploying K2 throughout your site, it will be safer to test custom license rules and group restrictions using the KeyVerify license or a license controlling some unimportant game. Since Calculator is a standard OS utility, disabling it by mistake (or on purpose) would be an unwelcome surprise on any client computer.

Key an Application — file modification for Secure Control

In addition to K2’s standard method of managing programs and their respective software licenses, K2 also provides an optional method to secure programs against intentional software piracy. The extra work of preparing and distributing a secured or “keyed” program version is optional and completely unnecessary except when intentional piracy is a concern. The license management interface and usage tracking options available for a standard program and for a secured copy are the same.

KeyVerify is an example of a specially modified, “keyed”, program. Unlike a standard program (e.g., Calculator), it will not run if the KeyAccess client software is absent or not properly setup. To enable a launch, KeyAccess must convey a “key” from the KeyServer to the keyed program. In this sense, the keyed program is controlled “securely” against software piracy. If you have other programs where this kind of security is required, you can transform a copy of the standard executable file into a “keyed version” which you can then distribute freely without risk of piracy.

Bug fix installers and version updates that are freely available from publisher’s web sites make the “security” of keyed programs much less certain than it used to be. An update installer's job is to replace an old executable file version with a newer version. When applied to a keyed program, the updater may behave in one of four ways.
The updater may:

For this part of the demo, we will transform a duplicate copy of Calculator to a keyed version and then compare to the unkeyed Calculator behavior illustrated above. We need to create the duplicate outside of the Windows directory because files inside are protected from modification.

A keyed program file cannot be unkeyed! Before transforming a program file into a keyed version always be sure the program installer is available so you can reconstruct the original or else be sure that you are transforming a duplicate copy and that the original is safely archived.

If you were to drag the calc.exe file into the Licenses window, a “Create License” dialog would pop up giving you the “Control as Keyed Program” option which would transform the calc.exe file. This would transform the calc.exe file into a keyed program while putting it under the control of a newly created license.

Instead of making a new license, we will show how the calc.exe file can be transformed to a keyed version and placed under the control of an existing license:

26. Transform a duplicate copy of calc.exe into a “keyed version”

Navigate to the folder C:\Windows\system32, then select the file calc.exe. Drag the file to the desktop and hold down the ctrl key before releasing so that a copy is made – we need a full duplicate file copy, not a shortcut!

Open the License details window for the existing Calculator License. Make sure the Programs pane is exposed (under the solid blue square icon) and use the expansion triangle to reveal the Program pane content. Now drag the duplicated calc.exe file from the desktop and drop it into the Programs pane in the white space below the item already listed. [Make sure calc.exe is not running, is not locked, and is not read-only! ]

A dialog titled “Control Program under Calculator License” will pop open. Instead of the default, “Control as Unkeyed...”, click on “Control as Keyed...”. When you click OK, the calc.exe file dragged from the desktop will be transformed into a keyed version.

From the Programs window, double click on the word “Controlled” in the left column. This will open a new window listing just the controlled programs so Calculator will be easy to spot. You should see two items for Calculator - click on the word "Refresh" at the bottom of the window if you don't see them. Note that the name change in step 11 pertained only to the unkeyed variant. The new keyed variant is still known to the KeyServer as "Windows Calculator application". You could change it to "Calculator keyed" or just re-use the name "Calculator". The “§” symbol on the right side of the Variant column will distinguish the keyed from the unkeyed variant.

In order to keep the two Calculator variants (keyed and unkeyed) sorted out, we will attach a distinct “On Launch” message to each:

27. Create a Custom Message

Double click on the Calculator variant that has the § symbol in the Variant column to open its “Program Details...” window. The § symbol indicates this is a keyed variant so let’s change the name to “Keyed Calculator”. Then mouse over the icons to the right of the name until you find the “Custom Message” icon. Click to open the Custom Message pane where you can enter the phrase “This keyed program file won’t run without KeyServer.” Save the changes and close the window.

Open up the program details for the other Calculator variant and enter the phrase: “KeyAccess will display this message whenever any unkeyed Calculator version is launched”. Save the changes and close the window.

28. Launch both the keyed and unmodified versions of Calculator

Double click on the desktop copy of Calculator (keyed) and also launch the unmodified version by typing “calc.exe” into the Run... item under the Start menu.

With both the keyed and unmodified programs running, the License window will show just one Calculator license in use because it’s a “suite license” - the two controlled programs running on the same computer count as a single use of the suite. Click Refresh at the bottom of the Programs (Controlled) window and you will see that the un-keyed and keyed program variants are listed separately - program usage (as opposed to license usage) is in fact being tracked separately. Quit both Calculator programs, and then run some reports like Usage (COMP x lic) and Usage (COMP x prog) to test your understanding.

As soon as a new client computer is set up properly with a KeyAccess connection to KeyServer, all of KeyServer’s license control actions will take effect immediately. It doesn’t matter whether a controlled program is launched from storage on a local hard disk or from a remote file server and it doesn’t matter whether the executable file is unmodified or it is keyed.

Controlled applications can be moved from remote to local storage, re-named, re-installed, duplicated, compressed, FTP’ed etc. with no effect on KeyServer control. Whenever a controlled application is launched on a client connected to KeyServer it will be subject to the rules imposed by the KeyServer regardless of where the application is located, what it is called, or how it got there.

The essential difference between an unmodified and a keyed version of a program is revealed when KeyAccess is absent. The unmodified version will simply run while the keyed version will not.

If KeyAccess is present but the connection to KeyServer is broken, then by default any unmodified program will be allowed to run “off-line”. Usage information will be recorded for upload when the client next connects to KeyServer. Any keyed program version, however, cannot run unless there is a “checked out” key available on the local computer, or a network connection to a “shadow” KeyServer can be established in lieu of the lost connection to KeyServer.

When a notebook computer is disconnected from the network, keyed applications won’t run (unless a portable key has been checked out). Unkeyed applications won’t be strictly controlled (unless “Allow launch when KeyServer not available” has been turned off). KeyServer gives you the options to customize a balance between strict enforcement and transparent software access for computers that are used both online and off-line.

Unlike our Calculator example, you will typically be interested in controlling applications that are not pre-installed with the operating system. Having decided to Control an application (as opposed to ignoring or logging usage) you must decide whether to install and control it as a keyed program, or as an unkeyed program, or both (perhaps using a “suite license” as in our Calculator demo above).

For both keyed and unkeyed program control, KeyConfigure is used only once to create the controlling license in KeyServer’s Licenses window. Thereafter, it’s just a matter of deploying the application program (keyed or unkeyed) onto other client computers. The extra step required for keyed control – replacing the unkeyed application version with a keyed version – can be automated in several ways. KeyConfigure’s “Deputize” feature will modify the application installer so that it automatically creates a keyed application version at install time. You can also use a software distribution tool to replace unkeyed executable files with their keyed variants. See the complete documentation for Deputy details and for comments on other deployment strategies for keyed software, but remember, in most circumstances management of just the unmodified executables is sufficient.

Software Audits — scheduled, centralized, data collection

Since new computers are discovered as "Full" clients by default, they will be audited for installed programs when first connecting to the KeyServer. The frequency of incremental audit updates for newly installed or deleted programs can be configured from the “General Settings” item in the Admin menu – auditing can also be turned off completely by changing the client computer Login type to Basic.

At some sites, the automatic initial audit for new KeyServer clients may be the wrong default, perhaps for privacy reasons. To change the default discovery rule, select the word "Discovered" in the Display column of the Computers window (Filters pane). Right click and select "Edit Filter..." – there you can choose either Full, Basic, or Prohibited as Login type for newly discovered computers.

Only computers logging in as Full clients will be audited for installed programs but program usage activity will be tracked on both Basic and Full clients (for programs configured as Controlled or Logged in the Programs window).

By this point in the tour, audit data has probably had enough time to trickle up. Click “Refresh” at the bottom of the Computers window and then look in the “Last Audit” column – if there is a time stamp then an audit has completed and we can have a look.

29. Show the program Installs data for a selected computer

Select a computer that has completed an audit and double click to open the Computer Details window. Note in the Audit pane that basic hardware characteristics have been filled in (disk space, CPU speed, etc). If the audit pane is not in view, click on the little audit icon at the top right of the Computer Details window to toggle the display. Click on the “Show” button in the audit pane to bring up the program Installs window for this computer.

The bottom of the Installs window shows the total number of distinct program variants/versions/files that have been found on the selected computer and are displayed in the window. You can click on the totals at the bottom of the window to toggle the contents to include/exclude the so called “ignored programs” (gray diamond icon) - these “ignored programs” are always excluded from all Report windows (generated from the Reports menu), and the default view for the Programs window also hides them.

The line items (marked with an expansion triangle) in the Installs window are program “variants” which aggregate distinct versions together based on the program family plus zero or more digits of version information. It is actually these same program variant items that appear in the Programs window, but without the expansion triangles.

If an expansion triangle is darkened for an Installs window line item, it means that the audit of this computer has found more than one version within the program variant – click to expand and see the versions. The column labeled “Copies” gives the total number of file copies that were found by the audit for each specific version and each variant.

30. Show the Audit data for a selected program

With one of the program items selected in an audit window, use the right-click “Show Installs” menu item to bring up a list of all computers where this program has been found. A click on the “Last Used” column header will sort the time stamps so you can quickly get a sense of which programs are actually used. Note: the context menu item “Show Installs” is also available directly from a selected item in the Programs window and from the Computers window.

In order to keep audit information current, K2 is set by default to tell each client to do a new audit every 4 weeks. If you want to shorten or lengthen (or remove) the audit interval, use General Settings from the Admin menu. You can also manually request an audit of any computer at any time. If that computer is currently connected, it will audit ASAP. If not, it will audit at next client connection.

While “Show Installs” lets you examine detailed audit data directly, for a summarization of software installation and usage patterns you should use the various audit and usage reports from the Reports menu. An appropriate subset of these same reports is available from the context menu (right-click) when a line is selected in any window (including report windows themselves). Remember, of course, that KeyServer has no information about usage prior to the installation of its client software.

By default, each single line in the Programs window represents an entire program family that is aggregated together into a single variant. You make decisions on how to control, log, audit, or ignore on a variant as a whole, while treating all versions included in the variant in the same way. Occasionally it may be important to split a program family into multiple distinct variants, based on the first few digits of version information. For example, your license for version “3.x” of a program may be different from version “4.x” so you will need to manage these separately. Consult context help (right-click) from any Program details window for instructions on how to split a program family based on one or more digits of version information.

Computer Divisions, Program Folders — discover / acknowledge / filter / hide

A large site might have tens of thousands of items listed in the Computers window and it is easy for the list of discovered programs to grow this large even at a small site. When either the Computers list or Programs list becomes large, custom defined Filters will become crucial in letting you find and select just the items of interest.

Two filters are already created by default: Win Programs and Mac Programs. You can easily display or hide Mac or Windows programs just by clicking in front of the filter name in the Filters pane. To open a separate window containing just the matching items, double click on the name of a filter.

Use right click and the Edit Filter... menu item to see how these filters are defined. They use both a platform (Win or Mac) and a path condition (Program Files or Applications folder). Now let’s create a new custom filter:

31. Custom filter to select Setup programs.

With the cursor in the Programs window, right-click in white space within the Filters pane to bring up the context menu. Select “New Filter...” and check the “Identifier” box - type in the string “setup”. Save the filter with the name “Installers” and then with this filter check-marked, take a look at what has been selected.

Let’s generalize this filter to catch more cases: right click and use the Edit Filter... menu item. Near the bottom of the filter definition window click the “Match This Filter” button. You will see the text: “("setup"~=Stamp)”. Let’s add some more clauses - copy/paste to replace with the text below:
    ("setup"~=Variant)||("install"~=Variant)||("SETUP"~=Stamp)||(Stamp="VIS3APPL")||(Stamp="_ISDEL")

and then save and test. Typically the additional clauses (using the “or” connective, || ) will select several more installer items. [See the Filters documentation for a complete explanation of the custom syntax.]

Checks in front of various items in the Display column (left) control which items are actually displayed in the list column (right). An additional check mark within a pane (Actions pane, Folder pane, Filter pane) will potentially increase the number of items displayed (“or”). But selected conditions from different panes must all be satisfied simultaneously - potentially reducing the number of items displayed (“and”). The double-check-mark at the top of the Programs window between Display and program list columns is used to toggle between the default display, all except ignored, and your last custom selectors.

One way to reduce clutter in the Programs window is to hide executable System files inside a custom folder. We may also want to set a default action to exclude these files from audits:

32. Select Win system files.

Make a “New Filter...” in the Programs window as in the previous step. Check the box, “Platform is Windows”, and also check “Path contains” with the search string “:\WINDOWS\” (not including the quotes). Save the filter with the name “Win Sys Files”.

When a new filter is created, it receives a check-mark by default so the current display is immediately restricted by the filter. You may have noticed in the filter creation dialog, you could optionally enable a Rule for the filter. The Discovered rule and other filters with rules categorize programs automatically. The filters pane displays rules at the top where they can be arranged in order from top to bottom. Filters without a rule appear below a horizontal dividing line. You can control the selection of displayed items with at most two filters check-marked - one filter above the dividing line and one below. The Action and Folders panels can have as many check-marks as you like.

33. Create a Program Folder for selected programs.

Right-click in the Folders pane and select the New Folder... menu item. Use the new folder dialog to create a folder named “Special”. Check mark the “Set Action to:” item and use the pull down menu to select “ignored” as the drop action.

Use the double-check-mark between the Display and computer list columns to toggle to the default view (display all except ignored). Then un-check the controlled action item (to remove blue dot items) and check-mark your “XP Sys Files” filter, reducing the display further to just system files.

Use "Select All" from the Edit menu to select all of the displayed items and drag them into your Special folder. All of the selected items will now be tagged with the folder name, “Special” and their action will be set to ignored. You may want to make another filter, “NT Sys Files”, to select NT programs (path contains “:\WINNT\”), and drag these to the “Special” folder.

More important than the convenience of the “Set Action to:” behavior illustrated above, is the fact that you, the administrator, explicitly dragged program items into the folder named Special. The program rules (filters with a rule action assigned) did not place the programs into Special, you did, and presumably you don't want rules to ever change this. The fact that these “exceptional” dragged program items are no longer governed by the program rules is indicated in the Folder column - the pink “rule icon” is no longer displayed for these items. We say that these non-pink item have been acknowledged.

Even if you make a new rule or change the definition of the default Win Programs or Mac Programs rules, items in the folder named Special will not change. Note: whenever a new rule is added or existing rule is edited, the word rule turns red - click on the red word to refresh. The changed rules will be applied to all “pink” programs - e.g. all programs except those in the Special folder which have been exempted from being ruled (no pink icon). To change an exceptional program item back a "ruled" program (pink icon), drag it onto the Filter - rule bar. It may still belong to the Special folder, but now with a pink icon there are no guarantees that it will stay because some new rule may move it elsewhere and/or change its action.

A very few rules (e.g filters with a rule) should suffice to assign most programs an appropriate action and optionally an appropriate Folder. Only a small number of programs need to be explicitly configured - most items can remain with their pink “ruled” icon.

Creating several additional filters will let you easily focus on items of interest, especially when used along with Action and Folder check marks. Since a filter (with or without a rule) can itself be used to restrict the scope of reports (select at filter and right-click), there is often no need to create an extensive set of program Folders.

The Computers window, like the Programs window, supports the same discover, acknowledge, display, filter, and customize behaviors. Again, right click is used to create your own custom categories (in addition to discovered) but for computers these are called computer “Divisions” to distinguish them from program “Folders”. It may be useful to create rules that organize computers into divisions according to their ip address. But consider just creating filters for various ip ranges - the filters alone may suffice as a way of restricting the scope of reports. Again, you select a filter and right-click to pick report that will use the filter as a restriction.

You have already seen how a custom Division was created and used to restrict a License (step 25). But even when all licenses are global (unrestricted by Group conditions), a partition of the computer list into meaningful Divisions can be very useful for organizational and reporting purposes. With one of your custom defined Divisions selected in the Computers Window, right click to see the context menu of all computer reports. Selecting a report from this context menu instead of from the main reports window will restrict the scope of the report to just the selected division. Note: any time range restriction that you have previously configured while running reports from the Reports menu will remain in effect.

Web Reports — scheduling reports, browser-based reports

The dedicated web report server, KeyReporter, is an optional component included in the K2 toolkit that can run reports automatically on schedules and provide web browser access. KeyConfigure can run and display all of the same reports in its own windows so installation of KeyReporter is not essential. When the usage and audit databases become large, however, some reports may take a considerable time to complete. Then it will be convenient to configure KeyReporter to run these same reports on an overnight schedule - perhaps automated to produce weekly or monthly summaries.

34. Install and start KeyReporter.

In the K2 image folder, open the “Reporter Installers” sub-folder and run the appropriate installer for KeyReporter (“K2Reporter.exe” for Windows or “K2Reporter.app” for Mac). It will create a folder named “Sassafras K2” in the Program Files directory with a shortcut installed in the Start menu. KeyReporter (kr.exe) and its “KeyReporter Data Folder” will be installed in the sub-folder named “Reporter”. On Windows, use the Services control panel to start the KeyReporter process if necessary. On Mac, use the kr-StartStop applescript applet.

By default, KeyReporter provides service on the official HTTP port 80. If the computer on which you are installing KeyReporter already has a web server using port 80, you will have to configure KeyReporter to use a different port. For more detailed installation instructions, please read the KeyReporter documentation.

For simplicity in this Tour, we assume that KeyReporter is installed on the computer that is also running the KeyServer process. While KeyReporter can be run separately from KeyServer, at most sites it is most efficient to run these two servers on the same host.

35. Connect to KeyReporter with any Web browser.

In the URL field of your preferred browser, enter “http://” followed by the address of the computer on which KeyReporter is installed. You will be presented with the Login page. For the Account, use “Administrator”, and type the same Administrator password as you used for KeyConfigure, by default “Sassafras”.

If you changed the Administrator password in KeyConfigure, use that password here as well, but make sure your custom password does not include any of the four characters % / : @ which cannot be entered in the browser login form.

Initially, the default “K2 Web Reports” page is not that interesting, since no reports have been created. You can create new reports on the “Builder” page, and these reports will be listed on the “Archive” page. The same set of reports available in KeyConfigure is also available from these web pages. Note: any completed reports that are stored in KeyReporter's archive can be displayed directly in a KeyConfigure window (from its Window menu. KeyReporter item) as well as in a browser. When displayed by KeyConfigure, these remotely stored reports become fully interactive the the admin interface supporting double-click, drag, etc.

Read the KeyReporter documentation for more information on how to use KeyReporter, including how to schedule reports to be created on a periodic basis, and how to allow your general user base to view selected reports.

Clean-up — removing the K2 demo files

Having completed the demonstration of basic K2 features, you will probably want to install your production KeyServer on a different host computer. Whenever you are ready, you can use the steps below to clean-up.

36. Remove keyed Calculator.

You probably won’t actually want to manage a keyed copy of Calculator (created in step 25), so you can move the keyed calc.exe file from the desktop into the Recycle Bin.

If you have transformed any programs into “keyed” versions, these will become useless when you trash the KeyServer Data Folder (inside the Sassafras K2 Server folder). This is the reason that the cleanup begins by removing keyed Calculator.

The KeyServer executable file and all its database files are contained in the folder named “Server” inside the folder “Sassafras K2”.

37. Uninstall the KeyServer.

Stop the KeyServer service using the Services Control Panel. From the DOS command prompt, cd into the directory “Sassafras K2\Server” and run the command “ks.exe -remove”. This will remove the KeyServer entry from the list of services. Now you can move the “Sassafras K2\Server” folder to the Recycle Bin.

The “Sassafras K2/Server” folder is actually an alias to the folder “/Library/KeyServer”. Use the ks-StartSop applet (or Activity Monitor) to quit the process named ks and then remove /Library/KeyServer.

The KeyReporter executable file and all its data files are contained in the folder named “Reporter” inside the folder “Sassafras K2”.

38. Uninstall the KeyReporter.

Stop the KeyReporter service using the Services Control Panel. From the DOS command prompt, cd into the directory “Sassafras K2\Reporter” and run the command “kr.exe -W remove”. This will remove the KeyReporter entry from the list of services. Now you can move the “Sassafras K2\Reporter” folder to the Recycle Bin.

The “Sassafras K2/Reporter” folder is actually an alias to the folder “/Library/KeyReporter”. Use the kr-StartSop applet (or Activity Monitor) to quit the process named kr and then remove /Library/KeyReporter.

You may want to keep the admin program, KeyConfigure, in place on your demo computer for use in managing your production KeyServer. It is also easy enough to remove:

39. Remove KeyConfigure.

The KeyConfigure admin program and all its support files are contained in the folder named “Admin” inside the folder “Sassafras K2”. Just drag this to the Recycle Bin. On Windows, you can also clean up the registry entry for the ksODBC driver (if you installed this extra option) by using the Add/Remove programs Control Panel. Use the ODBC Administrator utility on Macintosh.

You may want to keep the client program, KeyAccess, in place on your demo computer, but be sure to use KeyAccess Setup (see step 6) to re-configure the server address when your production KeyServer is in place. To remove the client software:

40. Remove the K2 client software, KeyAccess.

On Windows, use the Add/Remove Control panel to remove the “Sassafras K2 Client”. On Mac OS X, move the folder “/Library/KeyAccess/” to the trash. On Mac OS 9, remove the KeyAccess chooser extension from the System Folder.

This concludes the basic tour of K2. For further information on specific topics, be sure to consult the context sensitive help system which is always available from any KeyConfigure window or dialog via right click.

Installation

K2 – Getting Started