[API]How to successfully logoff users in Horizon

One of the things that annoy me about the Horizon admin interface is the fact that if you give a session the logoff command that this only works if the user is active aka when the desktop is not locked. With the api’s though (and Andrew implemented this in the helpdesk fling) it is possible to force a logoff. Let’s look at the available method’s first.

So we have a logoff and logoffForced. But there are also the logoffsessions and LofoffSessionsForced, I guess those let you logoff multiple sessions. this is what the extensiondata says about them.

So for the singular method’s we need a single id and for the sessions we need an array of ids. At first I will use get-hvglobalsession (yes, this works against sessions in other pod’s in a cloud pod architecture as well!) to get the id’s to show how it works. I have 5 sessions running from my desktop

$services1.Session.Session_Logoff((get-hvglobalsession | select -first 1).id)

Damn locked, let’s force this bastard from his desktop.

$services1.Session.Session_LogoffForced((get-hvglobalsession | select -first 1).id)

Aaaand it’s gone

And to show that it works I had to make sure the first session wasn’t locked.

And now the big bang fuck all of you!

$services1.Session.Session_LogoffSessionsForced((Get-HVGlobalSession).id)

As you can see one of my users was a but slow in logging off (nested esxi with only a couple vcpu’s for that one) I have also created a script that asks for the user whom you want to logoff and which session you want to logoff in case they have multiple. It’s not the cleanest code that I have written but it works 🙂

$hvserver1=connect-hvserver servername -user user -domain domain -password passwords
$Services1= $hvServer1.ExtensionData

$username= Read-Host "Which user do you want to logoff? (no wildcards needed, part of the name is enough)"

$queryService = New-Object VMware.Hv.QueryServiceService
$userdefn = New-Object VMware.Hv.QueryDefinition
$userdefn.queryEntityType = 'ADUserOrGroupSummaryView'
$userfilter1= New-Object VMware.Hv.QueryFilterContains
$userfilter1.membername='base.name'
$userfilter1.value=$username
$userfilter2= New-Object VMware.Hv.QueryFilterEquals
$userfilter2.membername='base.group'
$userfilter2.value=$False
$userfilter=new-object vmware.hv.QueryFilterAnd
[email protected]($userfilter1, $userfilter2)
$userdefn.filter=$userfilter
$users=($queryService.QueryService_Create($Services1, $userdefn)).results

$menu = @{}
for ($i=1;$i -le $users.count; $i++){ 
    Write-Host "$i. $($users[$i-1].base.name)" 
    $menu.Add($i,($users[$i-1].id))
}
[int]$ans = read-host "Please select the correct user"
$user=$menu.Item($ans)

$GlobalSessionQueryService = new-object VMware.Hv.GlobalSessionQueryServiceService
$sessionfilterspec=new-object vmware.hv.GlobalSessionQueryServiceQuerySpec
$sessionfilterspec.user=$user
$sessions=($GlobalSessionQueryService.GlobalSessionQueryService_QueryWithSpec($services1, $sessionfilterspec)).results

$menu = @{}
for ($i=1;$i -le $sessions.count; $i++){ 
    Write-Host "$i. $($sessions[$i-1].namesdata.basenames.MachineOrRDSServerName)" 
    $menu.Add($i,($sessions[$i-1].id))
}
[int]$ans = read-host "Please select the correct VDI Desktop"
$session=$menu.Item($ans)

$Services1.Session.Session_Logoffforced($session)
$queryService.QueryService_DeleteAll($services1)

This script forces the logoff for the sessions since I haven’t been able yet to find where the desktop status (locked or not) is visible.

Updates to the VMware Horizon Helpdesk fling

Today a new version has been released of the VMware Horizon Helpdesk fling by Andrew Morgan. One big change is that the Helpdesk license isn’t required anymore so at least a part of the functionality is available to owners of advanced or standard Horizon licenses.

the entire changelog:

Version 1.4.0.1

  • No longer requires a helpdesk license! Yay!
  • Added the ability to interact with vCenter machines
  • Added the ability to open vCenter VM consoles
  • Added the ability to perform bulk machine actions
  • Added the ability to perform refresh / recompose tasks directly from helpdesk.
  • Fixed performance issues with multiple windows open (see single instance).
  • Fixed a crash when logon durations could not be accessed.
  • Added polling to allow logon durations to be received if notavailable when the session page is requested.
  • Fixed a crash in the ending of processes.
  • Fixed a metric ton of bugs with delegated administration.
  • Fixed a memory leak in the tray icon menu, of all places.
  • Removed the logon page graphic as it was to much of a pain to change it’s colour when changing themes
  • Fixed some layout issues when changing themes.
  • Removed empty sites from the viewon the change pod tray menu.
  • Added preliminary support for Horizon 7.9.

 

Let’s look into some of the new options (will do the options without the helpdesk license last)

Added the ability to interact with vCenter machines 

