Chapter 13 Monitoring Software Usage

The following is a list of the overview information in this chapter.

• "What Is Software Usage Monitoring"

• "What Can Software Usage Monitoring Do"

• "How Can Software Usage Monitoring Be Used"

• "How Software Usage Monitoring Works"

• "Before Using Software Usage Monitoring"

• "Generating Software Usage Report Entries"

• "Transferring Software Usage Entries on a Client to the Master Log File on the Software Usage Monitoring Server"

• "Printing Software Usage Data from the Master Log File"

• "Removing the Master Log File"

The following is a list of the step-by-step instructions in this chapter.

• "How to Verify Software Usage Monitoring Has Been Installed on a Software Usage Monitoring Server"

• "How to Verify That Software Usage Monitoring Is Installed and Enabled on a Client"

• "How to Verify that Software Usage Monitoring is Enabled on a Host in a Shared File System Environment"

• "How to Stop the swu_svr Daemon"

• "How to Start the swu_svr Daemon"

• "How to Monitor Software Usage Using a Command-Line Interface"

• "How to Monitor Software Usage Using a Shell Script Wrapper"

• "How to Add Software Usage Monitoring to a Shell Script Program Executable Command Line"

• "How to Embed Software Usage Monitoring into Applications"

• "How to Transfer Software Usage Entries on the Client to the Master Log File on the Software Usage Monitoring Server"

• "How to Print Software Usage Data from the Master Log File"

• "How to Remove the Master Log File"

What Is Software Usage Monitoring

Software usage monitoring is a compilation of software programs that enable you to monitor software usage in your computer system. The software usage monitoring system tracks the software usage and installations across network servers and workstations, to simplify system administration and purchasing decisions. For example, after using software usage monitoring, you may find that some software is never used while other software may be used repeatedly and needs additional licenses. In addition, you may find that a piece of software is installed on a workstation and is never used; this software could be used by another user who needs it.

The software usage monitoring system is not intended to be a licensing manager, nor does it track all software usage on your computer system. The software usage monitoring system functions as a push system rather than a pull system. That is, the software monitoring system cannot randomly obtain usage information from your computer system. Software running on your computer system must push usage information to the software usage monitoring server.

What Can Software Usage Monitoring Do

Software usage monitoring can do three basic tasks:

• It generates software usage information (report entries).

• It transfers report entries from the client (local queue) to the software usage monitoring server.

• It formats and prints software report entries.

Software usage monitoring accomplishes these tasks using commands which are listed and described in Table 13-1.

Refer to the man pages for detailed descriptions of the commands.

How Can Software Usage Monitoring Be Used

To generate software usage entries, you must run the swu_rpt command or function with your software applications. You can accomplish this by using any of the following:

• You can use the swu_rpt command from the command line. The command line method enables you to start an application program and create a software usage entry. For example, if you want to start the FrameMaker program and create a software usage entry, you can do this at a command line.

• You can use the swu_rpt command in a shell script. The shell script method enables you to add the swu_rpt command into an existing shell script. For example, you may have a shell script called "frame" used to start the FrameMaker program. You can create a shell script wrapper by editing the frame script. Within this script, you can add the swu_rpt command before and after the script's program executable. Thus, you wrap the program executable with swu_rpt commands. This creates a Begin and End software usage entry each time the script is run. In addition to the shell script wrapper method, you can modify the shell script executable command line to include the swu_rpt command using the -c option, which will create a Begin and an End entry each time the script is run.

  ---

  Note -

  The end record may not be accurate if the command returns after spawning a new process (for example, in the background).

  ---

• You can embed calls to the swu_rpt() function in an application. The embedded application method enables you to add a call to the software usage library into your application source code. For example, if you or someone else on your computer network has created an application, you can call the software usage library from this application. This causes software usage entries to be created each time the application is run.

  ---

  Note -

  To use the embedded application method, you must have access to the application's source code.

  ---

  How to implement these methods is described in detail in "Generating Software Usage Report Entries".

How Software Usage Monitoring Works

