Controlling VirtualBox from the Command Line

Using Oracle VM VirtualBox's VBoxManage tool from the command line of the host operating system, you can control Oracle VM VirtualBox settings, create new VMs, and work on existing VMs.

There were times when a command line was the main tool—sometimes the only tool—you could employ to communicate with your computer. And although nowadays GUI tools have shot ahead, a command line still remains at your disposal in many operating systems, providing a low-level way to interact with the system and its components that permits scripting and automation.

Oracle VM VirtualBox, cross-platform virtualization software that allows you to run multiple operating systems simultaneously, is no exception. It comes with VirtualBox Manager, a convenient GUI tool for controlling the Oracle VM VirtualBox settings and its virtual machines (VMs). On the other hand, you can use VBoxManage, the command-line interface (CLI) to Oracle VM VirtualBox. This article explains how to use VBoxManage to control Oracle VM VirtualBox from the command line of the host operating system.

High-Level View of Oracle VM VirtualBox Interfaces

Oracle VM VirtualBox offers the following tools to control virtualization engine settings, create new VMs, and work on existing VMs within Oracle VM VirtualBox:

• VirtualBox Manager, the GUI for controlling Oracle VM VirtualBox

• VBoxManage, the CLI to Oracle VM VirtualBox

• The Main API, which is implemented using the Component Object Model (COM/XPCOM)

• The web service, which maps nearly the entire Main API for web applications

VirtualBox Manager and VBoxManage interact with the Main API behind the scenes, while client programs can directly use the Main API to control Oracle VM VirtualBox. These tools can be used concurrently, and changes made using one tool are immediately visible when using another. For example, changes made with the CLI are immediately reflected in the GUI and vice versa.

Diagrammatically, the Oracle VM VirtualBox architecture looks like Figure 1:

Figure 1. Interfaces for interacting with Oracle VM VirtualBox

Some of you might be wondering, "While the existence of programming interfaces to Oracle VM VirtualBox is understandable, why does the CLI tool even exist if there is a convenient GUI alternative?" The answer is that only the VBoxManage CLI guarantees access to all the features of the virtualization engine, as well as providing some advanced and experimental configuration settings for a VM. Moreover, on Linux and Oracle Solaris hosts, the VirtualBox Manager GUI has dependencies on the Qt and Simple DirectMedia Layer (SDL) libraries, which means you won't be able to use the GUI if your Linux or Oracle Solaris server doesn't have the X Window System installed.

In contrast, VBoxManage does not require the presence of the X Window System on your server, thus providing you with the ability to control Oracle VM VirtualBox on servers that have no graphical front end and, therefore, can run only console applications. Another benefit of using the CLI is that it permits scripting that can automate Oracle VM VirtualBox operation and eliminate repetitive user interaction.

Preparing Your Working Environment

Before you can start playing with Oracle VM VirtualBox, you have to install it on your host operating system (the latest release of Oracle VM VirtualBox can be found on the Oracle VM VirtualBox downloads page). It installs on any of the following operating systems: Windows, Mac OS X, Oracle Solaris, and Linux. The detailed list of the supported host operating systems can be found in the "Supported host operating systems" section of the Oracle VM VirtualBox User Manual. Also, the most up-to-date information on supported guest operating systems can be found in on this page. Note that you might need to install some additional packages before installing Oracle VM VirtualBox. For further details, refer to the Oracle VM VirtualBox User Manual.

VBoxManage Versus VirtualBox Manager

Although the ability to get the job done in a few clicks within a GUI tool sounds temptingly easy, a CLI alternative provides a more low-level way of interacting with the system you're working on. When using a GUI, you get access to the command set implicitly through buttons and menus, but often you aren't aware what commands and parameters are employed behind the scenes.

In a CLI, you work with the commands explicitly, manipulating their parameters as necessary. Moreover, often a GUI tool cannot provide access to the full set of available commands, exposing only the most used ones. Another advantage a CLI provides over a GUI is scriptability—the ability to put a series of commands in a single executable text file that can then executed as a single command. This is especially valuable for repetitive operations, such as creating multiple VMs for an application.

Supporters of a GUI might argue that, in contrast to a CLI, a GUI is intuitive. To understand how a GUI works, you often don't need to check the documentation; you can see the possible actions by looking at the buttons available in the GUI. VirtualBox Manager is a good example of a user-friendly GUI. It shows you a list of the installed VMs, if there are any, and provides buttons that allow you to create new VMs and work on existing ones, as shown in Figure 2:

Figure 2. VirtualBox Manager GUI for Oracle VM VirtualBox

Of course, a CLI does not look so friendly. However, the way to learn about your possible actions is surprisingly easy. If you type the VBoxManage command at the command line of your host operating system, the entire list of available options and subcommands is shown (see Figure 3).

Figure 3. VBoxManage CLI for Oracle VM VirtualBox

As you can see, everything you might use with VBoxManage can be viewed in detail. Your job is to employ a correct set of VBoxManage commands, subcommands, and parameters to accomplish a desired task. In the rest of this article, we'll look at how you might use VBoxManage commands to complete some of the most interesting tasks within Oracle VM VirtualBox.

Observing Existing Virtual Machines

If you already have VMs registered with Oracle VM VirtualBox (say, with the help of the GUI), the first thing you will most likely want to do with VBoxManage is look through the list of those VMs. This can be done with the VBoxManage list command followed by the vms subcommand:

$ VBoxManage list vms 
"Oracle Virtual Sysadmin Days" {e8744abc-96bb-4251-9dfe-b0cd059ff6bb}
"Oracle Developer Days" {c465cc52-dc11-4153-82d8-b5718182c117}

If the command outputs nothing, you either currently have no VMs registered with Oracle VM VirtualBox or you're running VBoxManage as a user different from the user who created those VMs. If the latter is the case, you need to log in as the right user and then issue the command again. However, if you have no VMs at the moment, your first step could be to create one, as discussed in the next section, "Creating a VM."

To view the VMs that are running at the moment, you might use the runningvms subcommand of VBoxManage list:

$ VBoxManage list runningvms
"Oracle Developer Days" {c465cc52-dc11-4153-82d8-b5718182c117}

The VBoxManage list command can be used with option -l, which instructs the list command to output a detailed list (truncated below to save space):

$ VBoxManage list -l runningvms
Name:            Oracle Developer Days
Groups:          /
Guest OS:        Oracle
UUID:            c465cc52-dc11-4153-82d8-b5718182c117
Config file:     /root/VirtualBox VMs/Oracle Developer Days/Oracle Developer Days.vbox
Snapshot folder: /root/VirtualBox VMs/Oracle Developer Days/Snapshots
Log folder:      /root/VirtualBox VMs/Oracle Developer Days/Logs
Hardware UUID:   c465cc52-dc11-4153-82d8-b5718182c117
Memory size:     900MB
Page Fusion:     off
VRAM size:       12MB
CPU exec cap:    100%
HPET:            off
Chipset:         piix3
Firmware:        BIOS
Number of CPUs:  1
Synthetic Cpu:   off
CPUID overrides: None
Boot menu mode:  message and menu
Boot Device (1): DVD
Boot Device (2): HardDisk
...

Creating a VM

If you're just getting started with Oracle VM VirtualBox and it has no VMs registered, your first step would be to create a VM. VBoxManage lets you do that with the createvm command. Actually, the process of creating a VM is reduced to building a new XML VM definition file. You can then register the VM with the help of the VBoxManage registervm command, importing the VM's definition into Oracle VM VirtualBox. Alternatively, you can use the --register option with the createvm command to make Oracle VM VirtualBox immediately register the VM being created.

In fact, the name of the VM is the only mandatory parameter of the createvm command. The details can be specified later through the various parameters of the modifyvm command. Both modifyvm and createvm, however, support the ostype optional parameter that you can use to give Oracle VM VirtualBox an idea of what guest operating system will be installed into the VM.

You can check the supported OS types using the following command, which outputs a long list of supported OS types, including Oracle Linux (64 bit), among many others:

$ VBoxManage list ostypes
...
ID:          Oracle_64
Description: Oracle (64 bit)
Family ID:   Linux
Family Desc: Linux
64 bit:      true
...

The following example assumes you're going to install Oracle Linux (64 bit) as the guest OS into the VM being created. (Of course, you might try out another operating system in a guest; consult this web page for details.)

$ VBoxManage createvm --name OracleLinux6Test --ostype Oracle_64 --register

If everything went smoothly, the output should look like this:

