Working with Customization Specifications in PowerCLI Part 2

PowerCLI has several cmdlets at your disposal for managing OS Customization Specifications. In the previous post we showed you how to create new customization specifications, retrieve and change them, in this post we will cover a common use case, being able to work with network interface card mappings.

Managing network interface card (NIC) mappings

One of the common things to use the customization specifications for is to configure the VM’s network adapters (e.g. static IP, DHCP, etc.). The part of the customization specification that handles the network adapters is the OSCustomizationNicMapping. Each OSCustomizationSpec can have zero or more OSCustomizationNicMappings associated with it – and each of them corresponds to a network adapter of the VM. In order for a customization to succeed – you need to have as many OSCustomizationNicMappings as the number of network adapters on the VM you are customizing. You will see an example for this later on.

PowerCLI offers 4 cmdlets for managing the NIC mappings of a customization specification – these are Get-, Set-, New- and Remove-OSCustomizationNicMapping. Creating a new OSCustomizationNicMapping is done through New-OSCustomizationNicMapping cmdlet. Since the NIC mapping is part of a customization specification – when creating one you need to specify the customization specification to which you want to add the new NIC mapping. This is done through the “-OSCustomizationSpec” parameter. With a single OSCustomizationNicMapping you can configure a network adapter to either use DHCP or static IP.

Here is an example how to configure a network adapter to use DHCP. We also configure 192.168.0.10 as the primary DNS and 192.168.0.20 as the secondary. Additionally we specify that 192.168.0.30 will be the primary WINS server and 192.168.0.40 – the secondary:

New-OSCustomizationNicMapping –OSCustomizationSpec “BasicWindowsSpec” –IpMode UseDhcp –Dns “192.168.0.10”, “192.168.0.20” –Wins “192.168.0.030”, “192.168.0.40”

The following is an example of how to configure a network adapter with static IP:

New-OSCustomizationNicMapping –OSCustomizationSpec “BasicWindowsSpec” –IpMode UseStaticIP –IpAddress “192.168.0.100” –SubnetMask “255.255.252.0” –DefaultGateway “192.168.0.1” –AlternateGateway “192.168.0.2” –Dns “192.168.0.10”

There are a couple of interesting parameters in this cmdlet – Position and NetworkAdapterMac. Since there has to be one OSCustomizationNicMapping for each network adapter of the VM – we need a way to specify which OSCustomizationNicMapping applies to which network adapter. There are a couple of ways to do this mapping.

The first one is to use Position – the positions of the NIC mappings in the OSCustomizationSpec are consecutive numbers starting from 1. The NIC mapping on position 1 will be applied to the first network adapter of the VM, the one on position 2 – to the second network adapter of the VM, and so on. When using New-OSCustomizationNicMapping – if you don’t specify a position the NIC mapping will automatically go on the last position. If you do specify a position – the NIC mapping will go on that position and any other NIC mappings with positions equal or greater than the one you specified – will have their positions shifted with +1.

# Create a new NIC mapping on position 1. If the “BasicWindowsSpec” customization spec has other NIC mappings – their positions will be shifted +1

New-OSCustomizationNicMapping –OSCustomizationSpec “BasicWindowsSpec” –IpMode UseDhcp –Position 1

The second way to map a NIC mapping to a VM’s network adapter is to use NetworkAdapterMac. Simply pass the MAC address of the network adapter to the NetworkAdapterMac parameter when creating the NIC mapping. Later on when you apply the customization specification on the VM – the NIC mapping will be applied to the desired network adapter of the VM.

# Retrieve the network adapter of the VM we want to customize (assume we have a single network adapter)

$networkAdapter = Get-VM “MyVM” | Get-NetworkAdapter

New-OSCustomizationNicMapping –OSCustomizationSpec “BasicWindowsSpec”–IpMode UseDhcp –NetworkAdapterMac $networkAdapter.MacAddress

There is one more thing worth mentioning here. When creating a new OSCustomizationSpec – by default a single OSCustomizationNicMapping is crated for it. So every OSCustomizationSpec will initially have one NIC mapping. This NIC mapping is configured with –IPMode “UseDhcp”. So you need to keep that NIC mapping in mind when configuring your customization specifications. You may either want to modify it according to your needs (with Set-OSCustomizationNicMapping – see more details below) and then add additional NIC mappings or first remove it (with Remove-OSCustomizationNicMapping) and then add the desired NIC mappings.

To retrieve the NIC mappings of an OSCustomizationSpec you can use the Get-OSCustomizationNicMapping cmdlet. This will give you information about the currently configured NIC mappings of the customization specification.

Get-OSCustomizationSpec –Name BasicWindowsSpec | Get-OSCustomizationNicMapping

You can use the output from Get-OSCustomizationNicMapping to modify or remove NIC mappings from the customization specification. Modifying them is done through Set-OSCustomizationNicMapping – this cmdlet allows you to change all properties of the NIC mapping. This is particularly useful when setting static IPs to your VMs – you can change the IP address of the NIC mapping before applying the customization specification to each VM:

$nicMapping = Get-OSCustomizationNicMapping –OSCustomizationSpec BasicWindowsSpec | where {$_.Position –eq 1}

$nicMapping | Set-OSCustomizationNicMapping –IpMode UseStaticIP –IpAddress “192.168.0.101” –SubnetMask “255.255.252.0” –DefaultGateway “192.168.0.1” –Dns “192.168.0.10”

Removing a NIC mapping is done through Remove-OSCustomizationNicMapping cmdlet:

Get-OSCustomizationNicMapping –OSCustomizationSpec BasicWindowsSpec | where {$_.Position –eq 2} | Remove-OSCustomizationNicMapping

# You can also remove all NIC mappings from the specification

$nicMappings = Get-OSCustomizationNicMapping –OSCustomizationSpec BasicWindowsSpec

Remove-OSCustomizationNicMapping –OSCustomizationNicMapping $nicMappings

This post was created by Dimitar Barfonchovski.

Dimitar joined VMware and the PowerCLI team in 2007. He is member of the development part of the team and his main responsibilities are the functional design and implementation of features for the vSphere and vCloud PowerCLI components.

As with all members of the team, he is working to deliver a good and valuable product. He is also working to improve all processes and tools involved in the product development and validation.