Part III Additional Solstice AdminSuite Administration

This part provides information on additional administration that you may need to do after using the Solstice AdminSuite software, and additional administration that the Solstice AdminSuite software provides.

Chapter 12, Booting a System From the Network

Booting a System From the Network provides instructions on how to manually boot your diskless clients from the network and how to set them up to automatically boot from the network.

Chapter 13, Monitoring Software Usage

Monitoring Software Usage provides overview information and instructions on how to use a compilation of software programs that enable you to monitor software usage in a server/client environment or on a non-networked system.

Chapter 12 Booting a System From the Network

After you add a diskless client (see "How to Add Support for a Diskless Client") to a server, the system is ready to boot and run the Solaris environment.

Diskless clients must always boot from the network.

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

• "SPARC: How to Manually Boot a System From the Network"

• "SPARC: How to Manually Boot a Sun-4 System From the Network"

• "SPARC: How to Set Up a System to Automatically Boot From the Network"

• "SPARC: How to Set Up a Sun-4/3nn System to Automatically Boot From the Network"

• "SPARC: How to Set Up a Sun-4/1nn, 2nn, or 4nn System to Automatically Boot From the Network"

• "x86: How to Manually Boot a System"

• "x86: How to Set Up a System to Automatically Boot From the Network"

SPARC: Booting From the Network

This section provides procedures on how to manually boot your SPARC system from the network, and how to set it up to automatically boot from the network.

You need to read only certain portions of this section. Table 12-1 shows you which task information to read for the type of systems you have on your network.

In the Solaris 2.5 environment, only the Sun-4c, Sun-4d, Sun-4m, Sun-4u kernel architectures, and the x86 platforms are supported. The Solaris 2.5 software no longer supports Sun-4 and Sun-4e.

Table 12-2 summarizes the commands you use to manually boot systems from the network for different system models.

For more information about the booting process in general, see the Solaris 2.4 Administration Supplement for Solaris Platforms for the Solaris 2.4 product, and the System Administration Guide, Volume I for the Solaris 2.5 product.

SPARC: How to Manually Boot a System From the Network

If you want to manually boot a Sun-4 system from the network, see "SPARC: How to Manually Boot a Sun-4 System From the Network".

1. Make sure the diskless client has been set up as described in "How to Add Support for a Diskless Client".

2. Make sure the system is in the prom monitor environment.

   If the system is not running, power it up. If the system is currently running, use the init 0 command to get it to the boot prom prompt.

3. If the screen displays the > prompt instead of the ok prompt, type n and press Return or Enter.

   The screen should now display the ok prompt. If not, see "SPARC: How to Manually Boot a Sun-4 System From the Network".

4. Boot the system from the network.

   ok boot net

Example of Manually Booting a SPARC System From the Network

# init 0
> n
ok
.
.
.
ok boot net
Booting from: le(0,0,0)
2bc00 hostname: pluto
domainname: Solar.COM
root server:
root directory: /export/root/pluto
SunOS Release 5.4 Version [2.4_FCS] [UNIX(R) System V Release
4.0]
Copyright (c) 1983-1994, Sun Microsystems, Inc.
configuring network interfaces: le0.
Hostname: pluto
Configuring cache and swap:......done.
The system is coming up. Please wait.
NIS domainname is Solar.COM
starting rpc services: rpcbind keyserv ypbind kerbd done.
Setting netmask of le0 to 255.255.255.0
Setting default interface for multicast: add net 224.0.0.0:
gateway pluto
syslog service starting.
Print services started.
volume management starting.
The system is ready.
login: root
password:
# exit

SPARC: How to Manually Boot a Sun-4 System From the Network

1. Make sure the diskless client has been set up as described in "How to Add Support for a Diskless Client".

2. Make sure the system is in the prom monitor environment.

   If the system is not running, power it up. If the system is currently running, use the init 0 command to get it to the boot prom prompt.

3. Type the appropriate boot command to boot the system from the network.

   > b le() or > b ie()

SPARC: How to Set Up a System to Automatically Boot From the Network

