Monday, January 12, 2009

Find and Fix the Missing eth0 Device on your Ubuntu Clones


Creating VM templates in VMware ESX/VI3+ that work immediately after you clone them can be challenging. VMware provides some built-in support for creating Windows templates, and Microsoft provides the SYSPREP utility to facilitate the process, but there are few, if any, standard tools available to help with the task in a *nix environment.

This article documents my response to an annoying snag I encountered while using a self-made ESX/VI3 VM template based on the Ubuntu Server operating system.

My template was based on the 64bit Ubuntu 8.04.1 LTS edition downloaded from the Ubuntu site. I built a standard basic installation of the base operating system components. Nothing fancy. After installing the OS and turning the VM into a template, I deployed a clone from the template. I've also tested this on Ubuntu 9.04 and 9.10 and it works as expected.

After the clone booted up, it worked as expected in all areas except networking. The eth0 interface was not visible using the "ifconfig" or "ip address show" commands, and a new eth1 interface had been created and was only visible using the "ip address show" command. The /etc/network/interfaces file only had a configuration for the eth0 interface and assigning it valid IP information did not allow me to bring up either interface. I was dead in the water with no network access.


The snag occurs on the cloned VM's that are deployed from the template VM because the MAC address assigned to the eth0 interface in the udev network configuration files of these clones ends up conflicting with the MAC address assigned to the .vmx configuration files that are auto-generated by ESX server for each VM at the time of cloning. The end result of this conflict causes the cloned VM's to be created with a broken networking configuration that is unusable.


Here is the sequence of events:
  1. The template VM is created and is assigned a virtual MAC address (address "A") by ESX.
  2. This address is inserted into the .vmx configuration file assigned to the VM.
  3. When the VM is booted up, it extracts the virtually assigned MAC address located in the .vmx file and inserts it into the OS's udev network configuration file that handles device to Ethernet mappings.
  4. When the VM is converted to a template, these settings are not removed from the udev file.
  5. When the template is cloned, the clone VM is assigned a new virtual MAC address (address "B") by ESX and this address is recorded in the new .vmx file assigned to the clone.
  6. When booting for the first time, the clone parses its .vmx file and locates the virtual MAC address that has been assigned to it (address "B").
  7. Once it has the new value, it tries to configure its eth0 interface with it by placing an entry into the udev file.
  8. Because the original MAC address (address "A") that was assigned to the template VM still exists in the udev file, the OS decides not to overwirte the old address (address "A") with the new one (address "B"), but instead, creates a new eth1 interface with the virtual MAC address it extracted from its .vmx file (address "B").
  9. When the "ip address show" command is typed, both the eth0 and eth1 interface configurations appear because the command retrieves its information from the udev file.
  10. Because there is no eth1 entry in the /etc/network/interfaces file, the eth1 interface won't work.
  11. Because the eth0 interface is assigned an invalid virtual MAC address in the udev file, the eth0 interface is unusable on the network, even if it is assigned valid IP information.
There are a couple of ways to correct the situation on a per clone basis. They work fine, but they both require extra manual effort. This can become quite time consuming if you have many clones to create. Or, if you don't create many clones, you may even forget the exact fix! One solution involves replacing address "A" with address "B" in the udev file, and the other involves renaming eth0 to eth1 in the /etc/network/interfaces file.

But there's a better solution that you only need to apply once to the original template VM!!


The solution in this article demonstrates how to bypass this problem without editing any ESX files, and with only very minor editing of the Ubuntu network configuration files on the template VM. All the other solutions to this problem that I have seen to date require you to edit each clone (manually or by script) or the .vmx file associated with the clone (not recommended). These solutions work, but in the end, they require much more effort. The solution provided in this article only needs to be applied once.

I have not tested this procedure with other Linux distributions or Ubuntu versions so any feedback on how this process differs in other environments would be helpful to users of those other distributions or Ubuntu versions. For reference, however, earlier Ubuntu versions maintain the MAC address information in the /etc/iftab file.

NOTE: The remaining steps are critical to making this process work correctly for each clone. If the template is booted up after these steps are completed, the steps will need to be repeated before the template can be used again to create new fully operational clones.

  1. Build a VM to be used as a template.
  2. Boot into the VM and log on with an account that has sudo privileges.
  3. Type "sudo ifdown eth0".
  4. Type "sudo /etc/init.d/networking stop".
  5. Type "sudo vi /etc/udev/rules.d/70-persistent-net.rules".
  6. Delete each line beginning at line 5. To do this, move the cursor to the beginning of the line, then type dd. Do not delete the first four commented lines.
  7. Press ESC, then press Shift-ZZ to save.
  8. Type "vi ~/.bash_history".
  9. For each line in the file, move the cursor to the beginning of the line, then type dd.
  10. Press ESC, then press Shift-ZZ to save.
  11. Type "sudo shutdown –P now" to shut down the VM.
  12. Wait for the VM to shut down completely.
  13. Right click the VM in the Virtual Center console and convert it to a Template (or perform the equivalent action if you are not connected via Virtual Center or the VI Client).

In conclusion, creating a VM template using Ubuntu 8+ in an ESX/VI3+ environment is a relatively straightforward process. To avoid having to manually repair an artifact of the cloning process on each VM clone after it is created, this article explains how to change the template VM so that a proper configuration is applied to each clone during the cloning process. The key to making this process work correctly is in disabling the template's networking capabilities prior to deleting the entry for the eth0 interface in the udev file responsible for network interface configuration. Additionally, the template must not be booted into again once these final changes are made to it, otherwise the changes will need to be re-applied.