From the pool view you’ll see an extra button for vCenter actions

And that will give these options

These all speak for themselves in functionality.

Added the ability to open vCenter VM consoles 

Open VM console will give an popup that asks for vCenter credentials.

Hit logon and a vrmc client should start if it’s installed

Added the ability to perform bulk machine actions 

The vCenter actions above can be done against multiple vm’s but also the various actions from View itself

Added the ability to perform refresh / recompose tasks directly from helpdesk. 

No longer requires a helpdesk license! Yay! 

when you use the std license the biggest difference is that you can’t view any specifics inside sessions since that’s all limited to the helpdesk license.

The VMware Labs flings monthly for May 2019

Originally I created this post with only 2 updated and one new fling. Some engineers though added two more new flings so 3 new ones and 2 have received an update. The new ones are the Distributed Trust Incident Reporting fling, vRealize Build Tools and Cloud Automation Services SDK for Python. while the Horizon Toolbox and Horizon Migration Tool have received updates.

New Releases

vRealize Build Tools

vRealize Build Tools provides tools to development and release teams implementing solutions based on vRealize Automation (vRA) and vRealize Orchestrator (vRO). The solution targets Virtual Infrastructure Administrators and Solution Developers working in parallel on multiple vRealize-based projects who want to use standard DevOps practices.

This Fling is focused on code quality, code reusability, unit testing, dependency management and parallel releases of vRealize projects. In practice, it is a set of Maven extensions, packaged in a Maven repository format, that support the use of IDE (via Maven) and CLI to develop, test and deliver vRA and vRO-based solutions. It includes a vRO plug-in that exposes autocomplete information for standard and third-party scripting objects and actions and CLI that can deploy packages to vRO and vRA via the standard APIs.

Cloud Automation Services SDK for Python

The Cloud Automation Services SDK for Python is a set of Python classes to simplify automation against several aspects of the Cloud Assembly, Service Broker, and Code Stream API when using Python.

Note: The github repo will be public soon!

 

Distributed Trust Incident Reporting

The Distributed Trust Incident Reporting fling is an  open source security incident tracker.

Security incidents are important to track so that all parties know the status of a breach and can respond in concert and with appropriate speed. Current methods to track incidents are generally paper-based manual processes. More recent systems are based on a centralized database with some web interface to interact with the record and response tracking.

We propose that this does not work well enough in the scenarios where:

  • security incidents may affect more than a single entity
  • where more than one entity must respond to an incident
  • some or all entities have no trust in the others
  • no party can or will be responsible for hosting the full system

For example, a security breach in the supply chain for a food manufacturer could result in several retail businesses with products on shelf that contain a pathogen. Current methods of notifying the proper authorities require a phone tree to call all the correct parties which then react as individuals or local committees. In addition the incident must either be initially submitted to each entity separately or one entity must take responsibility to notify the others.

This Fling:

  • allows all parties (e.g. retail, governmental, public) to see the incident via a single report transaction
  • allows all parties to respond in concert as required
  • allows automated systems to report incidents
  • allows transparency across all organizations

Updated flings

Horizon Toolbox

The Horizon toolbox is an extension to the Horizon Admin Console giving all kinds of user and session information. It is no replacement for the Horizon Helpdesk (or the fling).

Changelog

May 28, 2019, 7.8.0

  • Fix some incompatible issues
  • Only support Horizon View 7.7 & 7.8

Horizon Migration Tool

The Horizon Migration Tool helps you migrating from Citrix to an On-Prem Horizon Environment.

Changelog

Version 3.0.2

  • Updated the binary package and the document accordingly

[API’s] Getting session counts (incl performance comparison)

One of my customers asked the question if it is possible to get a quick sessioncount for a script that they can run very often for a correct logging of license usage. While this could easily be done by grabbing all the sessions I thought this could be a slow process. I remembered though that the first release of the vmware.hv.helper module had a function called get-podsessions that only returned a sessioncount. I decided to see what was used for this. By going back in time at github I found that the GlobalSessionQueryService was still used but with the GlobalSessionQueryService_GetCountWithSpec method. It needs the service and a spec of the type VMware.Hv.GlobalSessionQueryServiceCountSpec.

the spec itself can hold one of the many options to get a count for

As you can see there is a globalentitlement property that needs to be set using the id so let’s grab that one first.

$queryService = New-Object VMware.Hv.QueryServiceService
$defn = New-Object VMware.Hv.QueryDefinition
$defn.queryEntityType = 'GlobalEntitlementSummaryView'
$globalentitlements = ($queryService.QueryService_Create($Services1, $defn)).results

I will use the first globalentitlement to grab the sessioncount

