| 1 | <?xml version='1.0' encoding='UTF-8'?>
|
|---|
| 2 | <!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
|
|---|
| 3 | <topic xml:lang="en-us" id="vboxheadless">
|
|---|
| 4 | <title>VBoxHeadless, the Remote Desktop Server</title>
|
|---|
| 5 |
|
|---|
| 6 | <body>
|
|---|
| 7 | <p>While any VM started from <ph conkeyref="vbox-conkeyref-phrases/vbox-mgr"/> is capable of running virtual
|
|---|
| 8 | machines remotely, it is not convenient to have to run the full GUI if you never want to have VMs displayed
|
|---|
| 9 | locally in the first place. In particular, if you are running server hardware whose only purpose is to host VMs,
|
|---|
| 10 | and all your VMs are supposed to run remotely over VRDP, then it is pointless to have a graphical user interface
|
|---|
| 11 | on the server at all. This is especially true for Linux or Oracle Solaris hosts, as the <ph
|
|---|
| 12 | conkeyref="vbox-conkeyref-phrases/vbox-mgr"/> comes with dependencies on the Qt and SDL libraries. This is
|
|---|
| 13 | inconvenient if you would rather not have the X Window system on your server at all. </p>
|
|---|
| 14 | <p><ph conkeyref="vbox-conkeyref-phrases/product-name"/> therefore comes with a front end called
|
|---|
| 15 | <userinput>VBoxHeadless</userinput>, which produces no visible output on the host at all, but still can
|
|---|
| 16 | optionally deliver VRDP data. This front end has no dependencies on the X Window system on Linux and Oracle
|
|---|
| 17 | Solaris hosts. </p>
|
|---|
| 18 | <note>
|
|---|
| 19 | <p>In legacy releases of <ph conkeyref="vbox-conkeyref-phrases/product-name"/>, the headless server was called
|
|---|
| 20 | <userinput>VBoxVRDP</userinput>. For backward compatibility, the <ph
|
|---|
| 21 | conkeyref="vbox-conkeyref-phrases/product-name"/> installation still includes an executable with that name. </p>
|
|---|
| 22 | </note>
|
|---|
| 23 | <p>To start a virtual machine with <userinput>VBoxHeadless</userinput>, you have the following options: </p>
|
|---|
| 24 | <ul>
|
|---|
| 25 | <li>
|
|---|
| 26 | <p>Use the <userinput>VBoxManage</userinput> command, as follows: </p>
|
|---|
| 27 | <pre xml:space="preserve">$ VBoxManage startvm <varname>VM-name</varname> --type headless</pre>
|
|---|
| 28 | <p>The <codeph>--type</codeph> option causes <ph conkeyref="vbox-conkeyref-phrases/product-name"/> to use
|
|---|
| 29 | <userinput>VBoxHeadless</userinput> as the front end to the internal virtualization engine, instead of the
|
|---|
| 30 | Qt front end. </p>
|
|---|
| 31 | </li>
|
|---|
| 32 | <li>
|
|---|
| 33 | <p>Use the <userinput>VBoxHeadless</userinput> command, as follows: </p>
|
|---|
| 34 | <pre xml:space="preserve">VBoxHeadless --startvm <varname>uuid</varname>|<varname>vmname</varname>
|
|---|
| 35 | </pre>
|
|---|
| 36 | <p>This way of starting the VM helps troubleshooting problems reported by <userinput>VBoxManage
|
|---|
| 37 | startvm</userinput>, because you can sometimes see more detailed error messages, especially for early
|
|---|
| 38 | failures before the VM execution is started. In normal situations <userinput>VBoxManage startvm</userinput> is
|
|---|
| 39 | preferred, since it runs the VM directly as a background process which has to be done explicitly when directly
|
|---|
| 40 | starting with <userinput>VBoxHeadless</userinput>. </p>
|
|---|
| 41 | </li>
|
|---|
| 42 | <li>
|
|---|
| 43 | <p>Start <userinput>VBoxHeadless</userinput> from <ph conkeyref="vbox-conkeyref-phrases/vbox-mgr"/>, by pressing
|
|---|
| 44 | the Shift key when starting a virtual machine or by selecting <b outputclass="bold">Headless Start</b> from
|
|---|
| 45 | the <b outputclass="bold">Machine</b> menu. </p>
|
|---|
| 46 | </li>
|
|---|
| 47 | </ul>
|
|---|
| 48 | <p>When you use the <userinput>VBoxHeadless</userinput> command to start a VM, the VRDP server will be enabled
|
|---|
| 49 | according to the VM configuration. You can override the VM's setting using <codeph>--vrde</codeph> command line
|
|---|
| 50 | parameter. To enable the VRDP server, start the VM as follows: </p>
|
|---|
| 51 | <pre xml:space="preserve">VBoxHeadless --startvm <varname>uuid</varname>|<varname>vmname</varname> --vrde on</pre>
|
|---|
| 52 | <p>To disable the VRDP server: </p>
|
|---|
| 53 | <pre xml:space="preserve">VBoxHeadless --startvm <varname>uuid</varname>|<varname>vmname</varname> --vrde off</pre>
|
|---|
| 54 | <p>To have the VRDP server enabled depending on the VM configuration, as for other front ends: </p>
|
|---|
| 55 | <pre xml:space="preserve">VBoxHeadless --startvm <varname>uuid</varname>|<varname>vmname</varname> --vrde config</pre>
|
|---|
| 56 | <p>This command is the same as the following: </p>
|
|---|
| 57 | <pre xml:space="preserve">VBoxHeadless --startvm <varname>uuid</varname>|<varname>vmname</varname>
|
|---|
| 58 | </pre>
|
|---|
| 59 | <p>If you start the VM with <userinput>VBoxManage startvm</userinput> then the configuration settings of the VM are
|
|---|
| 60 | always used. </p>
|
|---|
| 61 | </body>
|
|---|
| 62 |
|
|---|
| 63 | </topic>
|
|---|
