VMware

VMware ACE

Features | Documentation | Knowledge Base | Discussion Forums

previous Prev   Contents   Last   Next next

 Writing Plug-In Policy Scripts

Writing Plug-In Policy Scripts

You may write your own plug-ins to control certain policies in VMware ACE. You may use any language that is supported on the end user's computer.

For security reasons, plug-ins must be deployed as part of a package and installed by the package installer. They cannot be deployed separately to end users' computers and cannot be modified by the end user.

Your plug-ins must write the appropriate values to StdOut. Output to StdOut maybe up to 4096 bytes long.

After creating a project, place any scripts you want to use for that project in the Project Resources folder under the project folder. They must be in the main Project Resources folder, not in a subdirectory under that folder. If the scripts need any additional resource files, place those files in the main Project Resources folder, too. Your script should reference those resources using relative paths.

Your plug-ins may also write messages to StdErr. Output to StdErr maybe up to 4096 bytes long. Any messages generated on StdErr are captured in the VMware ACE log file on the end user's machine at <UserAppData>\VMware\VMware ACE\<package_name>\Virtual Machines\<VM_name>\vmware.log.

The exit code of a script indicates whether the script succeeded or failed.

The following environment variables are set in the script execution environment:

 Variable
 Description
 VMWARE_NQ_DESCRIPTOR
 If custom network quarantine is in use, this variable holds the network quarantine descriptor that was last set by an update.
 VMWARE_EXPIRE_TIME
 This is the time at which this virtual machine will expire. If set to -1, it means never expire; if set to 0, it means expired.
 VMWARE_PROJ_ID
 The ID of the project to which this virtual machine belongs.
 VMWARE_MVM_ID
 The ID of this virtual machine. The virtual machine ID is unique within a project.

All plug-ins run each time the end user launches VMware ACE or resets the virtual machine. Some may run more often. For example, an expiration plug-in is run once each 24 hours, and you may specify the interval for running a network quarantine plug-in by setting an update interval in the Network Quarantine Wizard.

The sample scripts presented in Sample Scripts are installed with VMware ACE Manager. The default location is C:\Program Files\VMware\VMware ACE Manager\Samples.

The following descriptions give the format for the output that your plug-ins must write to StdOut to control various policies.

Authentication Plug-Ins

Authentication Plug-Ins