$globalentitlement=$globalentitlements | select -first 1
$globalsessionqueryservice_helper = New-Object VMware.Hv.GlobalSessionQueryServiceService  
$count_spec = New-Object VMware.Hv.GlobalSessionQueryServiceCountSpec  
$count_spec.globalentitlement=$globalentitlement.id
$sessioncountperglobalentitlements=$globalsessionqueryservice_helper.GlobalSessionQueryService_GetCountWithSpec($services1,$count_spec)

As you can see we actually get a count per pod so to get all the counts from all pods from all globalentitlements I have created a script with a couple foreach’s.

$hvserver1=connect-hvserver SERVERNAME
$services1=$hvserver1.extensiondata
$queryService = New-Object VMware.Hv.QueryServiceService
$defn = New-Object VMware.Hv.QueryDefinition
$defn.queryEntityType = 'GlobalEntitlementSummaryView'
$globalentitlements = ($queryService.QueryService_Create($Services1, $defn)).results
$queryservice.QueryService_DeleteAll($services1)
[email protected]()


foreach ($globalentitlement in $globalentitlements){
  $globalsessionqueryservice_helper = New-Object VMware.Hv.GlobalSessionQueryServiceService  
  $count_spec = New-Object VMware.Hv.GlobalSessionQueryServiceCountSpec  
  $count_spec.globalentitlement=$globalentitlement.id
  $sessioncountperglobalentitlements=$globalsessionqueryservice_helper.GlobalSessionQueryService_GetCountWithSpec($services1,$count_spec)
  foreach ($sessioncountperglobalentitlement in $sessioncountperglobalentitlements){
    $pod=$services1.pod.pod_get($sessioncountperglobalentitlement.id)
    $sessioncount+= New-Object PSObject -Property @{
      "Global_Entitlement_Name" = $globalentitlement.base.displayname;
      "Pod_Name"=$pod.displayname
      "Pod_Sessioncount" = ($sessioncountperglobalentitlement | select-object -expandproperty count);
      "Site_Name"= ($services1.site.site_get($pod.site)).base.Displayname;
    }
  }
}
 return $sessioncount | select-object Global_Entitlement_Name,Pod_Name,Site_Name,Pod_Sessioncount

The W10_MGMT global entitlement only has a pool in pod1 so even though the pod doesn’t have a pool inside the global entitlement it will still return a sessioncount.

Performance

I also decided to time it but in my small environment it took 3 seconds and 3 of those where for connecting to the connection server. If I removed the connecting part it was 0.7 seconds.

Measure-Command {D:\scripts\dev\session_count.ps1}

Back at the customer I decided to compare this against dumping all global sessions, this will give some better data since it has a couple more sessions in it (around 3500 at the moment of testing)

The script I used for getting all global sessions is the code that I used for the get-hvglobalsession in the vmware.hv.helper module

$query_service_helper = New-Object VMware.Hv.GlobalSessionQueryServiceService
$query=new-object vmware.hv.GlobalSessionQueryServiceQuerySpec

$SessionList = @()
foreach ($pod in $services1.Pod.Pod_List()) {
  $query.pod=$pod.id
  $queryResults = $query_service_helper.GlobalSessionQueryService_QueryWithSpec($services1, $query)
  $GetNext = $false
  do {
    if ($GetNext) { $queryResults = $query_service_helper.GlobalSessionQueryService_GetNext($services1, $queryResults.id) }
    $SessionList += $queryResults.results
    $GetNext = $true
  } while ($queryResults.remainingCount -gt 0)
    $query_service_helper.GlobalSessionQueryService_Delete($services1, $queryresults.id)

}
return $sessionlist

Screenshots from the timing:

so the getcountwithspec method is about 2.5 seconds faster but the data in the globalsession is way more extensive and usable for all kinds of management overviews.

[API]Resetting Desktops

This is the first post in a series of shorts that I will be posting about various methods that you can use with the VMware Horizon API’s. This time it will be about resetting desktops. When looking at the API Explorer you’ll see that there are two ways do do this from the machine service.

So the first is for a single VDI desktop and the latter for multiple.

First we need to get a list of vm’s I will be using the machines in pod1pool02 as victims for this post.

$queryservice=new-object VMware.Hv.QueryServiceService
$defn=New-Object VMware.Hv.QueryDefinition
$defn.QueryEntityType="MachineNamesView"
$filter=new-object VMware.Hv.QueryFilterContains
$filter.MemberName='base.name'
$filter.Value="Pod1Pool2"
$defn.filter=$filter
$results=($queryservice.QueryService_Query($services1, $defn)).results

with this result:

From this we’ll make a variable with all of them and one with a single one

$singlevm=$results | select-object -first 1
$multiplevms=$results

Before I will reset the single VM I will show the state of all the vm’s.

($queryservice.QueryService_Query($services1, $defn)).results.base.basicstate

And now let’s reset the vm.

$services1.machine.machine_reset($singlevm.id)

Since this is an instant clone you’ll see provisioned and not reset. Now let’s reset the rest as well.

$services1.Machine.Machine_ResetMachines($multiplevms.id)

