PowerCLI cmdlets: Get/Set-VMGuestNetworkInterface
After my last post on Get/Set-OSCustomizationNicMapping, I started looking further at what options there were to configure network settings for guests that were “already” created.
It is one thing to be able to set the network adapter properties during the cloning process and something entirely different to do it after the fact. Maybe a mistake was made during the cloning process. More likely a network migration could be planned, and a completely different way of doing things would be needed.
Using Invoke-VMScript
In January, I wrote a post on how to Update VMware Windows Guest DNS and WINS through PowerCLI that uses the Invoke-VMScript cmdlet to run a batch file in Windows to set the DNS and WINS information. For those versed with netsh, it is powerful, but there are requirements…
One pretty big requirement is that the name of the network adapter must be known. On older VM’s, or possibly P2V’ed VM’s the network adapter name could be something like “Local Network Connection 2″, “Local Network Connection 3″, etc. Using the above mentioned script is going to fail if the connection name is not known. The only way around that, would be to put some logic in to determine the name to use when calling the script. Additionally using netsh with DNS and WINS requires the addition of new values, and deletion of old values.
Another issue with the Invoke-VMScript method, is that it requires different scripts for Windows and Linux guests.
A Different Way
So I started to peruse the online docs for the current vSphere 4.0 Update 1 and found the Get/Set-VMGuestNetworkInterface cmdlets. Just like my last post, I couldn’t really find any example scripts of anyone using it.
Here is the syntax for these cmdlets:
Get-VMGuestNetworkInterface
Syntax
Get-VMGuestNetworkInterface [[-VM] <VirtualMachine[]>] [-VMGuest <VMGuest[]>] [-Server <VIServer[]>] [-ToolsWaitSecs <Int32>] [-GuestPassword <SecureString>] [-GuestUser <String>] [-GuestCredential <PSCredential>] [-HostPassword <SecureString>] [-HostUser <String>] [-HostCredential <PSCredential>] [<CommonParameters>]Set-VMGuestNetworkInterface
Syntax
Set-VMGuestNetworkInterface -VmGuestNetworkInterface <VMGuestNetworkInterface[]> [-WinsPolicy <DhcpPolicy>] [-Wins <String[]>] [-DnsPolicy <DhcpPolicy>] [-Dns <String[]>] [-IPPolicy <DhcpPolicy>] [[-Gateway] <Object>] [[-Netmask] <String>] [[-Ip] <IPAddress>] [-ToolsWaitSecs <Int32>] [-GuestPassword <SecureString>] [-GuestUser <String>] [-GuestCredential <PSCredential>] [-HostPassword <SecureString>] [-HostUser <String>] [-HostCredential <PSCredential>] [-WhatIf] [-Confirm] [<CommonParameters>]
One thing that struck me as odd, was that both of these commands have the following statements as part of their documentation:
… Consider that this functionality is experimental. …
and
…Notes
Supported on ESX 3.5 and newer. …
So which is it? Maybe @cshanklin can address this at some point.
How Does It Really Work?
Are the Get/Set-VMGuestNetworkInterface cmdlets really that different from Invoke-VMScript? Not really, except for the fact that VMware has taken some of the guesswork out of the process. These cmdlets actually call scripts in the Scripts folder located under the installation path of the vSphere PowerCLI. There are separate scripts for Windows OSes and Linux OSes (currently only supported on RHEL 5).
The netsh scripting limitation I mentioned earlier (network connection name) is actually taken care of by these scripts. Additionally these scripts can be modified/added to if desired.
There are a couple things to be aware of.
- Set-VMGuestNetworkInterface does not work in my environment if the vNic is disconnected.
- I could not use the vSphere PowerCLI in x64 mode to run the script. The PowerCLI stated that I needed to use the 32bit PowerCLI instead.
- WINS settings are not available in Linux guests.
How To Update
Now how do I go and update IP addresses on several machines (possibly those that I created in my last post)?
Here are the contents of my text file (C:\vms.csv) that contained my VM names and other settings.
basevm,datastore,vmhost,custspec,vmname,ipaddress,subnet,gateway,pdnswins,sdnswins,vlan
BASEVM,DS1,ESXi1,W2K3,VM01,192.168.0.80,255.255.255.0,192.168.0.1,192.168.0.199,192.168.0.198,Primary
BASEVM,DS1,ESXi1,W2K3,VM02,192.168.0.81,255.255.255.0,192.168.0.1,192.168.0.199,192.168.0.198,Primary
BASEVM,DS1,ESXi1,W2K3,VM03,192.168.0.82,255.255.255.0,192.168.0.1,192.168.0.199,192.168.0.198,Primary
BASEVM,DS1,ESXi1,W2K3,VM04,192.168.255.83,255.255.255.0,192.168.0.1,192.168.0.199,192.168.0.198,Secondary
BASEVM,DS1,ESXi1,W2K3,VM05,192.168.255.84,255.255.255.0,192.168.0.1,192.168.0.199,192.168.0.198,Secondary
So I’ll modify it because I didn’t mean to use 192.168.0.x, I meant to use 192.168.1.x. And I’ll pull out the things I don’t need, like basevm, datastore, vmhost, & custspec.
vmname,ipaddress,subnet,gateway,pdnswins,sdnswins,vlan
VM01,192.168.1.80,255.255.255.0,192.168.1.1,192.168.1.199,192.168.1.198,Primary
VM02,192.168.1.81,255.255.255.0,192.168.1.1,192.168.1.199,192.168.1.198,Primary
VM03,192.168.1.82,255.255.255.0,192.168.1.1,192.168.1.199,192.168.1.198,Primary
VM04,192.168.255.83,255.255.255.0,192.168.1.1,192.168.1.199,192.168.1.198,Secondary
VM05,192.168.255.84,255.255.255.0,192.168.1.1,192.168.1.199,192.168.1.198,Secondary
Now I’ll save it as C:\vms-newip.csv.
Also, unlike the Get/Set-OSCustomizationNicMapping cmdlet, I’ll have to connect specifically to the host and the guest with appropriate credentials. I have to do this, because credentials are required in the guest to make the change.
The Script
I’ll use the following script to update the VM’s.
##########################################################
# updateip.ps1
# Jase McCarty 6/6/2010
# Posh Script to update IP
# addresses in Virtual Machines
##########################################################
Connect-VIServer vcenter.jasemccarty.com
$HostCred = $Host.UI.PromptForCredential("Please enter credentials", "Enter ESX host credentials", "", "")
$GuestCred = $Host.UI.PromptForCredential("Please enter credentials", "Enter Guest credentials", "", "")
$vmlist = Import-CSV C:\vms.csv
foreach ($item in $vmlist) {
# I like to map out my variables
$vmname = $item.vmname
$ipaddr = $item.ipaddress
$subnet = $item.subnet
$gateway = $item.gateway
$pdnswins = $item.pdnswins
$sdnswins = $item.sdnswins
#Get the current interface info
$GuestInterface = Get-VMGuestNetworkInterface -VM $vmname -HostCredential $HostCred -GuestCredential $GuestCred
#If the IP in the VM matches, then I don't need to update
If ($ipaddr -ne $($GuestInterface.ip)) {
Set-VMGuestNetworkInterface -VMGuestNetworkInterface $GuestInterface -HostCredential $HostCred -GuestCredential $GuestCred -IP $ipaddr -Netmask $subnet -Gateway $gateway -DNS $pdnswins,$sdnswins -WINS $pdnswins,$sdnswins
}
}
As can be seen, it doesn’t take a complex script to update IP information in guests.
Keep in mind that not all of the attributes that I chose to use are required. If desired, only the IP, DNS, WINS, etc can be updated. My script just happens to update several of these items. Additionally, this can be used to change a guest from a static IP address to a DHCP address as well.
Hopefully this script will help you when presented with a similar task of updating IP addresses/DNS/WINS settings.
For More Info
For more info on each of these commands, look here for the VMware documentation:
