VI Toolkit (for Windows)

One user has suggested we rename the VI Toolkit forum the "Ask Luc Forum", referring to Luc Deken's continuous help and support to other toolkit users. Here's a few recent highlights from the forum, with Luc making quite a few appearances.

A previous post on this blog shows how to modify VMX file settings, but some VMX file setting can't be changed in this way. Changing a VM's boot delay is a good example. If you need to configure VM boot settings, Luc shows a way this can be done, using an API specifically designed for VM boot settings.

If you're accustomed to logging into ESX and using the esxcfg-mpath command, but are looking for something that works at the VirtualCenter level, across all your ESX hosts, Hal has some code that makes it really easy to make storage path reports across all your ESX server.

Hugo shows how you can use the -expand switch of PowerShell's Select-Object cmdlet to easily display a VM's available and used disk space (assuming the VM is running VMware Tools).

If you have VMs with multiple adapters that are members of multiple port groups, Luc has some tips that make it really easy to report on which VMs are connected to which port groups.

Finally, if you're writing reports and want the results emailed to you, Luc shows an easy PowerShell script to generate email.

If you're like me, and I know I am, you spend an hour or two a day reading through RSS feeds. In fact, I found out about this really cool new script from Hal Rottenberg through my RSS reader, courtesy of Alan Renouf, even though Hal emailed me to tell me about it (I get so much mail from Hal I usually just ignore it.)

The beauty of RSS (in case you've been living under a technological rock for the past few years) is that everything comes to you, rather than the other way around. How many times a day do you really want to log into your VI to figure out what's going on anyway? In VI you can get email notifications, but this is only for alarms, in addition to being a bad idea in general. If you look through Hal's feed you can see that this tells you about everything, including things like an ominous warning from VMware Update Manager that it only has about 500 megabytes of space left. Just add it to your RSS aggregator of choice and suddenly you know everything that's going on with your VI with minimal effort.

Hal hasn't made his script public, it seems he's using it as a teaser for his upcoming book. Let's hope he hurries up, so drop him a note and tell him to stop goofing off all the time.

I often call snapshots "the silent datastore killer". When you create a snapshot, the system records the difference between the current state and the state when the snapshot was made in something called a delta file. The delta file can grow to be as big as the base disk itself if you write a lot of data to it. If you create a snapshot of that snapshot, the process begins again, and that snapshot can also grow to be as big as the base disk.

I've personally filled up many a drive with snapshots that I've forgotten about. When your datastores fill up, any VM trying to expand files on that datastore (for example if it has snapshots it is trying to grow) will freeze until some space becomes available. It's a real disaster and I've even heard of people going so far as to disable snapshots entirely.

The trouble is that VI Client doesn't give you an easy way to figure out how big snapshots are. Even if it did, do you really want to sift through dozens or hundreds of VMs on a regular basis looking for big snapshots manually? We need automation to solve this problem.

A new cmdlet in the VI Toolkit Extensions can help. Get-TkeSnapshotExtended adds a property called SizeMB to snapshot objects. To use it, load the VI Toolkit Extensions (in PowerShell v2 CTP2 or higher) and run

Get-VM | Get-TkeSnapshotExtended | Select Name, VM, SizeMB

Here's some sample output:

Hope that helps!

I'm not sure if Stephen Campbell is a fan of the 2001 cinematic tour de force Not Another Teen Movie, but he has been keeping busy lately writing a bunch of useful PowerShell scripts, including:

• Not Another ESX Provisioning Script, which is a script that can be used for adding lots of ESX hosts to a cluster quickly and easily.
• Not Another Removable Media Disconnector, which adds a front end to disconnecting CD-ROM and floppy drives.
• Not Another Resource Pool Copier, which will duplicate a set of resource pools from one host to another, also useful if you've got a cluster of ESX hosts.
• Not Another Data Upload Script, which lets you bulk-upload data to your hosts. This is pretty useful if you need to upload lots of ISO images or VMDK files. Also, unlike the upload script in the VI Toolkit Extensions, this one is based on PowerShell version 1, for those of you who aren't able to use PowerShell 2 yet.

Keep 'em coming, Stephen!

I'm really excited about the VI Toolkit Extensions as a way for us to make the common problems we see on our forums really easy to do. Just today, a user wanted to find all files on his datastores that contain the word "delta" (which can indicate a snapshot that hasn't been cleaned up properly). As it turns out, with the extensions this is just a one-liner. The art of PowerShell really seems to be the art of the one-liner and with the extensions there are already a lot of great one-liners you can use.