And this method will work for all managed vdi desktops full, linked or instant clones.

vExpert 2019? check! Why does it matter for me?

Last week whilst on holiday in Disneyland Paris I received the email every aspiring and existing vExpert was waiting for.

This means that for the fourth consecutive year I have been named a vExpert.

What is a vExpert? (or any other community award like NutanixNTC)

Per the vExpert site the criteria for becoming a vExpert are:

If you are interested in becoming a vExpert the criteria is simple. We are looking for IT Professionals who are sharing their VMware knowledge and contributing that back to the community. The term “giving back” is defined as going above and beyond your day job. There are several ways to share your knowledge and engage with the community. Some of those activities are blogging, book authoring, magazine articles, CloudCred task writing, active in facebook groups, forum (VMTN as well as other non VMware) platforms, public speaking, VMUG leadership, videos and so on.

I totally agree on the above description, for me a real vExpert shares knowledge in one of many ways. But blogging, speaking, tweeting, podcasting, writing isn’t the only way. We answer questions online and offline and if we don’t know the answer than we have an awesome backstop to ask questions called the vCommunity. Is it technical only you might ask? Absolutely not! I have seen hundreds of job changes by now because of the vCommunity. People were helped with personal issues, hell even home deco tips and tricks are shared. I think it’s just in our nature to help one another.

Yes it’s also about advocacy but the sharing of information is all voluntary. Do you want to tweet or blog about stuff? No-one will force you but they do appreciate it if you share news.

One things advocacy program members are also good at is providing feedback. Not only to the software vendor but if you want some feedback about a possible blog post, presentation idea, news item or piece of hardware most of us will give you that feedback. Just be prepared because we can be brutally honest if it sucks!

But there are over 1700 vExperts, is it about quantity or Quality?

This is a point where I personally disagree on how the program is run. I have the idea that they want to grow just to grow and for me the selection criteria could be tightened quite a bit. I value growing but please do it by adding quality. If you look at smaller programs like some of the vExpert subprograms or others like the VMware EUC Champions or Nutanix NTC’s they are most times better managed, get more briefings, nda information and events. Not that the vExpert program is managed badly or doesn’t have an awesome party at VMworld but things just get more complicated at this scale.

But does the program still matter to you?

It certainly does! Through the vExpert program I have managed to grow personally and professionally but also made boatloads of friends online and offline. All the extra’s like licenses, swag and things like that are fun but nothing is as good as knowing you have some great people who are always happy to help you in any way possible!

I want in too, how do I become a vExpert?

Currently the sign ups are closed but until they open again (probably somewhere in June) you can start doing some things already:

  • Start a blog, most people do it as their own knowledge base. Write about what you experienced at work or a customer so you won’t forget it for next time.
  • Get a twitter account, follow a bunch of people and interact with them.
  • Help others out in places like VMTN, Reddit.
  • Present at a vmug or at your employer about things that could be interesting to others. This could be as basic as explaining how your homelab is setup.

If you need help or feedback on your blog or need help on how to build your presentation I am always happy to provide my 2 cents.

When the sign ups are opened again contact your local vExpert pro with how to tackle the application form. You can also ask me or any other vExpert you might know personally.

The Horizon Helpdesk Utility fling version 1.3.3.1 has been released

Last august I posted about a then new fling: the Horizon Helpdesk Utility While that release was great Andrew added a whole lot more of awesomeness.

Changelog

Version 1.3.3.1

  • Removed machine listings from session view (overkill)
  • Improved Environment view to include metrics on all connected infrastructure:
    • vSphere
    • Hosts
    • Datastores
    • Remote Pods
    • Events
    • Problem Machines
  • Added repeated queries for logon breakdown if missed on first instance
  • Added event query support for logon breakdown
  • Added events view for Farm and Desktop pools
  • Added inbuilt find / search to users / machines in pool views
  • Added support for multiselect in pool / farm views
  • Added graph / chart views of machines / sessions and problem machines on the environment overview
  • Added a pod switcher to the environment overview
  • Added a global search to the environment overview
  • Added support for Pod Jumping.
    • the ability to jump to a pod on demand
    • the ability to jump to a pod a session belongs to
  • Added support for an architecture view of Desktop Pools
  • Added support for an architecture view of Farms
    • Enhanced view of servers load evaluator value
  • Added bulk user tasks via pool or farm views:
    • Bulk messaging
    • Bulk log off
    • Bulk disconnect
    • Bulk reset
    • Bulk restart
  • Added support for a local pod view (AKA environment view):
    • Connection servers
    • Farms
    • Desktop pools
  • Added documentation (finally)
  • Added MSI installation support
  • Added a start time column to user sessions (this will persist as a preference)

Let’s take a look some of the new goodies, the first change is that you now get a proper connection alert:

The POD switcher

The show environment button will show you the environment as seen from the pod you are currently connected to. A lot of tabs with health information about those components and some counts on sessions, machines and problem machines.

