------------------------------------------------------------ Welcome ------------------------------------------------------------ Last updated Date: 02/02/2007 ------------------------------------------------------------ Sun Virtual Desktop Access Kit for VMware 1.0 - ReadMe ------------------------------------------------------------ Dear User This file contains important information about the Sun Virtual Desktop Access Kit for VMware. Please read this information very carefully before starting work. The ReadMe explains the installation process, gives insight into the configuration of the Access Kit components and lists any known issues. You find more information on our web site http://www.sun.com/sunray. ------------------------------------------------------------ Overview ------------------------------------------------------------ The Virtual Desktop Access Kit for VMware is the glue for linking a managed Virtual Desktop environment delivered through VMware VI 3 (VDI) and the Desktop Infrastructure components delivered by Sun, namely Sun Secure Global Desktop (SSGD) and Sun Ray Server Software (SRSS). The Access Kit manages the lifecycle of Windows XP or Windows 2000 based virtual machines, also called Virtual Desktops. This includes the Virtual Desktop creation, startup and shutdown (or suspension). The VDA Kit is also responsible for establishing the communication between desktop environment and access tier (SSGD + SRSS). This communication is based on Microsoft RDP supported both by SSGD and SRSS. The Access Kit encompasses 3 components that are installed on the different layers of the architecture: * VDA Tools for VMware: They are installed on the Guest OS inside the VM and deliver a more robust handling of the RDP connection. * VDA Service for VMware: This is a Windows service installed on the server hosting Virtual Center 2.x. It provides the control logic for managing the VM lifecycle. This component utilizes the VMware VI SDK. * VDA Client for VMware: The VDA Client is installed on the Access Tier (SGD or SRSS). It contacts the VDA Service to locate a VM based on a given identifier, like for example a User ID. Additionally the Access Kit for VMware delivers a couple of scripts that invoke the VDA Client. These scripts are responsible for establishing an RDP connection on behalf of SGD or SRSS. ------------------------------------------------------------ Installation of the Virtual Desktop Access Tools for VMware ------------------------------------------------------------ System Requirements: * Windows XP SP2 or higher * VMware Tools delivered through VMware ESX 3.01 or higher The VDA Tools are delivered as a simple component installed as a Windows NT Service on the Guest OS. Their purpose is to close RDP connections whenever the Guest OS gets suspended through a power event like a system standby. This is not handled by Windows XP, but is very important in order to avoid screen freezing on the access client. The installation includes the following steps: 1. Make sure that the VMware Tools are installed and running. They are a prerequisite for the Virtual Desktop Access Tools 2. Copy the Virtual Desktop Access Tools archive 'vda-tools.zip' to the XP image. 3. Extract the archive to 'c:\sun-vda' 4. Register the VDA Tools as a Windows NT service through the command: 'c:\sun-vda\bin\register-vda-tools.bat' After the final installation step the service should be listed in the services list and should be up and running. After a restart of the Guest OS the service will be automatically started. Uninstallation is also straightforward: 1. Unregister the VDA Tools service by running the command: 'c:\sun-vda\bin\unregister-vda-tools.bat' 2. Remove the directory 'c:\sun-vda' ------------------------------------------------------------- Installation of the Virtual Desktop Access Service for VMware ------------------------------------------------------------- System Requirements: * Windows 2003 Server * VMware Virtual Center 2.x The VDA Service contains the whole control logic for locating, starting, creating Virtual Desktops. It is installed on the server hosting the Virtual Center 2.x. The VDA Service is implemented as a Windows NT service. This service encompasses the VI SDK (vim.jar) and its own business logic aggregated in the 'via.jar' file. In order to work properly the VDA Service requires a couple of configuration settings, which need to be set before starting the service. These are the steps to install the VDA Service for VMware: 1. Make sure that the Virtual Center Service ('vpxd') is up and running. This is a prerequisite for the VDA Service. 2. Ensure that the Web Service Access for the SDK is configured. The URL for accessing the VMware Infrastructure is 'protocol://localhost/sdk'. The protocol can either be http or https. The VMware SDK Programming Guide details the configuration. 2. Copy the VDA Service archive 'vda-service.zip' to the VC host. 3. Extract the archive to 'c:\sun-vda' 4. Configure the service (see below) 5. Register the VDA Service through the command: 'c:\sun-vda\bin\register-vda-service.bat' After the final installation step the service should be listed in the services list and should be up and running. After a restart of the VC host the service will be automatically started. Uninstallation is done by: 1. Unregister the VDA Service by running the command: 'c:\sun-vda\bin\unregister-vda-service.bat' 2. Remove the directory 'c:\sun-vda' ------------------------------------------------------------ Configuration of the Virtual Desktop Access Service for VMware ------------------------------------------------------------ All configuration settings for the VDA Service are stored in a single file called 'vda.properties'. The file is located in the 'c:\sun-vda\conf' directory of the installation. It requires a couple of mandatory settings before connecting to the Virtual Center Service. Note: It is recommended to verify configuration changes before applying them through the command 'c:\sun-vda\bin\vda-service test'. Note: Each configuration change requires a restart of the VDA Service. ==> Configuration of the connection to the Virtual Infrastructure Web Service (mandatory) * Connection.User: User with proper privileges to handle the lifecycle of VMs and their parent folders. * Connection.Pwd: Password of the user. * Connection.WebServiceUrl: URL to connect to the VI Web Service. This should typically be defined as: 'https://localhost/sdk' ==> Configuration of Pools * Pool.Count: Defines the number of pools. For each pool setting there needs to be a pool number appended. Example: Pool.Count = 1 Note: You need to either not specify a count, and then use unsuffixed keys for a single pool setting, or specify a count and then use suffixed keys for all pools settings. * Pool.Path: Location of the pool. Example: Pool.Path0 = "/Datacenter/vm/Pool" * Pool.Template: Location of the template VM, that is used to clone new VMs. If not set, the factory is disabled for the pool. Example: Pool.Template0 = "/Datacenter/vm/Templates/Golden Master" * Pool.MinSize: Minimal number of available VMs in the pool. Example: Pool.MinSize0 = 5 * Pool.Customization: Name of the customization spec to use. Example: Pool.Customization0 = Desktop-Cust ==> Configuration of Folders * Folders.Static: Location of user assigned VMs. If not set or invalid, all VMs will be taken from dynamic pool(s) * Folders.Cluster: Location of a cluster. If not set or invalid, there must be at least a single host available. All advanced features like Dynamic Resource Scheduling will not work if clustering is disabled. ==> General Settings (optional) * General.LogLevel: Log level, output into the log subdirectory. * General.AgentPort: Port for communication with the VDA Client ==> Settings to test the sanity of a Virtual Machine (optional) * Startup.RDPPort: Port that is used for RDP connection. Before a VM is handed over to the Access Tier is verified that the RDP port is open for communication. * Startup.RDPTimeout: Is the time in seconds the service will wait for the RDP service to become available. * Startup.Timeout: Defines the duration for how long it is tried to get a valid IP for a VM. ==> Settings that control the behavior of the VM monitor (optional) * Monitor.RecyclePollInterval: Interval in which the monitor observes dynamic pools and their factories. * Monitor.FactoryPollInterval: Length between iterations that check if enough virtual machines are available in defined pools. If there are not enough VM available, the creation of new VMs is initiated. * Monitor.IdleTimeout: Is the time in minutes after which a suspended machine will be recycled. Note: In is important that the Virtual Center and the managed ESX server have the same time. Otherwise the behavior is undefined. # Monitor.FactoryMaxMachines: Maximum number of machines (across all pools) # being created at the same time. ------------------------------------------------------------ Installation of the Virtual Desktop Access Client for VMware ------------------------------------------------------------ System Requirements: * Solaris 10 Sparc or X86 * Either SRSS 3.1 or SSGD 4.2 or higher installed The VDA Client is the component that has to be installed on the Access Tier, namely the SRSS or SSGD. It is a simple client that contacts directly the VDA Service to obtain IP addresses of Virtual Machines on behalf of SRSS or SSGD. An RDP connection can be initiated thereafter with the returned IP address. Besides the 'vda-client' executable the installation archive contains scripts that can be used by SSGD or SRSS to initiate RDP sessions to Virtual Machines. The installation steps for the VDA Client are: 1. Copy the VDA Client archive 'vda-client.zip' to the SRSS or SGD server. 2. Extract the archive to '/opt/sun-vda' In order to uninstall the client you only need to remove the '/opt/sun-vda' directory. ----------------------------------------------------------------------- Commandline parameters for the Virtual Desktop Access Client for VMware ----------------------------------------------------------------------- The 'vda-client' executable expects a few command line arguments to initiate a connection to the VDA Service: * -s: host of the vda-service * -p: port of the vda-service, 3809 by default * -P: pool to be used to locate a Virtual Machine (optional) * -m: machine identifier, this can be a user-id or a token id or any other unique identifier that helps to locate a VM ------------------------------------------------------------ Example script for SRSS CAM ------------------------------------------------------------ The VDA Client archive contains a reference script for SRSS. This script '/opt/sun-vda/bin/vda-kiosk.sh' invokes the VDA Client based on the given session token. The script is written in such a way that it can be executed for smartcard and non-smardcard sessions. In case of an inserted smartcard the script tries to retrieve a user-id based on the smartcard token. This is done through the script 'vda-user.sh'. In the reference implementation the script searches within the Sun Ray Datastore, but of course this could also be an LDAP or Active Directory based lookup. The '/opt/sun-vda/bin/vda-kiosk.sh' script needs to be registered through the standard mechanisms as a CAM session script. Note: Make sure that the script is marked as 'critical' and that it is the only CAM X client. ------------------------------------------------------------ Example script for SGD Windows Terminal Sessions ------------------------------------------------------------ The VDA Client archive contains a reference script for SGD. This script is located in '/opt/sun-vda/bin/vda-wcpwts.exp'. The script needs to be copied to the '/opt/tarantella/var/serverresources/expect' folder. You can then define a new windows application within SGD Object Manager and assign the script as *Login Script* on the advanced settings page. Also make sure that this application is not resumable and offers only a single session at max. More is anyway not possible for Windows XP based hosts. The only lines that differ from the standard script 'wcpwts.exp' are: ##### EXTENSION FOR VMWARE set IpAddress [exec /opt/sun-vda/bin/i386/vda-client -s $env(TTA_HOSTNAME) -p 3809 -m $uname 2>/dev/null] if {[string length $IpAddress] > 0} { set env(TTA_HOSTNAME) $IpAddress } ##### EXTENSION FOR VMWARE Note: The script is written for the X86 platform, make sure that you adjust the path if you run it on Sparc. Note: The script assumes that a host is set for the application. This needs to be the host running Virtual Center.