Omnissa Horizon Unmanaged VDI Black Screen Issue

原文：Omnissa Horizon Unmanaged VDI Black Screen Issue — theDXT (Daniel Keer)

I recently encountered a strange issue with Omnissa Horizon (formerly VMware Horizon) that resulted in a black screen presenting to the VDI users when they logged in. When you search for this issue, you will find a lot of information about various solutions to the blank screen issue. However, none of them solved the problem I was running into.

VMware Horizon black screen on login

In a traditional VMware Horizon setup, there can be several causes for the black screen issue. If your setup is VDI VMs managed by VMware Horizon, then the black screen issue you may have is likely covered in my friend Stephen’s blog post, VMware Horizon Blank Screen.

His post did not cover my black screen issue. To replicate the problem I encountered, you need to have VDI VMs in VMware vCenter, and VMware Horizon configured not to use the VMware vCenter integration.

While having your VMware VDI VMs unmanaged by VMware vCenter in VMware Horizon is still a supported configuration, it is rare. However, there can be some edge cases where, even though your VDI VM exists in vCenter, you don’t want to let Omnissa Horizon access vCenter. My blog post, Omnissa Horizon Desktop Pool without vCenter, covers how to configure this.

The Why

The black screen issue presents itself when Omnissa Horizon does not have the integration to VMware vCenter to manage the VMware VDI VM. Due to this, a required setting in vCenter for the VDI VM is not configured when adding the VM to a desktop pool, as Horizon has no access to vCenter to make the change. That setting is called screen DMA (Direct Memory Access).

In version 6 of VMware vCenter, the default setting for screen DMA was changed to disabled by default. Screen DMA is required to enable proper streaming of the VDI desktop to the end users.

In this post, I will show you step-by-step how to enable the screen DMA setting to fix the black screen issue on a VMware Horizon VDI VM in VMware vCenter when the Omnissa Horizon integration to VMware vCenter is not used.

The Fix

Confirm The Issue

• Login to VMware vCenter and select the VDI VM experiencing the black screen issue.
• Click on Edit Settings.

• Click on Advanced Parameters.

If you are on vCenter version 7, click on VM Options, then expand Advanced, and click on Edit Configuration.

• Check and see if the attribute svga.enableScreenDMA exists.

VDI VM is missing the svga.enableScreenDMA attribute.

If the attribute svga.enableScreenDMA exists, then your black screen issue is not the same issue I ran into, and Stephen’s post VMware Horizon Blank Screen may have the fix you need.

If the attribute svga.enableScreenDMA does not exist, your black screen issue is likely the same one I encountered.

Add The Attribute

• Shut down the VDI VM.
• Click on Edit Settings.

• Click on Advanced Parameters.

If you are on vCenter version 7, click on VM Options, then expand Advanced, and click on Edit Configuration.

• Add the Attribute svga.enableScreenDMA with the Value TRUE.

If you are on vCenter version 7, click on Add Configuration Params, then enter the Name as svga.enableScreenDMA with the Value TRUE.

* Power On the VDI VM.

The black screen issue should now be resolved for your VMware Horizon VDI VM that is unmanaged by VMware vCenter.

VMware Horizon black screen on login fixed.

If you want to read more about manually enabling screen DMA, you can read the Omnissa documentation about it here.

What "unmanaged by vCenter" actually means in Horizon

Horizon has two ways to own a desktop pool. With the vCenter integration, Horizon talks to vCenter over its API: it clones from a parent image, customises the guest, powers machines on and off, and — critically — writes the VMX settings it needs before a desktop is ever handed to a user. Without the integration, the pool is still a supported configuration, but Horizon has no API path into vCenter, so it can only work with what already exists on the VM. Everything Horizon would normally set for you has to be set by hand, once per VM, or once on the template if you build it correctly in the first place.

That is the entire root cause of this black screen. The pool works, the agent registers, the session is brokered, and then the user is presented with a black window, because the one setting the display path depends on was never written into the VMX.

How to tell this black screen apart from the others

"Black screen on Horizon login" is a category, not a diagnosis. Before you touch anything, decide which of these you are actually looking at.

The tell-tale for the unmanaged case is uniformity: every machine in the pool, every protocol, every client, no error anywhere in the Horizon console, and a guest that is clearly running because you can see it alive on the console tab. If the picture is uneven, look somewhere else first.

What screen DMA is, and why the symptom is a black screen

Screen DMA (Direct Memory Access) lets the virtual SVGA device move frame data through shared memory instead of forcing the guest driver and the hypervisor to copy every frame through a synchronised, CPU-driven path. With DMA enabled, the virtual graphics device can hand buffers to the host in bulk; with it disabled, the streaming path that Blast and PCoIP depend on has nothing efficient to read from, and the session comes up black even though the guest OS, the agent and the connection broker are all perfectly healthy.

VMware changed the default in vCenter 6: svga.enableScreenDMA is set to FALSE by default on new VMs. In the managed case, Horizon writes TRUE into the VMX as part of its pool workflow, which is exactly why the problem is invisible in a normal deployment. In the unmanaged case nobody writes it, so the VM keeps the disabled default and the desktop streams black.

Two consequences are worth remembering. First, on an affected VM the attribute is usually not present at all rather than present and FALSE, so do not expect to find it and flip it — you will be adding it. Second, it can only be changed while the VM is powered off; an advanced-setting edit made against a running VM will appear to save and then quietly not take effect.