The address behind Connected To will send you to the Horizon Admin Console, this might sound small but I like it!

When you open a pool this is what you see

All of the events for that pool and yes you can sort & filter them!

Some details for a users session

If there are multiple sessions (unlike in my lab) you can select them and mass send messages or do other actions against them.

The view for an RDS farm

So yes the best Horizon helpdesk tool ever just got improved by a 100%!

 

 

 

Applying Golden Images for VDI & RDS cloned pools using the Horizon View API’s

Recently I came up with the idea to create a script to apply new Golden Images against the various types of desktop pools and farms that we have in Horizon View. This was something that I thought was not available from the vmware.hv.helper module but after some research I did find that it it available from the module by using start-hvpool and start-hvfarm. No those are not the best names for the functions in my opinion. This wouldn’t stop me for creating this post though on how to apply the images using api’s only since the module uses mapentries and I still hate those. I will cover full clones and defining a new image without recomposing in a next post since that requires updating the pools.

Let’s take a look at the api explorer on what is needed to recompose or push an image.

 

The DesktopPushImageSpec for instant clones has a comparable setup with some nuance differences.

For RDS farms the linked clones spec is equal to the desktop spec but for instant clones there’s a rather big difference but I will cover that later on.

So the common steps for most types of applying the golden image are:

  • Selecting the Desktop Pool or RDS Farm
  • getting the id for the vcenter or datacenter where the parent VM lives
  • getting the id of the Parent VM
  • getting the id of the snapshot to use
  • getting the id’s of the machines in the desktop pool (Linked Clones only)
  • Select date & time for the recompose or imagepush (if required)
  • combine the above info into a spec to recompose or imagepush
  • Apply the recompose or ImagePush

Each step uses information from the step above it.

Selecting the Desktop Pool or RDS Farm

This can be done using queries. For desktops we user the desktopsummaryview definition and for farms farmsummaryview.

$poolname="pod02_LC"
$queryservice=New-Object VMware.Hv.QueryServiceService
$defn=new-object VMware.Hv.QueryDefinition
$defn.QueryEntityType='DesktopSummaryView'
$defn.Filter= New-Object VMware.Hv.QueryFilterEquals -property @{'MemberName'='desktopSummaryData.name'; 'value'=$poolname}
$desktoppool=($queryservice.QueryService_Create($services1, $defn)).results

And for a farm

$farmname="rds_IC"
$queryservice=New-Object VMware.Hv.QueryServiceService
$defn=new-object VMware.Hv.QueryDefinition
$defn.QueryEntityType='FarmSummaryView'
$defn.Filter= New-Object VMware.Hv.QueryFilterEquals -property @{'MemberName'='data.name'; 'value'=$farmname}
$farm=($queryservice.QueryService_Create($services1, $defn)).results

getting the id for the vcenter or datacenter where the parent VM lives

For desktops this is a property of the $desktoppool object we have now

$desktopppoolvcenterid=$desktoppool.desktopsummarydata.VirtualCenter

For automated farms we need a small extra step since it is not property for the summary data we we can get it by doing a farm_get with the id we received from the query

$farmvcenterid=($services1.Farm.Farm_Get($farm.id)).automatedfarmdata.VirtualCenter

getting the id of the Parent VM

Using the vcenterid as done below we are able to list all vm’s in the vCenter that might be a Golden Image using

$services1.BaseImageVm.BaseImageVm_List($desktopppoolvcenterid)

You might be able to see it but this gives a list of all VM’s in the vCenter, sadly there is no query for this yet even though that would be really useful. If you know the exact name you can select on that but if you look at the IncompatibleReasons property there’s info to filter (if you want to create a menu for example)

$baseimagevmlist=$services1.BaseImageVm.BaseImageVm_List($desktopppoolvcenterid)
$baseimagevmlist.IncompatibleReasons

InUseByDesktop is a usable one for instantclones. I don’t know why InUseByLinkedCloneDesktop doesn’t give any true values even though I have one pool with linked clones, viewcomposerreplica does work. I have filtered this on some of the more obvious ones and end up with both my golden images for Windows 7 & Server 2016

$baseimagevmlist |where {$_.IncompatibleReasons.InUseByDesktop -eq $false -and $_.IncompatibleReasons.InstantInternal -eq $false -and $_.IncompatibleReasons.ViewComposerReplica -eq $false}

I will do it easy and select on the name for now

$Desktopbaseimagevm=$baseimagevmlist | where {$_.name -eq "GI_H72"}
$farmbaseimagevm=$baseimagevmlist | where {$_.name -eq "rds_template"}

getting the id of the snapshot to use

With the baseimagevmid we can utilize the baseimagesnapshot method to get the id for the snapshot.