We've got more than 10 cmdlets in the extensions now, and it's starting to get really useful. Here's a brief tour of what we've got so far:

One of the really great new things in the extensions is the ability to copy files to and from datastores. None of this would have been possible without the help of Stephen Campbell of Marchview Consultants Ltd. Stephen wrote an amazing example of actually compiling C# code within a PowerShell script. With this code, Stephen was able to create a .NET-based web client that would accept self-signed certificates, which is critical for enabling file uploads to ESX hosts. With the new Copy-TkeDatastoreFile cmdlet you can do some really amazing stuff.

Here's an example you can use to move VMs from one ESX host to another without having to rely on VirtualCenter. This example assumes that each ESX server has a datastore called datastore1 and that there's a VM called MyVM that is to be moved.

$server1 = connect-viserver server1
$server2 = connect-viserver server2
copy-tkedatastorefile `
  -source "[datastore1] MyVM/MyVM.vmdk" `

  -sourceServer $server1 `
  -sourceDatacenter (get-datacenter -server $server1) `
  -destination "[datastore1] MyVM/MyVM.vmdk" `

  -destinationServer $server2 `
  -destinationDatacenter (get-datacenter -server $server2)

The cmdlet can also accept arbitrary URLs as either sources or destinations. Here's an example of copying an Openfiler virtual appliance directly to your ESX host:

copy-tkedatastorefile `
  -source http://s3.amazonaws.com/rbuilder/openfiler/%2F16315%2Fopenfiler-2.3-x86.esx.tar.gz `
  -destination "[YourDatastore] OpenFiler/Openfiler.tar.gz" `
  -destinationDatacenter (get-datacenter)

If you combine that with a little more scripting it's fairly easy to have a one-liner that can create iSCSI storage on your ESX host, something we'll hopefully have in the extensions before too long. Neither of these examples even require a password, since they rely on connections already being established through the Connect-VIServer cmdlet.

Anyway, there's lots of great stuff we have planned for the extensions, so be sure to stay tuned. If you've got a feature you want to see, ask us. To get started with the extensions you need PowerShell 2 CTP2 as well as the VI Toolkit. Have fun!

In his blog, Mike DiPetrillo shows us another example of both the power of the VMware API and the ease of use we get with the VI Toolkit for Windows. His script will move a VM from one ESX host to another, without making use of VMware VMotion. The drawback is that the VM becomes unresponsive for a period of time (usually a few seconds). This is roughly functionally equivalent to Microsoft's Quick Migration feature, except that this was done in 130 lines of script.

I've traded a few emails with Mike on the subject so I can add one thing that Mike doesn't mention in his blog. Mike has quite a lot of industry experience and has done a lot of custom development like this  before. However, until recently Mike had never seen the PowerShell or the VI Toolkit at all, yet he still was able to put this script together in the span of roughly a weekend. So I'm not trying to imply that Mike's not a smart guy but there's no question in my mind that the simplicity of the VI Toolkit made it possible for this really interesting script to get developed in record time.

Mike's script asks you to log into VirtualCenter, then prompts for a source and destination host, as well as a VM to move. After a few sanity checks the VM is suspended, moved and un-suspended. That's all there is to it. You can do this process manually through the VI Client or automatically with Mike's script. With a couple of tweaks to Mike's script, you wouldn't even need VirtualCenter to make all of this happen.

Great work, Mike!

Ever had one of those moments when someone shows you something that's a whole lot simpler than what you had in mind? I just had one of those moments. For a long time I've wanted the ability to script VMX file changes because there's a lot of really important and useful stuff you can do with VMX files that you can't do any other way. With the recent changes to the VI Toolkit Community Extensions (more on that later) I had decided that I was finally close enough to do it, and was going to make it my weekend project (don't laugh). Out of the blue comes a script from Benjamin Attal, a VMware consultant in France that does exactly what I wanted to do, except his approach is really easy!

It's also a testament to the depth and power of the VMware API. Adding a key/value pair to every VMX file for every VM is as simple as this:

$key = "Key to set"
$value = "Value to set"
get-vm | foreach {
  $vm = Get-View $_.Id
  $vmConfigSpec = New-Object VMware.Vim.VirtualMachineConfigSpec
  $vmConfigSpec.extraconfig += New-Object VMware.Vim.optionvalue
  $vmConfigSpec.extraconfig[0].Key=$key
  $vmConfigSpec.extraconfig[0].Value=$value
  $vm.ReconfigVM($vmConfigSpec)
}

If every VM is too broad, all you have to do is pass a name (wildcards supported) to get-vm and you can target specific VMs or sets of VMs.

Great, so what do I do with that?

It's not immediately clear why anyone would care about this. The reason is that there's some really useful stuff you can do through the VMX file that it is not possible to do using VI Client. I want to focus the rest of this post around two use cases.

The VMX file is a dark, mysterious place, full of hidden surprises. To my knowledge there is no definitive source of information on what options are available and what they do. One piece of useful information can be found in a VMware KB article that discusses how to change VM logging behavior. By changing the "log.rotateSize" and "log.keepOld" keys you can keep more or less log information about your VMs, as your needs dictate. To do that you can either use the script above, changing the $key and $value variables as appropriate, or read the section below for how to do it with the community extensions.

A second really useful thing you can do with VMX files is described by Eric Siebert, who talks about how to change the location where VMware writes snapshots. As I've discussed before, snapshots can cause big problems when they are left unchecked. Some people place snapshots on a separate datastore so that if that datastore fills up it won't interfere with provisioning new systems. Setting the "workingDir" VMX key lets you do that very easily.

Community Extensions

I've been meaning to write about how there's been a whole lot of useful stuff added to the community extensions. I'll try to update later in the week about some of the new stuff, but for now let's stick with the VMX theme. We've added a cmdlet called set-tkevmx that provides a very simple interface for changing your VMX file. If you download the extension (available on CodePlex) and add it using add-module viToolkitExtensions.psm1, you can then do the stuff mentioned above as easily as this:

get-vm | set-tkevmx -key log.rotatesize -value 10000

This will set the log rotate size on ALL your VMs to 10,000.

get-vm | set-tkevmx -key workingDir -value /path/to/lots/of/storage

This will change every VM you've got to store its snapshots and vswp files to an alternative location.

Just for the sake of re-iteration, to run the code above you'll need PowerShell CTP2 V2, the VI Toolkit for Windows and the VI Toolkit Community Extensions. Enjoy!

When I was chatting with Glenn last night during the live PowerScripting Podcast he asked when he was going to be able to run PowerShell scripts from inside of VI Client. I asked if he had checked out icomasoft as they have a really nice tool called VI PowerScripter for doing just that.

I had used their Beta 1 plugin, but since they have a Beta 2 now I downloaded it and wanted to give an account of my experiences with Beta 2. I think you'll see how easy it is to get started and get to the point where you can plug in your own scripts. In this post I want to talk about one of the useful things you can do with icomasoft's tool.

Snapshots: The silent datastore killer.

Have you ever had a snapshot fill up your datastore because you forgot about it? One of the drawbacks of snapshots is that they get bigger and bigger as you VM writes data. If left unchecked they will keep getting bigger until they finally fill your datastore, making it impossible to do just about anything. It's happened to me more than once, and from the people I've talked to I'm certainly not the only one.

Step 1, of course is to download PowerScripter and run the installer on the same computer where you run VI Client. After you do that, PowerScripter will show up under the Plugins menu.

If you don't see PowerScripter, make sure it's enabled by clicking Manage Plugins...

With PowerScripter you define you own PowerShell scripts that run against hosts or against individual VMs. Let's go through the process of adding some custom scripts.

When you select Script Repository you'll find yourself in a folder with two subfolders, named HostScripts and VmScripts. To define custom ESX host scripts, place a file inside HostScripts. To define a custom VM script, place it in VmScripts.

When you install, there are no pre-canned VM scripts. You can find samples at icomasoft's website, but for this example I'll just add a few of my own.

I added two scripts, one called DeleteAllSnapshot.ps1, one called SnapshotReport.ps1.

Below is the text of the scripts:

Now let's head back to the VI Client to start running scripts. Unfortunately the Beta of PowerScripter has a small feature that hopefully gets fixed soon, you'll need to restart the client. Update: actually to have the scripts show up you can disable then re-enable the PowerScripter plug-in under the Plugins menu.

After we restart we're ready to run our scripts.

This is most useful when you multi-select systems, as show in this screen.

The report shows us the snapshot's name, description, parent VM, and, most importantly I think, when the snapshot was made. If a snapshot is too old, chances are it needs to get deleted.

If you find that a VM has snapshots that need to disappear, you can either remove individual snapshots from the VI Client's snapshot manager or you can remove them all at once through PowerScripter. Even better, if you need to remove all snapshots on a group of VMs, just multi-select them and you're nearly done.

Support resources for icomasoft

PowerScripter is just getting started, but icomasoft has a forum where you can go to share ideas and get samples, you should stop by and say hi. Also, even though PowerScripter doesn't come with any scripts out-of-the-box, there are several sample scripts in their manual that you can drop in and start using. One really useful one is their storage rescan script which allows you rescan all storage across all your hosts with just one click, a huge time saver if you're still doing it the old-fashioned way.

Thanks to everyone who came out to our Managing VMware with PowerShell session at VMworld 2008! We estimate that there were between 800 and 900 of you, which was way above any of our guesses. Hopefully it was worth everyone's time.

My slide deck is online, and in addition here are the demo videos we used at the end of the presentation.

If you missed the session, Eric Sloof posted some videos of it, as well as a few interviews as a bonus prize.

I'm really excited about Invoke-VMScript, but it's worth repeating that this feature is for a future release.

If you're looking for some of the session not contained in Eric's videos, look for the full video to be available later on vmworld.com.

And, as always, if you're interested in using any of the samples contained in the slide deck, get started by downloading the VI Toolkit (for Windows), it is free after all.

Thanks to everyone for you hard work and contributions to our VI Toolkit Scripting contest.

Now the time has come to announce our winners!

First Prize: Our first prize, a trip to VMworld, goes to LucD for his script, which is a really cool Guest Provisioning System.

I really like Luc's application because it very easily lets you clone lots of VMs, while giving you control over a lot of the parameters that are frustratingly manual when you try to do them with other VMware tools. Not only that, but you can queue up tens or even hundreds of clone jobs and run them all with the press of a button. This is especially useful since cloning VMs can take a really long time.

Not only that, but as you can see above, this is not just some script meant to be run on a grainy old CRT terminal, it's a full fledged UI. Speaking of its really cool UI, Bruce Payette, one of the key designers of PowerShell and author of the book PowerShell in Action, had this to say about it: "This is exactly the kind of application we were thinking about when we made PowerShell able to work with WinForms."

Those of us who follow the VI Toolkit for Windows community know Luc quite well, as he has contributed countless great scripts and has really made a difference to a lot of people. So again, congratulations to Luc and we hope to see you in Vegas!

Second Prize: Second prize, a Macbook air, goes to tzamora for his script, VMware Infrastructure Power Documenter. This script makes some really nice reports about VI and outputs them as OpenXML documents that can be read in your favorite word processor or spreadsheet. Here's a sample.

Here's what Bruce had to say about this script: "Very nice report generation tool, using OpenXML with templating, Excellent use of “meta” programming with paragraph and sentence functions. Fully parameterized so it can be used from other scripts. Well documented. Both useful and reusable."

Tzamora is something of a newcomer to the VMware PowerShell world, in fact this winning entry was tzamora's first post on our forums. Congratulations to you, whoever you are!

Third Prize: And Dan Baskette is the proud owner of our third prize, an XBox 360 Elite, for his script powerVDI. Dan's script can let you create thousands of virtual desktops instantly, consuming the space of one (assuming you have the right hardware).

Here's what Lee Holmes, author of the Windows PowerShell Cookbook had to say about it: "Automates a very complex scale-out task, and combines a lot of technology (VMWare, Putty, AD, etc) into a single PowerShell task. Offers interactive use, unattended scripting. For high-scale clusters, this would be an enormous time-saver. This script really demonstrates the super-glue nature of PowerShell."

Great work Dan!

Honorable Mentions:

I wanted to make a few honorable mentions because there really was a lot of great stuff contributed. We saw a lot of scripts around reporting, including our second prize winner -- obviously this is a big concern for everyone. I wanted to point out my personal favorite reporting script, Alan Renouf's "Report into MS Word". While Bruce mentioned that Power Reporter was a great example of meta-programming (I'm taking his word on it), I loved Alan's script because it produces a report with lots of pretty charts and graphs. This is one script everyone should check out.

Hal Rottenberg also nominated slx86's CloneVDI. As Hal mentions, this script really demonstrates the full power of the VMware Web Services API.

Each honorable mentionee will receive a VMware shirt and a VMware coffee mug.

Congratulations to all our winners, and thanks again to everyone for all your great contributions!