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.

VM-Name-Here.png127.97 KB

Linux rocks! Personal blog:


Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

Emule Adunanza

Anonymous's picture

Hi, i can't make forwarding on UDP for Emule. I setextradata on config file (is the same of line commands) like this:

but not working. Any ideas? THANKS!!!


Anonymous's picture


ExtraDataItem name="VBoxInternal/Devices/pcnet/0/LUN#0/Config/hostssh/GuestPort" value="4001"/
ExtraDataItem name="VBoxInternal/Devices/pcnet/0/LUN#0/Config/hostssh/HostPort" value="4001"/
ExtraDataItem name="VBoxInternal/Devices/pcnet/0/LUN#0/Config/hostssh/Protocol" value="TCP"/

Re: UDP traffic

Ross Larson's picture

The command that you listed forwards TCP traffic, not UDP traffic. Check out this Wikipedia article to see the difference between the two protocols.

Try changing TCP to UDP and see if that helps out. When in doubt, check the VirtualBox User Manual.

Linux rocks!
Personal blog:


Debien's picture

If you are using a Gigabit adataper, you may need to replace "pcnet" with "e1000".

You will see an error: Failed to get MAC value

You will need to use setextradata to delete the previous keys (no value deletes key).

Author's Comment

Ross Larson's picture

If you are using Windows XP, you can access the command line by clicking the run button from the Start Menu and typing "cmd" without the quotes. I believe that VirtualBox is installed in the "Program Files" directory. Change directories to the VirtualBox directory, and you should be able to use the VBoxManage commands listed in this article.

Linux rocks!
Personal blog:

Where is the Virtualbox CLI for windows virtualbox

Anonymous's picture

You rant and rave about the CLI. I can't even find it on my windows virtualbox. Where is this mysterious terminal window for virtualbox? Usually CLI is easy to find, not with virtualbox.

Ranting and Raving about CLI

<--iNT13-->'s picture

You rant and rave about the CLI. I can't even find it on my windows virtualbox. Where is this mysterious terminal window for virtualbox? Usually CLI is easy to find, not with virtualbox.

Are you serious?
CLI - Command Line Interface is in the same place in Windoof XP VM as it is in a real XP box.
Go to the Start Menu" (bottom-left of your screen)...
Click on it...
When it pops up select Run...
type cmd into the textarea and then press Enter
A black screen in a window will open (that's the command line)
the line of text in that window is called the "prompt" it will show your current directory (probably My Documents)
Enter cd C:\"Program Files"
Then hit Enter (but not too hard - you'll break it)
The prompt will change to show the new working directory
dir will list the directories
cd followed by a directory name will move you to it (sic).
Depending on how you have XP configured you can just use Explorer (not Internet Explorer) to navigate to the VirtualBox install directory and choose "open command prompt" (shorter way)
You can also just preface your vbox commands with the path to the VirtualBox installation directory and save moving there to execute them.
Note: Your mileage will vary according to how good my memory of Windoof is.

Suggestion: you'll catch more flies with honey - ranting and raving will just get you advice like del. > null