$desktopsnapshotlist=$services1.BaseImageSnapshot.BaseImageSnapshot_List($Desktopbaseimagevm.id)
$farmsnapshotlist=$services1.BaseImageSnapshot.BaseImageSnapshot_List($farmbaseimagevm.id)

In this there is also an IncompatibleReasons property but that doesn’t give a lot of information so we’ll need to filter on name.

$desktopLCsnapshot=$desktopsnapshotlist | where-object {$_.name -eq "gi_linked"}
$desktopICsnapshot=$desktopsnapshotlist | where-object {$_.name -eq "snap_gi"}
$farmsnapshot=$farmsnapshotlist | where-object {$_.name -eq "gi_rds_2016"}

getting the id’s of the machines in the desktop pool

As you’ll see later in the spec there’s a requirement to list the machine id’s for the pool if you want to do a recompose. These can be grabbed by doing a query

$queryService = New-Object VMware.Hv.QueryServiceService
$defn = New-Object VMware.Hv.QueryDefinition
$defn.queryEntityType = 'MachineSummaryView'
$defn.filter=New-Object VMware.Hv.QueryFilterEquals -property @{'memberName'='base.desktop'; 'value'=$desktoppool.id}
$QueryResults=$queryService.Queryservice_create($Services1, $defn)
$desktopmachinelist=$queryresults.results

For Linked Clone RDS farms you ned to use the QueryEntityType of RDSServerSummaryView but since I don’t have those in my lab I can only show the theory

$queryService = New-Object VMware.Hv.QueryServiceService
$defn = New-Object VMware.Hv.QueryDefinition
$defn.queryEntityType = 'RDSServerSummaryView'
$defn.filter=New-Object VMware.Hv.QueryFilterEquals -property @{'memberName'='base.desktop'; 'value'=$farm.id}
$QueryResults=$queryService.Queryservice_create($Services1, $defn)
$farmmachinelist=$queryresults.results

Settings date and time for the action

It’s not required to set a date and but is very usable if you want to schedule an action. Please be aware that this is based on us format for day and time so mm-dd-yyyy otherwise I would have scheduled it for august.

$datetime=[DateTime]"02-08-2019 10:00:00AM"

The [DateTime] converts the string that follows it to a variable of the type day and time

combine the above info into a spec to recompose or imagepush.

To build the spec we first need to declare a new object with new-object vmware.hv.DesktopRecomposeSpec please be aware that for this name you need to look at the data object in the API explorer and not the class.

$desktoprecomposespec=new-object vmware.hv.DesktopRecomposeSpec
$desktoprecomposespec.ParentVm=$desktopbaseimagevm.id
$desktoprecomposespec.Snapshot=$desktopLCsnapshot.id
$desktoprecomposespec.StartTime=$datetime
$desktoprecomposespec.LogoffSetting="WAIT_FOR_LOGOFF"
$desktoprecomposespec.StopOnFirstError=$true
$desktoprecomposespec.Machines=$desktopmachinelist.id

For the instant clone image push there’s an extra layer required for the settings

$desktopimagepushspec=new-object VMware.Hv.DesktopPushImageSpec
$desktopimagepushspec.settings=new-object vmware.hv.DesktopPushImageSettings
$desktopimagepushspec.ParentVm=$desktopbaseimagevm.id
$desktopimagepushspec.snapshot=$desktopICsnapshot.id
$desktopimagepushspec.settings.StartTime=$datetime
$desktopimagepushspec.settings.LogoffSetting="WAIT_FOR_LOGOFF"
$desktopimagepushspec.settings.StopOnFirstError=$true

The recompose for a linked clone rds farm is similar to the desktop linked clone.

$farmrecomposespec=new-object vmware.hv.farmRecomposeSpec
$farmrecomposespec.ParentVm=$farmbaseimagevm.id
$farmrecomposespec.Snapshot=$farmLCsnapshot.id
$farmrecomposespec.StartTime=$datetime
$farmrecomposespec.LogoffSetting="WAIT_FOR_LOGOFF"
$farmrecomposespec.StopOnFirstError=$true
$farmrecomposespec.Machines=$farmmachinelist.id

For RDS instant clone farms the pushing of a new image is part of the maintenance schedule that can be done immediate or recurring. I will do the recurring option for now since rds hosts needs to be refreshed every once in a while anyway. There’s some options inside the settings that are explained in the api explorer.

$farmmaintenancespec=new-object vmware.hv.FarmMaintenanceSpec
$farmmaintenancespec.recurringMaintenanceSettings=new-object vmware.hv.FarmRecurringMaintenanceSettings
$farmmaintenancespec.imageMaintenanceSettings=new-object vmware.hv.FarmImageMaintenanceSettings
$farmmaintenancespec.maintenanceMode="RECURRING"
$farmmaintenancespec.scheduledTime=$datetime
$farmmaintenancespec.logoffsetting="WAIT_FOR_LOGOFF"
$farmmaintenancespec.stopOnFirstError=$true
$farmmaintenancespec.recurringMaintenanceSettings.startTime="23:00"
$farmmaintenancespec.recurringMaintenanceSettings.maintenancePeriod="WEEKLY"
$farmmaintenancespec.recurringMaintenanceSettings.startInt=1
$farmmaintenancespec.ImageMaintenanceSettings.parentVm=$farmbaseimagevm.id
$farmmaintenancespec.ImageMaintenanceSettings.snapshot=$farmsnapshot.id