Virtual machine 'OracleLinux6Test' is created and registered.
UUID: 067c9e4f-183a-47a9-8506-6c18ed920c2b
Settings file: '/oracle/VirtualBox VMs/OracleLinux6Test/OracleLinux6Test.vbox'

An important thing to realize here is that the VM is created empty. Although you specified the operating system type when creating the VM, you still have to set the CPU, RAM, network, and disk configuration for your VM, and you need to install your guest operating system into the VM afterwards. This will be discussed in the following sections.

Setting Up a VM's Properties

As you might notice, Oracle VM VirtualBox requires minimal information from you to create and register a new VM, and it sets many properties of the VM to default values. However, to meet your needs and to comply with the requirements of the guest OS you're going to install, you might need to modify the properties of the VM.

To look at the current settings of the VM we created, you can issue the following command:

   $ VBoxManage showvminfo OracleLinux6Test 

Examining the output can help you see what settings should be set or modified. Below are some settings you might want to set up first.

   
$ VBoxManage modifyvm OracleLinux6Test --cpus 2 --memory 2048 --vram 12 

When setting the amount of RAM for a VM, you should take into account the requirements of the guest OS, as well as the requirements of the software components you're going to run on it. The amount of RAM given to the VM will be taken away from your host machine when you run the VM. So, make sure that the host will have enough memory left to operate properly after you start all the VMs that are supposed to work simultaneously. This advice also applies to the number of virtual CPUs allocated to guests: don't assign more virtual CPUs than the number of physical cores on the host computer.

After setting a property, you can check it with the VBoxManage showvminfo command. Since this command displays a lot of output, it is useful on Linux, Oracle Solaris and Mac OS systems to filter the output with the grep command, as in the following example:

$ VBoxManage showvminfo OracleLinux6Test | grep "Memory size"
Memory size:     2048MB

Configuring a Virtual Network Adapter

Other important settings available through the VBoxManage modifyvm command include networking settings. You can use this command to configure a virtual network card over a physical network interface of the host system to provide your VM with the ability to interact with the outside world.

Suppose you want to configure a virtual network interface using Oracle VM VirtualBox's bridged networking option. Before you can do that, you need to determine which network interfaces are available in the host system, so that you can choose one to be used with the given virtual network interface.

Note: Oracle VM VirtualBox enables you to configure up to eight virtual PCI Ethernet cards for a VM. As you might learn from the output of the VBoxManage showvminfo command issued for a newly created VM, Oracle VM VirtualBox configures by default one virtual adapter for a VM, setting it to operate in the network address translation (NAT) networking mode. In the example shown below, you change the mode of that adapter, nic1, to bridged (for bridged networking).

To list the available interfaces on the host system, you can use the ifconfig utility, provided your host is running under a UNIX-like OS (in Windows, you might use ipconfig instead).

Then you can create a bridge virtual adapter as follows:

   
$ VBoxManage modifyvm OracleLinux6Test --nic1 bridged --bridgeadapter1 eth0

Of course, the bridged networking option is not the only one you can choose when configuring a network adapter plugged into the VM. For further details, refer to the "Virtual networking" chapter of the Oracle VM VirtualBox User Manual.

Attaching Virtual Media to a VM

Like a real computer, your VM needs a storage device, such as a hard disk, to boot from and for storing and retrieving system and user data. So, let's now create a virtual hard disk for the VM. This is actually a three-step process.

As the first step, you create a new virtual hard disk image. With the following command, you create a disk image file in Oracle VM VirtualBox's VDI format. If the path specified does not exist, Oracle VM VirtualBox will create the missing directories.

$ VBoxManage createhd --filename /path/to/hard_drive_image/OracleLinux6Test.vdi --size 5120 
--variant Standard 
0%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%
Disk image created. UUID: c69e22d2-1560-44cc-85f6-d81979c81990

By choosing variant Standard, you instruct Oracle VM VirtualBox to create a dynamically allocated image file, whereas choosing variant Fixed would result in creating a fixed-size image. The difference between those two variants is that a dynamically allocated image occupies initially a very small amount of storage space on a real hard disk, growing as the amount of space utilized increases. Hence, it follows that the size specified for a dynamically allocated image merely specifies the upper bound of the image capacity. In contrast, when you create a fixed-size image, the amount of space specified by the size parameter is allocated at once, which ultimately might lead to inefficient utilization of disk space.

When specifying the image size, you should take into account the requirements of the guest OS and software components to be installed. It's interesting to note, however, that you'll be able to expand the image capacity anytime later with the VBoxManage modifyhd command (at the time of this writing, this capability is supported for the dynamically allocated variants of VDI and VHD formats only).

Now that you have a virtual hard disk created, the next step is to add a storage controller to be used with that hard disk:

$ VBoxManage storagectl OracleLinux6Test --name "SATA Controller" --add sata --bootable on

Note: When choosing Serial ATA (SATA) as the controller type, make sure that your guest OS has device support for Advanced Host Controller Interface (AHCI), which is the standard interface for SATA controllers. Be warned that older operating systems, such as Windows XP, do not support AHCI. In that case, you should rely on an Integrated Drive Electronics (IDE) controller.

Finally, you need to attach the hard disk to the controller:

$ VBoxManage storageattach OracleLinux6Test --storagectl "SATA Controller" 
--port 0 --device 0 --type hdd 
--medium /path/to/hard_drive_image/OracleLinux6Test.vdi

You can connect up to 30 virtual hard drives to a VM through a single SATA controller. In the case of an IDE controller, you're limited to just 4 virtual storage devices, where one of them is normally the virtual CD/DVD drive.

Installing a Guest OS into a VM

As mentioned, after creating a VM and setting its properties, you still need to install a guest operating system into it. Your installation options include using an ISO image or the host CD/DVD drive with installation media inserted. ISO images for Oracle Linux can be freely downloaded from Oracle E-Delivery. Once you have downloaded installation media in the form of an ISO file, you can use it directly or deploy it onto a DVD disk first and then use that disk as the installation media for the VM.

Next, you need to configure the VM to boot from the installation media, so that the installation begins when the VM starts for the first time. Whether you're using an installation DVD or an ISO image, you need to create a virtual CD/DVD drive and connect it to the installation media. Like virtual hard drives, virtual CD/DVD drives require a storage controller. While this can be done using a SATA controller for many operating systems, the following example illustrates adding an IDE controller for the CD/DVD drive.

$ VBoxManage storagectl OracleLinux6Test --name "IDE Controller" --add ide

Suppose you're going to install the guest OS from an installation DVD disk. Insert the installation disk into the host's CD/DVD drive and then issue the following command, connecting the VM's virtual CD/DVD drive to the physical CD/DVD drive on the host computer:

$ VBoxManage storageattach OracleLinux6Test --storagectl "IDE Controller" 
--port 0  --device 0 --type dvddrive --medium host:/dev/dvd 

Let's check what we've got using the following command, which should output information related to the VM's IDE controller:

$ VBoxManage showvminfo OracleLinux6Test | grep "IDE Controller"
Storage Controller Name (0):            IDE Controller
IDE Controller (0, 0): /dev/sr0 (UUID: 00445644-0000-0000-2f64-65762f737230)

Now you can boot the VM and start the guest installation using the following command, which starts in GUI mode by default, taking you through a standard guest OS installer:

$ VBoxManage startvm OracleLinux6Test 

All you need to do is follow the onscreen instructions to complete the installation. Figure 4 shows the first Oracle Linux 6.5 installation screen you should see upon the first start of the VM.

Figure 4. The guest OS installation begins upon the first boot of the VM

Once you have completed the OS installation, you can cleanly shut down the VM from within the guest, which causes Oracle VM VirtualBox to power off the VM was well. You can also initiate this from Oracle VM VirtualBox using the following command, which is equivalent to briefly pressing the power button on a physical computer:

$ VBoxManage controlvm OracleLinux6Test acpipowerbutton

Operating systems that are programmed to respond to this command will shut themselves down. You can forcibly shut down a VM using the following command, which is equivalent to pressing and holding a computer's power button:

$ VBoxManage controlvm OracleLinux6Test poweroff 

Finally, since the OS is installed in the guest, you can remove the DVD from the VM configuration:

$ VBoxManage storageattach OracleLinux6Test --storagectl "IDE Controller" 
--port 0 --device 0 --type dvddrive --medium none >

The next section explains how you can start a VM on a computer that does not have a monitor.

Starting a VM on a Headless Server

As an option, Oracle VM VirtualBox allows you to monitor a VM remotely over the VirtualBox Remote Display Protocol (VRDP). This can be particularly useful if your server doesn't have a physical monitor and you want the VM to be displayed on another computer.