The following table outlines the basic information you need to write authentication plug-ins.

 Question
 Explanation
 When does this script execute?
 This script executes when the virtual machine is opened.
 What relevant environment variables are available to the script?
 No authentication-specific environment variables are available, but VMWARE_PROJ_ID and VMWARE_MVM_ID give some context, indicating what virtual machine the user is trying to open.
 What is the expected output?
 The output of this script is hashed to create a key to encrypt and decrypt virtual machine files. The first time this script is run, the output is hashed to encrypt the virtual machine. When a virtual machine is decrypted, the script must return the same value. If the script returns a different value, the virtual machine is not decrypted and the user sees an error message.
 The script may return any value. To ensure best security, a value that includes only printable characters should be at least 32 bytes long. For binary data, the value should be at least 16 bytes long to ensure proper entropy.
 What can I do with this script?
 The script should do one of the following:
  • If the user is to be granted access to the virtual machine, generate the data used to create the key for this user and send it as output. The data should be unique for each user.
  • If the user is to be denied access to the virtual machine, the script should exit with a non-zero exit code.
    Note: This is a reference to the exit code, not the output value.
    		•
     Where should the output of the script go?
     The script should send its output to StdOut.
     What should the exit code of the script be?
     If access is granted, the exit code should be 0. If access is denied, the exit code should be nonzero.
    Note: This is a reference to the exit code, not the output value.

    Renewal Plug-Ins

    Renewal Plug-Ins

    The following table outlines the basic information you need to write renewal plug-ins.

     Questions
     Explanation
     When does this script execute?
     This script executes every time the virtual machine is powered on or reset.
     What relevant environment variables are available to the script?
     VMWARE_EXPIRE_TIME
    It holds the current expiration time, expressed as seconds since Jan. 1, 1970 (UTC).
     What is the expected output?
     If the output of this script is greater than 32767, it is interpreted as a date, expressed as the number of seconds since Jan. 1, 1970 (UTC). Otherwise, it is interpreted as the number of days to allow the virtual machine to run, beginning on the current date.
     What can I do with this script?
     The script may do one of the following:
  • Set the virtual machine expired. If the output is a time that is in the past, the virtual machine is expired. Note that the value must be greater than 32767, otherwise the output is treated as a number of days and the virtual machine is allowed to run for the specified number of days, beginning on the current date.
  • Allow the virtual machine to run. If the output is a date in the future, expressed as a number of seconds since Jan. 1, 1970 (UTC), the virtual machine is renewed. Times are rounded up to midnight of the day specified. If the output is a value less than 32767, the virtual machine is allowed to run for the specified number of days, beginning on the current date.
  • Take no action. If the output is 0, nothing is changed.
  • Set the virtual machine so it never expires. Generate an output value of -1.
    		•
     Where should the output of the script go?
     Your script should send its output to StdOut.
     What should the exit code of the script be?
     It should be 0. Any nonzero exit code voids any output to StdOut.

    Note: Because the script runs each time the end user launches VMware ACE or resets the virtual machine, the current date is different each time the script runs. Take this changing reference point into account in your script.

    Device Connection Plug-Ins

    Device Connection Plug-Ins

    The following table outlines the basic information you need to write device connection plug-ins:

     Question
     Explanation
     When does this script execute?
     This script executes when the virtual machine is powered on.
     What relevant environment variables are available to the script?
     No specific environment variables are available. But you should set different scripts (scripts with different arguments) for each device. This enables each script to determine why it is being called.
     What is the expected output?
     The output of this script is a boolean. Output a value of TRUE if the user is allowed to change the connection status of the device or FALSE to deny the user the ability to change the connection status of the device.
     What can I do with this script?
     The script should determine if the current user is allowed to change the connection status of a device.
  • Send TRUE to StdOut to allow permission to change connection status.
  • Send FALSE to StdOut to deny permission to change connection status.
    		•
     Where should the output of the script go?
     The script should send its output to StdOut.
     What should the exit code of the script be?
     The script should always exit with a status of 0.

    Network Quarantine Plug-Ins

    Network Quarantine Plug-Ins

    The following table outlines the basic information you need to write network quarantine plug-ins.

     Question
     Explanation
     When does this script execute?
     This script executes at power on, at reset and when a virtual machine sends a network quarantine descriptor update.
     What relevant environment variables are available to the script?
     VMWARE_NQ_DESCRIPTOR contains the string last set by a guest update. To do a guest update, you run nq-set (a command provided by VMware Tools) in the guest operating system.
     What is the expected output?
     The output of the script may be one of the following, in all capital letters as shown:
  • YES — The current network quarantine descriptor is valid and should be given normal access.
  • NO — The current network quarantine descriptor is valid and should be given restricted access.
  • REJECT — The current network quarantine descriptor is invalid.
    		•
     What can I do with this script?
     The script should do both of the following:
  • Verify that the string contained in VMWARE_NQ_DESCRIPTOR is valid.
  • Evaluate the network quarantine descriptor and decide whether to give normal or restricted access to the virtual machine.
    		•
     Where should the output of the script go?
     The script should send its output to StdOut.
     What should the exit code of the script be?
     It should be 0. Any nonzero exit code voids any output to StdOut.

    Updating Virtual Machine Versions with the nq-set Command

    Updating Virtual Machine Versions with the nq-set Command

    The comments in the sample network quarantine scripts provided with VMware ACE Manager mention the nq-set command. If you update the guest operating system or other software in the virtual machine after distributing it, be sure your updater runs the nq-set command inside the virtual machine to update the virtual machine's version descriptor appropriately.

    If you do not run nq-set, VMware ACE cannot detect that the virtual machine has been updated.

    For details on using nq-set, see Using nq-set to Update Network Quarantine Versions.

    Sample Scripts

    Sample Scripts

    Sample Authentication Script

    Sample Authentication Script

    The following sample script is written in C. It is installed by VMware ACE Manager as sampleAuth.c. You may compile it with a C compiler if you want to run it.

    /*
     *
     * VMware Sample Script
     *
     *
     * This is a sample authentication script for VMware ACE.
     *
     *
     * Input to script:
     * None

     *
     * Returns:
     * Exit code of 0 if successful (user is correctly authenticated)
     *     Exit code nonzero if an error occurred, or if authentication
     *     failed
     *
     *     Expected output:
     *     Seed data to hash to create key for encryption/authentication
     *     subsystem on stdout.
     *
     *
     * Notes:
     * If the script returns success, its output will be hashed to
     *      create a key. Therefore it is important that the output of
     *      this script is unique for each user, and that there is enough
     *      data to make a meaningful key. (That is, at least 16 bytes.)
     *
     *
     * Notes about this sample:
     * This script contains key data (hard-coded) for several users.
     * The script assumes that the username is contained in an
     * environment variable called TEST_USERNAME (a fictitious
     * environment variable used in this sample).
     *
     * It will then return the correct data for that user if one
     * exists; otherwise it will return an error exit code (1).
     *
     *
     */

    #include <stdio.h>
    #include <stdlib.h>
    #include <string.h>

    typedef struct {
       char *name;
       char *keydata;
    } UserListType;

    static UserListType userList[] = {
            {"charlie", "E1C4F612135B4D98A33B2C9BD595025D"},
            {"kathy", "C79AFFEF773D61225751C2566858DB08"},
            {"beth", "05B169B439B26AAB2EA4F755B7E3800C"},
            {"ernie", "8CE63D4AA2068BD8AFF2D1B05F3495A5"},
            {"bert", "172B1619B2EFBE0E4F381AA1C428F049"},
                    NULL
    };

    int
    main(int argc,
           char *argv[])
    {

       char *username;
        int counter;
       int result = 1;

        /* Get the username from the env. var TEST_USERNAME */
       username = getenv("TEST_USERNAME");
       if (username == NULL) {
           /* No user specified, exit with an error */
          fprintf(stderr, "TEST_USERNAME not set\n");
          goto exit;
        }


        counter = 0;

       while (userList[counter].name != NULL) {
           if (strcmp(userList[counter].name, username) == 0) {
              /* Found the right user; print their key */
             printf("%s", userList[counter].keydata);
             result = 0;
             goto exit;
           }
           counter++;
           }

        /* No match found */
       fprintf(stderr, "User (%s) not found in list\n", username);

    exit:
        return result;
    }

    Sample Renewal Script

    Sample Renewal Script

    The following sample script is written in VB Script. It is installed by VMware ACE Manager as expire_on_fridays.vbs.

    '
    ' VMware Sample Script
    '
    ' This is a sample expiration/renewal script for VMware ACE
    '
    ' This script returns a UTC time (number of seconds since
    ' 1/1/1970) for use in determining product expiration. If
    ' the time returned is less than the current time, the
    ' product has expired, otherwise it has not. This script
    ' always marks the product as expired on Fridays, just
    ' because. Otherwise, it expires on Jan 1, 2010.
    '
    ' This script must be run as follows:
    ' cscript -nologo expire_on_fridays.vbs

    Dim StdOut
    Dim StdErr

    Set StdOut = WScript.StdOut
    Set StdErr = WScript.StdErr

    ' Output to stderr is sent to the VMware log file. It
    ' does not, in itself, constitute an error in the script.
    StdErr.WriteLine "Running expire_on_fridays.vbs"

    If (DatePart("w", Now) = 6) Then

        ' It's a Friday. Game over.
         StdOut.Write DateDiff("s", "1/1/1970", Now) - 100
    Else
        StdOut.Write DateDiff("s", "1/1/1970", "1/1/2010")
    End If

    Sample Device Connection Script

    Sample Device Connection Script

    The following sample script is written in C. It is installed by VMware ACE Manager as sampleDevice.c. You may compile it with a C compiler if you want to run it.

    /*
     * VMware Sample Script
     *
     * This is a sample device policy script for VMware ACE.

     * Notes about this sample:
     *
     *    This script will examine the contents of an environment variable
     *     and output YES if the variable is set, or NO if it isn't.
     *
     *    This script always exits successfully (exit code 0)
     *
     *      The environment variable is called TEST_DEVICE
     *
     * Input to script:
     *     This script does not depend on any environment variables set by
     *      VMware ACE
     *
     * Returns:
     *      Returns 0 for success
     *
     * Expected output:
     *      The script may output to stdout:
     *              'YES' - Allow the user to manage the device
     *              'NO' - Do not allow the user to manage the device
     */

    #include <stdio.h>
    #include <stdlib.h>
    #include <string.h>

    int
    main(int argc,
           char *argv[])
    {
           char *env_var;

        /* Test for existence of TEST_DEVICE variable in environment: */
        env_var = getenv("TEST_DEVICE");
         if ((env_var == NULL) || (strlen(env_var) == 0)) {
             printf("NO");
         } else {
             printf("YES");
         }

         return 0;
    }

    Sample Network Quarantine Script 1

    Sample Network Quarantine Script 1

    The following sample script is written in C. It is installed by VMware ACE Manager as sampleQuarantine.c. sYou may compile it with a C compiler if you want to run it.

    /*
     * VMware Sample Script
     *
     * This is a sample network quarantine script for VMware ACE.
     *
     * Notes About this sample:
     *      The NQ Script does 2 things, (1) verifies that the string in
     *      VMWARE_NQ_DESCRIPTOR is valid, and (2) returns whether the
     *      guest operating system that this descriptor is from should be
     *      given normal access (YES), or should be given restricted
     *     access (NO)
     *
     *      For testing purposes a list of NQ_DESCRIPTORS is stored
     *      statically in this file, each with its corresponding result
     *      (YES/NO/REJECT); this sample script will match the value in
     *      VMWARE_NQ_DESCRIPTOR to a stored string and output its stored
     *      "up-to-date" state (YES/NO/REJECT).
     *      If there are no matches, then we output REJECT.
     *
     * Input to script:
     *      Script examines the environment variable VMWARE_NQ_DESCRIPTOR
     *
     * Returns:
     *      Returns 0 for success
     *
     * Expected output:
     *      The script may output to stdout:
     *          'YES' - the descriptor is valid and up-to-date
     *           'NO' - the descriptor is valid and not up-to-date
     *           'REJECT' - the descriptor is not valid
     *
     * Setting the NQ descriptor:
     *      To set the NQ descriptor from the guest os you must run the
     *      following command (without the brackets around the new
     *     descriptor):
     *
     *      On a Linux guest:
     *      (Binary located at /src/sbin)
     *         vmware-guestd --cmd "nq-set [new descriptor]"
     *
     *      On a Windows guest:
     *      (Binary located at C:\Program Files\VMware\VMware Tools)
     *         vmwareservice -cmd "nq-set [new descriptor]"
     *
     * (without the brackets around the new descriptor)
     *
     */

    #include <stdio.h>
    #include <stdlib.h>
    #include <string.h>

    typedef struct {
         char *descriptor;
         char *uptodate;
    } DescriptorListType;

    static DescriptorListType descriptorList[] = {
         {"os=winxp-sp2,ie=6.0,virusdefs=4.0,office=2003-sp1", "YES"},
         {"os=winxp-sp1,ie=6.0,virusdefs=4.0,office=2003-sp1", "NO"},
         {"uptodate", "YES"},
         {"notuptodate", "NO"},
         {"rejectme", "REJECT"}
         NULL
    };

    int
    main(int argc,
           char *argv[])
    {
         char *descriptor;
         int counter;
         int result = 1;

    /* Get the current descriptor from the env. var
       * VMWARE_NQ_DESCRIPTOR
        */
         descriptor = getenv("VMWARE_NQ_DESCRIPTOR");
         if (descriptor == NULL) {
         fprintf(stderr, "VMWARE_NQ_DESCRIPTOR not set\n");
         goto exit;
    }

         result = 0;
         counter = 0;
         while (descriptorList[counter].descriptor != NULL) {
         if (strcmp(descriptorList[counter].descriptor, descriptor) == 0 {
                   /* Found the right descriptor */
                    printf("%s", descriptorList[counter].uptodate);
                    goto exit;
               }
               counter++;
          }

          /* No match found */
          printf("REJECT");

    exit:
          return result;
    }

    Sample Network Quarantine Script 2

    Sample Network Quarantine Script 2

    The following sample script is written in Perl. It is installed by VMware ACE Manager as sampleQuarantine.pl. You need a Perl interpreter to run this script.

    #
    # VMware Sample Script
    #
    # This is a sample network quarantine script for VMware ACE.
    #
    # Notes About this sample:
    #    The NQ Script does 2 things, (1) verifies that the string in
    #    VMWARE_NQ_DESCRIPTOR is valid, and (2) returns wether the guest
    #    operating system that this descriptor is from should be given
    #    normal access (YES), or should be given restricted access (NO)
    #
    #     For testing purposes 2 lists of NQ_DESCRIPTORS are stored
    #     statically in this file: an approved list and an unapproved
    #     list. This sample script will match the value in
    #     VMWARE_NQ_DESCRIPTOR to a stored string, and output YES if it
    #     came from the approved list, NO if it came from the unapproved
    #     list, and REJECT otherwise.
    #
    # Input to script:
    #     Script examines the environment variable VMWARE_NQ_DESCRIPTOR
    #
    # Returns:
    #    Returns 0 for success
    #
    # Expected output:
    #    The script may output to stdout:
    #        'YES' - the descriptor is valid and up-to-date
    #        'NO'   - the descriptor is valid and not up-to-date
    #        'REJECT' - the descriptor is not valid
    #

    # Setting the NQ descriptor:
    #    To set the NQ descriptor from the guest os you must run the
    #    following command:
    #
    #    On a Linux guest:
    #    (Binary located at /src/sbin)
    #        vmware-guestd --cmd "nq-set [new descriptor]"
    #
    #    On a Windows guest:
    #    (Binary located at C:\Program Files\VMware\VMware Tools)
    #         vmwareservice -cmd "nq-set [new descriptor]"
    #
    # (without the brackets around the new descriptor)
    #

    my @approved = (
        "os=winxp-sp2,ie=6.0,virusdefs=4.0,office=2003-sp1",
        "uptodate"
    );

    my @unapproved = (
        "os=winxp-sp1,ie=6.0,virusdefs=4.0,office=2003-sp1",
        "notuptodate"
    );

    sub find_match{
        foreach (@approved) {
            if (/^$_[0]$/i) {
                return "YES";
            }
        }

        foreach (@unapproved) {
            if (/^$_[0]$/i) {
                return "NO";
            }
        }

        return "REJECT";
    }

    my $nqEnvName = 'VMWARE_NQ_DESCRIPTOR';
    my $nqVal = $ENV{$nqEnvName};

    print &find_match($nqVal);

    previous Prev   Contents   Last   Next next