| 1 | <?xml version="1.0" encoding="UTF-8"?>
|
|---|
| 2 | <!DOCTYPE topic
|
|---|
| 3 | PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
|
|---|
| 4 | <topic xml:lang="en-us" id="vboxmanage-intro">
|
|---|
| 5 | <title>Introduction</title>
|
|---|
| 6 |
|
|---|
| 7 | <body>
|
|---|
| 8 | <p>As briefly mentioned in <xref href="frontends.dita#frontends"/>, <userinput>VBoxManage</userinput> is
|
|---|
| 9 | the command-line interface to <ph conkeyref = "vbox-conkeyref-phrases/product-name"/>. With it, you can completely control <ph conkeyref = "vbox-conkeyref-phrases/product-name"/> from the
|
|---|
| 10 | command line of your host operating system. <userinput>VBoxManage</userinput> supports all the features that the
|
|---|
| 11 | graphical user interface gives you access to, but it supports a lot more than that. It exposes all the features of
|
|---|
| 12 | the virtualization engine, even those that cannot be accessed from the GUI. </p>
|
|---|
| 13 | <p>You will need to use the command line if you want to do the
|
|---|
| 14 | following:
|
|---|
| 15 | </p>
|
|---|
| 16 | <ul>
|
|---|
| 17 | <li>
|
|---|
| 18 | <p>
|
|---|
| 19 | Use a different user interface than the main GUI such as the
|
|---|
| 20 | VBoxHeadless server.
|
|---|
| 21 | </p>
|
|---|
| 22 | </li>
|
|---|
| 23 | <li>
|
|---|
| 24 | <p>
|
|---|
| 25 | Control some of the more advanced and experimental
|
|---|
| 26 | configuration settings for a VM.
|
|---|
| 27 | </p>
|
|---|
| 28 | </li>
|
|---|
| 29 | </ul>
|
|---|
| 30 | <p>There are two main things to keep in mind when using <userinput>VBoxManage</userinput>. First,
|
|---|
| 31 | <userinput>VBoxManage</userinput> must always be used with a specific subcommand, such as
|
|---|
| 32 | <userinput>list</userinput> or <userinput>createvm</userinput> or <userinput>startvm</userinput>. All the
|
|---|
| 33 | subcommands that <userinput>VBoxManage</userinput> supports are described in detail in <xref
|
|---|
| 34 | href="vboxmanage.dita#vboxmanage"/>. </p>
|
|---|
| 35 | <p>Second, most of these subcommands require that you specify a particular virtual machine after the
|
|---|
| 36 | subcommand. There are two ways you can do this: </p>
|
|---|
| 37 | <ul>
|
|---|
| 38 | <li>
|
|---|
| 39 | <p>
|
|---|
| 40 | You can specify the VM name, as it is shown in the
|
|---|
| 41 | <ph conkeyref = "vbox-conkeyref-phrases/product-name"/> GUI. Note that if that name contains spaces,
|
|---|
| 42 | then you must enclose the entire name in double quotes. This
|
|---|
| 43 | is always required with command line arguments that contain
|
|---|
| 44 | spaces. For example:
|
|---|
| 45 | </p>
|
|---|
| 46 | <pre xml:space="preserve">VBoxManage startvm "Windows XP"</pre>
|
|---|
| 47 | </li>
|
|---|
| 48 | <li>
|
|---|
| 49 | <p>
|
|---|
| 50 | You can specify the UUID, which is the internal unique
|
|---|
| 51 | identifier that <ph conkeyref = "vbox-conkeyref-phrases/product-name"/> uses to refer to the virtual
|
|---|
| 52 | machine. Assuming that the VM called "Windows XP" has the UUID
|
|---|
| 53 | shown below, the following command has the same effect as the
|
|---|
| 54 | previous example:
|
|---|
| 55 | </p>
|
|---|
| 56 | <pre xml:space="preserve">VBoxManage startvm 670e746d-abea-4ba6-ad02-2a3b043810a5</pre>
|
|---|
| 57 | </li>
|
|---|
| 58 | </ul>
|
|---|
| 59 | <p>You can enter <userinput>VBoxManage list vms</userinput> to have all currently registered VMs listed
|
|---|
| 60 | with all their settings, including their respective names and UUIDs. </p>
|
|---|
| 61 | <p>Some typical examples of how to control <ph conkeyref="vbox-conkeyref-phrases/product-name"/> from the
|
|---|
| 62 | command line are listed below: </p>
|
|---|
| 63 | <ul>
|
|---|
| 64 | <li>
|
|---|
| 65 | <p>To create a new virtual machine from the command line and immediately register it with <ph
|
|---|
| 66 | conkeyref="vbox-conkeyref-phrases/product-name"/>, use <userinput>VBoxManage createvm</userinput> with the
|
|---|
| 67 | <!--option not processed within -->--register option, as follows: </p>
|
|---|
| 68 | <pre xml:space="preserve">$ VBoxManage createvm --name "SUSE 10.2" --register
|
|---|
| 69 | VirtualBox Command Line Management Interface Version <varname>version-number</varname>
|
|---|
| 70 | (C) 2005-2018 Oracle Corporation
|
|---|
| 71 | All rights reserved.
|
|---|
| 72 |
|
|---|
| 73 | Virtual machine 'SUSE 10.2' is created.
|
|---|
| 74 | UUID: c89fc351-8ec6-4f02-a048-57f4d25288e5
|
|---|
| 75 | Settings file: '/home/username/.config/VirtualBox/Machines/SUSE 10.2/SUSE 10.2.xml'</pre>
|
|---|
| 76 | <p>As can be seen from the above output, a new virtual machine has been created with a new UUID and
|
|---|
| 77 | a new XML settings file. </p>
|
|---|
| 78 | <p>
|
|---|
| 79 | For more details, see
|
|---|
| 80 | <xref href="vboxmanage-createvm.dita"/>.
|
|---|
| 81 | </p>
|
|---|
| 82 | </li>
|
|---|
| 83 | <li>
|
|---|
| 84 | <p>To show the configuration of a particular VM, use <userinput>VBoxManage showvminfo</userinput>.
|
|---|
| 85 | See <xref href="vboxmanage-showvminfo.dita"/> for details and an example. </p>
|
|---|
| 86 | </li>
|
|---|
| 87 | <li>
|
|---|
| 88 | <p>To change settings while a VM is powered off, use <userinput>VBoxManage modifyvm</userinput>.
|
|---|
| 89 | For example: </p>
|
|---|
| 90 | <pre xml:space="preserve">VBoxManage modifyvm "Windows XP" --memory 512</pre>
|
|---|
| 91 | <p>See also <xref href="vboxmanage-modifyvm.dita"/>. </p>
|
|---|
| 92 | </li>
|
|---|
| 93 | <li>
|
|---|
| 94 | <p>To change the storage configuration, such as to add a storage controller and then a virtual
|
|---|
| 95 | disk, use <userinput>VBoxManage storagectl</userinput> and <userinput>VBoxManage storageattach</userinput>.
|
|---|
| 96 | See <xref href="vboxmanage-storagectl.dita"/> and <xref href="vboxmanage-storageattach.dita"/>. </p>
|
|---|
| 97 | </li>
|
|---|
| 98 | <li>
|
|---|
| 99 | <p>To control VM operation, use one of the following: </p>
|
|---|
| 100 | <ul>
|
|---|
| 101 | <li>
|
|---|
| 102 | <p>To start a VM that is currently powered off, use <userinput>VBoxManage
|
|---|
| 103 | startvm</userinput>. See <xref href="vboxmanage-startvm.dita"/>. </p>
|
|---|
| 104 | </li>
|
|---|
| 105 | <li>
|
|---|
| 106 | <p>To pause or save a VM that is currently running or change some of its settings, use
|
|---|
| 107 | <userinput>VBoxManage controlvm</userinput>. See <xref href="vboxmanage-controlvm.dita"/>. </p>
|
|---|
| 108 | </li>
|
|---|
| 109 | </ul>
|
|---|
| 110 | </li>
|
|---|
| 111 | </ul>
|
|---|
| 112 | </body>
|
|---|
| 113 |
|
|---|
| 114 | </topic>
|
|---|