Apply the recompose or ImagePush

This is the easiest part of the spec’s have been build properly.

Please note that the variables for the pools I use are a bit different to show the linked and instant clone pools

$services1.Desktop.Desktop_Recompose($linkedclonepool.id,  $desktoprecomposespec)
$services1.Desktop.Desktop_SchedulePushImage($instantclonepool.id, $desktopimagepushspec)
$services1.farm.Farm_ScheduleMaintenance($farm.id, $farmmaintenancespec)

No visible feedback but it’s visible from the admin console (sadly not all tasks can be gotten from the api’s yet 🙁 )

That’s it for now but expect future posts about full clones, setting a default image for linked clones without recompose and maybe a complete script that does it all for you.

Setting maintenance mode for Linked Clones using API’s

If you have used the VMware.hv.helper the title of this blog post might sound strange since the set-hvmachine already has a way to set maintenance mode. When Ryan Butler asked me the question this week though I didn’t think of that and dived into the api’s immediately. The machines.Machine_EnterMaintenanceMode method looked good to me and than I though of the vmware.hv.helper and noticed that with

Set-HVMachine -Maintenance ENTER_MAINTENANCE_MODE

it was also possible so set maintenance mode. The usage though made me think immediately that this was not actually using a proper api call but the update function. A quick look at the function itself confirmed this. It sets that status of the virtual machine by directly setting the status.

if ($Maintenance) {
      if ($Maintenance -eq 'ENTER_MAINTENANCE_MODE') {
        $updates += Get-MapEntry -key 'managedMachineData.inMaintenanceMode' -value $true
      } else {
        $updates += Get-MapEntry -key 'managedMachineData.inMaintenanceMode' -value $false
      }
    }
(this is just a snippet of the complete function)

If you are below version 7.5 of Horizon view it’s probably of no use to continue with the rest of this blog post. The api explorer only mentions the relevant functions since 7.5! They have been tried against 7.0.3 and 6.2 and there they don’t work.

So back to the drawing board it was and I needed to look at the API explorer, there are 4 relevant methods for maintenance mode.

As usual there are methods for multiple machines that use an array of id’s (with machines in the name) and methods for single machines id’s (without the machines in the name).

Since I usually use instant clones these days I created a small pool with three linked clones. With get-hvmachine I can show you their names and state.

(get-hvmachine -pool pod2_linked).base | select-object name,basicstate

Since I know that get-hvmachine will already give you the id of a machine it’s easy to do a one liner to set one system in maintenance mode.

 $services1.Machine.Machine_EnterMaintenanceMode((get-hvmachine -machinename p2lc001).id)

and exit maintenance mode.

 $services1.Machine.Machine_ExitMaintenanceMode((get-hvmachine -machinename p2lc001).id)

And the entire pool?

$services1.Machine.Machine_EnterMaintenanceModemachines((get-hvmachine -pool pod2_linked).id)

And exit maintenance mode for the entire pool.

$services1.Machine.Machine_ExitMaintenanceModemachines((get-hvmachine -pool pod2_linked).id)

Okay so we now know how this works but I don’t want to use to vmware.hv.helper module for this at all because I want to be able to use a list of machines or based on part of the name. That can be done using a query. The query entitytype to use is MachineSummaryView and if you use queryfiltercontains it’s also possible to use only a part of the name for a kind of wildcard selection. Combine several of these in with queryfilteror and it gives the opportunity to select them from a list.

$connectionserver="servername"
$hvserver1=connect-hvserver $connectionserver 
$Services1= $hvServer1.ExtensionData
$machines=get-content machines.txt
$queryService = New-Object VMware.Hv.QueryServiceService
$defn = New-Object VMware.Hv.QueryDefinition
$defn.queryentitytype='MachineSummaryView'
[email protected]()
foreach ($machine in $machines) {
    $queryfiltercontains=New-Object VMware.Hv.QueryFiltercontains -Property @{ 'memberName' = 'base.name'; 'value' = $machine }    
    $filterset+=$queryfiltercontains
    }
$orFilter = New-Object VMware.Hv.QueryFilterOr
$orFilter.filters = $filterSet
$defn.filter=$orFilter
$ids=($queryService.QueryService_Create($Services1, $defn)).results
$services1.Machine.Machine_EnterMaintenanceModeMachines($ids.id)
p2lc001
p2lc003

Now I replaced the names in the txt file with only p2lc00