Oracle VM VirtualBox provides remote machine display through the VirtualBox Remote Desktop Extension (VRDE) interface implemented within the Oracle VM VirtualBox Extension Pack package, which you can download from the Oracle VM VirtualBox download page. Make sure to pick the extension package that has the same version as your installed version of Oracle VM VirtualBox.

After installing the extension pack, you can enable the VRDE server as follows:

$ VBoxManage modifyvm OracleLinux6Test --vrde on 

Make sure the installation worked by running the following command:

$ VBoxManage showvminfo testMachine | grep VRDE
VRDE:  enabled (Address 0.0.0.0, Ports 3389, MultiConn: off, ReuseSingleConn: off, Authentication type: null)
VRDE property: TCP/Ports  = "3389"
VRDE property: TCP/Address = <not set>
...
VRDE Connection:    not active

Now you can start your VM for remote access, specifying type headless with the VBoxManage startvm command, which starts the VM but produces no visible output, delivering VRDP data to be displayed remotely on another computer:

$ VBoxManage startvm OracleLinux6Test --type headless
Waiting for VM "OracleLinux6Test" to power on...
VM "OracleLinux6Test" has been successfully started.

Then you can connect to the VM from another computer using any standard RDP viewer. In Windows, for example, you might use the Remote Desktop Connection tool, which is part of a regular installation. To start it, type in the mstsc command at the command line, which should invoke the dialog box shown in Figure 5:

Figure 5. The default RDP viewer in Windows

In this dialog box, you must specify the IP address of the host that is running the VM in headless mode, as well as the username and password for connecting to that host. Then, click Connect to establish a connection to the VM.

If everything is OK, you should see the first installation screen of the guest OS within the RDP viewer window, as shown in Figure 6. (If you recall, this example assumes that this is the first boot of the VM.)

Figure 6. Installing the guest OS remotely from a Windows host, using the RDP viewer that ships with Windows

Now you can follow the installation instructions appearing on the screen, just as if you were sitting in front of the host computer running the VM.

Importing Oracle VM VirtualBox Templates

Oracle offers a number of prebuilt developer VMs for Oracle VM VirtualBox, providing a quick way to install and experience entire software stacks packaged into deployable appliances. The VBoxManage import command allows you to import such appliances packaged in OVA format into Oracle VM VirtualBox.

Suppose you want to import Oracle Linux 6.5 into your Oracle VM VirtualBox from the OracleLinux65.ova package, which you have downloaded to your system from Oracle Linux Hands-on Labs. First, you might want to check the options available for the appliance to be imported. This can be done with the --dry-run option of the VBoxManage import command:

$ VBoxManage import /path/to/OracleLinux65.ova --dry-run 

Looking through the output, you'll discover the applicable options. In the following example, you specify the amount of RAM and the number of CPUs to be allocated, and, of course, you accept the license agreement to avoid the "Cannot import until the license agreement is accepted" error:

$ VBoxManage import /path/to/OracleLinux65.ova --vsys 0 --memory 1024 --cpus 2 --eula accept 

The import process might take a few minutes to complete, after which, you should see the following message:

Successfully imported the appliance. 

Once the import has successfully been completed, the Oracle Virtual Sysadmin Days VM icon should appear in the left pane of VirtualBox Manager. And, of course, you'll be able to manipulate the VM from the command line using the VBoxManage commands.

Conclusion

When working with a CLI, there is no handy wizard to guide you through setting up a new VM or editing the settings of an existing one. As you learned in this article, however, a CLI is indispensable when you need to have a command-level access to the system you're working with. Unlike a GUI, which hides many significant details from you, working with a CLI is all about the details. Thus, once you complete setting up a new VM using the VBoxManage CLI, you should have a deeper understanding of how an Oracle VM VirtualBox VM works and what key components it comprises.

See Also

• Oracle VM VirtualBox User Manual

• Oracle VM VirtualBox Programming Guide and Reference (PDF)

• Oracle VM VirtualBox download page

• Oracle Linux Installation Guide

About the Author

Yuli Vasiliev is a software developer, freelance author, and consultant currently specializing in open source development, Java technologies, business intelligence (BI), databases, service-oriented architecture (SOA) and, more recently, virtualization. He is the author of a series of books on Oracle technology, with the most recent one being Oracle Business Intelligence: An Introduction to Business Analysis and Reporting (Packt, 2010).