If you want to set up a Sun-4 system to automatically boot from the network, see "SPARC: How to Set Up a Sun-4/3nn System to Automatically Boot From the Network", or "SPARC: How to Set Up a Sun-4/1nn, 2nn, or 4nn System to Automatically Boot From the Network".

1. Make sure the diskless client has been set up as described in "How to Add Support for a Diskless Client".

2. Make sure the system is in the prom monitor environment.

   If the system is not running, power it up. If the system is currently running, use the init 0 command to get it to the boot prom prompt.

3. If the screen displays the > prompt instead of the ok prompt, type n and press Return or Enter.

   The screen should now display the ok prompt. If not, see "SPARC: How to Set Up a Sun-4/3nn System to Automatically Boot From the Network", or "SPARC: How to Set Up a Sun-4/1nn, 2nn, or 4nn System to Automatically Boot From the Network".

4. Determine the version number of the boot prom with the banner command. The following is an example:

   ok banner SPARCstation 2, Type 4 Keyboard ROM Rev. 2.0, 16MB memory installed, Serial # 289 Ethernet address 8:0:20:d:e2:7b, Host ID: 55000121

5. Set the boot device.

   If the boot prom is version 2.0 or greater, type the following command.

   ok setenv boot-device net boot-device=net

   If the boot prom version is less than 2.0, type the following command.

   ok setenv boot-from net

   For more information about boot proms, see the OpenBoot 2.x Command Reference Manual or the OpenBoot 3.x Command Reference Manual.

6. Boot the system automatically from the network by using the boot command.

   ok boot

SPARC: How to Display Existing Boot Device Values on Sun-4 Systems

This procedure describes how to display the current boot device values, if you need to record them before changing them.

1. Display the values of the system's current booting devices.

   > q18

   The system displays the first EEPROM value.

2. Write down the EEPROM number and value.

   For example, you might see EEPROM 018:12?. The EEPROM number is 018 and the value is 12.

3. Press Return to display the next value.

4. Repeat steps 2 and 3 until the last value is displayed.

   The last value is 00.

5. Quit the EEPROM display mode.

   EEPROM 01B: 00? q

Example of Displaying Existing Boot Device Values on Sun-4 Systems

> q18
EEPROM 018: 12?
EEPROM 019: 69?
EEPROM 01A: 65?
EEPROM 01B: 00? q
>

Entering q18 and pressing Return three times displays the three values. You should retain this information. The last q entry returns you to the > prompt.

SPARC: How to Set Up a Sun-4/3nn System to Automatically Boot From the Network

1. Make sure the diskless client has been set up as described in "How to Add Support for a Diskless Client".

2. Make sure the system is in the prom monitor environment.

3. (Optional) Perform the procedures in "SPARC: How to Display Existing Boot Device Values on Sun-4 Systems" if you want to record the current boot device values.

4. At the command prompt, enter the following boot device code sequence.

   > q18 12 6c 65

   This is the code for le (the Lance Ethernet).

   What you are doing for any of the Sun-4 architectures is programming the EEPROM (or NVRAM) by entering q followed by the hexadecimal address in the EEPROM. This sets the appropriate operating system boot device.

5. Boot the system automatically from the network.

   > b

Example of Setting Up a Sun-4/3nn System to Automatically Boot From the Network

> q18 12 6c 65
EEPROM 018 -> 12
EEPROM 019 -> 6C
EEPROM 01A -> 65
>

If the system output looks like the example above, you set the codes successfully. If the output looks similar to the following:

> b

EEPROM boot device... ie(0,0,0)