$connectionserver="servername"
$hvserver1=connect-hvserver $connectionserver 
$Services1= $hvServer1.ExtensionData
$machines=get-content machines.txt
$queryService = New-Object VMware.Hv.QueryServiceService
$defn = New-Object VMware.Hv.QueryDefinition
$defn.queryentitytype='MachineSummaryView'
[email protected]()
foreach ($machine in $machines) {
    $queryfiltercontains=New-Object VMware.Hv.QueryFiltercontains -Property @{ 'memberName' = 'base.name'; 'value' = $machine }    
    $filterset+=$queryfiltercontains
    }
$orFilter = New-Object VMware.Hv.QueryFilterOr
$orFilter.filters = $filterSet
$defn.filter=$orFilter
$ids=($queryService.QueryService_Create($Services1, $defn)).results
$services1.Machine.Machine_ExitMaintenanceModeMachines($ids.id)

And back into maintenance mode

So this is a nice way to manage the machines and their maintenance state. Please remember that these scripts only work against horizon 7.5 and higher.

Horizon View Api’s: back to basics part 3: Methods

Like I said in part two I wanted to do that first before going to method’s since for some methods you actually need the output from a query. I posted an example of that in the meanwhile with my post about sending messages to users. The get-hvglobalsession and get-hvlocalsession are based on queries that are used for the Session_SendMessages method of the session service.

The obvious way of finding available methods is by looking into the API Explorer.

It’s a complete list but it’s hard to find all the methods that belong to a service. It’s easier to do a get-method on a service.

$services1.connectionserverhealth | gm

So, in here we have two methods: ConnectionServerHealth_Get and ConnectionServerHealth_List. Even my wide PowerShell window is not big enough to show what’s needed to with the ConnectionServerHealth_Get method. For that we can use service.method without any brackets.

$services1.ConnectionServerHealth.ConnectionServerHealth_Get

and

$services1.ConnectionServerHealth.ConnectionServerHealth_List

The required input for the method’s is visible between the brackets. The _Get method requires an id of the type vmware.hv.connectionserverid and the list doesn’t even need an input. I will keep the first one to use for later while I run the latter one.

$services1.ConnectionServerHealth.ConnectionServerHealth_List()

A lot of these lists have information that is available on a deeper level, with a get-method everything is shown.

$services1.ConnectionServerHealth.ConnectionServerHealth_List() | gm

The ones where you see a property that has a definition that starts with vmware.hv…. has more content hidden. It is possible to access these by putting the entire line between brackets followed by .membername for example

($services1.ConnectionServerHealth.ConnectionServerHealth_List()).certificatehealth

Please be aware that this can go multiple levels deep for some methods. To avoid unneeded api calls it’s wise to declare a variable from the method and use that to access the data.

$connectionserverhealth=$services1.ConnectionServerHealth.ConnectionServerHealth_List()
$connectionserverhealth.certificatehealth

Now to show the use of the _get method I could use the id that I received from the _list method but that would be cheating. What I will do is put a list of all connectionservers into an array (even though I only have 1) and do a foreach with the _get method.

$connectionservers=$services1.ConnectionServer.ConnectionServer_List()
foreach ($connectionserver in $connectionservers){$services1.ConnectionServerHealth.ConnectionServerHealth_get($connectionserver.id)}

This is the basic usage for method’s. For some method’s a spec is required for input please take a look at this post about adding an instantclone administrator for an example. I will show some more details about that one in here. Let’s take a look at what the method requires as input.

$services1.InstantCloneEngineDomainAdministrator.InstantCloneEngineDomainAdministrator_Create

You can see that a spec is required of the type VMware.Hv.InstantCloneEngineDomainAdministratorSpec. The API Explorer will show that this actually is a bit weird one since it one contains a base.

If you click on the base you’ll see whats required in there.

These levels actually show that we need to declare multiple objects to build the actual spec. You can create the basic object with new-object objecttype

$InstantCloneEngineDomainAdministratorSpec=new-object vmware.hv.InstantCloneEngineDomainAdministratorSpec
$InstantCloneEngineDomainAdministratorSpec
$InstantCloneEngineDomainAdministratorSpec.base

As you see the base is empty and doesn’t know what data it can contain. This shows that we need to declare the object for every level where we need to enter some information.

First I tried this using the class that’s shown in the API explorer, this obviously didn’t work so I use the data object name.

$InstantCloneEngineDomainAdministratorSpec.base=new-object vmware.hv.InstantCloneEngineDomainAdministratorBase
$InstantCloneEngineDomainAdministratorSpec.base

In the link I posted above you should be able to find what’s required to create an actual instantcloneadministrator. With this I have covered most of the method’s and how they work. Please don’t assume that _list nevers needs an id or that _get always needs one because that’s not true. Sometimes it will also say ids like with my previous post about sending messages that means it needs an array of id’s most possibly generated by a query or an _list method.