✎ appnotes:gpxeonvmware - Etherboot/gPXE Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
===== Adding a gPXE ROM image directly into a VMware virtual machine =====

    * This guide covers VMWare virtual machines and should be nearly identical for all VMware hypervisor prodcuts.  [[wp>VMware_Workstation|VMWare Workstation]] is covered specifically by this guide, but you can adapt it easily for VMWare Server or ESX.
    * The capability to add a gPXE ROM directly to a VM is not limited to VMWare.  You can find out more on the [[romburning/|ROM burning HowTo]], or jump straight to the guide for [[romburning/vbox|Sun Virtualbox]] or [[romburning/qemu|QEMU]].
	

==== Overview ====
 
While most [[howtos/#how_to_deploy_gpxe|all other deployment methods]] will work well for VMware or any other hypervisor for booting your VM with gPXE, adding a ROM image directly to your VM's configuration file avoids the obscurity encountered when chainloading gPXE from a mounted CD ISO or Floppy image file, and likewise avoids the overhead, complexity, and potential modification of your infrastructure that's required to chainload gPXE from the VM's existing PXE ROM.  Furthermore, while any VM whose host that can access the ROM file can share it to avoid large numbers of duplicate ROM files in your datastore, you can also [[scripting/|embed scripts]] into individual ROM files as you add them to a VM, removing the need for you to [[howtos/#how_to_use_advanced_dhcp_options|configure advanced DHCP options]] on a per-client basis or maintain and secure a centralized script repository.

Not only is using a ROM one of the fastest methods of loading and booting from gPXE on //either// a physical or virtual machine, adding a ROM in this fashion __adds gPXE directly to your VM's BIOS boot order__, and when compared to the [[pxechaining/|PXE chainloading]], [[removable/|CD, floppy, or USB based]] methods it is quite possibly the most secure and concise deployment method available right now.

{{ :appnotes:vmware-gpxe-bios.jpg |gPXE as a boot option in VMware Workstation}}

===== Implementation =====

Here, we're going to manually edit the VM's configuration file to:
	* Change the virtual network adapter from the default, an AMD PCNET32, to an Intel E1000 as gPXE has better support for the Intel NIC.
	* Add the ROM image to the .vmx file to be used by the virtual NIC.
			
===== Acquire the binary ROM image file =====

	* **First**, we need to acquire the ROM image we're going to use when we modify the VM configuration, which we can do one of two ways:\\


==== > Option 1 (Easier): Use a pre-built binary from ROM-o-Matic ====
-------
{{ :appnotes:rom-o-matic-options.jpg?250|A screenshot of the data you'd fill out in ROM-o-Matic}}	
Acquire a pre-built ROM from gPXE's ROM-o-Matic for the Intel E1000 NIC.  The **VEN**dor and **DEV**ice ID codes for the E1000 are **8086** (signifying Intel's PCI Vendor code) and **100f** (for the Device code).
	* Go to www.rom-o-matic.net and click on the "gPXE git (current-top-of-git-tree) Image Generator."
	* On the image creation page, set the options to:
	- Output format: **ROM binary (flashable) image (.rom)**
	- NIC type: **e1000_84250**
	- PCI Vendor Code: **8086**
	- PCI Device Code: **100f**
	* After you've entered all of the relavant information, click the "Get Image" button and you should receive a .rom file named after the combination of the latest gPXE release and the VENdor+DEVice combination entered above.  At the time of writing, the latest gPXE version is **1.0.0+**, and the DEV+VEN is **8086100f**.  As such, the file I received is:
<code>gpxe-1.0.0+-8086100f.rom</code>
	* Now, let's skip to [[#locating_the_vm_s_.vmx_configuration_file|locating your VM's configuration file.]] \\ \\


==== > Option 2 (Advanced): Compile the binary ROM from source ====
----------
Building from source is obviously more complicated.  However, if you have a Linux machine and are comfortable building from source code, [[download/|follow the instructions here]] to download the gPXE source.
	* **cd** to your gPXE **src** directory, and then type **make bin/8086100f.rom**
<code>
user@user-ubuntu:~/gpxe-1.0.0+$ cd gpxe/src/
user@user-ubuntu:~/gpxe-1.0.0+/gpxe/src$ make bin/8086100f.rom 
   ....build process output....
[FINISH] bin/8086100f.rom
rm bin/8086100f.rom.bin bin/8086100f.rom.zbin bin/8086100f.rom.zinfo
user@user-ubuntu:~/gpxe-1.0.0+/gpxe/src$
</code>
	* Now, copy the output file, **bin/8086100f.bin**, to the directory your VM resides in
<code>
user@user-ubuntu:/home/user/gpxe-1.0.0+/gpxe/src# cp bin/8086100f.rom /home/user/Virtual\ Machines/WinXP/
</code>
Once you've copied the ROM image file to your VM directory, skip to the section on [[#editing_the_vmx_file|editing the .vmx file]] below.

===== Locating the VM's .vmx configuration file =====
Now we need to locate and edit the configuration file for the VM we wish to add the gPXE ROM image to.
	* If you already know where your .vmx file is, **browse to that folder and [[#Copy_the_ROM_image_to_the_VM_directory|skip this section.]]**
	{{ :appnotes:vmx-location.jpg?350|VMware Workstation showing the location of our target VM's .vmx configuration file.}}
	* If you don't already know where your VM's configuration file is stored:
		- Open VMware Workstation, and if the VM that you wish to add your gPXE ROM to is online, shut down it down.
			* If **VMware Tools** is installed in the guest OS, you can select the VM in the sidebar and click "VM > Power > Shut Down Guest" in the file menu at the top of the application.  If not, just shut down the VM in your usual fashion.
		- Once your VM is shut down, click on your VM in the VMware Workstation sidebar to bring up its summary page on the right hand side.
		- The .vmx file will be displayed next to the **Location** section of the tab that appears on the right side of the window (see the screenshot to the right).
		- Navigate to that folder.  Using our example, we'll go to:
<code>D:\Virtual Machines\Windows XP Professional PicoTest</code>
	* Locate the .vmx file in that folder.  Here's the file I've used in our example:
{{:appnotes:vmx-file.jpg}}\\ \\
__Note__: If you **don't** see a file ending in **.vmx** like the example above, but instead see a bunch of files with identical names and no "**.xxx**" on the end, your operating system may be set to hide file extensions.\\  To //turn on// display of file extensions in [[wp>windows_vista|Windows Vista]] or newer, [[http://windows.microsoft.com/en-US/windows-vista/Show-or-hide-file-name-extensions|follow the steps here]].  In [[wp>Windows XP]] or earlier, [[http://www.fileinfo.com/help/windows-show-extensions.html|follow this guide]] instead.\\

===== Copy the ROM image to the VM directory =====
Now, you need to copy the ROM image so that it resides in the same directory as as your .vmx file.\\
	* Locate wherever you downloaded the image to from ROM-o-Matic.net earlier, and drag and drop that file to your VM's folder.\\
	* You should now have your ROM image, which as per the example pictured here is **gpxe-1.0.0+-8086100f.rom**, in the same folder as the .vmx file.\\
{{:appnotes:rom-copied.jpg}}\\

===== Editing the .vmx file =====
Now we need to open the .vmx file in your text editor of choice.  Unfortunately for us, .vmx files are set to open with VMware Workstation by default, so, if you're using Windows, you need to right click the .vmx file and click "Open With...".\\  If a sub-menu comes up from clicking "Open With", click "Choose Default Program..."\\ 
{{:appnotes:open-with-dialog.jpg?250}}\\
In the "Open With" dialog that appears, select **Notepad** (or your favorite text editor) from the list.  You may have to expand the "Other Programs" section to find it.  After you select **Notepad** from the list, if you do not desire manual editing of .vmx files to be the default behavior when you double click on them, uncheck the "__Always use the selected program to open this kind of file__" box at the bottom-left of the dialog.\\
{{:appnotes:open-with-notepad-selected.jpg?250}}\\ \\
Once your text editor opens, take a look at the information you see in the .vmx file.  You are going to __add__ lines to the file, and they can go anywhere in the file, so if you like, just go to the last line and press __Enter__ to insert another line.  If you'd like to keep things neater, you can find the lines that reference **ethernet0** and insert them there.
	* The first line changes the virtual NIC from a **PCNET32** NIC to an **Intel E1000**:
<code>ethernet0.virtualDev = "e1000"</code>
	* The second line adds the gPXE ROM to the Virtual NIC's ROM:
<code>e1000bios.filename = "gpxe-1.0.0+-8086100f.rom"</code>
__Note__: The text "**gpxe-1.0.0+-8086100f.rom**" corresponds to the file that you downloaded from ROM-o-matic and then copied to the VM's folder in the above steps.  Your ROM's filename will likely be different.\\ \\
{{:appnotes:vmx-file-modified.jpg|Example of edited .vmx file}}\\
	* Once you've finished adding those lines to your .vmx file, save it and close it. \\

===== Finishing up =====

Go back into VMware Workstation and start up your VM.  You can press the ESC key during POST to bring up the boot menu and/or enter the VM's BIOS.  If gPXE shows up as a boot option, you're done!

{{:appnotes:vmware-gpxe-bootmenu.jpg|gPXE as a boot option in VMware Workstation}} \\

Congratulations, and enjoy your ROM-Based installation of gPXE!	 \\

==== Drivers ====

Most modern operating systems (Windows Vista/Server 2008 and newer and more recent versions of various Linux distros) include drivers for the Intel E1000 series NICs by default.  However, if your guest OS is 32 bit Windows XP or Windows Server 2003, you may need to download additional driver files from Intel's web site [[http://www.intel.com/support/network/sb/cs-006120.htm|here]].

==== Considerations ====

The downside to this method when compared with PXE chainloading is that it //does// require you to change the NIC in your VM.  If you have any application or service running in that VM where a NIC "swap" would be a problem, you may want to consider a less disruptive method of introducing gPXE into your environment.  It is worth pointing out that, considering the poor native driver support offered to PCNET32 or VMXNET NICs at this time, a PXE chainload that utilizes the UNDI driver is the best bet in those situations, but overhauling your DHCP/ProxyDHCP deployment might likely be a more time consuming task than reinstalling a VM's NIC.

Performing this procedure may cause VMware to generate a new MAC address for the virtual NIC.  You can permanently assign a MAC address either via the Workstation GUI (right click your VM, click "Settings" and select your network adapter) or by changing lines in the .vmx configuration file.


===== Notes for Advanced users =====

	* "ethernet0" in the vmx file can be changed to "ethernetX" to accomodate your virtual NIC of choice for a multi-homed VM.
	* "e1000bios.filename" can be an absolute or relative path, at least on Windows.  If you have many VM's and don't want duplicate files, consider using "..\ROMS\romfile.rom" or "X:\ROMS\romfile.rom"
	* This method is particularly good when you'd like to make use of embedded gPXE scripts.  Of course, you could accomplish the same thing with an ISO or floppy image attached to your VM, but ROM files are nice as they aren't quite so ambiguous.
	* To this author's knowledge, aside from watching while booting the VM or editing the .vmx file, there's no way to determine from the Workstation (or Infrastructure Manager) UI that a modified NIC ROM has been applied to a VM.
	* Lines in the .vmx file can be commented out with a semicolon (;) and the next setting begins on the next non-blank new line.  If you'd like to switch back and forth between settings introduced through manual .vmx file editing, like if you had several different ROM images each with a different embedded script, you can change between them by commenting in and out different settings.
Trace: • ibft • journal • journal • gpxeonvmware • 2011 • gdbstub • ubuntu_iscsi2 • usbwithstorage • andytim_todo • soc • 2010 • 2009 • commandline • usermanual