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