Tech Tip: Port Forwarding in Virtualbox with VBoxManage

VirtualBox is a free, powerful and versatile virtualization program which is available for Linux, Mac, and Windows hosts, and can virtualize many different Operating Systems. VirtualBox was originally developed by Innotek, but was purchased by Sun and renamed Sun xVM VirtualBox. There are several versions of the program, but I use the free closed-source version, since it has more features than Virtualbox OSE.

Several networking modes are available for the Virtualbox guest OS to connect to the Internet, but I will specifically mention Network Address Translation (NAT) networking here.

The VirtualBox Manual describes the advantages and disadvantages of NAT in this way:

Network Address Translation (NAT) is the simplest way of accessing an external network from a virtual machine. Usually, it does not require any configuration on the host network and guest system. For this reason, it is the default networking mode in VirtualBox.

A virtual machine with NAT enabled acts much like a real computer that connects to the Internet through a router. The “router”, in this case, is the VirtualBox networking engine, which maps traffic from and to the virtual machine transparently. The disadvantage of NAT mode is that, much like a private network behind a router, the virtual machine is invisible and unreachable from the outside internet; you cannot run a server this way unless you set up port forwarding (described below).

So, your shiny new virtual machine can access the net, but is invisible to other devices on your network. Usually this isn't an issue, but it isn't possible to ssh into your virtual machine or access any services of the machine (such as a webserver) without configuration of port forwarding.

Port Forwarding in VirtualBox

Port Forwarding can be initiated through the powerful and versatile VBoxManage command-line utility. VBoxManage has many options, but we will be using the “setextradata” feature to configure port forwarding.

The following commands will allow you to access your virtual machine via ssh. For this to work, I am making several assumptions about the guest OS:

• Your virtual machine is not currently running, but has already been created and saved.
• Your guest OS has ssh installed and correctly configured.
• Your guest OS is set up with the VirtualBox's default virtual network hardware (PCNET III).
• sshd is listening for incoming connections at the default port (port 22).
• Your guest OS is named “VM Name Here”, although I'd wager that isn't the actual name of your VM.

If you don't know the name of your virtual machine, the easiest way to verify the name is to start Virtualbox and to look at the names of the machines listed on the main screen. Scrolling down on the details also allows you to see other information, such as the network adapter being used.

The following commands will forward TCP traffic that originates from port 2222 on your host OS to port 22 on your guest OS:

$ VBoxManage setextradata "VM Name Here" \
      "VBoxInternal/Devices/pcnet/0/LUN#0/Config/guestssh/Protocol" TCP

$ VBoxManage setextradata "VM Name Here" \
      "VBoxInternal/Devices/pcnet/0/LUN#0/Config/guestssh/GuestPort" 22

$ VBoxManage setextradata "VM Name Here” \
      "VBoxInternal/Devices/pcnet/0/LUN#0/Config/guestssh/HostPort" 2222

Note the usage of double quotes for the virtual machine name. If you decided on a virtual machine name that is only one word such as “VMNameHere”, you can technically omit these double quotes, like this:

$ VBoxManage setextradata VMNameHere \
      "VBoxInternal/Devices/pcnet/0/LUN#0/Config/guestssh/Protocol" TCP

$ VBoxManage setextradata VMNameHere \
      "VBoxInternal/Devices/pcnet/0/LUN#0/Config/guestssh/GuestPort" 22

$ VBoxManage setextradata VMNameHere \
      "VBoxInternal/Devices/pcnet/0/LUN#0/Config/guestssh/HostPort" 2222

There is no harm done in leaving them there, so do whatever makes you feel most comfortable.

FYI, there are some limitations to NAT port forwarding, and I will list them as they are listed in the VirtualBox Manual:

There are four limitations of NAT mode which users should be aware of:

• ICMP protocol limitations: Some frequently used network debugging tools (e.g. ping or tracerouting) rely on the ICMP protocol for sending/receiving messages. While ICMP support has been improved with VirtualBox 2.1 (ping should now work), some other tools may not work reliably.
• Receiving of UDP broadcasts is not reliable: The guest does not reliably receive broadcasts, since, in order to save resources, it only listens for a certain amount of time after the guest has sent UDP data on a particular port. As a consequence, NetBios name resolution based on broadcasts does not always work (but WINS always works). As a workaround, you can use the numeric IP of the desired server in the \\server\share notation.
• Protocols such as GRE are unsupported: Protocols other than TCP and UDP are not supported. This means some VPN products (e.g. PPTP from Microsoft) cannot be used. There are other VPN products which use simply TCP and UDP.
• Forwarding host ports lower than 1024 impossible: On Unix-based hosts (e.g. Linux, Solaris, Mac OS X) it is not possible to bind to ports below 1024 from applications that are not run by root. As a result, if you try to configure such a port forwarding, the VM will refuse to start.

These limitations normally don’t affect standard network use. But the presence of NAT has also subtle effects that may interfere with protocols that are normally working. One example is NFS, where the server is often configured to refuse connections from non-privileged ports (i.e. ports not below 1024).

VBoxManage is an incredibly powerful utility, and this post just scratches the surface of its abilities. There is an entire section of the user manual dedicated to VBoxManage, and I encourage you to read it and discover the other things it can do.

First posted on my blog here.