Renaming Windows Network Adapter for VirtualBox

posted Mar 20, 2012, 7:25 PM by Tyler Akins   [ updated Jun 8, 2012, 10:23 AM ]
The problem with VirtualBox is that on Mac it names its virtual host-only adapters "vboxnet0" and the like.  On Windows they are called "VirtualBox Host-Only Ethernet Adapter", maybe with "#2" added at the end.  Normally this really is not a problem, but it is if you are working in a Macintosh-dominated environment and they have been using Opscode Chef,  Vagrant and VirtualBox to bundle up development environments into boxes.  These virtual machines may be scripted to enable specific networking configurations, such as making a host-only virtual ethernet adapter available to the virtual machine so your VMs can easily network to just each other.  The problem is that the default host-only adapter name changes based on your OS, so now my configuration that's stored in the box from Vagrant is expecting an adapter named "vboxnet0" and mine isn't called that at all.  Starting the VM in VirtualBox will cause problems and then Vagrant will think the install failed.

You'd think it would be as easy as just going to the network settings in the Windows control panel and then right-clicking the adapter and hitting "Rename".  No, it's unfortunately not nearly that simple.

Contributing Factors

This is a slightly more painful process because of the following wrinkles:
  1. This problem is a little more complex because this virtual ethernet adapter can be created automatically by Vagrant.  It's really a nice setup on the Mac, but because of the weird naming it can be irritating on Windows.
  2. When Vagrant kills a machine, it can optionally clean up network adapters that are no longer used.  This means you could lose your network adapter even if you do manage to call it "vboxnet0" on your Windows machine.
  3. The box files that Vagrant produces has the machine settings saved in them.  This includes the amount of RAM, the hard drive image files (see Shrinking VM Disk Images if you want yours smaller), and the networking configuration.  Vagrant can download the box during installation, so I don't want a manual step for modifying this box file before installation.
  4. The standard advice I'd find on VirtualBox forums and other places would be to always manually go in and check / change the network settings.  My goal is a fully automated solution, which means everything get scripted.
  5. I could use different configurations and double the amount of images I'd need to maintain in order to support Windows, but that's just making a problem bigger and more unmanageable.
  6. Windows XP's security model for registry changes is different than Windows 7.  More on this later.
Most of the problems can be eliminated by being able to rename a network adapter right after we create one with Vagrant.  It could be added safely to the scripts that spin up machines and people from around the world will rejoice.  Well, at least a couple might hum in a happy way.

The Solution

It turns out that the name of the network adapter, as seen by VirtualBox, is secreted away in the registry.  If you use regedit to check out HKLM\SYSTEM\CurrentControlSet\Enum\Root\NET and pick one of the keys listed there.  If you check out the Service value and it says "VBoxNetAdp", then you are in luck.  If there is a FriendlyName value just change it to "vboxnet0".  If not, make a FriendlyName value and set it to "vboxnet0".  Reboot or restart all of your VirtualBox software and you should now see this renamed network adapter.

Unfortunately, this is where we hit a snag.  On Windows XP you may need administrator privileges to set this value.  On Windows 7 you need to use the "SYSTEM" account (not the administrator account) or else you will get the wrath of the "access denied" alert.  Don't fret, I've got you covered.

Manual Process

  1. Run VirtualBox and make a virtual host-only network adapter
  2. Tie this virtual adapter to a new virtual machine
    • This is an optional step and is useful so Vagrant doesn't delete the network adapter
  3. Run regedit as administrator
  4. Browse to HKLM\SYSTEM\CurrentControlSet\Enum\Root\NET
    • This could be a specific control set if you are administering another person's account
  5. Look at the keys under here for one with a System value of "VBoxNetAdp"
  6. If there is not a FriendlyName value, right-click in the right pane and attempt to add a new string value; otherwise double-click the FriendlyName value and rename the adapter to "vboxnet0"
    • If you get an "access denied" message, grant Administrator permission to modify the key by right-clicking on the key, select Permissions -> Advanced -> Owner and grant full control to Administrators.  Apply and try to add or change the value again in regedit.
  7. "VBoxManage list hostonlyifs" from the command line should now list your new value.  If not, double-check that the FriendlyName is properly set.  Then try rebooting the machine.
Fantastic.  It's now named vboxnet0.  You could use this to rename the network adapter to anything you like if vboxnet0 doesn't tickle your fancy.

Automatic Process

If you are in a situation like where I was and you need to get this deployed to many machines, you will want to write a little script.  There's two key parts to the script - scanning and escalating.  The scanning part is pretty straightforward.  This is not real code, just in case you were wondering.

for each key in HKLM\SYSTEM\CurrentControlSet\Enum\Root\NET as key
    if value of (key + "\System") == "VBoxNetAdp"
        if value of (key + "\FriendlyName") == "vboxnet0"
            return SUCCESS // It's already there

for each key in HKLM\SYSTEM\CurrentControlSet\Enum\Root\NET as key
    if value of (key + "\System") == "VBoxNetAdp"
        if can set value of (key + "\FriendlyName") to "vboxnet0" then
            return SUCCESS // I made one exist
            return FAILURE // Could not rename - maybe escalate?

return FAILURE // None detected to change

What this will do is first scan all net adapters for a VirtualBox network adapter.  If it finds one with the name "vboxnet0" it will exit since we don't need to do any work.  Failing that, it will scan again to find the first VirtualBox network adapter and attempt to rename it to vboxnet0.  This will return either success or failure.  If no VirtualBox network adapters were found, this script fails.

Next up, the escalating of privileges.  Either you can write a real program or else you can perhaps use PsExec to grant you the right privileges when running a command-line tool.

Attempt to rename as regular user

if rename_script_result == FAILURE
    Attempt to rename as Administrator

    if rename_script_result == FAILURE
        Attempt to rename as SYSTEM

        if rename_script_result == FAILURE
            return FAILURE // Could not do it

I once wrote some JavaScript to do this and executed it with cscript in Windows, though I believe this could be done better as an application that could prompt for Administrator privileges and properly drop down to SYSTEM instead of relying on PsExec trickery.  It also turns out that you can run "cmd" as Administrator, but people have a hard time running cscript as administrator in a command shell, and there is no way that I found to run a command-line tool as SYSTEM without PsExec.  I've tried my best to recreate that script from memory and attached it below.  I haven't tested it much, so I'd appreciate feedback if there's a shortcoming.

While trying to get my solution to work, I found perhaps a half dozen ways that UAC didn't work with regard to batch files and windows scripting host.  I guess that there were enough skript kiddiez out there using these tools that Microsoft needed to clamp down on the interaction between the shell and programs. I can't blame them, but it is sure hard to pop open a UAC prompt on Windows 7 from a command line; I certainly didn't find a good way.
Tyler Akins,
Mar 21, 2012, 10:08 AM