Wrapping Unlicensed Tools

The wrapping technique for monitoring unlicensed tools uses Monitor's built-in license management capability. This basic capability is activated by first creating a served license, then instructing the tool to either count its run as a checkout, or to request a license before being checked out, via a script or binary wrapper. Monitoring occurs automatically.

Creating a License

The vovlmd daemon configuration file, found at licmon.swd/vovlmd/config.tcl, allows for the creation of served licenses. The following is an excerpt from the vovlmd configuration template which details how to create a served license.

#######################
### SERVED LICENSES ###
#######################

# The following line is required to register licenses to be served.
# Uncomment it to activate served licenses.
# vtkle_features_init

# Create a license
# vtkle_feature_set <NAME> <CAPACITY|unlimited> [OPTIONS]

### Options
#
# -expire TIMESPEC|never  -- Set the expiration time for the license. Can be
#                            specified in seconds-from-now or a VOV TIMESPEC
#                            (1d, 1w, 1y). Default is to expire in one hour.
#                            Note: 1m is 1 minute, not 1 month!
# -log                    -- Generate a log of activity for debugging purposes.
#                            The log is located at licmon.swd/logs/features.log.

### Examples
#
# vtkle_feature_set sqlite 3 -expire never -log
# vtkle_feature_set sqlite unlimited -expire 180d

Using a License

Using the capability requires an environment variable that points to the location of the licenses being served. This variable is in the format of:

% setenv VOV_JOBCOUNTER 5555@lmsrv,licmon

In the example above, lmsrv is the Monitor server name, 5555 is the port (which is the default), and licmon is the Monitor instance name (also default).

The license then must be requested by using the vtool wrapper:

% vtool LICENSENAME LICENSEQTY TOOL

The wrapper requires 2 arguments (the license feature requested and the number of tokens required), which are followed by the command to be executed, along with the command's arguments. The complete usage syntax for the vtool wrapper is:


vtool: Usage Message

DESCRIPTION:
    A tool to execute a command using one or more features managed by the
    Altair Engineering-LM license manager. The VOV_JOBCOUNTER environment
    variable must point to the license manager vovserver instance using the
    format of port@host,instance (eg: 5557@lmhost,licmon).
    
    Multiple instances can be specified by separating them with a colon
    (eg: 5557@lmhost1,licmon1:6667@lmhost2,licmon2). If multiple instances
    are specified, each subsequent instance will be queried if the requested
    tokens were not granted by the previous instance in the list.
    By default, each instance must be able to grant the requested number of
    tokens in whole.  However, scavenging mode (-s) can be used to allow
    each instance to partially fulfill the request.

USAGE:
    % vtool [-v] [-refresh <S>] [-jobid <I>] -f <feature1> <tokens1> \
         [-f <feature2> <tokens2> ...] <command ...>

OPTIONS:
    -v                -- Increase verbosity.
    -f <feature> <N>  -- Check-out N tokens of specified feature.
                         If N is negative, queueing will be enabled for the
                         absolute value of N tokens.
                         It is an error for N to be zero.
    -refresh     <S>  -- Specify refresh cycle (time-spec) for tokens
                         (default is 600 seconds), meaning that
                         the tokens are refreshed every 10 minutes.
                         Setting a refresh cycle of 0 disables
                         the refresh.
    -jobid       <I>  -- Specify a jobid. If a refresh is performed and
                         the jobid statusnc is Failed, then the command is
                         terminated with vovkill.
    -s                -- Scavenging mode. When VOV_JOBCOUNTER is set to a
                         colon delimited list of license servers, a check
                         out from each server will occur until the target
                         number of tokens has been reached. If queuing is
                         enabled, only the last server will enter queuing
                         mode regardless of its license capability.

SIGNALS:
     TSTP             -- Release licenses and suspend execution.
     CONT             -- Resume execution.
     HUP              -- Caught and ignored
     TERM             -- Caught and ignored
     QUIT             -- Caught and ignored

SEE ALSO:
    vlmstat vovcounters

EXAMPLES:
    % vtool -f lic_drc -1 -f lic_hdrc -1 sleep 10
    % vtool -s -f lic_drc 3 sleep 10
    % vtool -f lic_drc 3  -refresh 2m  sleep 10000

Script Wrapping Example

Suppose there is a tool called spice which performs circuit simulation and typically runs in a few seconds. The tool uses the feature expensive_spice. Because the tool is so fast, the sampling methodology will capture only a small fraction of the check-outs of expensive_spice. The tool's invocation command is:

%
                    spice netlist.spi

Set the environment variable VOV_JOBCOUNTER to point at the Monitor server:
```
% setenv VOV_JOBCOUNTER 5555@HOSTNAME,licmon
```

Create a new license called mirror_spice. In the vovlmd/config.tcl file add:

% vtkle_features_init
% vtk_feature_set mirror_spice 10 -expire never -log

Test the license availability:

% vovcounters
vovcounters Wed 17:14:15: message: JobCounter: 5555@bear,licmon
vovcounters Wed 17:14:15: message: Wed Oct 10 05:14:15 PM PDT 2007
Counter spice                              0  of 5

Another utility, called vlmstat has been provided that provides a look and feel similar to lmstat.

Create an instrumented script, also called spice as follows:

#!/bin/csh -f
# This is the 'instrumented spice'
vtool mirror_spice 1 /full/path/to/spice $1

Using the PATH search mechanism, make sure that when the users invoke spice they find the instrumented script before they find the real spice.

The overhead introduced by the instrumented script is negligible. The statistics collected for the counter mirror_spice will be fairly accurate, but not necessarily an exact, representation of the utilization of expensive_license, in those cases in which the job actually checks out the license many seconds after it starts or checks it in many seconds before it exits.

Binary Wrapping

A binary wrapper can also be created for a tool, instead of using vtool. A utility is provided that helps in the creation of the binary wrapper: vovprotectwithcounter.csh.

Description:
   A utility to compile a binary wrapper for a binary in order to 
   be able to count all invocations of that binary.

   The utility compiles a small C program linked to the 
   libcounters.a library.

   This utility is meant to be an example of how you can 
   use the libcounters.a library. 
   You are free to look at the details of the script 
   ($VOVDIR/scripts/vovprotectwithcounter.csh) 
   and modify it to suit your particular needs.

   To change the C compiler, set the variable CC. 

   The output is a binary in the current directory with the
   same name as the wrapped binary.

Usage:
% vovprotectwithcounter.csh [-debug] /full/path/to/binary countername tokens

Example:
% vovprotectwithcounter.csh /bin/cp count_cp 1
% vovprotectwithcounter.csh -debug /bin/cp count_cp 1
% env CC="gcc -m64 -g"  vovprotectwithcounter.csh /bin/cp count_cp 1

set B = "`basename $0`:"
set B = `basename /integ/zfbuild/integ/builds/201901release/build/common/scripts/vovprotectwithcounter.csh`:
basename /integ/zfbuild/integ/builds/201901release/build/common/scripts/vovprotectwithcounter.csh

if ( $#argv < 3 ) then
if ( 0 < 3 ) then
cat << EOF
cat
exit 2
exit 2