Invalid device = `ie'

you set the wrong code for the specific system architecture, and the system will not boot. You need to reset the codes. In the above example output, a Sun-4/3nn was set up with the wrong device code (ie instead of le).

SPARC: How to Set Up a Sun-4/1nn, 2nn, or 4nn System to Automatically Boot From the Network

1. Make sure the diskless client has been set up as described in "How to Add Support for a Diskless Client".

2. Make sure the system is in the prom monitor environment.

3. (Optional) Perform the procedures in "SPARC: How to Display Existing Boot Device Values on Sun-4 Systems" if you want to record the existing boot device values.

4. At the command prompt, enter the following boot device code sequence.

   > q18 12 69 65

   This is the code for ie (the Intel Ethernet).

   What you are doing for any of the Sun-4 architectures is programming the EEPROM (or NVRAM) by entering q followed by the hexadecimal address in the EEPROM. This sets the appropriate operating system boot device.

5. Boot the system automatically from the network.

   > b

Example of Setting Up a Sun-4/1nn, 2nn, or 4nn System to Automatically Boot From the Network

> q18 12 69 65
EEPROM 018 -> 12
EEPROM 019 -> 69
EEPROM 01A -> 65

If the system output looks like the example above, you set the codes successfully. If the output looks similar to the following:

> b

EEPROM boot device... le(0,0,0)

Invalid device = `le'

you set the wrong code for the specific system architecture, and the system will not boot. You need to reset the codes. In the above example output, a Sun-4/1nn, 2nn, or 4nn was set up with the wrong device code (le instead of ie).

x86: Booting From the Network

The following procedures apply to x86 systems. Booting an x86 system uses these two subsystems:

• Solaris boot diskette (contains the program that provides booting from the network)

• Secondary boot subsystem

The Solaris boot diskette, also known as the MDB diskette, provides a menu of bootable devices such as disk, network, or CD-ROM. (The system probes currently connected devices and displays the devices in the MDB menu.) Diskless clients must boot from the network so you would always enter the code for the network device.

The second boot subsystem menu displays available boot options. The system automatically boots to run level 3 if you do not select an option within 60 seconds. The other options enable you to specify boot options or enter the boot interpreter (see boot(1M)).

x86: How to Manually Boot a System

This procedure describes how to manually boot your x86 system from the network. Screen displays will vary based on system configurations.

1. Make sure the diskless client has been set up as described in "How to Add Support for a Diskless Client".

2. Insert the Solaris boot diskette into the drive.

3. Press the reset button.

   The Primary Boot Subsystem menu is displayed after a short time.

   

   The Solaris boot diskette provides a menu of bootable devices such as disk, network, or CD-ROM. (The system probes currently-connected devices and displays the devices in the MDB menu.)

   ---

   Note -

   The number 30 displayed in the bottom left corner counts down, indicating the number of seconds left to set the boot device code. If you do not specify the boot device code within 30 seconds, the system will attempt to boot from the C drive, which is the default device.

   ---

4. Enter the boot device code to boot from the network.

   In this example the boot device code is 12.

   The Secondary Boot Subsystem menu is displayed after a short time.

   

5. Type b or boot to boot the system and press Return.

x86: How to Set Up a System to Automatically Boot From the Network

This procedure describes how to create an x86 multiple device boot (MDB) diskette so that your x86 diskless client will always boot from the network--so you do not have to be there to boot it. Otherwise, if the master MDB diskette is inserted into the drive, an x86 system will attempt to boot off the C drive after a power cycle (for more information see "x86: Booting From the Network").

Before following these steps to create an MDB boot diskette, obtain the master MDB diskette for the x86 system and a blank 1.44 Mbyte diskette. The blank diskette will be formatted, so do not use a diskette with data on it.

1. Become root on your server.

2. Change your working directory.

   # cd /opt/SUNWadm/2.3/floppy

3. ++

   Create the MDB boot diskette.

   # ./mk_floppy

   The script prompts you when to insert the MDB master diskette and the blank diskette, and provides additional status information.

   Please insert the master MDB floppy and press Return: Please insert a blank floppy and press Return: Formatting 1.44 MB in /dev/rdiskette ............................................................. ................... fdformat: using "./mdboot" for MS-DOS boot loader Successfully created the AutoClient floppy. #

   ---

   Note -

   Even though the script says that it created an AutoClient floppy, you can also use this floppy on diskless x86 systems.

   ---

4. Insert the MDB boot diskette into the diskette drive of the x86 system.

   You must leave this boot diskette in the diskette drive so that the system will automatically boot from the network if a power cycle occurs.

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.

   ---