The software usage monitoring system can be used in a client/server environment or in a shared file system environment. Software usage monitoring operates differently, depending upon which environment it is run. The following sections describe how software usage monitoring operates in each environment.

Software Usage Monitoring in a Client/Server Environment

Figure 13-1 shows an illustration of the software usage monitoring sequence of events when used in a client/server environment.

Figure 13-1 Software Usage Monitoring Sequence Of Events (Client/Server)

The client may also act as a software usage server in that it may have the swu_svr daemon, master log file, and swu_print command installed on the client.

The following list describes the sequence of events.

1. The swu_rpt command or function is initiated on the software usage monitoring server or client from a command line, shell script, or within an application.

2. The swu_rpt command or function then creates a software usage report entry in the local queue for the associated program. (The type of entry depends upon the options used with the swu_rpt command or function.)

   ---

   Note -

   If the local queue has been disabled, no report entries will be logged.

   ---

3. A cron job (run from root's crontab) using the swu_queue command runs on the client or server that transfers (flushes) information in the local queue to the swu_svr daemon that is running on the software usage monitoring server.

   ---

   Note -

   Files can be transferred manually by a root user from the local queue to the swu_svr daemon using the swu_queue command using the -F option.

   ---

4. The swu_svr daemon accepts incoming report entries from the swu_queue command and saves it to the master log file (/var/opt/SUNWswusg/swusage.log) or the log file name specified when the swu_svr daemon was started by root on the software usage monitoring server.

   ---

   Note -

   If the swu_svr daemon is not running on the software usage monitoring server specified in the entry, that entry in the local queue is removed from the queue.

   ---

5. The swu_print command takes information in the master log file (/var/opt/SUNWswusg/swusage.log) or the specified log file name and copies all, part, or a summary of the information to another file where the information can be searched using awk or other search tool. By default, this command sends it to the standard output device if no file is specified.

   ---

   Note -

   This sequence of events shows the order in which commands are run; however, you should note that the swu_rpt command or function could be run numerous times before the swu_queue command transfers software usage report entries from the local queue.

   ---

Software Usage Monitoring in a Shared File System Environment

Software usage monitoring operates in a similar manner in a shared file system environment as it does in a client/server environment. By installing software usage monitoring on a dedicated software usage monitoring server, you can share the binary files with other hosts in your network.

Figure 13-2 shows an illustration of the software usage monitoring sequence of events when used in a shared file system environment.

Figure 13-2 Software Usage Monitoring Sequence of Events (Shared File System)

The following list describes the sequence of events.

1. The swu_rpt command or function is initiated on a host from a command line, shell script, or within an application.

2. The swu_svr daemon receives the information generated from the swu_rpt command or function and saves it to the master log file (/var/opt/SUNWswusg/swusage.log) or the file name specified when the swu_svr daemon was started by root.

   ---

   Note -

   If the swu_svr daemon is not running on the host server, the entry is lost.

   ---

3. The swu_print command takes information in the master log file (/var/opt/SUNWswusg/swusage.log) or the specified file name and copies all, part, or a summary of the information to another file where the information can be searched using awk or other search tool. By default, this command sends it to the standard output device if no file is specified.

Before Using Software Usage Monitoring

Before you use software usage monitoring, you need to complete a number of steps. Usually, these steps only need to be done once; however, it may be necessary to repeat some of them.

The steps required to set up software usage monitoring depend upon the environment in which you intend to run software usage monitoring. The following procedures describe how to set up software usage monitoring on a server and/or a client if you so choose.

How to Verify Software Usage Monitoring Has Been Installed on a Software Usage Monitoring Server

1. Verify that software usage monitoring server side code has been installed on the host server.

   $ cd /opt/SUNWswusg/bin $ ls swu_print swu_svr

   If software usage monitoring has not been installed, refer to the Solstice AdminSuite 2.3 Installation and Product Notes for information about installing software usage monitoring.

2. Verify that the swu_svr daemon is running on the host server.

   $ ps -ef | /usr/bin/grep swu_svr root 264 1 0 Jan 04 console 2:43 /opt/SUNWswusg/bin/swu_svr jod 752 311 1 14:50:16 pts/3 0:00 grep swu_svr $

   If the swu_svr daemon is not running, start the swu_svr daemon. Refer to the "Starting and Stopping the swu_svr Daemon" that describes how to start and stop the swu_svr daemon.

   ---

   Note -

   If you wish to generate software usage monitoring information on a host, the software usage monitoring client binary packages should be installed on that host or should be made available to that host through NFS.

   ---

How to Verify That Software Usage Monitoring Is Installed and Enabled on a Client

1. Verify that software usage monitoring client code has been installed on the host server.

   $ cd /opt/SUNWswusg/bin $ ls swu_queue swu_rpt

   If software usage monitoring has not been installed, refer to the Solstice AdminSuite 2.2 Installation and Product Notes for information about installing software usage monitoring.

2. Verify that the swu_queue is enabled.

   $ cd /var/opt/SUNWswusg/swusage $ ls $

   If queue_disabled appears after the ls command, login as root and enable the queue as shown below.

   $ ls queue_disabled # /opt/SUNWswusg/bin/swu_queue -e # ls #

How to Verify that Software Usage Monitoring is Enabled on a Host in a Shared File System Environment

1. Verify that a software usage monitoring server has been added to the name service.

   $ rpcinfo -t host 120100 program 120100 version 1 ready and waiting

2. Verify that the swu_rpt command is executable (through a shared file system or copied locally) by any shell scripts that use it.

   ---

   Note -

   Refer to the Solstice AdminSuite 2.3 Installation and Product Notes document for information about how to set up your swusage_host server.

   ---

Starting and Stopping the swu_svr Daemon

When software usage monitoring is installed, the swu_svr daemon is started on the software usage monitoring server. At times, you may want to stop or restart the swu_svr daemon. The following procedures describe how to start and stop this daemon.

How to Start the swu_svr Daemon

1. Log into the software usage monitoring host server as root.

2. Start the swu_svr daemon.

   # /etc/init.d/swusage start

3. Log out.

How to Stop the swu_svr Daemon

1. Log into the software usage monitoring host server as root.

2. Stop the swu_svr daemon.

   # /etc/init.d/swusage stop

3. Log out.

Generating Software Usage Report Entries

Software usage monitoring report entries can be generated using the following methods:

• A command line interface

• Shell scripts

• An embedded application

  Each method uses the same basic software usage components; however, the methods access the components differently. The following sections describe each method and the procedures used to implement each method.

Using a Command-Line Interface

The command-line interface method is probably the simplest method of implementing software usage monitoring; however, it can also be the most taxing method as it requires you to manually type in each command each time you run software usage monitoring with an application.

How to Monitor Software Usage Using a Command-Line Interface

At the shell prompt, generate a usage report using one of the following swu_rpt command lines.

To create a software usage report entry specifying that the associated program has been installed, use the -i option.

$ swu_rpt -p product-name [-I identifier] [-s server] [-a attr1=val1, attr2=val2,...] \
-i

To create a software usage report entry specifying that the associated program has started, use the -b option.

$ swu_rpt -p product-name [-I identifier] [-s server] [-a attr1=val1, attr2=val2,...]\
 -b

To create a software usage report entry specifying that the associated program has ended, use the -e option.

$ swu_rpt -p product-name [-I identifier] [-s server] [-a attr1=val1, attr2=val2,...] -e

To create software usage report entries specifying a begin and an end entry for the associated program, use the -c option.

$ swu_rpt -p product-name [-I identifier] [-s server] [-a attr1=val1, attr2=val2,...]\ 
-c command

In these commands,

Example of Monitoring Software Usage Using a Command-Line Interface

The following example shows the software usage monitoring command as used from a command line, which starts the FrameMaker program using the command maker, and logs the application using the software usage monitoring swu_rpt command.

$ swu_rpt -p FrameMaker -I 29581 -s sherlock -c maker

In this example, two software usage report entries are created because the -c option was used (the -c option creates a begin and an end entry). The entries look like the following.

Using Shell Scripts

Another method of monitoring software usage is to create a shell script that initiates a program. This method enables you to create a log entry each time a user executes the shell script. A shell script can be modified using one of two methods: you can create a shell script wrapper, or you can modify the script of an existing shell script program. Either method creates a begin and end software usage monitoring log entry.

• Using the shell script wrapper method, you would enter a software usage monitoring command line before and after the program executable command line. For example, you may have a script called "maker" that starts the FrameMaker^TM program. Within this "maker" script, you could add software usage monitoring commands that would "wrap" around the executable portion of the script. By doing this, the software usage monitoring commands are executed when the script is initiated and also when the script ends.

  ---

  Note -

  Using the shell script wrapper method may not be the best option if your command runs in the background. An end record is generated immediately after the command is executed and the time used is not accurate.

  ---

• Using the method of modifying the shell script executable command line, a single command line in the script starts the specified program, and also creates a begin and end software usage monitoring log entry.

  The following procedures describe how to implement each software usage monitoring shell script method.

How to Monitor Software Usage Using a Shell Script Wrapper

1. Using the editor of your choice, open the shell script to which you wish to add the software usage monitoring commands.

2. Before the program executable command line in the script, add the following swu_rpt command line.

   swu_rpt -p product name [-I identifier] [-s server] [-a attr1=val1, attr2=val2,...] -b

   In this command,

   -p product-name	Indicates the name of the product that software usage is being recorded for; this option must always be included.
   -I identifier	Specifies a unique, alpha numeric identifier for usage records; swu_rpt will provide its own identifier if one is not specified.
   -s server	Specifies the server to which the usage records are to be sent. The default is the host aliased to swusage_host.
   -a attr1=val1, attr2=val2,...	Allows the user to give the software usage entry unique or more descriptive information.
   -b	Indicates that a begin entry should be recorded.

3. After the program executable in the script, add the following swu_rpt command.

   swu_rpt -p product-name [-I identifier] [-s server] [-a attr1=val1, attr2=val2,...] -e

   In this command,

   -p product-name	Indicates the name of the product that software usage is being recorded for; this option must always be included.
   -I identifier	Specifies a unique, numerical identifier for usage records; swu_rpt will provide its own identifier if one is not specified.
   -s server	Specifies the server to which the usage records are to be sent. The default is the host aliased to swusage_host.
   -a attr1=val1, attr2=val2,...	Allows the user to give the software usage entry unique or more descriptive information.
   -e	Indicates that an end entry should be recorded.

4. Exit the script, saving your changes. Verify that the script is executable.

Example of Monitoring Software Usage Using a Shell Script Wrapper

The following example shows the software usage monitoring commands added to a shell script called dir_script that lists the directory in which it was called, the files in the directory, and the current date and time.

swu_rpt -p dir_script -I 295833 -s sherlock -a \
"Command1=pwd,Command2=ls,Options=-la,Command3=date" -b
pwd
ls -la
date
swu_rpt -p dir_script -I 295833 -s sherlock -a \
"Command1=pwd,Command2=ls,Command3=date" -e 

In this example, two software usage report entries are created and look like the following.

How to Add Software Usage Monitoring to a Shell Script Program Executable Command Line

1. Using the editor of your choice, open the shell script to which you wish to add the software usage monitoring commands.

2. Locate the command line in the script that calls the program.

3. Add the following arguments to the program executable command line.

   swu_rpt -p product-name [-I identifier] [-s server] [-a attr1=val1, attr2=val2,...] -ccommand

   In this command,

   -p product-name	Indicates the name of the product that software usage is being recorded for; this option must always be included.
   -I identifier	Specifies a unique, numerical identifier for usage records; swu_rpt will provide its own identifier if one is not specified.
   -s server	Specifies the server to which the usage records are to be sent. The default is the host aliased to swusage_host.
   -a attr1=val1, attr2=val2,...	Allows the user to give the software usage entry unique or more descriptive information.
   -c command	Specifies the program executable command.

4. Exit the script, saving your changes. Verify that it is executable.

Example of Adding Software Usage Monitoring to a Shell Script Program Executable Command Line

The following example shows the software usage monitoring command added to a program executable command line that executes FrameMaker.

swu_rpt -p Frame -I 295836 -s sherlock -a "Command=maker,Version=4.0" -c maker

In this example, the software usage report entry looks like this:

Using an Embedded Application

Software usage monitoring can be implemented by embedding calls to the swu_rpt() function into an application. This method works well for monitoring applications that you or others on your computer network have created.

For example, you may have created an online timecard to keep track of time spent on projects; however, you are not sure that it is being used by everyone. Within the online timecard application, you can embed calls to the swu_rpt() function, which then generates usage reports every time the application is executed.

The following procedure provides information about how to embed the software usage monitoring report function within an application.

How to Embed Software Usage Monitoring into Applications

1. Open the application source code file that will contain the software usage monitoring commands.

2. Add the following header file to the application source code.

   #include <swusage.h>

3. Add a swu_rpt() function specifying the begin of the application.

   swu_rpt ("Server_name", "Identifier", SWU_BEGIN, "Product name", avl)

4. Add a swu_rpt() function specifying the end of the application.

   swu_rpt ("Server_name", "Identifier", SWU_END, "Product name", avl)

5. Compile the application source code with one of the following arguments.

   For static linking of the libraries:

   $ ... -I/opt/SUNWswusg/include -L/opt/SUNWswusg/lib -Bstatic -lswusage -lnsl ...

   For dynamic linking of the libraries:

   $ ... -I/opt/SUNWswusg/include -R/opt/SUNWswusg/lib -L/opt/SUNWswusg/lib -lswusage -lnsl ...

Example of Embedding Software Usage Monitoring into Applications

The following example shows an application that includes the software usage monitoring function.

#include <stdio.h>	/* definition of NULL */
#include <swusage.h>	/* swu_rpt() prototype, swusage_alist definition */
#define 	ATTRIBUTE_COUNT 3
 
main()
{
	struct swusage_alist avl[ATTRIBUTE_COUNT];
 
	/*
	 * Define some product specific attribute-value pairs that will
	 * be included in the software usage report records.
	 */
	avl[0].u_attr = "ATTR_1";
	avl[0].u_value = "val_1";
	avl[1].u_attr = "ATTR_2";
	avl[1].u_value = "val_2";
 
	/*
	 * Terminate the attribute list
	 */
	avl[2].u_attr = NULL;
	avl[2].u_value = NULL;
 
	/*
	 * Create a begin record for the application
	 */
	swu_rpt("Server_name", "Identifier", SWU_BEGIN, "My product name", avl);
 
	/*
	 * The application code would go here.
	 */
 
	/*
	 * Create an end record for the application
	 */
	swu_rpt("Server_name", "Identifier",SWU_END, "My product name", avl);
}

In this example, the software usage report entry looks like this:

Transferring Software Usage Entries on a Client to the Master Log File on the Software Usage Monitoring Server

If software usage monitoring is installed on a client and software usage entries have been recorded on the client, you need to transfer the software usage report entries in the client's local queue to the master log file on the software usage monitoring server. Figure 13-3 provides an illustration of where the data is located.

Figure 13-3 Software Usage Monitoring Files and Locations

The software usage report entries in the local queue are located in the /var/opt/SUNWswusg/swusage directory. The report entries are designated by an alphanumeric string. For example, if you entered the ls command in the local queue, you would see something like the following:

$ cd /var/opt/SUNWswusg/swusage
$ ls
swrepAAAa000Tv  swrepAAAa000UL  swrepBAAa000Tv  swrepBAAa000UL

The software usage report entries are moved from this directory using the swu_queue command.

When the software usage monitoring system was installed, a cron job was added to the host's root crontab. This cron job runs the swu_queue command at a random time between midnight and 7 a.m. This swu_queue command transfers (flushes) the usage reports from the local queue to the master log file (/var/opt/SUNWswusg/swusage.log) on the software usage server specified in the usage entry.

Although this job runs automatically, there may be times when you wish to transfer the data in the local queue to the software usage monitoring server at a time other than when the cron job transfers the data. To do so, see "How to Transfer Software Usage Entries on the Client to the Master Log File on the Software Usage Monitoring Server".

When the swu_queue command is executed and the files are successfully transferred from the local queue to the master log file, the files are removed from the local queue; if the files do not get transferred (for example, the host specified in the entry was not running), the files in the local queue are not removed, which may cause your file system to fill. To prevent this from happening, you can disable the queue using the swu_queue -dcommand, which prevents usage records from being logged.

The following list explains what may happen when transferring software usage entries on the client to the master log file.

• If the swu_svr daemon is running on the host specified in the software usage entry, files will be transferred from the local queue to the master log file.

• If swu_queue can not connect to the software usage server daemon because the host in the record doesn't exist, the record is removed from the local queue.

• If swu_queue can communicate to the software usage server host, but there is no daemon running, then the record is removed.

• If the software usage server host specified in the usage record is not running or if there is an RPC failure, the usage record remains queued for later delivery.

• If the usage record doesn't contain a software usage server host, then the record is removed from the local queue.

How to Transfer Software Usage Entries on the Client to the Master Log File on the Software Usage Monitoring Server

1. Log in to the client that has software usage report entries.

2. Become root.

3. Enter the swu_queue command.

   # swu_queue -F

   In this command,

   -F	Transfers data in the local queue to the swu_svr daemon on the usage monitoring server.

Printing Software Usage Data from the Master Log File

After the software usage data has been moved from the local queue to the master log file on the host server, you may want to print the information in the master log file to another file, stdout (screen), or printer.

The software usage record entries are not formatted in the master log file. The swu_print command moves and formats the software usage report entries in the master log file to another file or the standard output device. Three options can be used with the swu_print command to format the entries differently.

The options available with the swu_print command are listed in Table 13-2, along with an example of how the software usage report entries are formatted with the associated option.

Formatting these entries enables you to use awk or another search tool to search on keywords; formatting also enables you to easily translate the entries into another database or report.

swu_print does not delete the software usage report entries from the master log file. In order to get rid of these entries, you must delete the master log file. Otherwise, entries are appended to the software usage report entries that you already copied out using the swu_print command. This could result in your file system becoming full; see "How to Remove the Master Log File" for information about how to safely remove this file.

The report entries created by the software usage monitoring system vary depending upon the command used to generate the entry; however, all entries have some fields that will always appear. Table 13-3 provides a list of all possible report entries, along with a description of each entry, and a list of when the entry is used.

If the field variable is not set, ?? would be the entry for the field variable because software usage monitoring could not determine its value.

To copy and format the software usage monitoring report entries in the master log file to another file or the standard output device, you need to perform the following procedure.

How to Print Software Usage Data from the Master Log File

1. Log in to the software usage monitoring host server.

2. Open a command tool and enter the swu_print command.

   $ swu_print [-a|-d|-s] [-f filename] [-l log_file]

   In this command,

   -a	Specifies the format swu_print is to use (default - all). Refer to Table 13-2for format examples.
   -d	Specifies the format swu_print is to use (dump). Refer to Table 13-2 for format examples.
   -s	Specifies the format swu_print is to use (summary). Refer to Table 13-2 for format examples.
   -f filename	Specifies the file to which information in the log file will be directed.
   -l log_file	Specifies the master log file. If this option is not specified, the default file /opt/SUNWswusg/swusage.log is used.

Removing the Master Log File

To keep your file system from filling up, you will periodically have to clean up the master log file; however, you must follow a certain procedure to properly remove this log file to prevent future data loss.

The following procedure describes how to safely remove the master log file.

How to Remove the Master Log File

1. Log in as root on the software usage monitoring server.

2. Move the master log file to a temporary log file.

   # mv /var/opt/SUNWswusg/swusage.log /tmp/tmp.log

3. Perform any processing you wish to /tmp/tmp.log.

4. Remove /tmp/tmp.log.

   # rm /tmp/tmp.log

5. Log out.

   ---

   Note -

   This procedure moves all the software usage record entries located in swusage.log to a new file; any new records generated during this procedure will cause a new swusage.log file to be created.

   ---