Applying it to one VM outside the GUI

If you prefer the shell, or you are scripting a rebuild, the same change is a single VMX entry. The value is a string, and case matters on some builds, so write it exactly as Horizon would.

# on the ESXi host, with the VM powered off
vim-cmd vmsvc/getallvms
vim-cmd vmsvc/power.off 42

# check, then add the flag to the .vmx directly
grep -i enableScreenDMA /vmfs/volumes/datastore1/VDI-01/VDI-01.vmx
echo 'svga.enableScreenDMA = "TRUE"' >> /vmfs/volumes/datastore1/VDI-01/VDI-01.vmx

# reload the VMX and power back on
vim-cmd vmsvc/reload 42
vim-cmd vmsvc/power.on 42
vim-cmd vmsvc/get.config 42 | grep -i enableScreenDMA

Editing the VMX file directly is fine on a standalone host, but remember that the edit lives in the file, not in vCenter's inventory cache. If the VM is reconfigured through vCenter without a reload, the two views can disagree, so always confirm with vim-cmd vmsvc/get.config after the power-on rather than trusting the file you just edited.

Rolling it out across a whole pool with PowerCLI

Connect-VIServer vcsa.lab.local

# Which VMs in the pool are missing the attribute?
$pool = Get-VM -Name "VDI-*"
$pool | Select-Object Name, @{N='ScreenDMA';E={
    (Get-AdvancedSetting -Entity $_ -Name 'svga.enableScreenDMA').Value
}} | Format-Table -AutoSize

# Apply it to every VM that needs it
foreach ($vm in $pool) {
    if ($vm.PowerState -ne 'PoweredOff') {
        Shutdown-VMGuest -VM $vm -Confirm:$false
        while ((Get-VM $vm).PowerState -ne 'PoweredOff') { Start-Sleep 5 }
    }
    New-AdvancedSetting -Entity $vm -Name 'svga.enableScreenDMA' `
        -Value $true -Confirm:$false -Force
    Start-VM -VM $vm
}

The -Force switch matters. PowerCLI will happily create a setting that does not exist, but on one that does exist it needs to be told to overwrite, otherwise the cmdlet prompts and a non-interactive run stalls. Run the check query before and after: you want a table that goes from blank to TRUE before you release the pool back to users.

Doing it through the vSphere API

# Reconfigure the VMX through the vSphere REST API
curl -k -u 'svc-horizon@vsphere.local:<password>' \
  -X PATCH https://vcsa.lab.local/api/vcenter/vm/vm-1042/settings \
  -H 'Content-Type: application/json' \
  -d '{"extra_config": {"svga.enableScreenDMA": "TRUE"}}'

# Confirm what the VM actually carries after the change
curl -k -u 'svc-horizon@vsphere.local:<password>' \
  https://vcsa.lab.local/api/vcenter/vm/vm-1042/settings | \
  jq '.extra_config["svga.enableScreenDMA"]'

Whatever route you take, the setting has to end up on the golden image as well. Fixing live VMs rolls the change forward only until the next recompose or refresh. A template that lacks the attribute re-breaks the pool at the next image update, and the symptom then looks like a regression when it is really a build error that was deferred.

Verifying that the fix really landed

• The VM reports svga.enableScreenDMA = TRUE in its advanced parameters, and you re-ran the query after the power-on rather than before it.
• A test user gets a rendered desktop rather than a black window, on at least two different client types.
• The Blast or PCoIP session shows non-zero bandwidth and frame counts in the Horizon Help Desk tool while the user is working.
• The golden image carries the same attribute, so the next recompose keeps it.

# From a Horizon connection server, confirm sessions and protocol
vdmadmin -L -b -server cs01.lab.local

# Guest side: confirm the agent and the display driver are present
"C:\Program Files\VMware\VMware View\Agent\bin\vdmagent.exe" -status

Do not stop at "it works for me". The change is only proven when it survives a recompose of one machine and a successful logon from the client type that reported the fault.

If the attribute is already TRUE and the screen is still black

Once svga.enableScreenDMA is confirmed present and set, the remaining black-screen causes on an unmanaged pool are worth checking in this order:

• Agent registration. The desktop shows as unavailable, or the session lands on the wrong machine. Check the agent's connection to the connection server, the pool assignment and the machine's DNS records.
• Display protocol selection. If the pool is set to Blast but the client only negotiates PCoIP, or the reverse, the handshake can complete and still present nothing. Force one protocol for a test.
• Graphics settings on the VM. 3D rendering, video memory size and the SVGA driver version in the guest all interact with the DMA path. A guest without the current VMware Tools display driver is a common culprit.
• Customisation and identity. On an unmanaged pool the guest is often customised by hand, so a duplicated SID, wrong hostname or stale sysprep state can leave the desktop half-built and black.
• Firewall between client and UAG. A Blast session that cannot reach the secure gateway gives an empty window rather than an error, especially with thin clients.

Design notes for unmanaged pools

If you deliberately run desktops outside vCenter integration, treat the VMX as part of your image specification rather than an afterthought. Record every attribute Horizon would normally write — screen DMA among them — in the build document, assert them in your template, and check them as part of image validation before a pool is published. That one habit converts a class of "mystery black screen" incidents into a build check that fails loudly at the right time.

Related reading on this site: building an Omnissa Horizon desktop pool without vCenter, Horizon GPO templates, configuring the UAG with Horizon and ESXi vSwitch, port groups and teaming.